feat: add 'rename' function

BREAKING CHANGE: The IndexedDB database format changed - the primary key is now an inode number rather than a filepath string. Adding this layer of indirection make renaming files and directories fast. (Before, renaming a directory would have required recursively copying all the files to a new location.) Rather than bloat the code with a migration script, I recommend simply creating a fresh filesystem or blowing the old filesystem away with the `wipe` argument. Maybe you can load v2 and v3 at the same time, and recursively read from the v2 instance  and write to the v3 instance? Database migrations are hard, and I apologize. But this should be the first and last backwards incompatible change to the database format.

BREAKING CHANGE: the `stat` function now returns `mtimeMs` rather than `mtimeSeconds` and `mtimeNanoseconds` to match what Node's `stat` function returns instead of catering to an implementation detail of `isomorphic-git`.

Author: billiegoose

README.md

@@ -31,7 +31,7 @@ Req #3 excludes pure in-memory solutions. Req #4 excludes `localStorage` because
 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
+- `mkdir`, `rmdir`, `readdir`, `rename`, 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.
@@ -40,7 +40,94 @@ Applications can always *add* an LRU cache on top of `lightning-fs` - if I add o
 
 ## Usage
 
-TODO
+### `new FS(name, opts?)`
+First, create or open a "filesystem". (The name is used to determine the IndexedDb store name.)
+
+```
+import FS from '@isomorphic-git/lightning-fs';
+
+const fs = new FS("testfs")
+```
+
+Options object:
+
+| Param  | Type [= default]   | Description                                                           |
+| ------ | ------------------ | --------------------------------------------------------------------- |
+| `wipe` | boolean = false    | Delete the database and start with an empty filesystem                |
+| `url`  | string = undefined | Let `readFile` requests fall back to an HTTP request to this base URL |
+
+### `fs.mkdir(filepath, opts?, cb)`
+
+Make directory
+
+Options object:
+
+| Param  | Type [= default] | Description            |
+| ------ | ---------------- | ---------------------- |
+| `mode` | number = 0o777   | Posix mode permissions |
+
+### `fs.rmdir(filepath, opts?, cb)`
+
+Remove directory
+
+### `fs.readdir(filepath, opts?, cb)`
+
+Read directory
+
+The callback return value is an Array of strings.
+
+### `fs.writeFile(filepath, data, opts?, cb)`
+
+`data` should be a string of a Uint8Array.
+
+If `opts` is a string, it is interpreted as `{ encoding: opts }`.
+
+Options object:
+
+| Param      | Type [= default]   | Description                      |
+| ---------- | ------------------ | -------------------------------- |
+| `mode`     | number = 0o777     | Posix mode permissions           |
+| `encoding` | string = undefined | Only supported value is `'utf8'` |
+
+### `fs.readFile(filepath, opts?, cb)`
+
+The result value will be a Uint8Array or (if `encoding` is `'utf8'`) a string.
+
+If `opts` is a string, it is interpreted as `{ encoding: opts }`.
+
+Options object:
+
+| Param      | Type [= default]   | Description                      |
+| ---------- | ------------------ | -------------------------------- |
+| `encoding` | string = undefined | Only supported value is `'utf8'` |
+
+### `fs.unlink(filepath, opts?, cb)`
+
+Delete a file
+
+### `fs.rename(oldFilepath, newFilepath, cb)`
+
+Rename a file or directory
+
+### `fs.stat(filepath, opts?, cb)`
+
+The result is a Stat object similar to the one used by Node but with fewer and slightly different properties and methods.
+The included properties are:
+
+- `type` ("file" or "dir")
+- `mode`
+- `size`
+- `ino`
+- `mtimeMs`
+- `ctimeMs`
+- `uid` (fixed value of 1)
+- `gid` (fixed value of 1)
+- `dev` (fixed value of 1)
+
+The included methods are:
+- `isFile()`
+- `isDirectory()`
+- `isSymbolicLink()`
 
 ## License
 

src/CacheFS.js

@@ -18,6 +18,32 @@ module.exports = class CacheFS {
       this._root = superblock
     }
   }
