File and Directory Entries API

File and Directory Entries API

↑ →

Status of this document

Table of Contents

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

4. The File Interface

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

partialinterfaceFile {
    readonlyattributeUSVString webkitRelativePath;
};

The webkitRelativePath getter steps are to return the file’s relative path, 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.

partialinterfaceHTMLInputElement {
    attributeboolean webkitdirectory;
    readonlyattributeFrozenArray<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:

  <inputid=btype=filewebkitdirectory>

  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:

  <inputid=atype=filemultiple>

  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.

partialinterfaceDataTransferItem {
    FileSystemEntry? webkitGetAsEntry();
};

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?

callbackErrorCallback = undefined (DOMException err);

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

7.1. The FileSystemEntry Interface

[Exposed=Window]
interfaceFileSystemEntry {
    readonlyattributeboolean isFile;
    readonlyattributeboolean isDirectory;
    readonlyattributeUSVString name;
    readonlyattributeUSVString fullPath;
    readonlyattributeFileSystem filesystem;

    undefined getParent(optionalFileSystemEntryCallback successCallback,
                   optionalErrorCallback errorCallback);
};

An FileSystemEntry has an associated entry.

The isFile getter steps are to return true if this is a file entry and false otherwise.

The isDirectory getter steps are to return true if this is a directory entry and false otherwise.

The name getter steps are to return this's name.

The fullPath getter steps are to return this's full path.

The filesystem getter steps are to return this's file system.

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');}elseif(entry.isDirectory){
    console.log('... is a directory');}}

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

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

7.2. The FileSystemDirectoryEntry Interface

[Exposed=Window]
interfaceFileSystemDirectoryEntry : FileSystemEntry {
    FileSystemDirectoryReader createReader();
    undefined getFile(optionalUSVString? path,
                 optionalFileSystemFlags options = {},
                 optionalFileSystemEntryCallback successCallback,
                 optionalErrorCallback errorCallback);
    undefined getDirectory(optionalUSVString? path,
                      optionalFileSystemFlags options = {},
                      optionalFileSystemEntryCallback successCallback,
                      optionalErrorCallback errorCallback);
};

dictionaryFileSystemFlags {
    boolean create = false;
    boolean exclusive = false;
};

callbackFileSystemEntryCallback = undefined (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.

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

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

7.3. The FileSystemDirectoryReader Interface

[Exposed=Window]
interfaceFileSystemDirectoryReader {
    undefined readEntries(FileSystemEntriesCallback successCallback,
                     optionalErrorCallback errorCallback);
};
callbackFileSystemEntriesCallback = undefined (sequence<FileSystemEntry> entries);

A FileSystemDirectoryReader has an associated directory reader.

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){returnnew 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]:

asyncfunction* 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:

asyncfunction show(entry){
  console.log(entry.fullPath);if(entry.isDirectory){forawait(const e of getEntriesAsAsyncIterator(entry))await show(e);}}

7.4. The FileSystemFileEntry Interface

[Exposed=Window]
interfaceFileSystemFileEntry : FileSystemEntry {
    undefined file(FileCallback successCallback,
              optionalErrorCallback errorCallback);
};
callbackFileCallback = undefined (File file);

A FileSystemFileEntry's associated entry is a file entry.

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){returnnew Promise((resolve, reject)=>{
    entry.file(resolve, reject);});}

7.5. The FileSystem Interface

[Exposed=Window]
interfaceFileSystem {
    readonlyattributeUSVString name;
    readonlyattributeFileSystemDirectoryEntry root;
};

A FileSystem has an associated file system.

The name getter steps are to return this's name.

