Native File System

Draft Community Group Report,

This version:
https://wicg.github.io/native-file-system/
Issue Tracking:
GitHub
Inline In Spec
Editor:
(Google)

Abstract

This document defines a web platform API that lets websites gain write access to the native file system. It builds on File API, but adds lots of new functionality on top.

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1. Introduction

This section is non-normative.

This provides similar functionality as earlier drafts of the File API: Directories and System as well as the File and Directory Entries API, but with a more modern API.

TODO explain native file system access

Additionally this API also makes it possible for websites to get access to some 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. It also makes it easier to write automated tests for code using this API. The entry point for this is the getOriginPrivateDirectory() method.

2. Files and Directories

2.1. Concepts

An entry is either a file entry or a directory entry.

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

A file entry additionally consists of binary data and a modification timestamp.

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

An 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. An entry's parent is null if no such directory entry exists.

Note: Two different 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. Typically an entry does not have a parent if it was returned by getOriginPrivateDirectory() or one of the native file system handle factories, and an entry will have a parent in all other cases.

Entries can (but don’t have to) be backed by files on the systems native 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.

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

TODO: Explain better how entries map to files on disk (multiple entries can map to the same file or directory on disk but an entry doesn’t have to map to any file on disk).

To resolve an entry child relative to a directory entry root, run the following steps:
  1. Let result be a new promise.

  2. Run the following steps in parallel:

    1. If child is the same as root, resolve result with an empty list, and abort.

    2. Let childPromises be « ».

    3. For each entry of root’s entry's children:

      1. Let p be the result of resolving child relative to entry.

      2. Append p to childPromises.

      3. Upon fulfillment of p with value path:

        1. If path is not null:

          1. Prepend entry’s name to path.

          2. Resolve result with path.

    4. Wait for all childPromises, with the following success steps:

      1. If result hasn’t been resolved yet, resolve result with null.

  3. Return result.

2.2. Permissions

Figure out some way to integrate this better with the permissions API [permissions], for example by making the entry be a part of the PermissionDescriptor.

An entry entry has associated query permission steps, which take a FileSystemHandlePermissionDescriptor descriptor and an environment settings object settings, and return a PermissionState. Unless specified otherwise, these steps are:
  1. Let parent be entry’s parent.

  2. Assert: parent is not null.

    Note: § 3.1 Native File System Permissions overrides these steps for entries returned by the native file system handle factories. Additionally § 4.1 Sandboxed File System Concepts overrides these steps for entries returned by getOriginPrivateDirectory(). All other entries always have a parent.

  3. Return the result of running parent’s query permission steps given descriptor and settings.

Note: These steps return the current state synchronously, however these steps are only invoked from "in parallel" sections of algorithms, so this doesn’t have to be implemented in a synchronous manner.

An entry entry also has associated request permission steps, which take a FileSystemHandlePermissionDescriptor descriptor and an environment settings object settings. Unless specified otherwise, these steps are:
  1. Let parent be entry’s parent.

  2. If parent is not null, run parent’s request permission steps given descriptor and settings.

Note: These steps do not return anything. However as a result of executing the request permission steps for an entry the permission state for that entry (and other entries) can be updated, and the new state can be queried by executing the query permission steps.

2.3. The FileSystemHandle interface

dictionary FileSystemHandlePermissionDescriptor {
  boolean writable = false;
};

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

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

  Promise<boolean> isSameEntry(FileSystemHandle other);

  Promise<PermissionState> queryPermission(optional FileSystemHandlePermissionDescriptor descriptor = {});
  Promise<PermissionState> requestPermission(optional FileSystemHandlePermissionDescriptor descriptor = {});
};

A FileSystemHandle object represents an entry. Each FileSystemHandle object is associated with an entry (an entry). Multiple separate objects implementing the FileSystemHandle interface can all be associated with the same entry simultaneously.

FileSystemHandle objects are serializable objects.

In the Origin Trial as available in Chrome 78, these objects are not yet serializable. In Chrome 82 they are.

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

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

  2. Set serialized.[[Entry]] to value’s entry.

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.

  2. Set value’s entry to serialized.[[Entry]]

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 name of the entry represented by handle.

The kind attribute must return "file" if the associated entry is a file entry, and return "directory" otherwise.

The name attribute must return the name of the associated entry.

2.3.1. The isSameEntry() method

same = await handle1 . isSameEntry( handle2 )

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

This method is first available in Chrome 82.

The isSameEntry(other) method, when invoked, must run these steps:
  1. Let realm be this's relevant Realm.

  2. Let p be a new promise in realm.

  3. Run the following steps in parallel:

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

    2. Else resolve p with false.

  4. Return p.

2.3.2. The queryPermission() method

the currently described API here assumes a model where it is not possible to have a write-only handle. I.e. it is not possible to have or request write access without also having read access. There definitely are use cases for write-only handles (e.g. directory downloads), so we might have to reconsider this. <https://github.com/wicg/native-file-system/issues/119>

status = await handle . queryPermission({ writable = false })
status = await handle . queryPermission()

