Update README

Author: billiegoose

README.md

@@ -1,35 +1,46 @@
-# isomorphic-pgp
+# @isomorphic-git/lightning-fs
 
-A lightweight library for creating and verifying OpenPGP signatures
+A lean and fast 'fs' for the browser
 
 ## Motivation
 
-PGP is the cryptographic standard used to sign git commits, and I wanted to provide `isomorphic-git` users a way
-to tap into that power without sacrificing bundle size or worrying about LGPL restrictions.
-So I wrote an entirely new JavaScript library with that narrow use case in mind.
+I wanted to see if I could make something faster than [BrowserFS](https://github.com/jvilk/BrowserFS) or [filer](https://github.com/filerjs/filer) that still implements enough of the `fs` API to run the [`isomorphic-git`](https://github.com/isomorphic-git/isomorphic-git) test suite in browsers.
 
-## IMPORTANT!!!
+## Comparison with other libraries
 
-Please read and understand the limitations of the [`sign-and-verify`](https://github.com/wmhilton/isomorphic-pgp/tree/master/src/sign-and-verify) module before using it.
+This library does not even come close to implementing the full [`fs`](https://nodejs.org/api/fs.html) API.
+Instead, it only implements [the subset used by isomorphic-git 'fs' plugin interface](https://isomorphic-git.org/docs/en/plugin_fs).
 
-## Comparison with other libraries
+Unlike BrowserFS, which has a dozen backends and is highly configurable, `lightning-fs` has a single configuration that should Just Work for most users.
 
-This library does not implement encryption or decryption - only signing and verifying signatures.
+## Philosophy
 
-|   | Size | License | Sign | Verify | Encrypt | Decrypt |
-|---|------|---------|------|--------|---------|---------|
-| isomorphic-pgp | [~17 kb](https://bundlephobia.com/result?p=@isomorphic-git/[email protected]) | MIT | 🗹 | 🗹 | ☐ | ☐|
-| OpenPGP.js | [~170 kb](https://bundlephobia.com/[email protected]) | LGPL | 🗹 | 🗹 | 🗹 | 🗹 |
-| kbpgp | [~160 kb](https://bundlephobia.com/[email protected]) | BSD |  🗹 | 🗹 | 🗹 | 🗹 |
+### Basic requirements:
 
-## Usage
+1. needs to work in all modern browsers
+2. needs to work with large-ish files and directories
+3. needs to persist data
+4. needs to enable performant web apps
+
+Req #3 excludes pure in-memory solutions. Req #4 excludes `localStorage` because it blocks the DOM and cannot be run in a webworker. Req #1 excludes WebSQL and Chrome's FileSystem API. So that leaves us with IndexedDB as the only usable storage technology.
+
+### Optimization targets (in order of priority):
 
-See individual READMEs for each package:
+1. speed (time it takes to execute file system operations)
+2. bundle size (time it takes to download the library)
+3. memory usage (will it work on mobile)
+
+In order to get improve #1, I ended up making a hybrid in-memory / IndexedDB system:
+- `mkdir`, `rmdir`, `readdir`, and `stat` are pure in-memory operations that take 0ms
+- `writeFile`, `readFile`, and `unlink` are throttled by IndexedDB
+
+The in-memory portion of the filesystem is persisted to IndexedDB with a debounce of 500ms.
+The files themselves are not currently cached in memory, because I don't want to waste a lot of memory.
+Applications can always *add* an LRU cache on top of `lightning-fs` - if I add one internally and it isn't tuned well for your application, it might be much harder to work around.
+
+## Usage
 
-- [parser](https://github.com/wmhilton/isomorphic-pgp/tree/master/src/parser)
-- [util](https://github.com/wmhilton/isomorphic-pgp/tree/master/src/util)
-- [sign-and-verify](https://github.com/wmhilton/isomorphic-pgp/tree/master/src/sign-and-verify)
-- [generate](https://github.com/wmhilton/isomorphic-pgp/tree/master/src/generate)
+TODO
 
 ## License
 

package.json

@@ -2,10 +2,10 @@
   "publishConfig": {
     "access": "public"
   },
-  "name": "@isomorphic-git/idb-fs",
+  "name": "@isomorphic-git/lightning-fs",
   "version": "0.0.0",
   "description": "A lean and fast 'fs' for the browser",
-  "main": "index.js",
+  "main": "src/index.js",
   "bin": {
     "superblocktxt": "src/superblocktxt.js"
   },
@@ -36,7 +36,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/isomorphic-git/idb-fs.git"
+    "url": "git+https://github.com/isomorphic-git/lightning-fs.git"
   },
   "files": [
     "**/*.js",
@@ -52,7 +52,7 @@
   "author": "William Hilton <[email protected]>",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/isomorphic-git/idb-fs/issues"
+    "url": "https://github.com/isomorphic-git/lightning-fs/issues"
   },
-  "homepage": "https://github.com/isomorphic-git/idb-fs#readme"
+  "homepage": "https://github.com/isomorphic-git/lightning-fs#readme"
 }

src/CacheFS.js

@@ -5,47 +5,41 @@ const STAT = 0;
 
 module.exports = class CacheFS {
   constructor() {
-    const root = this._makeRoot();
-    this._root = new Map([["/", root]]);
+    this._root = new Map([["/", this._makeRoot()]]);
   }
-  _makeRoot(root) {
-    root = root || new Map();
-    let stat = { mode: 0o777, type: "dir", size: 0, mtimeMs: Date.now() };
-    root.set(STAT, stat);
+  _makeRoot(root = new Map()) {
+    root.set(STAT, { mode: 0o777, type: "dir", size: 0, mtimeMs: Date.now() });
     return root
   }
   loadSuperBlock(superblock) {
     if (typeof superblock === 'string') {
-      let root = this.parse(superblock)
-      root = this._makeRoot(root);
-      this._root = new Map([["/", root]]);
+      this._root = new Map([["/", this._makeRoot(this.parse(superblock))]]);
     } else {
       this._root = superblock
     }
   }
-  print(root) {
-    root = root || this._root.get("/")
+  print(root = this._root.get("/")) {
     let str = "";
     const printTree = (root, indent) => {
       for (let [file, node] of root) {
         if (file === 0) continue;
         let stat = node.get(STAT);
         let mode = stat.mode.toString(8);
+        str += `${"\t".repeat(indent)}${file}\t${mode}`
         if (stat.type === "file") {
-          str += `\n${"\t".repeat(indent)}${file}\t${mode}\t${stat.size}\t${
-            stat.mtimeMs
-          }`;
+          str += `\t${stat.size}\t${stat.mtimeMs}\n`;
         } else {
-          str += `\n${"\t".repeat(indent)}${file}\t${mode}`;
+          str += `\n`
           printTree(node, indent + 1);
         }
       }
     };
     printTree(root, 0);
-    return str.trimStart() + '\n';
+    return str;
   }
   parse(print) {
     function mk(stat) {
+      // TODO: Use a better heuristic for determining whether file or dir
       if (stat.length === 1) {
         let [mode] = stat
         mode = parseInt(mode, 8);
@@ -68,7 +62,6 @@ module.exports = class CacheFS {
       { indent: 0, node: null }
     ];
     for (let line of lines) {
-      // let [, prefix, filename, stat]
       let prefix = line.match(/^\t*/)[0];
       let indent = prefix.length;
       line = line.slice(indent);

src/HttpBackend.js

@@ -1,4 +1,4 @@
-module.exports = class IdbBackend {
+module.exports = class HttpBackend {
   constructor(url) {
     this._url = url;
   }

src/__tests__/fallback.spec.js

@@ -22,14 +22,7 @@ describe("http fallback", () => {
         done();
       });
     });
-    it("read child dir /0", done => {
-      fs.readdir("/0", (err, data) => {
-        expect(err).toBe(null);
-        expect(data).toEqual(['a.txt', 'b.txt', 'c.txt'])
-        done();
-      });
-    });
-    it("read child dir /1", done => {
+    it("read child dir", done => {
       fs.readdir("/1", (err, data) => {
         expect(err).toBe(null);
         expect(data).toEqual(['d.txt', 'e.txt', 'f.txt'])
@@ -63,9 +56,9 @@ describe("http fallback", () => {
 
   describe("writeFile", () => {
     it("writing a file overwrites the server version", done => {
-      fs.writeFile("/a.txt", "welcome", (err) => {
+      fs.writeFile("/b.txt", "welcome", (err) => {
         expect(err).toBe(null)
-        fs.readFile("/a.txt", 'utf8', (err, data) => {
+        fs.readFile("/b.txt", 'utf8', (err, data) => {
           expect(err).toBe(null);
           expect(data).toEqual('welcome');
           done();

src/index.js

@@ -10,7 +10,7 @@ const IdbBackend = require("./IdbBackend.js");
 const HttpBackend = require("./HttpBackend.js")
 const clock = require("./clock.js");
 
-export default class FS {
+module.exports = class FS {
   constructor(name, { wipe, url } = {}) {
     this._backend = new IdbBackend(name);
     this._cache = new CacheFS(name);