The root getter steps are to return a FileSystemDirectoryEntry associated with this's root.

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.

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
• 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
• parent, in §2.2
• path, in §2.1
• path segment, in §2.1
• readEntries(successCallback), in §7.3
• readEntries(successCallback, errorCallback)
• reader error, in §2.4
• reading flag, in §2.4
• relative path, in §2.1
• resolve a relative path, in §3
• 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-interfaceReferenced in: https://tc39.github.io/ecma262/#sec-promise-objectsReferenced in: https://w3c.github.io/FileAPI/#dfn-fileReferenced in: https://w3c.github.io/FileAPI/#dfn-filereaderReferenced in: https://w3c.github.io/FileAPI/#dfn-nameReferenced in: https://html.spec.whatwg.org/multipage/dnd.html#datatransferitemReferenced in: https://html.spec.whatwg.org/multipage/input.html#htmlinputelementReferenced in: https://html.spec.whatwg.org/multipage/input.html#dom-input-acceptReferenced in: https://html.spec.whatwg.org/multipage/interaction.html#the-drag-data-item-kindReferenced in: https://html.spec.whatwg.org/multipage/interaction.html#drag-data-storeReferenced in: https://html.spec.whatwg.org/multipage/interaction.html#drag-data-store-item-listReferenced in: https://html.spec.whatwg.org/multipage/forms.html#file-upload-state-(type=file)Referenced in: https://html.spec.whatwg.org/multipage/input.html#dom-input-filesReferenced in: https://html.spec.whatwg.org/multipage/dnd.html#dom-datatransferitem-getasfileReferenced in: https://html.spec.whatwg.org/multipage/input.html#the-input-elementReferenced in: https://html.spec.whatwg.org/multipage/webappapis.html#queue-a-taskReferenced in: https://html.spec.whatwg.org/multipage/interaction.html#concept-dnd-roReferenced in: https://html.spec.whatwg.org/multipage/interaction.html#concept-dnd-rwReferenced in: https://html.spec.whatwg.org/multipage/forms.html#concept-input-type-file-selectedReferenced in: https://html.spec.whatwg.org/multipage/input.html#attr-input-typeReferenced in: https://infra.spec.whatwg.org/#strictly-splitReferenced in: https://heycam.github.io/webidl/#idl-DOMExceptionReferenced in: https://heycam.github.io/webidl/#ExposedReferenced in: https://heycam.github.io/webidl/#idl-frozen-arrayReferenced in: https://heycam.github.io/webidl/#invalidstateerrorReferenced in: https://heycam.github.io/webidl/#notfounderrorReferenced in: https://heycam.github.io/webidl/#securityerrorReferenced in: https://heycam.github.io/webidl/#exceptiondef-typeerrorReferenced in: https://heycam.github.io/webidl/#typemismatcherrorReferenced in: https://heycam.github.io/webidl/#idl-USVStringReferenced in: https://heycam.github.io/webidl/#idl-booleanReferenced in: https://heycam.github.io/webidl/#dfn-create-exceptionReferenced in: https://heycam.github.io/webidl/#invoke-a-callback-functionReferenced in: https://heycam.github.io/webidl/#idl-sequenceReferenced in: https://heycam.github.io/webidl/#thisReferenced in: https://heycam.github.io/webidl/#idl-undefinedReferenced in:

Terms defined by reference

• [ecma262] defines the following terms:
  • asynciterator
  • promise
• [FileAPI] defines the following terms:
  • FileReader
