@elurjs/core 3.6.2 → 3.7.0-beta.0

package/dist/lib/elur/next-2/reactivity.d.cts

@@ -0,0 +1,220 @@
+/**
+ * Elur "next" — grafo reactivo push-pull versionado (experimental).
+ *
+ * Módulo aislado de `../reactivity.ts` (PLAN_TECNICO_ELUR_NEXT §B.3–B.9):
+ * nunca importar ambos en el mismo path de producción — mezclar signals de
+ * dos grafos rompe la semántica.
+ *
+ * Modelo:
+ *  - PUSH: signal.set() → version++ → invalida consumidores (DIRTY directos,
+ *    CHECK transitivos) y encola effects una sola vez. No recalcula nada.
+ *  - PULL: antes de ejecutar un effect se estabilizan sus fuentes — los
+ *    computeds DIRTY/CHECK se refrescan recursivamente y sólo propagan si el
+ *    resultado realmente cambió (early cutoff por versión).
+ *  - Liveness: un computed sin consumidores vivos no se suscribe a sus
+ *    fuentes; se refresca por sondeo de versiones al leerse (O(1) si el
+ *    epoch global no cambió).
+ *  - Edges: `Link` doble-enlazado compartido entre la lista de sources del
+ *    consumidor y la de consumers del productor — subscribe/remove O(1),
+ *    reutilizados entre evaluaciones (mark & sweep por `evalMark`).
+ */
+/** Cualquier cosa que pueda poseer consumidores: Owner raíz, Effect, Computed. */
+export interface OwnerLike {
+    /**
+     * Cabeza de la lista doblemente enlazada de hijos poseídos (effects,
+     * computeds, sub-owners). Lista intrusiva — el unregistro de un hijo es
+     * O(1) (antes: array con indexOf+splice O(n), que hacía el clear de
+     * listas grandes O(n²) — el gap de `09_clear1k` en Krausest).
+     */
+    childrenHead: (Disposable & OwnerLike) | null;
+    /** Número de hijos vivos — `childCount` para diagnóstico/tests. */
+    childCount: number;
+    /** Cleanups registrados con onCleanup() durante la última evaluación. */
+    cleanups: (() => void)[] | null;
+    /** Owner que era activo cuando este nodo fue creado (árbol de owners). */
+    parent: OwnerLike | null;
+    /** Links intrusivos al sibling anterior/siguiente en la lista del padre. */
+    nextOwned: (Disposable & OwnerLike) | null;
+    prevOwned: (Disposable & OwnerLike) | null;
+    /**
+     * A.16: boundary por owner — un consumidor sin handler propio burbujea
+     * el error por la cadena de owners hasta que uno lo maneja (true).
+     */
+    onOwnerError?: (err: unknown) => boolean;
+}
+export interface Disposable {
+    dispose(): void;
+}
+/** Raíz de ownership explícita (un mount, un test, un sub-árbol). */
+export declare class Owner implements OwnerLike, Disposable {
+    childrenHead: (Disposable & OwnerLike) | null;
+    childCount: number;
+    cleanups: (() => void)[] | null;
+    parent: OwnerLike | null;
+    nextOwned: (Disposable & OwnerLike) | null;
+    prevOwned: (Disposable & OwnerLike) | null;
+    onOwnerError?: (err: unknown) => boolean;
+    private _disposed;
+    dispose(): void;
+}
+/** Owner actual — para diagnóstico e integración con el kernel de mounts. */
+export declare function getOwner(): OwnerLike | null;
+/**
+ * Ejecuta fn con `owner` como dueño activo. Todo effect/computed creado
+ * dentro queda poseído por él y se destruye con él.
+ */
+export declare function runWithOwner<T>(owner: OwnerLike | null, fn: () => T): T;
+/**
+ * Raíz reactiva: `const dispose = createRoot(d => {...})`. Todo lo creado
+ * dentro muere con `dispose()` — elimina la clase de leaks de B.2.5.
+ */
+export declare function createRoot<T>(fn: (dispose: () => void) => T): T;
+/** Registra una limpieza en el owner activo (effect, computed o root). */
+export declare function onCleanup(fn: () => void): void;
+/**
+ * B.9: ciclo de efectos — un write dentro de un effect re-encola trabajo; si
+ * un nodo corre más de MAX_RUNS_PER_FLUSH en el mismo flush, es un bucle.
+ * El mensaje incluye el camino de dependencias del efecto (sus fuentes y,
+ * si son computeds, las suyas) para localizar el ciclo.
+ */
+export declare class ReactiveCycleError extends Error {
+    constructor(effect: ConsumerNode, runs: number);
+}
+interface ErrorHandler {
+    (err: unknown): void;
+}
+/** @internal */
+export declare function _pushErrorHandler(h: ErrorHandler): void;
+/** @internal */
+export declare function _popErrorHandler(): void;
+export interface _SignalDebugHooks {
+    onCreate?: (signal: Signal<any>, initialValue: unknown) => void;
+    onWrite?: (signal: Signal<any>, value: unknown) => void;
+}
+/** @internal */
+export declare function _setSignalDebugHooks(hooks: _SignalDebugHooks | null): void;
+/** @internal — añade suscriptor sin reemplazar; devuelve unsubscribe. */
+export declare function _addSignalDebugHooks(hooks: _SignalDebugHooks): () => void;
+/** @internal — la nueva impl no tiene notify buffer; se expone para paridad. */
+export declare function _getNotifyBufSize(): number;
+interface ProducerNode {
+    /** Incrementa en cada cambio real de valor. */
+    version: number;
+    /**
+     * B.12.4 (durabilidad, Salsa): producer estático — nunca cambia.
+     * `link()` no crea edge: cero bookkeeping para deps estáticas.
+     */
+    durable?: boolean;
+    /** Nº de links vivos en `consumersHead` (liveness del productor). */
+    liveCount: number;
+    consumersHead: Link | null;
+}
+/**
+ * Edge compartido: vive en dos listas a la vez — la de sources del consumer
+ * (`nextSource/prevSource`) y la de consumers del producer
+ * (`nextTarget/prevTarget`). `mark` lo usa el consumer para decidir qué
+ * links sobrevivieron a la última evaluación; `linked` indica si está
+ * insertado en la lista del producer (los computeds fríos no lo están).
+ */
+interface Link {
+    source: ProducerNode;
+    target: ConsumerNode;
+    seenVersion: number;
+    mark: number;
+    linked: boolean;
+    nextSource: Link | null;
+    prevSource: Link | null;
+    nextTarget: Link | null;
+    prevTarget: Link | null;
+}
+interface ConsumerNode {
+    state: number;
+    sourcesHead: Link | null;
+    /** Contador de evaluación — marca los links usados en esta pasada. */
+    evalMark: number;
+    live(): boolean;
+}
+export declare class Signal<T> implements ProducerNode {
+    version: number;
+    liveCount: number;
+    durable: boolean;
+    consumersHead: Link | null;
+    private _v;
+    constructor(initialValue: T);
+    get value(): T;
+    set value(newValue: T);
+    update(fn: (current: T) => T): void;
+    peek(): T;
+    dispose(): void;
+}
+export declare class Computed<T> extends Signal<T> implements ConsumerNode, OwnerLike {
+    state: number;
+    sourcesHead: Link | null;
+    evalMark: number;
+    /** Último epoch en que se verificó fresco — sondeo O(1) para fríos. */
+    lastCleanEpoch: number;
+    childrenHead: (Disposable & OwnerLike) | null;
+    childCount: number;
+    nextOwned: (Disposable & OwnerLike) | null;
+    prevOwned: (Disposable & OwnerLike) | null;
+    cleanups: (() => void)[] | null;
+    parent: OwnerLike | null;
+    _value: T | undefined;
+    fn: () => T;
+    equals: (a: T, b: T) => boolean;
+    flags: number;
+    /** B.12.1: transientes del DFS de refresh (null entre refreshes). */
+    _pCursor: Link | null;
+    _pLink: Link | null;
+    constructor(fn: () => T, equals?: (a: T, b: T) => boolean);
+    live(): boolean;
+    get value(): T;
+    peek(): T;
+    dispose(): void;
+}
+export declare function signal<T>(initialValue: T): Signal<T>;
+/**
+ * B.12.4 (durabilidad): signal estática — `link()` no crea edges sobre ella,
+ * así que dependencias estáticas no cuestan bookkeeping ni checks de refresh.
+ * Escribirla rompe el contrato (warn en dev); el valor no se propaga.
+ */
+export declare function constSignal<T>(value: T): Signal<T>;
+export declare function computed<T>(fn: () => T, equals?: (a: T, b: T) => boolean): Computed<T>;
+/** Corre una vez al crear; re-corre sólo si una fuente cambió de verdad. */
+export declare function effect(fn: () => void | (() => void)): () => void;
+/**
+ * @internal — effect de render (bindings DOM internos): se encola en la
+ * cola de render, que se drena ANTES que la de user effects (B.8). La API
+ * pública `effect()` sigue siendo la de usuario.
+ */
+export declare function _renderEffect(fn: () => void | (() => void)): () => void;
+export declare function batch<T>(fn: () => T): T;
+export declare function untrack<T>(fn: () => T): T;
+export interface WatchOptions {
+    immediate?: boolean;
+    once?: boolean;
+}
+export declare function watch<T>(source: Signal<T> | (() => T), cb: (value: T, oldValue: T | undefined) => void, options?: WatchOptions): () => void;
+export declare function nextTick(fn?: () => void): Promise<void>;
+/**
+ * @internal — binding de texto especializado (C.6): `node.nodeValue` sigue
+ * `fn()` con el mínimo consumer posible. `null`/`false`/`undefined` → "".
+ * Devuelve disposer (mata la suscripción; el caller remueve el nodo).
+ */
+export declare function _bindText(node: {
+    nodeValue: string | null;
+}, fn: () => unknown): () => void;
+/**
+ * @internal — C.6 T1: suscripción directa señal→writer. El writer corre una
+ * vez al montar (valor inicial) y por cada cambio real de la señal, en la
+ * cola de render. Devuelve disposer.
+ */
+export declare function _bindSignal<T>(source: Signal<T>, write: (v: T) => void): () => void;
+/**
+ * @internal — C.7 T2: suscripción directa señal→(getter derivado)→writer.
+ * Equivale a `_bindSignal(dep, () => write(get()))` con compare incluido,
+ * pero sin el closure intermedio ni el double-compare: un solo binding.
+ * Devuelve disposer.
+ */
+export declare function _bindDerived<T>(source: Signal<unknown>, get: () => T, write: (v: T) => void): () => void;
+export {};

