@graphrefly/graphrefly 0.27.0 → 0.28.0

package/dist/extra/reactive.d.ts

@@ -0,0 +1,352 @@
+import { a as Node, V as VersioningLevel } from '../node-Cc1TniY8.js';
+export { L as LogBackend, N as NativeLogBackend, R as ReactiveLogBundle, a as ReactiveLogOptions, r as reactiveLog } from '../reactive-log-YuH9VYN8.js';
+export { M as MapBackend, N as NativeMapBackend, b as NativeMapBackendOptions, R as ReactiveMapBundle, a as ReactiveMapOptions, r as reactiveMap } from '../reactive-map-CdbNoSgP.js';
+
+type IndexRow<K, V = unknown> = {
+    readonly primary: K;
+    readonly secondary: unknown;
+    readonly value: V;
+};
+type ReactiveIndexOptions<K, V = unknown> = {
+    /** Optional registry name for `describe()` / debugging. */
+    name?: string;
+    /**
+     * Storage backend. Defaults to `NativeIndexBackend` (flat array + parallel `Map<K,IndexRow>`).
+     * Users can plug in persistent / B-tree backends via the {@link IndexBackend} interface.
+     */
+    backend?: IndexBackend<K, V>;
+    /**
+     * Optional versioning level for the underlying `ordered` state node. Set at
+     * construction time; cannot be changed later. Pass `0` for V0 identity +
+     * monotonic version counter, or `1` for V1 + content-addressed cid.
+     * (The `byPrimary` derived node inherits through the dep graph.)
+     */
+    versioning?: VersioningLevel;
+    /**
+     * Default row-equality used to short-circuit idempotent upserts. When
+     * provided, every `upsert` / `upsertMany` that finds an existing primary
+     * compares the stored and candidate rows via `equals(existing, next)` —
+     * on `true` the call is a no-op (no version bump, no emission). Per-call
+     * `UpsertOptions.equals` overrides this default. Analogous to
+     * `NodeOptions.equals` on the core `node()` primitive.
+     */
+    equals?: (existing: IndexRow<K, V>, next: IndexRow<K, V>) => boolean;
+};
+type ReactiveIndexBundle<K, V = unknown> = {
+    /** Rows sorted by `(secondary, primary)`. */
+    readonly ordered: Node<readonly IndexRow<K, V>[]>;
+    /** Map from primary key to stored value. */
+    readonly byPrimary: Node<ReadonlyMap<K, V>>;
+    /** O(1) primary-key existence check. */
+    has: (primary: K) => boolean;
+    /** O(1) value lookup by primary key. */
+    get: (primary: K) => V | undefined;
+    /** Number of rows currently in the index (O(1)). */
+    readonly size: number;
+    /**
+     * Upserts a row. When `opts.equals(existing, next)` returns `true` for an
+     * existing primary key, the upsert is a no-op (no version bump, no emission).
+     * Useful for idempotent writes.
+     *
+     * @returns `true` if a new row was inserted (primary key was absent),
+     *   `false` if the primary key was already present (updated in place OR
+     *   skipped idempotently via `opts.equals`). D5(a).
+     */
+    upsert: (primary: K, secondary: unknown, value: V, opts?: UpsertOptions<K, V>) => boolean;
+    /**
+     * Bulk upsert — emits one snapshot for the whole batch. `opts.equals` applied
+     * per-row. No-op if empty or all rows skipped.
+     *
+     * **Iterable consumption:** Consumes `rows` once (single-pass).
+     */
+    upsertMany: (rows: Iterable<{
+        primary: K;
+        secondary: unknown;
+        value: V;
+    }>, opts?: UpsertOptions<K, V>) => void;
+    delete: (primary: K) => void;
+    /**
+     * Bulk delete — emits one snapshot for the whole batch. No-op if nothing was removed.
+     *
+     * **Iterable consumption:** Consumes `primaries` once (single-pass).
+     */
+    deleteMany: (primaries: Iterable<K>) => void;
+    clear: () => void;
+    /**
+     * Releases internal keepalive subscriptions (on `byPrimary`) so the bundle
+     * can be GC'd. Safe to call more than once (subsequent calls are no-ops).
+     * Subsequent mutations after `dispose()` still execute on the backend but
+     * `byPrimary` may stop updating if no external subscriber is attached.
+     * D6(a).
+     */
+    dispose: () => void;
+};
+/**
+ * Storage contract for {@link reactiveIndex}. Implementations own the mutable state and
+ * expose a monotonic `version` counter that increments on every structural change.
+ *
+ * The reactive layer reads `version` to decide when to emit; it does not inspect
+ * internal representation. Users can plug in B-tree / skip-list / persistent backends
+ * without touching the reactive emission logic.
+ *
+ * @remarks Post-1.0 op-log changesets will extend this interface with a
+ * `changesSince(version: number): Iterable<Change>` method. Current consumers
+ * should treat all methods here as stable.
+ *
+ * @category extra
+ */
+/**
+ * Optional per-call options for {@link IndexBackend.upsert} and bulk upsert.
+ *
+ * @category extra
+ */
+type UpsertOptions<K, V> = {
+    /**
+     * Skip the upsert if an existing row is considered equal to the proposed row.
+     * Default: no skip — every upsert advances `version`. Provide for idempotent
+     * keys (e.g., `(a, b) => a.secondary === b.secondary && a.value === b.value`).
+     */
+    equals?: (existing: IndexRow<K, V>, next: IndexRow<K, V>) => boolean;
+};
+interface IndexBackend<K, V = unknown> {
+    /** Monotonic mutation counter; increments on every upsert/delete/clear that changes state. */
+    readonly version: number;
+    /** Number of rows currently stored. */
+    readonly size: number;
+    /** O(1) primary-key existence check. */
+    has(primary: K): boolean;
+    /** Value lookup by primary key. */
+    get(primary: K): V | undefined;
+    /**
+     * Insert or replace a row. Returns `true` if a row was inserted (primary
+     * didn't exist), `false` otherwise (updated OR skipped via `opts.equals`).
+     *
+     * **Atomicity contract:** Either fully succeeds or throws before any state
+     * change; `version` advances only on state change.
+     */
+    upsert(primary: K, secondary: unknown, value: V, opts?: UpsertOptions<K, V>): boolean;
+    /**
+     * Atomic bulk upsert. Returns the number of rows that caused a state change
+     * (inserts + non-skipped updates). Advances `version` at most once.
+     * No-op if iterable is empty or all rows skipped by `opts.equals`.
+     *
+     * **Consumes `rows` once** — pass an array for multi-shot consumers.
+     */
+    upsertMany(rows: Iterable<{
+        primary: K;
+        secondary: unknown;
+        value: V;
+    }>, opts?: UpsertOptions<K, V>): number;
+    /** Remove a row by primary key. Returns `true` if the row existed. Advances `version` only if true. */
+    delete(primary: K): boolean;
+    /**
+     * Atomic bulk delete. Returns count removed. Advances `version` at most once.
+     * No-op if no keys were present. Consumes `primaries` once.
+     */
+    deleteMany(primaries: Iterable<K>): number;
+    /** Remove all rows. Returns the number removed. Advances `version` only if non-zero. */
+    clear(): number;
+    /** Rows in sorted `(secondary, primary)` order — fresh snapshot suitable for emission. */
+    toArray(): readonly IndexRow<K, V>[];
+    /** Primary-key → value map — fresh snapshot. */
+    toPrimaryMap(): ReadonlyMap<K, V>;
+}
+/**
+ * Default flat-array backend. Maintains `buf: IndexRow[]` sorted by `(secondary, primary)`
+ * and a parallel `Map<K, IndexRow>` for O(1) primary-key lookup.
+ *
+ * **Complexity:**
+ * - `has`, `get`: O(1)
+ * - `upsert`: up to 2× O(log n) bisect (locate old + locate new) + up to 2× O(n) splice (remove-old + insert-new) = O(n)
+ * - `upsertMany(k rows)`: O(k log n) bisect + O(k·n) splice worst case; single version bump
+ * - `delete`: O(log n) bisect + O(n) splice = O(n)
+ * - `deleteMany(k keys)`: O(k log n) + O(k·n) splice worst case; single version bump
+ * - `clear`: O(1)
+ * - `toArray`, `toPrimaryMap`: O(n)
+ *
+ * @category extra
+ */
+declare class NativeIndexBackend<K, V = unknown> implements IndexBackend<K, V> {
+    private _version;
+    private readonly _buf;
+    private readonly _byPrimary;
+    get version(): number;
+    get size(): number;
+    has(primary: K): boolean;
+    get(primary: K): V | undefined;
+    upsert(primary: K, secondary: unknown, value: V, opts?: UpsertOptions<K, V>): boolean;
+    upsertMany(rows: Iterable<{
+        primary: K;
+        secondary: unknown;
+        value: V;
+    }>, opts?: UpsertOptions<K, V>): number;
+    delete(primary: K): boolean;
+    deleteMany(primaries: Iterable<K>): number;
+    clear(): number;
+    toArray(): readonly IndexRow<K, V>[];
+    toPrimaryMap(): ReadonlyMap<K, V>;
+}
+/**
+ * Creates a reactive index: unique primary key per row, rows sorted by `(secondary, primary)` for ordered scans.
+ *
+ * @param options - Optional `name` for `describe()` / debugging, and optional `backend` (see {@link IndexBackend}).
+ * @returns Bundle with `ordered` (sorted rows), `byPrimary` (map), O(1) `has` / `get` / `size`,
+ *   imperative `upsert` / `upsertMany` / `delete` / `deleteMany` / `clear`.
+ *
+ * @remarks
+ * **Ordering:** `secondary` and `primary` are compared via a small total order: same primitive `typeof` uses
+ * numeric/string/boolean/bigint comparison; mixed or object keys fall back to `String(a).localeCompare(String(b))`
+ * (not identical to Python's rich comparison for exotic types).
+ *
+ * **Backend:** The default {@link NativeIndexBackend} offers O(1) primary-key lookups and O(n) upserts.
+ * For scale beyond a few thousand rows, supply a user-pluggable persistent/B-tree backend via the
+ * `backend` option — reactive emission semantics are unchanged.
+ *
+ * @example
+ * ```ts
+ * import { reactiveIndex } from "@graphrefly/graphrefly-ts";
+ *
+ * const idx = reactiveIndex<string, string>();
+ * idx.upsert("id1", 10, "row-a");
+ * idx.upsert("id2", 5, "row-b");
+ * ```
+ *
+ * @category extra
+ */
+declare function reactiveIndex<K, V = unknown>(options?: ReactiveIndexOptions<K, V>): ReactiveIndexBundle<K, V>;
+
+type ReactiveListOptions<T> = {
+    name?: string;
+    /**
+     * Storage backend. Defaults to `NativeListBackend` (flat mutable array).
+     * Users can plug in persistent / RRB-tree backends via the {@link ListBackend} interface.
+     */
+    backend?: ListBackend<T>;
+    /**
+     * Optional versioning level for the underlying `items` state node. Set at
+     * construction time; cannot be changed later. Pass `0` for V0 identity +
+     * monotonic version counter, or `1` for V1 + content-addressed cid.
+     */
+    versioning?: VersioningLevel;
+};
+type ReactiveListBundle<T> = {
+    /** Emits `readonly T[]` on each structural change (two-phase). */
+    readonly items: Node<readonly T[]>;
+    /** Current entry count (O(1)). */
+    readonly size: number;
+    /** Positional access (O(1)); supports negative indices (Python-style). Returns `undefined` on out-of-range. */
+    at: (index: number) => T | undefined;
+    append: (value: T) => void;
+    /** Push all values, emit one snapshot. No-op if `values` is empty. */
+    appendMany: (values: readonly T[]) => void;
+    /** Insert a value at `index`. Throws `RangeError` on out-of-range. */
+    insert: (index: number, value: T) => void;
+    /** Insert all values at `index` as one bulk op; emits one snapshot. No-op if `values` is empty. */
+    insertMany: (index: number, values: readonly T[]) => void;
+    /** Remove and return the value at `index` (default: last). Negative indices Python-style. Throws on empty / out-of-range. */
+    pop: (index?: number) => T;
+    clear: () => void;
+    /**
+     * Releases any internal keepalive subscriptions so the bundle can be
+     * GC'd. `reactiveList` currently holds none (no internal derived nodes),
+     * so `dispose()` is a no-op today — exposed for API parity with
+     * `reactiveIndex.dispose` / `reactiveMap.dispose` / `reactiveLog.dispose`.
+     * Idempotent. D6(a).
+     */
+    dispose: () => void;
+};
+/**
+ * Storage contract for {@link reactiveList}. Implementations own the mutable state
+ * and expose a monotonic `version` counter that increments on every structural change.
+ *
+ * The reactive layer reads `version` before and after each backend call; when it
+ * advances, a snapshot is emitted.
+ *
+ * @remarks Post-1.0 op-log changesets will extend this interface with a
+ * `changesSince(version: number): Iterable<Change>` method. Current consumers
+ * should treat all methods here as stable.
+ *
+ * @category extra
+ */
+interface ListBackend<T> {
+    /** Monotonic mutation counter; increments on every structural change. */
+    readonly version: number;
+    /** Number of items currently stored. */
+    readonly size: number;
+    /** Positional access; `undefined` on out-of-range. */
+    at(index: number): T | undefined;
+    /** Append a single value. Advances `version`. */
+    append(value: T): void;
+    /** Append a batch. Advances `version` once. No-op if empty. */
+    appendMany(values: readonly T[]): void;
+    /** Insert at index; throws `RangeError` on out-of-range `0 <= index <= size`. Advances `version`. */
+    insert(index: number, value: T): void;
+    /** Bulk insert at index; throws on out-of-range. Advances `version` once. No-op if `values` empty. */
+    insertMany(index: number, values: readonly T[]): void;
+    /** Remove and return value at index; throws on empty / out-of-range. Advances `version`. */
+    pop(index: number): T;
+    /** Clear all entries. Returns count removed. Advances `version` only if non-zero. */
+    clear(): number;
+    /** Full snapshot as a fresh array. */
+    toArray(): readonly T[];
+}
+/**
+ * Default mutable-array backend.
+ *
+ * **Complexity:**
+ * - `at`, `size`: O(1)
+ * - `append`: O(1) amortized
+ * - `appendMany(values)`, `insertMany(index, values)`: O(n + k) where k = values.length
+ * - `insert`, `pop` (middle): O(n) due to splice
+ * - `pop` (last): O(1)
+ * - `clear`: O(1)
+ * - `toArray`: O(n)
+ *
+ * @category extra
+ */
+declare class NativeListBackend<T> implements ListBackend<T> {
+    private _version;
+    private readonly _buf;
+    constructor(initial?: readonly T[]);
+    get version(): number;
+    get size(): number;
+    at(index: number): T | undefined;
+    append(value: T): void;
+    appendMany(values: readonly T[]): void;
+    insert(index: number, value: T): void;
+    insertMany(index: number, values: readonly T[]): void;
+    pop(index: number): T;
+    clear(): number;
+    toArray(): readonly T[];
+}
+/**
+ * Creates a reactive list with immutable array snapshots.
+ *
+ * @param initial - Optional initial items (copied).
+ * @param options - Optional `name` for `describe()` / debugging, or pluggable `backend`.
+ * @returns Bundle with `items` (state node), `size` / `at`, `append` / `appendMany` / `insert` /
+ *   `insertMany` / `pop` / `clear`.
+ *
+ * @remarks
+ * **No `maxSize`:** insert/pop-anywhere semantics make eviction-under-cap ambiguous.
+ * For bounded append-heavy workloads use `reactiveLog` (head-trim is well-defined for
+ * append-only).
+ *
+ * **Backend:** Default {@link NativeListBackend}. For persistent / RRB-tree semantics
+ * supply a custom {@link ListBackend}. If you provide a `backend`, `initial` is ignored
+ * — seed the backend directly.
+ *
+ * @example
+ * ```ts
+ * import { reactiveList } from "@graphrefly/graphrefly-ts";
+ *
+ * const list = reactiveList<string>(["a"], { name: "queue" });
+ * list.append("b");
+ * list.insertMany(1, ["x", "y"]);
+ * ```
+ *
+ * @category extra
+ */
+declare function reactiveList<T>(initial?: readonly T[], options?: ReactiveListOptions<T>): ReactiveListBundle<T>;
+
+export { type IndexBackend, type IndexRow, type ListBackend, NativeIndexBackend, NativeListBackend, type ReactiveIndexBundle, type ReactiveIndexOptions, type ReactiveListBundle, type ReactiveListOptions, type UpsertOptions, reactiveIndex, reactiveList };

package/dist/extra/reactive.js

@@ -0,0 +1 @@
+import{a as m,b as p}from"../chunk-PIOGHC63.js";import{a as t,b as x}from"../chunk-VTPVOGHH.js";import{a as e,b as f}from"../chunk-OAWLCNJJ.js";import{a as o,b as r}from"../chunk-D7A7DBE4.js";import"../chunk-ZB5EHBIO.js";import"../chunk-CK2E7BTU.js";import"../chunk-QYADASLV.js";export{m as NativeIndexBackend,t as NativeListBackend,o as NativeLogBackend,e as NativeMapBackend,p as reactiveIndex,x as reactiveList,r as reactiveLog,f as reactiveMap};