From 7b0838d489b5d371674929169de66b69164f7e1a Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Fri, 21 Feb 2025 14:42:57 +0000 Subject: [PATCH 01/16] Document FileSystemObserver --- files/en-us/web/api/file_system_api/index.md | 2 + .../filesystemobserver/disconnect/index.md | 49 ++++++++ .../filesystemobserver/index.md | 108 +++++++++++++++++ .../en-us/web/api/filesystemobserver/index.md | 110 ++++++++++++++++++ .../api/filesystemobserver/observe/index.md | 103 ++++++++++++++++ files/jsondata/GroupData.json | 1 + 6 files changed, 373 insertions(+) create mode 100644 files/en-us/web/api/filesystemobserver/disconnect/index.md create mode 100644 files/en-us/web/api/filesystemobserver/filesystemobserver/index.md create mode 100644 files/en-us/web/api/filesystemobserver/index.md create mode 100644 files/en-us/web/api/filesystemobserver/observe/index.md diff --git a/files/en-us/web/api/file_system_api/index.md b/files/en-us/web/api/file_system_api/index.md index 7d02954a5dd86e4..8740412d2777030 100644 --- a/files/en-us/web/api/file_system_api/index.md +++ b/files/en-us/web/api/file_system_api/index.md @@ -85,6 +85,8 @@ Read our [Origin private file system](/en-US/docs/Web/API/File_System_API/Origin - : Provides a handle to a file system entry. - {{domxref("FileSystemDirectoryHandle")}} - : Provides a handle to a file system directory. +- {{domxref("FileSystemObserver")}} + - : Provides a mechanism to observe changes to the underlying file systems behind the File API, without having to rely on adhoc polling. - {{domxref("FileSystemSyncAccessHandle")}} - : Provides a synchronous handle to a file system entry, which operates in-place on a single file on disk. The synchronous nature of the file reads and writes allows for higher performance for critical methods in contexts where asynchronous operations come with high overhead, e.g., [WebAssembly](/en-US/docs/WebAssembly). This class is only accessible inside dedicated [Web Workers](/en-US/docs/Web/API/Web_Workers_API) for files within the [origin private file system](#origin_private_file_system). - {{domxref("FileSystemWritableFileStream")}} diff --git a/files/en-us/web/api/filesystemobserver/disconnect/index.md b/files/en-us/web/api/filesystemobserver/disconnect/index.md new file mode 100644 index 000000000000000..57ec85dbb34fbd1 --- /dev/null +++ b/files/en-us/web/api/filesystemobserver/disconnect/index.md @@ -0,0 +1,49 @@ +--- +title: "FileSystemObserver: disconnect() method" +short-title: disconnect() +slug: Web/API/FileSystemObserver/disconnect +page-type: web-api-instance-method +browser-compat: api.FileSystemObserver.disconnect +--- + +{{securecontext_header}}{{APIRef("File System API")}} + +The **`disconnect()`** method of the +{{domxref("FileSystemObserver")}} interface stops the observer observing the filesystem. + +## Syntax + +```js-nolint +disconnect() +``` + +### Parameters + +None. + +### Return value + +None ({{jsxref('undefined')}}). + +## Examples + +### Stop observing the file system + +Assuming a `FileSystemObserver` instance is available, you can call the `disconnect()` method on it when you want to stop observing changes to the file system entry: + +```js +observer.disconnect(); +``` + +## Specifications + +Not currently part of a specification. See [https://github.com/whatwg/fs/pull/165](https://github.com/whatwg/fs/pull/165) for the relevant specification PR. + +## Browser compatibility + +{{Compat}} + +## See also + +- [File System API](/en-US/docs/Web/API/File_System_API) +- [The File System Observer API origin trial](https://developer.chrome.com/blog/file-system-observer#stop-observing-the-file-system) on developer.chrome.com (2024) diff --git a/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md b/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md new file mode 100644 index 000000000000000..f3c7b98aafbd074 --- /dev/null +++ b/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md @@ -0,0 +1,108 @@ +--- +title: "FileSystemObserver: FileSystemObserver() constructor" +short-title: FileSystemObserver() +slug: Web/API/FileSystemObserver/FileSystemObserver +page-type: web-api-constructor +status: + - experimental +browser-compat: api.FileSystemObserver.FileSystemObserver +--- + +{{APIRef("Navigation API")}}{{SeeCompatTable}} + +The **`FileSystemObserver()`** constructor creates a new {{domxref("FileSystemObserver")}} object instance. + +## Syntax + +```js-nolint +new FileSystemObserver(callback) +``` + +### Parameters + +- `callback` + - : A user-defined callback function that will be called when the observer has observed a change in the file system entry it has been tasked to observe (via {{domxref("FileSystemObserver.observe()")}}). The callback function body can be specified to return and process file change observations in any way you want, however, it always includes the following two parameters: + - `records` + - : An array of [`FileSystemChangeRecord`](#filesystemchangerecord_structure) objects that contain details of all the observed changes. + - `observer` + - : A reference to the current `FileSystemObserver` object, which is made available in case, for example, you want to stop observations after the current records have been received using the {{domxref('FileSystemObserver.disconnect()')}} method. + +#### `FileSystemChangeRecord` structure + +`FileSystemChangeRecord` objects have the following structure: + +- `changedHandle` + - : A reference to the file system handle that the change was observed on. This can be a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} for the user-observable file system, or a {{domxref("FileSystemSyncAccessHandle")}} for the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS). This property will be `null` for records with a `"disappeared"`, `"errored"`, or `"unknown"` type. +- `relativePathComponents` + - : An array containing the path components that make up the relative file path from the `root` to the `changedHandle`, including the `changedHandle` filename. +- `relativePathMovedFrom` + - : An array containing the path components that make up the relative file path from the `root` to the `changedHandle`'s former location, in the case of observations with a `"moved"` type. If the type is not `"moved"`, this property will be `null`. +- `root` + - : A reference to the root file system handle, that is, the one passed to the `observe()` call that started the observation. Again, this can be a {{domxref("FileSystemFileHandle")}}, {{domxref("FileSystemDirectoryHandle")}}, or {{domxref("FileSystemSyncAccessHandle")}}. +- `type` + - : A string representing the type of change that was observed. Possible values are: + - `appeared` + - : The file or directory was created or moved into the `root` file structure. + - `disappeared` + - : The file or directory was deleted or moved out of the `root` file structure. To find out which file or directory disappeared, you can query the `relativePathComponents` property. + - `errored` + - : An error state occured in the observed directory. This can result when: + - The observation is no longer valid. This can occur when the observed handle (that is, the `root` of the observation) is deleted or moved. In this case, a `"disappeared"` observation will be recorded, followed by an `"errored"` observation. In such cases, you may wish to stop observing the file system using {{domxref("FileSystemObserver.disconnect()")}}. + - The maximum limit of per-origin observations is reached. This limit is dependent on the operating system and not known beforehand. If this happens, the site may decide to retry, though there's no guarantee that the operating system will have freed up enough resources. + - Permission to access the directory or file handle is removed. + - `modified` + - : The file or directory was modified. + - `moved` + - : The file or directory was moved within the root file structure. + > [!NOTE] + > On Windows, `"moved"` observations aren't supported between directories. They are reported as a `"disappeared"` observation in the source directory and an `"appeared"` observation in the destination directory. They are reported as `"moved"` when the source and destination are both in the same directory. + - `unknown` + - : Indicates that some observations were missed. If you wish to find out information on what changed in the missed observations, you could fall back to polling the observed directory. + +Depending on the operating system, not all observations will be reported with the same level of detail, for example, when the contents of a directory change recursively. At best, the website will receive a detailed change record containing the type of change and a handle to the affected path. At worst, the website will receive a more generic change record (that is, an `"unknown"` type) that still requires it to enumerate the directory to figure out which handle changed. + +This is still an improvement over polling, since the directory enumeration can be kicked off on-demand from the callback function, rather than needing to poll for changes in intervals. + +### Return value + +A new {{domxref("FileSystemObserver")}} object. + +## Examples + +> [!NOTE] +> For a complete working example, check out [File System Observer Demo](https://file-system-observer.glitch.me/). + +### Initializing a `FileSystemObserver` + +Before you can start observing file or directory changes, you need to initialize a `FileSystemObserver` to handle the observations: + +```js +const observer = new FileSystemObserver(callback); +``` + +The callback function body can be specified to return and process file change observations in any want you want: + +```js +const callback = (records, observer) => { + for (const record of records) { + console.log("Change detected:", record); + const reportContent = `Change observed to ${record.changedHandle.kind} ${record.changedHandle.name}. Type: ${record.type}.`; + sendReport(reportContent); // Some kind of user-defined reporting function + } + + observer.disconnect(); +}; +``` + +## Specifications + +Not currently part of a specification. See [https://github.com/whatwg/fs/pull/165](https://github.com/whatwg/fs/pull/165) for the relevant specification PR. + +## Browser compatibility + +{{Compat}} + +## See also + +- [File System API](/en-US/docs/Web/API/File_System_API) +- [The File System Observer API origin trial](https://developer.chrome.com/blog/file-system-observer#stop-observing-the-file-system) on developer.chrome.com (2024) diff --git a/files/en-us/web/api/filesystemobserver/index.md b/files/en-us/web/api/filesystemobserver/index.md new file mode 100644 index 000000000000000..c78a130aa947ae7 --- /dev/null +++ b/files/en-us/web/api/filesystemobserver/index.md @@ -0,0 +1,110 @@ +--- +title: FileSystemObserver +slug: Web/API/FileSystemObserver +page-type: web-api-interface +browser-compat: api.FileSystemObserver +--- + +{{securecontext_header}}{{APIRef("File System API")}} + +The **`FileSystemObserver`** interface of the {{domxref("File System API", "File System API", "", "nocode")}} provides a mechanism to observe changes to the underlying file systems behind the File API, both the user-observable file system and the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS). Previous to this, sites had to recursively poll the file system to find changes in the files or folder structure. This can be time-consuming, especially for large directories. + +## Constructor + +- {{domxref("FileSystemObserver.FileSystemObserver", "FileSystemObserver()")}} {{Experimental_Inline}} + - : Creates a new `FileSystemObserver` object instance. + +## Instance methods + +- {{domxref("FileSystemObserver.disconnect", "disconnect()")}} {{Experimental_Inline}} + - : Stop observing the filesystem. +- {{domxref("FileSystemObserver.observe", "observe()")}} {{Experimental_Inline}} + - : Start observing changes to a given file or directory. + +## Examples + +> [!NOTE] +> For a complete working example, check out [File System Observer Demo](https://file-system-observer.glitch.me/). + +### Initialize a `FileSystemObserver` + +Before you can start observing file or directory changes, you need to initialize a `FileSystemObserver` to handle the observations. This is done using the {{domxref("FileSystemObserver.FileSystemObserver", "FileSystemObserver()")}} constructor, which takes a callback function as an argument: + +```js +const observer = new FileSystemObserver(callback); +``` + +The [callback function](/en-US/docs/Web/API/FileSystemObserver/FileSystemObserver#callback) body can be specified to return and process file change observations in any way you want: + +```js +const callback = (records, observer) => { + for (const record of records) { + console.log("Change detected:", record); + const reportContent = `Change observed to ${record.changedHandle.kind} ${record.changedHandle.name}. Type: ${record.type}.`; + sendReport(reportContent); // Some kind of user-defined reporting function + } + + observer.disconnect(); +}; +``` + +The callback always includes two parameters: + +- `records` + - : An array of [`FileSystemChangeRecord`](/en-US/docs/Web/API/FileSystemObserver/FileSystemObserver#filesystemchangerecord_structure) objects that contain details of all the observed changes. +- `observer` + - : A reference to the current `FileSystemObserver` object, which is made available in case, for example, you want to stop observations after the current records have been received using the {{domxref('FileSystemObserver.disconnect', 'disconnect()')}} method, as shown above. + +### Observe a file or directory + +Once a `FileSystemObserver` instance is available, you can start observing changes to a file system entry by running the {{domxref("FileSystemObserver.observe()")}} method, passing it the handle of the entry to observe. This can be a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} for the user-observable file system: + +```js +// Observe a file +async function observeFile() { + const fileHandle = await window.showSaveFilePicker(); + + await observer.observe(fileHandle); +} + +// Observe a directory +async function observeDirectory() { + const directoryHandle = await window.showDirectoryPicker(); + + await observer.observe(directoryHandle); +} +``` + +or a {{domxref("FileSystemSyncAccessHandle")}} for the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS): + +```js +// Observe an OPFS file system entry +async function observeOPFSFile() { + const root = await navigator.storage.getDirectory(); + const draftHandle = await root.getFileHandle("draft.txt", { create: true }); + const opfsHandle = await draftHandle.createSyncAccessHandle(); + + await observer.observe(opfsHandle); +} +``` + +### Stop observing the file system + +When you want to stop observing changes to the file system entry, you can call {{domxref("FileSystemObserver.disconnect()")}}: + +```js +observer.disconnect(); +``` + +## Specifications + +Not currently part of a specification. See [https://github.com/whatwg/fs/pull/165](https://github.com/whatwg/fs/pull/165) for the relevant specification PR. + +## Browser compatibility + +{{Compat}} + +## See also + +- [File System API](/en-US/docs/Web/API/File_System_API) +- [The File System Observer API origin trial](https://developer.chrome.com/blog/file-system-observer#stop-observing-the-file-system) on developer.chrome.com (2024) diff --git a/files/en-us/web/api/filesystemobserver/observe/index.md b/files/en-us/web/api/filesystemobserver/observe/index.md new file mode 100644 index 000000000000000..3794f7f9f5706aa --- /dev/null +++ b/files/en-us/web/api/filesystemobserver/observe/index.md @@ -0,0 +1,103 @@ +--- +title: "FileSystemObserver: observe() method" +short-title: observe() +slug: Web/API/FileSystemObserver/observe +page-type: web-api-instance-method +browser-compat: api.FileSystemObserver.observe +--- + +{{securecontext_header}}{{APIRef("File System API")}} + +The **`observe()`** method of the +{{domxref("FileSystemObserver")}} interface starts the observer observing changes to a given file or directory. + +## Syntax + +```js-nolint +observe(handle) +observe(handle, options) +``` + +### Parameters + +- `handle` + - : The handle of the file system entry representing the file or directory to observe. This can be a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} for the user-observable file system, or a {{domxref("FileSystemSyncAccessHandle")}} for the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS). +- `options` {{optional_inline}} + + - : An object specifying options for the `observe()` call. This can contain the following properties: + + - `recursive` + + - : A boolean specifying whether you want to observe changes to a directory recursively. If set to `true`, changes are observed in the directory itself and all contained subdirectories and files. If set to `false`, changes are only observed in the directory itself and directly contained files (that is, not files in subdirectories). Defaults to `false`. + + This property has no effect if `handle` represents a file. + +### Return value + +A {{jsxref("Promise")}} that resolves to {{jsxref('undefined')}}. + +### Exceptions + +- `NotFoundError` {{domxref("DOMException")}} + - : Thrown if the file or directory represented by `handle` could not be found. + +## Examples + +### Observe a file or directory + +Assuming a `FileSystemObserver` instance is available, you can start observing changes to a file system entry by calling the `observe()` method on it, passing it the handle of the entry to observe. This can be a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} for the user-observable file system: + +```js +// Observe a file +async function observeFile() { + const fileHandle = await window.showSaveFilePicker(); + + await observer.observe(fileHandle); +} + +// Observe a directory +async function observeDirectory() { + const directoryHandle = await window.showDirectoryPicker(); + + await observer.observe(directoryHandle); +} +``` + +or a {{domxref("FileSystemSyncAccessHandle")}} for the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS): + +```js +// Observe an OPFS file system entry +async function observeOPFSFile() { + const root = await navigator.storage.getDirectory(); + const draftHandle = await root.getFileHandle("draft.txt", { create: true }); + const opfsHandle = await draftHandle.createSyncAccessHandle(); + + await observer.observe(opfsHandle); +} +``` + +### Observe a directory recursively + +To observe a directory recursively, call `observe()` with the `recursive` option set to `true`: + +```js +// Observe a directory recursively +async function observeDirectory() { + const directoryHandle = await window.showDirectoryPicker(); + + await observer.observe(directoryHandle, { recursive: true }); +} +``` + +## Specifications + +Not currently part of a specification. See [https://github.com/whatwg/fs/pull/165](https://github.com/whatwg/fs/pull/165) for the relevant specification PR. + +## Browser compatibility + +{{Compat}} + +## See also + +- [File System API](/en-US/docs/Web/API/File_System_API) +- [The File System Observer API origin trial](https://developer.chrome.com/blog/file-system-observer#stop-observing-the-file-system) on developer.chrome.com (2024) diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json index e4dded81dd47b54..e3f363bf8ca7047 100644 --- a/files/jsondata/GroupData.json +++ b/files/jsondata/GroupData.json @@ -581,6 +581,7 @@ "FileSystemHandle", "FileSystemFileHandle", "FileSystemDirectoryHandle", + "FileSystemObserver", "FileSystemSyncAccessHandle", "FileSystemWritableFileStream" ], From a17d3563c3ffad54a80af9bc14d6ee67f98981cf Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Sat, 22 Feb 2025 17:38:17 +0000 Subject: [PATCH 02/16] Update files/en-us/web/api/filesystemobserver/filesystemobserver/index.md Co-authored-by: Thomas Steiner --- .../web/api/filesystemobserver/filesystemobserver/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md b/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md index f3c7b98aafbd074..f97d3be4fa6ce9e 100644 --- a/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md +++ b/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md @@ -80,7 +80,7 @@ Before you can start observing file or directory changes, you need to initialize const observer = new FileSystemObserver(callback); ``` -The callback function body can be specified to return and process file change observations in any want you want: +The callback function body can be specified to return and process file change observations in any way you want: ```js const callback = (records, observer) => { From affae346ee30a78adf6cae3d8f038b18ee9776fa Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Sat, 22 Feb 2025 17:38:55 +0000 Subject: [PATCH 03/16] Update files/en-us/web/api/filesystemobserver/index.md Co-authored-by: Thomas Steiner --- files/en-us/web/api/filesystemobserver/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemobserver/index.md b/files/en-us/web/api/filesystemobserver/index.md index c78a130aa947ae7..df6644d021547f3 100644 --- a/files/en-us/web/api/filesystemobserver/index.md +++ b/files/en-us/web/api/filesystemobserver/index.md @@ -7,7 +7,7 @@ browser-compat: api.FileSystemObserver {{securecontext_header}}{{APIRef("File System API")}} -The **`FileSystemObserver`** interface of the {{domxref("File System API", "File System API", "", "nocode")}} provides a mechanism to observe changes to the underlying file systems behind the File API, both the user-observable file system and the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS). Previous to this, sites had to recursively poll the file system to find changes in the files or folder structure. This can be time-consuming, especially for large directories. +The **`FileSystemObserver`** interface of the {{domxref("File System API", "File System API", "", "nocode")}} provides a mechanism to observe changes to the underlying file systems behind the File API, both the user-observable file system and the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS). Previous to this, sites had to recursively poll the file system to find changes in the files or folder structure. This can be time-consuming and wasteful, especially for large directories. ## Constructor From 914f0d5047fda197edc62bf8317981ffabe9ded0 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Sat, 22 Feb 2025 17:41:55 +0000 Subject: [PATCH 04/16] Update files/en-us/web/api/file_system_api/index.md Co-authored-by: Thomas Steiner --- files/en-us/web/api/file_system_api/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/file_system_api/index.md b/files/en-us/web/api/file_system_api/index.md index 8740412d2777030..2ffdb83a765ab3a 100644 --- a/files/en-us/web/api/file_system_api/index.md +++ b/files/en-us/web/api/file_system_api/index.md @@ -86,7 +86,7 @@ Read our [Origin private file system](/en-US/docs/Web/API/File_System_API/Origin - {{domxref("FileSystemDirectoryHandle")}} - : Provides a handle to a file system directory. - {{domxref("FileSystemObserver")}} - - : Provides a mechanism to observe changes to the underlying file systems behind the File API, without having to rely on adhoc polling. + - : Provides a mechanism to observe changes to the underlying file systems behind the File API, without having to rely on polling. - {{domxref("FileSystemSyncAccessHandle")}} - : Provides a synchronous handle to a file system entry, which operates in-place on a single file on disk. The synchronous nature of the file reads and writes allows for higher performance for critical methods in contexts where asynchronous operations come with high overhead, e.g., [WebAssembly](/en-US/docs/WebAssembly). This class is only accessible inside dedicated [Web Workers](/en-US/docs/Web/API/Web_Workers_API) for files within the [origin private file system](#origin_private_file_system). - {{domxref("FileSystemWritableFileStream")}} From 84ee7119c4c78832ddf64c8ae9969fbccc381dbe Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Sat, 22 Feb 2025 18:08:34 +0000 Subject: [PATCH 05/16] Fixes for tomayac review comments --- .../api/filesystemobserver/filesystemobserver/index.md | 2 +- files/en-us/web/api/filesystemobserver/index.md | 8 ++++---- .../en-us/web/api/filesystemobserver/observe/index.md | 10 +++++----- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md b/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md index f97d3be4fa6ce9e..9acba444366660f 100644 --- a/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md +++ b/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md @@ -32,7 +32,7 @@ new FileSystemObserver(callback) `FileSystemChangeRecord` objects have the following structure: - `changedHandle` - - : A reference to the file system handle that the change was observed on. This can be a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} for the user-observable file system, or a {{domxref("FileSystemSyncAccessHandle")}} for the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS). This property will be `null` for records with a `"disappeared"`, `"errored"`, or `"unknown"` type. + - : A reference to the file system handle that the change was observed on. This can be a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} for the user-observable file system and the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS), or a {{domxref("FileSystemSyncAccessHandle")}} for the OPFS. This property will be `null` for records with a `"disappeared"`, `"errored"`, or `"unknown"` type. - `relativePathComponents` - : An array containing the path components that make up the relative file path from the `root` to the `changedHandle`, including the `changedHandle` filename. - `relativePathMovedFrom` diff --git a/files/en-us/web/api/filesystemobserver/index.md b/files/en-us/web/api/filesystemobserver/index.md index df6644d021547f3..0393c085e0bc3e5 100644 --- a/files/en-us/web/api/filesystemobserver/index.md +++ b/files/en-us/web/api/filesystemobserver/index.md @@ -57,7 +57,7 @@ The callback always includes two parameters: ### Observe a file or directory -Once a `FileSystemObserver` instance is available, you can start observing changes to a file system entry by running the {{domxref("FileSystemObserver.observe()")}} method, passing it the handle of the entry to observe. This can be a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} for the user-observable file system: +Once a `FileSystemObserver` instance is available, you can start observing changes to a file system entry by running the {{domxref("FileSystemObserver.observe()")}} method, passing it the handle of the entry to observe. This can be a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} for the user-observable file system and the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS): ```js // Observe a file @@ -75,16 +75,16 @@ async function observeDirectory() { } ``` -or a {{domxref("FileSystemSyncAccessHandle")}} for the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS): +or a {{domxref("FileSystemSyncAccessHandle")}} for the OPFS: ```js // Observe an OPFS file system entry async function observeOPFSFile() { const root = await navigator.storage.getDirectory(); const draftHandle = await root.getFileHandle("draft.txt", { create: true }); - const opfsHandle = await draftHandle.createSyncAccessHandle(); + const syncHandle = await draftHandle.createSyncAccessHandle(); - await observer.observe(opfsHandle); + await observer.observe(syncHandle); } ``` diff --git a/files/en-us/web/api/filesystemobserver/observe/index.md b/files/en-us/web/api/filesystemobserver/observe/index.md index 3794f7f9f5706aa..96bf70126dba132 100644 --- a/files/en-us/web/api/filesystemobserver/observe/index.md +++ b/files/en-us/web/api/filesystemobserver/observe/index.md @@ -21,7 +21,7 @@ observe(handle, options) ### Parameters - `handle` - - : The handle of the file system entry representing the file or directory to observe. This can be a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} for the user-observable file system, or a {{domxref("FileSystemSyncAccessHandle")}} for the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS). + - : The handle of the file system entry representing the file or directory to observe. This can be a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} for the user-observable file system and the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS), or a {{domxref("FileSystemSyncAccessHandle")}} for the OPFS. - `options` {{optional_inline}} - : An object specifying options for the `observe()` call. This can contain the following properties: @@ -45,7 +45,7 @@ A {{jsxref("Promise")}} that resolves to {{jsxref('undefined')}}. ### Observe a file or directory -Assuming a `FileSystemObserver` instance is available, you can start observing changes to a file system entry by calling the `observe()` method on it, passing it the handle of the entry to observe. This can be a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} for the user-observable file system: +Assuming a `FileSystemObserver` instance is available, you can start observing changes to a file system entry by calling the `observe()` method on it, passing it the handle of the entry to observe. This can be a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} for the user-observable file system and the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS): ```js // Observe a file @@ -63,16 +63,16 @@ async function observeDirectory() { } ``` -or a {{domxref("FileSystemSyncAccessHandle")}} for the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS): +or a {{domxref("FileSystemSyncAccessHandle")}} for the OPFS: ```js // Observe an OPFS file system entry async function observeOPFSFile() { const root = await navigator.storage.getDirectory(); const draftHandle = await root.getFileHandle("draft.txt", { create: true }); - const opfsHandle = await draftHandle.createSyncAccessHandle(); + const syncHandle = await draftHandle.createSyncAccessHandle(); - await observer.observe(opfsHandle); + await observer.observe(syncHandle); } ``` From 186f3785f97658dccf898ee9f112d3a1910a342c Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 25 Feb 2025 09:59:16 +0000 Subject: [PATCH 06/16] Update files/en-us/web/api/file_system_api/index.md Co-authored-by: wbamberg --- files/en-us/web/api/file_system_api/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/file_system_api/index.md b/files/en-us/web/api/file_system_api/index.md index 2ffdb83a765ab3a..61f364757bcc27e 100644 --- a/files/en-us/web/api/file_system_api/index.md +++ b/files/en-us/web/api/file_system_api/index.md @@ -86,7 +86,7 @@ Read our [Origin private file system](/en-US/docs/Web/API/File_System_API/Origin - {{domxref("FileSystemDirectoryHandle")}} - : Provides a handle to a file system directory. - {{domxref("FileSystemObserver")}} - - : Provides a mechanism to observe changes to the underlying file systems behind the File API, without having to rely on polling. + - : Provides a mechanism to observe changes to selected files or directories. - {{domxref("FileSystemSyncAccessHandle")}} - : Provides a synchronous handle to a file system entry, which operates in-place on a single file on disk. The synchronous nature of the file reads and writes allows for higher performance for critical methods in contexts where asynchronous operations come with high overhead, e.g., [WebAssembly](/en-US/docs/WebAssembly). This class is only accessible inside dedicated [Web Workers](/en-US/docs/Web/API/Web_Workers_API) for files within the [origin private file system](#origin_private_file_system). - {{domxref("FileSystemWritableFileStream")}} From f0db0b752fec65d9c0b5827f18e1b00871968fac Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 25 Feb 2025 09:59:28 +0000 Subject: [PATCH 07/16] Update files/en-us/web/api/filesystemobserver/disconnect/index.md Co-authored-by: wbamberg --- files/en-us/web/api/filesystemobserver/disconnect/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemobserver/disconnect/index.md b/files/en-us/web/api/filesystemobserver/disconnect/index.md index 57ec85dbb34fbd1..b261a8b86714a01 100644 --- a/files/en-us/web/api/filesystemobserver/disconnect/index.md +++ b/files/en-us/web/api/filesystemobserver/disconnect/index.md @@ -9,7 +9,7 @@ browser-compat: api.FileSystemObserver.disconnect {{securecontext_header}}{{APIRef("File System API")}} The **`disconnect()`** method of the -{{domxref("FileSystemObserver")}} interface stops the observer observing the filesystem. +{{domxref("FileSystemObserver")}} interface stops the observer observing the file system. ## Syntax From a758cfa911a971fa0c8cf264b13a0f9cc66c9a06 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 25 Feb 2025 10:00:50 +0000 Subject: [PATCH 08/16] Update files/en-us/web/api/filesystemobserver/filesystemobserver/index.md Co-authored-by: wbamberg --- .../web/api/filesystemobserver/filesystemobserver/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md b/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md index 9acba444366660f..e1a12c7f2516baa 100644 --- a/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md +++ b/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md @@ -8,7 +8,7 @@ status: browser-compat: api.FileSystemObserver.FileSystemObserver --- -{{APIRef("Navigation API")}}{{SeeCompatTable}} +{{APIRef("File System API")}}{{SeeCompatTable}} The **`FileSystemObserver()`** constructor creates a new {{domxref("FileSystemObserver")}} object instance. From 31283b6cf9253ba92555e16d574da6f8f36dea6c Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 25 Feb 2025 10:02:38 +0000 Subject: [PATCH 09/16] Update files/en-us/web/api/filesystemobserver/filesystemobserver/index.md Co-authored-by: wbamberg --- .../web/api/filesystemobserver/filesystemobserver/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md b/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md index e1a12c7f2516baa..534f67fb2f0f91a 100644 --- a/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md +++ b/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md @@ -61,7 +61,7 @@ new FileSystemObserver(callback) Depending on the operating system, not all observations will be reported with the same level of detail, for example, when the contents of a directory change recursively. At best, the website will receive a detailed change record containing the type of change and a handle to the affected path. At worst, the website will receive a more generic change record (that is, an `"unknown"` type) that still requires it to enumerate the directory to figure out which handle changed. -This is still an improvement over polling, since the directory enumeration can be kicked off on-demand from the callback function, rather than needing to poll for changes in intervals. +This is still an improvement over polling, since the directory enumeration can be kicked off on-demand from the callback function, rather than needing to poll for changes periodically. ### Return value From 340ed65f4d97e373dd565c457823446ce01ef1f8 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 25 Feb 2025 10:03:44 +0000 Subject: [PATCH 10/16] Update files/en-us/web/api/filesystemobserver/index.md Co-authored-by: wbamberg --- files/en-us/web/api/filesystemobserver/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemobserver/index.md b/files/en-us/web/api/filesystemobserver/index.md index 0393c085e0bc3e5..d1d6cd7ad7f3497 100644 --- a/files/en-us/web/api/filesystemobserver/index.md +++ b/files/en-us/web/api/filesystemobserver/index.md @@ -7,7 +7,7 @@ browser-compat: api.FileSystemObserver {{securecontext_header}}{{APIRef("File System API")}} -The **`FileSystemObserver`** interface of the {{domxref("File System API", "File System API", "", "nocode")}} provides a mechanism to observe changes to the underlying file systems behind the File API, both the user-observable file system and the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS). Previous to this, sites had to recursively poll the file system to find changes in the files or folder structure. This can be time-consuming and wasteful, especially for large directories. +The **`FileSystemObserver`** interface of the {{domxref("File System API", "File System API", "", "nocode")}} provides a mechanism to observe changes to the user-observable file system and the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS). This means web applications don't have to poll the file system to find changes in the files or folder structure, which can be time-consuming and wasteful. ## Constructor From e29eb03f269b11995bb1ea9e28b2c36d54dcd7b7 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 25 Feb 2025 10:05:03 +0000 Subject: [PATCH 11/16] Update files/en-us/web/api/filesystemobserver/observe/index.md Co-authored-by: wbamberg --- files/en-us/web/api/filesystemobserver/observe/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemobserver/observe/index.md b/files/en-us/web/api/filesystemobserver/observe/index.md index 96bf70126dba132..1b4f217a437d24f 100644 --- a/files/en-us/web/api/filesystemobserver/observe/index.md +++ b/files/en-us/web/api/filesystemobserver/observe/index.md @@ -9,7 +9,7 @@ browser-compat: api.FileSystemObserver.observe {{securecontext_header}}{{APIRef("File System API")}} The **`observe()`** method of the -{{domxref("FileSystemObserver")}} interface starts the observer observing changes to a given file or directory. +{{domxref("FileSystemObserver")}} interface asks the observer to start observing changes to a given file or directory. ## Syntax From 695bb161548832b725a50afd701ac3d0cd690ffa Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 25 Feb 2025 10:05:50 +0000 Subject: [PATCH 12/16] Update files/en-us/web/api/filesystemobserver/observe/index.md Co-authored-by: wbamberg --- files/en-us/web/api/filesystemobserver/observe/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemobserver/observe/index.md b/files/en-us/web/api/filesystemobserver/observe/index.md index 1b4f217a437d24f..e216ee5ab732eb0 100644 --- a/files/en-us/web/api/filesystemobserver/observe/index.md +++ b/files/en-us/web/api/filesystemobserver/observe/index.md @@ -28,7 +28,7 @@ observe(handle, options) - `recursive` - - : A boolean specifying whether you want to observe changes to a directory recursively. If set to `true`, changes are observed in the directory itself and all contained subdirectories and files. If set to `false`, changes are only observed in the directory itself and directly contained files (that is, not files in subdirectories). Defaults to `false`. + - : A boolean specifying whether you want to observe changes to a directory recursively. If set to `true`, changes are observed in the directory itself and all contained subdirectories and files. If set to `false`, changes are only observed in the directory itself and directly contained files (that is, files in subdirectories are excluded). Defaults to `false`. This property has no effect if `handle` represents a file. From acc0b9cec16d5e660bf2c4e75387275c603e00b8 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 25 Feb 2025 11:18:23 +0000 Subject: [PATCH 13/16] Add FileSystemChangeRecord page, other fixes from wbamberg review --- files/en-us/web/api/file_system_api/index.md | 4 +- .../web/api/filesystemchangerecord/index.md | 86 +++++++++++++++++++ .../filesystemobserver/index.md | 42 +-------- .../en-us/web/api/filesystemobserver/index.md | 15 ++-- .../api/filesystemobserver/observe/index.md | 13 ++- files/jsondata/GroupData.json | 1 + 6 files changed, 108 insertions(+), 53 deletions(-) create mode 100644 files/en-us/web/api/filesystemchangerecord/index.md diff --git a/files/en-us/web/api/file_system_api/index.md b/files/en-us/web/api/file_system_api/index.md index 61f364757bcc27e..f07034c6adddfb5 100644 --- a/files/en-us/web/api/file_system_api/index.md +++ b/files/en-us/web/api/file_system_api/index.md @@ -79,13 +79,15 @@ Read our [Origin private file system](/en-US/docs/Web/API/File_System_API/Origin ## Interfaces +- {{domxref("FileSystemChangeRecord")}} {{experimental_inline}} + - : Contains details of all the changes observed by a {{domxref("FileSystemObserver")}}. - {{domxref("FileSystemHandle")}} - : An object which represents a file or directory entry. Multiple handles can represent the same entry. For the most part you do not work with `FileSystemHandle` directly but rather its child interfaces {{domxref('FileSystemFileHandle')}} and {{domxref('FileSystemDirectoryHandle')}}. - {{domxref("FileSystemFileHandle")}} - : Provides a handle to a file system entry. - {{domxref("FileSystemDirectoryHandle")}} - : Provides a handle to a file system directory. -- {{domxref("FileSystemObserver")}} +- {{domxref("FileSystemObserver")}} {{experimental_inline}} - : Provides a mechanism to observe changes to selected files or directories. - {{domxref("FileSystemSyncAccessHandle")}} - : Provides a synchronous handle to a file system entry, which operates in-place on a single file on disk. The synchronous nature of the file reads and writes allows for higher performance for critical methods in contexts where asynchronous operations come with high overhead, e.g., [WebAssembly](/en-US/docs/WebAssembly). This class is only accessible inside dedicated [Web Workers](/en-US/docs/Web/API/Web_Workers_API) for files within the [origin private file system](#origin_private_file_system). diff --git a/files/en-us/web/api/filesystemchangerecord/index.md b/files/en-us/web/api/filesystemchangerecord/index.md new file mode 100644 index 000000000000000..2b563148587e350 --- /dev/null +++ b/files/en-us/web/api/filesystemchangerecord/index.md @@ -0,0 +1,86 @@ +--- +title: FileSystemChangeRecord +slug: Web/API/FileSystemChangeRecord +page-type: web-api-interface +--- + +{{APIRef("File System API")}} + +The **`FileSystemChangeRecord`** dictionary of the {{domxref("File System API", "File System API", "", "nocode")}} represents objects containing details of all the changes observed by a {{domxref("FileSystemObserver")}}. + +An array of `FileSystemChangeRecord` objects is available in the `records` array passed into the {{domxref("FileSystemObserver.FileSystemObserver", "FileSystemObserver()")}} constructor's callback function. + +## Instance properties + +- `changedHandle` + + - : A reference to the file system handle that the change was observed on. + + - For the user-observable file system, this can be a {{domxref("FileSystemFileHandle")}} or a {{domxref("FileSystemDirectoryHandle")}}. + - For the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS), it can be a {{domxref("FileSystemFileHandle")}}, a {{domxref("FileSystemDirectoryHandle")}}, or a {{domxref("FileSystemSyncAccessHandle")}}. + + This property will be `null` for records with a `"disappeared"`, `"errored"`, or `"unknown"` type. + +- `relativePathComponents` + - : An array containing the path components that make up the relative file path from the `root` to the `changedHandle`, including the `changedHandle` filename. +- `relativePathMovedFrom` + - : An array containing the path components that make up the relative file path from the `root` to the `changedHandle`'s former location, in the case of observations with a `"moved"` type. If the type is not `"moved"`, this property will be `null`. +- `root` + - : A reference to the root file system handle, that is, the one passed to the `observe()` call that started the observation. Again, this can be a {{domxref("FileSystemFileHandle")}}, {{domxref("FileSystemDirectoryHandle")}}, or {{domxref("FileSystemSyncAccessHandle")}}. +- `type` + - : A string representing the type of change that was observed. Possible values are: + - `appeared` + - : The file or directory was created or moved into the `root` file structure. + - `disappeared` + - : The file or directory was deleted or moved out of the `root` file structure. To find out which file or directory disappeared, you can query the `relativePathComponents` property. + - `errored` + - : An error state occured in the observed directory. This can result when: + - The observation is no longer valid. This can occur when the observed handle (that is, the `root` of the observation) is deleted or moved. In this case, a `"disappeared"` observation will be recorded, followed by an `"errored"` observation. In such cases, you may wish to stop observing the file system using {{domxref("FileSystemObserver.disconnect()")}}. + - The maximum limit of per-origin observations is reached. This limit is dependent on the operating system and not known beforehand. If this happens, the site may decide to retry, though there's no guarantee that the operating system will have freed up enough resources. + - Permission to access the directory or file handle is removed. + - `modified` + - : The file or directory was modified. + - `moved` + - : The file or directory was moved within the root file structure. + > [!NOTE] + > On Windows, `"moved"` observations aren't supported between directories. They are reported as a `"disappeared"` observation in the source directory and an `"appeared"` observation in the destination directory. + - `unknown` + - : Indicates that some observations were missed. If you wish to find out information on what changed in the missed observations, you could fall back to polling the observed directory. + +Depending on the operating system, not all observations will be reported with the same level of detail, for example, when the contents of a directory change recursively. At best, the website will receive a detailed change record containing the type of change and a handle to the affected path. At worst, the website will receive a more generic change record (that is, an `"unknown"` type) that still requires it to enumerate the directory to figure out which handle changed. + +This is still an improvement over polling, since the directory enumeration can be kicked off on-demand from the callback function, rather than needing to poll for changes periodically. + +## Examples + +### Initialize a `FileSystemObserver` + +Before you can start observing file or directory changes, you need to initialize a `FileSystemObserver` to handle the observations. This is done using the {{domxref("FileSystemObserver.FileSystemObserver", "FileSystemObserver()")}} constructor, which takes a callback function as an argument: + +```js +const observer = new FileSystemObserver(callback); +``` + +The [callback function](/en-US/docs/Web/API/FileSystemObserver/FileSystemObserver#callback) body can be specified to return and process file change observations in any way you want. Each object inside the `records` array is a `FileSystemChangeRecord` object: + +```js +const callback = (records, observer) => { + for (const record of records) { + console.log("Change detected:", record); + const reportContent = `Change observed to ${record.changedHandle.kind} ${record.changedHandle.name}. Type: ${record.type}.`; + sendReport(reportContent); // Some kind of user-defined reporting function + } + + observer.disconnect(); +}; +``` + +## Specifications + +Not currently part of a specification. See [https://github.com/whatwg/fs/pull/165](https://github.com/whatwg/fs/pull/165) for the relevant specification PR. + +## See also + +- {{domxref("FileSystemObserver.FileSystemObserver", "FileSystemObserver()")}} constructor +- [File System API](/en-US/docs/Web/API/File_System_API) +- [The File System Observer API origin trial](https://developer.chrome.com/blog/file-system-observer#stop-observing-the-file-system) on developer.chrome.com (2024) diff --git a/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md b/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md index 534f67fb2f0f91a..f6faec33b53d645 100644 --- a/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md +++ b/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md @@ -21,48 +21,12 @@ new FileSystemObserver(callback) ### Parameters - `callback` - - : A user-defined callback function that will be called when the observer has observed a change in the file system entry it has been tasked to observe (via {{domxref("FileSystemObserver.observe()")}}). The callback function body can be specified to return and process file change observations in any way you want, however, it always includes the following two parameters: + - : A user-defined callback function that will be called when the observer has observed a change in the file system entry it has been asked to observe (via {{domxref("FileSystemObserver.observe()")}}). The callback function will be passed the following two parameters: - `records` - - : An array of [`FileSystemChangeRecord`](#filesystemchangerecord_structure) objects that contain details of all the observed changes. + - : An array of {{domxref("FileSystemChangeRecord")}} objects that contain details of all the observed changes. - `observer` - : A reference to the current `FileSystemObserver` object, which is made available in case, for example, you want to stop observations after the current records have been received using the {{domxref('FileSystemObserver.disconnect()')}} method. -#### `FileSystemChangeRecord` structure - -`FileSystemChangeRecord` objects have the following structure: - -- `changedHandle` - - : A reference to the file system handle that the change was observed on. This can be a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} for the user-observable file system and the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS), or a {{domxref("FileSystemSyncAccessHandle")}} for the OPFS. This property will be `null` for records with a `"disappeared"`, `"errored"`, or `"unknown"` type. -- `relativePathComponents` - - : An array containing the path components that make up the relative file path from the `root` to the `changedHandle`, including the `changedHandle` filename. -- `relativePathMovedFrom` - - : An array containing the path components that make up the relative file path from the `root` to the `changedHandle`'s former location, in the case of observations with a `"moved"` type. If the type is not `"moved"`, this property will be `null`. -- `root` - - : A reference to the root file system handle, that is, the one passed to the `observe()` call that started the observation. Again, this can be a {{domxref("FileSystemFileHandle")}}, {{domxref("FileSystemDirectoryHandle")}}, or {{domxref("FileSystemSyncAccessHandle")}}. -- `type` - - : A string representing the type of change that was observed. Possible values are: - - `appeared` - - : The file or directory was created or moved into the `root` file structure. - - `disappeared` - - : The file or directory was deleted or moved out of the `root` file structure. To find out which file or directory disappeared, you can query the `relativePathComponents` property. - - `errored` - - : An error state occured in the observed directory. This can result when: - - The observation is no longer valid. This can occur when the observed handle (that is, the `root` of the observation) is deleted or moved. In this case, a `"disappeared"` observation will be recorded, followed by an `"errored"` observation. In such cases, you may wish to stop observing the file system using {{domxref("FileSystemObserver.disconnect()")}}. - - The maximum limit of per-origin observations is reached. This limit is dependent on the operating system and not known beforehand. If this happens, the site may decide to retry, though there's no guarantee that the operating system will have freed up enough resources. - - Permission to access the directory or file handle is removed. - - `modified` - - : The file or directory was modified. - - `moved` - - : The file or directory was moved within the root file structure. - > [!NOTE] - > On Windows, `"moved"` observations aren't supported between directories. They are reported as a `"disappeared"` observation in the source directory and an `"appeared"` observation in the destination directory. They are reported as `"moved"` when the source and destination are both in the same directory. - - `unknown` - - : Indicates that some observations were missed. If you wish to find out information on what changed in the missed observations, you could fall back to polling the observed directory. - -Depending on the operating system, not all observations will be reported with the same level of detail, for example, when the contents of a directory change recursively. At best, the website will receive a detailed change record containing the type of change and a handle to the affected path. At worst, the website will receive a more generic change record (that is, an `"unknown"` type) that still requires it to enumerate the directory to figure out which handle changed. - -This is still an improvement over polling, since the directory enumeration can be kicked off on-demand from the callback function, rather than needing to poll for changes periodically. - ### Return value A new {{domxref("FileSystemObserver")}} object. @@ -70,7 +34,7 @@ A new {{domxref("FileSystemObserver")}} object. ## Examples > [!NOTE] -> For a complete working example, check out [File System Observer Demo](https://file-system-observer.glitch.me/). +> For a complete working example, check out [File System Observer Demo](https://file-system-observer.glitch.me/) ([source code](https://glitch.com/edit/#!/file-system-observer)). ### Initializing a `FileSystemObserver` diff --git a/files/en-us/web/api/filesystemobserver/index.md b/files/en-us/web/api/filesystemobserver/index.md index d1d6cd7ad7f3497..57c2f5410b17dc9 100644 --- a/files/en-us/web/api/filesystemobserver/index.md +++ b/files/en-us/web/api/filesystemobserver/index.md @@ -24,7 +24,7 @@ The **`FileSystemObserver`** interface of the {{domxref("File System API", "File ## Examples > [!NOTE] -> For a complete working example, check out [File System Observer Demo](https://file-system-observer.glitch.me/). +> For a complete working example, check out [File System Observer Demo](https://file-system-observer.glitch.me/) ([source code](https://glitch.com/edit/#!/file-system-observer)). ### Initialize a `FileSystemObserver` @@ -48,16 +48,11 @@ const callback = (records, observer) => { }; ``` -The callback always includes two parameters: - -- `records` - - : An array of [`FileSystemChangeRecord`](/en-US/docs/Web/API/FileSystemObserver/FileSystemObserver#filesystemchangerecord_structure) objects that contain details of all the observed changes. -- `observer` - - : A reference to the current `FileSystemObserver` object, which is made available in case, for example, you want to stop observations after the current records have been received using the {{domxref('FileSystemObserver.disconnect', 'disconnect()')}} method, as shown above. - ### Observe a file or directory -Once a `FileSystemObserver` instance is available, you can start observing changes to a file system entry by running the {{domxref("FileSystemObserver.observe()")}} method, passing it the handle of the entry to observe. This can be a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} for the user-observable file system and the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS): +Once a `FileSystemObserver` instance is available, you can start observing changes to a file system entry by calling the {{domxref("FileSystemObserver.observe()")}} method. + +You can observe a file or directory in the user-observable file system or the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS) by passing a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} to `observe()`. Instances of these objects can be returned, for example, when asking the user to select a file or directory using {{domxref("Window.showSaveFilePicker()")}} or {{domxref("Window.showDirectoryPicker()")}}: ```js // Observe a file @@ -75,7 +70,7 @@ async function observeDirectory() { } ``` -or a {{domxref("FileSystemSyncAccessHandle")}} for the OPFS: +You can also observe changes to the OPFS by passing a {{domxref("FileSystemSyncAccessHandle")}} to `observe()`: ```js // Observe an OPFS file system entry diff --git a/files/en-us/web/api/filesystemobserver/observe/index.md b/files/en-us/web/api/filesystemobserver/observe/index.md index e216ee5ab732eb0..a57ee73b79f3317 100644 --- a/files/en-us/web/api/filesystemobserver/observe/index.md +++ b/files/en-us/web/api/filesystemobserver/observe/index.md @@ -21,7 +21,12 @@ observe(handle, options) ### Parameters - `handle` - - : The handle of the file system entry representing the file or directory to observe. This can be a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} for the user-observable file system and the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS), or a {{domxref("FileSystemSyncAccessHandle")}} for the OPFS. + + - : The handle of the file system entry representing the file or directory to observe. + + - For the user-observable file system, this can be a {{domxref("FileSystemFileHandle")}} or a {{domxref("FileSystemDirectoryHandle")}}. + - For the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS), it can be a {{domxref("FileSystemFileHandle")}}, a {{domxref("FileSystemDirectoryHandle")}}, or a {{domxref("FileSystemSyncAccessHandle")}}. + - `options` {{optional_inline}} - : An object specifying options for the `observe()` call. This can contain the following properties: @@ -45,7 +50,9 @@ A {{jsxref("Promise")}} that resolves to {{jsxref('undefined')}}. ### Observe a file or directory -Assuming a `FileSystemObserver` instance is available, you can start observing changes to a file system entry by calling the `observe()` method on it, passing it the handle of the entry to observe. This can be a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} for the user-observable file system and the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS): +Assuming a `FileSystemObserver` instance is available, you can start observing changes to a file system entry by calling `observe()`. + +You can observe a file or directory in the user-observable file system or the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS) by passing a {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} to `observe()`. Instances of these objects can be returned, for example, when asking the user to select a file or directory using {{domxref("Window.showSaveFilePicker()")}} or {{domxref("Window.showDirectoryPicker()")}}: ```js // Observe a file @@ -63,7 +70,7 @@ async function observeDirectory() { } ``` -or a {{domxref("FileSystemSyncAccessHandle")}} for the OPFS: +You can also observe changes to the OPFS by passing a {{domxref("FileSystemSyncAccessHandle")}} to `observe()`: ```js // Observe an OPFS file system entry diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json index e3f363bf8ca7047..d4270e9c2370de9 100644 --- a/files/jsondata/GroupData.json +++ b/files/jsondata/GroupData.json @@ -578,6 +578,7 @@ "overview": ["File System API"], "guides": ["/docs/Web/API/File_System_API/Origin_private_file_system"], "interfaces": [ + "FileSystemChangeRecord", "FileSystemHandle", "FileSystemFileHandle", "FileSystemDirectoryHandle", From 09300e3d9aa2836f1ca61442d5dac38c50c7a265 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Thu, 27 Feb 2025 18:56:46 +0000 Subject: [PATCH 14/16] Update files/en-us/web/api/filesystemchangerecord/index.md Co-authored-by: wbamberg --- files/en-us/web/api/filesystemchangerecord/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemchangerecord/index.md b/files/en-us/web/api/filesystemchangerecord/index.md index 2b563148587e350..9b74cbc4511045b 100644 --- a/files/en-us/web/api/filesystemchangerecord/index.md +++ b/files/en-us/web/api/filesystemchangerecord/index.md @@ -6,7 +6,7 @@ page-type: web-api-interface {{APIRef("File System API")}} -The **`FileSystemChangeRecord`** dictionary of the {{domxref("File System API", "File System API", "", "nocode")}} represents objects containing details of all the changes observed by a {{domxref("FileSystemObserver")}}. +The **`FileSystemChangeRecord`** dictionary of the {{domxref("File System API", "File System API", "", "nocode")}} contains details of a single change observed by a {{domxref("FileSystemObserver")}}. An array of `FileSystemChangeRecord` objects is available in the `records` array passed into the {{domxref("FileSystemObserver.FileSystemObserver", "FileSystemObserver()")}} constructor's callback function. From e1b86832cac8dd6298c6d4a761e159a07578ffb9 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Thu, 27 Feb 2025 18:57:06 +0000 Subject: [PATCH 15/16] Update files/en-us/web/api/filesystemchangerecord/index.md Co-authored-by: wbamberg --- files/en-us/web/api/filesystemchangerecord/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemchangerecord/index.md b/files/en-us/web/api/filesystemchangerecord/index.md index 9b74cbc4511045b..80a13b147784425 100644 --- a/files/en-us/web/api/filesystemchangerecord/index.md +++ b/files/en-us/web/api/filesystemchangerecord/index.md @@ -8,7 +8,7 @@ page-type: web-api-interface The **`FileSystemChangeRecord`** dictionary of the {{domxref("File System API", "File System API", "", "nocode")}} contains details of a single change observed by a {{domxref("FileSystemObserver")}}. -An array of `FileSystemChangeRecord` objects is available in the `records` array passed into the {{domxref("FileSystemObserver.FileSystemObserver", "FileSystemObserver()")}} constructor's callback function. +The `records` argument passed into the {{domxref("FileSystemObserver.FileSystemObserver", "FileSystemObserver()")}} constructor's callback function is an array of `FileSystemChangeRecord` objects. ## Instance properties From 041418182f6a71d97b2d2caba872126495d4c824 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Thu, 27 Feb 2025 18:59:55 +0000 Subject: [PATCH 16/16] Update FileSystemChangeRecord description --- files/en-us/web/api/file_system_api/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/file_system_api/index.md b/files/en-us/web/api/file_system_api/index.md index f07034c6adddfb5..6bf4addb1167370 100644 --- a/files/en-us/web/api/file_system_api/index.md +++ b/files/en-us/web/api/file_system_api/index.md @@ -80,7 +80,7 @@ Read our [Origin private file system](/en-US/docs/Web/API/File_System_API/Origin ## Interfaces - {{domxref("FileSystemChangeRecord")}} {{experimental_inline}} - - : Contains details of all the changes observed by a {{domxref("FileSystemObserver")}}. + - : Contains details of a single change observed by a {{domxref("FileSystemObserver")}}. - {{domxref("FileSystemHandle")}} - : An object which represents a file or directory entry. Multiple handles can represent the same entry. For the most part you do not work with `FileSystemHandle` directly but rather its child interfaces {{domxref('FileSystemFileHandle')}} and {{domxref('FileSystemDirectoryHandle')}}. - {{domxref("FileSystemFileHandle")}}