File System Observer एपीआई का ऑरिजिन ट्रायल

Thomas Steiner

File System Access API और Origin Private File System API, दोनों ही डेवलपर को उपयोगकर्ता के डिवाइस पर मौजूद फ़ाइलों और डायरेक्ट्री को ऐक्सेस करने की अनुमति देते हैं. पहले वाले विकल्प से डेवलपर, उपयोगकर्ता को दिखने वाले फ़ाइल सिस्टम को पढ़ और उसमें बदलाव कर सकते हैं. वहीं, दूसरे विकल्प से डेवलपर को एक खास फ़ाइल सिस्टम का ऐक्सेस मिलता है. यह फ़ाइल सिस्टम, उपयोगकर्ता को नहीं दिखता. यह हर साइट के ऑरिजिन के लिए निजी होता है. साथ ही, इससे परफ़ॉर्मेंस से जुड़े कुछ फ़ायदे मिलते हैं. दोनों ही मामलों में, डेवलपर फ़ाइलों और डायरेक्ट्री के साथ इंटरैक्ट करने के लिए FileSystemHandle ऑब्जेक्ट का इस्तेमाल करते हैं. ज़्यादा सटीक तरीके से कहें, तो फ़ाइलों के लिए FileSystemFileHandle और डायरेक्ट्री के लिए FileSystemDirectoryHandle ऑब्जेक्ट का इस्तेमाल करते हैं. अब तक, किसी भी फ़ाइल सिस्टम में किसी फ़ाइल या डायरेक्ट्री में हुए बदलावों के बारे में सूचना पाने के लिए, किसी तरह की पोलिंग और lastModified टाइमस्टैंप की तुलना करने की ज़रूरत होती थी. इसके अलावा, फ़ाइल के कॉन्टेंट की तुलना करने की भी ज़रूरत होती थी.

Chrome 129 में, File System Observer API का ऑरिजिन ट्रायल शुरू किया गया है. इससे यह समस्या हल हो जाती है. साथ ही, बदलाव होने पर डेवलपर को अपने-आप सूचना मिल जाती है. इस गाइड में, इस सुविधा के काम करने के तरीके और इसे आज़माने के तरीके के बारे में बताया गया है.

उपयोग के उदाहरण

उन ऐप्लिकेशन में File System Observer API का इस्तेमाल करें जिन्हें फ़ाइल सिस्टम में होने वाले संभावित बदलावों के बारे में तुरंत सूचना मिलनी चाहिए.

  • वेब पर आधारित इंटिग्रेटेड डेवलपमेंट एनवायरमेंट (आईडीई), जो प्रोजेक्ट के फ़ाइल सिस्टम ट्री को दिखाते हैं.
  • ऐसे ऐप्लिकेशन जो फ़ाइल सिस्टम में हुए बदलावों को सर्वर के साथ सिंक करते हैं. उदाहरण के लिए, SQLite डेटाबेस फ़ाइल.
  • ऐसे ऐप्लिकेशन जिन्हें वर्कर या किसी दूसरे टैब से फ़ाइल सिस्टम में हुए बदलावों के बारे में मुख्य थ्रेड को सूचना देनी होती है.
  • ऐसे ऐप्लिकेशन जो संसाधनों की डायरेक्ट्री पर नज़र रखते हैं. उदाहरण के लिए, इमेज को अपने-आप ऑप्टिमाइज़ करने के लिए.
  • ऐसे अनुभव जिन्हें हॉट-रीलोडिंग से फ़ायदा मिलता है. जैसे, एचटीएमएल पर आधारित स्लाइड डेक, जहां फ़ाइल में बदलाव होने पर रीलोड ट्रिगर होता है.

फ़ाइल सिस्टम ऑब्ज़र्वर एपीआई का इस्तेमाल कैसे करें

सुविधा का पता लगाना

यह देखने के लिए कि File System Observer API काम करता है या नहीं, सुविधा की जांच करें. इसके लिए, यहां दिया गया उदाहरण देखें.

if ('FileSystemObserver' in self) {
  // The File System Observer API is supported.
}

फ़ाइल सिस्टम ऑब्ज़र्वर को शुरू करना

