@graphrefly/graphrefly 0.27.0 → 0.29.0

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

@@ -0,0 +1,190 @@
+import { a as Node, V as VersioningLevel } from './node-Dd6wHSib.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;
+    /**
+     * 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>;
+};
+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 (Python-style). */
+    at: (index: number) => T | undefined;
+    append: (value: T) => void;
+    /**
+     * Push all values, emit one snapshot. No-op if `values` is empty.
+     * **Iterable consumption:** `values` is a `readonly T[]` — safe to pass arrays.
+     */
+    appendMany: (values: readonly T[]) => void;
+    clear: () => void;
+    /** Remove the first `n` entries (clamped to `size`). Throws on non-integer or negative `n`. */
+    trimHead: (n: number) => void;
+    /**
+     * Last `n` entries (or fewer) as a derived reactive view. Memoized with
+     * an LRU cache (default cap 64) — repeat calls with the same `n` return
+     * the same node. Throws on non-integer or negative `n`.
+     *
+     * **LRU eviction contract (D3(b)):** when a 65th distinct `n` is passed,
+     * the least-recently-used cached view is evicted and its keepalive is
+     * disposed. External holders of the evicted node will NOT receive further
+     * updates — re-call `tail(n)` for a fresh node, or dispose proactively
+     * via {@link disposeTail} / {@link disposeAllViews}. To avoid surprise:
+     * resolve `tail(n)` at the point of use rather than caching the returned
+     * node across many distinct `n`s.
+     */
+    tail: (n: number) => Node<readonly T[]>;
+    /**
+     * Reactive view of `entries.slice(start, stop)` — non-negative integer
+     * `start`, non-negative integer `stop` (exclusive) or `undefined` (to end).
+     * Memoized with an LRU cache (default cap 64) — repeat calls with the
+     * same `(start, stop)` return the same node.
+     *
+     * Throws on non-integer `start`, negative `start`, non-integer `stop`, or
+     * negative `stop` (P4 — the backend cannot cheaply honor JS-style
+     * negative `stop` without scanning length; disallowed for a consistent
+     * contract between backend, derived recomputation, and cached initial).
+     *
+     * **LRU eviction contract (D3(b)):** same as {@link tail} — past 64
+     * distinct `(start, stop)` pairs, the oldest cached view is evicted and
+     * its keepalive disposed. External holders stop receiving updates.
+     */
+    slice: (start: number, stop?: number) => Node<readonly T[]>;
+    /**
+     * Releases the cached `tail(n)` view if present (disposes its keepalive
+     * subscription). Subsequent `tail(n)` calls create a fresh node. No-op if
+     * `n` was not cached. Returns `true` if a view was disposed.
+     */
+    disposeTail: (n: number) => boolean;
+    /**
+     * Releases the cached `slice(start, stop?)` view if present. No-op if not cached.
+     */
+    disposeSlice: (start: number, stop?: number) => boolean;
+    /** Releases all cached tail/slice views and their keepalive subscriptions. */
+    disposeAllViews: () => void;
+    /**
+     * Releases all internal keepalive subscriptions so the bundle can be
+     * GC'd — currently equivalent to {@link disposeAllViews}, but exposed as
+     * a uniform API across all reactive data structures for lifecycle
+     * symmetry (mirrors `reactiveMap.dispose` / `reactiveList.dispose` /
+     * `reactiveIndex.dispose`). Idempotent. D6(a).
+     */
+    dispose: () => void;
+};
+/**
+ * Storage contract for {@link reactiveLog}. 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 persistent / ring-buffer / skip-list
+ * 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
+ */
+interface LogBackend<T> {
+    /** Monotonic mutation counter; increments on every append/trim/clear that changes state. */
+    readonly version: number;
+    /** Number of entries currently stored. */
+    readonly size: number;
+    /** O(1) positional access; returns `undefined` on out-of-range. */
+    at(index: number): T | undefined;
+    /** Append a value. Applies `maxSize` head-drop if configured. Advances `version`. */
+    append(value: T): void;
+    /** Append a batch; advances `version` once. No-op if `values.length === 0`. */
+    appendMany(values: readonly T[]): void;
+    /** Remove all entries. Returns count removed. Advances `version` only if non-zero. */
+    clear(): number;
+    /** Remove the first `n` entries (clamped). Returns count removed. Throws on negative `n`. */
+    trimHead(n: number): number;
+    /** Fresh snapshot array for `[start, stop)`. Throws on negative `start`. */
+    slice(start: number, stop?: number): readonly T[];
+    /** Last `n` entries as a fresh array. Throws on negative `n`. */
+    tail(n: number): readonly T[];
+    /** Full snapshot as a fresh array. */
+    toArray(): readonly T[];
+}
+/**
+ * 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.
+ *
+ * `appendMany` pre-trims oversize input: if `values.length > maxSize`, only the
+ * tail of `values` is pushed (the rest would be immediately evicted).
+ *
+ * @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[];
+    /** Internal append without version bump — used by `appendMany`. */
+    private _rawAppend;
+}
+/**
+ * Creates an append-only reactive log with immutable array snapshots.
+ *
+ * @param initial - Optional seed entries (copied; pre-trimmed to `maxSize` if set).
+ * @param options - `name`, `maxSize`, and optional pluggable `backend`.
+ * @returns Bundle with `entries` (state node), `append`/`appendMany`/`clear`/`trimHead`,
+ *   `size` / `at`, and memoized derived views `tail(n)` / `slice(start, stop?)`.
+ *
+ * @remarks
+ * **Backend:** The default {@link NativeLogBackend} uses a ring buffer when `maxSize`
+ * is set (O(1) append + trim) and a flat array otherwise. For persistent/structural-
+ * sharing semantics plug in a custom {@link LogBackend}.
+ *
+ * **`initial` + custom `backend` (F5):** When you supply `options.backend`, the
+ * `initial` argument is IGNORED — seed the backend yourself before passing it in.
+ * The `initial` seed only applies to the default `NativeLogBackend`.
+ *
+ * **Memoized views:** {@link ReactiveLogBundle.tail} and {@link ReactiveLogBundle.slice}
+ * cache derived nodes per-argument. Repeat calls with the same `n` / `(start, stop)`
+ * return the same node, bounding keepalive-subscription count to one per unique argument.
+ *
+ * @example
+ * ```ts
+ * import { reactiveLog } from "@graphrefly/graphrefly-ts";
+ *
+ * const lg = reactiveLog<number>([1, 2], { name: "audit", maxSize: 100 });
+ * lg.append(3);
+ * lg.entries.subscribe((msgs) => console.log(msgs));
+ * const last5 = lg.tail(5);          // derived node
+ * const window = lg.slice(10, 20);   // derived node
+ * ```
+ *
+ * @category extra
+ */
+declare function reactiveLog<T>(initial?: readonly T[], options?: ReactiveLogOptions<T>): ReactiveLogBundle<T>;
+
+export { type LogBackend as L, NativeLogBackend as N, type ReactiveLogBundle as R, type ReactiveLogOptions as a, reactiveLog as r };

