File System ( PR #165 )

PR Preview — Last Updated 18 July

Participate:
GitHub whatwg/fs ( new issue , open issues )
Chat on Matrix
Commits:
GitHub whatwg/fs/commits
Go to the living standard
@whatfilesystem
Tests:
web-platform-tests fs/ ( ongoing work )
Translations (non-normative) :
日本語
This is a pull request preview of the standard

This document contains the contents of the standard as modified by pull request #165 , and should only be used as a preview.

Do not attempt to implement this version of the standard. Do not reference this version as authoritative in any way. Instead, see https://fs.spec.whatwg.org/ for the living standard.

Abstract

File System defines infrastructure for file systems as well as their API.

1. Introduction

This section is non-normative.

This document defines fundamental infrastructure for file system APIs. In addition, it defines an API that makes it possible for websites to get access to a file system directory without having to first prompt the user for access. This enables use cases where a website wants to save data to disk before a user has picked a location to save to, without forcing the website to use a completely different storage mechanism with a different API for such files. The entry point for this is the navigator.storage.getDirectory() method.

It also defines an API to listen to file system change events. Without it, sites can recursively poll the file system to find changes in the files or folder structure. This can be time consuming especially for large directories. The FileSystemObserver provides an API to listen for change events so that polling for them isn’t required.

2. Files and Directories

2.1. Concepts

2.1.1. File System

A file system maintains an implementation-defined mapping of file system path s to file system entries .

Each file system has an associated root , an opaque string whose value is implementation-defined .

A file system path is a list of one or more strings . This may be a virtual path that is mapped to real location on disk or in memory, may correspond directly to a path on the local file system, or may not correspond to any file on disk at all. The actual physical location of the corresponding file system entry is implementation-defined .

Let path be the list « " data ", " drafts ", " example.txt " ». There is no expectation that a file named example.txt exists anywhere on disk.

A file system path a is the same path as a file system path b if a ’s size is the same as b ’s size and for each index of a ’s indices a .\[[ index ]] is b .\[[ index ]].

Each file system has an associated locate an entry algorithm, which takes file system path path and runs an implementation-defined series of steps returning a file system entry or null. A non-null return value entry must adhere to these constraints:
Each file system has an associated get the path algorithm, which takes file system entry entry and runs an implementation-defined series of steps returning a file system path . The return value path must adhere to these constraints:

A file system event is a struct consisting of a type (a FileSystemChangeType ), an entry type (a FileSystemHandleKind or null), a modified path (a file system path ), and a from path (a file system path or null).

Note: A file system fires these events in response to file operations.

The from path must be set when type is " moved " and must be null otherwise.

Note: The entry type is null when the file system cannot determine the FileSystemHandleKind of the modified path due to the underlying file system entry no longer being there.

A file system has an associated set of file system observer registrations observer registrations which is initialized to the empty set.

When a user agent receives a list of file system events events for a file system fileSystem , the user agent MUST notify observer registrations of the fileSystem of events .

Note: The file system events fired by a file system might be unreliable and can be inaccurate, out of order, or missing.

To notify observer registrations of a file system fileSystem of a list of file system events events :

  1. Enqueue the following steps to the file system queue :

    1. For each observerRegistration of the fileSystem ’s observer registrations .

      1. Notify observerRegistration of events from fileSystem .

When a user agent receives an error event for a file system fileSystem and observerRegistrations (a subset of the fileSystem ’s observer registrations ), the user agent MUST send the error to observerRegistrations of fileSystem .

To send an error to a set of file system observer registrations observerRegistrations of a file system fileSystem :

  1. Enqueue the following steps to the file system queue :

    1. Assert observerRegistrations is a subset of fileSystem ’s observer registrations .

    2. For each observerRegistration of observerRegistrations :

      1. Destroy observerRegistration .

      2. Let observer be observerRegistration ’s observer .

      3. Let global be observer ’s relevant global object .

      4. Queue a storage task with global to run these steps:

        1. Let changedHandle be the observerRegistration ’s root handle .

        2. Let record be the result of creating a new FileSystemChangeRecord for observerRegistration given changedHandle , " errored ", and null.

        3. Invoke observer ’s callback with « record » as the first argument and observer as the second argument.

A file system observer registration consists of a FileSystemObserver observer , a FileSystemHandle root handle , and a boolean recursive .

To create an observer registration for FileSystemObserver observer on FileSystemHandle rootHandle with boolean recursive :

  1. Let observerRegistration be a file system observer registration whose observer is observer , root handle is rootHandle , and recursive is recursive .

  2. Let observerRegistrationLocator be rootHandle ’s locator .

  3. Let observerRegistrationMap be observer ’s observerRegistrations .

  4. Let fileSystem be the observerRegistrationLocator ’s file system .

  5. Append observerRegistration to the fileSystem ’s observer registrations .

  6. set observerRegistrationMap [ observerRegistrationLocator ] to observerRegistration .

Note: These steps have to be run on the file system queue .

To destroy file system observer registration observerRegistration :

  1. Let observer be observerRegistration ’s observer .

  2. Let rootHandle be observerRegistration ’s root handle .

  3. Let observerRegistrationLocator be rootHandle ’s locator .

  4. Let fileSystem be observerRegistrationLocator ’s file system .

  5. Remove observerRegistration from the fileSystem ’s observer registrations .

  6. Remove observerRegistrationLocator from observer ’s observerRegistrations .

Note: These steps have to be run on the file system queue .

To notify a file system observer registration observerRegistration of a list of file system events events from a file system fileSystem :

  1. Let rootHandle be observerRegistration ’s root handle .

  2. Let observerRegistrationLocator be rootHandle ’s locator .

  3. Assert : observerRegistrationLocator ’s file system is equal to fileSystem .

  4. Let observer be observerRegistration ’s observer .

  5. Let global be observer ’s relevant global object .

  6. Queue a storage task with global to run these steps:

    1. Let records be a list of FileSystemChangeRecord .

    2. For each event of events :

      1. Let eventType be event ’s type .

      2. Assert eventType is not equal to " errored ".

        Note: " errored " events are sent in the send an error steps.

      3. Let eventEntryType be event ’s entry type .

      4. If eventType is " modified " and eventEntryType is " directory " or null, continue .

        Note: We can safely ignore " modified " events for " directory ". These might be sent when one of its children receives an event which the page will be made aware of through that child event. Or they might be sent when some OS specific property changes which the web page cannot observe through web APIs. Similarly when we don’t know the FileSystemHandleKind , we can ignore it since the file system entry at the modified path no longer exists.

      5. If eventEntryType is null:

        1. Set eventEntryType to observerRegistrationLocator ’s kind .

        Note: When we don’t know the FileSystemHandleKind of the modified path , we have to arbitrarily choose one to construct the changedHandle . Setting it to observerRegistrationLocator ’s kind at least means it’ll be right for events on the root handle.

      6. Let modifiedPath be event ’s modified path .

      7. Let fromPath be event ’s from path .

      8. Let changedLocator be a file system locator whose kind is eventEntryType , file system is fileSystem , and path is modifiedPath .

      9. Let movedFromLocator be null.

      10. Let modifiedPathInScope be equal to changedLocator is in scope of observerRegistration .

      11. Let fromPathInScope be false.

      12. If eventType is " moved ":

        1. Assert : fromPath is not null.

        2. Set movedFromLocator be a file system locator whose kind is eventEntryType , file system is fileSystem , and path is fromPath .

        3. Set fromPathInScope equal to movedFromLocator is in scope of observerRegistration .

      13. If both modifiedPathInScope and fromPathInScope are false, continue .

      14. If eventType is " moved ":

        1. If modifiedPathInScope is false:

          1. Set eventType to " disappeared ".

          2. Set changedLocator to movedFromLocator .

          3. Set fromPath to null.

        2. If fromPathInScope is false:

          1. Set eventType to " appeared ".

          2. Set fromPath to null.

        Note: Some file systems convert " moved " events in and out of scope to " appeared " and " disappeared " respectively before we can. So to maintain consistency, we do it here.

      15. Let record be the result of creating a new FileSystemChangeRecord for observerRegistration given changedLocator , eventType , and fromPath .

      16. Append record to records .

      17. If eventType is equal to " disappeared " and changedHandle ’s locator is equal to observerRegistrationLocator :

        1. Set errorRecord to the result of creating a new FileSystemChangeRecord for observerRegistration given changedHandle , " errored ", and null.

        2. Append errorRecord to records .

        3. Destroy observerRegistration .

        4. break .

    3. If records is not empty :

      1. Invoke observer ’s callback with records as the first argument and observer as the second argument.

Note: These steps have to be run on the file system queue .

To determine if a file system locator handleLocator is in scope of a file system observer registration observerRegistration :

  1. Let observerRegistrationLocator be observerRegistration ’s root handle 's locator .

  2. Let observerRegistrationRecursive be observerRegistration ’s recursive .

  3. Let pathRelation be the result of getting the relationship between observerRegistrationLocator and handleLocator .

  4. If pathRelation is " other " or " ancestor ", return false.

  5. If pathRelation is " descendant " and observerRegistrationRecursive is false, return false.

  6. Return true.

Note: These steps have to be run on the file system queue .

2.1.2. File System Entry

A file system entry is either a file entry or a directory entry .

Each file system entry has an associated file system file system .

Each file system entry has an associated query access algorithm, which takes " read " or " readwrite " mode and returns a file system access result . Unless specified otherwise it returns a file system access result with a permission state of " denied " and with an error name of the empty string.

Each file system entry has an associated request access algorithm, which takes " read " or " readwrite " mode and returns a file system access result . Unless specified otherwise it returns a file system access result with a permission state of " denied " and with an error name of the empty string.

A file system access result is a struct encapsulating the result of querying or requesting access to the file system. It has the following items :

permission state

A PermissionState

error name

A string which must be the empty string if permission state is " granted "; otherwise an name listed in the DOMException names table . It is expected that in most cases when permission state is not " granted ", this should be " NotAllowedError ".

Dependent specifications may consider this API a powerful feature . However, unlike other powerful features whose permission request algorithm may throw, file system entry 's query access and request access algorithms must run in parallel on the file system queue and are therefore not allowed to throw. Instead, the caller is expected to queue a storage task to reject , as appropriate, should these algorithms return an error name other than the empty string.

Note: Implementations that only implement this specification and not dependent specifications do not need to bother implementing file system entry 's query access and request access .

Make access check algorithms associated with a FileSystemHandle.

Each file system entry has an associated name (a string ).

A valid file name is a string that is not an empty string, is not equal to "." or "..", and does not contain '/' or any other character used as path separator on the underlying platform.

Note: This means that '\' is not allowed in names on Windows, but might be allowed on other operating systems. Additionally underlying file systems might have further restrictions on what names are or aren’t allowed, so a string merely being a valid file name is not a guarantee that creating a file or directory with that name will succeed.

We should consider having further normative restrictions on file names that will never be allowed using this API, rather than leaving it entirely up to underlying file systems.

A file entry additionally consists of binary data (a byte sequence ), a modification timestamp (a number representing the number of milliseconds since the Unix Epoch ), a lock (a string that may exclusively be " open ", " taken-exclusive " or " taken-shared ") and a shared lock count (a number representing the number shared locks that are taken at a given point in time).

A user agent has an associated file system queue which is the result of starting a new parallel queue . This queue is to be used for all file system operations.

To take a lock with a value of " exclusive " or " shared " on a given file entry file :

  1. Let lock be the file ’s lock .

  2. Let count be the file ’s shared lock count .

  3. If value is " exclusive ":

    1. If lock is " open ":

      1. Set lock to " taken-exclusive ".

      2. Return " success ".

  4. If value is " shared ":

    1. If lock is " open ":

      1. Set lock to " taken-shared ".

      2. Set count to 1.

      3. Return " success ".

    2. Otherwise, if lock is " taken-shared ":

      1. Increase count by 1.

      2. Return " success ".

  5. Return " failure ".

Note: These steps have to be run on the file system queue .

To release a lock on a given file entry file :

  1. Let lock be the file ’s associated lock .

  2. Let count be the file ’s shared lock count .

  3. If lock is " taken-shared ":

    1. Decrease count by 1.

    2. If count is 0, set lock to " open ".

  4. Otherwise, set lock to " open ".

Note: These steps have to be run on the file system queue .

Note: Locks help prevent concurrent modifications to a file. A FileSystemWritableFileStream requires a shared lock, while a FileSystemSyncAccessHandle requires an exclusive one.

A directory entry additionally consists of a set of children , which are themselves file system entries . Each member is either a file entry or a directory entry .

A file system entry entry should be contained in the children of at most one directory entry , and that directory entry is also known as entry ’s parent . A file system entry 's parent is null if no such directory entry exists.

Note: Two different file system entries can represent the same file or directory on disk, in which case it is possible for both entries to have a different parent, or for one entry to have a parent while the other entry does not have a parent.

File system entries can (but don’t have to) be backed by files on the host operating system’s local file system, so it is possible for the binary data , modification timestamp , and children of entries to be modified by applications outside of this specification. Exactly how external changes are reflected in the data structures defined by this specification, as well as how changes made to the data structures defined here are reflected externally is left up to individual user-agent implementations.

A file system entry a is the same entry as a file system entry b if a is equal to b , or if a and b are backed by the same file or directory on the local file system.

To resolve a file system locator child relative to a directory locator root : Let result be a new promise .

Enqueue the following steps to the file system queue : If child ’s locator 's root is not root ’s locator 's root , resolve result with null, and abort these steps. Let childPath be child ’s locator 's path . Let rootPath be root ’s locator 's path . If childPath is the same path as rootPath , resolve result with « », and abort these steps. If rootPath ’s size is greater than childPath ’s size , resolve result with null, and abort these steps. 2.1.3. For each index of rootPath ’s indices : If rootPath .\[[ index ]] is not childPath .\[[ index ]], then resolve result with null, and abort these steps. Let relativePath be « ». File System Locator For each index of the range from rootPath ’s size to rootPath ’s size , exclusive, append childPath .\[[ index ]] to relativePath . Resolve result with relativePath . Return result .

A file system locator represents a potential location of a file system entry . A file system locator is either a file locator or a directory locator .

Each file system locator has an associated path (a file system path ), a kind (a FileSystemHandleKind ), and a root file system (a file system root ).

Consider giving each locator a storage bucket .

A file locator is a file system locator whose kind is " file ". A directory locator is a file system locator whose kind is " directory ".

A file system root is an opaque string whose value is implementation-defined .

For a file system locator locator whichs locates to a file entry entry that conceptually exists at the path data/drafts/example.txt relative to the root directory of a bucket file system , locator ’s kind has to be " file ", locator ’s path has to be « " data ", " drafts ", " example.txt " », and locator ’s root file system might include relevant identifying information such as the storage has to be a bucket and the disk drive. file system .

A file system locator a is the same locator as a file system locator b if a ’s kind is b ’s kind , a ’s root file system is b ’s root file system , and a ’s path is the same path as b ’s path .

The locate an entry

To resolve algorithm given a file system locator locator child runs an implementation-defined relative to a file system locator series root :

  1. Let relationship be the result of steps adhering to these constraints: getting the relationship between root and child .

  2. If locator relationship is a file locator , they return a file entry equal to " other " or " ancestor ", return null.

  3. If locator relationship is a directory locator , they equal to " self ", return a directory entry or null. « ».

  4. If these steps return a non-null Let entry , then: childPath be child ’s path .

  5. Getting the locator with Let entry rootPath returns be locator , provided no intermediate file system operations were run. root ’s path .

  6. Let entry relativePath ’s name be « ».

  7. For each is index of the last item range of from locator rootPath ’s path size to childPath ’s size , exclusive, append childPath [ index ] to relativePath .

  8. Return relativePath .

Note: These steps have to be run on the file system queue .

The
To get the locator relationship algorithm given from a file system entry locator entry self runs an implementation-defined series of steps adhering to these constraints: a file system locator related :

  1. If entry self ’s file system is a not related ’s file entry system , they return a file locator . " other ".

  2. If Let entry selfPath is a directory entry , they return a directory locator be self ’s path .

  3. If these steps return Let locator , then: relatedPath be related ’s path .

  4. Locating an entry with Let locator selfPathSize returns be entry , provided no intermediate file system operations were run. selfPath ’s size .

  5. Let entry relatedPathSize ’s name is the last item of be locator relatedPath ’s path size .

  6. A file system path is a list For each index of one or more strings . This may be a virtual path that selfPath ’s indices :

    1. If index is mapped to real location on disk or in memory, may correspond directly to a path on the local file system, greater than or may not correspond equal to any file on disk at all. The actual physical location of the corresponding file system entry is implementation-defined . relatedPathSize , return " ancestor ".

      Let

    2. If path selfPath be the list « [ index ] is not relatedPath [ index ], return " data other ", ".

  7. If selfPathSize equals relatedPathSize , return " drafts self ", ".

  8. If selfPathSize + 1 equals relatedPathSize , return " example.txt direct child ".

  9. Return " ». There is no expectation that a file named example.txt descendant exists anywhere ".

Note: These steps have to be run on disk. the file system queue .

The locate an entry algorithm given a file system locator locator runs the following steps:

  1. A Let fileSystem be locator ’s file system .

  2. Let path be locator ’s path .

  3. Let entry be the result of running fileSystem ’s locate an entry given a path .

  4. If entry is null, return null.

  5. Return entry .

The get the same path as locator algorithm given a file system path entry b entry if runs the following steps:

  1. Let a fileSystem be entry ’s size is file system .

  2. Let path be the same as result of running b fileSystem ’s size get the path and for each given entry .

  3. Let locator be a file system locator whose path is index path of and whose file system is fileSystem .

  4. If entry is a file entry , set locator ’s indices kind to "file".

  5. If a .\[[ index entry ]] is a directory entry , set b .\[[ index locator ]]. ’s kind to "directory".

  6. Return entry .

The contents of a file system locator , including its path , are not expected to be shared in their entirety with the website process. The file system path might contain components which are not known to the website unless the file system locator is later resolved relative to a parent directory locator .

2.2. The FileSystemHandle interface 

enum FileSystemHandleKind {
  "file",
  "directory",
};
[Exposed=(Window,Worker), SecureContext, Serializable]
interface FileSystemHandle {
  ;

  readonly attribute FileSystemHandleKind kind;
  readonly attribute USVString name;
  );

  Promise<boolean> isSameEntry(FileSystemHandle other);
};

