rmapi-js 14.1.0 → 14.2.0

package/dist/index.d.ts

@@ -667,6 +667,28 @@ declare class Remarkable {
      * @returns a reference to the deleted entry, with its new hash
      */
     delete(ref: ItemRef, refresh?: boolean): Promise<ItemRef>;
+    /**
+     * permanently delete an entry
+     *
+     * Unlike {@link delete | `delete`}, which moves an entry to the trash where
+     * the device can still restore it, this drops the entry from the account
+     * outright. Its files stay in the cloud, but nothing points at them anymore
+     * and nothing brings the entry back.
+     *
+     * Only the entry named goes: purging a folder leaves everything inside it
+     * pointing at a parent that's no longer there. Those entries stay in the
+     * account and {@link listItems | `listItems`} still returns them, but no
+     * folder holds them, so nothing browsing the tree will find them. Purge the
+     * contents first, or use {@link purgeTrash | `purgeTrash`}, which takes the
+     * whole tree.
+     *
+     * @example
+     * ```ts
+     * await api.purge(file);
+     * ```
+     * @param ref - a reference to the entry to purge
+     */
+    purge(ref: ItemRef, refresh?: boolean): Promise<void>;
     /**
      * rename an entry
      *
@@ -716,6 +738,41 @@ declare class Remarkable {
      * @returns references to the deleted entries, each with its new hash
      */
     bulkDelete(refs: readonly ItemRef[], refresh?: boolean): Promise<ItemRef[]>;
+    /**
+     * permanently delete many entries
+     *
+     * The bulk form of {@link purge | `purge`}, done in a single root write.
+     *
+     * @example
+     * ```ts
+     * await api.bulkPurge([file]);
+     * ```
+     *
+     * @param refs - references to the entries to purge
+     */
+    bulkPurge(refs: readonly ItemRef[], refresh?: boolean): Promise<void>;
+    /**
+     * permanently delete everything in the trash
+     *
+     * Trashing a folder doesn't touch what's inside it — those entries keep
+     * naming the folder as their parent, which is what lets the device restore
+     * them together — so the trash holds the whole tree hanging off it, not just
+     * the entries whose parent is "trash". This purges all of it in one root
+     * write.
+     *
+     * @example
+     * ```ts
+     * await api.purgeTrash();
+     * ```
+     *
+     * @remarks
+     * Finding that tree means reading every item's metadata, so this costs about
+     * as much as {@link listItems | `listItems`}.
+     *
+     * @param refresh - if true, refresh the root hash before purging
+     * @returns references to the entries that were purged
+     */
+    purgeTrash(refresh?: boolean): Promise<ItemRef[]>;
     /**
      * listen for sync notifications
      *

package/dist/index.js

@@ -407,26 +407,35 @@ class Remarkable {
                 hash: rootHash,
             });
             entries.push(entry);
-            let newRoot;
-            {
-                const env_2 = { stack: [], error: void 0, hasError: false };
-                try {
-                    const rootEntry = __addDisposableResource(env_2, await this.raw.putEntries(ROOT_LIST, entries, 4), true);
-                    newRoot = rootEntry.hash;
-                }
-                catch (e_2) {
-                    env_2.error = e_2;
-                    env_2.hasError = true;
-                }
-                finally {
-                    const result_2 = __disposeResources(env_2);
-                    if (result_2)
-                        await result_2;
-                }
-            }
-            await this.#putRootHash(newRoot, generation);
+            await this.#writeRoot(entries, generation);
         });
     }
+    /**
+     * upload a new root index and point the account at it
+     *
+     * Every blob the index names must already be uploaded, since the root hash
+     * lands as soon as the index does.
+     */
+    async #writeRoot(entries, generation) {
+        let newRoot;
+        {
+            const env_2 = { stack: [], error: void 0, hasError: false };
+            try {
+                const rootEntry = __addDisposableResource(env_2, await this.raw.putEntries(ROOT_LIST, entries, 4), true);
+                newRoot = rootEntry.hash;
+            }
+            catch (e_2) {
+                env_2.error = e_2;
+                env_2.hasError = true;
+            }
+            finally {
+                const result_2 = __disposeResources(env_2);
+                if (result_2)
+                    await result_2;
+            }
+        }
+        await this.#putRootHash(newRoot, generation);
+    }
     async #authedFetch(url, { body, method = "POST", headers = {}, }) {
         // the root PUT is a compare-and-set; retrying a lost-but-applied response
         // would resurface as a false generation conflict and be double-applied by
