rmapi-js 2.2.0 → 3.0.0

package/dist/index.js

@@ -15,9 +15,8 @@
  * const token = await register(code)
  * // persist token
  * const api = await remarkable(token);
- * const [root] = await api.getRootHash();
- * const fileEntries = await api.getEntries(root);
- * for (const entry of fileEntries) {
+ * const rootEntries = await api.getEntries();
+ * for (const entry of rootEntries) {
  *   const children = await api.getEntries(entry.hash);
  *   for (const { hash, documentId } of children) {
  *     if (documentId.endsWith(".metadata")) {
@@ -42,6 +41,7 @@
  * @packageDocumentation
  */
 import { fromByteArray } from "base64-js";
+import stringify from "json-stable-stringify";
 import { v4 as uuid4 } from "uuid";
 import { concatBuffers, fromHex, toHex } from "./utils";
 import { validate } from "./validate";
@@ -295,15 +295,22 @@ export function parseEntry(line) {
 class Remarkable {
     #userToken;
     #fetch;
-    #cache;
     #subtle;
     #syncHost;
-    constructor(userToken, fetch, cache, subtle, syncHost) {
+    // caches
+    #cacheLimitBytes;
+    #cache = new Map();
+    #rootCache = null;
+    constructor(userToken, fetch, subtle, syncHost, cacheLimitBytes, initCache) {
         this.#userToken = userToken;
         this.#fetch = fetch;
-        this.#cache = cache;
         this.#subtle = subtle;
         this.#syncHost = syncHost;
+        this.#cacheLimitBytes = cacheLimitBytes;
+        // set cache
+        for (const [hash, val] of initCache) {
+            this.#cache.set(hash, Promise.resolve(val));
+        }
     }
     /** make an authorized request to remarkable */
     async #authedFetch(url, { body, method = "POST", headers = {}, }) {
@@ -348,7 +355,7 @@ class Remarkable {
     async #getUrl(relativePath, gen, rootHash) {
         const key = gen === undefined ? "downloads" : "uploads";
         // NOTE this is done manually to serialize the bigints appropriately
-        const body = rootHash
+        const body = rootHash && gen !== null && gen !== undefined
             ? `{ "http_method": "PUT", "relative_path": "${relativePath}", "root_schema": "${rootHash}", "generation": ${gen} }`
             : JSON.stringify({ http_method: "GET", relative_path: relativePath });
         const resp = await this.#authedFetch(`${this.#syncHost}/sync/v2/signed-urls/${key}`, { body });
@@ -360,14 +367,38 @@ class Remarkable {
     /**
      * get the root hash and the current generation
      */
-    async getRootHash() {
-        const signed = await this.#getUrl("root");
-        const resp = await this.#signedFetch(signed);
-        const generation = resp.headers.get(GENERATION_HEADER);
-        if (!generation) {
-            throw new Error("no generation header in root hash");
+    async getRootHash({ cache = true } = {}) {
+        if (cache) {
+            while (this.#rootCache) {
+                try {
+                    const [hash, gen] = await this.#rootCache;
+                    return [hash, gen];
+                }
+                catch {
+                    // noop
+                }
+            }
         }
-        return [await resp.text(), BigInt(generation)];
+        const prom = (async () => {
+            try {
+                const signed = await this.#getUrl("root");
+                const resp = await this.#signedFetch(signed);
+                const generation = resp.headers.get(GENERATION_HEADER);
+                if (!generation) {
+                    throw new Error("no generation header in root hash");
+                }
+                else {
+                    return [await resp.text(), BigInt(generation)];
+                }
+            }
+            catch (ex) {
+                this.#rootCache = null;
+                throw ex;
+            }
+        })();
+        this.#rootCache = prom;
+        const [hash, gen] = await prom;
+        return [hash, gen];
     }
     /**
      * write the root hash, incrementing from the current generation
@@ -382,55 +413,92 @@ class Remarkable {
         }
         catch (ex) {
             if (ex instanceof ResponseError && ex.status === 412) {
+                this.#rootCache = null;
                 throw new GenerationError();
             }
             else {
                 throw ex;
             }
         }
-        const gen = resp.headers.get(GENERATION_HEADER);
-        if (!gen) {
+        const genStr = resp.headers.get(GENERATION_HEADER);
+        if (!genStr) {
             throw new Error("no generation header in root hash");
         }
-        return BigInt(gen);
+        const gen = BigInt(genStr);
+        this.#rootCache = Promise.resolve([hash, gen]);
+        return gen;
+    }
+    /**
+     * get content associated with hash
+     */
+    async #getHash(hash) {
+        let cached = this.#cache.get(hash);
+        while (cached) {
+            try {
+                const val = await cached;
+                if (val) {
+                    return val;
+                }
+                else {
+                    cached = undefined; // break
+                }
+            }
+            catch {
+                // try again if promise rejected
+                cached = this.#cache.get(hash);
+            }
+        }
+        const prom = (async () => {
+            const signed = await this.#getUrl(hash);
+            const resp = await this.#signedFetch(signed);
+            return await resp.arrayBuffer();
+        })();
+        // set cache with appropriate promise that cleans up on rejection
+        this.#cache.set(hash, prom.then((buff) => (buff.byteLength < this.#cacheLimitBytes ? buff : null), (ex) => {
+            this.#cache.delete(hash);
+            throw ex;
+        }));
+        return await prom;
     }
     /**
      * get text content associated with hash
      */
     async getBuffer(hash) {
-        const signed = await this.#getUrl(hash);
-        const resp = await this.#signedFetch(signed);
-        return await resp.arrayBuffer();
+        const buff = await this.#getHash(hash);
+        // copy if it is long enough to be cached to preven mutations
+        return buff.byteLength < this.#cacheLimitBytes ? buff.slice(0) : buff;
     }
     /**
      * get text content associated with hash
      */
     async getText(hash) {
-        const cached = await this.#cache?.get(hash);
-        if (cached) {
-            return cached;
-        }
-        else {
-            const signed = await this.#getUrl(hash);
-            const resp = await this.#signedFetch(signed);
-            const raw = await resp.text();
-            await this.#cache?.set(hash, raw);
-            return raw;
-        }
+        const buff = await this.#getHash(hash);
+        const decoder = new TextDecoder();
+        return decoder.decode(buff);
+    }
+    /**
+     * get json content associated with hash
+     */
+    async getJson(hash) {
+        const str = await this.getText(hash);
+        return JSON.parse(str);
     }
     /**
      * get metadata from hash
      */
     async getMetadata(hash) {
-        const raw = await this.getText(hash);
-        const parsed = JSON.parse(raw);
-        validate(metadataSchema, parsed);
-        return parsed;
+        const raw = await this.getJson(hash);
+        validate(metadataSchema, raw);
+        return raw;
     }
     /**
      * get entries from a collection hash
      */
     async getEntries(hash) {
+        if (hash === undefined) {
+            const [newHash] = await this.getRootHash({ cache: true });
+            hash = newHash;
+        }
         const raw = await this.getText(hash);
         // slice for trailing new line
         const [schema, ...lines] = raw.slice(0, -1).split("\n");
@@ -441,8 +509,31 @@ class Remarkable {
     }
     /** upload data to hash */
     async #putHash(hash, body) {
-        const signed = await this.#getUrl(hash, null);
-        await this.#signedFetch(signed, body);
+        // try cached version
+        const cached = this.#cache.get(hash);
+        if (cached) {
+            try {
+                await cached;
+                return;
+            }
+            catch {
+                // noop
+            }
+        }
+        // if missing or rejected then put for real
+        const prom = (async () => {
+            try {
+                const signed = await this.#getUrl(hash, null);
+                await this.#signedFetch(signed, body);
+                return body.byteLength < this.#cacheLimitBytes ? body : null;
+            }
+            catch (ex) {
+                this.#cache.delete(hash);
+                throw ex;
+            }
+        })();
+        this.#cache.set(hash, prom);
+        await prom;
     }
     /** put a reference to a set of entries into the cloud */
     async putEntries(documentId, entries) {
@@ -456,7 +547,6 @@ class Remarkable {
         const contents = `${SCHEMA_VERSION}\n${entryContents}`;
         const buffer = enc.encode(contents);
         await this.#putHash(hash, buffer);
-        await this.#cache?.set(hash, contents);
         return {
             hash,
             type: "80000000",
@@ -475,19 +565,21 @@ class Remarkable {
             type: "0",
             documentId,
             subfiles: 0,
-            size: BigInt(buffer.length),
+            size: BigInt(buffer.byteLength),
         };
     }
-    /** put cached text in the cloud */
+    /** put text in the cloud */
     async putText(documentId, contents) {
         const enc = new TextEncoder();
-        const entry = await this.putBuffer(documentId, enc.encode(contents));
-        await this.#cache?.set(entry.hash, contents);
-        return entry;
+        return await this.putBuffer(documentId, enc.encode(contents));
+    }
+    /** put json in the cloud */
+    async putJson(documentId, contents) {
+        return await this.putText(documentId, stringify(contents));
     }
     /** put metadata into the cloud */
     async putMetadata(documentId, metadata) {
-        return await this.putText(`${documentId}.metadata`, JSON.stringify(metadata));
+        return await this.putJson(`${documentId}.metadata`, metadata);
     }
     /** put a new collection (folder) */
     async putCollection(visibleName, parent = "") {
@@ -593,32 +685,32 @@ class Remarkable {
         });
     }
     /** try to sync, always succeed */
-    async #trySync(gen) {
-        try {
-            await this.syncComplete(gen);
-            return true;
+    async #tryPutRootEntries(gen, entries, sync) {
+        const { hash } = await this.putEntries("", entries);
+        const nextGen = await this.putRootHash(hash, gen);
+        if (sync) {
+            try {
+                await this.syncComplete(nextGen);
+                return true;
+            }
+            catch {
+                return false;
+            }
         }
-        catch {
+        else {
             return false;
         }
     }
     /** high level api to create an entry */
-    async create(entry, sync = true) {
-        const [root, gen] = await this.getRootHash();
+    async create(entry, { cache = true, sync = true } = {}) {
+        const [root, gen] = await this.getRootHash({ cache });
         const rootEntries = await this.getEntries(root);
         rootEntries.push(entry);
-        const { hash } = await this.putEntries("", rootEntries);
-        const nextGen = await this.putRootHash(hash, gen);
-        if (sync) {
-            return await this.#trySync(nextGen);
-        }
-        else {
-            return false;
-        }
+        return await this.#tryPutRootEntries(gen, rootEntries, sync);
     }
     /** high level api to move a document / collection */
-    async move(documentId, dest, sync = true) {
-        const [root, gen] = await this.getRootHash();
+    async move(documentId, dest, { cache = true, sync = true } = {}) {
+        const [root, gen] = await this.getRootHash({ cache });
         const rootEntries = await this.getEntries(root);
         // check if destination is a collection
         if (!dest || dest === "trash") {
@@ -667,16 +759,7 @@ class Remarkable {
         // update root entries
         const newEntry = await this.putEntries(documentId, docEnts);
         rootEntries.push(newEntry);
-        // update generation
-        const { hash } = await this.putEntries("", rootEntries);
-        const nextGen = await this.putRootHash(hash, gen);
-        // sync
-        if (sync) {
-            return await this.#trySync(nextGen);
-        }
-        else {
-            return false;
-        }
+        return await this.#tryPutRootEntries(gen, rootEntries, sync);
     }
     /** get entries and metadata for all files */
     async getEntriesMetadata() {
@@ -720,6 +803,20 @@ class Remarkable {
         // TODO why doesn't this work
         return await this.#uploadFile(visibleName, buffer, "application/pdf");
     }
+    async getCache() {
+        const promises = [];
+        for (const [hash, prom] of this.#cache) {
+            promises.push(prom.then((val) => [hash, val], () => [hash, null]));
+        }
+        const entries = await Promise.all(promises);
+        const cache = new Map();
+        for (const [hash, val] of entries) {
+            if (val) {
+                cache.set(hash, val);
+            }
+        }
+        return cache;
+    }
 }
 /**
  * create an instance of the api
@@ -731,7 +828,10 @@ class Remarkable {
  *    registered. Create one with {@link register}.
  * @returns an api instance
  */
-export async function remarkable(deviceToken, { fetch = globalThis.fetch, cache, subtle = globalThis.crypto?.subtle, authHost = AUTH_HOST, syncHost = SYNC_HOST, } = {}) {
+export async function remarkable(deviceToken, { fetch = globalThis.fetch, subtle = globalThis.crypto?.subtle, authHost = AUTH_HOST, syncHost = SYNC_HOST, cacheLimitBytes = 1048576, initCache = [], } = {}) {
+    if (!subtle) {
+        throw new Error("subtle was missing, try specifying it manually");
+    }
     const resp = await fetch(`${authHost}/token/json/2/user/new`, {
         method: "POST",
         headers: {
@@ -742,5 +842,5 @@ export async function remarkable(deviceToken, { fetch = globalThis.fetch, cache,
         throw new Error(`couldn't fetch auth token: ${resp.statusText}`);
     }
     const userToken = await resp.text();
-    return new Remarkable(userToken, fetch, cache, subtle, syncHost);
+    return new Remarkable(userToken, fetch, subtle, syncHost, cacheLimitBytes, initCache);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rmapi-js",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "JavaScript implementation of the reMarkable 1.5 api",
   "repository": "git@github.com:erikbrinkman/rmapi-js.git",
   "author": "Erik Brinkman <erik.brinkman@gmail.com>",
@@ -21,14 +21,17 @@
   "scripts": {
     "doc": "typedoc",
     "fmt": "prettier --cache --write 'src/*.ts' '*.json' bundle.mjs",
-    "lint": "tsc && eslint --cache 'src/*.ts' bundle.mjs && typedoc --emit none",
+    "lint:es": "eslint --cache 'src/*.ts'",
+    "lint:doc": "typedoc --emit none",
+    "lint": "tsc && yarn lint:es && yarn lint:doc",
     "test": "jest --coverage",
-    "build": "tsc -p tsconfig.build.json && yarn node bundle.mjs",
+    "build": "tsc -p tsconfig.build.json && node bundle.mjs",
     "prepack": "yarn lint && yarn test && yarn build"
   },
   "dependencies": {
     "ajv": "^8.11.2",
     "base64-js": "^1.5.1",
+    "json-stable-stringify": "^1.0.2",
     "jtd": "^0.1.1",
     "uuid": "^9.0.0"
   },
@@ -38,7 +41,8 @@
     "@babel/preset-typescript": "^7.18.6",
     "@types/babel__core": "^7.1.20",
     "@types/babel__preset-env": "^7.9.2",
-    "@types/jest": "^29.2.4",
+    "@types/jest": "^29.2.5",
+    "@types/json-stable-stringify": "^1.0.34",
     "@types/node": "^18.11.18",
     "@types/uuid": "^9.0.0",
     "@typescript-eslint/eslint-plugin": "^5.47.1",
@@ -46,10 +50,10 @@
     "@yarnpkg/esbuild-plugin-pnp": "^3.0.0-rc.15",
     "babel-jest": "^29.3.1",
     "chalk": "^5.2.0",
-    "esbuild": "^0.16.10",
-    "eslint": "^8.30.0",
+    "esbuild": "^0.16.12",
+    "eslint": "^8.31.0",
     "eslint-config-prettier": "^8.5.0",
-    "eslint-plugin-jest": "^27.1.7",
+    "eslint-plugin-jest": "^27.2.0",
     "eslint-plugin-spellcheck": "^0.0.20",
     "eslint-plugin-tsdoc": "^0.2.17",
     "jest": "^29.3.1",
@@ -88,9 +92,15 @@
     "extends": [
       "eslint:recommended",
       "plugin:@typescript-eslint/recommended",
+      "plugin:@typescript-eslint/recommended-requiring-type-checking",
       "plugin:jest/recommended",
       "prettier"
     ],
+    "parserOptions": {
+      "project": [
+        "./tsconfig.json"
+      ]
+    },
     "env": {
       "node": true
     },