# File and Directory Entries API

## Draft Community Group Report, 1 January 1970

This version:
  https://wicg.github.io/entries-api/
Test Suite:
  https://github.com/web-platform-tests/wpt/tree/master/entries-api
Editor:
  Joshua Bell (Google Inc.)

Copyright © 1970 the Contributors to the File and Directory Entries API Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

## Abstract

This specification documents web browser support for file and directory upload by drag-and-drop operations. It introduces types representing directories with methods for asynchronous traversal, and extends `HTMLInputElement` and `DataTransferItem` [HTML].

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

This specification documents the types and operations made available by web browsers to script when a hierarchy of files and directories are dragged and dropped onto a page or selected using form elements, or equivalent user actions.

This is heavily based upon earlier drafts of [file-system-api] which defines similar types in the context of a sandboxed file system, including operations for creating and modifying files and directories, but which has not been broadly adopted by web browsers.

The APIs described by this document was initially implemented in Google Chrome. Other browsers (at this time: Edge, Firefox and Safari) are starting to support subsets of Chrome’s APIs and behavior. The intent of this document is to specify the common subset to ensure that the implementations are interoperable.

## 2. Concepts

### 2.1. Names and Paths

A name is a string which:

- does not contain '/' (U+002F SOLIDUS)

- does not contain NUL (U+0000)

- does not contain '\' (U+005C REVERSE SOLIDUS)

- is not '.' (U+002E FULL STOP)

- is not '..' (U+002E FULL STOP, U+002E FULL STOP)

A path segment is a name, '.' (U+002E FULL STOP) or '..' (U+002E FULL STOP, U+002E FULL STOP).

A relative path is a string consisting of one or more path segments joined by '/' (U+002F SOLIDUS) that does not start with '/' (U+002F SOLIDUS).

An absolute path is a string consisting of '/' (U+002F SOLIDUS) followed by zero or more path segments joined by '/' (U+002F SOLIDUS).

A path is either a relative path or an absolute path.

A valid path is a `USVString` which is a path.

### 2.2. Files and Directories

A file consists of binary data and a name (a non-empty name).

A directory consists of a name (a name) and an ordered list of members. Each member is either a file or a directory. Each member of a directory must have a distinct non-empty name.

A root directory is a directory that is not a member of a directory. A root directory's name is empty.

The parent of a file or directory is the directory it is a member of. A root directory has no parent.

EDITORIAL: Should directory be defined as a special type of file so that minimal changes are necessary in [HTML]?
In most cases, the files and directories selected by the user will be presented by the API as if contained by a virtual root that does not exist as an entity in the actual native file system backing the interaction with the API.

A file system consists of a name and a root which is an associated root directory. The name of a file system is a `USVString` which is implementation defined but is unique to the file system. A root directory is associated with exactly one file system.

Implementations could produce a name by generating a UUID for each file system instance with some fixed prefix and suffix strings applied. Authors using the API are adviised not to make assumptions about the structure or content of the names.

### 2.3. Entries

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

An entry has an name (a name) and a full path (an absolute path).

An entry also has a root, which is an associated root directory.

Entries are defined in terms of paths relative to a root directory to account for the fact that a native file system backing the interaction with the API could be modified asynchronously during operations such as enumerating the contents of a directory. Operations exposed on entries will produce errors in such cases where the paths no longer reference the same entity.

The file system of an entry is the file system associated with the entry's root.

### 2.4. Directory Reader

A directory reader consists of an associated directory entry, an associated directory (initially null), a reading flag (initially unset), a done flag (initially unset), and a reader error (initially null).

## 3. Algorithms

To resolve a relative path with abspath (an absolute path) and path (an absolute path, a relative path, or the empty string), run the following steps which return an absolute path:

1. If path is an absolute path, return path.

2. Let abspath segments be the result of strictly splitting abspath on '/' (U+002F SOLIDUS).

   The first string will be empty.

3. Let path segments be the result of strictly splitting path on '/' (U+002F SOLIDUS).

4. For each segment in path segments, switch on segment:

   empty string
     Continue.
   '.' (U+002E FULL STOP)
     Continue.
   '..' (U+002E FULL STOP, U+002E FULL STOP)
     Remove the last member of abspath segments unless it is the only member.
   Otherwise
     Append segment to abspath segments.

5. Return abspath segments joined by '/' (U+002F SOLIDUS).

To evaluate a path with directory (an root directory) and path (an absolute path), run the following steps which return a file, directory, or failure.

1. Let segments be the result of strictly splitting path on '/' (U+002F SOLIDUS).

2. Remove the first entry from segments.

   Since path was an absolute path, this first entry will always be empty.

3. For each segment in segments, switch on segment:

   empty string
     Continue.
   '.' (U+002E FULL STOP)
     Continue.
   '..' (U+002E FULL STOP, U+002E FULL STOP)
     Let directory be directory’s parent, or directory if none.
   Otherwise
     Run these substeps:

     1. Let item be the member of directory with name equal to segment, or return failure if none.

     2. If segment is the last item in segments, return item.

     3. If item is a file, return failure.

     4. Let directory be item.

## 4. The `File` Interface

EDITORIAL: This section should be merged into [FileAPI] once it is complete.

    partial interface File {
        readonly attribute USVString webkitRelativePath;
    };

The `webkitRelativePath` attribute of the `File` interface must return the relative path of the file, or the empty string if not specified.