new FileSystemObserver() को कॉल करके, फ़ाइल सिस्टम ऑब्ज़र्वर को शुरू करें. साथ ही, इसे callback फ़ंक्शन को आर्ग्युमेंट के तौर पर दें.

const observer = new FileSystemObserver(callback);

किसी फ़ाइल या डायरेक्ट्री को मॉनिटर करना शुरू करना

किसी फ़ाइल या डायरेक्ट्री पर नज़र रखने के लिए, observe() इंस्टेंस के एसिंक्रोनस observe() तरीके को कॉल करें.FileSystemObserver इस तरीके में, चुनी गई फ़ाइल या डायरेक्ट्री का FileSystemHandle आर्ग्युमेंट के तौर पर दें. किसी डायरेक्ट्री पर नज़र रखते समय, options आर्ग्युमेंट का इस्तेमाल किया जा सकता है. इससे यह तय किया जा सकता है कि आपको डायरेक्ट्री में बार-बार होने वाले बदलावों के बारे में सूचना चाहिए या नहीं. इसका मतलब है कि डायरेक्ट्री और उसमें मौजूद सभी सबडायरेक्ट्री और फ़ाइलों के लिए सूचनाएं चाहिए या नहीं. डिफ़ॉल्ट विकल्प के तौर पर, सिर्फ़ डायरेक्ट्री और उसमें मौजूद फ़ाइलों को मॉनिटर किया जाता है.

// Observe a file.
await observer.observe(fileHandle);
// Observe a directory.
await observer.observe(directoryHandle);
// Observe a directory recursively.
await observer.observe(directoryHandle, {recursive: true});

कॉलबैक फ़ंक्शन

जब फ़ाइल सिस्टम में बदलाव होते हैं, तब कॉलबैक फ़ंक्शन को फ़ाइल सिस्टम में बदलाव records और observer के साथ कॉल किया जाता है. observer आर्ग्युमेंट का इस्तेमाल, उदाहरण के लिए, तब किया जा सकता है, जब आपकी पसंद की सभी फ़ाइलें मिटा दी गई हों. ऐसा करने पर, ऑब्ज़र्वर डिसकनेक्ट हो जाएगा. इसके बारे में जानने के लिए, फ़ाइल सिस्टम को मॉनिटर करना बंद करना लेख पढ़ें.

const callback = (records, observer) => {
  for (const record of records) {
    console.log('Change detected', record);
  }
};

फ़ाइल सिस्टम में बदलाव का रिकॉर्ड

