dacument 1.0.0

package/dist/CRMap/class.js

@@ -0,0 +1,222 @@
+import { v7 as uuidv7 } from "uuid";
+export class CRMap {
+    nodes = [];
+    seenNodeIds = new Set();
+    setTagsByKeyId = new Map();
+    tombstones = new Set();
+    aliveKeyIds = new Set();
+    latestKeyByKeyId = new Map();
+    latestValueByKeyId = new Map();
+    listeners = new Set();
+    keyIdByObjectRef = new WeakMap();
+    objectKeyCounter = 0;
+    symbolKeyByRef = new Map();
+    symbolKeyCounter = 0;
+    keyFn;
+    constructor(options) {
+        this.keyFn = options?.key;
+        if (options?.snapshot?.length)
+            this.merge(options.snapshot);
+    }
+    // --- public API ---
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    snapshot() {
+        return this.nodes.slice();
+    }
+    merge(input) {
+        const nodes = Array.isArray(input) ? input : [input];
+        const accepted = [];
+        for (const node of nodes) {
+            if (this.seenNodeIds.has(node.id))
+                continue;
+            this.seenNodeIds.add(node.id);
+            this.nodes.push(node);
+            this.applyNode(node);
+            accepted.push(node);
+        }
+        if (accepted.length)
+            this.emit(accepted);
+        return accepted;
+    }
+    // --- Map<K, V> API ---
+    get size() {
+        return this.aliveKeyIds.size;
+    }
+    clear() {
+        const patches = [];
+        for (const keyId of this.aliveKeyIds) {
+            const targets = this.currentSetTagsForKeyId(keyId);
+            if (targets.length === 0)
+                continue;
+            patches.push({ op: "del", id: this.newId(), keyId, targets });
+        }
+        if (patches.length === 0)
+            return;
+        for (const patch of patches) {
+            this.seenNodeIds.add(patch.id);
+            this.nodes.push(patch);
+            this.applyNode(patch);
+        }
+        this.emit(patches);
+    }
+    delete(key) {
+        const keyId = this.keyIdOf(key);
+        const targets = this.currentSetTagsForKeyId(keyId);
+        if (targets.length === 0)
+            return false;
+        const node = {
+            op: "del",
+            id: this.newId(),
+            keyId,
+            targets,
+        };
+        this.appendAndApply(node);
+        return true;
+    }
+    forEach(callbackfn, thisArg) {
+        for (const [key, value] of this.entries())
+            callbackfn.call(thisArg, value, key, this);
+    }
+    get(key) {
+        const keyId = this.keyIdOf(key);
+        if (!this.aliveKeyIds.has(keyId))
+            return undefined;
+        return this.latestValueByKeyId.get(keyId);
+    }
+    has(key) {
+        const keyId = this.keyIdOf(key);
+        return this.aliveKeyIds.has(keyId);
+    }
+    set(key, value) {
+        const keyId = this.keyIdOf(key);
+        const node = {
+            op: "set",
+            id: this.newId(),
+            key,
+            keyId,
+            value,
+        };
+        this.appendAndApply(node);
+        return this;
+    }
+    *entries() {
+        for (const keyId of this.aliveKeyIds) {
+            if (!this.latestKeyByKeyId.has(keyId) ||
+                !this.latestValueByKeyId.has(keyId))
+                continue;
+            const key = this.latestKeyByKeyId.get(keyId);
+            const value = this.latestValueByKeyId.get(keyId);
+            yield [key, value];
+        }
+    }
+    *keys() {
+        for (const [key] of this.entries())
+            yield key;
+    }
+    *values() {
+        for (const [, value] of this.entries())
+            yield value;
+    }
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+    [Symbol.toStringTag] = "CRMap";
+    // --- internals ---
+    appendAndApply(node) {
+        this.seenNodeIds.add(node.id);
+        this.nodes.push(node);
+        this.applyNode(node);
+        this.emit([node]);
+    }
+    applyNode(node) {
+        if (node.op === "set") {
+            let tags = this.setTagsByKeyId.get(node.keyId);
+            if (!tags) {
+                tags = new Map();
+                this.setTagsByKeyId.set(node.keyId, tags);
+            }
+            tags.set(node.id, { key: node.key, value: node.value });
+            this.recomputeKeyId(node.keyId);
+            return;
+        }
+        for (const targetTag of node.targets)
+            this.tombstones.add(targetTag);
+        this.recomputeKeyId(node.keyId);
+    }
+    recomputeKeyId(keyId) {
+        const tags = this.setTagsByKeyId.get(keyId);
+        if (!tags || tags.size === 0) {
+            this.aliveKeyIds.delete(keyId);
+            this.latestKeyByKeyId.delete(keyId);
+            this.latestValueByKeyId.delete(keyId);
+            return;
+        }
+        let winnerTag = null;
+        let winner = null;
+        for (const [tag, entry] of tags) {
+            if (this.tombstones.has(tag))
+                continue;
+            if (!winnerTag || tag > winnerTag) {
+                winnerTag = tag;
+                winner = entry;
+            }
+        }
+        if (winnerTag && winner) {
+            this.aliveKeyIds.add(keyId);
+            this.latestKeyByKeyId.set(keyId, winner.key);
+            this.latestValueByKeyId.set(keyId, winner.value);
+            return;
+        }
+        this.aliveKeyIds.delete(keyId);
+        this.latestKeyByKeyId.delete(keyId);
+        this.latestValueByKeyId.delete(keyId);
+    }
+    currentSetTagsForKeyId(keyId) {
+        const tags = this.setTagsByKeyId.get(keyId);
+        if (!tags)
+            return [];
+        return [...tags.keys()];
+    }
+    emit(patches) {
+        for (const listener of this.listeners)
+            listener(patches);
+    }
+    newId() {
+        return uuidv7();
+    }
+    keyIdOf(key) {
+        if (this.keyFn)
+            return this.keyFn(key);
+        const keyType = typeof key;
+        if (keyType === "string")
+            return `str:${key}`;
+        if (keyType === "number")
+            return `num:${Object.is(key, -0) ? "-0" : String(key)}`;
+        if (keyType === "bigint")
+            return `big:${String(key)}`;
+        if (keyType === "boolean")
+            return `bool:${key ? "1" : "0"}`;
+        if (keyType === "undefined")
+            return "undef";
+        if (key === null)
+            return "null";
+        if (keyType === "symbol") {
+            const existing = this.symbolKeyByRef.get(key);
+            if (existing)
+                return existing;
+            const created = `sym:${(++this.symbolKeyCounter).toString(36)}`;
+            this.symbolKeyByRef.set(key, created);
+            return created;
+        }
+        const objectRef = key;
+        const existing = this.keyIdByObjectRef.get(objectRef);
+        if (existing)
+            return existing;
+        const created = `obj:${(++this.objectKeyCounter).toString(36)}`;
+        this.keyIdByObjectRef.set(objectRef, created);
+        return created;
+    }
+}

