@procedures/collections 0.13.1 → 0.13.2

package/dist/undo/inverse.js

@@ -0,0 +1,186 @@
+import { applyPatch, isPatchOperations, patchProblems } from "@procedures/client/query";
+const INDEX = /^(?:0|[1-9][0-9]*)$/;
+/** True for an object that is not an array and not null. */
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The keys of an object whose values are not `undefined`. */
+function definedKeys(value) {
+    return value === undefined ? [] : Object.keys(value).filter((key) => value[key] !== undefined);
+}
+/** The child of a container at a key, and whether the container has it. */
+function childOf(container, key) {
+    if (Array.isArray(container)) {
+        return INDEX.test(key) && Number(key) < container.length ? { found: true, value: container[Number(key)] } : { found: false };
+    }
+    return isObject(container) && Object.hasOwn(container, key) ? { found: true, value: container[key] } : { found: false };
+}
+/** The value at a path, and whether it is there. */
+function valueAt(value, path) {
+    let current = { found: true, value };
+    for (const key of path) {
+        current = childOf(current.value, key);
+        if (!current.found)
+            return current;
+    }
+    return current;
+}
+/** This function sets a key as an own property, also the key `__proto__`. */
+function define(target, key, value) {
+    Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+}
+/** True when two JSON values are equal. The order of the keys of an object does not count. */
+function equal(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a))
+        return Array.isArray(b) && a.length === b.length && a.every((item, i) => equal(item, b[i]));
+    if (!isObject(a) || !isObject(b))
+        return false;
+    const keys = definedKeys(a);
+    return keys.length === definedKeys(b).length && keys.every((key) => b[key] !== undefined && equal(a[key], b[key]));
+}
+/**
+ * This function gives the patch that undoes a patch: applied to the item after the patch, the
+ * inverse gives the item before the patch again. It gives `undefined` when no patch can undo it
+ * exactly. Then keep the whole item before the change.
+ *
+ * - The inverse of `$remove` of an element is an `$insert` of the element, and the inverse of an
+ *   `$insert` is a `$remove`. The inverse does not keep the whole array.
+ * - The inverse of `$set` and `$unset` sets each old value again, or removes the new path.
+ * - The indices of the inverse refer to the item after the patch.
+ * - The function applies the inverse to check it. It gives `undefined` when the check fails, for
+ *   example after the removal of two adjacent elements, or when `before` is not an object.
+ *
+ * @example
+ * ```ts
+ * inversePatch({ tags: ["a", "b"] }, { $remove: ["tags.0"] }); // { $insert: { "tags.0": "a" } }
+ * ```
+ *
+ * @throws TypeError when `applyPatch` refuses the patch
+ */
+export function inversePatch(before, patch) {
+    const after = applyPatch(before, patch);
+    if (!isObject(before))
+        return undefined;
+    const inverse = isPatchOperations(patch) ? inverseOfOperations(before, patch) : inverseOfMerge(before, patch);
+    if (inverse === undefined || patchProblems(inverse).length > 0)
+        return undefined;
+    try {
+        return equal(applyPatch(after, inverse), before) ? inverse : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The inverse of a JSON Merge Patch: the old value of each top field, or its removal. */
+function inverseOfMerge(before, patch) {
+    const set = {};
+    const remove = [];
+    for (const key of definedKeys(patch)) {
+        // A field name with a dot is a path for the operations, so the operations cannot name it
+        if (key.includes(".") || key.startsWith("$"))
+            return undefined;
+        if (Object.hasOwn(before, key))
+            define(set, key, before[key]);
+        else
+            remove.push(key);
+    }
+    return operations(set, remove, {});
+}
+/** The inverse of the operations of a patch. */
+function inverseOfOperations(before, patch) {
+    // The moves of each array, by the path of the array in the item before the patch
+    const moves = new Map();
+    const addMove = (path, kind) => {
+        const array = path.slice(0, -1).join(".");
+        const entry = moves.get(array) ?? { kind, indices: [] };
+        entry.indices.push(Number(path.at(-1)));
+        moves.set(array, entry);
+    };
+    const removals = (patch.$remove ?? []).map((key) => key.split("."));
+    for (const path of removals) {
+        const parent = valueAt(before, path.slice(0, -1));
+        if (parent.found && Array.isArray(parent.value) && childOf(parent.value, path.at(-1)).found)
+            addMove(path, "remove");
+    }
+    const insertions = definedKeys(patch.$insert).map((key) => key.split("."));
+    for (const path of insertions)
+        addMove(path, "insert");
+    // A path of the item before the patch, as a path of the item after it
+    const translate = (path) => {
+        const out = [...path];
+        for (let i = 0; i < path.length; i++) {
+            const move = moves.get(path.slice(0, i).join("."));
+            if (!move || !INDEX.test(path[i]))
+                continue;
+            const index = Number(path[i]);
+            const shift = move.kind === "remove" ? -move.indices.filter((r) => r < index).length : move.indices.filter((n) => n <= index).length;
+            out[i] = String(index + shift);
+        }
+        return out.join(".");
+    };
+    const set = {};
+    const remove = new Set();
+    const insert = {};
+    const put = (target, key, value) => {
+        if (Object.hasOwn(target, key))
+            return false;
+        define(target, key, value);
+        return true;
+    };
+    // `$set` and `$unset`: the old value, or the removal of the part that the patch made
+    const restore = (path, made) => {
+        let current = before;
+        for (let n = 0; n < path.length; n++) {
+            const child = childOf(current, path[n]);
+            if (!child.found) {
+                if (made)
+                    remove.add(translate(path.slice(0, n + 1)));
+                return true;
+            }
+            current = child.value;
+            // `$set` makes an object of a null on its path
+            if (made && current === null && n < path.length - 1)
+                return put(set, translate(path.slice(0, n + 1)), null);
+        }
+        return put(set, translate(path), current);
+    };
+    for (const key of definedKeys(patch.$set))
+        if (!restore(key.split("."), true))
+            return undefined;
+    for (const key of patch.$unset ?? [])
+        if (!restore(key.split("."), false))
+            return undefined;
+    // `$remove`: an `$insert` of the element, or the old value of a field of an object
+    for (const path of removals) {
+        const parent = valueAt(before, path.slice(0, -1));
+        if (!parent.found || !Array.isArray(parent.value)) {
+            if (!restore(path, false))
+                return undefined;
+            continue;
+        }
+        const element = childOf(parent.value, path.at(-1));
+        if (!element.found)
+            continue;
+        const index = Number(path.at(-1));
+        const target = `${translate(path.slice(0, -1))}.${index - moves.get(path.slice(0, -1).join(".")).indices.filter((r) => r < index).length}`;
+        if (!put(insert, target, element.value))
+            return undefined;
+    }
+    // `$insert`: a `$remove` of the new element
+    for (const path of insertions) {
+        const index = Number(path.at(-1));
+        remove.add(`${translate(path.slice(0, -1))}.${index + moves.get(path.slice(0, -1).join(".")).indices.filter((n) => n < index).length}`);
+    }
+    return operations(set, [...remove], insert);
+}
+/** The operations, without the empty ones. */
+function operations(set, remove, insert) {
+    return {
+        ...(Object.keys(set).length > 0 ? { $set: set } : {}),
+        ...(remove.length > 0 ? { $remove: remove } : {}),
+        ...(Object.keys(insert).length > 0 ? { $insert: insert } : {}),
+    };
+}
+//# sourceMappingURL=inverse.js.map

package/dist/undo/inverse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inverse.js","sourceRoot":"","sources":["../../src/undo/inverse.ts"],"names":[],"mappings":"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"}

package/dist/undo/undo-log.d.ts

@@ -0,0 +1,120 @@
+import { type StoragePatch, type StoragePatchOperations } from "@procedures/client/query";
+import type { CollectionStorage } from "../storage/interface.js";
+/** One change of one item, as the caller gives it to `UndoLog.record`. */
+export interface UndoChange {
+    /** The name of the collection of the item. */
+    readonly collection: string;
+    /** The id of the item. */
+    readonly id: string;
+    /** The item before the change. `undefined` or `null`: the item did not exist. */
+    readonly before: unknown;
+    /** The patch of the change. Without a patch, the change replaced or removed the whole item. */
+    readonly patch?: StoragePatch;
+    /**
+     * The item after the change, as the storage keeps it. `undefined` or `null`: the change removed
+     * the item. With a patch, the default is `applyPatch(before, patch)`. Give the result of
+     * `patch` of the storage when the storage changes the value, for example when it adds the id.
+     */
+    readonly after?: unknown;
+    /**
+     * The changes with the same group undo together, for example the two items of a move. Give each
+     * action a new group id: two actions with one id undo as one.
+     */
+    readonly group?: string;
+}
+/** One entry of an undo log. */
+export interface UndoEntry {
+    /** The id of the entry in the storage of the log. */
+    readonly key: string;
+    /** The name of the collection of the item. */
+    readonly collection: string;
+    /** The id of the item. */
+    readonly id: string;
+    /** The patch that undoes the change. An entry without it restores `item`. */
+    readonly inverse?: StoragePatchOperations;
+    /** The whole item before the change, when the entry has no `inverse`. `null`: the item did not exist. */
+    readonly item?: unknown;
+    /** The fingerprint of the item after the change. The undo refuses an item that changed since. */
+    readonly after: string;
+    /** The group of the change. */
+    readonly group?: string;
+    /** The time of the change, in milliseconds. */
+    readonly at: number;
+    /** The order of the entries of one log with the same time. */
+    readonly seq: number;
+}
+/** The options of an `UndoLog`. */
+export interface UndoLogOptions {
+    /** The most entries. The log removes the oldest entries past this number. The default is 50. */
+    readonly cap?: number;
+    /** The clock, in milliseconds. The default is `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * The error of an undo of an item that changed after the recorded change, for example by another
+ * writer. The undo writes nothing, and its entries stay in the log.
+ */
+export declare class UndoConflictError extends Error {
+    /** The entry whose item changed. */
+    readonly entry: UndoEntry;
+    constructor(entry: UndoEntry);
+}
+/**
+ * The fingerprint of an item: a 64-bit hash of its canonical JSON text, in hexadecimal. A missing
+ * item and `null` have the same fingerprint. Two items with the same fields in another order have
+ * the same fingerprint.
+ */
+export declare function fingerprintOf(item: unknown): string;
+/**
+ * An undo log of the changes of items in collection storages (Graph's split, wave 2, W10). Each
+ * entry keeps the patch that undoes one change (`inversePatch`), or the whole item before the
+ * change when no patch can undo it, and the fingerprint of the item after the change.
+ *
+ * `undo()` undoes the newest entry and the entries of its group. It first reads each item and
+ * compares it with the fingerprint. When another writer changed an item after the recorded change,
+ * the undo writes nothing and gives an `UndoConflictError`. Then each item gets one write through
+ * its storage, so an undo reaches the observers of the storage as a change.
+ *
+ * @example
+ * ```ts
+ * const log = new UndoLog(new InMemoryStorage<UndoEntry>(), (name) => storages[name]);
+ * const before = await notes.get("n1");
+ * const after = await notes.patch!("n1", { $remove: ["tags.0"] });
+ * await log.record({ collection: "notes", id: "n1", before, patch: { $remove: ["tags.0"] }, after });
+ * await log.undo(); // the tag is back
+ * ```
+ */
+export declare class UndoLog {
+    #private;
+    /**
+     * @param entries - The storage of the entries of the log
+     * @param storageOf - The storage of each collection that the log can undo
+     * @param options - The cap and the clock
+     */
+    constructor(entries: CollectionStorage<UndoEntry>, storageOf: (collection: string) => CollectionStorage<unknown> | undefined, options?: UndoLogOptions);
+    /**
+     * This method records one change, and gives its entry. It keeps the inverse patch of the change
+     * when one exists, or else the whole item before the change, and the fingerprint of the item
+     * after the change. Then it removes the oldest entries past the cap.
+     *
+     * @throws TypeError when `applyPatch` refuses the patch of the change
+     */
+    record(change: UndoChange): Promise<UndoEntry>;
+    /** This method gives the entries, the newest first. */
+    entries(): Promise<UndoEntry[]>;
+    /**
+     * This method undoes the newest change, and each change of its group, the newest first. It
+     * removes their entries, and gives them. An empty list means that the log is empty.
+     *
+     * It reads and checks each item before the first write. A refused undo writes nothing, and its
+     * entries stay in the log.
+     *
+     * A change by another writer between that read and the write of the undo is still overwritten. A
+     * storage with versions can close that window later with a conditional write.
+     *
+     * @throws UndoConflictError when an item changed after its recorded change
+     * @throws Error when the log has no storage for a collection
+     */
+    undo(): Promise<UndoEntry[]>;
+}
+//# sourceMappingURL=undo-log.d.ts.map

package/dist/undo/undo-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"undo-log.d.ts","sourceRoot":"","sources":["../../src/undo/undo-log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,YAAY,EAAE,KAAK,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACtG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAGjE,0EAA0E;AAC1E,MAAM,WAAW,UAAU;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,gCAAgC;AAChC,MAAM,WAAW,SAAS;IACxB,qDAAqD;IACrD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAC;IAC1C,yGAAyG;IACzG,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,iGAAiG;IACjG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC7B,gGAAgG;IAChG,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAE1B,YAAY,KAAK,EAAE,SAAS,EAI3B;CACF;AAkBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAWnD;AAOD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,OAAO;;IAOlB;;;;OAIG;IACH,YACE,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,EACrC,SAAS,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,iBAAiB,CAAC,OAAO,CAAC,GAAG,SAAS,EACzE,OAAO,GAAE,cAAmB,EAM7B;IAED;;;;;;OAMG;IACG,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAoBnD;IAED,uDAAuD;IACjD,OAAO,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAEpC;IAED;;;;;;;;;;;;OAYG;IACG,IAAI,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAyBjC;CACF"}

package/dist/undo/undo-log.js

@@ -0,0 +1,165 @@
+import { applyPatch } from "@procedures/client/query";
+import { inversePatch } from "./inverse.js";
+/**
+ * The error of an undo of an item that changed after the recorded change, for example by another
+ * writer. The undo writes nothing, and its entries stay in the log.
+ */
+export class UndoConflictError extends Error {
+    /** The entry whose item changed. */
+    entry;
+    constructor(entry) {
+        super(`The undo of ${entry.collection}/${entry.id} is refused: the item changed after the recorded change`);
+        this.name = "UndoConflictError";
+        this.entry = entry;
+    }
+}
+/** True for an object that is not an array and not null. */
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The JSON text of a value with the keys of each object in order. A missing item is `undefined`. */
+function canonical(value) {
+    if (value === undefined || value === null)
+        return "null";
+    if (Array.isArray(value))
+        return `[${value.map((item) => (item === undefined ? "null" : canonical(item))).join(",")}]`;
+    if (isObject(value)) {
+        const keys = Object.keys(value).filter((key) => value[key] !== undefined).sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+/**
+ * The fingerprint of an item: a 64-bit hash of its canonical JSON text, in hexadecimal. A missing
+ * item and `null` have the same fingerprint. Two items with the same fields in another order have
+ * the same fingerprint.
+ */
+export function fingerprintOf(item) {
+    const text = canonical(item);
+    // Two 32-bit FNV-1a hashes with different offsets: no dependency, and the same in each runtime
+    let a = 0x811c9dc5;
+    let b = 0x01000193 ^ 0x5bd1e995;
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        a = Math.imul(a ^ code, 0x01000193);
+        b = Math.imul(b ^ code, 0x01000193) ^ (b >>> 15);
+    }
+    return (a >>> 0).toString(16).padStart(8, "0") + (b >>> 0).toString(16).padStart(8, "0");
+}
+/** The newest entry first: by time, then by the order of the log. */
+function newestFirst(a, b) {
+    return b.at - a.at || b.seq - a.seq;
+}
+/**
+ * An undo log of the changes of items in collection storages (Graph's split, wave 2, W10). Each
+ * entry keeps the patch that undoes one change (`inversePatch`), or the whole item before the
+ * change when no patch can undo it, and the fingerprint of the item after the change.
+ *
+ * `undo()` undoes the newest entry and the entries of its group. It first reads each item and
+ * compares it with the fingerprint. When another writer changed an item after the recorded change,
+ * the undo writes nothing and gives an `UndoConflictError`. Then each item gets one write through
+ * its storage, so an undo reaches the observers of the storage as a change.
+ *
+ * @example
+ * ```ts
+ * const log = new UndoLog(new InMemoryStorage<UndoEntry>(), (name) => storages[name]);
+ * const before = await notes.get("n1");
+ * const after = await notes.patch!("n1", { $remove: ["tags.0"] });
+ * await log.record({ collection: "notes", id: "n1", before, patch: { $remove: ["tags.0"] }, after });
+ * await log.undo(); // the tag is back
+ * ```
+ */
+export class UndoLog {
+    #entries;
+    #storageOf;
+    #cap;
+    #now;
+    #seq = 0;
+    /**
+     * @param entries - The storage of the entries of the log
+     * @param storageOf - The storage of each collection that the log can undo
+     * @param options - The cap and the clock
+     */
+    constructor(entries, storageOf, options = {}) {
+        this.#entries = entries;
+        this.#storageOf = storageOf;
+        this.#cap = Math.max(1, Math.floor(options.cap ?? 50));
+        this.#now = options.now ?? Date.now;
+    }
+    /**
+     * This method records one change, and gives its entry. It keeps the inverse patch of the change
+     * when one exists, or else the whole item before the change, and the fingerprint of the item
+     * after the change. Then it removes the oldest entries past the cap.
+     *
+     * @throws TypeError when `applyPatch` refuses the patch of the change
+     */
+    async record(change) {
+        const at = this.#now();
+        const seq = ++this.#seq;
+        const inverse = change.patch === undefined ? undefined : inversePatch(change.before, change.patch);
+        const after = "after" in change || change.patch === undefined ? change.after : applyPatch(change.before, change.patch);
+        const entry = {
+            key: `undo_${at}_${seq}_${Math.random().toString(36).slice(2, 8)}`,
+            collection: change.collection,
+            id: change.id,
+            ...(inverse === undefined ? { item: change.before ?? null } : { inverse }),
+            after: fingerprintOf(after),
+            ...(change.group === undefined ? {} : { group: change.group }),
+            at,
+            seq,
+        };
+        await this.#entries.set(entry.key, entry);
+        const all = (await this.#entries.getAll()).sort(newestFirst);
+        const old = all.slice(this.#cap).map((e) => e.key);
+        if (old.length > 0)
+            await this.#entries.deleteBatch(old);
+        return entry;
+    }
+    /** This method gives the entries, the newest first. */
+    async entries() {
+        return (await this.#entries.getAll()).sort(newestFirst);
+    }
+    /**
+     * This method undoes the newest change, and each change of its group, the newest first. It
+     * removes their entries, and gives them. An empty list means that the log is empty.
+     *
+     * It reads and checks each item before the first write. A refused undo writes nothing, and its
+     * entries stay in the log.
+     *
+     * A change by another writer between that read and the write of the undo is still overwritten. A
+     * storage with versions can close that window later with a conditional write.
+     *
+     * @throws UndoConflictError when an item changed after its recorded change
+     * @throws Error when the log has no storage for a collection
+     */
+    async undo() {
+        const all = await this.entries();
+        const top = all[0];
+        if (top === undefined)
+            return [];
+        const entries = top.group === undefined ? [top] : all.filter((e) => e.group === top.group);
+        // The check, and the value of each item after the undo of its entries (newest first)
+        const items = new Map();
+        for (const entry of entries) {
+            const storage = this.#storageOf(entry.collection);
+            if (storage === undefined)
+                throw new Error(`The undo log has no storage for the collection ${entry.collection}`);
+            const address = JSON.stringify([entry.collection, entry.id]);
+            const item = items.get(address) ?? { storage, id: entry.id, value: await storage.get(entry.id) };
+            if (fingerprintOf(item.value) !== entry.after)
+                throw new UndoConflictError(entry);
+            item.value = entry.inverse === undefined ? (entry.item ?? undefined) : applyPatch(item.value, entry.inverse);
+            items.set(address, item);
+        }
+        // One write for each item
+        for (const { storage, id, value } of items.values()) {
+            if (value === undefined || value === null)
+                await storage.delete(id);
+            else
+                await storage.set(id, value);
+        }
+        await this.#entries.deleteBatch(entries.map((e) => e.key));
+        return entries;
+    }
+}
+//# sourceMappingURL=undo-log.js.map

package/dist/undo/undo-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"undo-log.js","sourceRoot":"","sources":["../../src/undo/undo-log.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/collections",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "description": "Collections for TypeScript: ArrayList, LinkedList, ArrayDeque, HashMap, LinkedHashMap, TreeMap (red-black), PriorityQueue, LRU and TTL maps, async queues, channels and collectors, tested with fast-check.",
   "keywords": [
     "collections",
@@ -59,7 +59,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@procedures/client": "0.13.1"
+    "@procedures/client": "0.13.2"
   },
   "devDependencies": {
     "typescript": "^7.0.2",

package/src/index.ts

@@ -78,6 +78,9 @@ export * from "./overlay/index.js";
 // The order of a list as data: a rank between two neighbors, and the index of a drop
 export * from "./order/index.js";
 
+// The undo of the changes of items: the inverse of a patch, and an undo log
+export * from "./undo/index.js";
+
 // Export queue interfaces with disambiguation for PriorityQueue
 export type {
   ReadonlyQueue,

package/src/storage/interface.ts

@@ -172,8 +172,9 @@ export interface CollectionStorage<T> {
   /**
    * This method changes one item in one step. The fields are a JSON Merge Patch (RFC 7386): each
    * field replaces the field of the item, an object field merges into an object field, and `null`
-   * removes the field. Or they are the operations `{ $set, $unset }`: `$set` can set `null` and
-   * nested field paths. Two patches of one item at the same time keep the fields of each. A storage
+   * removes the field. Or they are the operations `{ $set, $unset, $remove, $insert }`: `$set` can
+   * set `null` and nested field paths, and `$remove` and `$insert` move the elements of arrays.
+   * Two patches of one item at the same time keep the fields of each. A storage
    * without this method cannot change an item in one step.
    *
    * @param id - Item identifier

package/src/testing/storage-contract.ts

@@ -940,6 +940,35 @@ export function collectionStorageContract(options: CollectionStorageContractOpti
     }),
   );
 
+  add("patch() with $remove and $insert moves the elements of an array, and each index refers to the item before the patch", (context) =>
+    withStorage(create, async (typed) => {
+      if (lacks(typed, "patch", context)) return;
+      const storage = typed as unknown as JsonStorage;
+      await storage.set("a", { id: "a", tags: ["a", "b", "c", "d"], rows: [{ n: 1, keys: ["x"] }, { n: 2, keys: ["y"] }], meta: { kind: "k1" } });
+      same(
+        await storage.patch!("a", { $remove: ["tags.1", "tags.3", "meta.kind"], $insert: { "rows.1.keys.0": "w" } }),
+        { id: "a", tags: ["a", "c"], rows: [{ n: 1, keys: ["x"] }, { n: 2, keys: ["w", "y"] }], meta: {} },
+        "patch() with $remove and $insert",
+      );
+      same(
+        await storage.patch!("a", { $insert: { "tags.0": "z", "tags.2": "e" }, $remove: ["rows.0", "missing.0"], $set: { "rows.1.n": 3 } }),
+        { id: "a", tags: ["z", "a", "c", "e"], rows: [{ n: 3, keys: ["w", "y"] }], meta: {} },
+        "patch() that inserts at the start and at the end, and removes a missing path",
+      );
+      const after = { id: "a", tags: ["z", "a", "c", "e"], rows: [{ n: 3, keys: ["w", "y"] }], meta: {} };
+      const wrong: Array<[string, unknown]> = [
+        ["a $remove that is not a list of paths", { $remove: "tags" }],
+        ["an $insert path that does not end with an index", { $insert: { "meta.kind": 1 } }],
+        ["a $remove and an $insert in the same array", { $remove: ["tags.0"], $insert: { "tags.1": "q" } }],
+        ["a path under a removed element", { $remove: ["rows.0"], $set: { "rows.0.n": 4 } }],
+        ["an $insert past the end of an array", { $insert: { "tags.9": "q" } }],
+        ["an $insert into a value that is not an array", { $insert: { "meta.0": "q" } }],
+      ];
+      for (const [what, fields] of wrong) await rejects(() => storage.patch!("a", fields as never), `patch() with ${what}`);
+      same(await storage.get("a"), after, "get() after the patches that were not correct");
+    }),
+  );
+
   add("patch() runs in one step: patches of one item at the same time keep each field", (context) =>
     withStorage(create, async (typed) => {
       if (lacks(typed, "patch", context)) return;

package/src/undo/index.ts

@@ -0,0 +1,6 @@
+/**
+ * The undo of the changes of items (Graph's split, wave 2, W10). `inversePatch` gives the patch
+ * that undoes a patch, and `UndoLog` keeps the undo of each change in a storage.
+ */
+export { inversePatch } from "./inverse.js";
+export { fingerprintOf, UndoConflictError, UndoLog, type UndoChange, type UndoEntry, type UndoLogOptions } from "./undo-log.js";