Editorial review: Document FileSystemObserver by chrisdavidmills · Pull Request #38270 · mdn/content

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.

…x.md Co-authored-by: Thomas Steiner <tomac@google.com>

Co-authored-by: Thomas Steiner <tomac@google.com>

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.

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

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

Co-authored-by: wbamberg <will@bootbonnet.ca>

…x.md Co-authored-by: wbamberg <will@bootbonnet.ca>

Co-authored-by: wbamberg <will@bootbonnet.ca>

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.

Co-authored-by: wbamberg <will@bootbonnet.ca>

wbamberg

👍 thank you Chris!

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

+
+{{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 <tomac@google.com> * Update files/en-us/web/api/filesystemobserver/index.md Co-authored-by: Thomas Steiner <tomac@google.com> * Update files/en-us/web/api/file_system_api/index.md Co-authored-by: Thomas Steiner <tomac@google.com> * Fixes for tomayac review comments * Update files/en-us/web/api/file_system_api/index.md Co-authored-by: wbamberg <will@bootbonnet.ca> * Update files/en-us/web/api/filesystemobserver/disconnect/index.md Co-authored-by: wbamberg <will@bootbonnet.ca> * Update files/en-us/web/api/filesystemobserver/filesystemobserver/index.md Co-authored-by: wbamberg <will@bootbonnet.ca> * Update files/en-us/web/api/filesystemobserver/filesystemobserver/index.md Co-authored-by: wbamberg <will@bootbonnet.ca> * Update files/en-us/web/api/filesystemobserver/index.md Co-authored-by: wbamberg <will@bootbonnet.ca> * Update files/en-us/web/api/filesystemobserver/observe/index.md Co-authored-by: wbamberg <will@bootbonnet.ca> * Update files/en-us/web/api/filesystemobserver/observe/index.md Co-authored-by: wbamberg <will@bootbonnet.ca> * Add FileSystemChangeRecord page, other fixes from wbamberg review * Update files/en-us/web/api/filesystemchangerecord/index.md Co-authored-by: wbamberg <will@bootbonnet.ca> * Update files/en-us/web/api/filesystemchangerecord/index.md Co-authored-by: wbamberg <will@bootbonnet.ca> * Update FileSystemChangeRecord description --------- Co-authored-by: Thomas Steiner <tomac@google.com> Co-authored-by: wbamberg <will@bootbonnet.ca>

Document FileSystemObserver

7b0838d

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

chrisdavidmills requested review from pepelsbey and sideshowbarker 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 <tomac@google.com>

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

affae34

Co-authored-by: Thomas Steiner <tomac@google.com>

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

914f0d5

Co-authored-by: Thomas Steiner <tomac@google.com>

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 <will@bootbonnet.ca>

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

f0db0b7

Co-authored-by: wbamberg <will@bootbonnet.ca>

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

a758cfa

…x.md Co-authored-by: wbamberg <will@bootbonnet.ca>

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

31283b6

…x.md Co-authored-by: wbamberg <will@bootbonnet.ca>

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

340ed65

Co-authored-by: wbamberg <will@bootbonnet.ca>

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

e29eb03

Co-authored-by: wbamberg <will@bootbonnet.ca>

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

695bb16

Co-authored-by: wbamberg <will@bootbonnet.ca>

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

Comment thread files/en-us/web/api/filesystemchangerecord/index.md Outdated

Comment thread files/en-us/web/api/filesystemchangerecord/index.md Outdated

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 <will@bootbonnet.ca>

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

e1b8683

Co-authored-by: wbamberg <will@bootbonnet.ca>

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

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

github-actions Bot locked as resolved and limited conversation to collaborators Apr 1, 2026

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

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

chrisdavidmills commented Feb 21, 2025 •

edited

Loading

github-actions Bot commented Feb 21, 2025 •

edited

Loading

Elchi3 commented Feb 27, 2025 •

edited

Loading