meridian-sdk 1.2.0 → 1.3.0

package/dist/undo/UndoManager.d.ts

@@ -0,0 +1,74 @@
+import { RGAHandle } from "../crdt/rga.js";
+import { TreeHandle } from "../crdt/tree.js";
+type SupportedHandle = RGAHandle | TreeHandle;
+/**
+ * CRDT-aware per-client undo/redo manager.
+ *
+ * Wraps an RGAHandle or TreeHandle. Intercept mutating methods via the manager
+ * instead of the handle directly to record undo history.
+ *
+ * Rules:
+ * - Undo sends a new valid CrdtOp (never a state rollback).
+ * - Only the local client's ops are tracked — remote ops are unaffected.
+ * - RGA Delete is NOT recorded (tombstones are final).
+ * - Stack is capped at 100 batches; oldest entries are dropped silently.
+ *
+ * @example
+ * ```ts
+ * const manager = new UndoManager(client.rga("doc"));
+ * manager.insert(0, "hello");
+ * manager.undo(); // sends 5 × RgaOp::Delete
+ * ```
+ */
+export declare class UndoManager<H extends SupportedHandle> {
+    private readonly handle;
+    private undoStack;
+    private redoStack;
+    private readonly stackListeners;
+    private openBatch;
+    private debounceTimer;
+    constructor(handle: H);
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    /**
+     * Subscribe to stack change notifications (fired after any undo/redo/record).
+     * @returns Unsubscribe function.
+     */
+    onStackChange(listener: () => void): () => void;
+    /** Begin accumulating entries into a single undo step. */
+    startBatch(): void;
+    /** Commit the open batch as one entry on the undo stack. No-op if no batch is open. */
+    commitBatch(): void;
+    /** Discard the open batch without recording anything. */
+    cancelBatch(): void;
+    undo(): void;
+    redo(): void;
+    /**
+     * Insert text at visible position. Records undo entry with HLC node IDs.
+     * Uses 250ms debounce — consecutive inserts within the window form one batch.
+     */
+    insert(pos: number, text: string, ttlMs?: number): string[];
+    /**
+     * Delete characters by position. NOT recorded — RGA delete is non-undoable
+     * (tombstones are final; content is irrecoverable).
+     * clearRedo() is intentional: a destructive untracked op should invalidate
+     * any pending redo history, matching ProseMirror/Yjs behaviour.
+     */
+    delete(pos: number, length: number, ttlMs?: number): void;
+    addNode(parentId: string | null, position: string, value: string, ttlMs?: number): string;
+    moveNode(nodeId: string, newParentId: string | null, newPosition: string, ttlMs?: number): void;
+    updateNode(nodeId: string, value: string, ttlMs?: number): void;
+    deleteNode(nodeId: string, ttlMs?: number): void;
+    private applyInverse;
+    private record;
+    /** Record with 250ms debounce — consecutive calls within window share one batch. */
+    private recordWithDebounce;
+    private pushUndo;
+    private clearRedo;
+    private notifyStackChange;
+    private asRGA;
+    private asTree;
+    private getCrdtId;
+}
+export {};
+//# sourceMappingURL=UndoManager.d.ts.map

package/dist/undo/UndoManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UndoManager.d.ts","sourceRoot":"","sources":["../../src/undo/UndoManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAc7C,KAAK,eAAe,GAAG,SAAS,GAAG,UAAU,CAAC;AAE9C;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,WAAW,CAAC,CAAC,SAAS,eAAe;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAI;IAC3B,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IAGxD,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,aAAa,CAA8C;gBAEvD,MAAM,EAAE,CAAC;IAMrB,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;OAGG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO/C,0DAA0D;IAC1D,UAAU,IAAI,IAAI;IAMlB,uFAAuF;IACvF,WAAW,IAAI,IAAI;IAOnB,yDAAyD;IACzD,WAAW,IAAI,IAAI;IAMnB,IAAI,IAAI,IAAI;IAkBZ,IAAI,IAAI,IAAI;IAsBZ;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE;IAmB3D;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAOzD,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;IAgBzF,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAiB/F,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAgB/D,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAmBhD,OAAO,CAAC,YAAY;IAsEpB,OAAO,CAAC,MAAM;IAQd,oFAAoF;IACpF,OAAO,CAAC,kBAAkB;IAgB1B,OAAO,CAAC,QAAQ;IAQhB,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,KAAK;IAOb,OAAO,CAAC,MAAM;IAOd,OAAO,CAAC,SAAS;CAGlB"}

