dacument 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 simple-crdts contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# Dacument
+
+Dacument is a schema-driven CRDT document that signs every operation and
+enforces role-based ACLs at merge time. Local writes emit signed ops; state
+advances only when ops are merged. It gives you a JS object-like API for
+register fields and safe CRDT views for all other field types.
+
+## Install
+
+```sh
+npm install dacument
+# or
+pnpm add dacument
+# or
+yarn add dacument
+```
+
+## Quick start
+
+```ts
+import { generateNonce } from "bytecodec";
+import { Dacument } from "dacument";
+
+const actorId = generateNonce(); // 256-bit base64url id
+Dacument.setActorId(actorId);
+
+const schema = Dacument.schema({
+  title: Dacument.register({ jsType: "string", regex: /^[a-z ]+$/i }),
+  body: Dacument.text(),
+  items: Dacument.array({ jsType: "string" }),
+  tags: Dacument.set({ jsType: "string" }),
+  meta: Dacument.record({ jsType: "string" }),
+});
+
+const { docId, snapshot, roleKeys } = await Dacument.create({ schema });
+
+const doc = await Dacument.load({
+  schema,
+  roleKey: roleKeys.owner.privateKey,
+  snapshot,
+});
+
+doc.title = "Hello world";
+doc.body.insertAt(0, "H");
+doc.tags.add("draft");
+doc.items.push("milk");
+
+doc.addEventListener("change", (event) => channel.send(event.ops));
+channel.onmessage = (ops) => doc.merge(ops);
+
+doc.addEventListener("merge", ({ actor, target, method, data }) => {
+  // Update UI from a single merge stream.
+});
+```
+
+`create()` returns `roleKeys` for owner/manager/editor; store them securely and
+distribute the highest role key per actor as needed.
+
+## Schema and fields
+
+- `register` fields behave like normal properties: `doc.title = "hi"`.
+- Other fields return safe CRDT views: `doc.items.push("x")`.
+- Unknown fields and schema bypasses throw.
+- UI updates should listen to `merge` events.
+
+Supported CRDT field types:
+
+- `register` - last writer wins register.
+- `text` - text RGA.
+- `array` - array RGA.
+- `set` - OR-Set.
+- `map` - OR-Map.
+- `record` - OR-Record.
+
+Map keys must be JSON-compatible values (`string`, `number`, `boolean`, `null`, arrays, or objects). For string-keyed data, prefer `record`.
+
+## Roles and ACL
+
+Roles are evaluated at the op stamp time (HLC).
+
+- Owner: full control (including ownership transfer).
+- Manager: can grant editor/viewer/revoked roles.
+- Editor: can write non-ACL fields.
+- Viewer: read-only.
+- Revoked: reads are masked to initial values; writes are rejected.
+
+Grant roles via `doc.acl` (viewer/revoked have no key):
+
+```ts
+const bobId = generateNonce();
+doc.acl.setRole(bobId, "editor");
+doc.acl.setRole("user-viewer", "viewer");
+await doc.flush();
+```
+
+Before any schema/load/create, call `Dacument.setActorId()` once per process.
+The actor id must be a 256-bit base64url string (e.g. `bytecodec.generateNonce()`).
+Subsequent calls are ignored.
+
+Each actor signs with the role key they were given (owner/manager/editor). Load
+with the highest role key you have; viewers load without a key.
+Role keys are generated once at `create()`; public keys are embedded in the
+snapshot and never rotated.
+
+## Networking and sync
+
+Use `change` events to relay signed ops, and `merge` to apply them:
+
+```ts
+doc.addEventListener("change", (event) => send(event.ops));
+
+// on remote
+await peer.merge(ops);
+```
+
+Local writes do not update state until merged. If you want a single UI update
+path, broadcast ops (even back to yourself) and drive UI from `merge` events.
+
+`merge` events mirror the confirmed operation parameters (e.g. `insertAt`,
+`deleteAt`, `push`, `pop`, `set`, `add`) so UIs can apply minimal updates
+without snapshotting.
+
+To add a new replica, share a snapshot and load it:
+
+```ts
+Dacument.setActorId(bobId);
+const bob = await Dacument.load({
+  schema,
+  roleKey: bobKey.privateKey,
+  snapshot,
+});
+```
+
+Snapshots do not include schema or schema ids; callers must supply the schema on load.
+
+## Events and values
+
+- `doc.addEventListener("change", handler)` emits ops for network sync (writer ops are signed; acks are unsigned).
+- `doc.addEventListener("merge", handler)` emits `{ actor, target, method, data }`.
+- `doc.addEventListener("error", handler)` emits signing/verification errors.
+- `doc.addEventListener("revoked", handler)` fires when the current actor is revoked.
+- `await doc.flush()` waits for pending signatures so all local ops are emitted.
+- `doc.snapshot()` returns a loadable op log (`{ docId, roleKeys, ops }`).
+- Revoked actors cannot snapshot; reads are masked to initial values.
+
+## Garbage collection
+
+Dacument tracks per-actor `ack` ops and compacts tombstones once all non-revoked
+actors (including viewers) have acknowledged a given HLC. Acks are emitted
+automatically after merges that apply new non-ack ops. Acks are unsigned
+(`alg: "none"`); signed acks are rejected.
+If any non-revoked actor is offline and never acks, tombstones are kept.
+
+## Guarantees
+
+- Schema enforcement is strict; unknown fields are rejected.
+- Ops are accepted only if the CRDT patch is valid and the signature verifies
+  (acks are unsigned and signed acks are rejected).
+- Role checks are applied at the op stamp time (HLC).
+- IDs are base64url nonces from `bytecodec` librarys `generateNonce()` (32 random bytes).
+- Private keys are returned by `create()` and never stored by Dacument.
+- Snapshots may include ops that are rejected; invalid ops are ignored on load.
+
+Eventual consistency is achieved when all signed ops are delivered to all
+replicas. Dacument does not provide transport; use `change` events to wire it up.
+
+## Compatibility
+
+- ESM only (`type: module`).
+- Requires WebCrypto (`node >= 18` or modern browsers).
+
+## Scripts
+
+- `npm test` runs the test suite (build included).
+- `npm run bench` runs all CRDT micro-benchmarks (build included).
+- `npm run sim` runs a worker-thread stress simulation.
+- `npm run verify` runs tests, benchmarks, and the simulation in one go.
+
+## Benchmarks
+
+`npm run bench` prints CRDT timings alongside native structure baselines
+(Array/Set/Map/string). Use environment variables like `RUNS`, `SIZE`, `READS`,
+`WRITES`, and `MERGE_SIZE` to tune scale. Compare the CRDT lines to the native
+lines in the output to estimate overhead on your machine. CRDT ops retain
+causal metadata and tombstones, so write-heavy paths will be slower than native
+structures; the baselines show the relative cost.
+
+## Advanced exports
+
+`CRArray`, `CRMap`, `CRRecord`, `CRRegister`, `CRSet`, and `CRText` are exported
+from the package for building custom CRDT workflows.

