bireactive 0.2.0

package/dist/core/signal.d.ts

@@ -0,0 +1,254 @@
+interface ReactiveNode {
+    flags: number;
+    deps: Link | undefined;
+    depsTail: Link | undefined;
+    subs: Link | undefined;
+    subsTail: Link | undefined;
+    _update(): boolean;
+    _notify(): void;
+    _unwatched(): void;
+}
+interface Link {
+    version: number;
+    dep: ReactiveNode;
+    sub: ReactiveNode;
+    prevSub: Link | undefined;
+    nextSub: Link | undefined;
+    prevDep: Link | undefined;
+    nextDep: Link | undefined;
+}
+/** Install a hook fired on every source value-change; returns a restore fn. */
+export declare function setCellWriteHook(fn: ((sig: Cell<unknown>) => void) | undefined): () => void;
+export interface MergePolicy<T> {
+    readonly identity: T;
+    combine(acc: T, x: T): T;
+    /** Optional inverse for incremental fold. */
+    remove?(acc: T, x: T): T;
+}
+export declare const DIRECT_SLOT: unique symbol;
+declare class MergeNode<T> {
+    readonly parent: Cell<T>;
+    readonly policy: MergePolicy<T>;
+    readonly slots: Map<unknown, T>;
+    readonly hasIncrementalAcc: boolean;
+    acc: T;
+    constructor(parent: Cell<T>, policy: MergePolicy<T>);
+    receive(slot: unknown, next: T): void;
+    fold(): T;
+    reset(): void;
+}
+declare class BwdSpec {
+    /** Backward target(s): one `Cell` (1→1 / merge) or `Cell[]` (multi-out). */
+    parent: Cell<unknown> | Cell<unknown>[] | undefined;
+    /** Lens `put` — backward derivation (dual of `getter`). Always called by
+     *  the engine in 1-arg form `put(target)`; a source-reading lens bakes
+     *  `settled(parent)` into this closure at build time. Multi-output:
+     *  returns a per-parent update array. Stateful: the spec's `bwd`. */
+    put: ((target: any, current?: any) => any) | undefined;
+    /** Backward aggregation node; presence IS the merge-mode discriminant. */
+    merge: MergeNode<unknown> | undefined;
+    /** Complement machinery; presence IS the stateful-mode discriminant. */
+    stateful: StatefulCore | undefined;
+    /** Index in `bwdQueue` of this cell's latest push; the drain skips stale
+     *  entries so each cell propagates backward once per flush, last-write. */
+    queueIdx: number;
+}
+/** Runtime state of a stateful (complement-carrying) lens — the rare
+ *  backward mode, kept off `BwdSpec` so plain lenses don't carry its slots.
+ *  `put` (the spec's `bwd`) and `parent` stay on `BwdSpec`; this holds the
+ *  complement and the closures that project from / advance it. */
+declare class StatefulCore {
+    /** Engine-owned memory the view discards. */
+    complement: unknown;
+    /** Forward projection `fwd(sources, complement) → view`. */
+    fwd: (sources: any, complement: any) => any;
+    /** Advance the complement: `step(sources, complement, external)`. */
+    step: (sources: any, complement: any, external: boolean) => any;
+    /** Source values last written back (own-vs-external test); `undefined`
+     *  until the first back-write. */
+    lastBwd: unknown[] | undefined;
+    constructor(complement: unknown, fwd: (sources: any, complement: any) => any, step: (sources: any, complement: any, external: boolean) => any);
+}
+/** Plain T or any read-shape; snapshot via `readNow`, close via `reader`. */
+export type Val<T> = T | Read<T>;
+/** Covariant read-only surface. */
+export interface Read<out T> {
+    readonly value: T;
+    peek(): T;
+}
+/** Brand discriminating writable receivers in conditional return types. */
+declare const WRITABLE: unique symbol;
+export interface WritableBrand {
+    readonly [WRITABLE]: never;
+}
+/** Value type carried by a reactive read shape. */
+export type Inner<R> = R extends Cell<infer T> ? T : R extends Read<infer T> ? T : never;
+/** The writable form of R: adds the brand + a settable `value`. */
+export type Writable<R> = R & WritableBrand & {
+    value: Inner<R>;
+};
+/** Strict factory input: a literal, or an existing `Writable<Cls>`. */
+export type Init<C extends Cell<any>> = Inner<C> | Writable<C>;
+/** Snapshot a `Val<T>` to plain `T` (one-shot, no tracking). */
+export declare function readNow<T>(v: Val<T>): T;
+/** Resolve a `Val<T>` to a `() => T` closure that unwraps on each call. */
+export declare function reader<T>(v: Val<T>): () => T;
+/** Lazy getter: computes once, installs a non-enumerable own prop under
+ *  `key` that shadows this getter on later reads. */
+export declare function lazy<R>(self: object, key: string | symbol, make: () => R): R;
+export declare const isCell: (v: unknown) => v is Cell<unknown>;
+/** Lens mode: a derived cell that can be written back (has a backward sidecar). */
+export declare const isLens: (v: unknown) => v is Cell<unknown>;
+/** Computed mode: derived + read-only (no backward path). */
+export declare const isComputed: (v: unknown) => v is Cell<unknown>;
+export interface CellOptions<T = unknown> {
+    /** First subscriber attached; fired from `link`. */
+    watched?: () => void;
+    /** Last subscriber detached; fired from `_unwatched`. */
+    unwatched?: () => void;
+    /** Per-instance value equality; defaults to `Object.is`. */
+    equals?: (a: T, b: T) => boolean;
+}
+export declare class Cell<T = unknown> implements ReactiveNode {
+    flags: number;
+    subs: Link | undefined;
+    subsTail: Link | undefined;
+    deps: Link | undefined;
+    depsTail: Link | undefined;
+    /** Forward derivation (computed/lens/merge). `undefined` ⇒ source. */
+    getter: (() => T) | undefined;
+    /** Per-instance equality, always defined (defaults to `Object.is` at
+     *  construction) so hot paths call it without an `undefined` branch. */
+    _equals: (a: T, b: T) => boolean;
+    /** First-subscriber / last-subscriber lifecycle hooks. */
+    _watched: (() => void) | undefined;
+    _unwatchedHook: (() => void) | undefined;
+    /** Source: `currentValue` = committed, `pendingValue` = staged write.
+     *  Getter cell: `currentValue` = last derived cache, `pendingValue`
+     *  reused as the deferred backward target (see `set value`). The two
+     *  roles never coexist, so two fields suffice for four. */
+    currentValue: T;
+    pendingValue: T;
+    /** Backward sidecar: target(s) + lens closures + queue slot, or
+     *  `undefined` for a read-only cell (source or computed). Allocated only
+     *  for writable derived cells, keeping the common node lean. Writability
+     *  is exactly `_bwd !== undefined`. See `BwdSpec`. */
+    _bwd: BwdSpec | undefined;
+    constructor(initial: T, opts?: CellOptions<T>);
+    readonly value: T;
+    _enqueueBwd(): void;
+    /** Source write (alien's signal setter). Self-excludes the active
+     *  network so a body writing its own dep doesn't re-trigger itself. */
+    _writeSource(next: T): void;
+    _update(): boolean;
+    _notify(): void;
+    _unwatched(): void;
+    peek(): T;
+    /** Guard: silent coercion to string/number is almost always a bug. */
+    [Symbol.toPrimitive](hint: string): never;
+    /** Endomorphic lens. A 2-arg `bwd(view, current)` consults the current
+     *  source; a 1-arg `bwd(view)` reconstructs it from the view alone. */
+    lens(this: Cell<T>, fwd: (v: T) => T, bwd: (target: T, current: T) => T): this;
+    /** Backward-aggregating node — bwd dual of computed. Forward, the
+     *  identity view of its parent; backward, folds contributions from
+     *  upstream lenses (slot-keyed) and direct writes (DIRECT_SLOT). */
+    merge(this: Cell<T>, policy: MergePolicy<T>): Cell<T>;
+    /** Read-only typed view. `Cls.derive(parent, fn)` (1-input),
+     *  `Cls.derive(parents, fn)` (N-input), or `Cls.derive(fn)` (closure).
+     *  Polymorphic-`this`: `Vec.derive(...)` → `Vec`. */
+    static derive<C extends new (...args: never[]) => Cell<any>, P>(this: C, parent: Read<P>, fn: (v: P) => Inner<InstanceType<C>>): InstanceType<C>;
+    static derive<C extends new (...args: never[]) => Cell<any>, P extends readonly Read<unknown>[]>(this: C, parents: P, fn: (vals: {
+        [K in keyof P]: P[K] extends Read<infer V> ? V : never;
+    }) => Inner<InstanceType<C>>): InstanceType<C>;
+    static derive<C extends new (...args: never[]) => Cell<any>>(this: C, fn: () => Inner<InstanceType<C>>): InstanceType<C>;
+    /** Writable lens. `Cls.lens(parent, fwd, bwd)` for one input,
+     *  `Cls.lens(parents, fwd, bwd)` for N; a 2-arg `bwd` reads the source,
+     *  a 1-arg `bwd` reconstructs it. `Cls.lens(parent(s), spec)` builds a
+     *  complement-carrying lens from `{ init, step, fwd, bwd }`. */
+    static lens<C extends new (...args: never[]) => Cell<any>, P>(this: C, parent: Read<P>, fwd: (v: P) => Inner<InstanceType<C>>, bwd: (target: Inner<InstanceType<C>>, v: P) => P): Writable<InstanceType<C>>;
+    static lens<C extends new (...args: never[]) => Cell<any>, P extends readonly Read<unknown>[]>(this: C, parents: P, fwd: (vals: {
+        [K in keyof P]: P[K] extends Read<infer V> ? V : never;
+    }) => Inner<InstanceType<C>>, bwd: (target: Inner<InstanceType<C>>, vals: {
+        [K in keyof P]: P[K] extends Read<infer V> ? V : never;
+    }) => {
+        [K in keyof P]?: P[K] extends Read<infer V> ? V : never;
+    }): Writable<InstanceType<C>>;
+    static lens<C extends new (...args: never[]) => Cell<any>, P, Cm>(this: C, parent: Read<P>, spec: StatefulLensSpec<readonly [P], Inner<InstanceType<C>>, Cm>): Writable<InstanceType<C>>;
+    static lens<C extends new (...args: never[]) => Cell<any>, P extends readonly Read<unknown>[], Cm>(this: C, parents: P, spec: StatefulLensSpec<{
+        [K in keyof P]: P[K] extends Read<infer V> ? V : never;
+    }, Inner<InstanceType<C>>, Cm>): Writable<InstanceType<C>>;
+    /** Type predicate against this class: `Vec.is(x)` narrows `x` to `Vec`.
+     *  Inherited static; works for any subclass via polymorphic `this`. */
+    static is<C extends new (...args: never[]) => Cell<any>>(this: C, v: unknown): v is InstanceType<C>;
+    /** Lift `Val<Inner<Cls>>` → `Cls`: instance → identity, RO cell →
+     *  tracked `derive`, literal → fresh seed. */
+    static from<C extends new (...args: never[]) => Cell<any>>(this: C, v: Val<Inner<InstanceType<C>>>): InstanceType<C>;
+    /** Writable-shaped constant: always reads `v`, absorbs writes
+     *  (parentless sink lens), for APIs demanding bidirectionality. */
+    static pin<C extends new (...args: never[]) => Cell<any>>(this: C, v: Inner<InstanceType<C>>): Writable<InstanceType<C>>;
+    /** Typed field lens onto `parent.value[key]`. A read-only computed
+     *  parent yields a RO derive view; any writable parent yields a
+     *  bidirectional field lens with spread-replace `put`. */
+    static fieldOf<C extends new (...args: never[]) => Cell<any>>(parent: Cell<any>, key: string | number | symbol, Cls: C): InstanceType<C>;
+}
+export interface StatefulBwd<S extends readonly unknown[], C> {
+    updates: {
+        readonly [K in keyof S]: S[K] | undefined;
+    };
+    complement: C;
+}
+export interface StatefulLensSpec<S extends readonly unknown[], V, C> {
+    init: (sources: S) => C;
+    step: (sources: S, complement: C, external: boolean) => C;
+    fwd: (sources: S, complement: C) => V;
+    bwd: (target: V, sources: S, complement: C) => StatefulBwd<S, C>;
+}
+/** Writable source; passes an existing `Writable` through (idempotent). */
+export declare function cell<T>(initial: T | Writable<Cell<T>>, opts?: CellOptions<T>): Writable<Cell<T>>;
+export declare function computed<T>(fn: () => T): Cell<T>;
+/** Untyped read-only view: `derive(parent, fn)`, `derive(parents, fn)`,
+ *  or `derive(fn)` (closure). */
+export declare function derive<P, R>(parent: Read<P>, fn: (v: P) => R): Cell<R>;
+export declare function derive<P extends readonly Read<unknown>[], R>(parents: P, fn: (vals: {
+    [K in keyof P]: P[K] extends Read<infer V> ? V : never;
+}) => R): Cell<R>;
+export declare function derive<R>(fn: () => R): Cell<R>;
+/** Untyped lens, inferring `R` from the closures. A 2-arg `bwd` reads the
+ *  source, a 1-arg `bwd` reconstructs it; `lens(parent(s), spec)` builds a
+ *  complement-carrying lens. */
+export declare function lens<P, R>(parent: Read<P>, fwd: (v: P) => R, bwd: (target: R, v: P) => P): Writable<Cell<R>>;
+export declare function lens<P extends readonly Read<unknown>[], R>(parents: P, fwd: (vals: {
+    [K in keyof P]: P[K] extends Read<infer V> ? V : never;
+}) => R, bwd: (target: R, vals: {
+    [K in keyof P]: P[K] extends Read<infer V> ? V : never;
+}) => {
+    [K in keyof P]?: P[K] extends Read<infer V> ? V : never;
+}): Writable<Cell<R>>;
+export declare function lens<P, R, C>(parent: Read<P>, spec: StatefulLensSpec<readonly [P], R, C>): Writable<Cell<R>>;
+export declare function lens<P extends readonly Read<unknown>[], R, C>(parents: P, spec: StatefulLensSpec<{
+    [K in keyof P]: P[K] extends Read<infer V> ? V : never;
+}, R, C>): Writable<Cell<R>>;
+export declare function effect(fn: () => (() => void) | void): () => void;
+export declare function batch<R>(fn: () => R): R;
+export declare function untracked<R>(fn: () => R): R;
+/** Handle to a `network` invocation. */
+export interface Network {
+    /** Tear down: unsubscribe from every cell, drop internal state. */
+    dispose(): void;
+    /** Run the body now (manual mode's only advance; no-op if unchanged). */
+    flush(): void;
+    /** Add cells to the topology (idempotent; does NOT fire the body). */
+    subscribe(...sigs: Cell<any>[]): void;
+    /** Remove cells from the topology (idempotent; does NOT fire). */
+    unsubscribe(...sigs: Cell<any>[]): void;
+}
+/** Build a reactive sub-DAG node with explicit topology. The body fires
+ *  when any subscribed dep changes (`dirty` = the changed subset), runs
+ *  inside `batch()`, and self-excludes its own writes. Topology is the
+ *  deps array + later subscribe/unsubscribe (body reads add no deps).
+ *  `flush()` from inside the body throws; `manual: true` defers
+ *  auto-firing so only `flush()` advances. */
+export declare function network(deps: readonly Cell<any>[], body: (dirty: ReadonlySet<Cell<unknown>>, handle: Network) => void, opts?: {
+    manual?: boolean;
+}): Network;
+export {};