Queries the current state of the read permission of this handle. If this returns "prompt" the website will have to call requestPermission() before any operations on the handle can be done. If this returns "denied" any operations will reject.

Usually handles returned by the native file system handle factories will initially return "granted" for their read permission state, however other than through the user revoking permission, a handle retrieved from IndexedDB is also likely to return "prompt".

status = await handle . queryPermission({ writable = true })

Queries the current state of the write permission of this handle. If this returns "prompt", attempting to modify the file or directory this handle represents will require user activation and will result in a confirmation prompt being shown to the user. However if the state of the read permission of this handle is also "prompt" the website will need to call requestPermission(). There is no automatic prompting for read access when attempting to read from a file or directory.

The queryPermission(descriptor) method, when invoked, must run these steps:
  1. Let result be a new promise.

  2. Run the following steps in parallel:

    1. Resolve result with the result of running this’s entry's query permission steps given descriptor and this’s relevant settings object.

  3. Return result.

2.3.3. The requestPermission() method

status = await handle . requestPermission({ writable = false })
status = await handle . requestPermission()

If the state of the read permission of this handle is anything other than "prompt", this will return that state directly. If it is "prompt" however, user activation is needed and this will show a confirmation prompt to the user. The new read permission state is then returned, depending on the user’s response to the prompt.

status = await handle . requestPermission({ writable = true })

If the state of the write permission of this handle is anything other than "prompt", this will return that state directly. If the status of the read permission of this handle is "denied" this will return that.

Otherwise the state of the write permission is "prompt" and this will show a confirmation prompt to the user. The new write permission state is then returned, depending on what the user selected.

The requestPermission(descriptor) method, when invoked, must run these steps:
  1. Let result be a new promise.

  2. Run the following steps in parallel:

    1. Run this’s entry's request permission steps given descriptor and this’s relevant settings object. If that throws an exception, reject result with that exception and abort.

    2. Resolve result with the result of running this’s entry's query permission steps given descriptor and this’s relevant settings object.

  3. Return result.

2.4. 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 = {});
};

A FileSystemFileHandle's associated entry must be a file entry.

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

In the Origin Trial as available in Chrome 78, these objects are not yet serializable. In Chrome 82 they are.

2.4.1. The getFile() method

file = await fileHandle . getFile()

Returns a File representing the state on disk of the entry represented by handle. 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, when invoked, must run these steps:
  1. Let result be a new promise.

  2. Run the following steps in parallel:

    1. Let entry be this’s entry.

    2. Let permissionStatus be the result of running entry’s query permission steps given «[ "writable" → false ]» and this’s relevant settings object.

    3. If permissionStatus is not "granted", reject result with a NotAllowedError and abort.

    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. Initialize the value of f’s name attribute to entry’s name.

    8. Initialize the value of f’s lastModified attribute to entry’s modification timestamp.

    9. Initialize the value of f’s type attribute to an implementation defined value, based on for example entry’s name and/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.

  3. Return result.

2.4.2. The createWritable() method

In the Origin Trial as available in Chrome 82, createWritable replaces the createWriter 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 represented by fileHandle until the stream has been closed. User agents try to ensure that no partial writes happen, i.e. the file represented by fileHandle will either contains 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 represented by fileHandle 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.

There has been some 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. <https://github.com/wicg/native-file-system/issues/67>

The createWritable(options) method, when invoked, must run these steps:
  1. Let result be a new promise.

  2. Run the following steps in parallel:

    1. Let entry be this’s entry.

    2. Run entry’s request permission steps given «[ "writable" → true ]» and this’s relevant settings object. If that throws an exception, reject result with that exception and abort.

    3. Let permissionStatus be the result of running entry’s query permission steps given «[ "writable" → true ]» and this’s relevant settings object.

    4. If permissionStatus is not "granted", reject result with a NotAllowedError and abort.

    5. Let stream be the result of creating a new FileSystemWritableFileStream for entry in this’s relevant realm.

    6. If options.keepExistingData is true:

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

    7. Resolve result with stream.

  3. Return result.

2.5. 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<void> removeEntry(USVString name, optional FileSystemRemoveOptions options = {});

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

A FileSystemDirectoryHandle's associated entry must be a directory entry.

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

In the Origin Trial as available in Chrome 78, these objects are not yet serializable. In Chrome 82 they are.

In Chrome versions upto Chrome 85 getFileHandle and getDirectoryHandle where called getFile and getDirectory instead.

2.5.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 entry represented by directoryHandle. 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 Chrome this is currently implemented as a directoryHandle.getEntries() method that can be used in a for await..of loop. This getEntries() method returns more or less the same async iterable as what is returned by values() in this specification. The proper async iterable declaration is not yet implemented.

In the future we might want to add arguments to the async iterable declaration to support for example recursive iteration. <https://github.com/wicg/native-file-system/issues/173>