package/dist/CRArray/class.d.ts

@@ -0,0 +1,34 @@
+import { DAGNode } from "../DAGNode/class.js";
+export declare class CRArray<T> {
+    private readonly nodes;
+    private readonly nodeById;
+    private readonly listeners;
+    constructor(snapshot?: readonly DAGNode<T>[]);
+    get length(): number;
+    onChange(listener: (nodes: readonly DAGNode<T>[]) => void): () => void;
+    snapshot(): DAGNode<T>[];
+    push(...items: T[]): number;
+    unshift(...items: T[]): number;
+    pop(): T | undefined;
+    shift(): T | undefined;
+    at(index: number): T | undefined;
+    setAt(index: number, value: T): this;
+    slice(start?: number, end?: number): T[];
+    includes(value: T): boolean;
+    indexOf(value: T): number;
+    find(predicate: (value: T, index: number, array: T[]) => boolean, thisArg?: unknown): T | undefined;
+    findIndex(predicate: (value: T, index: number, array: T[]) => boolean, thisArg?: unknown): number;
+    forEach(callback: (value: T, index: number, array: T[]) => void, thisArg?: unknown): void;
+    map<U>(callback: (value: T, index: number, array: T[]) => U, thisArg?: unknown): U[];
+    filter(predicate: (value: T, index: number, array: T[]) => boolean, thisArg?: unknown): T[];
+    reduce<U>(reducer: (prev: U, curr: T, index: number, array: T[]) => U, initialValue: U): U;
+    every(predicate: (value: T, index: number, array: T[]) => boolean, thisArg?: unknown): boolean;
+    some(predicate: (value: T, index: number, array: T[]) => boolean, thisArg?: unknown): boolean;
+    [Symbol.iterator](): Iterator<T>;
+    merge(remoteSnapshot: DAGNode<T>[] | DAGNode<T>): DAGNode<T>[];
+    sort(compareFn?: (a: DAGNode<T>, b: DAGNode<T>) => number): this;
+    private alive;
+    private lastAliveId;
+    private afterIdForAliveInsertAt;
+    private emit;
+}

