@graphrefly/graphrefly 0.44.0 → 0.46.0

package/dist/reactive-log-DIGdYqQ6.d.cts

@@ -1,223 +0,0 @@
-import { V as VersioningLevel, b as NodeGuard, N as Node } from './node-kK3CvTrR.cjs';
-import { AppendLogStorageTier } from './extra/storage-tiers.cjs';
-
-type ReactiveLogOptions<T> = {
-    name?: string;
-    maxSize?: number;
-    /**
-     * Optional versioning level for the underlying `entries` 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;
-    /**
-     * Optional guard policy applied to the `entries` node. Use to deny
-     * external `write` while permitting `observe` / `signal` — eliminates the
-     * passthrough-derived pattern in CQRS event streams (Audit 1 #7).
-     */
-    guard?: NodeGuard;
-    /**
-     * Storage backend. Defaults to `NativeLogBackend` (ring buffer if `maxSize` is set,
-     * flat array otherwise). Users can plug in persistent / RRB-tree backends via
-     * the {@link LogBackend} interface.
-     */
-    backend?: LogBackend<T>;
-};
-/**
- * Discriminated view spec for {@link ReactiveLogBundle.view}. New `kind`s
- * (e.g. `"filter"`, `"windowByTime"`) layer in without new methods.
- */
-type ViewSpec<_T = unknown> = {
-    kind: "tail";
-    n: number;
-} | {
-    kind: "slice";
-    start: number;
-    stop?: number;
-} | {
-    kind: "fromCursor";
-    cursor: Node<number>;
-};
-type ReactiveLogBundle<T> = {
-    /** Emits `readonly T[]` on each append/clear/trim (two-phase). */
-    readonly entries: Node<readonly T[]>;
-    /** Current entry count (O(1)). */
-    readonly size: number;
-    /** Positional access (O(1)); returns `undefined` on out-of-range. Supports negative indices. */
-    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;
-    clear: () => void;
-    /** Remove the first `n` entries (clamped to `size`). */
-    trimHead: (n: number) => void;
-    /**
-     * Activate the {@link ReactiveLogBundle.lastValue} / {@link ReactiveLogBundle.hasLatest}
-     * companion nodes (lazy — installed on first call, reused thereafter).
-     * Returns `entries` so chaining reads naturally.
-     *
-     * **Companion-node access is on the bundle** (not `entries.meta`) because
-     * `Node.meta` is frozen at construction; bundle-level lazy properties
-     * give the same semantics with simpler ergonomics.
-     */
-    withLatest: () => Node<readonly T[]>;
-    /**
-     * Most-recently-appended value, or `undefined` if no entries exist (spec
-     * §5.12 SENTINEL alignment). Accessing this property activates the
-     * companion lazily — same as calling {@link ReactiveLogBundle.withLatest}.
-     *
-     * **Empty-log path emits `RESOLVED`, not `DATA(undefined)`.** When the log
-     * holds no entries, `lastValue` settles via `[[RESOLVED]]` so the §1.2
-     * "DATA(undefined) is not a valid emission" invariant stands.
-     *
-     * **Caveat when `T` itself includes `undefined`:** if a literal `undefined`
-     * value is appended, `lastValue` emits `[[DATA, undefined]]` for that
-     * append wave — the per-value semantics are intentionally preserved so
-     * subscribers can observe the transition. Use
-     * {@link ReactiveLogBundle.hasLatest} to disambiguate "no entries yet"
-     * from "an undefined value was appended"; `lastValue.cache` alone cannot
-     * tell them apart.
-     */
-    readonly lastValue: Node<T | undefined>;
-    /** Reactive `true` once at least one entry has been appended. */
-    readonly hasLatest: Node<boolean>;
-    /**
-     * Reactive view per discriminated `ViewSpec`. Memoized per-spec — repeat
-     * calls with identical spec return the same node.
-     */
-    view: (spec: ViewSpec<T>) => Node<readonly T[]>;
-    /**
-     * Subscribe to `upstream` and append every DATA into this log. Returns a
-     * disposer. ERROR / COMPLETE on `upstream` propagate through the disposer
-     * (caller is responsible for terminal handling on the log).
-     */
-    attach: (upstream: Node<T>) => () => void;
-    /**
-     * Wire one or more append-log storage tiers. Each tier receives entries on
-     * every append wave; tier-internal flush/rollback honors the wave-as-
-     * transaction model (Audit 4). Returns a disposer.
-     */
-    attachStorage: (tiers: readonly AppendLogStorageTier<T>[]) => () => void;
-    /** Releases all cached views (tail + slice + fromCursor). */
-    disposeAllViews: () => void;
-    /** Releases all internal keepalives. Idempotent. */
-    dispose: () => void;
-};
-/**
- * Storage contract for {@link reactiveLog}. Implementations own the mutable state and
- * expose a monotonic `version` counter that increments on every structural change.
- *
- * **Audit 1:** `snapshot()` returns an immutable readonly view (codec encodes
- * at the storage tier boundary). `restore(values)` replaces backend state on
- * cold-tier startup load — fires one DATA emission for the restored shape.
- *
- * @category extra
- */
-interface LogBackend<T> {
-    readonly version: number;
-    readonly size: number;
-    at(index: number): T | undefined;
-    append(value: T): void;
-    appendMany(values: readonly T[]): void;
-    clear(): number;
-    trimHead(n: number): number;
-    slice(start: number, stop?: number): readonly T[];
-    tail(n: number): readonly T[];
-    toArray(): readonly T[];
-    /** Immutable snapshot for codec serialization. Equivalent to `toArray()`. */
-    snapshot(): readonly T[];
-    /** Replace backend state with `values` (used by cold-tier restore). */
-    restore(values: readonly T[]): void;
-}
-/**
- * Default append-only log backend.
- *
- * - When `maxSize` is set: uses a **ring buffer** with `_head` index and circular
- *   modular arithmetic. Append and trim become O(1); snapshot is O(size) unrolling.
- * - When `maxSize` is unset: uses a flat array with standard push/splice.
- *
- * @category extra
- */
-declare class NativeLogBackend<T> implements LogBackend<T> {
-    private _version;
-    private readonly _maxSize?;
-    private readonly _buf;
-    private _head;
-    private _size;
-    constructor(initial?: readonly T[], maxSize?: number);
-    get version(): number;
-    get size(): number;
-    at(index: number): T | undefined;
-    append(value: T): void;
-    appendMany(values: readonly T[]): void;
-    clear(): number;
-    trimHead(n: number): number;
-    slice(start: number, stop?: number): readonly T[];
-    tail(n: number): readonly T[];
-    toArray(): readonly T[];
-    snapshot(): readonly T[];
-    restore(values: readonly T[]): void;
-    private _rawAppend;
-}
-/**
- * Creates an append-only reactive log that emits immutable `readonly T[]` snapshots.
- *
- * Each structural mutation (`append`, `appendMany`, `clear`, `trimHead`) triggers
- * a two-phase `[DIRTY, DATA]` emission on the `entries` node so downstream
- * derived nodes update reactively. Views (`tail`, `slice`, `fromCursor`) are
- * memoized derived nodes — subscribe once and they stay live.
- *
- * @param initial - Optional initial entries loaded into the log at construction.
- * @param options - Optional name, max size (ring buffer), versioning level, guard policy, and custom backend.
- * @returns `ReactiveLogBundle<T>` with `entries`, `append`, `appendMany`, `clear`, `trimHead`, `view`, `attach`, `attachStorage`, and disposal methods.
- *
- * @example
- * ```ts
- * import { reactiveLog } from "@graphrefly/graphrefly/extra";
- *
- * const log = reactiveLog<string>([], { name: "messages" });
- * log.entries.subscribe((msgs) => {
- *   for (const m of msgs) {
- *     if (m[0] === 1) console.log("entries:", m[1]);
- *   }
- * });
- * log.append("hello");
- * log.append("world");
- * ```
- *
- * @remarks
- * **Ring buffer:** Pass `maxSize` to cap the log length; older entries are evicted on overflow.
- * **Storage:** Call `attachStorage(tiers)` to wire one or more `AppendLogStorageTier` instances for persistence.
- *
- * @category extra
- */
-declare function reactiveLog<T>(initial?: readonly T[], options?: ReactiveLogOptions<T>): ReactiveLogBundle<T>;
-/**
- * Bundle returned by {@link mergeReactiveLogs}. `node` is the merged output;
- * `dispose()` releases the internal subscriptions to all input logs and the
- * keepalive on `node`. After dispose the merge stops responding to inputs
- * but `node`'s last cached value remains queryable.
- *
- * @category extra
- */
-interface MergedReactiveLog<T> {
-    readonly node: Node<readonly T[]>;
-    dispose(): void;
-}
-/**
- * Fan-in helper that merges N reactive logs into a single time-ordered output
- * by concatenation. Returns `{ node, dispose }`. Producer-pattern: subscribes
- * to each input internally; COMPLETE on an input drops it from the active
- * set; ERROR propagates per spec §2.2. Memoized by reference identity on the
- * `logs` array — repeat calls with the same reference return the same bundle.
- *
- * Internal subscriptions are invisible in `describe()` (sanctioned per §24);
- * `explain()` across the merge surfaces only the merged stream. Caller must
- * `dispose()` when done to release subscriptions to input logs (no auto-GC
- * because of the memoization map).
- *
- * @category extra
- */
-declare function mergeReactiveLogs<T>(logs: readonly Node<readonly T[]>[]): MergedReactiveLog<T>;
-
-export { type LogBackend as L, type MergedReactiveLog as M, NativeLogBackend as N, type ReactiveLogOptions as R, type ViewSpec as V, type ReactiveLogBundle as a, mergeReactiveLogs as m, reactiveLog as r };