@@ -1517,6 +1526,30 @@ class Remarkable {
     async delete(ref, refresh = false) {
         return await this.move(ref, TRASH_ID, refresh);
     }
+    /**
+     * permanently delete an entry
+     *
+     * Unlike {@link delete | `delete`}, which moves an entry to the trash where
+     * the device can still restore it, this drops the entry from the account
+     * outright. Its files stay in the cloud, but nothing points at them anymore
+     * and nothing brings the entry back.
+     *
+     * Only the entry named goes: purging a folder leaves everything inside it
+     * pointing at a parent that's no longer there. Those entries stay in the
+     * account and {@link listItems | `listItems`} still returns them, but no
+     * folder holds them, so nothing browsing the tree will find them. Purge the
+     * contents first, or use {@link purgeTrash | `purgeTrash`}, which takes the
+     * whole tree.
+     *
+     * @example
+     * ```ts
+     * await api.purge(file);
+     * ```
+     * @param ref - a reference to the entry to purge
+     */
+    async purge(ref, refresh = false) {
+        await this.bulkPurge([ref], refresh);
+    }
     /**
      * rename an entry
      *
@@ -1631,6 +1664,118 @@ class Remarkable {
     async bulkDelete(refs, refresh = false) {
         return await this.bulkMove(refs, TRASH_ID, refresh);
     }
+    /**
+     * permanently delete many entries
+     *
+     * The bulk form of {@link purge | `purge`}, done in a single root write.
+     *
+     * @example
+     * ```ts
+     * await api.bulkPurge([file]);
+     * ```
+     *
+     * @param refs - references to the entries to purge
+     */
+    async bulkPurge(refs, refresh = false) {
+        if (!refs.length) {
+            return;
+        }
+        await this.#withRetry(async () => {
+            const [rootHash, generation] = await this.#getRootHash(refresh);
+            const { entries } = await this.raw.getEntries({
+                id: ROOT_LIST,
+                hash: rootHash,
+            });
+            const wanted = new Set(refs.map((ref) => `${ref.id}\0${ref.hash}`));
+            const found = new Set();
+            const newEntries = [];
+            for (const entry of entries) {
+                const key = `${entry.id}\0${entry.hash}`;
+                if (wanted.has(key)) {
+                    found.add(key);
+                }
+                else {
+                    newEntries.push(entry);
+                }
+            }
+            for (const ref of refs) {
+                if (!found.has(`${ref.id}\0${ref.hash}`)) {
+                    throw new HashNotFoundError(ref.hash);
+                }
+            }
+            await this.#writeRoot(newEntries, generation);
+        });
+    }
+    /**
+     * permanently delete everything in the trash
+     *
+     * Trashing a folder doesn't touch what's inside it — those entries keep
+     * naming the folder as their parent, which is what lets the device restore
+     * them together — so the trash holds the whole tree hanging off it, not just
+     * the entries whose parent is "trash". This purges all of it in one root
+     * write.
+     *
+     * @example
+     * ```ts
+     * await api.purgeTrash();
+     * ```
+     *
+     * @remarks
+     * Finding that tree means reading every item's metadata, so this costs about
+     * as much as {@link listItems | `listItems`}.
+     *
+     * @param refresh - if true, refresh the root hash before purging
+     * @returns references to the entries that were purged
+     */
+    async purgeTrash(refresh = false) {
+        return await this.#withRetry(async () => {
+            const [rootHash, generation] = await this.#getRootHash(refresh);
+            const { entries } = await this.raw.getEntries({
+                id: ROOT_LIST,
+                hash: rootHash,
+            });
+            const parents = await Promise.all(entries.map(async (entry) => (await this.getMetadata(entry)).parent));
+            const children = new Map();
+            for (const [ind, entry] of entries.entries()) {
+                const siblings = children.get(parents[ind]);
+                if (siblings === undefined) {
+                    children.set(parents[ind], [entry]);
+                }
+                else {
+                    siblings.push(entry);
+                }
+            }
+            const trashed = new Set();
+            let frontier = children.get(TRASH_ID) ?? [];
+            while (frontier.length) {
+                const next = [];
+                for (const { id } of frontier) {
+                    // skipping what we've already seen also ends a parent cycle, which
+                    // the account shouldn't have but which would loop here forever
+                    if (!trashed.has(id)) {
+                        trashed.add(id);
+                        next.push(...(children.get(id) ?? []));
+                    }
+                }
+                frontier = next;
+            }
+            if (!trashed.size) {
+                return [];
+            }
+            const purged = [];
+            const newEntries = [];
+            for (const entry of entries) {
+                if (trashed.has(entry.id)) {
+                    purged.push({ id: entry.id, hash: entry.hash });
+                }
+                else {
+                    newEntries.push(entry);
+                }
+            }
+            await this.#writeRoot(newEntries, generation);
+            return purged;
+        });
+    }
     /**
      * listen for sync notifications
      *