package/dist/CRArray/class.js

@@ -0,0 +1,284 @@
+import { DAGNode } from "../DAGNode/class.js";
+const ROOT = [];
+function afterKey(after) {
+    return after.join(",");
+}
+export class CRArray {
+    nodes = [];
+    nodeById = new Map();
+    listeners = new Set();
+    constructor(snapshot) {
+        if (snapshot) {
+            for (const node of snapshot) {
+                if (this.nodeById.has(node.id))
+                    continue;
+                this.nodes.push(node);
+                this.nodeById.set(node.id, node);
+            }
+        }
+        this.sort();
+        return new Proxy(this, {
+            get: (target, property, receiver) => {
+                if (typeof property === "string") {
+                    if (property === "length")
+                        return target.length;
+                    if (/^(0|[1-9]\d*)$/.test(property))
+                        return target.at(Number(property));
+                }
+                return Reflect.get(target, property, receiver);
+            },
+            set: (target, property, value, receiver) => {
+                if (typeof property === "string" && /^(0|[1-9]\d*)$/.test(property)) {
+                    const index = Number(property);
+                    target.setAt(index, value);
+                    return true;
+                }
+                return Reflect.set(target, property, value, receiver);
+            },
+            has: (target, property) => {
+                if (typeof property === "string" && /^(0|[1-9]\d*)$/.test(property)) {
+                    return Number(property) < target.length;
+                }
+                return Reflect.has(target, property);
+            },
+            ownKeys: (target) => {
+                const keys = Reflect.ownKeys(target);
+                const aliveCount = target.length;
+                for (let index = 0; index < aliveCount; index++)
+                    keys.push(String(index));
+                return keys;
+            },
+            getOwnPropertyDescriptor: (target, property) => {
+                if (typeof property === "string" && /^(0|[1-9]\d*)$/.test(property)) {
+                    if (Number(property) >= target.length)
+                        return undefined;
+                    return {
+                        configurable: true,
+                        enumerable: true,
+                        writable: true,
+                        value: target.at(Number(property)),
+                    };
+                }
+                return Reflect.getOwnPropertyDescriptor(target, property);
+            },
+        });
+    }
+    get length() {
+        let count = 0;
+        for (const node of this.nodes)
+            if (!node.deleted)
+                count++;
+        return count;
+    }
+    // --- public API ---
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    snapshot() {
+        return this.nodes.slice();
+    }
+    push(...items) {
+        let after = this.lastAliveId()
+            ? [this.lastAliveId()]
+            : ROOT;
+        const changed = [];
+        for (const item of items) {
+            const node = new DAGNode({ value: item, after });
+            this.nodes.push(node);
+            this.nodeById.set(node.id, node);
+            changed.push(node);
+            after = [node.id];
+        }
+        this.sort();
+        this.emit(changed);
+        return this.length;
+    }
+    unshift(...items) {
+        let after = ROOT;
+        const changed = [];
+        for (const item of items) {
+            const node = new DAGNode({ value: item, after });
+            this.nodes.push(node);
+            this.nodeById.set(node.id, node);
+            changed.push(node);
+            after = [node.id];
+        }
+        this.sort();
+        this.emit(changed);
+        return this.length;
+    }
+    pop() {
+        for (let index = this.nodes.length - 1; index >= 0; index--) {
+            const node = this.nodes[index];
+            if (!node.deleted) {
+                node.deleted = true;
+                this.emit([node]);
+                return node.value;
+            }
+        }
+        return undefined;
+    }
+    shift() {
+        for (const node of this.nodes) {
+            if (!node.deleted) {
+                node.deleted = true;
+                this.emit([node]);
+                return node.value;
+            }
+        }
+        return undefined;
+    }
+    at(index) {
+        return this.alive().at(index);
+    }
+    setAt(index, value) {
+        if (!Number.isInteger(index))
+            throw new TypeError("CRArray.setAt: index must be an integer");
+        if (index < 0)
+            throw new RangeError("CRArray.setAt: negative index not supported");
+        let aliveIndex = 0;
+        let deletedNode = null;
+        for (const node of this.nodes) {
+            if (node.deleted)
+                continue;
+            if (aliveIndex === index) {
+                node.deleted = true;
+                deletedNode = node;
+                break;
+            }
+            aliveIndex++;
+        }
+        if (index > aliveIndex)
+            throw new RangeError("CRArray.setAt: index out of bounds");
+        const after = this.afterIdForAliveInsertAt(index);
+        const newNode = new DAGNode({ value, after });
+        this.nodes.push(newNode);
+        this.nodeById.set(newNode.id, newNode);
+        this.sort();
+        const changed = deletedNode ? [deletedNode, newNode] : [newNode];
+        this.emit(changed);
+        return this;
+    }
+    slice(start, end) {
+        return this.alive().slice(start, end);
+    }
+    includes(value) {
+        return this.alive().includes(value);
+    }
+    indexOf(value) {
+        return this.alive().indexOf(value);
+    }
+    find(predicate, thisArg) {
+        return this.alive().find(predicate, thisArg);
+    }
+    findIndex(predicate, thisArg) {
+        return this.alive().findIndex(predicate, thisArg);
+    }
+    forEach(callback, thisArg) {
+        this.alive().forEach(callback, thisArg);
+    }
+    map(callback, thisArg) {
+        return this.alive().map(callback, thisArg);
+    }
+    filter(predicate, thisArg) {
+        return this.alive().filter(predicate, thisArg);
+    }
+    reduce(reducer, initialValue) {
+        return this.alive().reduce(reducer, initialValue);
+    }
+    every(predicate, thisArg) {
+        return this.alive().every(predicate, thisArg);
+    }
+    some(predicate, thisArg) {
+        return this.alive().some(predicate, thisArg);
+    }
+    [Symbol.iterator]() {
+        return this.alive()[Symbol.iterator]();
+    }
+    merge(remoteSnapshot) {
+        const snapshot = Array.isArray(remoteSnapshot)
+            ? remoteSnapshot
+            : [remoteSnapshot];
+        const changed = [];
+        for (const remote of snapshot) {
+            const local = this.nodeById.get(remote.id);
+            if (!local) {
+                const clone = structuredClone(remote);
+                this.nodes.push(clone);
+                this.nodeById.set(clone.id, clone);
+                changed.push(clone);
+            }
+            else if (!local.deleted && remote.deleted) {
+                local.deleted = true;
+                changed.push(local);
+            }
+        }
+        if (changed.length) {
+            this.sort();
+            this.emit(changed);
+        }
+        return changed;
+    }
+    sort(compareFn) {
+        if (compareFn) {
+            this.nodes.sort(compareFn);
+            return this;
+        }
+        this.nodes.sort((left, right) => {
+            const leftIsRoot = left.after.length === 0;
+            const rightIsRoot = right.after.length === 0;
+            if (leftIsRoot !== rightIsRoot)
+                return leftIsRoot ? -1 : 1;
+            const leftAfterKey = afterKey(left.after);
+            const rightAfterKey = afterKey(right.after);
+            if (leftAfterKey !== rightAfterKey)
+                return leftAfterKey < rightAfterKey ? -1 : 1;
+            if (left.id === right.id)
+                return 0;
+            if (leftIsRoot)
+                return left.id > right.id ? -1 : 1;
+            return left.id < right.id ? -1 : 1;
+        });
+        return this;
+    }
+    // --- internals ---
+    alive() {
+        const values = [];
+        for (const node of this.nodes)
+            if (!node.deleted)
+                values.push(node.value);
+        return values;
+    }
+    lastAliveId() {
+        for (let index = this.nodes.length - 1; index >= 0; index--) {
+            const node = this.nodes[index];
+            if (!node.deleted)
+                return node.id;
+        }
+        return null;
+    }
+    afterIdForAliveInsertAt(index) {
+        if (index === 0)
+            return ROOT;
+        let aliveIndex = 0;
+        let previousAliveId = null;
+        for (const node of this.nodes) {
+            if (node.deleted)
+                continue;
+            if (aliveIndex === index)
+                break;
+            previousAliveId = node.id;
+            aliveIndex++;
+        }
+        if (previousAliveId)
+            return [previousAliveId];
+        return ROOT;
+    }
+    emit(nodes) {
+        if (nodes.length === 0)
+            return;
+        for (const listener of this.listeners)
+            listener(nodes);
+    }
+}

