filer.js

filer.js is a wrapper library for the HTML5 Filesystem API, an API which enables web applications to read and write files and folders to to its own sandboxed filesystem.

Unlike other wrapper libraries [1, 2], filer.js takes a different approach by reusing familiar UNIX commands (cp, mv, ls) for its API. The goal is to make the HTML5 API more approachable for developers that have done file I/O in other languages.

Getting started

I highly recommended that you familiarize yourself with the HTML5 Filesystem API. I've written a book on the topic, "Using the HTML5 Filesystem API", and there are two great articles on HTML5 Rocks that walk you through all of its different methods and capabilities:

1. Exploring the FileSystem APIs
2. The Synchronous FileSystem API for Workers

Usage

The underlying Filesystem API is asynchronous, therefore, the library calls are mostly asynchronous. This means you'll be passing callbacks all over the place.

First, create a Filer object:

var filer = new Filer();

Next, initialize the library:

filer.init({persistent: false, size: 1024 * 1024}, function(fs) {
  //  filer.size == Filer.DEFAULT_FS_SIZE
}, onError);

The first argument is an optional initialization object that can contain two properties, persistent (the type of storage to use) and size. The second and third arguments are a success and error callback, respectively:

The success callback is passed a LocalFileSystem object. If you don't initialize the the filesystem with a size, a default size of Filer.DEFAULT_FS_SIZE (1MB) will be used. Thus, the previous call can be simplified to:

filer.init({}, function(fs) {
  ...
}, onError);

filer.init(); // All parameters are optional.

Error handling

Many methods take an optional error callback as their last argument. It can be a good idea to setup a global error handler for all methods to use:

function onError(e) {
  console.log('Error' + e.name);
}

Examples

ls()

ls() lists the files in the directory you pass it. The first arg is a path to a directory:

filer.ls('.', function(entries) {
  // entries in the current working directory.
}, onError);

filer.ls('path/to/some/dir/', function(entries) {
  // entries in "path/to/some/dir/"
}, onError);

For versatility, the library accepts paths to files and directories as string values or as FileEntry/DirectoryEntry objects. For example, you can pass a DirectorEntry to ls():

filer.ls(filer.fs.root, function(entries) {
  // entries in the root directory.
}, onError);

which equivalent to:

filer.ls('/', function(entries) {
  // entries in the root directory.
}, onError);

cd()

cd() allows you to change into another directory. Future operations will become relative to the new directory:

// Passing a path.
filer.cd('/path/to/folder', function(dirEntry) {
  ...
}, onError);

// Passing a DirectoryEntry.
filer.cd(dirEntry, function(dirEntry2) {
  // dirEntry == dirEntry2
}, onError);

filer.cd('/path/to/folder'); // Both callbacks are optional.