package/dist/reactive-map-CEFGp8TK.d.cts

@@ -1,296 +0,0 @@
-import { N as Node, V as VersioningLevel, a as NodeOptions } from './node-kK3CvTrR.cjs';
-
-type ReactiveMapOptions<K, V> = {
-    /** Optional registry name for `describe()` / debugging. */
-    name?: string;
-    /**
-     * LRU cap. When set, evicts least-recently-used keys after inserts that exceed this size.
-     * Forwarded to the default `NativeMapBackend`. Ignored if a custom `backend` is provided.
-     *
-     * **Mutually exclusive with `retention`** — the LRU cap is "youngest-access wins,"
-     * score-based retention is "highest-score wins." Configuring both would make
-     * eviction nondeterministic; construction throws if both are set.
-     */
-    maxSize?: number;
-    /**
-     * Default TTL in seconds. Used when `set`/`setMany` omits per-call `ttl`.
-     * Forwarded to the default `NativeMapBackend`. Ignored if a custom `backend` is provided.
-     */
-    defaultTtl?: number;
-    /**
-     * Storage backend. Defaults to `NativeMapBackend`. Users can plug in persistent
-     * (HAMT / Immutable.js) or shared-state backends via the {@link MapBackend} interface.
-     */
-    backend?: MapBackend<K, V>;
-    /**
-     * Optional versioning level for the underlying `entries` 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;
-    /**
-     * Score-based retention policy. After every mutation, each live entry is
-     * scored; entries below `archiveThreshold` and / or over `maxSize` (lowest-
-     * scored first) are archived via `onArchive` before being removed.
-     *
-     * Retention replaces the ad-hoc "tierClassifier effect writing back to its
-     * own store dep" pattern — the feedback cycle is gone because archival is
-     * part of the atomic mutation, not a second reactive wave.
-     *
-     * Mutually exclusive with top-level `maxSize` (LRU). Pass one or the other.
-     */
-    retention?: ReactiveMapRetention<K, V>;
-} & Omit<NodeOptions, "initial" | "describeKind" | "equals" | "versioning">;
-/**
- * Score-based retention policy for {@link reactiveMap}. Evaluated synchronously
- * on every successful mutation (`set` / `setMany` / `delete` / `clear` /
- * `pruneExpired`). Entries are archived in ascending score order until the
- * map satisfies both constraints:
- *
- * 1. Every remaining entry has `score >= archiveThreshold` (if set).
- * 2. Total entry count `<= maxSize` (if set).
- *
- * At least one of `archiveThreshold` / `maxSize` must be set; otherwise there's
- * no eviction trigger.
- *
- * **Archival order.** When multiple entries are candidates for archival in the
- * same mutation, they are archived in ascending score order (lowest first). On
- * score ties, iteration order (insertion order in the default backend) is the
- * tiebreak.
- *
- * **No recursion.** Archival deletes happen on the backend directly — they do
- * NOT re-enter the retention evaluator. The one-pass scan collects archival
- * candidates against the post-mutation snapshot before removing them.
- *
- * @category extra
- */
-type ReactiveMapRetention<K, V> = {
-    /** Score entry — higher is kept. Should be a pure function of `(key, value)`. */
-    score: (key: K, value: V) => number;
-    /** Below-threshold entries are archived. Omit for pure `maxSize`-based retention. */
-    archiveThreshold?: number;
-    /**
-     * Cap on live entry count. Over this, the lowest-scored entries are
-     * archived until the size fits. Omit for pure threshold-based retention.
-     */
-    maxSize?: number;
-    /**
-     * Synchronous callback fired **before** archival deletion. Receives the
-     * key, value, and computed score. Callers typically persist the entry to
-     * a cold tier here (`await permanent.set(key, value)` — async is fine but
-     * the archival deletion happens synchronously after this callback
-     * returns).
-     */
-    onArchive?: (key: K, value: V, score: number) => void;
-};
-type ReactiveMapBundle<K, V> = {
-    /** Emits `ReadonlyMap<K, V>` on each structural change (two-phase). */
-    entries: Node<ReadonlyMap<K, V>>;
-    /**
-     * Checks existence. O(1) for live keys. If the key is expired, prunes it AND
-     * emits a snapshot so the reactive surface stays consistent with the return
-     * value. Reads on expired keys are therefore **observable side effects**.
-     *
-     * **LRU touch (F4):** When `maxSize` is configured, a live-key `has` also
-     * marks the entry as most-recently-used — which rearranges internal insertion
-     * order without bumping `version` or emitting. If you care about iteration
-     * order in a downstream subscriber, rely on the `entries` snapshot (a fresh
-     * `ReadonlyMap` per mutation) rather than iterating the backend directly.
-     */
-    has: (key: K) => boolean;
-    /**
-     * Gets value. O(1) for live keys. If the key is expired, prunes it AND emits
-     * a snapshot. Reads on expired keys are therefore **observable side effects**.
-     *
-     * **LRU touch (F4):** When `maxSize` is configured, a live-key `get` also
-     * marks the entry as most-recently-used (no version bump, no emission). See
-     * `has` for the full note on iteration order.
-     */
-    get: (key: K) => V | undefined;
-    /**
-     * Sets value with optional TTL (seconds). Throws on `ttl <= 0`. Applies LRU eviction
-     * if `maxSize` is set. Always emits.
-     */
-    set: (key: K, value: V, opts?: {
-        ttl?: number;
-    }) => void;
-    /**
-     * Bulk set — emits one snapshot for the whole batch. Applies `opts.ttl` (falls back
-     * to `defaultTtl`) to every entry. No-op if `entries` is empty.
-     *
-     * **Iterable consumption:** Consumes `entries` once (single-pass). Pass an array
-     * or `Set` for multi-shot consumers. If the iterator throws mid-iteration,
-     * entries already applied remain committed and a snapshot IS emitted (via the
-     * wrapper's finally-block).
-     */
-    setMany: (entries: Iterable<readonly [K, V]>, opts?: {
-        ttl?: number;
-    }) => void;
-    delete: (key: K) => void;
-    /**
-     * Bulk delete — emits one snapshot. No-op if no keys were present.
-     *
-     * **Iterable consumption:** Consumes `keys` once (single-pass).
-     */
-    deleteMany: (keys: Iterable<K>) => void;
-    clear: () => void;
-    /**
-     * Current entry count — O(1), **pure read** (no emission). May include
-     * expired entries on TTL maps until a mutation or explicit
-     * `pruneExpired()` / `has(key)` / `get(key)` prunes them. Call
-     * `pruneExpired()` first if you need a live count.
-     */
-    readonly size: number;
-    /** Explicitly prunes all expired entries. Emits if any were removed. */
-    pruneExpired: () => void;
-    /**
-     * Releases any internal keepalive subscriptions so the bundle can be
-     * GC'd. `reactiveMap` currently holds none (the `entries` node lives only
-     * as long as external subscribers keep it alive), so `dispose()` is a
-     * no-op today — exposed for API parity with `reactiveIndex.dispose` /
-     * `reactiveList.dispose` / `reactiveLog.dispose`. Idempotent. D6(a).
-     */
-    dispose: () => void;
-};
-/**
- * Storage contract for {@link reactiveMap}. Implementations own the mutable state,
- * including optional TTL and LRU semantics, and expose a monotonic `version` counter
- * that increments on every change to visible state.
- *
- * The reactive layer reads `version` before and after each backend call; when it
- * advances, a snapshot is emitted. Reads (`has`, `get`) may internally prune the
- * target key if expired and advance `version` — in which case the layer emits so
- * subscribers see state consistent with the read's return value.
- *
- * @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 MapBackend<K, V> {
-    /** Monotonic mutation counter; increments on every visible state change. */
-    readonly version: number;
-    /** Raw entry count (may include expired entries until a read / prune removes them). */
-    readonly size: number;
-    /** Checks existence. May prune target key if expired; advances `version` if pruned. */
-    has(key: K): boolean;
-    /** Gets value. May prune target key if expired; advances `version` if pruned. */
-    get(key: K): V | undefined;
-    /**
-     * Sets a value with optional TTL (seconds). Throws `RangeError` if `ttl <= 0`.
-     * Applies LRU eviction if `maxSize` is configured. Advances `version`.
-     *
-     * **Atomicity contract:** Either fully succeeds or throws before any state
-     * change; `version` advances only on success.
-     */
-    set(key: K, value: V, ttl?: number): void;
-    /**
-     * Atomic bulk set. Pre-validates TTL once, then applies all entries. Advances
-     * `version` at most once (even for N entries). No-op if iterable is empty.
-     *
-     * **Consumes `entries` once** — pass an array if you want repeatability.
-     *
-     * **Atomicity contract:** TTL validation throws before any mutation. If the
-     * iterable itself throws mid-iteration, entries committed before the throw
-     * remain persisted AND `version` is bumped once (surfaced via finally) so
-     * the reactive wrapper emits a snapshot reflecting the partial state. "At
-     * most once" invariant is preserved.
-     */
-    setMany(entries: Iterable<readonly [K, V]>, ttl?: number): void;
-    /** Removes a key. Returns `true` if the key existed. Advances `version` only if true. */
-    delete(key: K): boolean;
-    /**
-     * Atomic bulk delete. Returns count removed. Advances `version` at most once
-     * (even for N keys). No-op if no keys were present. Consumes `keys` once.
-     */
-    deleteMany(keys: Iterable<K>): number;
-    /** Removes all entries. Returns count removed. Advances `version` only if non-zero. */
-    clear(): number;
-    /** Removes all expired entries. Returns count removed. Advances `version` only if non-zero. */
-    pruneExpired(): number;
-    /** Fresh snapshot of non-expired entries (does NOT mutate state). */
-    toMap(): ReadonlyMap<K, V>;
-}
-type NativeMapBackendOptions = {
-    maxSize?: number;
-    /** Default TTL in seconds. */
-    defaultTtl?: number;
-};
-/**
- * Default `Map<K, {value, expiresAt}>` backend with optional per-key TTL and LRU cap.
- *
- * **Complexity:**
- * - `has`, `get`, `delete`, `size`: O(1)
- * - `set`: O(1) amortized (LRU touch + eviction)
- * - `pruneExpired`, `toMap`: O(n)
- *
- * LRU order uses native `Map` insertion order. `get` / `has` on a live key "touches"
- * it by delete-then-reinsert (moving it to the end). This touch does NOT advance
- * `version` — it's an internal optimization; the externally visible snapshot
- * preserves iteration order as of the last mutation. **Note:** because touch
- * reorders the internal `_store` without emitting, an in-process consumer iterating
- * `_store` directly (custom subclasses) could observe changing order; external
- * subscribers only see `toMap()` snapshots which are defensively copied and stable.
- *
- * @category extra
- */
-declare class NativeMapBackend<K, V> implements MapBackend<K, V> {
-    private _version;
-    private readonly _store;
-    private readonly _maxSize?;
-    private readonly _defaultTtl?;
-    constructor(options?: NativeMapBackendOptions);
-    get version(): number;
-    get size(): number;
-    has(key: K): boolean;
-    get(key: K): V | undefined;
-    set(key: K, value: V, ttl?: number): void;
-    setMany(entries: Iterable<readonly [K, V]>, ttl?: number): void;
-    delete(key: K): boolean;
-    deleteMany(keys: Iterable<K>): number;
-    clear(): number;
-    pruneExpired(): number;
-    toMap(): ReadonlyMap<K, V>;
-    private _resolveExpiresAt;
-    private _isExpired;
-    private _touchLru;
-    private _evictLruWhileOver;
-}
-/**
- * Creates a reactive `Map` with optional per-key TTL and optional LRU max size.
- *
- * @param options - `name`, `maxSize`, `defaultTtl` (seconds), or custom `backend`.
- * @returns `ReactiveMapBundle` — imperative methods (`has`/`get`/`set`/`setMany`/`delete`/
- *   `deleteMany`/`clear`/`pruneExpired`), reactive `entries` node, and O(1)-ish `size`.
- *
- * @remarks
- * **TTL:** Expiry is checked on `get`, `has`, `size`, `pruneExpired`, and before each
- * snapshot emission (expired keys are pruned first). Reads that discover expired keys
- * emit a snapshot so subscribers see state consistent with the read's return value.
- * There is no background timer; monotonic-clock expiry is immune to wall-clock changes.
- *
- * **LRU:** Uses native `Map` insertion order — `get` / `has` refreshes position via
- * delete-then-reinsert; under `maxSize` pressure the first key in iteration order is
- * evicted. LRU touching does NOT trigger emission (internal optimization).
- *
- * **Backend:** The default {@link NativeMapBackend} owns LRU/TTL. For persistent /
- * HAMT / shared-state semantics plug in a custom {@link MapBackend}. `maxSize` and
- * `defaultTtl` on the options object are only applied to the default backend — if
- * you supply `backend`, configure those on your backend directly.
- *
- * @example
- * ```ts
- * import { reactiveMap } from "@graphrefly/graphrefly-ts";
- *
- * const m = reactiveMap<string, number>({ name: "cache", maxSize: 100, defaultTtl: 60 });
- * m.set("x", 1);
- * m.setMany([["y", 2], ["z", 3]]);
- * m.entries.subscribe((msgs) => { console.log(msgs); });
- * ```
- *
- * @category extra
- */
-declare function reactiveMap<K, V>(options?: ReactiveMapOptions<K, V>): ReactiveMapBundle<K, V>;
-
-export { type MapBackend as M, NativeMapBackend as N, type ReactiveMapBundle as R, type NativeMapBackendOptions as a, type ReactiveMapOptions as b, type ReactiveMapRetention as c, reactiveMap as r };