## 5. HTML: Forms

EDITORIAL: This section should be merged into [HTML] once it is complete. Sections such as the steps to construct the form data set need to be extended to include the `webkitRelativePath` property.

    partial interface HTMLInputElement {
        attribute boolean webkitdirectory;
        readonly attribute FrozenArray<FileSystemEntry> webkitEntries;
    };

When an `input` element’s `type` attribute is in the File Upload state, the rules in this section apply.

The `webkitdirectory` attribute is a boolean attribute that indicates whether the user is to be allowed to select a directory rather than a file or files. When specified, the behavior on the selection of a directory is as if all files with that directory as an ancestor were selected. In addition, the `webkitRelativePath` property of each `File` is set to a relative path starting from (and including) the selected directory to the file.

Given the following directory structure:

    documents/
      to_upload/
        a/
          b/
            1.txt
            2.txt
          3.txt
      not_uploaded.txt

If the `to_upload` directory was selected, then `files` would include:

- An entry with `name` == "`1.txt`" and `webkitRelativePath` == "`to_upload/a/b/1.txt`"

- An entry with `name` == "`2.txt`" and `webkitRelativePath` == "`to_upload/a/b/2.txt`"

- An entry with `name` == "`3.txt`" and `webkitRelativePath` == "`to_upload/a/3.txt`"

A user agent could represent any hierarchical data as directories during a selection operation. For example, on a device that does not expose a native file system directly to the user, photo albums could be presented as directories if `"image/*"` is specified for the `accept` attribute.
Inspecting the `webkitRelativePath` properties after a directory is selected with an `input` element:

      <input id=b type=file webkitdirectory>

      document.querySelector('#b').addEventListener('change', e => {
        for (file entry of e.target.files)
          console.log(file.name, file.webkitRelativePath);
      });

The `webkitEntries` IDL attribute allows scripts to access the element’s selected entries. On getting, if the IDL attribute applies, it must return an array of `FileSystemEntry` objects that represent the current selected files (including directories, if permitted). If the IDL attribute does not apply, then it must instead return null.

Enumerating entries using `webkitEntries`:

      <input id=a type=file multiple>

      document.querySelector('#a').addEventListener('change', e => {
        for (const entry of e.target.webkitEntries)
          handleEntry(entry);
      });

INTEROP: In Chrome, `webkitEntries` is only populated as the result of a drag-and-drop operation, not when the element is clicked. Should we fix this so it is always populated?
INTEROP: In Chrome, if `webkitdirectory` is specified on a `HTMLInputElement`, `webkitEntries` is not populated; the `files` collection and `webkitRelativePath` properties must be used instead to reconstruct the directory structure. Should we fix this so it is always populated?

## 6. HTML: Drag and drop

EDITORIAL: This section should be merged into [HTML] once it is complete.

During a drag-and-drop operation, file and directory items are associated with entries. Each entry is a member of a root directory unique to the drag data store.

Additionally, each directory item is represented in the drag data store item list as a File. If it is accessed via `getAsFile()` a zero-length `File` is returned.

A user agent could represent any hierarchical data as files and directories during a drag-and-drop operation. For example, audio data stored in a relational database with separate tables for albums metadata and blobs for tracks could be exposed to script as directories and files when dragged from a media player application.

    partial interface DataTransferItem {
        FileSystemEntry? webkitGetAsEntry();
    };

The `webkitGetAsEntry()` method must run the following steps when invoked:

1. If the `DataTransferItem` object is not in the read/write mode or the read-only mode, return null and abort these steps.

2. If the drag data item kind is not File, then return null and abort these steps.

3. Return a new `FileSystemEntry` object representing the entry.

Handling drag and drop of files and directories:

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

      // Process all of the items.
      for (const item of e.dataTransfer.items) {
        // kind will be 'file' for file/directory entries.
        if (item.kind === 'file') {
          const entry = item.webkitGetAsEntry();
          handleEntry(entry);
        }
      }
    });

## 7. Files and Directories

WEB COMPAT: The legacy `TypeMismatchError` has been replaced in most specifications by `TypeError`, but the name differs. Is it compatible to switch here as well?

    callback ErrorCallback = void (DOMException err);

An `ErrorCallback` function is used for operations that may return an error asynchronously.

### 7.1. The `FileSystemEntry` Interface

    [Exposed=Window]
    interface FileSystemEntry {
        readonly attribute boolean isFile;
        readonly attribute boolean isDirectory;
        readonly attribute USVString name;
        readonly attribute USVString fullPath;
        readonly attribute FileSystem filesystem;

        void getParent(optional FileSystemEntryCallback successCallback,
                       optional ErrorCallback errorCallback);
    };

An `FileSystemEntry` has an associated entry.

The `isFile` attribute of the `FileSystemEntry` interface must return true if the entry is a file entry and false otherwise.

The `isDirectory` attribute of the `FileSystemEntry` interface must return true if the entry is a directory entry and false otherwise.

The `name` attribute of the `FileSystemEntry` interface must return the name of the entry.

The `fullPath` attribute of the `FileSystemEntry` interface must return the full path of the entry.

The `filesystem` attribute of the `FileSystemEntry` interface must return the file system of the entry.

The `getParent(successCallback, errorCallback)` method, when invoked, must run the following steps:

