Skip to content

Commit 328a784

Browse files
chrisdavidmillstomayacwbamberg
authored
Editorial review: Document FileSystemObserver (#38270)
* Document FileSystemObserver * Update files/en-us/web/api/filesystemobserver/filesystemobserver/index.md Co-authored-by: Thomas Steiner <[email protected]> * Update files/en-us/web/api/filesystemobserver/index.md Co-authored-by: Thomas Steiner <[email protected]> * Update files/en-us/web/api/file_system_api/index.md Co-authored-by: Thomas Steiner <[email protected]> * Fixes for tomayac review comments * Update files/en-us/web/api/file_system_api/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/filesystemobserver/disconnect/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/filesystemobserver/filesystemobserver/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/filesystemobserver/filesystemobserver/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/filesystemobserver/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/filesystemobserver/observe/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/filesystemobserver/observe/index.md Co-authored-by: wbamberg <[email protected]> * Add FileSystemChangeRecord page, other fixes from wbamberg review * Update files/en-us/web/api/filesystemchangerecord/index.md Co-authored-by: wbamberg <[email protected]> * Update files/en-us/web/api/filesystemchangerecord/index.md Co-authored-by: wbamberg <[email protected]> * Update FileSystemChangeRecord description --------- Co-authored-by: Thomas Steiner <[email protected]> Co-authored-by: wbamberg <[email protected]>
1 parent bc18969 commit 328a784

File tree

7 files changed

+428
-0
lines changed

7 files changed

+428
-0
lines changed

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,12 +79,16 @@ Read our [Origin private file system](/en-US/docs/Web/API/File_System_API/Origin
7979

8080
## Interfaces
8181

82+
- {{domxref("FileSystemChangeRecord")}} {{experimental_inline}}
83+
- : Contains details of a single change observed by a {{domxref("FileSystemObserver")}}.
8284
- {{domxref("FileSystemHandle")}}
8385
- : 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')}}.
8486
- {{domxref("FileSystemFileHandle")}}
8587
- : Provides a handle to a file system entry.
8688
- {{domxref("FileSystemDirectoryHandle")}}
8789
- : Provides a handle to a file system directory.
90+
- {{domxref("FileSystemObserver")}} {{experimental_inline}}
91+
- : Provides a mechanism to observe changes to selected files or directories.
8892
- {{domxref("FileSystemSyncAccessHandle")}}
8993
- : 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).
9094
- {{domxref("FileSystemWritableFileStream")}}

‎files/en-us/web/api/filesystemchangerecord/index.md

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
title: FileSystemChangeRecord
3+
slug: Web/API/FileSystemChangeRecord
4+
page-type: web-api-interface
5+
---
6+
7+
{{APIRef("File System API")}}
8+
9+
The **`FileSystemChangeRecord`** dictionary of the {{domxref("File System API", "File System API", "", "nocode")}} contains details of a single change observed by a {{domxref("FileSystemObserver")}}.
10+
11+
The `records` argument passed into the {{domxref("FileSystemObserver.FileSystemObserver", "FileSystemObserver()")}} constructor's callback function is an array of `FileSystemChangeRecord` objects.
12+
13+
## Instance properties
14+
15+
- `changedHandle`
16+
17+
- : A reference to the file system handle that the change was observed on.
18+
19+
- For the user-observable file system, this can be a {{domxref("FileSystemFileHandle")}} or a {{domxref("FileSystemDirectoryHandle")}}.
20+
- 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")}}.
21+
22+
This property will be `null` for records with a `"disappeared"`, `"errored"`, or `"unknown"` type.
23+
24+
- `relativePathComponents`
25+
- : An array containing the path components that make up the relative file path from the `root` to the `changedHandle`, including the `changedHandle` filename.
26+
- `relativePathMovedFrom`
27+
- : 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`.
28+
- `root`
29+
- : 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")}}.
30+
- `type`
31+
- : A string representing the type of change that was observed. Possible values are:
32+
- `appeared`
33+
- : The file or directory was created or moved into the `root` file structure.
34+
- `disappeared`
35+
- : 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.
36+
- `errored`
37+
- : An error state occured in the observed directory. This can result when:
38+
- 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()")}}.
39+
- 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.
40+
- Permission to access the directory or file handle is removed.
41+
- `modified`
42+
- : The file or directory was modified.
43+
- `moved`
44+
- : The file or directory was moved within the root file structure.
45+
> [!NOTE]
46+
> 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.
47+
- `unknown`
48+
- : 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.
49+
50+
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.
51+
52+
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.
53+
54+
## Examples
55+
56+
### Initialize a `FileSystemObserver`
57+
58+
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:
59+
60+
```js
61+
const observer = new FileSystemObserver(callback);
62+
```
63+
64+
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:
65+
66+
```js
67+
const callback = (records, observer) => {
68+
for (const record of records) {
69+
console.log("Change detected:", record);
70+
const reportContent = `Change observed to ${record.changedHandle.kind} ${record.changedHandle.name}. Type: ${record.type}.`;
71+
sendReport(reportContent); // Some kind of user-defined reporting function
72+
}
73+
74+
observer.disconnect();
75+
};
76+
```
77+
78+
## Specifications
79+
80+
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.
81+
82+
## See also
83+
84+
- {{domxref("FileSystemObserver.FileSystemObserver", "FileSystemObserver()")}} constructor
85+
- [File System API](/en-US/docs/Web/API/File_System_API)
86+
- [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

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: "FileSystemObserver: disconnect() method"
3+
short-title: disconnect()
4+
slug: Web/API/FileSystemObserver/disconnect
5+
page-type: web-api-instance-method
6+
browser-compat: api.FileSystemObserver.disconnect
7+
---
8+
9+
{{securecontext_header}}{{APIRef("File System API")}}
10+
11+
The **`disconnect()`** method of the
12+
{{domxref("FileSystemObserver")}} interface stops the observer observing the file system.
13+
14+
## Syntax
15+
16+
```js-nolint
17+
disconnect()
18+
```
19+
20+
### Parameters
21+
22+
None.
23+
24+
### Return value
25+
26+
None ({{jsxref('undefined')}}).
27+
28+
## Examples
29+
30+
### Stop observing the file system
31+
32+
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:
33+
34+
```js
35+
observer.disconnect();
36+
```
37+
38+
## Specifications
39+
40+
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.
41+
42+
## Browser compatibility
43+
44+
{{Compat}}
45+
46+
## See also
47+
48+
- [File System API](/en-US/docs/Web/API/File_System_API)
49+
- [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

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
title: "FileSystemObserver: FileSystemObserver() constructor"
3+
short-title: FileSystemObserver()
4+
slug: Web/API/FileSystemObserver/FileSystemObserver
5+
page-type: web-api-constructor
6+
status:
7+
- experimental
8+
browser-compat: api.FileSystemObserver.FileSystemObserver
9+
---
10+
11+
{{APIRef("File System API")}}{{SeeCompatTable}}
12+
13+
The **`FileSystemObserver()`** constructor creates a new {{domxref("FileSystemObserver")}} object instance.
14+
15+
## Syntax
16+
17+
```js-nolint
18+
new FileSystemObserver(callback)
19+
```
20+
21+
### Parameters
22+
23+
- `callback`
24+
- : 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:
25+
- `records`
26+
- : An array of {{domxref("FileSystemChangeRecord")}} objects that contain details of all the observed changes.
27+
- `observer`
28+
- : 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.
29+
30+
### Return value
31+
32+
A new {{domxref("FileSystemObserver")}} object.
33+
34+
## Examples
35+
36+
> [!NOTE]
37+
> 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)).
38+
39+
### Initializing a `FileSystemObserver`
40+
41+
Before you can start observing file or directory changes, you need to initialize a `FileSystemObserver` to handle the observations:
42+
43+
```js
44+
const observer = new FileSystemObserver(callback);
45+
```
46+
47+
The callback function body can be specified to return and process file change observations in any way you want:
48+
49+
```js
50+
const callback = (records, observer) => {
51+
for (const record of records) {
52+
console.log("Change detected:", record);
53+
const reportContent = `Change observed to ${record.changedHandle.kind} ${record.changedHandle.name}. Type: ${record.type}.`;
54+
sendReport(reportContent); // Some kind of user-defined reporting function
55+
}
56+
57+
observer.disconnect();
58+
};
59+
```
60+
61+
## Specifications
62+
63+
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.
64+
65+
## Browser compatibility
66+
67+
{{Compat}}
68+
69+
## See also
70+
71+
- [File System API](/en-US/docs/Web/API/File_System_API)
72+
- [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

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
title: FileSystemObserver
3+
slug: Web/API/FileSystemObserver
4+
page-type: web-api-interface
5+
browser-compat: api.FileSystemObserver
6+
---
7+
8+
{{securecontext_header}}{{APIRef("File System API")}}
9+
10+
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.
11+
12+
## Constructor
13+
14+
- {{domxref("FileSystemObserver.FileSystemObserver", "FileSystemObserver()")}} {{Experimental_Inline}}
15+
- : Creates a new `FileSystemObserver` object instance.
16+
17+
## Instance methods
18+
19+
- {{domxref("FileSystemObserver.disconnect", "disconnect()")}} {{Experimental_Inline}}
20+
- : Stop observing the filesystem.
21+
- {{domxref("FileSystemObserver.observe", "observe()")}} {{Experimental_Inline}}
22+
- : Start observing changes to a given file or directory.
23+
24+
## Examples
25+
26+
> [!NOTE]
27+
> 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)).
28+
29+
### Initialize a `FileSystemObserver`
30+
31+
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:
32+
33+
```js
34+
const observer = new FileSystemObserver(callback);
35+
```
36+
37+
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:
38+
39+
```js
40+
const callback = (records, observer) => {
41+
for (const record of records) {
42+
console.log("Change detected:", record);
43+
const reportContent = `Change observed to ${record.changedHandle.kind} ${record.changedHandle.name}. Type: ${record.type}.`;
44+
sendReport(reportContent); // Some kind of user-defined reporting function
45+
}
46+
47+
observer.disconnect();
48+
};
49+
```
50+
51+
### Observe a file or directory
52+
53+
Once a `FileSystemObserver` instance is available, you can start observing changes to a file system entry by calling the {{domxref("FileSystemObserver.observe()")}} method.
54+
55+
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()")}}:
56+
57+
```js
58+
// Observe a file
59+
async function observeFile() {
60+
const fileHandle = await window.showSaveFilePicker();
61+
62+
await observer.observe(fileHandle);
63+
}
64+
65+
// Observe a directory
66+
async function observeDirectory() {
67+
const directoryHandle = await window.showDirectoryPicker();
68+
69+
await observer.observe(directoryHandle);
70+
}
71+
```
72+
73+
You can also observe changes to the OPFS by passing a {{domxref("FileSystemSyncAccessHandle")}} to `observe()`:
74+
75+
```js
76+
// Observe an OPFS file system entry
77+
async function observeOPFSFile() {
78+
const root = await navigator.storage.getDirectory();
79+
const draftHandle = await root.getFileHandle("draft.txt", { create: true });
80+
const syncHandle = await draftHandle.createSyncAccessHandle();
81+
82+
await observer.observe(syncHandle);
83+
}
84+
```
85+
86+
### Stop observing the file system
87+
88+
When you want to stop observing changes to the file system entry, you can call {{domxref("FileSystemObserver.disconnect()")}}:
89+
90+
```js
91+
observer.disconnect();
92+
```
93+
94+
## Specifications
95+
96+
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.
97+
98+
## Browser compatibility
99+
100+
{{Compat}}
101+
102+
## See also
103+
104+
- [File System API](/en-US/docs/Web/API/File_System_API)
105+
- [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)

0 commit comments

Comments
 (0)