Editorial review: Document FileSystemObserver #38270

chrisdavidmills · 2025-02-21T14:48:06Z

Description

Chrome 133 supports the FileSystemObserver interface, which allows you to observe changes to the underlying file system via a standard observer mechanism.

This PR adds documentation for the new functionality, which mainly consists of new reference pages for the new interface.

Note that the feature is currently non-standard (see whatwg/fs#165), although it should be added to the spec soon. I have currently documented it as such.

Motivation

Additional details

See the relevant ChromeStatus entry for data: https://chromestatus.com/feature/4622243656630272

Relevant blog post: https://developer.chrome.com/blog/file-system-observer#start_observing_a_file_or_directory

Related issues and pull requests

Related BCD: mdn/browser-compat-data#25986

github-actions · 2025-02-21T14:49:38Z

Preview URLs (6 pages)

Flaws (6)

Note! 5 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/File_System_API
Title: File System API
Flaw count: 6

broken_links:
- /en-US/docs/Web/API/window/showOpenFilePicker is ill cased
- /en-US/docs/Web/API/window/showDirectoryPicker is ill cased
- /en-US/docs/Web/API/window/postMessage is ill cased
macros:
- Macro produces link /en-US/docs/Web/API/window/showOpenFilePicker which is a redirect
- Macro produces link /en-US/docs/Web/API/window/showDirectoryPicker which is a redirect
- Macro produces link /en-US/docs/Web/API/window/postMessage which is a redirect

External URLs (14)

URL: /en-US/docs/Web/API/FileSystemChangeRecord
Title: FileSystemChangeRecord

https://developer.chrome.com/blog/file-system-observer (1 time) (Note! This may be a new URL 👀)
https://github.com/whatwg/fs/pull/165 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/FileSystemObserver
Title: FileSystemObserver

https://developer.chrome.com/blog/file-system-observer (1 time) (Note! This may be a new URL 👀)
https://file-system-observer.glitch.me/ (1 time) (Note! This may be a new URL 👀)
https://github.com/whatwg/fs/pull/165 (1 time) (Note! This may be a new URL 👀)
https://glitch.com/edit/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/FileSystemObserver/observe
Title: FileSystemObserver: observe() method

https://developer.chrome.com/blog/file-system-observer (1 time) (Note! This may be a new URL 👀)
https://github.com/whatwg/fs/pull/165 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/FileSystemObserver/FileSystemObserver
Title: FileSystemObserver: FileSystemObserver() constructor

https://developer.chrome.com/blog/file-system-observer (1 time) (Note! This may be a new URL 👀)
https://file-system-observer.glitch.me/ (1 time) (Note! This may be a new URL 👀)
https://github.com/whatwg/fs/pull/165 (1 time) (Note! This may be a new URL 👀)
https://glitch.com/edit/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/FileSystemObserver/disconnect
Title: FileSystemObserver: disconnect() method

https://developer.chrome.com/blog/file-system-observer (1 time) (Note! This may be a new URL 👀)
https://github.com/whatwg/fs/pull/165 (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-02-25 11:20:06)

tomayac

This looks great. Left a bunch of suggestions.

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

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

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

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

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

…x.md Co-authored-by: Thomas Steiner <[email protected]>

Co-authored-by: Thomas Steiner <[email protected]>

chrisdavidmills · 2025-02-22T18:14:56Z

@tomayac thanks for the review! I think I've answered everything. Let me know if you feel this needs anything else, or give me an LGTM if you are happy with it.

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

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

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

wbamberg · 2025-02-24T22:57:56Z

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

+#### `FileSystemChangeRecord` structure
+
+`FileSystemChangeRecord` objects have the following structure:


I think there are really two ways of dealing with dictionaries:

document them inline as anonymous objects (so under the records bullet above say something like "an array of objects contain details of all the observed changes. Each object has the following properties:"

document them in separate pages, like we do for example with https://developer.mozilla.org/en-US/docs/Web/API/RequestInit.

Because this is quite a complex object it might be worth going with (2) here.

OK, I've given it a go. My next commit now contains a new FileSystemChangeRecord page, which is included in the sidebar and linked to from the appropriate places.

wbamberg · 2025-02-25T00:02:08Z

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

+### 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:


Suggested change

- : 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 following two parameters:

Subjective I suppose but surely it's obvious that you can implement the callback however you like?

Agreed. I've implemented this change in my next commit, with a small tweak.

wbamberg · 2025-02-25T01:04:49Z

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

+}
+```
+
+or a {{domxref("FileSystemSyncAccessHandle")}} for the OPFS:


As before this reads like you're duplicating the syntax description.

I would say, for example, something like:

Once a FileSystemObserver instance is available, you can start observing changes to a file system entry.

You can observe a file or a directory in the user-visible file system, for example by asking the user to select a file or directory using window.showSaveFilePicker() or window.showDirectoryPicker():

(example)

You can also observe a file in the OPFS:

(example)

Good call; I've updated this as suggested

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

wbamberg · 2025-02-25T01:06:56Z

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

+### 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.


Same comment as before:

Suggested change

- : 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 or a a {{domxref("FileSystemFileHandle")}}, a {{domxref("FileSystemDirectoryHandle")}}, or a {{domxref("FileSystemSyncAccessHandle")}}.

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

wbamberg · 2025-02-25T01:09:01Z

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

+
+### 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):


As before, I think explaining the different use cases is more helpful in an example than duplicating the types you can pass.

updated, same as the other page.

Co-authored-by: wbamberg <[email protected]>

…x.md Co-authored-by: wbamberg <[email protected]>

Co-authored-by: wbamberg <[email protected]>

Document FileSystemObserver

7b0838d

chrisdavidmills requested review from a team as code owners February 21, 2025 14:48

chrisdavidmills requested review from sideshowbarker and pepelsbey and removed request for a team February 21, 2025 14:48

github-actions bot added Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed labels Feb 21, 2025

chrisdavidmills changed the title ~~Document FileSystemObserver~~ Technical review: Document FileSystemObserver Feb 21, 2025

tomayac reviewed Feb 21, 2025

View reviewed changes

chrisdavidmills and others added 4 commits February 22, 2025 17:38

Update files/en-us/web/api/filesystemobserver/filesystemobserver/inde…

a17d356

…x.md Co-authored-by: Thomas Steiner <[email protected]>

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

affae34

Co-authored-by: Thomas Steiner <[email protected]>

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

914f0d5

Co-authored-by: Thomas Steiner <[email protected]>

Fixes for tomayac review comments

84ee711

chrisdavidmills requested a review from tomayac February 22, 2025 18:10

chrisdavidmills changed the title ~~Technical review: Document FileSystemObserver~~ Editorial review: Document FileSystemObserver Feb 24, 2025

wbamberg requested review from wbamberg and removed request for tomayac February 24, 2025 16:39

wbamberg reviewed Feb 25, 2025

View reviewed changes

chrisdavidmills and others added 8 commits February 25, 2025 09:59

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

186f378

Co-authored-by: wbamberg <[email protected]>

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

f0db0b7

Co-authored-by: wbamberg <[email protected]>

Update files/en-us/web/api/filesystemobserver/filesystemobserver/inde…

a758cfa

…x.md Co-authored-by: wbamberg <[email protected]>

Update files/en-us/web/api/filesystemobserver/filesystemobserver/inde…

31283b6

…x.md Co-authored-by: wbamberg <[email protected]>

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

340ed65

Co-authored-by: wbamberg <[email protected]>

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

e29eb03

Co-authored-by: wbamberg <[email protected]>

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

695bb16

Co-authored-by: wbamberg <[email protected]>

Add FileSystemChangeRecord page, other fixes from wbamberg review

acc0b9c

chrisdavidmills requested a review from wbamberg February 25, 2025 11:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Editorial review: Document FileSystemObserver #38270

Editorial review: Document FileSystemObserver #38270

chrisdavidmills commented Feb 21, 2025 •

edited

Loading

github-actions bot commented Feb 21, 2025 •

edited

Loading

tomayac left a comment

chrisdavidmills commented Feb 22, 2025

wbamberg Feb 24, 2025

chrisdavidmills Feb 25, 2025

wbamberg Feb 25, 2025

chrisdavidmills Feb 25, 2025

wbamberg Feb 25, 2025

chrisdavidmills Feb 25, 2025

wbamberg Feb 25, 2025

chrisdavidmills Feb 25, 2025

wbamberg Feb 25, 2025

chrisdavidmills Feb 25, 2025

		#### `FileSystemChangeRecord` structure

		`FileSystemChangeRecord` objects have the following structure:

	- : 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 following two parameters:


		### 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):

Editorial review: Document FileSystemObserver #38270

Are you sure you want to change the base?

Editorial review: Document FileSystemObserver #38270

Conversation

chrisdavidmills commented Feb 21, 2025 • edited Loading

Description

Motivation

Additional details

Related issues and pull requests

github-actions bot commented Feb 21, 2025 • edited Loading

tomayac left a comment

Choose a reason for hiding this comment

chrisdavidmills commented Feb 22, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisdavidmills commented Feb 21, 2025 •

edited

Loading

github-actions bot commented Feb 21, 2025 •

edited

Loading