1. Queue a task to perform the following substeps:

   1. Let path be the result of running the steps to resolve a relative path with the entry's full path and '..'.

   2. Let item be the result of running the steps to evaluate a path with the entry's root and path.

   3. If item is failure, invoke errorCallback (if given) with a newly created "`NotFoundError`" `DOMException`, and terminate these steps.

   4. Let entry be a new directory entry with item’s name as name and path as full path.

   5. Invoke successCallback with a new `FileSystemDirectoryEntry` object associated with entry.

An error is possible if files have been modified on disk since the `FileSystemEntry` was created.
Handling an entry:

    function handleEntry(entry) {
      console.log('name: ' + entry.name);
      console.log('path: ' + entry.fullPath);
      if (entry.isFile) {
        console.log('... is a file');
      } else if (entry.isDirectory) {
        console.log('... is a directory');
      }
    }

Helper function to adapt `getParent()` for use with Promises [ECMA-262]:

    function getParentAsPromise(entry) {
      return new Promise((resolve, reject) => {
        entry.getParent(resolve, reject);
      });
    }

### 7.2. The `FileSystemDirectoryEntry` Interface

    [Exposed=Window]
    interface FileSystemDirectoryEntry : FileSystemEntry {
        FileSystemDirectoryReader createReader();
        void getFile(optional USVString? path,
                     optional FileSystemFlags options = {},
                     optional FileSystemEntryCallback successCallback,
                     optional ErrorCallback errorCallback);
        void getDirectory(optional USVString? path,
                          optional FileSystemFlags options = {},
                          optional FileSystemEntryCallback successCallback,
                          optional ErrorCallback errorCallback);
    };

    dictionary FileSystemFlags {
        boolean create = false;
        boolean exclusive = false;
    };

    callback FileSystemEntryCallback = void (FileSystemEntry entry);

The `create` member of `FileSystemFlags` and the associated behavior are included for compatibility with existing implementations, even though there is no useful behavior when the flag is specified. Similarly, the `exclusive` member is not explicitly referenced, but the binding behavior is observable from script if an object with a getter is passed.

A `FileSystemDirectoryEntry`'s associated entry is a directory entry.

The `createReader()` method, when invoked, must run the following steps:

1. Let reader be a new directory reader associated with the directory entry's directory.

2. Return a newly created `FileSystemDirectoryReader` object associated with reader.

The `getFile(path, options, successCallback, errorCallback)` method, when invoked, must run the following steps:

1. Queue a task to run the following substeps:

   1. If path is undefined or null let path be the empty string.

   2. If path is not a valid path, invoke errorCallback (if given) with a newly created "`TypeMismatchError`" `DOMException`, and terminate these steps.

   3. If options’s `create` member is true, invoke errorCallback (if given) with a newly created "`SecurityError`" `DOMException`, and terminate these steps.

   4. Let path be the result of running the steps to resolve a relative path with the directory entry's full path and path.

   5. Let item be the result of running the steps to evaluate a path with the directory entry's root and path.

   6. If item is failure, invoke errorCallback (if given) with a newly created "`NotFoundError`" `DOMException`, and terminate these steps.

   7. If item is not a file, invoke errorCallback (if given) with a newly created "`TypeMismatchError`" `DOMException`, and terminate these steps.

   8. Let entry be a new file entry with item’s name as name and path as full path.

   9. Invoke successCallback (if given) with a new `FileSystemFileEntry` object associated with entry.

The `getDirectory(path, options, successCallback, errorCallback)` method, when invoked, must run the following steps:

1. Queue a task to run the following substeps:

   1. If path is undefined or null let path be the empty string.

   2. If path is not a valid path, invoke errorCallback (if given) with a newly created "`TypeMismatchError`" `DOMException`, and terminate these steps.

   3. If options’s `create` member is true, invoke errorCallback (if given) with a newly created "`SecurityError`" `DOMException`, and terminate these steps.

   4. Let path be the result of running the steps to resolve a relative path with the directory entry's full path and path.

   5. Let item be the result of running the steps to evaluate a path with the directory entry's root and path.

   6. If item is failure, invoke errorCallback (if given) with a newly created "`NotFoundError`" `DOMException`, and terminate these steps.

   7. If item is not a directory, invoke errorCallback (if given) with a newly created "`TypeMismatchError`" `DOMException`, and terminate these steps.

   8. Let entry be a new directory entry with item’s name as name and path as full path.

   9. invoke successCallback (if given) with a new `FileSystemDirectoryEntry` associated with entry.

Helper functions to adapt `getFile()` and `getDirectory()` for use with Promises [ECMA-262]:

    function getFileAsPromise(entry, path) {
      return new Promise((resolve, reject) => {
        entry.getFile(path, {}, resolve, reject);
      });
    }
    function getDirectoryAsPromise(entry, path) {
      return new Promise((resolve, reject) => {
        entry.getDirectory(path, {}, resolve, reject);
      });
    }

### 7.3. The `FileSystemDirectoryReader` Interface

    [Exposed=Window]
    interface FileSystemDirectoryReader {
        void readEntries(FileSystemEntriesCallback successCallback,
                         optional ErrorCallback errorCallback);
    };
    callback FileSystemEntriesCallback = void (sequence<FileSystemEntry> entries);

A `FileSystemDirectoryReader` has an associated directory reader.

The `readEntries(successCallback, errorCallback)` method, when invoked, must run the following steps:

1. If the directory reader's reading flag is set, queue a task to invoke errorCallback with a newly created "`InvalidStateError`" `DOMException`, and terminate these steps.

2. If the directory reader's reader error is not null, queue a task to invoke errorCallback (if given) with reader error, and terminate these steps.

3. If the directory reader's done flag is set, queue a task to invoke successCallback with an empty sequence and terminate these steps.

4. Set the directory reader's reading flag.

5. Queue a task to perform the following substeps:

   1. Clear the directory reader's reading flag.

   2. Let dir be the directory reader's directory.

   3. If dir is null, run these substeps:

      1. Let dir be the result of running the steps to evaluate a path with the entry's root and full path.

      2. If dir is failure, set the directory reader's reader error to a newly created "`NotFoundError`" `DOMException`, invoke errorCallback (if given) with reader error, and terminate these steps.

      3. Set the directory reader's directory to dir.

   4. Let entries be a non-zero number of entries from the dir that have not yet been produced by this directory reader, if any.

   5. If the previous step failed (for example, the directory was deleted or permission is denied), then set the directory reader's reader error to an appropriate `DOMException`, invoke errorCallback (if given) with reader error, and terminate these steps.

   6. If entries is empty, set the directory reader's done flag.

   7. invoke successCallback with entries.

Enumerating a directory:

    let reader = dirEntry.createReader();
    let doBatch = function() {

        // Read a batch.
        reader.readEntries(entries => {

          // Complete?
          if (entries.length === 0) {
            return;
          }

          // Process the batch.
          entries.forEach(handleEntry);

          // Read the next batch.
          doBatch();

        }, error => console.warn(error));
      };

    // Start reading
    doBatch();

Helper function to adapt `FileSystemDirectoryReader` for use with Promises [ECMA-262]:

    function getEntriesAsPromise(dirEntry) {
      return new Promise((resolve, reject) => {
        const result = [];
        const reader = dirEntry.createReader();
        const doBatch = () => {
          reader.readEntries(entries => {
            if (entries.length > 0) {
              entries.forEach(e => result.push(e));
              doBatch();
            } else {
              resolve(result);
            }
          }, reject);
        };
        doBatch();
      });
    }

Helper function to adapt `FileSystemDirectoryReader` for use with AsyncIterators [ECMA-262]:

    async function* getEntriesAsAsyncIterator(dirEntry) {
      const reader = dirEntry.createReader();
      const getNextBatch = () => new Promise((resolve, reject) => {
        reader.readEntries(resolve, reject);
      });

      do {
        const entries = await getNextBatch();
        for (const entry of entries) {
          yield entry;
        }
      } while (entries.length > 0);
    }

This allows for ordered asynchronous traversal of a directory tree using `for-await-of`:

    async function show(entry) {
      console.log(entry.fullPath);
      if (entry.isDirectory) {
        for await (const e of getEntriesAsAsyncIterator(entry))
          await show(e);
      }
    }

### 7.4. The `FileSystemFileEntry` Interface

    [Exposed=Window]
    interface FileSystemFileEntry : FileSystemEntry {
        void file(FileCallback successCallback,
                  optional ErrorCallback errorCallback);
    };
    callback FileCallback = void (File file);

A `FileSystemFileEntry`'s associated entry is a file entry.

The `file(successCallback, errorCallback)` method, when invoked, must run the following steps:

1. Queue a task to perform the following substeps:

   1. Let item be the result of running the steps to evaluate a path with the file entry's root and full path.

   2. If item is failure, invoke errorCallback (if given) with a newly created "`NotFoundError`" `DOMException`, and terminate these steps.

   3. If item is a directory, invoke errorCallback (if given) with a newly created "`TypeMismatchError`" `DOMException`, and terminate these steps.

   4. invoke successCallback with a new `File` object representing item.

Read the contents of a dropped file using `FileReader`:

    function readFileEntry(entry) {
      entry.file(file => {
        const reader = new FileReader();
        reader.readAsText(file);
        reader.onerror = error => console.warn(error);
        reader.onload = () => {
          console.log(reader.result);
        };
      }, error => console.warn(error));
    }

Helper function to adapt `file()` for use with Promises [ECMA-262]:

    function fileAsPromise(entry) {
      return new Promise((resolve, reject) => {
        entry.file(resolve, reject);
      });
    }

### 7.5. The `FileSystem` Interface

    [Exposed=Window]
    interface FileSystem {
        readonly attribute USVString name;
        readonly attribute FileSystemDirectoryEntry root;
    };

A `FileSystem` has an associated file system.

The `name` attribute of the `FileSystem` interface must return the name of the file system.

The `root` attribute of the `FileSystem` interface must return a `FileSystemDirectoryEntry` associated with the root of the file system.

## 8. Acknowledgements

This specification is based heavily on the work of Eric Uhrhane in [file-system-api], which introduced the `FileSystemEntry` types.

Thanks to Tab Atkins, Jr. for creating and maintaining Bikeshed, the specification authoring tool used to create this document.

And thanks to Ali Alabbas, Philip Jägenstedt, Marijn Kruisselbrink, Olli Pettay, and Kent Tamura for suggestions, reviews, and other feedback.

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

