File System Access

Abstract

This document defines a web platform API that enables developers to build

powerful web apps that interact with files on the user’s local device. It builds on File API for file reading capabilities, and adds new API surface to enable modifying files, as well as working with directories.

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

1. Let entry be desc.handle's entry.

2. If entry represents an entry in an origin private file system, this descriptor’s permission state must always be "granted".

3. Otherwise, if entry’s parent is not null, this descriptor’s permission state must be equal to the permission state for a descriptor with the same mode, and a handle representing entry’s parent.

4. Otherwise, if desc.mode is "readwrite":

   1. Let read state be the permission state for a descriptor with the same handle, but mode = "read".

   2. If read state is not "granted", this descriptor’s permission state must be equal to read state.

1. Let desc be a FileSystemPermissionDescriptor.

2. Set desc.name to "file-system".

3. Set desc.handle to handle.

4. Set desc.mode to mode.

5. Let status be the result of running create a PermissionStatus for desc.

6. Run the permission request algorithm for the "file-system" feature, given desc and status.

7. Return desc’s permission state.

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.

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.

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

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.

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

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.

1. Let result be a new promise.

2. Run the following steps in parallel:

   1. Let state be the result of querying file system permission given this and descriptor.mode.

   2. Resolve result with state.

3. Return result.

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.

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.

1. Let result be a new promise.

2. Run the following steps in parallel:

   1. Let state be the result of requesting file system permission given this and descriptor.mode. If that throws an exception, reject result with that exception and abort.

   2. Resolve result with state.

3. Return result.

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.

1. Let result be a new promise.

2. Run the following steps in parallel:

   1. Let permissionStatus be the result of querying file system permission given this and "read".

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

   3. Let entry be this’s 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. 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.

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 contain its old contents or it will contain whatever data was written through stream up until the stream has been closed.

This is typically implemented by writing data to a temporary file, and only replacing the file 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.

1. Let result be a new promise.

2. Run the following steps in parallel:

   1. Let permissionStatus be the result of requesting file system permission given this and "readwrite". If that throws an exception, reject result with that exception and abort.

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

   3. Let entry be this’s entry.

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

   5. If options.keepExistingData is true:

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

   6. Resolve result with stream.

3. Return result.

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.

1. Let permissionStatus be the result of querying file system permission given handle and "read".

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

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

1. Let promise be a new promise.

2. Let directory be handle’s entry.

3. Let permissionStatus be the result of querying file system permission given handle and "read".

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.