The asynchronous iterator initialization steps for a FileSystemDirectoryHandle handle ant its async iterator iterator are:
  1. Let entry be handle’s entry.

  2. Let permissionStatus be the result of running entry’s query permission steps given «[ "writable" → false ]» and this’s relevant settings object.

  3. If permissionStatus is not "granted", throw a NotAllowedError.

  4. 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. Let directory be handle’s entry.

  3. Let permissionStatus be the result of running directory’s query permission steps given «[ "writable" → false ]» and this’s relevant settings object.

  4. If permissionStatus is not "granted", reject promise with a NotAllowedError and return promise.

  5. Let child be an 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.

  6. If child is null, then:

    1. Resolve promise with undefined.

  7. Otherwise:

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

    2. If child is a file entry:

      1. Let result be a new FileSystemFileHandle associated with child.

    3. Otherwise:

      1. Let result be a new FileSystemDirectoryHandle associated with child.

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

  8. Return promise.

2.5.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 represented by directoryHandle. 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 represented by directoryHandle. 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, when invoked, must run these steps:
  1. Let result be a new promise.

  2. Run the following steps in parallel:

    1. If name is not a valid file name, reject result with a TypeError and abort.

    2. Let entry be this’s entry.

    3. If options.create is true:

      1. Run entry’s request permission steps given «[ "writable" → true ]» and this’s relevant settings object. If that throws an exception, reject result with that exception and abort.

      2. Let permissionStatus be the result of running entry’s query permission steps given «[ "writable" → true ]» and this’s relevant settings object.

    4. Otherwise:

      1. Let permissionStatus be the result of running entry’s query permission steps given «[ "writable" → false ]» and this’s relevant settings object.

    5. If permissionStatus is not "granted", reject result with a NotAllowedError and abort.

    6. 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 and abort.

        2. Resolve result with a new FileSystemFileHandle whose entry is child and abort.

    7. If options.create is false:

      1. Reject result with a NotFoundError and abort.

    8. Let child be a new file entry.

    9. Set child’s name to name.

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

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

    12. Append child to entry’s children.

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

      Better specify what possible exceptions this could throw. <https://github.com/wicg/native-file-system/issues/68>

    14. Resolve result with a new FileSystemFileHandle whose entry is child.

  3. Return result.

2.5.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 represented by directoryHandle. 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 represented by directoryHandle. 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, when invoked, must run these steps:
  1. Let result be a new promise.

  2. Run the following steps in parallel:

    1. If name is not a valid file name, reject result with a TypeError and abort.

    2. Let entry be this’s entry.

    3. If options.create is true:

      1. Run entry’s request permission steps given «[ "writable" → true ]» and this’s relevant settings object. If that throws an exception, reject result with that exception and abort.

      2. Let permissionStatus be the result of running entry’s query permission steps given «[ "writable" → true ]» and this’s relevant settings object.

    4. Else:

      1. Let permissionStatus be the result of running entry’s query permission steps given «[ "writable" → false ]» and this’s relevant settings object.

    5. If permissionStatus is not "granted", reject result with a NotAllowedError and abort.

    6. 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 and abort.

        2. Resolve result with a new FileSystemDirectoryHandle whose entry is child and abort.

    7. If options.create is false:

      1. Reject result with a NotFoundError and abort.

    8. Let child be a new directory entry.

    9. Set child’s name to name.

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

    11. Append child to entry’s children.

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

      Better specify what possible exceptions this could throw. <https://github.com/wicg/native-file-system/issues/68>

    13. Resolve result with a new FileSystemDirectoryHandle whose entry is child.

  3. Return result.

2.5.4. The removeEntry() method

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

If the directory represented by directoryHandle 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 entry named name in the directory represented by directoryHandle. If that entry is a directory, its contents will also be deleted recursively. recursively.

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

The removeEntry(name, options) method, when invoked, must run these steps:
  1. Let result be a new promise.

  2. Run the following steps in parallel:

    1. If name is not a valid file name, reject result with a TypeError and abort.

    2. Let entry be this’s entry.

    3. Run entry’s request permission steps given «[ "writable" → true ]» and this’s relevant settings object. If that throws an exception, reject result with that exception.

    4. Let permissionStatus be the result of running entry’s query permission steps given «[ "writable" → true ]» and this’s relevant settings object.

    5. If permissionStatus is not "granted", reject result with a NotAllowedError and abort.

    6. 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 and abort.

        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.

          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. <https://github.com/wicg/native-file-system/issues/68>

        4. Resolve result with undefined.

    7. Reject result with a NotFoundError.

  3. Return result.

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

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

This method is first available in Chrome 82.

// 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 by showing a file picker:
const file_ref = await self.chooseFileSystemEntries({type: 'openFile'});
if (!file_ref) {
    // User cancelled, or otherwise failed to open a file.
    return;
}

// 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, when invoked, must return the result of resolving possibleDescendant’s entry relative to this's entry.