package/dist/CRRecord/class.d.ts

@@ -0,0 +1,34 @@
+type CRRecordNode<V> = {
+    op: "set";
+    id: string;
+    prop: string;
+    value: V;
+} | {
+    op: "del";
+    id: string;
+    prop: string;
+    targets: string[];
+};
+type CRRecordListener<V> = (patches: CRRecordNode<V>[]) => void;
+export declare class CRRecord<V = unknown> {
+    private readonly nodes;
+    private readonly seenNodeIds;
+    private readonly setTagsByProp;
+    private readonly tombstones;
+    private readonly aliveProps;
+    private readonly latestValueByProp;
+    private readonly listeners;
+    constructor(snapshot?: CRRecordNode<V>[]);
+    onChange(listener: CRRecordListener<V>): () => void;
+    snapshot(): CRRecordNode<V>[];
+    merge(input: CRRecordNode<V>[] | CRRecordNode<V>): CRRecordNode<V>[];
+    private get;
+    private set;
+    private delete;
+    private appendAndApply;
+    private applyNode;
+    private emit;
+    private recompute;
+    private newId;
+}
+export {};

package/dist/CRRecord/class.js

@@ -0,0 +1,154 @@
+import { v7 as uuidv7 } from "uuid";
+export class CRRecord {
+    nodes = [];
+    seenNodeIds = new Set();
+    setTagsByProp = new Map();
+    tombstones = new Set();
+    aliveProps = new Set();
+    latestValueByProp = new Map();
+    listeners = new Set();
+    constructor(snapshot) {
+        if (snapshot?.length)
+            this.merge(snapshot);
+        return new Proxy(this, {
+            get: (target, prop, receiver) => {
+                if (typeof prop !== "string")
+                    return Reflect.get(target, prop, receiver);
+                if (prop in target)
+                    return Reflect.get(target, prop, receiver);
+                return target.get(prop);
+            },
+            set: (target, prop, value, receiver) => {
+                if (typeof prop !== "string")
+                    return Reflect.set(target, prop, value, receiver);
+                if (prop in target)
+                    return Reflect.set(target, prop, value, receiver);
+                target.set(prop, value);
+                return true;
+            },
+            deleteProperty: (target, prop) => {
+                if (typeof prop !== "string")
+                    return Reflect.deleteProperty(target, prop);
+                if (prop in target)
+                    return Reflect.deleteProperty(target, prop);
+                return target.delete(prop);
+            },
+            has: (target, prop) => {
+                if (typeof prop !== "string")
+                    return Reflect.has(target, prop);
+                if (prop in target)
+                    return true;
+                return target.aliveProps.has(prop);
+            },
+            ownKeys: (target) => [...target.aliveProps],
+            getOwnPropertyDescriptor: (target, prop) => {
+                if (typeof prop !== "string")
+                    return Reflect.getOwnPropertyDescriptor(target, prop);
+                if (prop in target)
+                    return Reflect.getOwnPropertyDescriptor(target, prop);
+                if (!target.aliveProps.has(prop))
+                    return undefined;
+                return { enumerable: true, configurable: true };
+            },
+        });
+    }
+    // --- public API ---
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    snapshot() {
+        return this.nodes.slice();
+    }
+    merge(input) {
+        const nodes = Array.isArray(input) ? input : [input];
+        const accepted = [];
+        for (const node of nodes) {
+            if (this.seenNodeIds.has(node.id))
+                continue;
+            this.seenNodeIds.add(node.id);
+            this.nodes.push(node);
+            this.applyNode(node);
+            accepted.push(node);
+        }
+        if (accepted.length)
+            this.emit(accepted);
+        return accepted;
+    }
+    // --- internals ---
+    get(prop) {
+        if (!this.aliveProps.has(prop))
+            return undefined;
+        return this.latestValueByProp.get(prop);
+    }
+    set(prop, value) {
+        const node = { op: "set", id: this.newId(), prop, value };
+        this.appendAndApply(node);
+    }
+    delete(prop) {
+        const tags = this.setTagsByProp.get(prop);
+        if (!tags?.size)
+            return false;
+        const node = {
+            op: "del",
+            id: this.newId(),
+            prop,
+            targets: [...tags.keys()],
+        };
+        this.appendAndApply(node);
+        return true;
+    }
+    appendAndApply(node) {
+        this.seenNodeIds.add(node.id);
+        this.nodes.push(node);
+        this.applyNode(node);
+        this.emit([node]);
+    }
+    applyNode(node) {
+        if (node.op === "set") {
+            let tags = this.setTagsByProp.get(node.prop);
+            if (!tags) {
+                tags = new Map();
+                this.setTagsByProp.set(node.prop, tags);
+            }
+            tags.set(node.id, node.value);
+        }
+        else {
+            for (const t of node.targets)
+                this.tombstones.add(t);
+        }
+        this.recompute(node.prop);
+    }
+    emit(patches) {
+        for (const l of this.listeners)
+            l(patches);
+    }
+    recompute(prop) {
+        const tags = this.setTagsByProp.get(prop);
+        if (!tags || tags.size === 0) {
+            this.aliveProps.delete(prop);
+            this.latestValueByProp.delete(prop);
+            return;
+        }
+        let winnerTag = null;
+        let winnerValue;
+        for (const [tag, value] of tags) {
+            if (this.tombstones.has(tag))
+                continue;
+            if (!winnerTag || tag > winnerTag) {
+                winnerTag = tag;
+                winnerValue = value;
+            }
+        }
+        if (winnerTag) {
+            this.aliveProps.add(prop);
+            this.latestValueByProp.set(prop, winnerValue);
+            return;
+        }
+        this.aliveProps.delete(prop);
+        this.latestValueByProp.delete(prop);
+    }
+    newId() {
+        return uuidv7();
+    }
+}