Returns a handle for a file named name in the directory represented by directoryHandle. If no such file exists, this rejects.

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

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. Let permissionStatus be the result of requesting file system permission given this and "readwrite". If that throws an exception, reject result with that exception and abort.

   4. Otherwise:

      1. Let permissionStatus be the result of querying file system permission given this and "read".

   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:

   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. [Issue #68]

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

3. Return result.

Returns a handle for a directory named name in the directory represented by directoryHandle. If no such directory exists, this rejects.

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

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. Let permissionStatus be the result of requesting file system permission given this and "readwrite". If that throws an exception, reject result with that exception and abort.

   4. Otherwise:

      1. Let permissionStatus be the result of querying file system permission given this and "read".

   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:

   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. [Issue #68]

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

3. Return result.

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.

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.

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. Let permissionStatus be the result of requesting file system permission given this and "readwrite". If that throws an exception, reject result with that exception and abort.

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

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

         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. [Issue #68]

         4. Resolve result with undefined.

   6. Reject result with a NotFoundError.

3. Return result.

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

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

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

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

This functionality can be useful if a web application shows a directory listing to highlight a file opened through a file picker in that directory listing.

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

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.

1. Let stream be a new FileSystemWritableFileStream in realm.

2. Set stream.[[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 the following steps:

   1. Let closeResult be a new promise.

   2. Run the following steps in parallel:

      1. Let permissionStatus be the permission state for a FileSystemPermissionDescriptor with handle representing stream.[[file]], and mode = "readwrite".

      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.

5. Let highWaterMark be 1.

6. Let sizeAlgorithm be an algorithm that returns 1.

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

8. Return stream.

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 permission state for a FileSystemPermissionDescriptor with handle representing stream.[[file]], and mode = "readwrite".

   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 data is a BufferSource, let dataBytes be a copy of data.

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

      8. Else:

         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.[[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.[[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. If the operations modifying stream.[[buffer]] in the previous steps failed due to exceeding the storage quota, reject p with a QuotaExceededError and abort, leaving stream.[[buffer]] unmodified.

          Note: Storage quota only applies to files stored in the origin private 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.[[seekOffset]] to writePosition + data.length.

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

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

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

      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.

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.

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.

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

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.

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.

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

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.

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.

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.

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. Extensions have to be strings that start with a "." and only contain valid suffix code points. Additionally extensions are limited to a length of 16 code points.

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

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 typeString → suffixes 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.

      4. If suffixes is a string:

         1. Validate a suffix given suffixes.

      5. Otherwise, for each suffix of suffixes:

         1. Validate a suffix given suffix.

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

      1. For each typeString → suffixes 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. If suffixes is a string, set suffixes to « suffixes ».

         4. For each suffix of suffixes:

            1. If filename ends with suffix, 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.

1. If suffix does not start with ".", throw a TypeError.

2. If suffix contains any code points that are not valid suffix code points, throw a TypeError.

3. If suffix ends with ".", throw a TypeError.

4. If suffix’s length is more than 16, throw a TypeError.

If neither of these options are specified, the user agent remembers the last directory a file or directory was picked from, and new pickers will start out in that directory. By specifying an id the user agent can remember different directories for different IDs (user agents will only remember directories for a limited number of IDs).

// If a mapping exists from this ID to a previousy picked directory, start in
// this directory. Otherwise, a mapping will be created from this ID to the
// directory of the resulting file picker invocation.
const options = {
  id: 'foo',
};

Specifying startIn as a FileSystemFileHandle will result in the dialog starting in the parent directory of that file, while passing in a FileSystemDirectoryHandle will result in the dialog to start in the passed in directory. These take precedence even if an explicit id is also passed in.

For example, given a FileSystemDirectoryHandle project_dir, the following will show a file picker that starts out in that directory:

// The picker will open to the directory of |project_dir| regardless of whether
// 'foo' has a valid mapping.
const options = {
  id: 'foo',
  startIn: |project_dir|,
};

The id and startIn fields control only the directory the picker opens to. In the above example, it cannot be assumed that the id 'foo' will map to the same directory as project_dir once the file picker operation has completed.

Specifying startIn as a WellKnownDirectory will result in the dialog starting in that directory, unless an explicit id was also passed in which has a mapping to a valid directory.

Below is an example of specifying both an id and startIn as a WellKnownDirectory. If there is an existing mapping from the given ID to a path, this mapping is used. Otherwise, the path suggested via the WellKnownDirectory is used.

// First time specifying the ID 'foo'. It is not mapped to a directory.
// The file picker will fall back to opening to the Downloads directory. TODO: link this.
const options = {
  id: 'foo',  // Unmapped.
  startIn: "downloads",  // Start here.
};

// Later...

// The ID 'foo' might or might not be mapped. For example, the mapping for this ID
// might have been evicted.
const options = {
  id: 'foo',  // Maybe mapped. If so, start here.
  startIn: "downloads",  // Otherwise, start here.
};

1. If id given, and is not a valid path id, throw a TypeError.

2. If id’s length is more than 32, throw a TypeError.

3. Let origin be environment’s origin.

4. If startIn is a FileSystemHandle:

   1. Let entry be startIn’s entry.

   2. If entry does not represent an entry in an origin private file system:

      1. If entry is a file entry, and a path on the local file system corresponding to the parent directory if entry can be determined, then return that path.

      2. If entry is a directory entry, and a path on the local file system corresponding to entry can be determined, then return that path.

5. If id is non-empty:

   1. If recently picked directory map[origin] exists:

      1. Let path map be recently picked directory map[origin].

      2. If path map[id] exists, then return path map[id].

6. If startIn is a WellKnownDirectory:

   1. Return a user agent defined path corresponding to the WellKnownDirectory value of startIn.

7. If id is not specified, or is an empty string:

   1. If recently picked directory map[origin] exists:

      1. Let path map be recently picked directory map[origin].

      2. If path map[""] exists, then return path map[""].

8. Return a default path in a user agent specific manner.

1. Let origin be environment’s origin.

2. If recently picked directory map[origin] does not exist, then set recently picked directory map[origin] to an empty path id map.

3. If id is not specified, let id be an empty string.

4. Set recently picked directory map[origin][id] to the path on the local file system corresponding to entry, if such a path can be determined.

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

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 and the directory in which the file picker will open. See § 3.2 File picker options for details.

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

2. Let accepts options be the result of processing accept types given options.

3. Let starting directory be the result of determining the directory the picker will start in given options.id, options.startIn and environment.

4. Let global be environment’s global object.

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

6. Let p be a new promise.

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

      When possible, this prompt should start out showing starting 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 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. Add a new FileSystemFileHandle associated with entry to result.

   8. Remember a picked directory given options.id, entries[0] and environment.

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

   10. Resolve p with result.

8. Return p.

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.

Shows a file picker with the suggested "README.md" file name pre-filled as the default file name to save as.

Additional options can be passed to showSaveFilePicker() to indicate the types of files the website wants the user to select and the directory in which the file picker will open. See § 3.2 File picker options for details.

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

2. Let accepts options be the result of processing accept types given options.

3. Let starting directory be the result of determining the directory the picker will start in given options.id, options.startIn and environment.

4. Let global be environment’s global object.

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

6. Let p be a new promise.

7. 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 implementation-defined. If accepts options are displayed in the UI, the selected option should also be used to suggest an extension to append to a user provided file name, but this is not required. In particular user agents are free to ignore potentially dangerous suffixes such as those ending in ".lnk" or ".local".

      When possible, this prompt should start out showing starting directory.

      If options.suggestedName is specified and not null, the file picker prompt will be pre-filled with the options.suggestedName as the default name to save as. The interaction between the suggestedName and accepts options is implementation-defined. If the suggestedName is deemed too dangerous, user agents should ignore or sanitize the suggested file name, similar to the sanitization done when fetching something as a download.

      Note: A user agent could for example pick whichever option in accepts options that matches suggestedName as the default filter.

   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 binary data to an empty byte sequence.

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

   9. Remember a picked directory given options.id, entry and environment.

   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.

   11. Resolve p with result.

8. Return p.

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

The id and startIn fields behave identically to the id and startIn fields, respectively. See § 3.2.2 Starting Directory for details on how to use these fields.

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

2. Let starting directory be the result of determining the directory the picker will start in given options.id, options.startIn and environment.

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

      When possible, this prompt should start out showing starting 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 result to a new FileSystemDirectoryHandle associated with entry.

   8. Remember a picked directory given options.id, entry and environment.

   9. 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. [Issue #89]

   10. Resolve p with result.

7. Return p.

Returns a FileSystemFileHandle object if the dragged item is a file and a FileSystemDirectoryHandle object if the dragged item is a directory.

The getAsFileSystemHandle() method steps are:

1. If the DataTransferItem object is not in the read/write mode or the read-only mode, return a promise resolved with null.

2. If the the drag data item kind is not File, then return a promise resolved with null.

3. Let p be a new promise.

4. Run the following steps in parallel:

   1. Let entry be the entry representing the dragged file or directory.

   2. If entry is a file entry:

      1. Let handle be a FileSystemFileHandle associated with entry.

   3. Else if entry is a directory entry:

      1. Let handle be a FileSystemDirectoryHandle associated with entry.

   4. Resolve p with entry.

5. Return p.

elem.addEventListener('dragover', (e) => {
  // Prevent navigation.
  e.preventDefault();
});

elem.addEventListener('drop', async (e) => {
  e.preventDefault();

  const fileHandlesPromises = [...e.dataTransfer.items]
    .filter(item => item.kind === 'file')
    .map(item => item.getAsFileSystemHandle());

  for await (const handle of fileHandlesPromises) {
    if (handle.kind === 'directory') {
      console.log(<code data-opaque bs-autolink-syntax='`Directory: ${handle.name}`'>Directory: ${handle.name}</code>);
    } else {
      console.log(<code data-opaque bs-autolink-syntax='`File: ${handle.name}`'>File: ${handle.name}</code>);
    }
  }
});

Returns the root directory of the origin private file system.

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.

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

   1. Let dir be a new directory entry.

   2. Set dir’s name to "".

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

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

4. Return a promise resolved with a new FileSystemDirectoryHandle, whose associated entry is map["root"].

Conformance

Document conventions

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:

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.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.