2.6. 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<void> write(FileSystemWriteChunkType data);
  Promise<void> seek(unsigned long long position);
  Promise<void> 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, perform the following steps:
  1. Let stream be a new FileSystemWritableFileStream in realm.

  2. Perform InitializeWritableStream(stream)

  3. Set stream.[[file]] to file.

  4. Let controller be a new WritableStreamDefaultController.

  5. Let startAlgorithm be an algorithm that returns undefined.

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

  7. Let closeAlgorithm be the following steps:

    1. Let closeResult be a new promise.

    2. Run the following steps in parallel:

      1. Let permissionStatus be the result of running stream.[[file]]'s query permission steps given «[ "writable" → true ]» and stream’s relevant settings object.

      2. If permissionStatus is not "granted", reject closeResult with a NotAllowedError and abort.

      3. Perform user agent-specific malware scans and safe browsing checks. If these checks fail, reject closeResult with an AbortError and abort.

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

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

      5. Resolve closeResult with undefined.

    3. Return closeResult.

  8. Let abortAlgorithm be an algorithm that returns a promise resolved with undefined.

  9. Let highWaterMark be 1.

  10. Let sizeAlgorithm be an algorithm that returns 1.

  11. Perform SetUpWritableStreamDefaultController(stream, controller, startAlgorithm, writeAlgorithm, closeAlgorithm, abortAlgorithm, highWaterMark, sizeAlgorithm).

  12. 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. Run the following steps in parallel:

    1. Let permissionStatus be the result of running stream.[[file]]'s query permission steps given «[ "writable" → true ]» and stream’s relevant settings object.

    2. If permissionStatus is not "granted", reject p with a NotAllowedError and abort.

    3. Let command be input.type if input is a WriteParams, and "write" otherwise.

    4. If command is "write":

      1. Let data be input.data if input is a WriteParams, and input otherwise.

      2. If data is undefined, reject p with a TypeError and abort.

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

      4. If input is a WriteParams and input.position is not undefined, set writePosition to input.position.

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

      6. If writePosition is larger than oldSize, reject p with a InvalidStateError and abort.

        Not clear if this should reject, and if it does, is this really the right error type? Chrome’s implementation is actually inconsistent about this rejecting or not.

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

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

      9. Else:

        1. Assert: data is a USVString.

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

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

      11. Let tail be an empty byte sequence.

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

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

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

      14. Set stream.[[seekOffset]] to writePosition + data.length.

      15. Resolve p.

    5. Else if command is "seek":

      1. If chunk.position is undefined, reject p with a TypeError and abort.

      2. Set stream.[[seekOffset]] to chunk.position.

      3. Resolve p.

    6. Else if command is "truncate":

      1. If chunk.size is undefined, reject p with a TypeError and abort.

      2. Let newSize be chunk.size.

      3. Let oldSize be stream.[[buffer]]'s length.

      4. If newSize is larger than oldSize:

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

      5. Else if newSize is smaller than oldSize:

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

      6. If stream.[[seekOffset]] is bigger than newSize, set stream.[[seekOffset]] to newSize.

      7. Resolve p.

  4. Return p.

2.6.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 offset is smaller than offset, it remains unchanged. If the offset is larger than size, the offset 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, when invoked, must run these steps:
  1. Let writer be the result of calling AcquireWritableStreamDefaultWriter(this).

  2. Let result be WritableStreamDefaultWriterWrite(writer, data).

  3. Perform WritableStreamDefaultWriterRelease(writer).

  4. Return result.

2.6.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, when invoked, must run these steps:
  1. Let writer be the result of calling AcquireWritableStreamDefaultWriter(this).

  2. Let result be WritableStreamDefaultWriterWrite(writer, {type: "seek", position: position, size: undefined, data: undefined}).

  3. Perform WritableStreamDefaultWriterRelease(writer).

  4. Return result.

2.6.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 offset is smaller than offset, it remains unchanged. If the offset is larger than size, the offset 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, when invoked, must run these steps:
  1. Let writer be the result of calling AcquireWritableStreamDefaultWriter(this).

  2. Let result be WritableStreamDefaultWriterWrite(writer, {type: "truncate", size: size, position: undefined, data: undefined}).

  3. Perform WritableStreamDefaultWriterRelease(writer).

  4. Return result.

3. Accessing Native File System

dictionary FilePickerAcceptType {
    USVString description;
    record<USVString, sequence<USVString>> accept;
};

dictionary FilePickerOptions {
    sequence<FilePickerAcceptType> types;
    boolean excludeAcceptAllOption = false;
};

dictionary OpenFilePickerOptions : FilePickerOptions {
    boolean multiple = false;
};

dictionary SaveFilePickerOptions : FilePickerOptions {
};

dictionary DirectoryPickerOptions {
};

[SecureContext]
partial interface Window {
    Promise<sequence<FileSystemFileHandle>> showOpenFilePicker(optional OpenFilePickerOptions options = {});
    Promise<FileSystemFileHandle> showSaveFilePicker(optional SaveFilePickerOptions options = {});
    Promise<FileSystemDirectoryHandle> showDirectoryPicker(optional DirectoryPickerOptions options = {});
};

The showOpenFilePicker(), showSaveFilePicker() and showDirectoryPicker() methods are together known as the native file system handle factories.

In Chrome this is currently implemented as a chooseFileSystemEntries method. Starting in Chrome 85 these new methods will also become available.

3.1. Native File System Permissions

