Skip to content

feat: add comprehensive FileSystem observer API types with full MDN spec compliance #1171

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 3 commits into
base: master
Choose a base branch
from
Draft

feat: add comprehensive FileSystem observer API types with full MDN spec compliance #1171

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a07ffbc
Initial plan
Copilot Aug 22, 2025
7fc1c21
feat: add FileSystem observer API types
Copilot Aug 22, 2025
38e2f13
feat: update FileSystem observer API types with complete spec compliance
Copilot Aug 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions src/fsa/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,3 +126,32 @@ export type Data =
| DataView
| Blob
| string;

/**
* @see https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord
*/
export interface FileSystemChangeRecord {
Copy link
Owner

@streamich streamich Aug 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This interface is lacking types, see docs:

[Instance properties](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#instance_properties)
[changedHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#changedhandle)
A reference to the file system handle that the change was observed on.

For the user-observable file system, this can be a [FileSystemFileHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle) or a [FileSystemDirectoryHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle).
For the [Origin Private File System](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS), it can be a [FileSystemFileHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle), a [FileSystemDirectoryHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle), or a [FileSystemSyncAccessHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemSyncAccessHandle).
This property will be null for records with a "disappeared", "errored", or "unknown" type.

[relativePathComponents](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#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](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#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](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#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 [FileSystemFileHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle), [FileSystemDirectoryHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle), or [FileSystemSyncAccessHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemSyncAccessHandle).

[type](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#type)
A string representing the type of change that was observed. Possible values are:

[appeared](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#appeared)
The file or directory was created or moved into the root file structure.

[disappeared](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#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](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#errored)
An error state occurred 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 [FileSystemObserver.disconnect()](https://developer.mozilla.org/en-US/docs/Web/API/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](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#modified)
The file or directory was modified.

[moved](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#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](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord#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.

Copy link
Contributor Author

Copilot AI Aug 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added all missing properties from the MDN spec: relativePathMovedFrom, root, nullable changedHandle, and complete type values including "errored", "moved", and "unknown". Also added support for IFileSystemSyncAccessHandle for OPFS compatibility. Changes implemented in commit 38e2f13.

/** The changed file system handle. */
changedHandle: IFileSystemHandle;
/** Path components from the observed directory to the changed handle. */
relativePathComponents: string[];
/** The type of change that occurred. */
type: 'appeared' | 'disappeared' | 'modified';
}

export interface FileSystemObserverObserveOptions {
/** Whether to observe changes recursively in subdirectories. */
recursive?: boolean;
}

/**
* @see https://developer.mozilla.org/en-US/docs/Web/API/FileSystemObserver
*/
export interface FileSystemObserver {
Copy link
Owner

@streamich streamich Aug 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Prefix it with I

Suggested change
export interface FileSystemObserver {
export interface IFileSystemObserver {

The observer also needs its constructor to be typed:

js

Copy
const observer = new FileSystemObserver(callback);
The [callback function](https://developer.mozilla.org/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

Copy
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();
};

Copy link
Contributor Author

Copilot AI Aug 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated interface name to IFileSystemObserver and added constructor signature with callback function as specified in the MDN documentation. Changes implemented in commit 38e2f13.

/** Start observing changes to a directory handle. */
observe(handle: IFileSystemDirectoryHandle, options?: FileSystemObserverObserveOptions): Promise<void>;
/** Stop observing changes to a directory handle. */
unobserve(handle: IFileSystemDirectoryHandle): void;
/** Disconnect and stop all observations. */
disconnect(): void;
}