+  size () {
+    // subtract 1 to ignore the root directory itself from the count.
+    return this._countInodes(this._root.get("/")) - 1;
+  }
+  _countInodes(map) {
+    let count = 1;
+    for (let [key, val] of map) {
+      if (key === STAT) continue;
+      count += this._countInodes(val);
+    }
+    return count;
+  }
+  autoinc () {
+    console.time('autoinc')
+    let val = this._maxInode(this._root.get("/")) + 1;
+    console.timeEnd('autoinc')
+    return val;
+  }
+  _maxInode(map) {
+    let max = 0;
+    for (let [key, val] of map) {
+      if (key === STAT) continue;
+      max = Math.max(max, val.get(STAT).ino);
+    }
+    return max;
+  }
   print(root = this._root.get("/")) {
     let str = "";
     const printTree = (root, indent) => {
@@ -38,21 +64,17 @@ module.exports = class CacheFS {
     return str;
   }
   parse(print) {
+    let autoinc = 0;
+
     function mk(stat) {
+      const ino = ++autoinc;
       // TODO: Use a better heuristic for determining whether file or dir
-      if (stat.length === 1) {
-        let [mode] = stat
-        mode = parseInt(mode, 8);
-        return new Map([
-          [STAT, { mode, type: "dir", size: 0, mtimeMs: Date.now() }]
-        ]);
-      } else {
-        let [mode, size, mtimeMs] = stat;
-        mode = parseInt(mode, 8);
-        size = parseInt(size);
-        mtimeMs = parseInt(mtimeMs);
-        return new Map([[STAT, { mode, type: "file", size, mtimeMs }]]);
-      }
+      const type = stat.length === 1 ? "dir" : "file"
+      let [mode, size, mtimeMs] = stat;
+      mode = parseInt(mode, 8);
+      size = size ? parseInt(size) : 0;
+      mtimeMs = mtimeMs ? parseInt(mtimeMs) : Date.now();
+      return new Map([[STAT, { mode, type, size, mtimeMs, ino }]]);
     }
 
     let lines = print.trim().split("\n");
@@ -99,6 +121,7 @@ module.exports = class CacheFS {
       type: "dir",
       size: 0,
       mtimeMs: Date.now(),
+      ino: this.autoinc(),
     };
     entry.set(STAT, stat);
     dir.set(basename, entry);
@@ -132,17 +155,29 @@ module.exports = class CacheFS {
       type: "file",
       size: data.length,
       mtimeMs: Date.now(),
+      ino: this.autoinc(),
     };
     let entry = new Map();
     entry.set(STAT, stat);
     dir.set(basename, entry);
+    return stat;
   }
   unlink(filepath) {
     // remove from parent
     let parent = this._lookup(path.dirname(filepath));
     let basename = path.basename(filepath);
     parent.delete(basename);
   }
+  rename(oldFilepath, newFilepath) {
+    // grab reference
+    let entry = this._lookup(oldFilepath);
+    // remove from parent directory
+    this.unlink(oldFilepath)
+    // insert into new parent directory
+    let dir = this._lookup(path.dirname(newFilepath));
+    let basename = path.basename(newFilepath);
+    dir.set(basename, entry);
+  }
   stat(filepath) {
     return this._lookup(filepath).get(STAT);
   }

src/IdbBackend.js

@@ -11,14 +11,14 @@ module.exports = class IdbBackend {
   loadSuperblock() {
     return idb.get("!root", this._store);
   }
-  readFile(filepath) {
-    return idb.get(filepath, this._store)
+  readFile(inode) {
+    return idb.get(inode, this._store)
   }
-  writeFile(filepath, data) {
-    return idb.set(filepath, data, this._store)
+  writeFile(inode, data) {
+    return idb.set(inode, data, this._store)
   }
-  unlink(filepath) {
-    return idb.del(filepath, this._store)
+  unlink(inode) {
+    return idb.del(inode, this._store)
   }
   wipe() {
     return idb.clear(this._store)

src/Stat.js

@@ -1,28 +1,17 @@
-function SecondsNanoseconds(milliseconds) {
-  if (milliseconds == null) {
-    milliseconds = Date.now();
-  }
-  const seconds = Math.floor(milliseconds / 1000);
-  const nanoseconds = (milliseconds - seconds * 1000) * 1000000;
-  return [seconds, nanoseconds];
-}
-
 module.exports = class Stat {
   constructor(stats) {
     this.type = stats.type;
     this.mode = stats.mode;
     this.size = stats.size;
-    const [mtimeSeconds, mtimeNanoseconds] = SecondsNanoseconds(stats.mtimeMs);
-    const [ctimeSeconds, ctimeNanoseconds] = SecondsNanoseconds(stats.ctimeMs || stats.mtimeMs);
-    this.mtimeSeconds = mtimeSeconds;
-    this.ctimeSeconds = ctimeSeconds;
-    this.mtimeNanoseconds = mtimeNanoseconds;
-    this.ctimeNanoseconds = ctimeNanoseconds;
-
+    this.ino = stats.ino;
+    this.mtimeMs = stats.mtimeMs;
+    this.ctimeMs = stats.ctimeMs || stats.mtimeMs;
     this.uid = 1;
     this.gid = 1;
     this.dev = 1;
-    this.ino = 1;
+  }
+  isFile() {
+    return this.type === "file";
   }
   isDirectory() {
     return this.type === "dir";

src/__tests__/CacheFS.spec.js

@@ -10,4 +10,10 @@ describe("CacheFS module", () => {
     let text = fs.print(parsed)
     expect(text).toEqual(treeText)
   });
+  it("size()", () => {
+    expect(fs.size()).toEqual(0)
+    fs.loadSuperBlock(treeText)
+    let inodeCount = treeText.trim().split('\n').length
+    expect(fs.size()).toEqual(inodeCount)
+  });
 });

src/__tests__/fallback.spec.js

@@ -1,6 +1,6 @@
 import FS from "../index.js";
 
-const fs = new FS("testfs", { wipe: true, url: 'http://localhost:9876/base/src/__tests__/__fixtures__/test-folder' });
+const fs = new FS("fallbackfs", { wipe: true, url: 'http://localhost:9876/base/src/__tests__/__fixtures__/test-folder' });
 
 describe("http fallback", () => {
   it("sanity check", () => {

src/__tests__/fs.spec.js

@@ -202,4 +202,53 @@ describe("fs module", () => {
       });
     });
   });
+
+  describe("rename", () => {
+    it("create and rename file", done => {
+      fs.mkdir("/rename", () => {
+        fs.writeFile("/rename/a.txt", "", () => {
+          fs.rename("/rename/a.txt", "/rename/b.txt", (err) => {
+            expect(err).toBe(null);
+            fs.readdir("/rename", (err, data) => {
+              expect(data.includes("a.txt")).toBe(false);
+              expect(data.includes("b.txt")).toBe(true);
+              fs.readFile("/rename/a.txt", (err, data) => {
+                expect(err).not.toBe(null)
+                expect(err.code).toBe("ENOENT")
+                fs.readFile("/rename/b.txt", "utf8", (err, data) => {
+                  expect(err).toBe(null)
+                  expect(data).toBe("")
+                  done();
+                });
+              });
+            });
+          });
+        });
+      });
+    });
+    it("create and rename directory", done => {
+      fs.mkdir("/rename", () => {
+        fs.mkdir("/rename/a", () => {
+          fs.writeFile("/rename/a/file.txt", "", () => {
+            fs.rename("/rename/a", "/rename/b", (err) => {
+              expect(err).toBe(null);
+              fs.readdir("/rename", (err, data) => {
+                expect(data.includes("a")).toBe(false);
+                expect(data.includes("b")).toBe(true);
+                fs.readFile("/rename/a/file.txt", (err, data) => {
+                  expect(err).not.toBe(null)
+                  expect(err.code).toBe("ENOENT")
+                  fs.readFile("/rename/b/file.txt", "utf8", (err, data) => {
+                    expect(err).toBe(null)
+                    expect(data).toBe("")
+                    done();
+                  });
+                });
+              });
+            });
+          });
+        });
+      });
+    });
+  });
 });