The native file system query permission steps for an entry entry given a FileSystemHandlePermissionDescriptor descriptor and an environment settings object settings are:
  1. If descriptor.writable is true:

    1. Let readState be the result of running the query permission steps for entry given «[ "writable" → false ]» and settings.

    2. If readState is not "granted", return readState.

  2. If there was a previous invocation of this algorithm for the same entry, descriptor and settings, returning previousResult, and the UA has not received new information about the user’s intent since that invocation, return previousResult.

  3. Return whichever of the following options most accurately reflects the user’s intent for the calling algorithm:

    succeed without prompting the user

    "granted"

    show the user a prompt to decide whether to succeed

    "prompt"

    fail without prompting the user

    "denied"

The fact that the user picked the specific files returned by the native file system handle factories in a prompt should be treated by the user agent as the user intending to grant read access to the website for the returned files. As such, at the time the promise returned by one of the native file system handle factories resolves, the query permission steps for the returned entries given «[ "writable" → false ]» should return "granted".

Additionally for calls to {{showSaveFilePicker} the query permission steps for the returned entries given «[ "writable" → true ]» should also return "granted".

The native file system request permission steps for an entry entry given a FileSystemHandlePermissionDescriptor descriptor and an environment settings object settings are:
  1. Let status be the result of running the query permission steps for entry given descriptor and settings.

  2. If status is not "prompt" return.

  3. Let global be settings’s global object.

  4. If global is not a Window, return.

    Should this throw instead of returning silently?

  5. If global does not have transient activation, throw a NotAllowedError.

  6. If settings’s origin is not same origin with settings’s top-level origin, throw a NotAllowedError.

  7. Display a prompt to the user requesting access as described by descriptor to entry.

  8. Wait for the user to accept or reject the prompt. The user’s interaction may provide new information about the user’s intent for this descriptor and entry. Additionally if descriptor.writable is true, the user’s interaction may also provide new information about the user’s intent for the same entry with «[ "writable" → false ]».

Note: This is intentionally vague about the details of the permission UI and how the UA infers user intent. UAs should be able to explore a variety of UI approaches within this framework.

To verify that an environment is allowed to show a file picker, run these steps:
  1. If environment’s origin is an opaque origin, return a promise rejected with a SecurityError.

  2. If environment’s origin is not same origin with environment’s top-level origin, return a promise rejected with a SecurityError.

  3. Let global be environment’s global object.

  4. If global does not have transient activation, throw a SecurityError.

    Should this be SecurityError or NotAllowedError (and same question for the request permission steps checking for user activation)?

3.2. The showOpenFilePicker() method

[ handle ] = await window . showOpenFilePicker()
[ handle ] = await window . showOpenFilePicker({ multiple: false })

Shows a file picker that lets a user select a single existing file, returning a handle for the selected file.

handles = await window . showOpenFilePicker({ multiple: true })

Shows a file picker that lets a user select multiple existing files, returning handles for the selected files.

Additional options can be passed to showOpenFilePicker() to indicate the types of files the website wants the user to select. See § 3.4 FilePickerOptions.types for details.

The showOpenFilePicker(options) method, when invoked, must run these steps:
  1. Let accepts options be the result of processing accept types given options.

  2. Let environment be this’s relevant settings object.

  3. Let global be environment’s global object.

  4. Verify that environment is allowed to show a file picker.

  5. Let p be a new promise.

  6. Run the following steps in parallel:

    1. Optionally, wait until any prior execution of this algorithm has terminated.

    2. Display a prompt to the user requesting that the user pick some files. If options.multiple is false, there must be no more than one file selected; otherwise any number may be selected.

      The displayed prompt should let the user pick one of the accepts options to filter the list of displayed files. Exactly how this is implemented, and what this prompt looks like is left up to the user agent.

    3. Wait for the user to have made their selection.

    4. If the user dismissed the prompt without making a selection, reject p with an AbortError and abort.

    5. Let entries be a list of file entries representing the selected files or directories.

    6. Let result be a empty list.

    7. For each entry of entries:

      1. If entry is deemed too sensitive or dangerous to be exposed to this website by the user agent:

        1. Inform the user that the selected files or directories can’t be exposed to this website.

        2. At the discretion of the user agent, either go back to the beginning of these in parallel steps, or reject p with an AbortError and abort.

      2. Set entry’s query permission steps to the native file system query permission steps.

      3. Set entry’s request permission steps to the native file system request permission steps.

      4. Add a new FileSystemFileHandle associated with entry to result.

    8. Perform the activation notification steps in global’s browsing context.

      Note: This lets a website immediately perform operations on the returned handles that might require user activation, such as requesting more permissions.

    9. Resolve p with result.

  7. Return p.

3.3. The showSaveFilePicker() method

handle = await window . showSaveFilePicker( options )

Shows a file picker that lets a user select a single file, returning a handle for the selected file. The selected file does not have to exist already. If the selected file does not exist a new empty file is created before this method returns, otherwise the existing file is cleared before this method returned.

Additional options can be passed to showSaveFilePicker() to indicate the types of files the website wants the user to select. See § 3.4 FilePickerOptions.types for details.

The showSaveFilePicker(options) method, when invoked, must run these steps:
  1. Let accepts options be the result of processing accept types given options.

  2. Let environment be this’s relevant settings object.

  3. Let global be environment’s global object.

  4. Verify that environment is allowed to show a file picker.

  5. Let p be a new promise.

  6. Run the following steps in parallel:

    1. Optionally, wait until any prior execution of this algorithm has terminated.

    2. Display a prompt to the user requesting that the user pick exactly one file.

      The displayed prompt should let the user pick one of the accepts options to filter the list of displayed files. Exactly how this is implemented, and what this prompt looks like is left up to the user agent.

    3. Wait for the user to have made their selection.

    4. If the user dismissed the prompt without making a selection, reject p with an AbortError and abort.

    5. Let entry be a file entry representing the selected file.

    6. If entry is deemed too sensitive or dangerous to be exposed to this website by the user agent:

      1. Inform the user that the selected files or directories can’t be exposed to this website.

      2. At the discretion of the user agent, either go back to the beginning of these in parallel steps, or reject p with an AbortError and abort.

    7. Set entry’s query permission steps to the native file system query permission steps.

    8. Set entry’s request permission steps to the native file system request permission steps.

    9. Set entry’s binary data to an empty byte sequence.

    10. Set result to a new FileSystemFileHandle associated with entry.

    11. Perform the activation notification steps in global’s browsing context.

      Note: This lets a website immediately perform operations on the returned handles that might require user activation, such as requesting more permissions.

    12. Resolve p with result.

  7. Return p.

3.4. FilePickerOptions.types

The showOpenFilePicker(options) and showSaveFilePicker(options) methods accept a FilePickerOptions argument, which lets the website specify the types of files the file picker will let the user select.

Each entry in types specifies a single user selectable option for filtering the files displayed in the file picker.

Each option consists of an optional description and a number of MIME types and extensions (specified as a mapping of MIME type to a list of extensions). If no description is provided one will be generated.

In addition to complete MIME types, "" can be used as the subtype of a MIME type to match for example all image formats with "image/".

Websites should always provide both MIME types and file extensions for each option. On platforms that only use file extensions to describe file types user agents can match on the extensions, while on platforms that don’t use extensions, user agents can match on MIME type.

By default the file picker will also include an option to not apply any filter, letting the user select any file. Set excludeAcceptAllOption to true to not include this option in the file picker.

For example , the following options will let the user pick one of three different filter. One for text files (either plain text or HTML), one for images, and a third one that doesn’t apply any filter and lets the user select any file.

const options = {
  types: [
    {
      description: 'Text Files',
      accept: {
        'text/plain': ['txt', 'text'],
        'text/html': ['html', 'htm']
      }
    },
    {
      description: 'Images',
      accept: {
        'image/*': ['png', 'gif', 'jpeg', 'jpg']
      }
    }
  ],
};

On the other hand, the following example will only let the user select SVG files. The dialog will not show an option to not apply any filters.

const options = {
  types: [
    {
      accept: {
        'image/svg+xml': ['svg']
      }
    },
  ],
  excludeAcceptAllOption: true
};
To process accept types, given FilePickerOptions options, run these steps:
  1. Let accepts options be a empty list of pairs.

  2. For each type of options.types:

    1. Let description be type.description.

    2. For each type stringextensions of type.accept:

      1. Let parsedType be the result of parse a MIME type with typeString.

      2. If parsedType is failure, throw a TypeError.

      3. If parsedType’s parameters are not empty, throw a TypeError.

    3. Let filter be the following steps, given a filename (a string), and a type (a MIME type):

      1. For each type stringextensions of type.accept:

      2. Let parsedType be the result of parse a MIME type with typeString.

        1. If parsedType’s subtype is "*":

          1. If parsedType’s type is "*", return true.

          2. If parsedType’s type is type’s type, return true.

        2. parsedType’s essence is type’s essence, return true.

        3. For each extension of extensions:

          1. If filename ends with "." followed by extension, return true.

      3. Return false.

    4. If description is an empty string, set description to some user understandable string describing filter.

    5. Append description/filter to accepts options.

  3. If either accepts options is empty, or options.excludeAcceptAllOption is false:

    1. Let description be a user understandable string describing "all files".

      1. Let filter be an algorithm that returns true.

      2. Append description/filter to accepts options.

  4. If accepts options is empty, throw a TypeError.

  5. Return accepts options.

3.5. The showDirectoryPicker() method

handle = await window . showDirectoryPicker()

Shows a directory picker that lets the user select a single directory, returning a handle for the selected directory.

The showDirectoryPicker(options) method, when invoked, must run these steps:
  1. Let environment be this’s relevant settings object.

  2. Let global be environment’s global object.

  3. Verify that environment is allowed to show a file picker.

  4. Let p be a new promise.

  5. Run the following steps in parallel:

    1. Optionally, wait until any prior execution of this algorithm has terminated.

    2. Display a prompt to the user requesting that the user pick a directory.

    3. Wait for the user to have made their selection.

    4. If the user dismissed the prompt without making a selection, reject p with an AbortError and abort.

    5. Let entry be a directory entry representing the selected directory.

    6. If entry is deemed too sensitive or dangerous to be exposed to this website by the user agent:

      1. Inform the user that the selected files or directories can’t be exposed to this website.

      2. At the discretion of the user agent, either go back to the beginning of these in parallel steps, or reject p with an AbortError and abort.

    7. Set entry’s query permission steps to the native file system query permission steps.

    8. Set entry’s request permission steps to the native file system request permission steps.

    9. Set result to a new FileSystemDirectoryHandle associated with entry.

    10. Perform the activation notification steps in global’s browsing context.

      Note: This lets a website immediately perform operations on the returned handles that might require user activation, such as requesting more permissions.

      Rather than requiring the website to prompt separately for a writable directory, we should provide some kind of API to request a writable directory in one step. <https://github.com/wicg/native-file-system/issues/89>

    11. Resolve p with result.

  6. Return p.

4. Accessing the Sandboxed File System

4.1. Sandboxed File System Concepts

A bucket contains a sandboxed file system root, a directory entry.

The sandboxed file system root for one bucket must be completely separate from that of any other bucket.

Note: While user agents will typically implement this by persisting the contents of this sandboxed file system root 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 the sandboxed file system root exist.

Note: In Chrome this sandboxed file system root refers to the same storage as the temporary file system as used to be defined in File API: Directories and System.

The sandboxed file system root's query permission steps are the following:
  1. Return "granted".

4.2. The getOriginPrivateDirectory() method

[SecureContext]
partial interface mixin WindowOrWorkerGlobalScope {
  Promise<FileSystemDirectoryHandle> getOriginPrivateDirectory();
};

In Chrome this functionality is currently exposed as FileSystemDirectoryHandle.getSystemDirectory({type: "sandbox"}).

directoryHandle = await window . getOriginPrivateDirectory()

Returns the root directory of the sandboxed file system.

The getOriginPrivateDirectory() method, when invoked, must run these steps:
  1. Let environment be the current settings object.

  2. If environment’s origin is an opaque origin, return a promise rejected with a SecurityError.

  3. Let storage be environment’s origin's storage unit.

  4. Let bucket be storage’s bucket.

  5. Return a promise resolved with a new FileSystemDirectoryHandle, whose associated entry is bucket’s sandboxed file system root.

5. Privacy Considerations

This section is non-normative.

This API does not give websites any more read access to data than the existing <input type=file> and <input type=file webkitdirectory> APIs already do. Furthermore similarly to those APIs, all access to files and directories is explicitly gated behind a file or directory picker.

There are however several major privacy risks with this new API:

5.1. Users giving access to more, or more sensitive files than they intended.

This isn’t a new risk with this API, but user agents should try to make sure that users are aware of what exactly they’re giving websites access to. This is particularly important when giving access to a directory, where it might not be immediately clear to a user just how many files actually exist in that directory.

A related risk is having a user give access to particularly sensitive data. This could include some of a user agent’s configuration data, network cache or cookie store, or operating system configuration data such as password files. To protect against this, user agents are encouraged to restrict which directories a user is allowed to select in a directory picker, and potentially even restrict which files the user is allowed to select. This will make it much harder to accidentally give access to a directory that contains particularly sensitive data. Care must be taken to strike the right balance between restricting what the API can access while still having the API be useful. After all, this API intentionally lets the user use websites to interact with some of their most private personal data.

Examples of directories that user agents might want to restrict as being too sensitive or dangerous include:

5.2. Websites trying to use this API for tracking.

This API could be used by websites to track the user across clearing browsing data. This is because, in contrast with existing file access APIs, user agents are able to grant persistent access to files or directories and can re-prompt. In combination with the ability to write to files, websites will be able to persist an identifier on the users' disk. Clearing browsing data will not affect those files in any way, making these identifiers persist through those actions.

This risk is somewhat mitigated by the fact that clearing browsing data will also clear IndexedDB, so websites won’t have any handles to re-prompt for permission after browsing data was cleared. Furthermore user agents are encouraged to make it clear what files and directories a website has access to, and to automatically expire permission grants except for particularly well trusted origins (for example persistent permissions could be limited to "installed" web applications).

User agents also are encouraged to provide a way for users to revoke permissions granted. Clearing browsing data is expected to revoke all permissions as well.

5.3. First-party vs third-party contexts.

In third-party contexts (e.g. an iframe whose origin does not match that of the top-level frame) websites can’t gain access to data they don’t already have access to. This includes both getting access to new files or directories via the native file system handle factories, as well as requesting more permissions to existing handles via the requestPermission API.

Handles can also only be post-messaged to same-origin destinations. Attempts to send a handle to a cross-origin destination will result in a messageerror event.

6. Security Considerations

This section is non-normative.

This API gives websites the ability to modify existing files on disk, as well as write to new files. This has a couple of important security considerations:

6.1. Malware

This API could be used by websites to try to store and/or execute malware on the users system. To mitigate this risk, this API does not provide any way to mark files as executable (on the other hand files that are already executable likely remain that way, even after the files are modified through this API). Furthermore user agents are encouraged to apply things like Mark-of-the-Web to files created or modified by this API.

Finally, user agents are encouraged to verify the contents of files modified by this API via malware scans and safe browsing checks, unless some kind of external strong trust relation already exists. This of course has effects on the performance characteristics of this API.

6.2. Ransomware attacks

Another risk factor is that of ransomware attacks. The limitations described above regarding blocking access to certain sensitive directories helps limit the damage such an attack can do. Additionally user agents can grant write access to files at whatever granularity they deem appropriate.

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[ECMASCRIPT]
ECMAScript Language Specification. URL: https://tc39.es/ecma262/
[ENCODING]
Anne van Kesteren. Encoding Standard. Living Standard. URL: https://encoding.spec.whatwg.org/
[FILE-API]
Marijn Kruisselbrink; Arun Ranganathan. File API. 11 September 2019. WD. URL: https://www.w3.org/TR/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/
[MIMESNIFF]
Gordon P. Hemsley. MIME Sniffing Standard. Living Standard. URL: https://mimesniff.spec.whatwg.org/
[PERMISSIONS]
Mounir Lamouri; Marcos Caceres; Jeffrey Yasskin. Permissions. 25 September 2017. WD. URL: https://www.w3.org/TR/permissions/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[STREAMS]
Adam Rice; Domenic Denicola; 吉野剛史 (Takeshi Yoshino). Streams Standard. Living Standard. URL: https://streams.spec.whatwg.org/
[WebIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

Informative References

[ENTRIES-API]
File and Directory Entries API. cg-draft. URL: https://wicg.github.io/entries-api/
[FILE-SYSTEM-API]
Eric Uhrhane. File API: Directories and System. 24 April 2014. NOTE. URL: https://www.w3.org/TR/file-system-api/

IDL Index

dictionary FileSystemHandlePermissionDescriptor {
  boolean writable = false;
};

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

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

  Promise<boolean> isSameEntry(FileSystemHandle other);

  Promise<PermissionState> queryPermission(optional FileSystemHandlePermissionDescriptor descriptor = {});
  Promise<PermissionState> requestPermission(optional FileSystemHandlePermissionDescriptor descriptor = {});
};

dictionary FileSystemCreateWritableOptions {
  boolean keepExistingData = false;
};

[Exposed=(Window,Worker), SecureContext, Serializable]
interface FileSystemFileHandle : FileSystemHandle {
  Promise<File> getFile();
  Promise<FileSystemWritableFileStream> createWritable(optional FileSystemCreateWritableOptions options = {});
};

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<void> 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<void> write(FileSystemWriteChunkType data);
  Promise<void> seek(unsigned long long position);
  Promise<void> truncate(unsigned long long size);
};

