v1.3.0

* XHRFS with synchronous listings download is now deprecated. Will be removed next major version (2.0). * Made BFS amenable to API documentation. We now have API documenation. :) * Added XHRFS static method to construct asynchronously from listings URL.
jvilk · Mar 19, 2017 · 8977a70 · 8977a70
1 parent 424547a
commit 8977a70
Show file tree

Hide file tree

Showing 34 changed files with 952 additions and 238 deletions.
diff --git a/LICENSE b/LICENSE
@@ -2,7 +2,7 @@ BrowserFS's license follows:
 
 ====
 
-Copyright (c) 2013, 2014, 2015, 2016 John Vilk and other BrowserFS contributors.
+Copyright (c) 2013, 2014, 2015, 2016, 2017 John Vilk and other BrowserFS contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# BrowserFS v1.2.1
+# BrowserFS v1.3.0
 > BrowserFS is an in-browser file system that emulates the [Node JS file system API](http://nodejs.org/api/fs.html) and supports storing and retrieving files from various backends. BrowserFS also integrates nicely into the Emscripten file system.
 
 [![Build Status](https://travis-ci.org/jvilk/BrowserFS.svg?branch=master)](https://travis-ci.org/jvilk/BrowserFS)
@@ -33,7 +33,7 @@ BrowserFS is highly extensible, and ships with many filesystem backends:
 
 More backends can be defined by separate libraries, so long as they extend the `BaseFileSystem`. Multiple backends can be active at once at different locations in the directory hierarchy.
 
-For more information, see the [wiki](https://github.com/jvilk/BrowserFS/wiki).
+For more information, see the [API documentation for BrowserFS](https://jvilk.com/browserfs/1.3.0/index.html).
 
 ### Building
 

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "browserfs",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "A filesystem in your browser!",
   "main": "dist/browserfs.js",
   "typings": "dist/browserfs",
@@ -102,7 +102,8 @@
     "test:prepare": "npm-run-all build:scripts script:make_fixture_loader script:make_test_launcher test:build script:make_zip_fixtures script:make_xhrfs_index",
     "test": "npm-run-all test:prepare test:karma",
     "watch-test": "npm-run-all test:prepare --parallel watch:scripts test:watch test:karma",
-    "prepublish": "npm run dist"
+    "prepublish": "npm run dist",
+    "docs": "typedoc --mode file --out doc --excludePrivate --readme src/DOCS.md --name BrowserFS src"
   },
   "dependencies": {
     "async": "^2.1.4",

diff --git a/src/DOCS.md b/src/DOCS.md
@@ -0,0 +1,138 @@
+# BrowserFS API Documentation
+
+BrowserFS is an in-browser file system that emulates the [Node JS file system API](http://nodejs.org/api/fs.html) and supports storing and retrieving files from various backends. BrowserFS also integrates nicely into the Emscripten file system.
+
+The [README](https://github.com/jvilk/browserfs) provides an overview of how to integrate BrowserFS into your project. This API documentation will focus on how to use BrowserFS once you have added it to your project.
+
+## BrowserFS Interface
+
+The main BrowserFS interface is [documented here](interfaces/browserfs.html).
+
+Before you can use BrowserFS, you must initialize it with a single root file system backend using `BrowserFS.initialize`. Think of this as your "storage device".
+
+If you need to use multiple "storage devices", instantiate multiple file system backend types, mount them into a `MountableFileSystem` backend, and then use that as the root file system for BrowserFS.
+
+There are all sorts of adapter file systems available to make it easy to access files stored in Emscripten, files stored in a different context (e.g., a web worker), isolate file operations to a particular folder, access asynchronous storage backends synchronously, and more!
+
+## Overview of Backends
+
+**Key:**
+
+* ✓ means 'yes'
+* ✗ means 'no'
+* ? means 'depends on configuration'
+
+Note that any asynchronous file system can be accessed synchronously using the [AsyncMirror](classes/asyncmirror.html) file system.
+
+<table>
+  <tr>
+    <th></th>
+    <th></th>
+    <th colspan="3">Optional API Support</th>
+  </tr>
+  <tr>
+    <th>Backend Name</th>
+    <th>Read-only?</th>
+    <th>Synchronous</th>
+    <th>Properties</th>
+    <th>Links</th>
+  </tr>
+  <tr>
+    <td><a href="classes/asyncmirror.html">AsyncMirror</a></td>
+    <td>✗</td>
+    <td>✓</td>
+    <td>✗</td>
+    <td>✗</td>
+  </tr>
+  <tr>
+    <td><a href="classes/dropboxfilesystem.html">Dropbox</a></td>
+    <td>✗</td>
+    <td>✗</td>
+    <td>✗</td>
+    <td>✗</td>
+  </tr>
+  <tr>
+    <td><a href="classes/emscriptenfilesystem.html">Emscripten</a></td>
+    <td>✗</td>
+    <td>✓</td>
+    <td>✓</td>
+    <td>✓</td>
+  </tr>
+  <tr>
+    <td><a href="classes/folderadapter.html">FolderAdapter</a></td>
+    <td>?</td>
+    <td>?</td>
+    <td>?</td>
+    <td>✗</td>
+  </tr>
+  <tr>
+    <td><a href="classes/html5fs.html">HTML5FS</a></td>
+    <td>✗</td>
+    <td>✗</td>
+    <td>✗</td>
+    <td>✗</td>
+  </tr>
+  <tr>
+    <td><a href="classes/indexeddbfilesystem.html">IndexedDB</a></td>
+    <td>✗</td>
+    <td>✗</td>
+    <td>✗</td>
+    <td>✗</td>
+  </tr>
+  <tr>
+    <td><a href="classes/inmemoryfilesystem.html">InMemory</a></td>
+    <td>✗</td>
+    <td>✓</td>
+    <td>✗</td>
+    <td>✗</td>
+  </tr>
+  <tr>
+    <td><a href="classes/isofs.html">IsoFS</a></td>
+    <td>✓</td>
+    <td>✓</td>
+    <td>✗</td>
+    <td>✗</td>
+  </tr>
+  <tr>
+    <td><a href="classes/localstoragefilesystem.html">LocalStorage</a></td>
+    <td>✗</td>
+    <td>✓</td>
+    <td>✗</td>
+    <td>✗</td>
+  </tr>
+  <tr>
+    <td><a href="classes/mountablefilesystem.html">MountableFileSystem</a></td>
+    <td>?</td>
+    <td>?</td>
+    <td>?</td>
+    <td>?</td>
+  </tr>
+  <tr>
+    <td><a href="classes/overlayfs.html">OverlayFS</a></td>
+    <td>✗</td>
+    <td>?</td>
+    <td>?</td>
+    <td>✗</td>
+  </tr>
+  <tr>
+    <td><a href="classes/xmlhttprequest.html">XmlHttpRequest</a></td>
+    <td>✓</td>
+    <td>✓</td>
+    <td>✗</td>
+    <td>✗</td>
+  </tr>
+  <tr>
+    <td><a href="classes/workerfs.html">WorkerFS</a></td>
+    <td>?</td>
+    <td>✗</td>
+    <td>?</td>
+    <td>?</td>
+  </tr>
+  <tr>
+    <td><a href="classes/zipfs.html">ZipFS</a></td>
+    <td>✓</td>
+    <td>✓</td>
+    <td>✗</td>
+    <td>✗</td>
+  </tr>
+</table>
diff --git a/src/backend/AsyncMirror.ts b/src/backend/AsyncMirror.ts
@@ -6,6 +6,9 @@ import Stats from '../core/node_fs_stats';
 import PreloadFile from '../generic/preload_file';
 import * as path from 'path';
 
+/**
+ * @hidden
+ */
 interface IAsyncOperation {
   apiMethod: string;
   arguments: any[];
@@ -34,12 +37,27 @@ class MirrorFile extends PreloadFile<AsyncMirror> implements File {
 /**
  * AsyncMirrorFS mirrors a synchronous filesystem into an asynchronous filesystem
  * by:
+ *
  * * Performing operations over the in-memory copy, while asynchronously pipelining them
  *   to the backing store.
  * * During application loading, the contents of the async file system can be reloaded into
  *   the synchronous store, if desired.
+ *
  * The two stores will be kept in sync. The most common use-case is to pair a synchronous
  * in-memory filesystem with an asynchronous backing store.
+ *
+ * Example: Mirroring an IndexedDB file system to an in memory file system. Now, you can use
+ * IndexedDB synchronously.
+ *
+ * ```javascript
+ * new BrowserFS.FileSystem.IndexedDB(function (e, idbfs) {
+ *   var inMemory = new BrowserFS.FileSystem.InMemory();
+ *   var mirrored = new BrowserFS.FileSystem.AsyncMirror(inMemory, idbfs);
+ *   mirrored.initialize(function (e) {
+ *     BrowserFS.initialized(mirrored);
+ *   });
+ * });
+ * ```
  */
 export default class AsyncMirror extends SynchronousFileSystem implements FileSystem {
   public static isAvailable(): boolean {
@@ -55,6 +73,14 @@ export default class AsyncMirror extends SynchronousFileSystem implements FileSy
   private _async: FileSystem;
   private _isInitialized: boolean = false;
   private _initializeCallbacks: ((e?: ApiError) => void)[] = [];
+
+  /**
+   * Mirrors the synchronous file system into the asynchronous file system.
+   *
+   * **IMPORTANT**: You must call `initialize` on the file system before it can be used.
+   * @param sync The synchronous file system to mirror the asynchronous file system to.
+   * @param async The asynchronous file system to mirror.
+   */
   constructor(sync: FileSystem, async: FileSystem) {
     super();
     this._sync = sync;

diff --git a/src/backend/Dropbox.ts b/src/backend/Dropbox.ts
@@ -8,8 +8,14 @@ import {each as asyncEach} from 'async';
 import * as path from 'path';
 import {arrayBuffer2Buffer, buffer2ArrayBuffer, emptyBuffer} from '../core/util';
 
+/**
+ * @hidden
+ */
 let errorCodeLookup: {[dropboxErrorCode: number]: ErrorCode};
-// Lazily construct error code lookup, since DropboxJS might be loaded *after* BrowserFS (or not at all!)
+/**
+ * Lazily construct error code lookup, since DropboxJS might be loaded *after* BrowserFS (or not at all!)
+ * @hidden
+ */
 function constructErrorCodeLookup() {
   if (errorCodeLookup) {
     return;
@@ -42,33 +48,52 @@ function constructErrorCodeLookup() {
   errorCodeLookup[Dropbox.ApiError.OVER_QUOTA] = ErrorCode.ENOSPC;
 }
 
+/**
+ * @hidden
+ */
 interface ICachedPathInfo {
   stat: Dropbox.File.Stat;
 }
 
+/**
+ * @hidden
+ */
 interface ICachedFileInfo extends ICachedPathInfo {
   contents: ArrayBuffer;
 }
 
+/**
+ * @hidden
+ */
 function isFileInfo(cache: ICachedPathInfo): cache is ICachedFileInfo {
   return cache && cache.stat.isFile;
 }
 
+/**
+ * @hidden
+ */
 interface ICachedDirInfo extends ICachedPathInfo {
   contents: string[];
 }
 
+/**
+ * @hidden
+ */
 function isDirInfo(cache: ICachedPathInfo): cache is ICachedDirInfo {
   return cache && cache.stat.isFolder;
 }
 
+/**
+ * @hidden
+ */
 function isArrayBuffer(ab: any): ab is ArrayBuffer {
   // Accept null / undefined, too.
   return ab === null || ab === undefined || (typeof(ab) === 'object' && typeof(ab['byteLength']) === 'number');
 }
 
 /**
  * Wraps a Dropbox client and caches operations.
+ * @hidden
  */
 class CachedDropboxClient {
   private _cache: {[path: string]: ICachedPathInfo} = {};
@@ -311,6 +336,13 @@ export class DropboxFile extends PreloadFile<DropboxFileSystem> implements File
   }
 }
 
+/**
+ * A read/write file system backed by Dropbox cloud storage.
+ *
+ * Uses the Dropbox V1 API.
+ *
+ * NOTE: You must use the v0.10 version of the [Dropbox JavaScript SDK](https://www.npmjs.com/package/dropbox).
+ */
 export default class DropboxFileSystem extends BaseFileSystem implements FileSystem {
   public static isAvailable(): boolean {
     // Checks if the Dropbox library is loaded.
@@ -321,7 +353,9 @@ export default class DropboxFileSystem extends BaseFileSystem implements FileSys
   private _client: CachedDropboxClient;
 
   /**
-   * Arguments: an authenticated Dropbox.js client
+   * Constructs a Dropbox-backed file system using the *authenticated* DropboxJS client.
+   *
+   * Note that you must use the old v0.10 version of the Dropbox JavaScript SDK.
    */
   constructor(client: Dropbox.Client) {
     super();

diff --git a/src/backend/Emscripten.ts b/src/backend/Emscripten.ts
@@ -6,11 +6,17 @@ import {uint8Array2Buffer, buffer2Uint8array} from '../core/util';
 import {ApiError, ErrorCode, ErrorStrings} from '../core/api_error';
 import {EmscriptenFSNode} from '../generic/emscripten_fs';
 
+/**
+ * @hidden
+ */
 interface EmscriptenError {
   node: EmscriptenFSNode;
   errno: number;
 }
 
+/**
+ * @hidden
+ */
 function convertError(e: EmscriptenError, path: string = ''): ApiError {
   const errno = e.errno;
   let parent = e.node;
@@ -175,13 +181,17 @@ export class EmscriptenFile extends BaseFile implements File {
 }
 
 /**
- * A simple in-memory file system backed by an InMemoryStore.
+ * Mounts an Emscripten file system into the BrowserFS file system.
  */
 export default class EmscriptenFileSystem extends SynchronousFileSystem {
   public static isAvailable(): boolean { return true; }
 
   private _FS: any;
 
+  /**
+   * Creates a BrowserFS file system for the given Emscripten file system.
+   * @param _FS The Emscripten file system (`FS`).
+   */
   constructor(_FS: any) {
     super();
     this._FS = _FS;