package/dist/CRRegister/class.d.ts

@@ -0,0 +1,30 @@
+type LWWValue = string | number | boolean;
+type HLCStamp = {
+    /** Unix ms */
+    readonly wallTimeMs: number;
+    /** logical counter for same/older wallTimeMs */
+    readonly logical: number;
+    /** stable actor/node id for deterministic tie-break */
+    readonly clockId: string;
+};
+type CRRegisterNode<TValue extends LWWValue> = {
+    readonly value: TValue;
+    readonly stamp: HLCStamp;
+};
+type CRRegisterListener<TValue extends LWWValue> = (patches: CRRegisterNode<TValue>[]) => void;
+export declare class CRRegister<TValue extends LWWValue> {
+    private last;
+    private winner;
+    private readonly listeners;
+    constructor();
+    onChange(listener: CRRegisterListener<TValue>): () => void;
+    snapshot(): CRRegisterNode<TValue>[];
+    merge(input: CRRegisterNode<TValue>[] | CRRegisterNode<TValue>): CRRegisterNode<TValue>[];
+    set(value: TValue, incomingStamp?: HLCStamp): void;
+    get(): TValue | null;
+    private nextLocalStamp;
+    private apply;
+    private advanceClock;
+    private emit;
+}
+export {};

package/dist/CRRegister/class.js