- absolute path, in §2.1
- create, in §7.2
- createReader(), in §7.2
- directory, in §2.2
- directory entry, in §2.3
- directory reader, in §2.4
- done flag, in §2.4
- entry, in §2.3
- ErrorCallback, in §7
- evaluate a path, in §3
- exclusive, in §7.2
- file, in §2.2
- FileCallback, in §7.4
- file entry, in §2.3
- file(successCallback), in §7.4
- file(successCallback, errorCallback), in §7.4
- file system
  - definition of, in §2.2
  - dfn for entry, in §2.3
- FileSystem, in §7.5
- filesystem, in §7.1
- FileSystemDirectoryEntry, in §7.2
- FileSystemDirectoryReader, in §7.3
- FileSystemEntriesCallback, in §7.3
- FileSystemEntry, in §7.1
- FileSystemEntryCallback, in §7.2
- FileSystemFileEntry, in §7.4
- FileSystemFlags, in §7.2
- full path, in §2.3
- fullPath, in §7.1
- getDirectory(), in §7.2
- getDirectory(path), in §7.2
- getDirectory(path, options), in §7.2
- getDirectory(path, options, successCallback), in §7.2
- getDirectory(path, options, successCallback, errorCallback), in §7.2
- getFile(), in §7.2
- getFile(path), in §7.2
- getFile(path, options), in §7.2
- getFile(path, options, successCallback), in §7.2
- getFile(path, options, successCallback, errorCallback), in §7.2
- getParent(), in §7.1
- getParent(successCallback), in §7.1
- getParent(successCallback, errorCallback), in §7.1
- isDirectory, in §7.1
- isFile, in §7.1
- name
  - attribute for FileSystem, in §7.5
  - attribute for FileSystemEntry, in §7.1
  - definition of, in §2.1
  - dfn for directory, in §2.2
  - dfn for entry, in §2.3
  - dfn for file, in §2.2
  - dfn for file system, in §2.2
- parent, in §2.2
- path, in §2.1
- path segment, in §2.1
- readEntries(successCallback), in §7.3
- readEntries(successCallback, errorCallback)
  - method for FileSystemDirectoryEntry, in §7.3
  - method for FileSystemDirectoryReader, in §7.3
- reader error, in §2.4
- reading flag, in §2.4
- relative path, in §2.1
- resolve a relative path, in §3
- root
  - attribute for FileSystem, in §7.5
  - dfn for entry, in §2.3
  - dfn for file system, in §2.2
- root directory, in §2.2
- valid path, in §2.1
- webkitdirectory, in §5
- webkitEntries, in §5
- webkitGetAsEntry(), in §6
- webkitRelativePath, in §4

https://tc39.github.io/ecma262/#sec-asynciterator-interface Referenced in:

- 7.3. The FileSystemDirectoryReader Interface

https://tc39.github.io/ecma262/#sec-promise-objects Referenced in:

- 7.1. The FileSystemEntry Interface
- 7.2. The FileSystemDirectoryEntry Interface
- 7.3. The FileSystemDirectoryReader Interface
- 7.4. The FileSystemFileEntry Interface

https://w3c.github.io/FileAPI/#dfn-file Referenced in:

- 4. The File Interface (2) (3)
- 5. HTML: Forms
- 6. HTML: Drag and drop
- 7.4. The FileSystemFileEntry Interface (2)

https://w3c.github.io/FileAPI/#dfn-filereader Referenced in:

- 7.4. The FileSystemFileEntry Interface

https://w3c.github.io/FileAPI/#dfn-name Referenced in:

- 5. HTML: Forms (2) (3)

https://html.spec.whatwg.org/multipage/dnd.html#datatransferitem Referenced in:

- Unnumbered Section
- 6. HTML: Drag and drop (2)

https://html.spec.whatwg.org/multipage/input.html#htmlinputelement Referenced in:

- Unnumbered Section
- 5. HTML: Forms (2)

https://html.spec.whatwg.org/multipage/input.html#dom-input-accept Referenced in:

- 5. HTML: Forms

https://html.spec.whatwg.org/multipage/interaction.html#the-drag-data-item-kind Referenced in:

- 6. HTML: Drag and drop

https://html.spec.whatwg.org/multipage/interaction.html#drag-data-store Referenced in:

- 6. HTML: Drag and drop

https://html.spec.whatwg.org/multipage/interaction.html#drag-data-store-item-list Referenced in:

- 6. HTML: Drag and drop

https://html.spec.whatwg.org/multipage/forms.html#file-upload-state-(type=file)Referenced in:

- 5. HTML: Forms

https://html.spec.whatwg.org/multipage/input.html#dom-input-files Referenced in:

- 5. HTML: Forms (2)

https://html.spec.whatwg.org/multipage/dnd.html#dom-datatransferitem-getasfile Referenced in:

- 6. HTML: Drag and drop

https://html.spec.whatwg.org/multipage/input.html#the-input-element Referenced in:

- 5. HTML: Forms (2)

https://html.spec.whatwg.org/multipage/webappapis.html#queue-a-task Referenced in:

- 7.1. The FileSystemEntry Interface
- 7.2. The FileSystemDirectoryEntry Interface (2)
- 7.3. The FileSystemDirectoryReader Interface (2) (3) (4)
- 7.4. The FileSystemFileEntry Interface

https://html.spec.whatwg.org/multipage/interaction.html#concept-dnd-ro Referenced in:

- 6. HTML: Drag and drop

https://html.spec.whatwg.org/multipage/interaction.html#concept-dnd-rw Referenced in:

- 6. HTML: Drag and drop