package/dist/undo/UndoManager.js

@@ -0,0 +1,318 @@
+import { RGAHandle } from "../crdt/rga.js";
+import { TreeHandle } from "../crdt/tree.js";
+const MAX_STACK_DEPTH = 100;
+const RGA_DEBOUNCE_MS = 250;
+/**
+ * CRDT-aware per-client undo/redo manager.
+ *
+ * Wraps an RGAHandle or TreeHandle. Intercept mutating methods via the manager
+ * instead of the handle directly to record undo history.
+ *
+ * Rules:
+ * - Undo sends a new valid CrdtOp (never a state rollback).
+ * - Only the local client's ops are tracked — remote ops are unaffected.
+ * - RGA Delete is NOT recorded (tombstones are final).
+ * - Stack is capped at 100 batches; oldest entries are dropped silently.
+ *
+ * @example
+ * ```ts
+ * const manager = new UndoManager(client.rga("doc"));
+ * manager.insert(0, "hello");
+ * manager.undo(); // sends 5 × RgaOp::Delete
+ * ```
+ */
+export class UndoManager {
+    handle;
+    undoStack = [];
+    redoStack = [];
+    stackListeners = new Set();
+    // Batch accumulation
+    openBatch = null;
+    debounceTimer = null;
+    constructor(handle) {
+        this.handle = handle;
+    }
+    // ─── Stack state ────────────────────────────────────────────────────────────
+    get canUndo() {
+        return this.undoStack.length > 0;
+    }
+    get canRedo() {
+        return this.redoStack.length > 0;
+    }
+    /**
+     * Subscribe to stack change notifications (fired after any undo/redo/record).
+     * @returns Unsubscribe function.
+     */
+    onStackChange(listener) {
+        this.stackListeners.add(listener);
+        return () => { this.stackListeners.delete(listener); };
+    }
+    // ─── Manual batching ────────────────────────────────────────────────────────
+    /** Begin accumulating entries into a single undo step. */
+    startBatch() {
+        if (this.openBatch === null) {
+            this.openBatch = [];
+        }
+    }
+    /** Commit the open batch as one entry on the undo stack. No-op if no batch is open. */
+    commitBatch() {
+        if (this.openBatch !== null && this.openBatch.length > 0) {
+            this.pushUndo({ entries: this.openBatch });
+        }
+        this.openBatch = null;
+    }
+    /** Discard the open batch without recording anything. */
+    cancelBatch() {
+        this.openBatch = null;
+    }
+    // ─── Undo / Redo ────────────────────────────────────────────────────────────
+    undo() {
+        const batch = this.undoStack.pop();
+        if (batch === undefined)
+            return;
+        const inverseEntries = [];
+        // Apply inverse ops in reverse entry order.
+        for (let i = batch.entries.length - 1; i >= 0; i--) {
+            const entry = batch.entries[i];
+            const inverse = this.applyInverse(entry);
+            if (inverse !== null)
+                inverseEntries.unshift(inverse);
+        }
+        if (inverseEntries.length > 0) {
+            this.redoStack.push({ entries: inverseEntries });
+        }
+        this.notifyStackChange();
+    }
+    redo() {
+        const batch = this.redoStack.pop();
+        if (batch === undefined)
+            return;
+        const inverseEntries = [];
+        for (let i = batch.entries.length - 1; i >= 0; i--) {
+            const entry = batch.entries[i];
+            const inverse = this.applyInverse(entry);
+            if (inverse !== null)
+                inverseEntries.unshift(inverse);
+        }
+        if (inverseEntries.length > 0) {
+            this.undoStack.push({ entries: inverseEntries });
+            if (this.undoStack.length > MAX_STACK_DEPTH) {
+                this.undoStack.shift();
+            }
+        }
+        this.notifyStackChange();
+    }
+    // ─── RGA handle proxy methods ────────────────────────────────────────────────
+    /**
+     * Insert text at visible position. Records undo entry with HLC node IDs.
+     * Uses 250ms debounce — consecutive inserts within the window form one batch.
+     */
+    insert(pos, text, ttlMs) {
+        const handle = this.asRGA();
+        const nodeIds = handle.insert(pos, text, ttlMs);
+        for (let i = 0; i < nodeIds.length; i++) {
+            const entry = {
+                kind: "rga_insert",
+                crdtId: handle.id,
+                nodeId: nodeIds[i],
+                pos: pos + i,
+                content: text[i],
+            };
+            this.recordWithDebounce(entry);
+        }
+        this.clearRedo();
+        return nodeIds;
+    }
+    /**
+     * Delete characters by position. NOT recorded — RGA delete is non-undoable
+     * (tombstones are final; content is irrecoverable).
+     * clearRedo() is intentional: a destructive untracked op should invalidate
+     * any pending redo history, matching ProseMirror/Yjs behaviour.
+     */
+    delete(pos, length, ttlMs) {
+        this.asRGA().delete(pos, length, ttlMs);
+        this.clearRedo();
+    }
+    // ─── Tree handle proxy methods ───────────────────────────────────────────────
+    addNode(parentId, position, value, ttlMs) {
+        const handle = this.asTree();
+        const nodeId = handle.addNode(parentId, position, value, ttlMs);
+        const entry = {
+            kind: "tree_add",
+            crdtId: this.getCrdtId(),
+            nodeId,
+            parentId,
+            position,
+            value,
+        };
+        this.record(entry);
+        this.clearRedo();
+        return nodeId;
+    }
+    moveNode(nodeId, newParentId, newPosition, ttlMs) {
+        const handle = this.asTree();
+        const meta = handle.getNodeMeta(nodeId);
+        handle.moveNode(nodeId, newParentId, newPosition, ttlMs);
+        const entry = {
+            kind: "tree_move",
+            crdtId: this.getCrdtId(),
+            nodeId,
+            oldParentId: meta?.parentId ?? null,
+            oldPosition: meta?.position ?? "a0",
+            newParentId,
+            newPosition,
+        };
+        this.record(entry);
+        this.clearRedo();
+    }
+    updateNode(nodeId, value, ttlMs) {
+        const handle = this.asTree();
+        const meta = handle.getNodeMeta(nodeId);
+        handle.updateNode(nodeId, value, ttlMs);
+        const entry = {
+            kind: "tree_update",
+            crdtId: this.getCrdtId(),
+            nodeId,
+            previousValue: meta?.value ?? "",
+            previousUpdatedAt: meta?.updatedAt ?? nodeId,
+            newValue: value,
+        };
+        this.record(entry);
+        this.clearRedo();
+    }
+    deleteNode(nodeId, ttlMs) {
+        const handle = this.asTree();
+        const meta = handle.getNodeMeta(nodeId);
+        handle.deleteNode(nodeId, ttlMs);
+        const entry = {
+            kind: "tree_delete",
+            crdtId: this.getCrdtId(),
+            nodeId,
+            parentId: meta?.parentId ?? null,
+            position: meta?.position ?? "a0",
+            value: meta?.value ?? "",
+            updatedAt: meta?.updatedAt ?? nodeId,
+        };
+        this.record(entry);
+        this.clearRedo();
+    }
+    // ─── Internal ────────────────────────────────────────────────────────────────
+    applyInverse(entry) {
+        switch (entry.kind) {
+            case "rga_insert": {
+                this.asRGA().deleteById(entry.nodeId);
+                // Inverse of an insert is a delete — not re-recordable as an undo entry.
+                return null;
+            }
+            case "tree_add": {
+                this.asTree().deleteNode(entry.nodeId);
+                // Inverse: a delete entry (for redo — re-add the node).
+                const inverse = {
+                    kind: "tree_delete",
+                    crdtId: entry.crdtId,
+                    nodeId: entry.nodeId,
+                    parentId: entry.parentId,
+                    position: entry.position,
+                    value: entry.value,
+                    updatedAt: entry.nodeId,
+                };
+                return inverse;
+            }
+            case "tree_delete": {
+                // Re-add with original state. Gets a new nodeId (tombstone is permanent).
+                const newNodeId = this.asTree().addNode(entry.parentId, entry.position, entry.value);
+                const inverse = {
+                    kind: "tree_add",
+                    crdtId: entry.crdtId,
+                    nodeId: newNodeId,
+                    parentId: entry.parentId,
+                    position: entry.position,
+                    value: entry.value,
+                };
+                return inverse;
+            }
+            case "tree_move": {
+                this.asTree().moveNode(entry.nodeId, entry.oldParentId, entry.oldPosition);
+                const inverse = {
+                    kind: "tree_move",
+                    crdtId: entry.crdtId,
+                    nodeId: entry.nodeId,
+                    oldParentId: entry.newParentId,
+                    oldPosition: entry.newPosition,
+                    newParentId: entry.oldParentId,
+                    newPosition: entry.oldPosition,
+                };
+                return inverse;
+            }
+            case "tree_update": {
+                this.asTree().updateNode(entry.nodeId, entry.previousValue);
+                const inverse = {
+                    kind: "tree_update",
+                    crdtId: entry.crdtId,
+                    nodeId: entry.nodeId,
+                    previousValue: entry.newValue,
+                    previousUpdatedAt: entry.previousUpdatedAt,
+                    newValue: entry.previousValue,
+                };
+                return inverse;
+            }
+        }
+    }
+    record(entry) {
+        if (this.openBatch !== null) {
+            this.openBatch.push(entry);
+        }
+        else {
+            this.pushUndo({ entries: [entry] });
+        }
+    }
+    /** Record with 250ms debounce — consecutive calls within window share one batch. */
+    recordWithDebounce(entry) {
+        if (this.debounceTimer === null) {
+            // Start a new debounce batch.
+            this.openBatch = [entry];
+        }
+        else {
+            // Extend the current batch.
+            clearTimeout(this.debounceTimer);
+            this.openBatch?.push(entry);
+        }
+        this.debounceTimer = setTimeout(() => {
+            this.debounceTimer = null;
+            this.commitBatch();
+        }, RGA_DEBOUNCE_MS);
+    }
+    pushUndo(batch) {
+        this.undoStack.push(batch);
+        if (this.undoStack.length > MAX_STACK_DEPTH) {
+            this.undoStack.shift();
+        }
+        this.notifyStackChange();
+    }
+    clearRedo() {
+        if (this.redoStack.length > 0) {
+            this.redoStack = [];
+            this.notifyStackChange();
+        }
+    }
+    notifyStackChange() {
+        for (const listener of this.stackListeners)
+            listener();
+    }
+    asRGA() {
+        if (!(this.handle instanceof RGAHandle)) {
+            throw new Error("UndoManager: handle is not an RGAHandle");
+        }
+        return this.handle;
+    }
+    asTree() {
+        if (!(this.handle instanceof TreeHandle)) {
+            throw new Error("UndoManager: handle is not a TreeHandle");
+        }
+        return this.handle;
+    }
+    getCrdtId() {
+        return this.handle.id;
+    }
+}
+//# sourceMappingURL=UndoManager.js.map

