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 all 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
49 changes: 49 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,52 @@ export type Data =
| DataView
| Blob
| string;

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

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

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.
* This property will be null for records with a "disappeared", "errored", or "unknown" type.
*/
changedHandle: IFileSystemHandle | IFileSystemSyncAccessHandle | null;
/** Path components from the observed directory to the changed handle. */
relativePathComponents: string[];
/**
* 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.
*/
relativePathMovedFrom: string[] | null;
/**
* A reference to the root file system handle, that is, the one passed to the observe()
* call that started the observation.
*/
root: IFileSystemHandle | IFileSystemSyncAccessHandle;
/** The type of change that occurred. */
type: 'appeared' | 'disappeared' | 'modified' | 'moved' | 'errored' | 'unknown';
}

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 IFileSystemObserver {
/**
* Constructor for creating a FileSystemObserver.
* @param callback - Function called with file system change records and the observer instance
*/
new (callback: (records: FileSystemChangeRecord[], observer: IFileSystemObserver) => void): IFileSystemObserver;

/** 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;
}
Loading