Editorial review: Document FileSystemObserver

files/en-us/web/api/file_system_api/index.md

@@ -79,12 +79,16 @@ Read our [Origin private file system](/en-US/docs/Web/API/File_System_API/Origin
 
 ## Interfaces
 
+- {{domxref("FileSystemChangeRecord")}} {{experimental_inline}}
+  - : 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")}}
   - : Provides a handle to a file system entry.
 - {{domxref("FileSystemDirectoryHandle")}}
   - : Provides a handle to a file system directory.
+- {{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).
 - {{domxref("FileSystemWritableFileStream")}}

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")}} contains details of a single change observed by a {{domxref("FileSystemObserver")}}.
+
+The `records` argument passed into the {{domxref("FileSystemObserver.FileSystemObserver", "FileSystemObserver()")}} constructor's callback function is an array of `FileSystemChangeRecord` objects.
+
+## 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)

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 file system.
+
+## 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)

files/en-us/web/api/filesystemobserver/filesystemobserver/index.md

@@ -0,0 +1,72 @@
+---
+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("File System 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 asked to observe (via {{domxref("FileSystemObserver.observe()")}}). The callback function will be passed the following two parameters:
+    - `records`
+      - : 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.
+
+### 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/) ([source code](https://glitch.com/edit/#!/file-system-observer)).
+
+### 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 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();
+};
+```
+
+## 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)

files/en-us/web/api/filesystemobserver/index.md

@@ -0,0 +1,105 @@
+---
+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 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
+
+- {{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/) ([source code](https://glitch.com/edit/#!/file-system-observer)).
+
+### 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();
+};
+```
+
+### Observe a file or directory
+
+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
+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);
+}
+```
+
+You can also observe changes to the OPFS by passing a {{domxref("FileSystemSyncAccessHandle")}} to `observe()`:
+
+```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 syncHandle = await draftHandle.createSyncAccessHandle();
+
+  await observer.observe(syncHandle);
+}
+```
+
+### 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)