package/dist/undo/UndoManager.js.map

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

package/dist/undo/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Undo/redo entry types for CRDT-aware per-client history.
+ *
+ * Each entry stores enough information to produce the inverse operation.
+ * RGA Delete is intentionally not recorded — tombstones are final and
+ * the content is not recoverable (same semantics as ProseMirror/Yjs).
+ */
+export interface RgaInsertEntry {
+    readonly kind: "rga_insert";
+    readonly crdtId: string;
+    /** HLC string "wall_ms:logical:node_id" of the inserted node. Undo = deleteById(nodeId). */
+    readonly nodeId: string;
+    /** Original visible position — used for redo re-insert. */
+    readonly pos: number;
+    /** The character that was inserted. */
+    readonly content: string;
+}
+export interface TreeAddEntry {
+    readonly kind: "tree_add";
+    readonly crdtId: string;
+    /** Node ID returned by addNode(). Undo = deleteNode(nodeId). */
+    readonly nodeId: string;
+    /** Stored for redo: re-add with same parent/position/value. */
+    readonly parentId: string | null;
+    readonly position: string;
+    readonly value: string;
+}
+export interface TreeDeleteEntry {
+    readonly kind: "tree_delete";
+    readonly crdtId: string;
+    readonly nodeId: string;
+    /** State captured before the delete — used to reconstruct addNode for undo. */
+    readonly parentId: string | null;
+    readonly position: string;
+    readonly value: string;
+    readonly updatedAt: string;
+}
+export interface TreeMoveEntry {
+    readonly kind: "tree_move";
+    readonly crdtId: string;
+    readonly nodeId: string;
+    readonly oldParentId: string | null;
+    readonly oldPosition: string;
+    /** Stored for redo. */
+    readonly newParentId: string | null;
+    readonly newPosition: string;
+}
+export interface TreeUpdateEntry {
+    readonly kind: "tree_update";
+    readonly crdtId: string;
+    readonly nodeId: string;
+    /** Captured before the update — used for undo. */
+    readonly previousValue: string;
+    readonly previousUpdatedAt: string;
+    /** Stored for redo. */
+    readonly newValue: string;
+}
+export type UndoEntry = RgaInsertEntry | TreeAddEntry | TreeDeleteEntry | TreeMoveEntry | TreeUpdateEntry;
+/** A batch groups one or more entries into a single logical undo step. */
+export interface UndoBatch {
+    readonly entries: readonly UndoEntry[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/undo/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/undo/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uBAAuB;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,uBAAuB;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,SAAS,GACjB,cAAc,GACd,YAAY,GACZ,eAAe,GACf,aAAa,GACb,eAAe,CAAC;AAEpB,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;CACxC"}

package/dist/undo/types.js

@@ -0,0 +1,9 @@
+/**
+ * Undo/redo entry types for CRDT-aware per-client history.
+ *
+ * Each entry stores enough information to produce the inverse operation.
+ * RGA Delete is intentionally not recorded — tombstones are final and
+ * the content is not recoverable (same semantics as ProseMirror/Yjs).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/undo/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/undo/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/utils/fractional.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Fractional indexing helpers for TreeCRDT sibling ordering.
+ *
+ * Positions are lexicographically ordered strings over the alphabet [a-z0-9].
+ * They can be compared with plain string comparison: "a0" < "b0" < "z9".
+ *
+ * Use these helpers to compute positions when inserting nodes between, before,
+ * or after existing siblings — without having to manage the alphabet manually.
+ *
+ * @example
+ * ```ts
+ * import { fi } from "meridian-sdk";
+ *
+ * const first = fi.start();            // "a0"
+ * const last  = fi.end();              // "z9"
+ * const mid   = fi.between("a0","z9"); // "m4" (midpoint)
+ * const prev  = fi.before("a0");       // "V9" (below a0)
+ * const next  = fi.after("z9");        // "{0" (above z9, still valid)
+ * ```
+ */
+/**
+ * Returns a position string strictly between `a` and `b`.
+ *
+ * Both `a` and `b` must be valid fractional index strings, and `a < b`
+ * lexicographically. Uses BigInt arithmetic to find the exact midpoint,
+ * appending an extra character when the gap is too small.
+ *
+ * @param a - Lower bound (exclusive).
+ * @param b - Upper bound (exclusive).
+ */
+export declare function between(a: string, b: string): string;
+/**
+ * Returns a position string that sorts before `a`.
+ *
+ * @param a - The reference position.
+ */
+export declare function before(a: string): string;
+/**
+ * Returns a position string that sorts after `b`.
+ *
+ * @param b - The reference position.
+ */
+export declare function after(b: string): string;
+/**
+ * Returns the canonical start position — the lowest recommended initial value.
+ */
+export declare function start(): string;
+/**
+ * Returns the canonical end position — the highest recommended initial value.
+ */
+export declare function end(): string;
+/**
+ * Computes an array of `n` evenly-spaced positions between `a` and `b`
+ * (exclusive). Useful for bulk-inserting nodes in order.
+ *
+ * @param a - Lower bound (exclusive).
+ * @param b - Upper bound (exclusive).
+ * @param n - Number of positions to generate.
+ */
+export declare function spread(a: string, b: string, n: number): string[];
+/**
+ * Namespace object for convenient import.
+ *
+ * @example
+ * ```ts
+ * import { fi } from "meridian-sdk";
+ * const pos = fi.between("a0", "z9");
+ * ```
+ */
+export declare const fi: {
+    between: typeof between;
+    before: typeof before;
+    after: typeof after;
+    start: typeof start;
+    end: typeof end;
+    spread: typeof spread;
+};
+//# sourceMappingURL=fractional.d.ts.map

package/dist/utils/fractional.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fractional.d.ts","sourceRoot":"","sources":["../../src/utils/fractional.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA+CH;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAgBpD;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvC;AAED;;GAEG;AACH,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED;;GAEG;AACH,wBAAgB,GAAG,IAAI,MAAM,CAE5B;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAoBhE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,EAAE;;;;;;;CAAiD,CAAC"}