A FileSystemHandle object is associated with a locator (a file system locator ).

Note: Multiple FileSystemHandle objects can have the same file system locator .

To create a new FileSystemHandle given a file system locator locator in a Realm realm :

  1. Let kind be locator ’s kind .

  2. Let fileSystem be locator ’s file system .

  3. Let path be locator ’s path .

  4. If kind is " file ":

    1. Return the result of creating a new FileSystemFileHandle given fileSystem and path in realm .

  5. Otherwise:

    1. Return the result of creating a new FileSystemDirectoryHandle given fileSystem and path in realm .

A FileSystemHandle is in a bucket file system if the first item of its locator 's path is the empty string.

Note: This is a bit magical, but it works since only the root directory of a bucket file system can have a path which contains an empty string. See getDirectory() . All other item s of a path will be a valid file name .

Consider improving this situation by giving each locator a storage bucket .

FileSystemHandle objects are serializable objects .

Their serialization steps , given value , serialized and forStorage are:

  1. Set serialized .[[Origin]] to value ’s relevant settings object 's origin .

  2. Set serialized .[[Locator]] to value ’s locator .

Their deserialization steps , given serialized and value are:

  1. If serialized .[[Origin]] is not same origin with value ’s relevant settings object 's origin , then throw a " DataCloneError " DOMException .

  2. Set value ’s locator to serialized .[[Locator]].