package/dist/{composite-aUCvjZVR.d.ts → reactive-map-CwO_COHy.d.cts}

@@ -1,5 +1,4 @@
-import { N as Node, a6 as VersioningLevel, a as NodeOptions } from './node-BmerH3kS.js';
-import { NodeInput } from './extra/sources.js';
+import { a as Node, V as VersioningLevel, N as NodeOptions } from './node-Dd6wHSib.cjs';
 
 type ReactiveMapOptions<K, V> = {
     /** Optional registry name for `describe()` / debugging. */
@@ -236,68 +235,4 @@ declare class NativeMapBackend<K, V> implements MapBackend<K, V> {
  */
 declare function reactiveMap<K, V>(options?: ReactiveMapOptions<K, V>): ReactiveMapBundle<K, V>;
 
-/**
- * Composite data patterns (roadmap §3.2b).
- *
- * These helpers compose existing primitives (`node`, `switchMap`, `reactiveMap`,
- * `dynamicNode`, `fromAny`) without introducing new protocol semantics.
- */
-
-/**
- * Verification payload shape is intentionally user-defined.
- */
-type VerifyValue = unknown;
-type VerifiableOptions<TVerify = VerifyValue> = Omit<NodeOptions, "describeKind" | "initial"> & {
-    /** Reactive re-verification trigger. */
-    trigger?: NodeInput<unknown>;
-    /** Re-run verification whenever `source` settles. */
-    autoVerify?: boolean;
-    /** Initial verification companion value. */
-    initialVerified?: TVerify | null;
-};
-type VerifiableBundle<T, TVerify = VerifyValue> = {
-    /** Coerced source node. */
-    node: Node<T>;
-    /** Latest verification result (`null` before first verification). */
-    verified: Node<TVerify | null>;
-    /** Effective trigger node used for verification, if any. */
-    trigger: Node<unknown> | null;
-};
-/**
- * Composes a value node with a reactive verification companion.
- *
- * Uses `switchMap` so newer triggers cancel stale in-flight verification work.
- */
-declare function verifiable<T, TVerify = VerifyValue>(source: NodeInput<T>, verifyFn: (value: T) => NodeInput<TVerify>, opts?: VerifiableOptions<TVerify>): VerifiableBundle<T, TVerify>;
-type Extraction<TMem> = {
-    upsert: Array<{
-        key: string;
-        value: TMem;
-    }>;
-    remove?: string[];
-};
-type DistillOptions<TMem> = {
-    score: (mem: TMem, context: unknown) => number;
-    cost: (mem: TMem) => number;
-    budget?: number;
-    evict?: (key: string, mem: TMem) => boolean | Node<boolean>;
-    consolidate?: (entries: ReadonlyMap<string, TMem>) => NodeInput<Extraction<TMem>>;
-    consolidateTrigger?: NodeInput<unknown>;
-    context?: NodeInput<unknown>;
-    mapOptions?: ReactiveMapOptions<string, TMem>;
-};
-type DistillBundle<TMem> = {
-    store: ReactiveMapBundle<string, TMem>;
-    compact: Node<Array<{
-        key: string;
-        value: TMem;
-        score: number;
-    }>>;
-    size: Node<number>;
-};
-/**
- * Budget-constrained reactive memory composition.
- */
-declare function distill<TRaw, TMem>(source: NodeInput<TRaw>, extractFn: (raw: TRaw, existing: ReadonlyMap<string, TMem>) => NodeInput<Extraction<TMem>>, opts: DistillOptions<TMem>): DistillBundle<TMem>;
-
-export { type DistillBundle as D, type Extraction as E, type MapBackend as M, NativeMapBackend as N, type ReactiveMapBundle as R, type VerifiableBundle as V, type DistillOptions as a, type NativeMapBackendOptions as b, type ReactiveMapOptions as c, type VerifiableOptions as d, type VerifyValue as e, distill as f, reactiveMap as r, verifiable as v };
+export { type MapBackend as M, NativeMapBackend as N, type ReactiveMapBundle as R, type ReactiveMapOptions as a, type NativeMapBackendOptions as b, reactiveMap as r };

package/dist/{composite-C7PcQvcs.d.cts → reactive-map-FeuTVAJb.d.ts}

@@ -1,5 +1,4 @@
-import { N as Node, a6 as VersioningLevel, a as NodeOptions } from './node-BmerH3kS.cjs';
-import { NodeInput } from './extra/sources.cjs';
+import { a as Node, V as VersioningLevel, N as NodeOptions } from './node-Dd6wHSib.js';
 
 type ReactiveMapOptions<K, V> = {
     /** Optional registry name for `describe()` / debugging. */
@@ -236,68 +235,4 @@ declare class NativeMapBackend<K, V> implements MapBackend<K, V> {
  */
 declare function reactiveMap<K, V>(options?: ReactiveMapOptions<K, V>): ReactiveMapBundle<K, V>;
 
-/**
- * Composite data patterns (roadmap §3.2b).
- *
- * These helpers compose existing primitives (`node`, `switchMap`, `reactiveMap`,
- * `dynamicNode`, `fromAny`) without introducing new protocol semantics.
- */
-
-/**
- * Verification payload shape is intentionally user-defined.
- */
-type VerifyValue = unknown;
-type VerifiableOptions<TVerify = VerifyValue> = Omit<NodeOptions, "describeKind" | "initial"> & {
-    /** Reactive re-verification trigger. */
-    trigger?: NodeInput<unknown>;
-    /** Re-run verification whenever `source` settles. */
-    autoVerify?: boolean;
-    /** Initial verification companion value. */
-    initialVerified?: TVerify | null;
-};
-type VerifiableBundle<T, TVerify = VerifyValue> = {
-    /** Coerced source node. */
-    node: Node<T>;
-    /** Latest verification result (`null` before first verification). */
-    verified: Node<TVerify | null>;
-    /** Effective trigger node used for verification, if any. */
-    trigger: Node<unknown> | null;
-};
-/**
- * Composes a value node with a reactive verification companion.
- *
- * Uses `switchMap` so newer triggers cancel stale in-flight verification work.
- */
-declare function verifiable<T, TVerify = VerifyValue>(source: NodeInput<T>, verifyFn: (value: T) => NodeInput<TVerify>, opts?: VerifiableOptions<TVerify>): VerifiableBundle<T, TVerify>;
-type Extraction<TMem> = {
-    upsert: Array<{
-        key: string;
-        value: TMem;
-    }>;
-    remove?: string[];
-};
-type DistillOptions<TMem> = {
-    score: (mem: TMem, context: unknown) => number;
-    cost: (mem: TMem) => number;
-    budget?: number;
-    evict?: (key: string, mem: TMem) => boolean | Node<boolean>;
-    consolidate?: (entries: ReadonlyMap<string, TMem>) => NodeInput<Extraction<TMem>>;
-    consolidateTrigger?: NodeInput<unknown>;
-    context?: NodeInput<unknown>;
-    mapOptions?: ReactiveMapOptions<string, TMem>;
-};
-type DistillBundle<TMem> = {
-    store: ReactiveMapBundle<string, TMem>;
-    compact: Node<Array<{
-        key: string;
-        value: TMem;
-        score: number;
-    }>>;
-    size: Node<number>;
-};
-/**
- * Budget-constrained reactive memory composition.
- */
-declare function distill<TRaw, TMem>(source: NodeInput<TRaw>, extractFn: (raw: TRaw, existing: ReadonlyMap<string, TMem>) => NodeInput<Extraction<TMem>>, opts: DistillOptions<TMem>): DistillBundle<TMem>;
-
-export { type DistillBundle as D, type Extraction as E, type MapBackend as M, NativeMapBackend as N, type ReactiveMapBundle as R, type VerifiableBundle as V, type DistillOptions as a, type NativeMapBackendOptions as b, type ReactiveMapOptions as c, type VerifiableOptions as d, type VerifyValue as e, distill as f, reactiveMap as r, verifiable as v };
+export { type MapBackend as M, NativeMapBackend as N, type ReactiveMapBundle as R, type ReactiveMapOptions as a, type NativeMapBackendOptions as b, reactiveMap as r };