package/dist/lib/elur/next-2/reactivity.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Elur "next" — grafo reactivo push-pull versionado (experimental).
+ *
+ * Módulo aislado de `../reactivity.ts` (PLAN_TECNICO_ELUR_NEXT §B.3–B.9):
+ * nunca importar ambos en el mismo path de producción — mezclar signals de
+ * dos grafos rompe la semántica.
+ *
+ * Modelo:
+ *  - PUSH: signal.set() → version++ → invalida consumidores (DIRTY directos,
+ *    CHECK transitivos) y encola effects una sola vez. No recalcula nada.
+ *  - PULL: antes de ejecutar un effect se estabilizan sus fuentes — los
+ *    computeds DIRTY/CHECK se refrescan recursivamente y sólo propagan si el
+ *    resultado realmente cambió (early cutoff por versión).
+ *  - Liveness: un computed sin consumidores vivos no se suscribe a sus
+ *    fuentes; se refresca por sondeo de versiones al leerse (O(1) si el
+ *    epoch global no cambió).
+ *  - Edges: `Link` doble-enlazado compartido entre la lista de sources del
+ *    consumidor y la de consumers del productor — subscribe/remove O(1),
+ *    reutilizados entre evaluaciones (mark & sweep por `evalMark`).
+ */
+/** Cualquier cosa que pueda poseer consumidores: Owner raíz, Effect, Computed. */
+export interface OwnerLike {
+    /**
+     * Cabeza de la lista doblemente enlazada de hijos poseídos (effects,
+     * computeds, sub-owners). Lista intrusiva — el unregistro de un hijo es
+     * O(1) (antes: array con indexOf+splice O(n), que hacía el clear de
+     * listas grandes O(n²) — el gap de `09_clear1k` en Krausest).
+     */
+    childrenHead: (Disposable & OwnerLike) | null;
+    /** Número de hijos vivos — `childCount` para diagnóstico/tests. */
+    childCount: number;
+    /** Cleanups registrados con onCleanup() durante la última evaluación. */
+    cleanups: (() => void)[] | null;
+    /** Owner que era activo cuando este nodo fue creado (árbol de owners). */
+    parent: OwnerLike | null;
+    /** Links intrusivos al sibling anterior/siguiente en la lista del padre. */
+    nextOwned: (Disposable & OwnerLike) | null;
+    prevOwned: (Disposable & OwnerLike) | null;
+    /**
+     * A.16: boundary por owner — un consumidor sin handler propio burbujea
+     * el error por la cadena de owners hasta que uno lo maneja (true).
+     */
+    onOwnerError?: (err: unknown) => boolean;
+}
+export interface Disposable {
+    dispose(): void;
+}
+/** Raíz de ownership explícita (un mount, un test, un sub-árbol). */
+export declare class Owner implements OwnerLike, Disposable {
+    childrenHead: (Disposable & OwnerLike) | null;
+    childCount: number;
+    cleanups: (() => void)[] | null;
+    parent: OwnerLike | null;
+    nextOwned: (Disposable & OwnerLike) | null;
+    prevOwned: (Disposable & OwnerLike) | null;
+    onOwnerError?: (err: unknown) => boolean;
+    private _disposed;
+    dispose(): void;
+}
+/** Owner actual — para diagnóstico e integración con el kernel de mounts. */
+export declare function getOwner(): OwnerLike | null;
+/**
+ * Ejecuta fn con `owner` como dueño activo. Todo effect/computed creado
+ * dentro queda poseído por él y se destruye con él.
+ */
+export declare function runWithOwner<T>(owner: OwnerLike | null, fn: () => T): T;
+/**
+ * Raíz reactiva: `const dispose = createRoot(d => {...})`. Todo lo creado
+ * dentro muere con `dispose()` — elimina la clase de leaks de B.2.5.
+ */
+export declare function createRoot<T>(fn: (dispose: () => void) => T): T;
+/** Registra una limpieza en el owner activo (effect, computed o root). */
+export declare function onCleanup(fn: () => void): void;
+/**
+ * B.9: ciclo de efectos — un write dentro de un effect re-encola trabajo; si
+ * un nodo corre más de MAX_RUNS_PER_FLUSH en el mismo flush, es un bucle.
+ * El mensaje incluye el camino de dependencias del efecto (sus fuentes y,
+ * si son computeds, las suyas) para localizar el ciclo.
+ */
+export declare class ReactiveCycleError extends Error {
+    constructor(effect: ConsumerNode, runs: number);
+}
+interface ErrorHandler {
+    (err: unknown): void;
+}
+/** @internal */
+export declare function _pushErrorHandler(h: ErrorHandler): void;
+/** @internal */
+export declare function _popErrorHandler(): void;
+export interface _SignalDebugHooks {
+    onCreate?: (signal: Signal<any>, initialValue: unknown) => void;
+    onWrite?: (signal: Signal<any>, value: unknown) => void;
+}
+/** @internal */
+export declare function _setSignalDebugHooks(hooks: _SignalDebugHooks | null): void;
+/** @internal — añade suscriptor sin reemplazar; devuelve unsubscribe. */
+export declare function _addSignalDebugHooks(hooks: _SignalDebugHooks): () => void;
+/** @internal — la nueva impl no tiene notify buffer; se expone para paridad. */
+export declare function _getNotifyBufSize(): number;
+interface ProducerNode {
+    /** Incrementa en cada cambio real de valor. */
+    version: number;
+    /**
+     * B.12.4 (durabilidad, Salsa): producer estático — nunca cambia.
+     * `link()` no crea edge: cero bookkeeping para deps estáticas.
+     */
+    durable?: boolean;
+    /** Nº de links vivos en `consumersHead` (liveness del productor). */
+    liveCount: number;
+    consumersHead: Link | null;
+}
+/**
+ * Edge compartido: vive en dos listas a la vez — la de sources del consumer
+ * (`nextSource/prevSource`) y la de consumers del producer
+ * (`nextTarget/prevTarget`). `mark` lo usa el consumer para decidir qué
+ * links sobrevivieron a la última evaluación; `linked` indica si está
+ * insertado en la lista del producer (los computeds fríos no lo están).
+ */
+interface Link {
+    source: ProducerNode;
+    target: ConsumerNode;
+    seenVersion: number;
+    mark: number;
+    linked: boolean;
+    nextSource: Link | null;
+    prevSource: Link | null;
+    nextTarget: Link | null;
+    prevTarget: Link | null;
+}
+interface ConsumerNode {
+    state: number;
+    sourcesHead: Link | null;
+    /** Contador de evaluación — marca los links usados en esta pasada. */
+    evalMark: number;
+    live(): boolean;
+}
+export declare class Signal<T> implements ProducerNode {
+    version: number;
+    liveCount: number;
+    durable: boolean;
+    consumersHead: Link | null;
+    private _v;
+    constructor(initialValue: T);
+    get value(): T;
+    set value(newValue: T);
+    update(fn: (current: T) => T): void;
+    peek(): T;
+    dispose(): void;
+}
+export declare class Computed<T> extends Signal<T> implements ConsumerNode, OwnerLike {
+    state: number;
+    sourcesHead: Link | null;
+    evalMark: number;
+    /** Último epoch en que se verificó fresco — sondeo O(1) para fríos. */
+    lastCleanEpoch: number;
+    childrenHead: (Disposable & OwnerLike) | null;
+    childCount: number;
+    nextOwned: (Disposable & OwnerLike) | null;
+    prevOwned: (Disposable & OwnerLike) | null;
+    cleanups: (() => void)[] | null;
+    parent: OwnerLike | null;
+    _value: T | undefined;
+    fn: () => T;
+    equals: (a: T, b: T) => boolean;
+    flags: number;
+    /** B.12.1: transientes del DFS de refresh (null entre refreshes). */
+    _pCursor: Link | null;
+    _pLink: Link | null;
+    constructor(fn: () => T, equals?: (a: T, b: T) => boolean);
+    live(): boolean;
+    get value(): T;
+    peek(): T;
+    dispose(): void;
+}
+export declare function signal<T>(initialValue: T): Signal<T>;
+/**
+ * B.12.4 (durabilidad): signal estática — `link()` no crea edges sobre ella,
+ * así que dependencias estáticas no cuestan bookkeeping ni checks de refresh.
+ * Escribirla rompe el contrato (warn en dev); el valor no se propaga.
+ */
+export declare function constSignal<T>(value: T): Signal<T>;
+export declare function computed<T>(fn: () => T, equals?: (a: T, b: T) => boolean): Computed<T>;
+/** Corre una vez al crear; re-corre sólo si una fuente cambió de verdad. */
+export declare function effect(fn: () => void | (() => void)): () => void;
+/**
+ * @internal — effect de render (bindings DOM internos): se encola en la
+ * cola de render, que se drena ANTES que la de user effects (B.8). La API
+ * pública `effect()` sigue siendo la de usuario.
+ */
+export declare function _renderEffect(fn: () => void | (() => void)): () => void;
+export declare function batch<T>(fn: () => T): T;
+export declare function untrack<T>(fn: () => T): T;
+export interface WatchOptions {
+    immediate?: boolean;
+    once?: boolean;
+}
+export declare function watch<T>(source: Signal<T> | (() => T), cb: (value: T, oldValue: T | undefined) => void, options?: WatchOptions): () => void;
+export declare function nextTick(fn?: () => void): Promise<void>;
+/**
+ * @internal — binding de texto especializado (C.6): `node.nodeValue` sigue
+ * `fn()` con el mínimo consumer posible. `null`/`false`/`undefined` → "".
+ * Devuelve disposer (mata la suscripción; el caller remueve el nodo).
+ */
+export declare function _bindText(node: {
+    nodeValue: string | null;
+}, fn: () => unknown): () => void;
+/**
+ * @internal — C.6 T1: suscripción directa señal→writer. El writer corre una
+ * vez al montar (valor inicial) y por cada cambio real de la señal, en la
+ * cola de render. Devuelve disposer.
+ */
+export declare function _bindSignal<T>(source: Signal<T>, write: (v: T) => void): () => void;
+/**
+ * @internal — C.7 T2: suscripción directa señal→(getter derivado)→writer.
+ * Equivale a `_bindSignal(dep, () => write(get()))` con compare incluido,
+ * pero sin el closure intermedio ni el double-compare: un solo binding.
+ * Devuelve disposer.
+ */
+export declare function _bindDerived<T>(source: Signal<unknown>, get: () => T, write: (v: T) => void): () => void;
+export {};