TheFileSystemChangeRecord dictionary of theFile System API contains details of a single change observed by aFileSystemObserver.

Therecords argument passed into theFileSystemObserver() constructor's callback function is an array ofFileSystemChangeRecord objects.

Instance properties

changedHandle

A reference to the file system handle that the change was observed on.

• For the user-observable file system, this can be aFileSystemFileHandle or aFileSystemDirectoryHandle.
• For theOrigin Private File System (OPFS), it can be aFileSystemFileHandle, aFileSystemDirectoryHandle, or aFileSystemSyncAccessHandle.

This property will benull for records with a"disappeared","errored", or"unknown" type.

relativePathComponents

An array containing the path components that make up the relative file path from theroot to thechangedHandle, including thechangedHandle filename.

relativePathMovedFrom

An array containing the path components that make up the relative file path from theroot to thechangedHandle's former location, in the case of observations with a"moved" type. If the type is not"moved", this property will benull.

root

A reference to the root file system handle, that is, the one passed to theobserve() call that started the observation. Again, this can be aFileSystemFileHandle,FileSystemDirectoryHandle, orFileSystemSyncAccessHandle.

type

A string representing the type of change that was observed. Possible values are:

appeared

The file or directory was created or moved into theroot file structure.

disappeared

The file or directory was deleted or moved out of theroot file structure. To find out which file or directory disappeared, you can query therelativePathComponents property.

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, theroot 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 usingFileSystemObserver.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

The file or directory was modified.

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

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.

Depending on the operating system, not all observations will be reported with the same level of detail, for example, when the contents of a directory change recursively. At best, the website will receive a detailed change record containing the type of change and a handle to the affected path. At worst, the website will receive a more generic change record (that is, an"unknown" type) that still requires it to enumerate the directory to figure out which handle changed.

This is still an improvement over polling, since the directory enumeration can be kicked off on-demand from the callback function, rather than needing to poll for changes periodically.

Examples

Initialize aFileSystemObserver

Before you can start observing file or directory changes, you need to initialize aFileSystemObserver to handle the observations. This is done using theFileSystemObserver() constructor, which takes a callback function as an argument:

const observer = new FileSystemObserver(callback);

Thecallback function body can be specified to return and process file change observations in any way you want. Each object inside therecords array is aFileSystemChangeRecord object:

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

Specifications

Not currently part of a specification. Seehttps://github.com/whatwg/fs/pull/165 for the relevant specification PR.

See also

• FileSystemObserver() constructor
• File System API
• The File System Observer API origin trial on developer.chrome.com (2024)