dictionary FilePickerAcceptType {
    USVString description;
    record<USVString, sequence<USVString>> accept;
};

dictionary FilePickerOptions {
    sequence<FilePickerAcceptType> types;
    boolean excludeAcceptAllOption = false;
};

dictionary OpenFilePickerOptions : FilePickerOptions {
    boolean multiple = false;
};

dictionary SaveFilePickerOptions : FilePickerOptions {
};

dictionary DirectoryPickerOptions {
};

[SecureContext]
partial interface Window {
    Promise<sequence<FileSystemFileHandle>> showOpenFilePicker(optional OpenFilePickerOptions options = {});
    Promise<FileSystemFileHandle> showSaveFilePicker(optional SaveFilePickerOptions options = {});
    Promise<FileSystemDirectoryHandle> showDirectoryPicker(optional DirectoryPickerOptions options = {});
};

[SecureContext]
partial interface mixin WindowOrWorkerGlobalScope {
  Promise<FileSystemDirectoryHandle> getOriginPrivateDirectory();
};

Issues Index

TODO: Explain better how entries map to files on disk (multiple entries can map to the same file or directory on disk but an entry doesn’t have to map to any file on disk).
Figure out some way to integrate this better with the permissions API [permissions], for example by making the entry be a part of the PermissionDescriptor.
the currently described API here assumes a model where it is not possible to have a write-only handle. I.e. it is not possible to have or request write access without also having read access. There definitely are use cases for write-only handles (e.g. directory downloads), so we might have to reconsider this. <https://github.com/wicg/native-file-system/issues/119>
The reading and snapshotting behavior needs to be better specified in the [FILE-API] spec, for now this is kind of hand-wavy.
There has been some 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. <https://github.com/wicg/native-file-system/issues/67>
In the future we might want to add arguments to the async iterable declaration to support for example recursive iteration. <https://github.com/wicg/native-file-system/issues/173>
Better specify what possible exceptions this could throw. <https://github.com/wicg/native-file-system/issues/68>
Better specify what possible exceptions this could throw. <https://github.com/wicg/native-file-system/issues/68>
Better specify what possible exceptions this could throw. <https://github.com/wicg/native-file-system/issues/68>
Not clear if this should reject, and if it does, is this really the right error type? Chrome’s implementation is actually inconsistent about this rejecting or not.
Should this throw instead of returning silently?
Should this be SecurityError or NotAllowedError (and same question for the request permission steps checking for user activation)?
Rather than requiring the website to prompt separately for a writable directory, we should provide some kind of API to request a writable directory in one step. <https://github.com/wicg/native-file-system/issues/89>