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/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 👀)

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 👀)

(comment last updated: 2025-02-27 19:01:14)

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.

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

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

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

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

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

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

tomayac · 2025-02-27T10:07:43Z

Just confirming that https://glitch.com/edit/#!/file-system-observer?path=.prettierrc%3A1%3A0 is by me, @tomayac. It's the demo embedded in the article on chrome.dev.

Elchi3 · 2025-02-27T10:50:02Z

What's the license of your code, @tomayac? If we want to publish your code (at a later stage) in https://github.com/mdn/dom-examples (CCO) would that be compatible?

tomayac · 2025-02-27T10:52:39Z

What's the license of your code, @tomayac? If we want to publish your code (at a later stage) in https://github.com/mdn/dom-examples (CCO) would that be compatible?

All our code samples are Apache-2.0 licensed. You can publish the sample without any worries.

chrisdavidmills · 2025-02-27T13:58:47Z

What's the license of your code, @tomayac? If we want to publish your code (at a later stage) in https://github.com/mdn/dom-examples (CCO) would that be compatible?

All our code samples are Apache-2.0 licensed. You can publish the sample without any worries.

Thanks @tomayac; see #38270 (comment).

wbamberg

Just a couple of suggestions in the new FileSystemChangeRecord page.

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

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

wbamberg

👍 thank you Chris!

Josh-Cena · 2025-03-29T04:23:34Z

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

+
+{{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")}}.


@wbamberg @chrisdavidmills Any reason for documenting this dictionary in its own page rather than inlining it, as per our typical policy?

It's discussed here: #38270 (comment). Arguably, because it's a large and complex object, it's easier to read the docs when it is a separate page than when it is inline.

I don't feel very strongly though. I don't think this is a clear "use a dictionary" case - in particular, it is only used in that one place. But I could see the constructor page getting pretty unwieldy with all those indented lists to keep straight.

OK that sounds reasonable. Just making sure we are not making more undesirable stuff that we have to clean up laer.

* 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]>

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

chrisdavidmills mentioned this pull request Feb 27, 2025

Add FileSystemObserver demo mdn/dom-examples#297

Merged

Merge branch 'main' into filesystemobserver

ca190b7

wbamberg reviewed Feb 27, 2025

View reviewed changes

files/en-us/web/api/filesystemchangerecord/index.md Outdated Show resolved Hide resolved

files/en-us/web/api/filesystemchangerecord/index.md Outdated Show resolved Hide resolved

chrisdavidmills and others added 3 commits February 27, 2025 18:56

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

09300e3

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

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

e1b8683

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

Update FileSystemChangeRecord description

0414181

chrisdavidmills requested a review from wbamberg February 27, 2025 19:00

wbamberg approved these changes Feb 27, 2025

View reviewed changes

wbamberg merged commit 328a784 into mdn:main Feb 27, 2025
9 checks passed

Josh-Cena reviewed Mar 29, 2025

View reviewed changes

nathanmemmott mentioned this pull request Apr 10, 2025

Add the FileSystemObserver API whatwg/fs#165

Open

5 tasks

		#### `FileSystemChangeRecord` structure

		`FileSystemChangeRecord` objects have the following structure:


		{{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")}}.

Editorial review: Document FileSystemObserver #38270

Editorial review: Document FileSystemObserver #38270

Uh oh!

Conversation

chrisdavidmills commented Feb 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

github-actions bot commented Feb 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tomayac left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chrisdavidmills commented Feb 22, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wbamberg Feb 24, 2025

Choose a reason for hiding this comment

Uh oh!

chrisdavidmills Feb 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tomayac commented Feb 27, 2025

Uh oh!

Elchi3 commented Feb 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tomayac commented Feb 27, 2025

Uh oh!

chrisdavidmills commented Feb 27, 2025

Uh oh!

wbamberg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

wbamberg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Josh-Cena Mar 29, 2025

Choose a reason for hiding this comment

Uh oh!

wbamberg Mar 29, 2025

Choose a reason for hiding this comment

Uh oh!

wbamberg Mar 29, 2025

Choose a reason for hiding this comment

Uh oh!

Josh-Cena Mar 29, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chrisdavidmills commented Feb 21, 2025 •

edited

Loading

github-actions bot commented Feb 21, 2025 •

edited

Loading

Elchi3 commented Feb 27, 2025 •

edited

Loading