handle . kind

Returns " file " if handle is a FileSystemFileHandle , or " directory " if handle is a FileSystemDirectoryHandle .

This can be used to distinguish files from directories when iterating over the contents of a directory.

handle . name

Returns the last path component of handle ’s locator 's path .

The kind getter steps are to return this 's locator 's kind .

The name getter steps are to return the last item (a string ) of this 's locator 's path .

2.2.1. The isSameEntry() method

same = await handle1 . isSameEntry ( handle2 )

Returns true if handle1 and handle2 represent the same file or directory.

The isSameEntry( other ) method steps are:

  1. Let realm be this 's relevant Realm .

  2. Let p be a new promise in realm .

  3. Enqueue the following steps to the file system queue :

    1. If this 's locator is the same locator as other ’s locator , resolve p with true.

    2. Otherwise resolve p with false.

  4. Return p .

2.3. The FileSystemFileHandle interface 

dictionary FileSystemCreateWritableOptions {
  boolean keepExistingData = false;
};
[Exposed=(Window,Worker), SecureContext, Serializable]
 {

interface FileSystemFileHandle : FileSystemHandle {
  Promise<File> getFile();
  Promise<FileSystemWritableFileStream> createWritable(optional FileSystemCreateWritableOptions options = {});
  [Exposed=DedicatedWorker]
  Promise<FileSystemSyncAccessHandle> createSyncAccessHandle();
};

Note: A FileSystemFileHandle 's associated locator 's kind is " file ".

To create a child FileSystemFileHandle given a directory locator parentLocator and a string name in a Realm realm :

  1. Let handle be a new FileSystemFileHandle in realm .

  2. Let childType be " file ".

  3. Let childRoot childFileSystem be a copy of the parentLocator ’s root file system .

  4. Let childPath be the result of cloning parentLocator ’s path and appending name .

  5. Set handle ’s locator to a file system locator whose kind is childType , root file system is childRoot childFileSystem , and path is childPath .

  6. Return handle .

To create a new FileSystemFileHandle given a file system root root fileSystem and a file system path path in a Realm realm :

  1. Let handle be a new FileSystemFileHandle in realm .

  2. Set handle ’s locator to a file system locator whose kind is " file ", root file system is root fileSystem , and path is path .

  3. Return handle .

FileSystemFileHandle objects are serializable objects . Their serialization steps and deserialization steps are the same as those for FileSystemHandle .

2.3.1. The getFile() method

file = await fileHandle . getFile()

Returns a File representing the state on disk of the file entry locatable by handle ’s locator . If the file on disk changes or is removed after this method is called, the returned File object will likely be no longer readable.

The getFile() method steps are:

  1. Let result be a new promise .

  2. Let locator be this 's locator .

  3. Let global be this 's relevant global object .

  4. Enqueue the following steps to the file system queue :

    1. Let entry be the result of locating an entry given locator .

    2. Let accessResult be the result of running entry ’s query access given " read ".

    3. Queue a storage task with global to run these steps:

      1. If accessResult ’s permission state is not " granted ", reject result with a DOMException of accessResult ’s error name and abort these steps.

      2. If entry is null, reject result with a " NotFoundError " DOMException and abort these steps.

      3. Assert : entry is a file entry .

      4. Let f be a new File .

      5. Set f ’s snapshot state to the current state of entry .

      6. Set f ’s underlying byte sequence to a copy of entry ’s binary data .

      7. Set f ’s name to entry ’s name .

      8. Set f ’s lastModified to entry ’s modification timestamp .

      9. Set f ’s type to an implementation-defined value, based on for example entry ’s name or its file extension.

        The reading and snapshotting behavior needs to be better specified in the [FILE-API] spec, for now this is kind of hand-wavy.

      10. Resolve result with f .

  5. Return result .

2.3.2. The createWritable() method

stream = await fileHandle . createWritable()
stream = await fileHandle . createWritable ({ keepExistingData : true/false })

Returns a FileSystemWritableFileStream that can be used to write to the file. Any changes made through stream won’t be reflected in the file entry locatable by fileHandle ’s locator until the stream has been closed. User agents try to ensure that no partial writes happen, i.e. the file will either contain its old contents or it will contain whatever data was written through stream up until the stream has been closed.

This is typically implemented by writing data to a temporary file, and only replacing the file entry locatable by fileHandle ’s locator with the temporary file when the writable filestream is closed.

If keepExistingData is false or not specified, the temporary file starts out empty, otherwise the existing file is first copied to this temporary file.

Creating a FileSystemWritableFileStream takes a shared lock on the file entry locatable with fileHandle ’s locator . This prevents the creation of FileSystemSyncAccessHandles for the entry, until the stream is closed.

See WICG/file-system-access issue #67 for discussion around and desire for a "inPlace" mode for createWritable (where changes will be written to the actual underlying file as they are written to the writer, for example to support in-place modification of large files or things like databases). This is not currently implemented in Chrome. Implementing this is currently blocked on figuring out how to combine the desire to run malware checks with the desire to let websites make fast in-place modifications to existing large files. In-place writes are available for files in a bucket file system via the FileSystemSyncAccessHandle interface.

The createWritable( options ) method steps are:

  1. Let result be a new promise .

  2. Let locator be this 's locator .

  3. Let realm be this 's relevant Realm .

  4. Let global be this 's relevant global object .

  5. Enqueue the following steps to the file system queue :

    1. Let entry be the result of locating an entry given locator .

    2. Let accessResult be the result of running entry ’s request access given " readwrite ".

    3. If accessResult ’s permission state is not " granted ", queue a storage task with global to reject result with a DOMException of accessResult ’s error name and abort these steps.

    4. If entry is null , queue a storage task with global to reject result with a " NotFoundError " DOMException and abort these steps.

    5. Assert : entry is a file entry .

    6. Let lockResult be the result of taking a lock with " shared " on entry .

    7. Queue a storage task with global to run these steps:

      1. If lockResult is " failure ", reject result with a " NoModificationAllowedError " DOMException and abort these steps.

      2. Let stream be the result of creating a new FileSystemWritableFileStream for entry in realm .

      3. If options [" keepExistingData "] is true:

        1. Set stream ’s [[buffer]] to a copy of entry ’s binary data .

      4. Resolve result with stream .

  6. Return result .

2.3.3. The createSyncAccessHandle() method

handle = await fileHandle . createSyncAccessHandle ()

Returns a FileSystemSyncAccessHandle that can be used to read from/write to the file. Changes made through handle might be immediately reflected in the file entry locatable by fileHandle ’s locator . To ensure the changes are reflected in this file, the handle can be flushed.

Creating a FileSystemSyncAccessHandle takes an exclusive lock on the file entry locatable with fileHandle ’s locator . This prevents the creation of further FileSystemSyncAccessHandles or FileSystemWritableFileStreams for the entry, until the access handle is closed.

The returned FileSystemSyncAccessHandle offers synchronous methods. This allows for higher performance on contexts where asynchronous operations come with high overhead, e.g., WebAssembly.

For the time being, this method will only succeed when the fileHandle is in a bucket file system .

The createSyncAccessHandle() method steps are:

  1. Let result be a new promise .

  2. Let locator be this 's locator .

  3. Let realm be this 's relevant Realm .

  4. Let global be this 's relevant global object .

  5. Let isInABucketFileSystem be true if this is in a bucket file system ; otherwise false.

  6. Enqueue the following steps to the file system queue :

    1. Let entry be the result of locating an entry given locator .

    2. Let accessResult be the result of running entry ’s request access given " readwrite ".

    3. If accessResult ’s permission state is not " granted ", queue a storage task with global to reject result with a DOMException of accessResult ’s error name and abort these steps.

    4. If isInABucketFileSystem is false, queue a storage task with global to reject result with an " InvalidStateError " DOMException and abort these steps.

    5. If entry is null , queue a storage task with global to reject result with a " NotFoundError " DOMException and abort these steps.

    6. Assert : entry is a file entry .

    7. Let lockResult be the result of taking a lock with " exclusive " on entry .

    8. Queue a storage task with global to run these steps:

      1. If lockResult is " failure ", reject result with a " NoModificationAllowedError " DOMException and abort these steps.

      2. Let handle be the result of creating a new FileSystemSyncAccessHandle for entry in realm .

      3. Resolve result with handle .

  7. Return result .

2.4. The FileSystemDirectoryHandle interface 

dictionary FileSystemGetFileOptions {
  boolean create = false;
};
dictionary FileSystemGetDirectoryOptions {
  boolean create = false;
};
dictionary FileSystemRemoveOptions {
  boolean recursive = false;
};
[Exposed=(Window,Worker), SecureContext, Serializable]
 {
  >;

interface FileSystemDirectoryHandle : FileSystemHandle {
  async iterable<USVString, FileSystemHandle>;
  Promise<FileSystemFileHandle> getFileHandle(USVString name, optional FileSystemGetFileOptions options = {});
  Promise<FileSystemDirectoryHandle> getDirectoryHandle(USVString name, optional FileSystemGetDirectoryOptions options = {});
  Promise<undefined> removeEntry(USVString name, optional FileSystemRemoveOptions options = {});
  );

  Promise<sequence<USVString>?> resolve(FileSystemHandle possibleDescendant);
};

Note: A FileSystemDirectoryHandle 's associated locator 's kind is " directory ".

To create a child FileSystemDirectoryHandle given a directory locator parentLocator and a string name in a Realm realm :

  1. Let handle be a new FileSystemDirectoryHandle in realm .

  2. Let childType be " directory ".

  3. Let childRoot childFileSystem be a copy of the parentLocator ’s root file system .

  4. Let childPath be the result of cloning parentLocator ’s path and appending name .

  5. Set handle ’s locator to a file system locator whose kind is childType , root file system is childRoot childFileSystem , and path is childPath .

  6. Return handle .

To create a new FileSystemDirectoryHandle given a file system root root fileSystem and a file system path path in a Realm realm :

  1. Let handle be a new FileSystemDirectoryHandle in realm .

  2. Set handle ’s locator to a file system locator whose kind is " directory ", root file system is root fileSystem , and path is path .

  3. Return handle .

FileSystemDirectoryHandle objects are serializable objects . Their serialization steps and deserialization steps are the same as those for FileSystemHandle .

2.4.1. Directory iteration

for await (let [ name , handle ] of directoryHandle ) {}
for await (let [ name , handle ] of directoryHandle . entries()) {}
for await (let handle of directoryHandle . values()) {}
for await (let name of directoryHandle . keys()) {}

Iterates over all entries whose parent is the directory entry locatable by directoryHandle ’s locator . Entries that are created or deleted while the iteration is in progress might or might not be included. No guarantees are given either way.

In the future we might want to add arguments to the async iterable declaration to support for example recursive iteration.

The asynchronous iterator initialization steps for a FileSystemDirectoryHandle handle and its async iterator iterator are:

  1. Set iterator ’s past results to an empty set .

To get the next iteration result for a FileSystemDirectoryHandle handle and its async iterator iterator :

  1. Let promise be a new promise .

  2. Enqueue the following steps to the file system queue :

    1. Let directory be the result of locating an entry given handle ’s locator .

    2. Let accessResult be the result of running directory ’s query access given " read ".

    3. Queue a storage task with handle ’s relevant global object to run these steps:

      1. If accessResult ’s permission state is not " granted ", reject promise with a DOMException of accessResult ’s error name and abort these steps.:

      2. If directory is null , reject result with a " NotFoundError " DOMException and abort these steps.

        1. Assert : directory is a directory entry .

      3. Let child be a file system entry in directory ’s children , such that child ’s name is not contained in iterator ’s past results , or null if no such entry exists.

        Note: This is intentionally very vague about the iteration order. Different platforms and file systems provide different guarantees about iteration order, and we want it to be possible to efficiently implement this on all platforms. As such no guarantees are given about the exact order in which elements are returned.

      4. If child is null , resolve promise with undefined and abort these steps.

      5. Append child ’s name to iterator ’s past results .

      6. If child is a file entry :

        1. Let result be the result of creating a child FileSystemFileHandle with handle ’s locator and child ’s name in handle ’s relevant Realm .

      7. Otherwise:

        1. Let result be the result of creating a child FileSystemDirectoryHandle with handle ’s locator and child ’s name in handle ’s relevant Realm .

      8. Resolve promise with ( child ’s name , result ).

  3. Return promise .

2.4.2. The getFileHandle() method

fileHandle = await directoryHandle . getFileHandle ( name )
fileHandle = await directoryHandle . getFileHandle ( name , { create : false })

Returns a handle for a file named name in the directory entry locatable by directoryHandle ’s locator . If no such file exists, this rejects.

fileHandle = await directoryHandle . getFileHandle ( name , { create : true })

Returns a handle for a file named name in the directory entry locatable by directoryHandle ’s locator . If no such file exists, this creates a new file. If no file with named name can be created this rejects. Creation can fail because there already is a directory with the same name, because the name uses characters that aren’t supported in file names on the underlying file system, or because the user agent for security reasons decided not to allow creation of the file.

This operation requires write permission, even if the file being returned already exists. If this handle doesn’t already have write permission, this could result in a prompt being shown to the user. To get an existing file without needing write permission, call this method with { create : false } .

The getFileHandle( name , options ) method steps are:

  1. Let result be a new promise .

  2. Let realm be this 's relevant Realm .

  3. Let locator be this 's locator .

  4. Let global be this 's relevant global object .

  5. Enqueue the following steps to the file system queue :

    1. If name is not a valid file name , queue a storage task with global to reject result with a TypeError and abort these steps.

    2. Let entry be the result of locating an entry given locator .

    3. If options [" create "] is true:

      1. Let accessResult be the result of running entry ’s request access given " readwrite ".

    4. Otherwise:

      1. Let accessResult be the result of running entry ’s query access given " read ".

    5. Queue a storage task with global to run these steps:

      1. If accessResult ’s permission state is not " granted ", reject result with a DOMException of accessResult ’s error name and abort these steps.

      2. If entry is null , reject result with a " NotFoundError " DOMException and abort these steps.

      3. Assert : entry is a directory entry .

      4. For each child of entry ’s children :

        1. If child ’s name equals name :

          1. If child is a directory entry :

            1. Reject result with a " TypeMismatchError " DOMException and abort these steps.

          2. Resolve result with the result of creating a child FileSystemFileHandle with locator and child ’s name in realm and abort these steps.

      5. If options [" create "] is false:

        1. Reject result with a " NotFoundError " DOMException and abort these steps.

      6. Let child be a new file entry whose query access and request access algorithms are those of entry .

      7. Set child ’s name to name .

      8. Set child ’s binary data to an empty byte sequence .

      9. Set child ’s modification timestamp to the current time.

      10. Append child to entry ’s children .

      11. If creating child in the underlying file system throws an exception, reject result with that exception and abort these steps.

        Better specify what possible exceptions this could throw.

      12. Resolve result with the result of creating a child FileSystemFileHandle with locator and child ’s name in realm .

  6. Return result .

2.4.3. The getDirectoryHandle() method

subdirHandle = await directoryHandle . getDirectoryHandle ( name )
subdirHandle = await directoryHandle . getDirectoryHandle ( name , { create : false })

Returns a handle for a directory named name in the directory entry locatable by directoryHandle ’s locator . If no such directory exists, this rejects.

subdirHandle = await directoryHandle . getDirectoryHandle ( name , { create : true })

Returns a handle for a directory named name in the directory entry locatable by directoryHandle ’s locator . If no such directory exists, this creates a new directory. If creating the directory failed, this rejects. Creation can fail because there already is a file with the same name, or because the name uses characters that aren’t supported in file names on the underlying file system.

This operation requires write permission, even if the directory being returned already exists. If this handle doesn’t already have write permission, this could result in a prompt being shown to the user. To get an existing directory without needing write permission, call this method with { create : false } .

The getDirectoryHandle( name , options ) method steps are:

  1. Let result be a new promise .

  2. Let realm be this 's relevant Realm .

  3. Let locator be this 's locator .

  4. Let global be this 's relevant global object .

  5. Enqueue the following steps to the file system queue :

    1. If name is not a valid file name , queue a storage task with global to reject result with a TypeError and abort these steps.

    2. Let entry be the result of locating an entry given locator .

    3. If options [" create "] is true:

      1. Let accessResult be the result of running entry ’s request access given " readwrite ".

    4. Otherwise:

      1. Let accessResult be the result of running entry ’s query access given " read ".

    5. Queue a storage task with global to run these steps:

      1. If accessResult ’s permission state is not " granted ", reject result with a DOMException of accessResult ’s error name and abort these steps.

      2. If entry is null , reject result with a " NotFoundError " DOMException and abort these steps.

      3. Assert : entry is a directory entry .

      4. For each child of entry ’s children :

        1. If child ’s name equals name :

          1. If child is a file entry :

            1. Reject result with a " TypeMismatchError " DOMException and abort these steps.

          2. Resolve result with the result of creating a child FileSystemDirectoryHandle with locator and child ’s name in realm and abort these steps.

      5. If options [" create "] is false:

        1. Reject result with a " NotFoundError " DOMException and abort these steps.

      6. Let child be a new directory entry whose query access and request access algorithms are those of entry .

      7. Set child ’s name to name .

      8. Set child ’s children to an empty set .

      9. Append child to entry ’s children .

      10. If creating child in the underlying file system throws an exception, reject result with that exception and abort these steps.

        Better specify what possible exceptions this could throw.

      11. Resolve result with the result of creating a child FileSystemDirectoryHandle with locator and child ’s name in realm .

  6. Return result .

2.4.4. The removeEntry() method

await directoryHandle . removeEntry ( name )
await directoryHandle . removeEntry ( name , { recursive : false })

If the directory entry locatable by directoryHandle ’s locator contains a file named name , or an empty directory named name , this will attempt to delete that file or directory.

Attempting to delete a file or directory that does not exist is considered success, while attempting to delete a non-empty directory will result in a promise rejection.

await directoryHandle . removeEntry ( name , { recursive : true })

Removes the file system entry named name in the directory entry locatable by directoryHandle ’s locator . If that entry is a directory, its contents will also be deleted recursively.

Attempting to delete a file or directory that does not exist is considered success.

The removeEntry( name , options ) method steps are:

  1. Let result be a new promise .

  2. Let locator be this 's locator .

  3. Let global be this 's relevant global object .

  4. Enqueue the following steps to the file system queue :

    1. If name is not a valid file name , queue a storage task with global to reject result with a TypeError and abort these steps.

    2. Let entry be the result of locating an entry given locator .

    3. Let accessResult be the result of running entry ’s request access given " readwrite ".

    4. Queue a storage task with global to run these steps:

      1. If accessResult ’s permission state is not " granted ", reject result with a DOMException of accessResult ’s error name and abort these steps.

      2. If entry is null , reject result with a " NotFoundError " DOMException and abort these steps.

      3. Assert : entry is a directory entry .

      4. For each child of entry ’s children :

        1. If child ’s name equals name :

          1. If child is a directory entry :

            1. If child ’s children is not empty and options [" recursive "] is false:

              1. Reject result with an " InvalidModificationError " DOMException and abort these steps.

          2. Remove child from entry ’s children .

          3. If removing child in the underlying file system throws an exception, reject result with that exception and abort these steps.

            Note: If recursive is true, the removal can fail non-atomically. Some files or directories might have been removed while other files or directories still exist.

            Better specify what possible exceptions this could throw.

          4. Resolve result with undefined .

      5. Reject result with a " NotFoundError " DOMException .

  5. Return result .

2.4.5. The resolve() method

path = await directory . resolve ( child )

If child is equal to directory , path will be an empty array.

If child is a direct child of directory , path will be an array containing child ’s name.

If child is a descendant of directory , path will be an array containing the names of all the intermediate directories and child ’s name as last element. For example if directory represents /home/user/project and child represents /home/user/project/foo/bar , this will return ['foo', 'bar'] .

Otherwise ( directory and child are not related), path will be null. 

// Assume we at some point got a valid directory handle.
const dir_ref = current_project_dir;
if (!dir_ref) return;
// Now get a file reference:
const file_ref = await dir_ref.getFileHandle(filename, { create: true });
// Check if file_ref exists inside dir_ref:
const relative_path = await dir_ref.resolve(file_ref);
if (relative_path === null) {
    // Not inside dir_ref.
} else {
    // relative_path is an array of names, giving the relative path
    // from dir_ref to the file that is represented by file_ref:
    assert relative_path.pop() === file_ref.name;
    let entry = dir_ref;
    for (const name of relative_path) {
        entry = await entry.getDirectory(name);
    }
    entry = await entry.getFile(file_ref.name);
    // Now |entry| will represent the same file on disk as |file_ref|.
    assert await entry.isSameEntry(file_ref) === true;
}
The resolve( possibleDescendant ) method steps are are:

  1. Let result be a new promise .

  2. Let global be this 's relevant global object .

  3. Enqueue the following steps to return the file system queue :

    1. Let relativePath be the result of resolving possibleDescendant ’s locator relative to this 's locator .

    2. Queue a storage task with global to run these steps:

      1. resolve result with relativePath .

  4. Return result .

2.5. The FileSystemWritableFileStream interface 

enum WriteCommandType {
  "write",
  "seek",
  "truncate",
};
dictionary WriteParams {
  required WriteCommandType type;
  unsigned long long? size;
  unsigned long long? position;
  (BufferSource or Blob or USVString)? data;
};
typedef (BufferSource or Blob or USVString or WriteParams) FileSystemWriteChunkType;
[Exposed=(Window,Worker), SecureContext]
interface FileSystemWritableFileStream : WritableStream {
  Promise<undefined> write(FileSystemWriteChunkType data);
  Promise<undefined> seek(unsigned long long position);
  Promise<undefined> truncate(unsigned long long size);
};

A FileSystemWritableFileStream has an associated [[file]] (a file entry ).

A FileSystemWritableFileStream has an associated [[buffer]] (a byte sequence ). It is initially empty.

Note: This buffer can get arbitrarily large, so it is expected that implementations will not keep this in memory, but instead use a temporary file for this. All access to [[buffer]] is done in promise returning methods and algorithms, so even though operations on it seem sync, implementations can implement them async.

A FileSystemWritableFileStream has an associated [[seekOffset]] (a number). It is initially 0.

A FileSystemWritableFileStream object is a WritableStream object with additional convenience methods, which operates on a single file on disk.

Upon creation, an underlying sink will have been created and the stream will be usable. All operations executed on the stream are queuable and producers will be able to respond to backpressure.

The underlying sink’s write method, and therefore WritableStreamDefaultWriter’s write() method, will accept byte-like data or WriteParams as input.

The FileSystemWritableFileStream has a file position cursor initialized at byte offset 0 from the top of the file. When using write() or by using WritableStream capabilities through the WritableStreamDefaultWriter’s write() method, this position will be advanced based on the number of bytes written through the stream object.

Similarly, when piping a ReadableStream into a FileSystemWritableFileStream object, this position is updated with the number of bytes that passed through the stream.

getWriter() returns an instance of WritableStreamDefaultWriter .

To create a new FileSystemWritableFileStream given a file entry file in a Realm realm :

  1. Let stream be a new FileSystemWritableFileStream in realm .

  2. Set stream ’s [[file]] to file .

  3. Let writeAlgorithm be an algorithm which takes a chunk argument and returns the result of running the write a chunk algorithm with stream and chunk .

  4. Let closeAlgorithm be these steps:

    1. Let closeResult be a new promise .

    2. Enqueue the following steps to the file system queue :

      1. Let accessResult be the result of running file ’s query access given " readwrite ".

      2. Queue a storage task with file ’s relevant global object to run these steps:

        1. If accessResult ’s permission state is not " granted ", reject closeResult with a DOMException of accessResult ’s error name and abort these steps.

        2. Run implementation-defined malware scans and safe browsing checks. If these checks fail, reject closeResult with an " AbortError " DOMException and abort these steps.

        3. Set stream ’s [[file]] 's binary data to stream ’s [[buffer]] . If that throws an exception, reject closeResult with that exception and abort these steps.

          Note: It is expected that this atomically updates the contents of the file on disk being written to.

        4. Enqueue the following steps to the file system queue :

          1. Release the lock on stream ’s [[file]] .

          2. Queue a storage task with file ’s relevant global object to resolve closeResult with undefined .

    3. Return closeResult .

  5. Let abortAlgorithm be these steps:

    1. Enqueue this step to the file system queue :

      1. Release the lock on stream ’s [[file]] .

  6. Let highWaterMark be 1.

  7. Let sizeAlgorithm be an algorithm that returns 1 .

  8. Set up stream with writeAlgorithm set to writeAlgorithm , closeAlgorithm set to closeAlgorithm , abortAlgorithm set to abortAlgorithm , highWaterMark set to highWaterMark , and sizeAlgorithm set to sizeAlgorithm .

  9. Return stream .

The write a chunk algorithm, given a FileSystemWritableFileStream stream and chunk , runs these steps:

  1. Let input be the result of converting chunk to a FileSystemWriteChunkType . If this throws an exception, then return a promise rejected with that exception.

  2. Let p be a new promise .

  3. Enqueue the following steps to the file system queue :

    1. Let accessResult be the result of running stream ’s [[file]] 's query access given " readwrite ".

    2. Queue a storage task with stream ’s relevant global object to run these steps:

      1. If accessResult ’s permission state is not " granted ", reject p with a DOMException of accessResult ’s error name and abort these steps.

      2. Let command be input [" type "] if input is a dictionary ; otherwise " write ".

      3. If command is " write ":

        1. If input is undefined or input is a dictionary and input [" data "] does not exist , reject p with a TypeError and abort these steps.

        2. Let data be input [" data "] if input is a dictionary ; otherwise input .

        3. Let writePosition be stream ’s [[seekOffset]] .

        4. If input is a dictionary and input [" position "] exists , set writePosition to input [" position "].

        5. Let oldSize be stream ’s [[buffer]] 's length .

        6. If data is a BufferSource , let dataBytes be a copy of data .

        7. Otherwise, if data is a Blob :

          1. Let dataBytes be the result of performing the read operation on data . If this throws an exception, reject p with that exception and abort these steps.

        8. Otherwise:

          1. Assert : data is a USVString .

          2. Let dataBytes be the result of UTF-8 encoding data .

        9. If writePosition is larger than oldSize , append writePosition - oldSize 0x00 (NUL) bytes to the end of stream ’s [[buffer]] .

          Note: Implementations are expected to behave as if the skipped over file contents are indeed filled with NUL bytes. That doesn’t mean these bytes have to actually be written to disk and take up disk space. Instead most file systems support so called sparse files, where these NUL bytes don’t take up actual disk space.

        10. Let head be a byte sequence containing the first writePosition bytes of stream ’s [[buffer]] .

        11. Let tail be an empty byte sequence .

        12. If writePosition + data ’s length is smaller than oldSize :

          1. Let tail be a byte sequence containing the last oldSize - ( writePosition + data ’s length ) bytes of stream ’s [[buffer]] .

        13. Set stream ’s [[buffer]] to the concatenation of head , data and tail .

        14. If the operations modifying stream ’s [[buffer]] in the previous steps failed due to exceeding the storage quota , reject p with a " QuotaExceededError " DOMException and abort these steps, leaving stream ’s [[buffer]] unmodified.

          Note: Storage quota only applies to files stored in a bucket file system . However this operation could still fail for other files, for example if the disk being written to runs out of disk space.

        15. Set stream ’s [[seekOffset]] to writePosition + data ’s length .

        16. Resolve p .

      4. Otherwise, if command is " seek ":

        1. Assert : chunk is a dictionary .

        2. If chunk [" position "] does not exist , reject p with a TypeError and abort these steps.

        3. Set stream ’s [[seekOffset]] to chunk [" position "].

        4. Resolve p .

      5. Otherwise, if command is " truncate ":

        1. Assert : chunk is a dictionary .

        2. If chunk [" size "] does not exist , reject p with a TypeError and abort these steps.

        3. Let newSize be chunk [" size "].

        4. Let oldSize be stream ’s [[buffer]] 's length .

        5. If newSize is larger than oldSize :

          1. Set stream ’s [[buffer]] to a byte sequence formed by concating stream ’s [[buffer]] with a byte sequence containing newSize - oldSize 0x00 bytes.

          2. If the operation in the previous step failed due to exceeding the storage quota , reject p with a " QuotaExceededError " DOMException and abort these steps, leaving stream ’s [[buffer]] unmodified.

            Note: Storage quota only applies to files stored in a bucket file system . However this operation could still fail for other files, for example if the disk being written to runs out of disk space.

        6. Otherwise, if newSize is smaller than oldSize :

          1. Set stream ’s [[buffer]] to a byte sequence containing the first newSize bytes in stream ’s [[buffer]] .

        7. If stream ’s [[seekOffset]] is bigger than newSize , set stream ’s [[seekOffset]] to newSize .

        8. Resolve p .

  4. Return p .

2.5.1. The write() method

await stream . write ( data )
await stream . write ({ type : " write ", data : data })

Writes the content of data into the file associated with stream at the current file cursor offset.

No changes are written to the actual file on disk until the stream has been closed. Changes are typically written to a temporary file instead.

await stream . write ({ type : " write ", position : position , data : data })

Writes the content of data into the file associated with stream at position bytes from the top of the file. Also updates the current file cursor offset to the end of the written data.

No changes are written to the actual file on disk until the stream has been closed. Changes are typically written to a temporary file instead.

await stream . write ({ type : " seek ", position : position })

Updates the current file cursor offset the position bytes from the top of the file.

await stream . write ({ type : " truncate ", size : size })

Resizes the file associated with stream to be size bytes long. If size is larger than the current file size this pads the file with null bytes, otherwise it truncates the file.

The file cursor is updated when truncate is called. If the cursor is smaller than size , it remains unchanged. If the cursor is larger than size , it is set to size to ensure that subsequent writes do not error.

No changes are written to the actual file until on disk until the stream has been closed. Changes are typically written to a temporary file instead.

The write( data ) method steps are:

  1. Let writer be the result of getting a writer for this .

  2. Let result be the result of writing a chunk to writer given data .

  3. Release writer .

  4. Return result .

2.5.2. The seek() method

await stream . seek ( position )

Updates the current file cursor offset the position bytes from the top of the file.

The seek( position ) method steps are:

  1. Let writer be the result of getting a writer for this .

  2. Let result be the result of writing a chunk to writer given «[ " type " → " seek ", " position " → position ]».

  3. Release writer .

  4. Return result .

2.5.3. The truncate() method

await stream . truncate ( size )

Resizes the file associated with stream to be size bytes long. If size is larger than the current file size this pads the file with null bytes, otherwise it truncates the file.

The file cursor is updated when truncate is called. If the cursor is smaller than size , it remains unchanged. If the cursor is larger than size , it is set to size to ensure that subsequent writes do not error.

No changes are written to the actual file until on disk until the stream has been closed. Changes are typically written to a temporary file instead.

The truncate( size ) method steps are:

  1. Let writer be the result of getting a writer for this .

  2. Let result be the result of writing a chunk to writer given «[ " type " → " truncate ", " size " → size ]».

  3. Release writer .

  4. Return result .

2.6. The FileSystemSyncAccessHandle interface 

dictionary FileSystemReadWriteOptions {
  [EnforceRange] unsigned long long at;
};
[Exposed=DedicatedWorker, SecureContext]
interface FileSystemSyncAccessHandle {
  unsigned long long read(AllowSharedBufferSource buffer,
                          optional FileSystemReadWriteOptions options = {});
  unsigned long long write(AllowSharedBufferSource buffer,
                           optional FileSystemReadWriteOptions options = {});
  undefined truncate([EnforceRange] unsigned long long newSize);
  unsigned long long getSize();
  undefined flush();
  undefined close();
};

A FileSystemSyncAccessHandle has an associated [[file]] (a file entry ).

A FileSystemSyncAccessHandle has an associated [[state]] , a string that may exclusively be " open " or " closed ".

A FileSystemSyncAccessHandle is an object that is capable of reading from/writing to, as well as obtaining and changing the size of, a single file.

A FileSystemSyncAccessHandle offers synchronous methods. This allows for higher performance on contexts where asynchronous operations come with high overhead, e.g., WebAssembly.

A FileSystemSyncAccessHandle has a file position cursor initialized at byte offset 0 from the top of the file.

To create a new FileSystemSyncAccessHandle given a file entry file in a Realm realm :

  1. Let handle be a new FileSystemSyncAccessHandle in realm .

  2. Set handle ’s [[file]] to file .

  3. Set handle ’s [[state]] to " open ".

  4. Return handle .

2.6.1. The read() method

handle . read ( buffer )
handle . read ( buffer , { at })

Reads the contents of the file associated with handle into buffer , optionally at a given offset.

The file cursor is updated when read() is called to point to the byte after the last byte read.

Specify how Access Handles should react when reading from a file that has been modified externally.

The read( buffer , FileSystemReadWriteOptions : options ) method steps are:

  1. If this 's [[state]] is " closed ", throw an " InvalidStateError " DOMException .

  2. Let bufferSize be buffer ’s byte length .

  3. Let fileContents be this 's [[file]] 's binary data .

  4. Let fileSize be fileContents ’s length .

  5. Let readStart be options [" at "] if options [" at "] exists ; otherwise this 's file position cursor .

  6. If the underlying file system does not support reading from a file offset of readStart , throw a TypeError .

  7. If readStart is larger than fileSize :

    1. Set this 's file position cursor to fileSize .

    2. Return 0.

  8. Let readEnd be readStart + ( bufferSize − 1).

  9. If readEnd is larger than fileSize , set readEnd to fileSize .

  10. Let bytes be a byte sequence containing the bytes from readStart to readEnd of fileContents .

  11. Let result be bytes ’s length .

  12. If the operations reading from fileContents in the previous steps failed:

    1. If there were partial reads and the number of bytes that were read into bytes is known, set result to the number of read bytes.

    2. Otherwise set result to 0.

  13. Let arrayBuffer be buffer ’s underlying buffer .

  14. Write bytes into arrayBuffer .

  15. Set this 's file position cursor to readStart + result .

  16. Return result .

2.6.2. The write() method

handle . write ( buffer )
handle . write ( buffer , { at })

Writes the content of buffer into the file associated with handle , optionally at a given offset, and returns the number of written bytes. Checking the returned number of written bytes allows callers to detect and handle errors and partial writes.

The file cursor is updated when write is called to point to the byte after the last byte written.

The write( buffer , FileSystemReadWriteOptions : options ) method steps are:

  1. If this 's [[state]] is " closed ", throw an " InvalidStateError " DOMException .

  2. Let writePosition be options [" at "] if options [" at "] exists ; otherwise this 's file position cursor .

  3. If the underlying file system does not support writing to a file offset of writePosition , throw a TypeError .

  4. Let fileContents be a copy of this 's [[file]] 's binary data .

  5. Let oldSize be fileContents ’s length .

  6. Let bufferSize be buffer ’s byte length .

  7. If writePosition is larger than oldSize , append writePosition − oldSize 0x00 (NUL) bytes to the end of fileContents .

    Note: Implementations are expected to behave as if the skipped over file contents are indeed filled with NUL bytes. That doesn’t mean these bytes have to actually be written to disk and take up disk space. Instead most file systems support so called sparse files, where these NUL bytes don’t take up actual disk space.

  8. Let head be a byte sequence containing the first writePosition bytes of fileContents .

  9. Let tail be an empty byte sequence .

  10. If writePosition + bufferSize is smaller than oldSize :

    1. Set tail to a byte sequence containing the last oldSize − ( writePosition + bufferSize ) bytes of fileContents .

  11. Let newSize be head ’s length + bufferSize + tail ’s length .

  12. If newSize − oldSize exceeds the available storage quota , throw a " QuotaExceededError " DOMException .

  13. Set this 's [[file]] 's binary data to the concatenation of head , the contents of buffer and tail .

    Note: The mechanism used to access buffer’s contents is left purposely vague. It is likely that implementations will choose to focus on performance by issuing direct write calls to the host operating system (instead of creating a copy of buffer), which prevents a detailed specification of the write order and the results of partial writes.

  14. If the operations modifying the this 's [[file]] 's binary data in the previous steps failed:

    1. If there were partial writes and the number of bytes that were written from buffer is known:

      1. Let bytesWritten be the number of bytes that were written from buffer .

      2. Set this 's file position cursor to writePosition + bytesWritten .

      3. Return bytesWritten .

    2. Otherwise throw an " InvalidStateError " DOMException .

  15. Set this 's file position cursor to writePosition + bufferSize .

  16. Return bufferSize .

2.6.3. The truncate() method

handle . truncate ( newSize )

Resizes the file associated with handle to be newSize bytes long. If newSize is larger than the current file size this pads the file with null bytes; otherwise it truncates the file.

The file cursor is updated when truncate is called. If the cursor is smaller than newSize , it remains unchanged. If the cursor is larger than newSize , it is set to newSize .

The truncate( newSize ) method steps are:

  1. If this 's [[state]] is " closed ", throw an " InvalidStateError " DOMException .

  2. Let fileContents be a copy of this 's [[file]] 's binary data .

  3. Let oldSize be the length of this 's [[file]] 's binary data .

  4. If the underlying file system does not support setting a file’s size to newSize , throw a TypeError .

  5. If newSize is larger than oldSize :

    1. If newSize − oldSize exceeds the available storage quota , throw a " QuotaExceededError " DOMException .

    2. Set this 's [[file]] 's to a byte sequence formed by concatenating fileContents with a byte sequence containing newSize − oldSize 0x00 bytes.

    3. If the operations modifying the this 's [[file]] 's binary data in the previous steps failed, throw an " InvalidStateError " DOMException .

  6. Otherwise, if newSize is smaller than oldSize :

    1. Set this 's [[file]] 's to a byte sequence containing the first newSize bytes in fileContents .

    2. If the operations modifying the this 's [[file]] 's binary data in the previous steps failed, throw an " InvalidStateError " DOMException .

  7. If this 's file position cursor is greater than newSize , then set file position cursor to newSize .

2.6.4. The getSize() method

handle . getSize()

Returns the size of the file associated with handle in bytes.

The getSize() method steps are:

  1. If this 's [[state]] is " closed ", throw an " InvalidStateError " DOMException .

  2. Return this 's [[file]] 's binary data 's length .

2.6.5. The flush() method

handle . flush()

Ensures that the contents of the file associated with handle contain all the modifications done through write() .

The flush() method steps are:

  1. If this 's [[state]] is " closed ", throw an " InvalidStateError " DOMException .

  2. Attempt to transfer all cached modifications of the file’s content to the file system’s underlying storage device.

    Note: This is also known as flushing. This may might be a no-op on some file systems, such as in-memory file systems, which do not have a "disk" to flush to.

2.6.6. The close() method

handle . close()

Closes the access handle or no-ops if the access handle is already closed. This disables any further operations on it and releases the lock on the [[file]] associated with handle .

The close() method steps are:

  1. If this 's [[state]] is " closed ", return.

  2. Set this 's [[state]] to " closed ".

  3. Set lockReleased to false.

  4. Let file be this 's [[file]] .

  5. Enqueue the following steps to the file system queue :

    1. Release the lock on file .

    2. Set lockReleased to true.

  6. Pause until lockReleased is true.

Note: This method does not guarantee that all file modifications will be immediately reflected in the underlying storage device. Call the flush() method first if you require this guarantee.

3. Accessing the Bucket File System

The bucket file system is a storage endpoint whose identifier is "fileSystem" , types are « "local" » , and quota is null.

The bucket file system implements file system with root as an implementation-defined opaque string .

Note: bucket file system 's root might include relevant identifying information such as the storage bucket .

Storage endpoints should be defined in [storage] itself, rather than being defined here. So merge this into the table there.

Note: While user agents will typically implement this by persisting the contents of a bucket file system to disk, it is not intended that the contents are easily user accessible. Similarly there is no expectation that files or directories with names matching the names of children of a bucket file system exist. 

[SecureContext]
partial interface StorageManager {
  Promise<FileSystemDirectoryHandle> getDirectory();
};
directoryHandle = await navigator . storage . getDirectory()

Returns the root directory of the bucket file system .

The getDirectory() method steps are:

  1. Let environment be the current settings object .

  2. Let map be the result of running obtain a local storage bottle map with environment and "fileSystem" . If this returns failure, return a promise rejected with a " SecurityError " DOMException .

  3. If map ["root"] does not exist :

    1. Let dir be a new directory entry whose query access and request access algorithms always return a file system access result with a permission state of " granted " and with an error name of the empty string.

    2. Set dir ’s name to the empty string.

    3. Set dir ’s children to an empty set .

    4. Set map ["root"] to dir .

  4. Let root fileSystem be an implementation-defined the relevant bucket file system opaque string 's root .

  5. Let path be « the empty string ».

  6. Let handle be the result of creating a new FileSystemDirectoryHandle . given root fileSystem and path in the current realm .

    Note: root might include relevant identifying information such as the storage bucket .

  7. Assert: locating an entry given handle ’s locator returns a directory entry that is the same entry as map ["root"].

  8. Return a promise resolved with handle .

4. Observing file system change events

4.1. The FileSystemObserver interface 

dictionary FileSystemObserverObserveOptions {  boolean recursive = false;
};
callback FileSystemObserverCallback = undefined (  sequence<FileSystemChangeRecord> records,  FileSystemObserver observer
);
[
    Exposed=(DedicatedWorker,SharedWorker,Window),    SecureContext
] interface FileSystemObserver {
  constructor(FileSystemObserverCallback callback);  Promise<undefined> observe(FileSystemHandle handle,                          optional FileSystemObserverObserveOptions options = {});  undefined unobserve(FileSystemHandle handle);  undefined disconnect();
};
The FileSystemObserver interface can be used to observe file system events .

The FileSystemObserver has an asociated FileSystemObserverCallback callback .

The FileSystemObserver has an associated observerRegistrations (a map of file system locators to file system observer registrations ).

4.1.1. The FileSystemObserver constructor

The new FileSystemObserver(FileSystemObserverCallback callback ) steps are:

  1. Let this be a new FileSystemObserver .

  2. Set this 's callback to callback .

  3. Set this 's observerRegistrations be the empty map.

4.1.2. The observe() method

The observe(FileSystemHandle handle , FileSystemObserverObserveOptions options ) steps are:

  1. Let result be a new promise .

  2. Let recursive be options [" recursive "].

  3. Let observerRegistrationMap be this 's observerRegistrations .

  4. Let locator be handle ’s locator .

  5. Let global be this 's relevant global object .

  6. Enqueue the following steps to the file system queue :

    1. If observerRegistrationMap [ locator ] exists , abort these steps.

    2. Let entry be the result of locating an entry given locator .

    3. Let accessResult be the result of running entry ’s query access given " read ".

    4. Queue a storage task with global to run these steps:

      1. If accessResult ’s permission state is not " granted ", reject result with a DOMException of accessResult ’s error name and abort these steps.

      2. If entry is null, reject result with a " NotFoundError " DOMException and abort these steps.

      3. Enqueue the following steps to the file system queue :

        1. Create an observer registration for this on handle with recursive .

      4. Resolve result with null.

4.1.3. The unobserve() method

The unobserve(FileSystemHandle handle ) steps are:

  1. Let locator be handle ’s locator .

  2. Let observerRegistrationMap be this 's observerRegistrations .

  3. Enqueue the following steps to the file system queue :

    1. If observerRegistrationMap [ locator ] does not exist , abort these steps.

    2. Destroy observerRegistrationMap [ locator ].

4.1.4. The disconnect() method

The disconnect() steps are:

  1. Let observerRegistrationMap be this 's observerRegistrations .

  2. Enqueue the following steps to the file system queue :

    1. Let observerRegistrations be the result of getting the values of observerRegistrationMap .

    2. For each observerRegistration in observerRegistrations :

      1. Destroy observerRegistration .

4.2. The FileSystemChangeRecord interface 

enum FileSystemChangeType {  "appeared",  "disappeared",  "errored",  "modified",  "moved",  "unknown",
};
dictionary FileSystemChangeRecord {  required FileSystemHandle root;  FileSystemHandle? changedHandle;  required sequence<DOMString> relativePathComponents;  required FileSystemChangeType type;  sequence<DOMString>? relativePathMovedFrom;
};
root

The handle that was passed to FileSystemObserver.observe().

changedHandle

The handle that the change occurred on. This is not set for "disappeared", "errored", and "unknown" events. It’s not given for "disappeared" since the handle would point to a non-existent folder or file. It’s not given for "errored" and "unknown" since it is meaningless in these contexts as these events are sent for the observation as a whole and not any one particular file or folder.

relativePathComponents

The path of changedHandle relative to root .

type

The type of change.

relativePathMovedFrom

If type is " moved ", this corresponds to the former path of changedHandle relative to root , if the former path is known; otherwise null.

The values of the FileSystemChangeType indicate the following:
"appeared"

The changedHandle was created or moved into the scope of the root .

"disappeared"

The changedHandle was deleted or moved out of the scope of the root .

"errored"

An error has occurred for this file system observer registration and it will no longer receive change events. For example, this might be sent for a Linux implementation using the inotify API when it runs out of watches.

"modified"

The changedHandle has been modified.

"moved"

The changedHandle has been moved within the watch scope from relativePathMovedFrom to relativePathComponents .

"unknown"

Zero or more events might have been missed. For example, this might be sent for a Windows implementation using the ReadDirectoryChangesW API when it has a buffer overflow. A developer might want to poll the watched directory or file for changes they missed.

To create a new FileSystemChangeRecord for a file system observer registration observerRegistration given a file system locator changedLocator , a FileSystemChangeType type , and an optional file system locator movedFromLocator :

  1. Let root be observerRegistration ’s root handle .

  2. Let rootLocator be root ’s locator .

  3. Let relativePathComponents be the result of resolving changedLocator relative to rootLocator .

  4. Let relativePathMovedFrom be null.

  5. If movedFromLocator was given, set relativePathMovedFrom to the result of resolving movedFromLocator relative to rootLocator .

  6. Let realm be root ’s relevant realm .

  7. Let record be a new FileSystemChangeRecord in realm .

  8. Set record ’s root to root .

  9. Set record ’s changedHandle to null.

  10. Set record ’s relativePathComponents to relativePathComponents .

  11. Set record ’s type to type .

  12. Set record ’s relativePathMovedFrom to relativePathMovedFrom .

  13. If type is not equal to "disappeared", "errored", or "unknown":

    1. Set record ’s changedHandle to the result of creating a new FileSystemHandle given changedLocator in realm .

  14. Return record .

Acknowledgments

Many thanks to Alex Danilo, Anne van Kesteren, Anoesj Sadraee, Austin Sullivan, Chase Phillips, Daseul Lee, Dru Knox, Edgar Chen, Emanuel Krivoy, Hazim Mohamed, Ingvar Stepanyan, Jari Jalkanen, Joshua Bell, Kagami Sascha Rosylight, Marcos Cáceres, Martin Thomson, Olivier Yiptong, Philip Jägenstedt, Randell Jesup, Richard Stotz, Ruth John, Sid Vishnoi, Sihui Liu, Stefan Sauer, Thomas Steiner, Victor Costan, and Youenn Fablet for being awesome!

This standard is written by Marijn Kruisselbrink ( Google , mek@chromium.org ).

Intellectual property rights

This Living Standard includes material copied from W3C WICG’s File System Access , which is available under the W3C Software and Document License .

Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a Creative Commons Attribution 4.0 International License . To the extent portions of it are incorporated into source code, such portions in the source code are licensed under the BSD 3-Clause License instead.

This is the Living Standard. Those interested in the patent-review version should view the Living Standard Review Draft .

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[ECMASCRIPT]
ECMAScript Language Specification . URL: https://tc39.es/ecma262/multipage/
[ENCODING]
Anne van Kesteren. Encoding Standard . Living Standard. URL: https://encoding.spec.whatwg.org/
[FILE-API]
Marijn Kruisselbrink. File API . URL: https://w3c.github.io/FileAPI/
[HTML]
Anne van Kesteren; et al. HTML Standard . Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard . Living Standard. URL: https://infra.spec.whatwg.org/
[PERMISSIONS]
Marcos Caceres; Mike Taylor. Permissions . URL: https://w3c.github.io/permissions/
[PERMISSIONS-REQUEST]
Requesting Permissions . cg-draft. URL: https://wicg.github.io/permissions-request/
[STORAGE]
Anne van Kesteren. Storage Standard . Living Standard. URL: https://storage.spec.whatwg.org/
[STREAMS]
Adam Rice; et al. Streams Standard . Living Standard. URL: https://streams.spec.whatwg.org/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard . Living Standard. URL: https://webidl.spec.whatwg.org/

IDL Index 

enum FileSystemHandleKind {
  "file",
  "directory",
};
[Exposed=(Window,Worker), SecureContext, Serializable]
interface FileSystemHandle {
  readonly attribute FileSystemHandleKind kind;
  readonly attribute USVString name;
  Promise<boolean> isSameEntry(FileSystemHandle other);
};
dictionary FileSystemCreateWritableOptions {
  boolean keepExistingData = false;
};
[Exposed=(Window,Worker), SecureContext, Serializable]
interface FileSystemFileHandle : FileSystemHandle {
  Promise<File> getFile();
  Promise<FileSystemWritableFileStream> createWritable(optional FileSystemCreateWritableOptions options = {});
  [Exposed=DedicatedWorker]
  Promise<FileSystemSyncAccessHandle> createSyncAccessHandle();
};
dictionary FileSystemGetFileOptions {
  boolean create = false;
};
dictionary FileSystemGetDirectoryOptions {
  boolean create = false;
};
dictionary FileSystemRemoveOptions {
  boolean recursive = false;
};
[Exposed=(Window,Worker), SecureContext, Serializable]
interface FileSystemDirectoryHandle : FileSystemHandle {
  async iterable<USVString, FileSystemHandle>;
  Promise<FileSystemFileHandle> getFileHandle(USVString name, optional FileSystemGetFileOptions options = {});
  Promise<FileSystemDirectoryHandle> getDirectoryHandle(USVString name, optional FileSystemGetDirectoryOptions options = {});
  Promise<undefined> removeEntry(USVString name, optional FileSystemRemoveOptions options = {});
  Promise<sequence<USVString>?> resolve(FileSystemHandle possibleDescendant);
};
enum WriteCommandType {
  "write",
  "seek",
  "truncate",
};
dictionary WriteParams {
  required WriteCommandType type;
  unsigned long long? size;
  unsigned long long? position;
  (BufferSource or Blob or USVString)? data;
};
typedef (BufferSource or Blob or USVString or WriteParams) FileSystemWriteChunkType;
[Exposed=(Window,Worker), SecureContext]
interface FileSystemWritableFileStream : WritableStream {
  Promise<undefined> write(FileSystemWriteChunkType data);
  Promise<undefined> seek(unsigned long long position);
  Promise<undefined> truncate(unsigned long long size);
};
dictionary FileSystemReadWriteOptions {
  [EnforceRange] unsigned long long at;
};
[Exposed=DedicatedWorker, SecureContext]
interface FileSystemSyncAccessHandle {
  unsigned long long read(AllowSharedBufferSource buffer,
                          optional FileSystemReadWriteOptions options = {});
  unsigned long long write(AllowSharedBufferSource buffer,
                           optional FileSystemReadWriteOptions options = {});
  undefined truncate([EnforceRange] unsigned long long newSize);
  unsigned long long getSize();
  undefined flush();
  undefined close();
};
[SecureContext]
partial interface StorageManager {
  Promise<FileSystemDirectoryHandle> getDirectory();
};
dictionary FileSystemObserverObserveOptions {
  boolean recursive = false;
};
callback FileSystemObserverCallback = undefined (  sequence<FileSystemChangeRecord> records,  FileSystemObserver observer
);
[
    Exposed=(DedicatedWorker,SharedWorker,Window),    SecureContext
] interface FileSystemObserver {
  constructor(FileSystemObserverCallback callback);  Promise<undefined> observe(FileSystemHandle handle,                          optional FileSystemObserverObserveOptions options = {});  undefined unobserve(FileSystemHandle handle);  undefined disconnect();
};
enum FileSystemChangeType {  "appeared",  "disappeared",  "errored",  "modified",  "moved",  "unknown",
};
dictionary FileSystemChangeRecord {  required FileSystemHandle root;  FileSystemHandle? changedHandle;  required sequence<DOMString> relativePathComponents;  required FileSystemChangeType type;  sequence<DOMString>? relativePathMovedFrom;
};