https://html.spec.whatwg.org/multipage/forms.html#concept-input-type-file-selected Referenced in:

- 5. HTML: Forms

https://html.spec.whatwg.org/multipage/input.html#attr-input-type Referenced in:

- 5. HTML: Forms

https://infra.spec.whatwg.org/#strictly-split Referenced in:

- 3. Algorithms (2) (3)

https://heycam.github.io/webidl/#idl-DOMException Referenced in:

- 7. Files and Directories
- 7.1. The FileSystemEntry Interface
- 7.2. The FileSystemDirectoryEntry Interface (2) (3) (4) (5) (6) (7) (8)
- 7.3. The FileSystemDirectoryReader Interface (2) (3)
- 7.4. The FileSystemFileEntry Interface (2)

https://heycam.github.io/webidl/#Exposed Referenced in:

- 7.1. The FileSystemEntry Interface
- 7.2. The FileSystemDirectoryEntry Interface
- 7.3. The FileSystemDirectoryReader Interface
- 7.4. The FileSystemFileEntry Interface
- 7.5. The FileSystem Interface

https://heycam.github.io/webidl/#invalidstateerror Referenced in:

- 7.3. The FileSystemDirectoryReader Interface

https://heycam.github.io/webidl/#notfounderror Referenced in:

- 7.1. The FileSystemEntry Interface
- 7.2. The FileSystemDirectoryEntry Interface (2)
- 7.3. The FileSystemDirectoryReader Interface
- 7.4. The FileSystemFileEntry Interface

https://heycam.github.io/webidl/#securityerror Referenced in:

- 7.2. The FileSystemDirectoryEntry Interface (2)

https://heycam.github.io/webidl/#exceptiondef-typeerror Referenced in:

- 7. Files and Directories

https://heycam.github.io/webidl/#typemismatcherror Referenced in:

- 7. Files and Directories
- 7.2. The FileSystemDirectoryEntry Interface (2) (3) (4)
- 7.4. The FileSystemFileEntry Interface

https://heycam.github.io/webidl/#idl-USVString Referenced in:

- 2.1. Names and Paths
- 2.2. Files and Directories
- 4. The File Interface
- 7.1. The FileSystemEntry Interface (2)
- 7.2. The FileSystemDirectoryEntry Interface (2)
- 7.5. The FileSystem Interface

https://heycam.github.io/webidl/#idl-boolean Referenced in:

- 5. HTML: Forms
- 7.1. The FileSystemEntry Interface (2)
- 7.2. The FileSystemDirectoryEntry Interface (2)

https://heycam.github.io/webidl/#dfn-create-exception Referenced in:

- 7.1. The FileSystemEntry Interface
- 7.2. The FileSystemDirectoryEntry Interface (2) (3) (4) (5) (6) (7) (8)
- 7.3. The FileSystemDirectoryReader Interface (2)
- 7.4. The FileSystemFileEntry Interface (2)

https://heycam.github.io/webidl/#invoke-a-callback-function Referenced in:

- 7.1. The FileSystemEntry Interface (2)
- 7.2. The FileSystemDirectoryEntry Interface (2) (3) (4) (5) (6) (7) (8) (9) (10)
- 7.3. The FileSystemDirectoryReader Interface (2) (3) (4) (5) (6)
- 7.4. The FileSystemFileEntry Interface (2) (3)

### Terms defined by reference

- [ecma262] defines the following terms:
  - asynciterator
  - promise
- [FileAPI] defines the following terms:
  - File
  - FileReader
  - name
- [HTML] defines the following terms:
  - DataTransferItem
  - HTMLInputElement
  - accept
  - drag data item kind
  - drag data store
  - drag data store item list
  - file upload
  - files
  - getAsFile()
  - input
  - queue a task
  - read-only mode
  - read/write mode
  - selected files
  - type
- [INFRA] defines the following terms:
  - strictly split
- [WebIDL] defines the following terms:
  - DOMException
  - Exposed
  - InvalidStateError
  - NotFoundError
  - SecurityError
  - TypeError
  - TypeMismatchError
  - USVString
  - boolean
  - created
  - invoke

## References

### Normative References

[FileAPI]
  Marijn Kruisselbrink; Arun Ranganathan. File API. 31 May 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/