• [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
• [INFRA] defines the following terms:
  • strictly split
• [WebIDL] defines the following terms:
  • DOMException
  • Exposed
  • FrozenArray
  • InvalidStateError
  • NotFoundError
  • SecurityError
  • TypeError
  • TypeMismatchError
  • USVString
  • boolean
  • created
  • invoke
  • sequence
  • undefined

References

Normative References

[FileAPI] Marijn Kruisselbrink; Arun Ranganathan. File API. 27 April 2021. 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.es/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

partialinterfaceFile {
    readonlyattributeUSVString webkitRelativePath;
};

partialinterfaceHTMLInputElement {
    attributeboolean webkitdirectory;
    readonlyattributeFrozenArray<FileSystemEntry> webkitEntries;
};

partialinterfaceDataTransferItem {
    FileSystemEntry? webkitGetAsEntry();
};

callbackErrorCallback = undefined (DOMException err);

[Exposed=Window]
interfaceFileSystemEntry {
    readonlyattributeboolean isFile;
    readonlyattributeboolean isDirectory;
    readonlyattributeUSVString name;
    readonlyattributeUSVString fullPath;
    readonlyattributeFileSystem filesystem;

    undefined getParent(optionalFileSystemEntryCallback successCallback,
                   optionalErrorCallback errorCallback);
};

[Exposed=Window]
interfaceFileSystemDirectoryEntry : FileSystemEntry {
    FileSystemDirectoryReader createReader();
    undefined getFile(optionalUSVString? path,
                 optionalFileSystemFlags options = {},
                 optionalFileSystemEntryCallback successCallback,
                 optionalErrorCallback errorCallback);
    undefined getDirectory(optionalUSVString? path,
                      optionalFileSystemFlags options = {},
                      optionalFileSystemEntryCallback successCallback,
                      optionalErrorCallback errorCallback);
};

dictionaryFileSystemFlags {
    boolean create = false;
    boolean exclusive = false;
};

callbackFileSystemEntryCallback = undefined (FileSystemEntry entry);

[Exposed=Window]
interfaceFileSystemDirectoryReader {
    undefined readEntries(FileSystemEntriesCallback successCallback,
                     optionalErrorCallback errorCallback);
};
callbackFileSystemEntriesCallback = undefined (sequence<FileSystemEntry> entries);

[Exposed=Window]
interfaceFileSystemFileEntry : FileSystemEntry {
    undefined file(FileCallback successCallback,
              optionalErrorCallback errorCallback);
};
callbackFileCallback = undefined (File file);

[Exposed=Window]
interfaceFileSystem {
    readonlyattributeUSVString name;
    readonlyattributeFileSystemDirectoryEntry root;
};

Issues Index

#nameReferenced in: #path-segmentReferenced in: #relative-pathReferenced in: #absolute-pathReferenced in: #pathReferenced in: #valid-pathReferenced in: #fileReferenced in: #file-nameReferenced in: #directoryReferenced in: #directory-nameReferenced in: #root-directoryReferenced in: #parentReferenced in: #file-systemReferenced in: #file-system-nameReferenced in: #file-system-rootReferenced in: #entry-conceptReferenced in: #file-entryReferenced in: #directory-entryReferenced in: #entry-nameReferenced in: #full-pathReferenced in: #entry-rootReferenced in: #entry-file-systemReferenced in: #directory-readerReferenced in: #reading-flagReferenced in: #done-flagReferenced in: #reader-errorReferenced in: #resolve-a-relative-pathReferenced in: #evaluate-a-pathReferenced in: #dom-file-webkitrelativepathReferenced in: #dom-htmlinputelement-webkitdirectoryReferenced in: #dom-htmlinputelement-webkitentriesReferenced in: #dom-datatransferitem-webkitgetasentryReferenced in: #callbackdef-errorcallbackReferenced in: #filesystementryReferenced in: #dom-filesystementry-isfileReferenced in: #dom-filesystementry-isdirectoryReferenced in: #dom-filesystementry-nameReferenced in: #dom-filesystementry-fullpathReferenced in: #dom-filesystementry-filesystemReferenced in: #dom-filesystementry-getparentReferenced in: #filesystemdirectoryentryReferenced in: #dictdef-filesystemflagsReferenced in: #dom-filesystemflags-createReferenced in: #dom-filesystemflags-exclusiveReferenced in: #callbackdef-filesystementrycallbackReferenced in: #dom-filesystemdirectoryentry-createreaderReferenced in: #dom-filesystemdirectoryentry-getfileReferenced in: #dom-filesystemdirectoryentry-getdirectoryReferenced in: #filesystemdirectoryreaderReferenced in: #callbackdef-filesystementriescallbackReferenced in: #filesystemfileentryReferenced in: #callbackdef-filecallbackReferenced in: #dom-filesystemfileentry-fileReferenced in: #filesystemReferenced in: #dom-filesystem-nameReferenced in: #dom-filesystem-rootReferenced in: