Merge pull request #89 from humphd/docs

Epic! Thanks :)

CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# How to Contribute
+
+The best way to get started is to read through the `Getting Started` and `Example`
+sections before having a look through the open [issues](https://github.com/js-platform/filer/issues).
+Some of the issues are marked as `good first bug`, but feel free to contribute to
+any of the issues there, or open a new one if the thing you want to work on isn't
+there yet. If you would like to have an issue assigned to you, please send me a
+message and I'll update it.
+
+## Setup
+
+The Filer build system is based on [grunt](http://gruntjs.com/). To get a working build system
+do the following:
+
+```
+npm install
+npm install -g grunt-cli
+```
+
+You can now run the following grunt tasks:
+* `grunt check` will run [JSHint](http://www.jshint.com/) on your code (do this before submitting a pull request) to catch errors
+* `grunt develop` will create a single file version of the library for testing in `dist/idbfs.js`
+* `grunt release` like `develop` but will also create a minified version of the library in `dist/idbfs.min.js`
+
+Once you've done some hacking and you'd like to have your work merged, you'll need to
+make a pull request. If you're patch includes code, make sure to check that all the
+unit tests pass, including any new tests you wrote. Finally, make sure you add yourself
+to the `AUTHORS` file.
+
+## Tests
+
+Tests are writting using [Jasmine](http://pivotal.github.io/jasmine/). You can run the tests
+in your browser by opening the `tests` directory. You can also run them
+[here](http://js-platform.github.io/idbfs/tests/).
+
+## Communication
+
+If you'd like to talk to someone about the project, you can reach us on irc.mozilla.org in the
+mofodev channel. Look for "ack" or "humph".

README.md

@@ -3,59 +3,47 @@
 ###Filer
 
 Filer is a POSIX-like file system interface for browser-based JavaScript.
-The API is as close to the node.js [fs module](http://nodejs.org/api/fs.html) as possible
-with the following differences:
-
-* No synchronous versions of methods (e.g., `mkdir()` but not `mkdirSync()`).
-
-* No permissions (e.g., no `chown()`, `chmod()`, etc.).
-
-* No support (yet) for `fs.watchFile()`, `fs.unwatchFile()`, `fs.watch()`.
-
-* No support for stream-based operations (e.g., `fs.ReadStream`, `fs.WriteStream`).
 
 ### Contributing
 
-The best way to get started is to read through the `Getting Started` and `Example` sections before having a look through the open [issues](https://github.com/js-platform/filer/issues). Some of the issues are marked as `good first bug`, but feel free to contribute to any of the issues there, or open a new one if the thing you want to work on isn't there yet. If you would like to have an issue assigned to you, please send me a message and I'll update it.
+Want to join the fun? We'd love to have you! See [CONTRIBUTING](CONTRIBUTING.md).
-
-The build system is based on [grunt](http://gruntjs.com/). To get a working build system
-do the following:
-
-```
-npm install
-npm install -g grunt-cli
-```
-
-You can now run the following grunt tasks:
-* `grunt check` will run [JSHint](http://www.jshint.com/) on your code (do this before submitting a pull request) to catch errors
-* `grunt develop` will create a single file version of the library for testing in `dist/idbfs.js`
-* `grunt release` like `develop` but will also create a minified version of the library in `dist/idbfs.min.js`
-
-Once you've done some hacking and you'd like to have your work merged, you'll need to make a pull request. If you're patch includes code, make sure to check that all the unit tests pass, including any new tests you wrote. Finally, make sure you add yourself to the `AUTHORS` file.
-
-#### Tests
-
-You can run the tests from the project by opening the `tests` directory in your browser. You can also run them [here](http://js-platform.github.io/idbfs/tests/).
 
 ###Downloading
 
 Pre-built versions of the library are available in the repo:
 
-* [idbfs.js](https://raw.github.com/js-platform/filer/develop/dist/idbfs.js)
+* [filer.js](https://raw.github.com/js-platform/filer/develop/dist/filer.js)
-* [idbfs.min.js](https://raw.github.com/js-platform/filer/develop/dist/idbfs.min.js)
+* [filer.min.js](https://raw.github.com/js-platform/filer/develop/dist/filer.min.js)
 
 ### Getting Started
 
-IDBFS is partly based on the `fs` module from node.js. The API is asynchronous and most methods require the caller to provide a callback function. Errors are passed to callbacks through the first parameter.
+Filer is as close to the node.js [fs module](http://nodejs.org/api/fs.html) as possible,
+with the following differences:
 
-To create a new file system or open an existing one, create a new `FileSystem` instance and pass the name of the file system. A new IndexedDB database is created for each file system.
+* No synchronous versions of methods (e.g., `mkdir()` but not `mkdirSync()`).
+* No permissions (e.g., no `chown()`, `chmod()`, etc.).
+* No support (yet) for `fs.watchFile()`, `fs.unwatchFile()`, `fs.watch()`.
+* No support for stream-based operations (e.g., `fs.ReadStream`, `fs.WriteStream`).
 
-For additional documentation, check out the `API Reference` below and have a look through the unit tests for more concrete examples of how things work.
+Filer has other features lacking in node.js (e.g., swappable backend
+storage providers, support for encryption and compression, extended attributes, etc).
 
-#### Example
+Like node.js, the API is asynchronous and most methods expect the caller to provide
+a callback function (note: like node.js, Filer will supply one if it's missing).
+Errors are passed to callbacks through the first parameter.  As with node.js,
+there is no guarantee that file system operations will be executed in the order
+they are invoked. Ensure proper ordering by chaining operations in callbacks.
+
+### Example
+
+To create a new file system or open an existing one, create a new `FileSystem`
+instance.  By default, a new [IndexedDB](https://developer.mozilla.org/en/docs/IndexedDB)
+database is created for each file system. The file system can also use other
+backend storage providers, for example [WebSQL](http://en.wikipedia.org/wiki/Web_SQL_Database)
+or even RAM (i.e., for temporary storage). See the section on [Storage Providers](#providers).
 
 ```javascript
-var fs = new IDBFS.FileSystem();
+var fs = new Filer.FileSystem();
 fs.open('/myfile', 'w+', function(err, fd) {
   if (err) throw err;
   fs.close(fd, function(err) {
@@ -68,19 +56,21 @@ fs.open('/myfile', 'w+', function(err, fd) {
 });
 ```
 
-As with node.js, there is no guarantee that file system operations will be executed in the order they are invoked. Ensure proper ordering by chaining operations in callbacks.
-
 ### API Reference
 
-Like node.js, callbacks for methods that accept them are optional but suggested. The first callback parameter is reserved for passing errors. It will be `null` if no errors occurred and should always be checked.
+Like node.js, callbacks for methods that accept them are optional but suggested (i.e., if
+you omit the callback, errors will be thrown as exceptions). The first callback parameter is
+reserved for passing errors. It will be `null` if no errors occurred and should always be checked.
 
-#### IDBFS.FileSystem(options, callback)
+#### Filer.FileSystem(options, callback) constructor
 
-File system constructor, invoked to open an existing file system or create a new one. Accepts two arguments: an `options` object,
+File system constructor, invoked to open an existing file system or create a new one.
-and an optional `callback`.  The `options` object can specify a number of optional arguments, including:
+Accepts two arguments: an `options` object, and an optional `callback`. The `options`
-* `name`: the name of the file system, defaults to "local"
+object can specify a number of optional arguments, including:
-* `flags`: one or more flags to use when creating/opening the file system. Use `'FORMAT'` to force IDBFS to format (i.e., erase) the file system
+
-* `provider`: an explicit storage provider to use for the file system's database context provider.  See below for details
+* `name`: the name of the file system, defaults to `'"local'`
+* `flags`: one or more flags to use when creating/opening the file system. Use `'FORMAT'` to force Filer to format (i.e., erase) the file system
+* `provider`: an explicit storage provider to use for the file system's database context provider. See the section on [Storage Providers](#providers).
 
 The `callback` function indicates when the file system is ready for use. Depending on the storage provider used, this might
 be right away, or could take some time. The callback should expect an `error` argument, which will be null if everything worked.
@@ -94,18 +84,23 @@ function fsReady(err) {
   // Safe to use fs now...
 }
 
-fs = new IDBFS.FileSystem({
+fs = new Filer.FileSystem({
   name: "my-filesystem",
   flags: 'FORMAT',
-  provider: new IDBFS.FileSystem.providers.Memory()
+  provider: new Filer.FileSystem.providers.Memory()
 }, fsReady);
 ```
 
-####IDBFS.FileSystem.providers - Storage Providers
+NOTE: if the optional callback argument is not passed to the `FileSystem` constructor,
+operations done on the resulting file system will be queued and run in sequence when
+it becomes ready.
 
-IDBFS can be configured to use a number of different storage providers. The provider object encapsulates all aspects
+####Filer.FileSystem.providers - Storage Providers<a name="providers"></a>
+
+Filer can be configured to use a number of different storage providers. The provider object encapsulates all aspects
 of data access, making it possible to swap in different backend storage options.  There are currently 4 different
 providers to choose from:
+
 * `FileSystem.providers.IndexedDB()` - uses IndexedDB
 * `FileSystem.providers.WebSQL()` - uses WebSQL
 * `FileSystem.providers.Fallback()` - attempts to use IndexedDB if possible, falling-back to WebSQL if necessary
@@ -114,7 +109,7 @@ providers to choose from:
 You can choose your provider when creating a `FileSystem`:
 
 ```javascript
-var FileSystem = IDBFS.FileSystem;
+var FileSystem = Filer.FileSystem;
 var providers = FileSystem.providers;
 
 // Example 1: Use the default provider (currently IndexedDB)
@@ -130,20 +125,21 @@ var fs3 = new FileSystem({ provider: new providers.Fallback() });
 Every provider has an `isSupported()` method, which returns `true` if the browser supports this provider:
 
 ```javascript
-if( IDBFS.FileSystem.providers.WebSQL.isSupported() ) {
+if( Filer.FileSystem.providers.WebSQL.isSupported() ) {
-  ...
+  // WebSQL provider will work in current environment...
 }
 ```
 
 You can also write your own provider if you need a different backend. See the code in `src/providers` for details.
 
-####IDBFS.FileSystem.adapters - Adapters for Storage Providers
+####Filer.FileSystem.adapters - Adapters for Storage Providers
 
-IDBFS based file systems can acquire new functionality by using adapters. These wrapper objects extend the abilities
+Filer based file systems can acquire new functionality by using adapters. These wrapper objects extend the abilities
 of storage providers without altering them in anway. An adapter can be used with any provider, and multiple
 adapters can be used together in order to compose complex functionality on top of a provider.
 
 There are currently 5 adapters available:
+
 * `FileSystem.adapters.Compression(provider)` - a default compression adapter that uses [Zlib](https://github.com/imaya/zlib.js)
 * `FileSystem.adapters.Encryption(passphrase, provider)` - a default encryption adapter that uses [AES encryption](http://code.google.com/p/crypto-js/#AES)
 
@@ -153,7 +149,7 @@ You can also pick from other encryption cipher algorithms:
 * `FileSystem.adapters.Rabbit(passphrase, provider)` - extends a provider with [Rabbit encryption](http://code.google.com/p/crypto-js/#Rabbit)
 
 ```javascript
-var FileSystem = IDBFS.FileSystem;
+var FileSystem = Filer.FileSystem;
 var providers = FileSystem.providers;
 var adapters = FileSystem.adapters;
 
@@ -168,15 +164,15 @@ var fs = new FileSystem({ provider: compressionAdapter });
 You can also write your own adapter if you need to add new capabilities to the providers. Adapters share the same
 interface as providers.  See the code in `src/providers` and `src/adapters` for many examples.
 
-####IDBFS.Path
+####Filer.Path
 
-The node.js [path module](http://nodejs.org/api/path.html) is available via the `IDBFS.Path` object. It is
+The node.js [path module](http://nodejs.org/api/path.html) is available via the `Filer.Path` object. It is
 identical to the node.js version with the following differences:
 * No support for `exits()` or `existsSync()`. Use `fs.stat()` instead.
 * No notion of a current working directory in `resolve` (the root dir is used instead)
 
 ```javascript
-var path = IDBFS.Path;
+var path = Filer.Path;
 var dir = path.dirname('/foo/bar/baz/asdf/quux');
 // dir is now '/foo/bar/baz/asdf'
 
@@ -201,9 +197,131 @@ For more info see the docs in the [path module](http://nodejs.org/api/path.html)
 * `path.sep`
 * `path.delimiter`
 
-#### fs.stat(path, callback)
+###FileSystem Instance Methods
 
-Asynchronous stat(2). Callback gets `(error, stats)`, where `stats` is an object like
+Once a `FileSystem` is created, it has the following methods. NOTE: code examples below assume
+a `FileSystem` instance named `fs` has been created like so:
+
+```javascript
+var fs = new Filer.FileSystem();
+```
+
+* [fs.rename(oldPath, newPath, callback)](#rename)
+* [fs.ftruncate(fd, len, callback)](#ftruncate)
+* [fs.truncate(path, len, callback)](#truncate)
+* [fs.stat(path, callback)](#stat)
+* [fs.fstat(fd, callback)](#fstat)
+* [fs.lstat(path, callback)](#lstat)
+* [fs.link(srcpath, dstpath, callback)](#link)
+* [fs.symlink(srcpath, dstpath, [type], callback)](#symlink)
+* [fs.readlink(path, callback)](#readlink)
+* [fs.realpath(path, [cache], callback)](#realpath)
+* [fs.unlink(path, callback)](#unlink)
+* [fs.rmdir(path, callback)](#rmdir)
+* [fs.mkdir(path, [mode], callback)](#mkdir)
+* [fs.readdir(path, callback)](#readdir)
+* [fs.close(fd, callback)](#close)
+* [fs.open(path, flags, [mode], callback)](#open)
+* [fs.utimes(path, atime, mtime, callback)](#utimes)
+* [fs.futimes(fd, atime, mtime, callback)](#fsutimes)
+* [fs.fsync(fd, callback)](#fsync)
+* [fs.write(fd, buffer, offset, length, position, callback)](#write)
+* [fs.read(fd, buffer, offset, length, position, callback)](#read)
+* [fs.readFile(filename, [options], callback)](#readFile)
+* [fs.writeFile(filename, data, [options], callback)](#writeFile)
+* [fs.appendFile(filename, data, [options], callback)](#appendFile)
+* [fs.setxattr(path, name, value, [flag], callback)](#setxattr)
+* [fs.fsetxattr(fd, name, value, [flag], callback)](#fsetxattr)
+* [fs.getxattr(path, name, callback)](#getxattr)
+* [fs.fgetxattr(fd, name, callback)](#fgetxattr)
+* [fs.removexattr(path, name, callback)](#removexattr)
+* [fs.fremovexattr(fd, name, callback)](#fremovexattr)
+
+#### fs.rename(oldPath, newPath, callback)<a name="rename"></a>
+
+Renames the file at `oldPath` to `newPath`. Asynchronous [rename(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/rename.html).
+Callback gets no additional arguments.
+
+Example:
+
+```javascript
+// Rename myfile.txt to myfile.bak
+fs.rename("/myfile.txt", "/myfile.bak", function(err) {
+  if(err) throw err;
+  // myfile.txt is now myfile.bak
+});
+```
+
+#### fs.ftruncate(fd, len, callback)<a name="ftruncate"></a>
+
+Change the size of the file represented by the open file descriptor `fd` to be length
+`len` bytes. Asynchronous [ftruncate(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/ftruncate.html).
+If the file is larger than `len`, the extra bytes will be discarded; if smaller, its size will
+be increased, and the extended area will appear as if it were zero-filled. See also [fs.truncate()](#truncate).
+
+Example:
+
+```javascript
+// Create a file, shrink it, expand it.
+var buffer = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
+
+fs.open('/myfile', 'w', function(err, fd) {
+  if(err) throw error;
+  fs.write(fd, buffer, 0, buffer.length, 0, function(err, result) {
+    if(err) throw error;
+      fs.ftruncate(fd, 3, function(err) {
+        if(err) throw error;
+        // /myfile is now 3 bytes in length, rest of data discarded
+
+        fs.ftruncate(fd, 50, function(err) {
+          if(err) throw error;
+          // /myfile is now 50 bytes in length, with zero padding at end
+
+          fs.close(fd);
+        });
+      });
+    });
+  });
+});
+```
+
+#### fs.truncate(path, len, callback)<a name="truncate"></a>
+
+Change the size of the file at `path` to be length `len` bytes. Asynchronous [truncate(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/truncate.html). If the file is larger than `len`, the extra bytes will be discarded; if smaller, its size will
+be increased, and the extended area will appear as if it were zero-filled. See also [fs.ftruncate()](#ftruncate).
+
+Example:
+
+```javascript
+// Create a file, shrink it, expand it.
+var buffer = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
+
+fs.open('/myfile', 'w', function(err, fd) {
+  if(err) throw error;
+  fs.write(fd, buffer, 0, buffer.length, 0, function(err, result) {
+    if(err) throw error;
+    fs.close(fd, function(err) {
+      if(err) throw error;
+
+      fs.truncate('/myfile', 3, function(err) {
+        if(err) throw error;
+        // /myfile is now 3 bytes in length, rest of data discarded
+
+        fs.truncate('/myfile', 50, function(err) {
+          if(err) throw error;
+          // /myfile is now 50 bytes in length, with zero padding at end
+
+        });
+      });
+    });
+  });
+});
+```
+
+#### fs.stat(path, callback)<a name="stat"></a>
+
+Obtain file status about the file at `path`. Asynchronous [stat(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/stat.html).
+Callback gets `(error, stats)`, where `stats` is an object with the following properties:
 
 ```
 {
@@ -214,41 +332,243 @@ Asynchronous stat(2). Callback gets `(error, stats)`, where `stats` is an object
   atime: <number>  // last access time
   mtime: <number>  // last modified time
   ctime: <number>  // creation time
-  type: <string> // file type (FILE, DIRECTORY, ...)
+  type: <string>   // file type (FILE, DIRECTORY, SYMLINK)
 }
 ```
 
-#### fs.fstat(fd, callback)
+If the file at `path` is a symbolik link, the file to which it links will be used instead.
+To get the status of a symbolic link file, use [fs.lstat()](#lstat) instead.
 
-Asynchronous stat(2). Callback gets `(error, stats)`. See `fs.stat`.
+Examples:
 
-#### fs.link(srcPath, dstPath, callback)
+```javascript
+// Check if a directory exists
+function dirExists(path, callback) {
+  fs.stat(path, function(err, stats) {
+    if(err) return callback(err);
+    var exists = stats.type === "DIRECTORY";
+    callback(null, exists);
+  });
+};
 
-Asynchronous link(2). Callback gets no additional arguments.
+// Get the size of a file in KB
+function fileSize(path, callback) {
+  fs.stat(path, function(err, stats) {
+    if(err) return callback(err);
+    var kb = stats.size / 1000;
+    callback(null, kb);
+  });
+}
+```
 
-#### fs.unlink(path, callback)
+#### fs.fstat(fd, callback)<a name="fstat"></a>
 
-Asynchronous unlink(2). Callback gets no additional arguments.
+Obtain information about the open file known by the file descriptor `fd`.
+Asynchronous [fstat(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/fstat.html).
+Callback gets `(error, stats)`. `fstat()` is identical to `stat()`, except that the file to be stat-ed is
+specified by the open file descriptor `fd` instead of a path.  See also [fs.stat](#stat)
 
-#### fs.rename(oldPath, newPath, callback)#
+Example:
 
-Asynchronous rename(2). Callback gets no additional arguments.
+```javascript
+fs.open("/file.txt", "r", function(err, fd) {
+  if(err) throw err;
+  fs.fstat(fd, function(err, stats) {
+    if(err) throw err;
+    // do something with stats object
+    // ...
+    fs.close(fd);
+  });
+});
+```
 
-#### fs.rmdir(path, callback)
+#### fs.lstat(path, callback)<a name="lstat"></a>
 
-Asynchronous rmdir(2). Callback gets no additional arguments.
+Obtain information about the file at `path` (i.e., the symbolic link file itself) vs.
+the destination file to which it links. Asynchronous [lstat(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/lstat.html).
+Callback gets `(error, stats)`. See also [fs.stat](#stat).
 
-#### fs.mkdir(path, callback)
+Example:
 
-Asynchronous mkdir(2). Callback gets no additional arguments.
+```javascript
+// Create a symbolic link, /data/logs/current to /data/logs/august
+// and get info about the symbolic link file, and linked file.
+fs.link("/data/logs/august", "/data/logs/current", function(err) {
+  if(err) throw err;
 
-#### fs.close(fd, callback)
+  // Get status of linked file, /data/logs/august
+  fs.stat("/data/logs/current", function(err, stats) {
+    if(err) throw err;
+    // Size of /data/logs/august
+    var size = stats.size;
+  });
 
-Asynchronous close(2). Callback gets no additional arguments.
+  // Get status of symbolic link file itself
+  fs.lstat("/data/logs/current", function(err, stats) {
+    if(err) throw err;
+    // Size of /data/logs/current
+    var size = stats.size;
+  });
+});
+````
 
-#### fs.open(path, flags, callback)
+#### fs.link(srcPath, dstPath, callback)<a name="link"></a>
 
-Asynchronous open(2). Flags can be
+Create a (hard) link to the file at `srcPath` named `dstPath`. Asynchronous [link(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/link.html). Callback gets no additional arguments. Links are directory entries that point to the same file node.
+
+Example:
+
+```javascript
+fs.link('/logs/august.log', '/logs/current', function(err) {
+  if(err) throw err;
+  fs.readFile('/logs/current', 'utf8', function(err, data) {
+    // data is the contents of /logs/august.log
+    var currentLog = data;
+  });
+});
+```
+
+#### fs.symlink(srcPath, dstPath, [type], callback)<a name="symlink"></a>
+
+Create a symbolic link to the file at `dstPath` containing the path `srcPath`. Asynchronous [symlink(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/symlink.html). Callback gets no additional arguments.
+Symbolic links are files that point to other paths.
+
+NOTE: Filer allows for, but ignores the optional `type` parameter used in node.js.
+
+Example:
+
+```javascript
+fs.symlink('/logs/august.log', '/logs/current', function(err) {
+  if(err) throw err;
+  fs.readFile('/logs/current', 'utf8', function(err, data) {
+    // data is the contents of /logs/august.log
+    var currentLog = data;
+  });
+});
+```
+
+#### fs.readlink(path, callback)<a name="readlink"></a>
+
+Reads the contents of a symbolic link. Asynchronous [readlink(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/readlink.html). Callback gets `(error, linkContents)`, where `linkContents` is a string containing the symbolic link's link path.
+
+Example:
+
+```javascript
+fs.symlink('/logs/august.log', '/logs/current', function(error) {
+  if(error) throw error;
+
+  fs.readlink('/logs/current', function(error, linkContents) {
+    // linkContents is now '/logs/august.log'
+  });
+});
+```
+
+#### fs.realpath(path, [cache], callback)<a name="realpath"></a>
+
+NOTE: Not yet implemented, see https://github.com/js-platform/filer/issues/85
+
+#### fs.unlink(path, callback)<a name="unlink"></a>
+
+Removes the directory entry located at `path`. Asynchronous [unlink(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/unlink.html).
+Callback gets no additional arguments. If `path` names a symbolic link, the symbolic link will be removed
+(i.e., not the linked file). Otherwise, the filed named by `path` will be removed (i.e., deleted).
+
+Example:
+
+```javascript
+// Delete regular file /backup.old
+fs.unlink('/backup.old', function(err) {
+  if(err) throw err;
+  // /backup.old is now removed
+});
+```
+
+#### fs.rmdir(path, callback)<a name="rmdir"></a>
+
+Removes the directory at `path`. Asynchronous [rmdir(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/rmdir.html).
+Callback gets no additional arguments. The operation will fail if the directory at `path` is not empty.
+
+Example:
+
+```javascript
+/**
+ * Given the following dir structure, remove docs/
+ *  /docs
+ *    a.txt
+ */
+
+// Start by deleting the files in docs/, then remove docs/
+fs.unlink('/docs/a.txt', function(err) {
+  if(err) throw err;
+  fs.rmdir('/docs', function(err) {
+    if(err) throw err;
+  });
+});
+```
+
+#### fs.mkdir(path, [mode], callback)<a name="mkdir"></a>
+
+Makes a directory with name supplied in `path` argument. Asynchronous [mkdir(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/mkdir.html). Callback gets no additional arguments.
+
+NOTE: Filer allows for, but ignores the optional `mode` argument used in node.js.
+
+Example:
+
+```javascript
+// Create /home and then /home/carl directories
+fs.mkdir('/home', function(err) {
+  if(err) throw err;
+
+  fs.mkdir('/home/carl', function(err) {
+    if(err) throw err;
+    // directory /home/carl now exists
+  });
+});
+```
+
+#### fs.readdir(path, callback)<a name="readdir"></a>
+
+Reads the contents of a directory. Asynchronous [readdir(3)](http://pubs.opengroup.org/onlinepubs/009695399/functions/readdir.html).
+Callback gets `(error, files)`, where `files` is an array containing the names of each directory entry (i.e., file, directory, link) in the directory, excluding `.` and `..`.
+
+Example:
+
+```javascript
+/**
+ * Given the following dir structure:
+ *  /docs
+ *    a.txt
+ *    b.txt
+ *    c/
+ */
+fs.readdir('/docs', function(err, files) {
+  if(err) throw err;
+  // files now contains ['a.txt', 'b.txt', 'c']
+});
+```
+
+#### fs.close(fd, callback)<a name="close"></a>
+
+Closes a file descriptor. Asynchronous [close(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/close.html).
+Callback gets no additional arguments.
+
+Example:
+
+```javascript
+fs.open('/myfile', 'w', function(err, fd) {
+  if(err) throw error;
+
+  // Do something with open file descriptor `fd`
+
+  // Close file descriptor when done
+  fs.close(fd);
+});
+```
+
+#### fs.open(path, flags, [mode], callback)<a name="open"></a>
+
+Opens a file. Asynchronous [open(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/open.html).
+Callback gets `(error, fd)`, where `fd` is the file descriptor. The `flags` argument can be:
 
 * `'r'`: Open file for reading. An exception occurs if the file does not exist.
 * `'r+'`: Open file for reading and writing. An exception occurs if the file does not exist.
@@ -257,19 +577,165 @@ Asynchronous open(2). Flags can be
 * `'a'`: Open file for appending. The file is created if it does not exist.
 * `'a+'`: Open file for reading and appending. The file is created if it does not exist.
 
-Callback gets `(error, fd)`, where `fd` is the file descriptor.
+NOTE: Filer allows for, but ignores the optional `mode` argument used in node.js.
 
-Unlike node.js, IDBFS does not accept the optional `mode` parameter since it doesn't yet implement file permissions.
+Example:
 
-#### fs.write(fd, buffer, offset, length, position, callback)
+```javascript
+fs.open('/myfile', 'w', function(err, fd) {
+  if(err) throw error;
 
-Write bytes from `buffer` to the file specified by `fd`, where `offset` and `length` describe the part of the buffer to be written. The `position` refers to the offset from the beginning of the file where this data should be written. If `position` is `null`, the data will be written at the current position. See pwrite(2).
+  // Do something with open file descriptor `fd`
 
-The callback gets `(error, nbytes)`, where `nbytes` is the number of bytes written.
+  // Close file descriptor when done
+  fs.close(fd);
+});
+```
 
-#### fs.writeFile(filename, data, [options], callback)
+#### fs.utimes(path, atime, mtime, callback)<a name="utimes"></a>
 
-Asynchronously writes data to a file. `data` can be a string or a buffer, in which case any encoding option is ignored. The `options` argument is optional, and can take the form `"utf8"` (i.e., an encoding) or be an object literal: `{ encoding: "utf8", flag: "w" }`. If no encoding is specified, and `data` is a string, the encoding defaults to `'utf8'`.  The callback gets `(error)`.
+Changes the file timestamps for the file given at path `path`. Asynchronous [utimes(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/utimes.html). Callback gets no additional arguments. Both `atime` (access time) and `mtime` (modified time) arguments should be a JavaScript Date.
+
+Example:
+
+```javascript
+var now = Date.now();
+fs.utimes('/myfile.txt', now, now, function(err) {
+  if(err) throw err;
+  // Access Time and Modified Time for /myfile.txt are now updated
+});
+```
+
+#### fs.futimes(fd, atime, mtime, callback)<a name="futimes"></a>
+
+Changes the file timestamps for the open file represented by the file descriptor `fd`. Asynchronous [utimes(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/utimes.html). Callback gets no additional arguments. Both `atime` (access time) and `mtime` (modified time) arguments should be a JavaScript Date.
+
+Example:
+
+```javascript
+fs.open('/myfile.txt', function(err, fd) {
+  if(err) throw err;
+
+  var now = Date.now();
+  fs.futimes(fd, now, now, function(err) {
+    if(err) throw err;
+
+    // Access Time and Modified Time for /myfile.txt are now updated
+
+    fs.close(fd);
+  });
+});
+```
+
+#### fs.fsync(fd, callback)<a name="fsync"></a>
+
+NOTE: Not yet implemented, see https://github.com/js-platform/filer/issues/87
+
+#### fs.write(fd, buffer, offset, length, position, callback)<a name="write"></a>
+
+Writes bytes from `buffer` to the file specified by `fd`. Asynchronous [write(2), pwrite(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/write.html). The `offset` and `length` arguments describe the part of the buffer to be written. The `position` refers to the offset from the beginning of the file where this data should be written. If `position` is `null`, the data will be written at the current position. The callback gets `(error, nbytes)`, where `nbytes` is the number of bytes written.
+
+NOTE: Filer currently writes the entire buffer in a single operation. However, future versions may do it in chunks.
+
+Example:
+
+```javascript
+// Create a file with the following bytes.
+var buffer = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
+
+fs.open('/myfile', 'w', function(err, fd) {
+  if(err) throw error;
+
+  var expected = buffer.length, written = 0;
+  function writeBytes(offset, position, length) {
+    length = length || buffer.length - written;
+
+    fs.write(fd, buffer, offset, length, position, function(err, nbytes) {
+      if(err) throw error;
+
+      // nbytes is now the number of bytes written, between 0 and buffer.length.
+      // See if we still have more bytes to write.
+      written += nbytes;
+
+      if(written < expected)
+        writeBytes(written, null);
+      else
+        fs.close(fd);
+    });
+  }
+
+  writeBytes(0, 0);
+});
+```
+
+#### fs.read(fd, buffer, offset, length, position, callback)<a name="read"></a>
+
+Read bytes from the file specified by `fd` into `buffer`. Asynchronous [read(2), pread(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/read.html). The `offset` and `length` arguments describe the part of the buffer to be used. The `position` refers to the offset from the beginning of the file where this data should be read. If `position` is `null`, the data will be written at the current position. The callback gets `(error, nbytes)`, where `nbytes` is the number of bytes read.
+
+NOTE: Filer currently reads into the buffer in a single operation. However, future versions may do it in chunks.
+
+Example:
+
+```javascript
+fs.open('/myfile', 'r', function(err, fd) {
+  if(err) throw error;
+
+  // Determine size of file
+  fs.fstat(fd, function(err, stats) {
+    if(err) throw error;
+
+    // Create a buffer large enough to hold the file's contents
+    var nbytes = expected = stats.size;
+    var buffer = new Uint8Array(nbytes);
+    var read = 0;
+
+    function readBytes(offset, position, length) {
+      length = length || buffer.length - read;
+
+      fs.read(fd, buffer, offset, length, position, function(err, nbytes) {
+        if(err) throw error;
+
+        // nbytes is now the number of bytes read, between 0 and buffer.length.
+        // See if we still have more bytes to read.
+        read += nbytes;
+
+        if(read < expected)
+          readBytes(read, null);
+        else
+          fs.close(fd);
+      });
+    }
+
+    readBytes(0, 0);
+  });
+});
+```
+
+#### fs.readFile(filename, [options], callback)<a name="readFile"></a>
+
+Reads the entire contents of a file. The `options` argument is optional, and can take the form `"utf8"` (i.e., an encoding) or be an object literal: `{ encoding: "utf8", flag: "r" }`. If no encoding is specified, the raw binary buffer is returned via the callback. The callback gets `(error, data)`, where data is the contents of the file.
+
+Examples:
+
+```javascript
+// Read UTF8 text file
+fs.readFile('/myfile.txt', 'utf8', function (err, data) {
+  if (err) throw err;
+  // data is now the contents of /myfile.txt (i.e., a String)
+});
+
+// Read binary file
+fs.readFile('/myfile.txt', function (err, data) {
+  if (err) throw err;
+  // data is now the contents of /myfile.txt (i.e., an Uint8Array of bytes)
+});
+```
+
+#### fs.writeFile(filename, data, [options], callback)<a name="writeFile"></a>
+
+Writes data to a file. `data` can be a string or a buffer, in which case any encoding option is ignored. The `options` argument is optional, and can take the form `"utf8"` (i.e., an encoding) or be an object literal: `{ encoding: "utf8", flag: "w" }`. If no encoding is specified, and `data` is a string, the encoding defaults to `'utf8'`.  The callback gets `(error)`.
+
+Examples:
 
 ```javascript
 // Write UTF8 text file
@@ -278,93 +744,148 @@ fs.writeFile('/myfile.txt', "...data...", function (err) {
 });
 
 // Write binary file
+var buffer = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
 fs.writeFile('/myfile', buffer, function (err) {
   if (err) throw err;
 });
 ```
 
-#### fs.read(fd, buffer, offset, length, position, callback)
+#### fs.appendFile(filename, data, [options], callback)<a name="appendFile"></a>
 
-Read bytes from the file specified by `fd` into `buffer`, where `offset` and `length` describe the part of the buffer to be used. The `position` refers to the offset from the beginning of the file where this data should be read. If `position` is `null`, the data will be written at the current position. See pread(2).
+NOTE: Not yet implemented, see https://github.com/js-platform/filer/issues/88
 
-The callback gets `(error, nbytes)`, where `nbytes` is the number of bytes read.
+#### fs.setxattr(path, name, value, [flag], callback)<a name="setxattr"></a>
 
-#### fs.readFile(filename, [options], callback)
+Sets an extended attribute of a file or directory named `path`. Asynchronous [setxattr(2)](http://man7.org/linux/man-pages/man2/setxattr.2.html).
-
+The optional `flag` parameter can be set to the following:
-Asynchronously reads the entire contents of a file. The `options` argument is optional, and can take the form `"utf8"` (i.e., an encoding) or be an object literal: `{ encoding: "utf8", flag: "r" }`. If no encoding is specified, the raw binary buffer is returned on the callback. The callback gets `(error, data)`, where data is the contents of the file.
+* `XATTR_CREATE`: ensures that the extended attribute with the given name will be new and not previously set. If an attribute with the given name already exists, it will return an `EExists` error to the callback.
-
+* `XATTR_REPLACE`: ensures that an extended attribute with the given name already exists. If an attribute with the given name does not exist, it will return an `ENoAttr` error to the callback.
-```javascript
-// Read UTF8 text file
-fs.readFile('/myfile.txt', 'utf8', function (err, data) {
-  if (err) throw err;
-  console.log(data);
-});
-
-// Read binary file
-fs.readFile('/myfile.txt', function (err, data) {
-  if (err) throw err;
-  console.log(data);
-});
-```
-
-#### fs.lseek(fd, offset, whence, callback)
-
-Asynchronous lseek(2), where `whence` can be `SET`, `CUR`, or `END`. Callback gets `(error, pos)`, where `pos` is the resulting offset, in bytes, from the beginning of the file.
-
-#### fs.readdir(path, callback)
-
-Asynchronous readdir(3). Reads the contents of a directory. Callback gets `(error, files)`, where `files` is an array containing the names of each file in the directory, excluding `.` and `..`.
-
-#### fs.symlink(srcPath, dstPath, callback)
-
-Asynchronous symlink(2). Callback gets no additional arguments.
-
-Unlike node.js, IDBFS does not accept the optional `type` parameter.
-
-#### fs.readlink(path, callback)
-
-Asynchronous readlink(2). Callback gets `(error, linkContents)`, where `linkContents` is a string containing the path to which the symbolic link links to.
-
-#### fs.lstat(path, callback)
-
-Asynchronous lstat(2). Callback gets `(error, stats)`, See `fs.stat`.
-
-#### fs.truncate(path, length, callback)
-
-Asynchronous truncate(2). Callback gets no additional arguments.
-
-#### fs.ftruncate(fd, length, callback)
-
-Asynchronous ftruncate(2). Callback gets no additional arguments.
-
-#### fs.utimes(path, atime, mtime, callback)
-
-Asynchronous utimes(3). Callback gets no additional arguments.
-
-#### fs.futimes(fd, atime, mtime, callback)
-
-Asynchronous futimes(3). Callback gets no additional arguments.
-
-#### fs.setxattr(path, name, value, [flag], callback)
-
-Asynchronous setxattr(2). Sets an extended attribute of a file or directory. 
-
-The optional flag parameter can be set to the following:
-  XATTR_CREATE: ensures that the extended attribute with the given name will be new and not previously set. If  an attribute with the given name already exists, it will return EExists error to the callback.
-  XATTR_REPLACE: ensures that an extended attribute with the given name already exists. If an attribute with the given name does not exist, it will return an ENoAttr error to the callback.
 
 Callback gets no additional arguments.
 
-#### fs.getxattr(path, name, callback)
+Example:
 
-Asynchronous getxattr(2). Gets an extended attribute value for a file or directory.
+```javascript
+fs.writeFile('/myfile', 'data', function(err) {
+  if(err) throw err;
 
-Callback gets `(error, value)`, where value is the value for the extended attribute.
+  // Set a simple extended attribute on /myfile
+  fs.setxattr('/myfile', 'extra', 'some-information', function(err) {
+    if(err) throw err;
 
-#### fs.fsetxattr(fd, name, value, [flag], callback)
+    // /myfile now has an added attribute of extra='some-information'
+  });
 
-Asynchronous fsetxattr(2). See `fs.setxattr` for flag options. Callback gets no additional arguments.
+  // Set a complex object attribute on /myfile
+  fs.setxattr('/myfile', 'extra-complex', { key1: 'value1', key2: 103 }, function(err) {
+    if(err) throw err;
 
-#### fs.fgetxattr(fs, name, callback)
+    // /myfile now has an added attribute of extra={ key1: 'value1', key2: 103 }
+  });
+});
+```
 
-Asynchronous fgetxattr(2). Callback gets `(error, value)`, See `fs.getxattr`.
+#### fs.fsetxattr(fd, name, value, [flag], callback)<a name="fsetxattr"></a>
+
+Sets an extended attribute of the file represented by the open file descriptor `fd`. Asynchronous [setxattr(2)](http://man7.org/linux/man-pages/man2/setxattr.2.html).  See `fs.setxattr` for more details. Callback gets no additional arguments.
+
+Example:
+
+```javascript
+fs.open('/myfile', 'w', function(err, fd) {
+  if(err) throw err;
+
+  // Set a simple extended attribute on fd for /myfile
+  fs.fsetxattr(fd, 'extra', 'some-information', function(err) {
+    if(err) throw err;
+
+    // /myfile now has an added attribute of extra='some-information'
+  });
+
+  // Set a complex object attribute on fd for /myfile
+  fs.fsetxattr(fd, 'extra-complex', { key1: 'value1', key2: 103 }, function(err) {
+    if(err) throw err;
+
+    // /myfile now has an added attribute of extra={ key1: 'value1', key2: 103 }
+  });
+
+  fs.close(fd);
+});
+```
+
+#### fs.getxattr(path, name, callback)<a name="getxattr"></a>
+
+Gets an extended attribute value for a file or directory. Asynchronous [getxattr(2)](http://man7.org/linux/man-pages/man2/getxattr.2.html).
+Callback gets `(error, value)`, where `value` is the value for the extended attribute named `name`.
+
+Example:
+
+```javascript
+// Get the value of the extended attribute on /myfile named `extra`
+fs.getxattr('/myfile', 'extra', function(err, value) {
+  if(err) throw err;
+
+  // `value` is now the value of the extended attribute named `extra` for /myfile
+});
+```
+
+#### fs.fgetxattr(fd, name, callback)<a name="fgetxattr"></a>
+
+Gets an extended attribute value for the file represented by the open file descriptor `fd`.
+Asynchronous [getxattr(2)](http://man7.org/linux/man-pages/man2/getxattr.2.html).
+See `fs.getxattr` for more details. Callback gets `(error, value)`, where `value` is the value for the extended attribute named `name`.
+
+Example:
+
+```javascript
+// Get the value of the extended attribute on /myfile named `extra`
+fs.open('/myfile', 'r', function(err, fd) {
+  if(err) throw err;
+
+  fs.fgetxattr(fd, 'extra', function(err, value) {
+    if(err) throw err;
+
+    // `value` is now the value of the extended attribute named `extra` for /myfile
+  });
+
+  fs.close(fd);
+});
+```
+
+#### fs.removexattr(path, name, callback)<a name="removexattr"></a>
+
+Removes the extended attribute identified by `name` for the file given at `path`. Asynchronous [removexattr(2)](http://man7.org/linux/man-pages/man2/removexattr.2.html). Callback gets no additional arguments.
+
+Example:
+
+```javascript
+// Remove an extended attribute on /myfile
+fs.removexattr('/myfile', 'extra', function(err) {
+  if(err) throw err;
+
+  // The `extra` extended attribute on /myfile is now gone
+});
+```
+
+#### fs.fremovexattr(fd, name, callback)<a name="fremovexattr"></a>
+
+Removes the extended attribute identified by `name` for the file represented by the open file descriptor `fd`.
+Asynchronous [removexattr(2)](http://man7.org/linux/man-pages/man2/removexattr.2.html). See `fs.removexattr` for more details.
+Callback gets no additional arguments.
+
+Example:
+
+```javascript
+// Remove an extended attribute on /myfile
+fs.open('/myfile', 'r', function(err, fd) {
+  if(err) throw err;
+
+  fs.fremovexattr(fd, 'extra', function(err) {
+    if(err) throw err;
+
+    // The `extra` extended attribute on /myfile is now gone
+  });
+
+  fs.close(fd);
+});
+```

build/wrap.end

@@ -1,7 +1,7 @@
 
-  var IDBFS = require( "src/index" );
+  var Filer = require( "src/index" );
 
-  return IDBFS;
+  return Filer;
 
 }));
 

build/wrap.start

@@ -19,9 +19,9 @@ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
   } else if (typeof define === "function" && define.amd) {
     // AMD. Register as an anonymous module.
     define( factory );
-  } else if( !root.IDBFS ) {
+  } else if( !root.Filer ) {
     // Browser globals
-    root.IDBFS = factory();
+    root.Filer = factory();
   }
 
 }( this, function() {

examples/refactoring-test.html

@@ -8,8 +8,8 @@
 </body>
 <script src="../dist/idbfs.js"></script>
 <script>
-window.IDBFS = IDBFS;
+window.Filer = Filer;
-var fs = new IDBFS.FileSystem({
+var fs = new Filer.FileSystem({
         name: 'local',
         flags: ['FORMAT']
       });

examples/test5.html

@@ -1,7 +1,7 @@
 var write_buffer = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]);
 var read_buffer = new Uint8Array(16);
 
-var fs = new FileSystem('local');
+var fs = new Filer.FileSystem('local');
 fs.mkdir('/tmp');
 fs.open('/tmp/', 'w+', function(error, fd) {
   if(error) return console.error(error);

gruntfile.js

@@ -11,8 +11,8 @@ module.exports = function(grunt) {
         banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n'
       },
       develop: {
-        src: 'dist/idbfs.js',
+        src: 'dist/filer.js',
-        dest: 'dist/idbfs.min.js'
+        dest: 'dist/filer.min.js'
       }
     },
 
@@ -38,7 +38,7 @@ module.exports = function(grunt) {
           baseUrl: "lib",
           name: "build/almond",
           include: ["src/index"],
-          out: "dist/idbfs.js",
+          out: "dist/filer.js",
           optimize: "none",
           wrap: {
             startFile: 'build/wrap.start',

src/providers/providers.js

@@ -27,7 +27,7 @@ define(function(require) {
       }
 
       function NotSupported() {
-        throw "[IDBFS Error] Your browser doesn't support IndexedDB or WebSQL.";
+        throw "[Filer Error] Your browser doesn't support IndexedDB or WebSQL.";
       }
       NotSupported.isSupported = function() {
         return false;

tests/require-config.js

@@ -8,7 +8,7 @@ require.config({
     "tests": "../tests",
     "src": "../src",
     "spec": "../tests/spec",
-    "IDBFS": "../src/index"
+    "Filer": "../src/index"
   },
   baseUrl: "../lib",
   optimize: "none",

tests/spec/adapters/adapters.general.spec.js

@@ -1,4 +1,4 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   // We reuse the same set of tests for all adapters.
   // buildTestsFor() creates a set of tests bound to an
@@ -6,7 +6,7 @@ define(["IDBFS"], function(IDBFS) {
 
   function buildTestsFor(adapterName, buildAdapter) {
     function encode(str) {
-      // TextEncoder is either native, or shimmed by IDBFS
+      // TextEncoder is either native, or shimmed by Filer
       return (new TextEncoder("utf-8")).encode(str);
     }
 
@@ -16,15 +16,15 @@ define(["IDBFS"], function(IDBFS) {
     var value2Str = "value2", value2Buffer = encode(value2Str);
 
     function createProvider() {
-      var memoryProvider = new IDBFS.FileSystem.providers.Memory();
+      var memoryProvider = new Filer.FileSystem.providers.Memory();
       return buildAdapter(memoryProvider);
     }
 
-    describe("IDBFS.FileSystem.adapters." + adapterName, function() {
+    describe("Filer.FileSystem.adapters." + adapterName, function() {
       it("is supported -- if it isn't, none of these tests can run.", function() {
         // Allow for combined adapters (e.g., 'AES+Zlib') joined by '+'
         adapterName.split('+').forEach(function(name) {
-          expect(IDBFS.FileSystem.adapters[name].isSupported()).toEqual(true);
+          expect(Filer.FileSystem.adapters[name].isSupported()).toEqual(true);
         });
       });
 
@@ -200,27 +200,27 @@ define(["IDBFS"], function(IDBFS) {
   // Encryption
   buildTestsFor('AES', function buildAdapter(provider) {
     var passphrase = '' + Date.now();
-    return new IDBFS.FileSystem.adapters.AES(passphrase, provider);
+    return new Filer.FileSystem.adapters.AES(passphrase, provider);
   });
   buildTestsFor('TripleDES', function buildAdapter(provider) {
     var passphrase = '' + Date.now();
-    return new IDBFS.FileSystem.adapters.TripleDES(passphrase, provider);
+    return new Filer.FileSystem.adapters.TripleDES(passphrase, provider);
   });
   buildTestsFor('Rabbit', function buildAdapter(provider) {
     var passphrase = '' + Date.now();
-    return new IDBFS.FileSystem.adapters.Rabbit(passphrase, provider);
+    return new Filer.FileSystem.adapters.Rabbit(passphrase, provider);
   });
 
   // Compression
   buildTestsFor('Zlib', function buildAdapter(provider) {
-    return new IDBFS.FileSystem.adapters.Zlib(provider);
+    return new Filer.FileSystem.adapters.Zlib(provider);
   });
 
   // AES + Zlib together
   buildTestsFor('AES+Zlib', function buildAdapter(provider) {
     var passphrase = '' + Date.now();
-    var zlib = new IDBFS.FileSystem.adapters.Zlib(provider);
+    var zlib = new Filer.FileSystem.adapters.Zlib(provider);
-    var AESwithZlib = new IDBFS.FileSystem.adapters.AES(passphrase, zlib);
+    var AESwithZlib = new Filer.FileSystem.adapters.AES(passphrase, zlib);
     return AESwithZlib;
   });
 

tests/spec/adapters/adapters.spec.js

@@ -1,31 +1,31 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
-  describe("IDBFS.FileSystem.adapters", function() {
+  describe("Filer.FileSystem.adapters", function() {
     it("is defined", function() {
-      expect(typeof IDBFS.FileSystem.adapters).not.toEqual(undefined);
+      expect(typeof Filer.FileSystem.adapters).not.toEqual(undefined);
     });
 
     it("has an AES constructor", function() {
-      expect(typeof IDBFS.FileSystem.adapters.AES).toEqual('function');
+      expect(typeof Filer.FileSystem.adapters.AES).toEqual('function');
     });
 
     it("has a TripleDES constructor", function() {
-      expect(typeof IDBFS.FileSystem.adapters.TripleDES).toEqual('function');
+      expect(typeof Filer.FileSystem.adapters.TripleDES).toEqual('function');
     });
 
     it("has a Rabbit constructor", function() {
-      expect(typeof IDBFS.FileSystem.adapters.Rabbit).toEqual('function');
+      expect(typeof Filer.FileSystem.adapters.Rabbit).toEqual('function');
     });
 
     it("has a default Encryption constructor", function() {
-      expect(typeof IDBFS.FileSystem.adapters.Encryption).toEqual('function');
+      expect(typeof Filer.FileSystem.adapters.Encryption).toEqual('function');
     });
 
     it("has a Zlib constructor", function() {
-      expect(typeof IDBFS.FileSystem.adapters.Zlib).toEqual('function');
+      expect(typeof Filer.FileSystem.adapters.Zlib).toEqual('function');
     });
 
     it("has a default Compression constructor", function() {
-      expect(typeof IDBFS.FileSystem.adapters.Compression).toEqual('function');
+      expect(typeof Filer.FileSystem.adapters.Compression).toEqual('function');
     });
   });
 });

tests/spec/filer.spec.js

@@ -0,0 +1,13 @@
+define(["Filer"], function(Filer) {
+
+  describe("Filer", function() {
+    it("is defined", function() {
+      expect(typeof Filer).not.toEqual(undefined);
+    });
+
+    it("has FileSystem constructor", function() {
+      expect(typeof Filer.FileSystem).toEqual('function');
+    });
+  });
+
+});

tests/spec/fs.close.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe('fs.close', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.link.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe('fs.link', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.lseek.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe('fs.lseek', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.lstat.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
  describe('fs.lstat', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.mkdir.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
  describe('fs.mkdir', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.open.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe('fs.open', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.read.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe('fs.read', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.readdir.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
  describe('fs.readdir', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.readlink.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe('fs.readlink', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.rename.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe('fs.rename', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.rmdir.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
  describe('fs.rmdir', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe("fs", function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.stat.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe('fs.stat', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.symlink.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe('fs.symlink', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.truncate.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe('fs.truncate', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.unlink.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe('fs.unlink', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.utimes.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe('fs.utimes', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.write.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe('fs.write', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/fs.writeFile-readFile.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe('fs.writeFile, fs.readFile', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/idbfs.spec.js

@@ -1,13 +0,0 @@
-define(["IDBFS"], function(IDBFS) {
-
-  describe("IDBFS", function() {
-    it("is defined", function() {
-      expect(typeof IDBFS).not.toEqual(undefined);
-    });
-
-    it("has FileSystem constructor", function() {
-      expect(typeof IDBFS.FileSystem).toEqual('function');
-    });
-  });
-
-});

tests/spec/node-js/simple/test-fs-mkdir.js

@@ -1,10 +1,10 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe("node.js tests: https://github.com/joyent/node/blob/master/test/simple/test-fs-mkdir.js", function() {
 
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/node-js/simple/test-fs-null-bytes.js

@@ -1,10 +1,10 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe("node.js tests: https://github.com/joyent/node/blob/master/test/simple/test-fs-null-bytes.js", function() {
 
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/path-resolution.spec.js

@@ -1,9 +1,9 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   describe('path resolution', function() {
     beforeEach(function() {
       this.db_name = mk_db_name();
-      this.fs = new IDBFS.FileSystem({
+      this.fs = new Filer.FileSystem({
         name: this.db_name,
         flags: 'FORMAT'
       });

tests/spec/providers/providers.indexeddb.spec.js

@@ -1,12 +1,12 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
-  describe("IDBFS.FileSystem.providers.IndexedDB", function() {
+  describe("Filer.FileSystem.providers.IndexedDB", function() {
     it("is supported -- if it isn't, none of these tests can run.", function() {
-      expect(IDBFS.FileSystem.providers.IndexedDB.isSupported()).toEqual(true);
+      expect(Filer.FileSystem.providers.IndexedDB.isSupported()).toEqual(true);
     });
 
     it("has open, getReadOnlyContext, and getReadWriteContext instance methods", function() {
-      var indexedDBProvider = new IDBFS.FileSystem.providers.IndexedDB();
+      var indexedDBProvider = new Filer.FileSystem.providers.IndexedDB();
       expect(typeof indexedDBProvider.open).toEqual('function');
       expect(typeof indexedDBProvider.getReadOnlyContext).toEqual('function');
       expect(typeof indexedDBProvider.getReadWriteContext).toEqual('function');
@@ -25,7 +25,7 @@ define(["IDBFS"], function(IDBFS) {
         var complete = false;
         var _error, _result;
 
-        var provider = new IDBFS.FileSystem.providers.IndexedDB(this.db_name);
+        var provider = new Filer.FileSystem.providers.IndexedDB(this.db_name);
         provider.open(function(err, firstAccess) {
           _error = err;
           _result = firstAccess;
@@ -56,7 +56,7 @@ define(["IDBFS"], function(IDBFS) {
         var complete = false;
         var _error, _result;
 
-        var provider = new IDBFS.FileSystem.providers.IndexedDB(this.db_name);
+        var provider = new Filer.FileSystem.providers.IndexedDB(this.db_name);
         provider.open(function(err, firstAccess) {
           _error = err;
 
@@ -86,7 +86,7 @@ define(["IDBFS"], function(IDBFS) {
         var complete = false;
         var _error, _result;
 
-        var provider = new IDBFS.FileSystem.providers.IndexedDB(this.db_name);
+        var provider = new Filer.FileSystem.providers.IndexedDB(this.db_name);
         provider.open(function(err, firstAccess) {
           _error = err;
 
@@ -119,7 +119,7 @@ define(["IDBFS"], function(IDBFS) {
         var complete = false;
         var _error, _result1, _result2;
 
-        var provider = new IDBFS.FileSystem.providers.IndexedDB(this.db_name);
+        var provider = new Filer.FileSystem.providers.IndexedDB(this.db_name);
         provider.open(function(err, firstAccess) {
           _error = err;
 
@@ -163,7 +163,7 @@ define(["IDBFS"], function(IDBFS) {
         var complete = false;
         var _error, _result;
 
-        var provider = new IDBFS.FileSystem.providers.IndexedDB(this.db_name);
+        var provider = new Filer.FileSystem.providers.IndexedDB(this.db_name);
         provider.open(function(err, firstAccess) {
           _error = err;
 

tests/spec/providers/providers.memory.spec.js

@@ -1,12 +1,12 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
   
-  describe("IDBFS.FileSystem.providers.Memory", function() {
+  describe("Filer.FileSystem.providers.Memory", function() {
     it("is supported -- if it isn't, none of these tests can run.", function() {
-      expect(IDBFS.FileSystem.providers.Memory.isSupported()).toEqual(true);
+      expect(Filer.FileSystem.providers.Memory.isSupported()).toEqual(true);
     });
 
     it("has open, getReadOnlyContext, and getReadWriteContext instance methods", function() {
-      var indexedDBProvider = new IDBFS.FileSystem.providers.Memory();
+      var indexedDBProvider = new Filer.FileSystem.providers.Memory();
       expect(typeof indexedDBProvider.open).toEqual('function');
       expect(typeof indexedDBProvider.getReadOnlyContext).toEqual('function');
       expect(typeof indexedDBProvider.getReadWriteContext).toEqual('function');
@@ -17,7 +17,7 @@ define(["IDBFS"], function(IDBFS) {
         var complete = false;
         var _error, _result;
 
-        var provider = new IDBFS.FileSystem.providers.Memory(this.db_name);
+        var provider = new Filer.FileSystem.providers.Memory(this.db_name);
         provider.open(function(err, firstAccess) {
           _error = err;
           _result = firstAccess;
@@ -40,7 +40,7 @@ define(["IDBFS"], function(IDBFS) {
         var complete = false;
         var _error, _result;
 
-        var provider = new IDBFS.FileSystem.providers.Memory(this.db_name);
+        var provider = new Filer.FileSystem.providers.Memory(this.db_name);
         provider.open(function(err, firstAccess) {
           _error = err;
 
@@ -70,7 +70,7 @@ define(["IDBFS"], function(IDBFS) {
         var complete = false;
         var _error, _result;
 
-        var provider = new IDBFS.FileSystem.providers.Memory(this.db_name);
+        var provider = new Filer.FileSystem.providers.Memory(this.db_name);
         provider.open(function(err, firstAccess) {
           _error = err;
 
@@ -103,7 +103,7 @@ define(["IDBFS"], function(IDBFS) {
         var complete = false;
         var _error, _result1, _result2;
 
-        var provider = new IDBFS.FileSystem.providers.Memory(this.db_name);
+        var provider = new Filer.FileSystem.providers.Memory(this.db_name);
         provider.open(function(err, firstAccess) {
           _error = err;
 
@@ -147,7 +147,7 @@ define(["IDBFS"], function(IDBFS) {
         var complete = false;
         var _error, _result;
 
-        var provider = new IDBFS.FileSystem.providers.Memory(this.db_name);
+        var provider = new Filer.FileSystem.providers.Memory(this.db_name);
         provider.open(function(err, firstAccess) {
           _error = err;
 

tests/spec/providers/providers.spec.js

@@ -1,27 +1,27 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
-  describe("IDBFS.FileSystem.providers", function() {
+  describe("Filer.FileSystem.providers", function() {
     it("is defined", function() {
-      expect(typeof IDBFS.FileSystem.providers).not.toEqual(undefined);
+      expect(typeof Filer.FileSystem.providers).not.toEqual(undefined);
     });
 
     it("has IndexedDB constructor", function() {
-      expect(typeof IDBFS.FileSystem.providers.IndexedDB).toEqual('function');
+      expect(typeof Filer.FileSystem.providers.IndexedDB).toEqual('function');
     });
 
     it("has WebSQL constructor", function() {
-      expect(typeof IDBFS.FileSystem.providers.WebSQL).toEqual('function');
+      expect(typeof Filer.FileSystem.providers.WebSQL).toEqual('function');
     });
 
     it("has Memory constructor", function() {
-      expect(typeof IDBFS.FileSystem.providers.Memory).toEqual('function');
+      expect(typeof Filer.FileSystem.providers.Memory).toEqual('function');
     });
 
     it("has a Default constructor", function() {
-      expect(typeof IDBFS.FileSystem.providers.Default).toEqual('function');
+      expect(typeof Filer.FileSystem.providers.Default).toEqual('function');
     });
 
     it("has Fallback constructor", function() {
-      expect(typeof IDBFS.FileSystem.providers.Fallback).toEqual('function');
+      expect(typeof Filer.FileSystem.providers.Fallback).toEqual('function');
     });
   });
 });

tests/spec/providers/providers.websql.spec.js

@@ -1,4 +1,4 @@
-define(["IDBFS"], function(IDBFS) {
+define(["Filer"], function(Filer) {
 
   var WEBSQL_NAME = "websql-test-db";
 
@@ -11,18 +11,18 @@ define(["IDBFS"], function(IDBFS) {
     });
   }
 
-  if(!IDBFS.FileSystem.providers.WebSQL.isSupported()) {
+  if(!Filer.FileSystem.providers.WebSQL.isSupported()) {
-    console.log("Skipping IDBFS.FileSystem.providers.WebSQL tests, since WebSQL isn't supported.");
+    console.log("Skipping Filer.FileSystem.providers.WebSQL tests, since WebSQL isn't supported.");
     return;
   }
 
-  describe("IDBFS.FileSystem.providers.WebSQL", function() {
+  describe("Filer.FileSystem.providers.WebSQL", function() {
     it("is supported -- if it isn't, none of these tests can run.", function() {
-      expect(IDBFS.FileSystem.providers.WebSQL.isSupported()).toEqual(true);
+      expect(Filer.FileSystem.providers.WebSQL.isSupported()).toEqual(true);
     });
 
     it("has open, getReadOnlyContext, and getReadWriteContext instance methods", function() {
-      var webSQLProvider = new IDBFS.FileSystem.providers.WebSQL();
+      var webSQLProvider = new Filer.FileSystem.providers.WebSQL();
       expect(typeof webSQLProvider.open).toEqual('function');
       expect(typeof webSQLProvider.getReadOnlyContext).toEqual('function');
       expect(typeof webSQLProvider.getReadWriteContext).toEqual('function');
@@ -37,7 +37,7 @@ define(["IDBFS"], function(IDBFS) {
         var complete = false;
         var _error, _result;
 
-        var provider = this.provider = new IDBFS.FileSystem.providers.WebSQL(WEBSQL_NAME);
+        var provider = this.provider = new Filer.FileSystem.providers.WebSQL(WEBSQL_NAME);
         provider.open(function(err, firstAccess) {
           _error = err;
           _result = firstAccess;
@@ -64,7 +64,7 @@ define(["IDBFS"], function(IDBFS) {
         var complete = false;
         var _error, _result;
 
-        var provider = this.provider = new IDBFS.FileSystem.providers.WebSQL(WEBSQL_NAME);
+        var provider = this.provider = new Filer.FileSystem.providers.WebSQL(WEBSQL_NAME);
         provider.open(function(err, firstAccess) {
           _error = err;
 
@@ -94,7 +94,7 @@ define(["IDBFS"], function(IDBFS) {
         var complete = false;
         var _error, _result;
 
-        var provider = this.provider = new IDBFS.FileSystem.providers.WebSQL(WEBSQL_NAME);
+        var provider = this.provider = new Filer.FileSystem.providers.WebSQL(WEBSQL_NAME);
         provider.open(function(err, firstAccess) {
           _error = err;
 
@@ -127,7 +127,7 @@ define(["IDBFS"], function(IDBFS) {
         var complete = false;
         var _error, _result1, _result2;
 
-        var provider = this.provider = new IDBFS.FileSystem.providers.WebSQL(WEBSQL_NAME);
+        var provider = this.provider = new Filer.FileSystem.providers.WebSQL(WEBSQL_NAME);
         provider.open(function(err, firstAccess) {
           _error = err;
 
@@ -171,7 +171,7 @@ define(["IDBFS"], function(IDBFS) {
         var complete = false;
         var _error, _result;
 
-        var provider = this.provider = new IDBFS.FileSystem.providers.WebSQL(WEBSQL_NAME);
+        var provider = this.provider = new Filer.FileSystem.providers.WebSQL(WEBSQL_NAME);
         provider.open(function(err, firstAccess) {
           _error = err;
 

tests/test-manifest.js

@@ -5,10 +5,10 @@ define([
    * get them running by default.
    */
 
-  // IDBFS
+  // Filer
-  "spec/idbfs.spec",
+  "spec/filer.spec",
 
-  // IDBFS.FileSystem.*
+  // Filer.FileSystem.*
   "spec/fs.spec",
   "spec/fs.stat.spec",
   "spec/fs.lstat.spec",
@@ -31,13 +31,13 @@ define([
   "spec/fs.xattr.spec",
   "spec/path-resolution.spec",
 
-  // IDBFS.FileSystem.providers.*
+  // Filer.FileSystem.providers.*
   "spec/providers/providers.spec",
   "spec/providers/providers.memory.spec",
   "spec/providers/providers.indexeddb.spec",
   "spec/providers/providers.websql.spec",
 
-  // IDBFS.FileSystem.adapters.*
+  // Filer.FileSystem.adapters.*
   "spec/adapters/adapters.spec",
   "spec/adapters/adapters.general.spec",