@@ -0,0 +1,82 @@
+import { v7 as uuidv7 } from "uuid";
+function compareHLC(left, right) {
+    if (left.wallTimeMs !== right.wallTimeMs)
+        return left.wallTimeMs - right.wallTimeMs;
+    if (left.logical !== right.logical)
+        return left.logical - right.logical;
+    // final deterministic tie-break
+    if (left.clockId === right.clockId)
+        return 0;
+    return left.clockId < right.clockId ? -1 : 1;
+}
+export class CRRegister {
+    last;
+    winner = null;
+    listeners = new Set();
+    constructor() {
+        this.last = { wallTimeMs: 0, logical: 0, clockId: uuidv7() };
+    }
+    // --- public API ---
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    snapshot() {
+        return this.winner ? [this.winner] : [];
+    }
+    merge(input) {
+        const nodes = Array.isArray(input) ? input : [input];
+        const accepted = [];
+        for (const node of nodes) {
+            if (this.apply(node))
+                accepted.push(node);
+        }
+        if (accepted.length)
+            this.emit(accepted);
+        return accepted;
+    }
+    set(value, incomingStamp) {
+        const stamp = incomingStamp ?? this.nextLocalStamp(Date.now());
+        const candidate = { value, stamp };
+        if (this.apply(candidate))
+            this.emit([candidate]);
+    }
+    get() {
+        return this.winner ? this.winner.value : null;
+    }
+    // --- internals ---
+    nextLocalStamp(nowMs) {
+        const wallTimeMs = Math.max(nowMs, this.last.wallTimeMs);
+        const logical = wallTimeMs === this.last.wallTimeMs ? this.last.logical + 1 : 0;
+        const next = { wallTimeMs, logical, clockId: this.last.clockId };
+        this.last = next;
+        return next;
+    }
+    apply(node) {
+        this.advanceClock(node.stamp);
+        const current = this.winner;
+        if (!current || compareHLC(node.stamp, current.stamp) > 0) {
+            this.winner = node;
+            return true;
+        }
+        return false;
+    }
+    advanceClock(stamp) {
+        // Keep local HLC monotonic even when receiving remote stamps.
+        const mergedWall = Math.max(this.last.wallTimeMs, stamp.wallTimeMs, Date.now());
+        const mergedLogical = mergedWall === this.last.wallTimeMs
+            ? Math.max(this.last.logical, stamp.logical) + 1
+            : mergedWall === stamp.wallTimeMs
+                ? stamp.logical
+                : 0;
+        this.last = {
+            wallTimeMs: mergedWall,
+            logical: mergedLogical,
+            clockId: this.last.clockId,
+        };
+    }
+    emit(patches) {
+        for (const listener of this.listeners)
+            listener(patches);
+    }
+}

package/dist/CRSet/class.d.ts

@@ -0,0 +1,52 @@
+type CRSetNode<T> = {
+    op: "add";
+    id: string;
+    value: T;
+    key: string;
+} | {
+    op: "rem";
+    id: string;
+    key: string;
+    targets: string[];
+};
+type CRSetListener<T> = (patches: CRSetNode<T>[]) => void;
+export declare class CRSet<T> implements Set<T> {
+    private readonly nodes;
+    private readonly seenNodeIds;
+    private readonly addTagsByKey;
+    private readonly tombstones;
+    private readonly aliveKeys;
+    private readonly latestValueByKey;
+    private readonly listeners;
+    private readonly objectKeyByRef;
+    private objectKeyCounter;
+    private readonly symbolKeyByRef;
+    private symbolKeyCounter;
+    private readonly keyFn;
+    constructor(options?: {
+        snapshot?: CRSetNode<T>[];
+        key?: (value: T) => string;
+    });
+    onChange(listener: CRSetListener<T>): () => void;
+    snapshot(): CRSetNode<T>[];
+    merge(input: CRSetNode<T>[] | CRSetNode<T>): CRSetNode<T>[];
+    get size(): number;
+    add(value: T): this;
+    delete(value: T): boolean;
+    clear(): void;
+    has(value: T): boolean;
+    forEach(callbackfn: (value: T, value2: T, set: Set<T>) => void, thisArg?: unknown): void;
+    values(): SetIterator<T>;
+    keys(): SetIterator<T>;
+    entries(): SetIterator<[T, T]>;
+    [Symbol.iterator](): SetIterator<T>;
+    readonly [Symbol.toStringTag] = "CRSet";
+    private appendAndApply;
+    private applyNode;
+    private recomputeAliveForKey;
+    private currentAddTagsForKey;
+    private emit;
+    private newId;
+    private keyOf;
+}
+export {};