[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
[WebIDL]
  Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

### Informative References

[ECMA-262]
  ECMAScript Language Specification. URL: https://tc39.github.io/ecma262/
[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

    partial interface File {
        readonly attribute USVString webkitRelativePath;
    };

    partial interface HTMLInputElement {
        attribute boolean webkitdirectory;
        readonly attribute FrozenArray<FileSystemEntry> webkitEntries;
    };

    partial interface DataTransferItem {
        FileSystemEntry? webkitGetAsEntry();
    };

    callback ErrorCallback = void (DOMException err);

    [Exposed=Window]
    interface FileSystemEntry {
        readonly attribute boolean isFile;
        readonly attribute boolean isDirectory;
        readonly attribute USVString name;
        readonly attribute USVString fullPath;
        readonly attribute FileSystem filesystem;

        void getParent(optional FileSystemEntryCallback successCallback,
                       optional ErrorCallback errorCallback);
    };

    [Exposed=Window]
    interface FileSystemDirectoryEntry : FileSystemEntry {
        FileSystemDirectoryReader createReader();
        void getFile(optional USVString? path,
                     optional FileSystemFlags options = {},
                     optional FileSystemEntryCallback successCallback,
                     optional ErrorCallback errorCallback);
        void getDirectory(optional USVString? path,
                          optional FileSystemFlags options = {},
                          optional FileSystemEntryCallback successCallback,
                          optional ErrorCallback errorCallback);
    };

    dictionary FileSystemFlags {
        boolean create = false;
        boolean exclusive = false;
    };

    callback FileSystemEntryCallback = void (FileSystemEntry entry);

    [Exposed=Window]
    interface FileSystemDirectoryReader {
        void readEntries(FileSystemEntriesCallback successCallback,
                         optional ErrorCallback errorCallback);
    };
    callback FileSystemEntriesCallback = void (sequence<FileSystemEntry> entries);

    [Exposed=Window]
    interface FileSystemFileEntry : FileSystemEntry {
        void file(FileCallback successCallback,
                  optional ErrorCallback errorCallback);
    };
    callback FileCallback = void (File file);

    [Exposed=Window]
    interface FileSystem {
        readonly attribute USVString name;
        readonly attribute FileSystemDirectoryEntry root;
    };

## Issues Index

EDITORIAL: Should directory be defined as a special type of file so that minimal changes are necessary in [HTML]? ↵
EDITORIAL: This section should be merged into [FileAPI] once it is complete. ↵
EDITORIAL: This section should be merged into [HTML] once it is complete. Sections such as the steps to construct the form data set need to be extended to include the `webkitRelativePath` property. ↵
INTEROP: In Chrome, `webkitEntries` is only populated as the result of a drag-and-drop operation, not when the element is clicked. Should we fix this so it is always populated? ↵
INTEROP: In Chrome, if `webkitdirectory` is specified on a `HTMLInputElement`, `webkitEntries` is not populated; the `files` collection and `webkitRelativePath` properties must be used instead to reconstruct the directory structure. Should we fix this so it is always populated? ↵
EDITORIAL: This section should be merged into [HTML] once it is complete. ↵
WEB COMPAT: The legacy `TypeMismatchError` has been replaced in most specifications by `TypeError`, but the name differs. Is it compatible to switch here as well? ↵
#name Referenced in:

- 2.1. Names and Paths
- 2.2. Files and Directories (2) (3) (4)
- 2.3. Entries
- 3. Algorithms

#path-segment Referenced in:

- 2.1. Names and Paths (2)

#relative-path Referenced in:

- 2.1. Names and Paths
- 3. Algorithms
- 4. The File Interface
- 5. HTML: Forms

#absolute-path Referenced in:

- 2.1. Names and Paths
- 2.3. Entries
- 3. Algorithms (2) (3) (4) (5) (6)

#path Referenced in:

- 2.1. Names and Paths
- 2.3. Entries (2)

#valid-path Referenced in:

- 7.2. The FileSystemDirectoryEntry Interface (2)

#file Referenced in:

- 2.2. Files and Directories (2) (3)
- 3. Algorithms (2)
- 6. HTML: Drag and drop
- 7.2. The FileSystemDirectoryEntry Interface

#file-name Referenced in:

- 7.2. The FileSystemDirectoryEntry Interface

#directory Referenced in:

- 2.2. Files and Directories (2) (3) (4) (5) (6) (7)
- 2.4. Directory Reader
- 3. Algorithms
- 6. HTML: Drag and drop (2)
- 7.2. The FileSystemDirectoryEntry Interface (2)
- 7.3. The FileSystemDirectoryReader Interface (2) (3)
- 7.4. The FileSystemFileEntry Interface

#directory-name Referenced in:

- 7.1. The FileSystemEntry Interface
- 7.2. The FileSystemDirectoryEntry Interface

#root-directory Referenced in:

- 2.2. Files and Directories (2) (3) (4)
- 2.3. Entries (2)
- 3. Algorithms
- 6. HTML: Drag and drop

#parent Referenced in:

- 2.2. Files and Directories
- 3. Algorithms

#file-system Referenced in:

- 2.2. Files and Directories (2) (3) (4)
- 2.3. Entries
- 7.5. The FileSystem Interface (2) (3)

#file-system-name Referenced in:

- 2.2. Files and Directories (2)
- 7.5. The FileSystem Interface

#file-system-root Referenced in:

- 7.5. The FileSystem Interface

#entry-concept Referenced in:

- 2.3. Entries (2) (3) (4) (5) (6)
- 6. HTML: Drag and drop (2) (3)
- 7.1. The FileSystemEntry Interface (2) (3) (4) (5) (6) (7) (8)
- 7.2. The FileSystemDirectoryEntry Interface
- 7.3. The FileSystemDirectoryReader Interface
- 7.4. The FileSystemFileEntry Interface

#file-entry Referenced in:

- 7.1. The FileSystemEntry Interface
- 7.2. The FileSystemDirectoryEntry Interface
- 7.4. The FileSystemFileEntry Interface (2)

#directory-entry Referenced in:

- 2.4. Directory Reader
- 7.1. The FileSystemEntry Interface (2)
- 7.2. The FileSystemDirectoryEntry Interface (2) (3) (4) (5) (6) (7)

#entry-name Referenced in:

- 7.1. The FileSystemEntry Interface (2)
- 7.2. The FileSystemDirectoryEntry Interface (2)

#full-path Referenced in:

- 7.1. The FileSystemEntry Interface (2) (3)
- 7.2. The FileSystemDirectoryEntry Interface (2) (3) (4)
- 7.3. The FileSystemDirectoryReader Interface
- 7.4. The FileSystemFileEntry Interface

#entry-root Referenced in:

- 2.3. Entries
- 7.1. The FileSystemEntry Interface
- 7.2. The FileSystemDirectoryEntry Interface (2)
- 7.3. The FileSystemDirectoryReader Interface
- 7.4. The FileSystemFileEntry Interface

#entry-file-system Referenced in:

- 7.1. The FileSystemEntry Interface

#directory-reader Referenced in:

- 7.2. The FileSystemDirectoryEntry Interface
- 7.3. The FileSystemDirectoryReader Interface (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12)

#reading-flag Referenced in:

- 7.3. The FileSystemDirectoryReader Interface (2) (3)

#done-flag Referenced in:

- 7.3. The FileSystemDirectoryReader Interface (2)

#reader-error Referenced in:

- 7.3. The FileSystemDirectoryReader Interface (2) (3) (4) (5) (6)

#resolve-a-relative-path Referenced in:

- 7.1. The FileSystemEntry Interface
- 7.2. The FileSystemDirectoryEntry Interface (2)

#evaluate-a-path Referenced in:

- 7.1. The FileSystemEntry Interface
- 7.2. The FileSystemDirectoryEntry Interface (2)
- 7.3. The FileSystemDirectoryReader Interface
- 7.4. The FileSystemFileEntry Interface

#dom-file-webkitrelativepath Referenced in:

- 4. The File Interface
- 5. HTML: Forms (2) (3) (4) (5) (6) (7)

#dom-htmlinputelement-webkitdirectory Referenced in:

- 5. HTML: Forms (2)

#dom-htmlinputelement-webkitentries Referenced in:

- 5. HTML: Forms (2) (3) (4)

#dom-datatransferitem-webkitgetasentry Referenced in:

- 6. HTML: Drag and drop

#callbackdef-errorcallback Referenced in:

- 7. Files and Directories
- 7.1. The FileSystemEntry Interface
- 7.2. The FileSystemDirectoryEntry Interface (2)
- 7.3. The FileSystemDirectoryReader Interface
- 7.4. The FileSystemFileEntry Interface

#filesystementry Referenced in:

- 5. HTML: Forms (2)
- 6. HTML: Drag and drop (2)
- 7.1. The FileSystemEntry Interface (2) (3) (4) (5) (6) (7) (8)
- 7.2. The FileSystemDirectoryEntry Interface (2)
- 7.3. The FileSystemDirectoryReader Interface
- 7.4. The FileSystemFileEntry Interface
- 8. Acknowledgements

#dom-filesystementry-isfile Referenced in:

- 7.1. The FileSystemEntry Interface

#dom-filesystementry-isdirectory Referenced in:

- 7.1. The FileSystemEntry Interface

#dom-filesystementry-name Referenced in:

- 7.1. The FileSystemEntry Interface

#dom-filesystementry-fullpath Referenced in:

- 7.1. The FileSystemEntry Interface

#dom-filesystementry-filesystem Referenced in:

- 7.1. The FileSystemEntry Interface

#dom-filesystementry-getparent Referenced in:

- 7.1. The FileSystemEntry Interface (2)

#filesystemdirectoryentry Referenced in:

- 7.1. The FileSystemEntry Interface
- 7.2. The FileSystemDirectoryEntry Interface (2) (3)
- 7.5. The FileSystem Interface (2)

#dictdef-filesystemflags Referenced in:

- 7.2. The FileSystemDirectoryEntry Interface (2) (3)

#dom-filesystemflags-create Referenced in:

- 7.2. The FileSystemDirectoryEntry Interface (2) (3)

#dom-filesystemflags-exclusive Referenced in:

- 7.2. The FileSystemDirectoryEntry Interface

#callbackdef-filesystementrycallback Referenced in:

- 7.1. The FileSystemEntry Interface
- 7.2. The FileSystemDirectoryEntry Interface (2)

#dom-filesystemdirectoryentry-createreader Referenced in:

- 7.2. The FileSystemDirectoryEntry Interface

#dom-filesystemdirectoryentry-getfile Referenced in:

- 7.2. The FileSystemDirectoryEntry Interface (2)

#dom-filesystemdirectoryentry-getdirectory Referenced in:

- 7.2. The FileSystemDirectoryEntry Interface (2)

#filesystemdirectoryreader Referenced in:

- 7.2. The FileSystemDirectoryEntry Interface (2)
- 7.3. The FileSystemDirectoryReader Interface (2) (3) (4)

#callbackdef-filesystementriescallback Referenced in:

- 7.3. The FileSystemDirectoryReader Interface

#filesystemfileentry Referenced in:

- 7.2. The FileSystemDirectoryEntry Interface
- 7.4. The FileSystemFileEntry Interface (2)

#callbackdef-filecallback Referenced in:

- 7.4. The FileSystemFileEntry Interface

#dom-filesystemfileentry-file Referenced in:

- 7.4. The FileSystemFileEntry Interface (2)

#filesystem Referenced in:

- 7.1. The FileSystemEntry Interface
- 7.5. The FileSystem Interface (2) (3) (4)

#dom-filesystem-name Referenced in:

- 7.5. The FileSystem Interface

#dom-filesystem-root Referenced in:

- 7.5. The FileSystem Interface