package/dist/CRMap/class.d.ts

@@ -0,0 +1,55 @@
+type CRMapNode<K, V> = {
+    op: "set";
+    id: string;
+    key: K;
+    keyId: string;
+    value: V;
+} | {
+    op: "del";
+    id: string;
+    keyId: string;
+    targets: string[];
+};
+type CRMapListener<K, V> = (patches: CRMapNode<K, V>[]) => void;
+export declare class CRMap<K, V> implements Map<K, V> {
+    private readonly nodes;
+    private readonly seenNodeIds;
+    private readonly setTagsByKeyId;
+    private readonly tombstones;
+    private readonly aliveKeyIds;
+    private readonly latestKeyByKeyId;
+    private readonly latestValueByKeyId;
+    private readonly listeners;
+    private readonly keyIdByObjectRef;
+    private objectKeyCounter;
+    private readonly symbolKeyByRef;
+    private symbolKeyCounter;
+    private readonly keyFn;
+    constructor(options?: {
+        snapshot?: CRMapNode<K, V>[];
+        key?: (key: K) => string;
+    });
+    onChange(listener: CRMapListener<K, V>): () => void;
+    snapshot(): CRMapNode<K, V>[];
+    merge(input: CRMapNode<K, V>[] | CRMapNode<K, V>): CRMapNode<K, V>[];
+    get size(): number;
+    clear(): void;
+    delete(key: K): boolean;
+    forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: unknown): void;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    set(key: K, value: V): this;
+    entries(): MapIterator<[K, V]>;
+    keys(): MapIterator<K>;
+    values(): MapIterator<V>;
+    [Symbol.iterator](): MapIterator<[K, V]>;
+    readonly [Symbol.toStringTag] = "CRMap";
+    private appendAndApply;
+    private applyNode;
+    private recomputeKeyId;
+    private currentSetTagsForKeyId;
+    private emit;
+    private newId;
+    private keyIdOf;
+}
+export {};