File System (PR #165)

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:

• Getting the path with entry returns path, provided no intermediate file system operations were run.

• entry’s name is the last item of path.

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:

• Locating an entry with path returns entry, provided no intermediate file system operations were run.

• entry’s name is the last item of path.

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.

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.

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.

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.

To resolve a file system locator child relative to a file system locator root:

1. Let relationship be the result of getting the relationship between root and child.

2. If relationship is equal to "other" or "ancestor", return null.

3. If relationship is equal to "self", return « ».

4. Let childPath be child’s path.

5. Let rootPath be root’s path.

6. Let relativePath be « ».

7. For each index of the range from rootPath’s 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.

To get the relationship from a file system locator self to a file system locator related:

1. If self’s file system is not related’s file system, return "other".

2. Let selfPath be self’s path.

3. Let relatedPath be related’s path.

4. Let selfPathSize be selfPath’s size.

5. Let relatedPathSize be relatedPath’s size.

6. For each index of selfPath’s indices:

   1. If index is greater than or equal to relatedPathSize, return "ancestor".

   2. If selfPath[index] is not relatedPath[index], return "other".

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

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

9. Return "descendant".

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

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

1. 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 path.

4. If entry is null, return null.

5. Return entry.

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

1. Let fileSystem be entry’s file system.

2. Let path be the result of running fileSystem’s get the path given entry.

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

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

5. If entry is a directory entry, set locator’s kind to "directory".

6. Return entry.

enum FileSystemHandleKind {
  "file",
  "directory",
};

[Exposed=(Window,Worker), SecureContext, Serializable]
interface FileSystemHandle {
  readonly attribute FileSystemHandleKind kind;
  readonly attribute USVString name;

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

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.

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]].

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.

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

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 childFileSystem be the parentLocator’s 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, file system is childFileSystem, and path is childPath.

6. Return handle.

To create a new FileSystemFileHandle given a file system 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", file system is fileSystem, and path is path.

3. Return handle.

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.

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.

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.

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

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 childFileSystem be the parentLocator’s 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, file system is childFileSystem, and path is childPath.

6. Return handle.

To create a new FileSystemDirectoryHandle given a file system 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", file system is fileSystem, and path is path.

3. Return handle.

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.

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.

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.

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.

// 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:

1. Let result be a new promise.

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

3. Enqueue the following steps to 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.

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

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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 might be a no-op on some file systems, such as in-memory file systems, which do not have a "disk" to flush to.

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.

[SecureContext]
partial interface StorageManager {
  Promise<FileSystemDirectoryHandle> getDirectory();
};

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 fileSystem be the relevant bucket file system’s root.

5. Let path be « the empty string ».

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

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.

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 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.

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.

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].

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.

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

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.