The FileSystem API works on a local sandboxed file system exposed only to Web Applications, with all the well-known metaphors of a file system, including files and directories, and the ability to navigate through these with standard file system operations, such as creation of files and directories, reading, writing, and copying. It builds on top of the [[FileAPI]].

Introduction

The FileSystem API is for Web applications that have client-side storage needs not readily addressed by database APIs such as [[IndexedDB]]. Such applications need to handle common file types that end users typically link with logical directory structures in a file system, and generally involve large binary Blobs [[FileAPI]] that may be shared with other applications. The API is designed to be asynchronous using Promises [[DOM4]].

The FileSystem API is a virtual file system, and thus user agents are responsible for allocating space for the creation of a sandboxed file system and for imposing storage quotas on that virtual file system.

Use Cases

  1. Persistent uploader
    • When a file or directory is selected for upload, it copies it into a local sandbox and uploads a chunk at a time.
    • It can restart uploads after browser crashes, network interruptions, etc.
  2. Video game or other app with lots of media assets
    • It downloads one or several large tarballs, and expands them locally into a directory structure.
    • The same download should work on any operating system.
    • It can manage prefetching just the next-to-be-needed assets in the background, so going to the next game level or activating a new feature doesn't require waiting for a download.
    • It uses those assets directly from its local cache, by direct file reads or by handing local URLs to image or video tags, WebGL asset loaders, etc.
    • The files may be of arbitrary binary format.
  3. Audio/Photo editor with offline access or local cache for speed
    • Data here is potentially quite large, and is read-write.
    • It may want to do partial writes to files (ovewriting just the ID3/EXIF tags, for example).
    • The ability to organize project files by creating directories would be useful.
    • Edited files should be accessable by other client-side applications.
  4. Offline video viewer
    • It downloads large files (>1GB) for later viewing.
    • It needs efficient seek + streaming.
    • It must be able to hand a URL to the video tag.
    • It should enable access to partly-downloaded files e.g. to let you watch the first episode of the DVD even if your download didn't complete before you got on the plane.
    • It should be able to pull a single episode out of the middle of a download and give just that to the video tag.
  5. Offline Web Mail Client
    • Downloads attachments and stores them locally.
    • Caches user-selected attachments for later upload.
    • Needs to be able to refer to cached attachments and image thumbnails for display and upload.
    • Should be able to trigger the UA's download manager just as if talking to a server.
    • Should be able to upload an email with attachments as a multipart post, rather than sending a file at a time in an XHR.

Model

TBD

Extensions to Existing Objects

The FileSystem API is exposed to the Web via an extension to the window.navigator object [[!HTML]]. A URL-generating method for individual files within the virtualized filesystem is generated via an extension to the window.URL object [[!URL]].

Extension to Navigator

Promise<Directory> getFileSystem(optional FileSystemParameters parameters)

The getFileSystem method returns a new Promise object which is a , the getFileSystem must perform the following steps:

Extension to URL

static DOMString? getPersistentURL(File file)

TBD

The Directory Interface

readonly attribute DOMString name

TBD

Promise<File> createFile(DOMString path, createFileOptions options)

TBD

Promise<Directory> createDirectory(DOMString path)

TBD

Promise<(File or Directory)> get(DOMString path)

TBD

AbortableProgressPromise<void> move((DOMString or File or Directory) path, (DOMString or Directory or DestinationDict) dest)

TBD

Promise<boolean> remove((DOMString or File or Directory) path)

TBD

Promise<boolean> removeDeep((DOMString or File or Directory) path)

TBD

Promise<FileHandle> openRead((DOMString or File) path)

TBD

Promise<FileHandleWritable> openWrite((DOMString or File) path, OpenWriteOptions options)

TBD

EventStream<(File or Directory)> enumerate(optional DOMString path)

TBD

EventStream<File> enumerateDeep(optional DOMString path)

TBD

The FileHandle interface

readonly attribute FileOpenMode mode

TBD

readonly attribute boolean active

TBD

attribute long long? offset

TBD

Promise<File> getFile()

TBD

AbortableProgressPromise<ArrayBuffer> read(unsigned long long size)

TBD

void abort()

TBD

The FileHandleWritable Interface

AbortableProgressPromise<void> write((DOMString or ArrayBuffer or ArrayBufferView or Blob) value)

TBD

Promise<void> setSize(optional unsigned long long size)

TBD

Promise<void> flush()

TBD

FileSystem Configuration Parameters

temporary

TBD

persistent

TBD

StorageType storage = "temporary"

TBD

CreateIfExistsMode ifExists = "fail"

TBD

(DOMString or Blob or ArrayBuffer or ArrayBufferView) data
OpenIfNotExistsMode ifNotExists = "create"

TBD

OpenIfExistsMode ifExists = "open"

TBD

replace

TBD

fail

TBD

open

TBD

fail

TBD

create

TBD

fail

TBD

Directory dir

TBD

DOMString name

TBD

readonly

TBD

readwrite

TBD

Acknowledgements

Jonas Sicking, Mounir Lamouri, Ben Turner, Jan Varga, Andrea Marchesini, Doug Turner, Maciej Stachowiak