फ़ाइल सिस्टम में हुए बदलाव के हर रिकॉर्ड का स्ट्रक्चर यहां दिया गया है. सभी फ़ील्ड सिर्फ़ पढ़े जा सकते हैं.

  • root (एक FileSystemHandle): यह FileSystemObserver.observe() फ़ंक्शन को पास किया गया हैंडल है.
  • changedHandle (a FileSystemHandle): फ़ाइल सिस्टम में हुए बदलाव से प्रभावित हैंडल. यह फ़ील्ड, "errored", "unknown", और "disappeared" टाइप के इवेंट के लिए null होगा. यह देखने के लिए कि कौनसी फ़ाइल या डायरेक्ट्री गायब हो गई है, relativePathComponents का इस्तेमाल करें.
  • relativePathComponents (Array): यह root के हिसाब से changedHandle का पाथ होता है.
  • type (a String): बदलाव का टाइप. ये टाइप उपलब्ध हैं:
    • "appeared": फ़ाइल या डायरेक्ट्री को root में बनाया गया था या ले जाया गया था.
    • "disappeared": फ़ाइल या डायरेक्ट्री को मिटा दिया गया है या उसे root से हटा दिया गया है.
    • "modified": फ़ाइल या डायरेक्ट्री में बदलाव किया गया है.
    • "moved": फ़ाइल या डायरेक्ट्री को root में ले जाया गया था.
    • "unknown": इससे पता चलता है कि शून्य या उससे ज़्यादा इवेंट छूट गए हैं. इसके जवाब में, डेवलपर को वॉच की गई डायरेक्ट्री को पोल करना चाहिए.
    • "errored": यह ऑब्ज़र्वेशन अब मान्य नहीं है. ऐसे में, आपको फ़ाइल सिस्टम को मॉनिटर करना बंद करना पड़ सकता है. यह वैल्यू तब भी भेजी जाएगी, जब हर ऑरिजिन के लिए तय की गई ऑब्ज़र्वेशन की ज़्यादा से ज़्यादा सीमा पूरी हो जाएगी. यह सीमा ऑपरेटिंग सिस्टम पर निर्भर करती है और इसके बारे में पहले से नहीं पता होता. ऐसा होने पर, साइट फिर से कोशिश कर सकती है. हालांकि, इस बात की कोई गारंटी नहीं है कि ऑपरेटिंग सिस्टम ने ज़रूरत के मुताबिक संसाधन खाली कर दिए हैं. इस वैल्यू को तब भी भेजा जाएगा, जब मॉनिटर किए जा रहे हैंडल (यानी कि मॉनिटरिंग का रूट) को मिटा दिया गया हो या उसे दूसरी जगह ले जाया गया हो. इस मामले में, सबसे पहले "disappeared" इवेंट भेजा जाता है. इसके बाद, "errored" इवेंट भेजा जाता है. इससे पता चलता है कि अब ऑब्ज़र्वेशन मान्य नहीं है. आखिर में, यह इवेंट तब भेजा जाता है, जब डायरेक्ट्री या फ़ाइल हैंडल से अनुमति हटा दी जाती है.
  • relativePathMovedFrom (Array, ज़रूरी नहीं): यह उस हैंडल की पिछली जगह की जानकारी है जिसे ट्रांसफ़र किया गया है. यह सुविधा सिर्फ़ तब उपलब्ध होती है, जब type "moved" हो.

किसी फ़ाइल या डायरेक्ट्री को मॉनिटर करने की सुविधा बंद करना

किसी FileSystemHandle को मॉनिटर करना बंद करने के लिए, unobserve() तरीके को कॉल करें. इसके लिए, हैंडल को आर्ग्युमेंट के तौर पर पास करें.

observer.unobserve(fileHandle);

फ़ाइल सिस्टम को मॉनिटर करना बंद करें

फ़ाइल सिस्टम को मॉनिटर करना बंद करने के लिए, FileSystemObserver इंस्टेंस को इस तरह डिसकनेक्ट करें.

observer.disconnect();

एपीआई आज़माएं

File System Observer API को स्थानीय तौर पर टेस्ट करने के लिए, about:flags में #file-system-observer फ़्लैग सेट करें. असली उपयोगकर्ताओं के साथ एपीआई को टेस्ट करने के लिए, ऑरिजिन ट्रायल के लिए साइन अप करें. साथ ही, Chrome ऑरिजिन ट्रायल गाइड में दिए गए निर्देशों का पालन करें. यह ऑरिजिन ट्रायल, Chrome 129 (11 सितंबर, 2024) से लेकर Chrome 134 (26 फ़रवरी, 2025) तक चलेगा.

डेमो

एम्बेड किए गए डेमो में, File System Observer API को काम करते हुए देखा जा सकता है. सोर्स कोड देखें. डेमो, मॉनिटर की जा रही डायरेक्ट्री में फ़ाइलों को बनाता है, मिटाता है या उनमें बदलाव करता है. साथ ही, ऐप्लिकेशन विंडो के ऊपरी हिस्से में अपनी गतिविधि को लॉग करता है. इसके बाद, यह ऐप्लिकेशन विंडो के निचले हिस्से में होने वाले बदलावों को लॉग करता है. अगर आपने इस जानकारी को ऐसे ब्राउज़र पर पढ़ा है जो File System Observer API के साथ काम नहीं करता, तो डेमो का स्क्रीनशॉट देखें.

सुझाव/राय दें या शिकायत करें

अगर आपको File System Observer API के बारे में कोई सुझाव या राय देनी है, तो WHATWG/fs रिपॉज़िटरी में मौजूद समस्या #123 पर टिप्पणी करें.

Acknowledgements

इस दस्तावेज़ की समीक्षा डेसुल ली, नाथन मेमॉट, एटिएन नोएल, और राशेल ऐंड्रयू ने की है.