File System Access API

Draft

This page is not complete.

Secure context

This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The File System Access API allows read, write and file management capabilities.

Concepts and Usage

The API allows interaction with files on a users local device. These don't have to be files directly stored on the device, they can be files accessed through cloud storage software. Core functionality includes reading files, writing or saving files, as well as access to directory structure.

It expands the current file capabilities of a browser and can enable developers to create software to open and save files. Software such as IDE's, photo or video editors and text editors, to name but a few.

Most of the interaction with files and directories is accomplished through handles. A parent FileSystemHandle class helps define two child classes: FileSystemFileHandle and FileSystemDirectoryHandle, depending if you want to work with files or directories respectively.

These handles represent the file or directory on the users system. You gain access to them by showing the user a file or directory picker. The methods which allow this are window.showOpenFilePicker and window.showDirectoryPicker. Once these are called the picker presents itself and the user selects either a file or directory. Once this happens successfully a handle is returned. You can also gain access to file handles via the DataTransferItem.getAsFileSystemHandle() method of the HTML Drag and Drop API.

The handle provides it's own functionality and there are a few differences depending on whether a file or directory was selected (see the below interfaces section for specific details). For the main part you gain access to the file data, or information (including children) of the directory selected.

There is also save functionality, which is where the FilesystemWritableFileStream interface comes in. Once the data you'd like to save is in a format of Blob, USVString or buffer, you can open a stream and save the data to a file. That can be the existing file or a new file.

Primarily this API opens up functionality the web has been lacking. Security has been of upmost consideration when designing the API and access to file/directory data is not allowed unless the user specifically permits it.

Interfaces

FileSystemHandle
The FileSystemHandle interface is an object which represents an entry. Multiple handles can represent the same entry. For the most part you do not work with FileSystemEntry directly but rather it's child interfaces FileSystemFileEntry and FileSystemDirectoryEntry.
FileSystemFileHandle
Provides a handle to a file system entry.
FileSystemDirectoryHandle
provides a handle to a file system directory.
FileSystemWritableFileStream
is a WritableStream object with additional convenience methods, which operates on a single file on disk.

Examples

Accessing files.

The below code allows the user to choose a file from the file picker and then tests to see whether the handle returned is a file or directory

// store a reference to our file handle
let fileHandle;

async function getFile() {
  // open file picker
  [fileHandle] = await window.showOpenFilePicker();

  if (fileHandle.type === 'file') {
    // run file code
  } else if (fileHandle.type === 'directory')
    // run directory code
  }

}

The following asynchronous function presents a file picker and once a file is chosen, uses the getFile() method to retrieve the contents.

const pickerOpts = {
  types: [
    {
      description: 'Images',
      accept: {
        'image/*': ['.png', '.gif', '.jpeg', '.jpg']
      }
    },
  ],
  excludeAcceptAllOption: true,
  multiple: false
};

async function getTheFile() {
  // open file picker
  [fileHandle] = await window.showOpenFilePicker(pickerOpts);

  // get file contents
  const fileData = await fileHandle.getFile();
}

Accessing directories.

The following example returns a directory handle with the specified name, if the directory does not exist it is created.

const dirName = 'directoryToGetName';

// assuming we have a directory handle: 'currentDirHandle'
const subDir = currentDirHandle.getDirectoryHandle(dirName, {create: true});

The following asynchronous function uses resolve() to find the path to a chosen file, relative to a specified directory handle.

async function returnPathDirectories(directoryHandle) {

  // Get a file handle by showing a file picker:
  const handle = await self.showOpenFilePicker();
  if (!handle) {
    // User cancelled, or otherwise failed to open a file.
    return;
  }

  // Check if handle exists inside directory our directory handle
  const relativePaths = await directoryHandle.resolve(handle);

  if (relativePath === null) {
    // Not inside directory handle
  } else {
    // relativePath is an array of names, giving the relative path

    for (const name of relativePaths) {
      // log each entry
      console.log(name);
    }
  }
}

Writing to files.

This asynchronous function opens the save file picker, which returns a FileSystemFileHandle once a file is selected. From which a writable stream is then created using the FileSystemFileHandle.createWritable() method.

A user defined Blob is then written to the stream which is subsequently closed.

async function saveFile() {

  // create a new handle
  const newHandle = await window.showSaveFilePicker();

  // create a FileSystemWritableFileStream to write to
  const writableStream = await newHandle.createWritable();

  // write our file
  await writableStream.write(imgBlob);

  // close the file and write the contents to disk.
  await writableStream.close();
}

The following show different examples of options that can be passed into the write() method.

// just pass in the data (no options)
writableStream.write(data)

// writes the data to the stream from the determined position
writableStream.write({ type: "write", position: position, data: data })

// updates the current file cursor offset to the position specified
writableStream.write({ type: "seek", position: position })

// resizes the file to be size bytes long
writableStream.write({ type: "truncate", size: size })

Specifications

Specification Status Comment
File System Access API Working Draft Initial definition.

See also