@actuallab/fusion 13.0.25 → 13.0.167

package/dist/index.d.ts

@@ -1,9 +1,21 @@
 import * as _actuallab_core from '@actuallab/core';
-import { IResult, EventHandlerSet, Result, AsyncContext, AsyncContextKey } from '@actuallab/core';
+import { IResult, Result, AsyncContext, AsyncContextKey, RetryDelaySeq, EventHandlerSet } from '@actuallab/core';
 
 type FusionLogScope = 'Computed' | 'ComputedRegistry' | 'ComputedState' | 'ComputeFunction' | 'MutableState' | 'State' | 'UIActionTracker' | 'UIUpdateDelayer';
 declare const getLogs: (scope: FusionLogScope) => _actuallab_core.LogScopeFns;
 
+/**
+ * Per-Computed configuration, carried by every {@link Computed} via its
+ * {@link ComputeFunction} (compute methods) or its kind's static default.
+ * The home for per-method knobs; the C# analog is `ActualLab.Fusion.ComputedOptions`.
+ */
+declare class ComputedOptions {
+    static default: ComputedOptions;
+    static mutableStateDefault: ComputedOptions;
+    readonly errorAutoInvalidateDelay: number;
+    constructor(overrides?: Partial<ComputedOptions>);
+}
+
 declare const enum ConsistencyState {
     Computing = 0,
     Consistent = 1,
@@ -11,20 +23,20 @@ declare const enum ConsistencyState {
 }
 /** Core Fusion abstraction — a cached computation with dependency tracking and invalidation. */
 declare class Computed<T> implements IResult<T> {
-    /** Delay before auto-invalidating a Computed that holds an error result. 0 = disabled. */
-    static errorAutoInvalidateDelay: number;
     /** Capture the Computed backing a computation — works with both local and RPC compute methods. */
     static capture<T>(fn: () => T | Promise<T>): Promise<Computed<T>>;
     readonly input: ComputedInput;
+    readonly options: ComputedOptions;
     private _version;
     private _state;
     private _output;
     private _invalidatePending;
+    private _errorTimer;
     private _dependencies;
     private _dependants;
-    readonly onInvalidated: EventHandlerSet<void>;
+    private _onInvalidated;
     readonly _renewer: (() => Computed<T> | Promise<Computed<T>>) | undefined;
-    constructor(input: ComputedInput, renewer?: () => Computed<T> | Promise<Computed<T>>);
+    constructor(input: ComputedInput, renewer?: () => Computed<T> | Promise<Computed<T>>, options?: ComputedOptions);
     get version(): number;
     get output(): Result<T>;
     get hasValue(): boolean;
@@ -34,6 +46,7 @@ declare class Computed<T> implements IResult<T> {
     get valueOrUndefined(): T | undefined;
     get state(): ConsistencyState;
     get isConsistent(): boolean;
+    get isComputing(): boolean;
     get dependencies(): ReadonlySet<Computed<unknown>>;
     update(): Computed<T> | Promise<Computed<T>>;
     protected _latest(): Computed<T> | undefined;
@@ -43,11 +56,13 @@ declare class Computed<T> implements IResult<T> {
     protected _register(): void;
     protected _unregister(): void;
     invalidate(): void;
+    onInvalidated(handler: () => void): void;
     whenInvalidated(abortSignal?: AbortSignal): Promise<void>;
     addDependency(dependency: Computed<unknown>): void;
 }
 /** Computed variant for State types — skips registry registration since the State holds a direct reference. */
 declare class StateBoundComputed<T> extends Computed<T> {
+    constructor(input: ComputedInput, renewer?: () => Computed<T> | Promise<Computed<T>>, options?: ComputedOptions);
     protected _latest(): Computed<T> | undefined;
     protected _register(): void;
     protected _unregister(): void;
@@ -57,9 +72,11 @@ declare class StateBoundComputed<T> extends Computed<T> {
 declare abstract class State<T> implements IResult<T> {
     protected _computed: Computed<T>;
     protected _updateIndex: number;
-    protected _lastNonErrorValue: T | undefined;
+    protected _lastNonErrorComputed: Computed<T> | undefined;
     private _whenUpdatedSource;
+    private _isDisposed;
     get updateIndex(): number;
+    get isDisposed(): boolean;
     get lastNonErrorValue(): T | undefined;
     get hasValue(): boolean;
     get hasError(): boolean;
@@ -73,10 +90,13 @@ declare abstract class State<T> implements IResult<T> {
     update(): Computed<T> | Promise<Computed<T>>;
     recompute(): Computed<T> | Promise<Computed<T>>;
     whenInvalidated(): Promise<void>;
-    whenUpdated(): Promise<void>;
+    whenUpdated(sinceIndex?: number): Promise<void>;
     whenFirstTimeUpdated(): Promise<void>;
     protected _initialize(output: Result<T> | T, renewer?: () => Computed<T> | Promise<Computed<T>>): void;
+    protected _createComputed(renewer?: () => Computed<T> | Promise<Computed<T>>): Computed<T>;
     protected _update(computed: Computed<T>, output: Result<T> | T): void;
+    protected _onDisposed(): void;
+    private static _disposedError;
 }
 
 declare function getInstanceId(instance: object): number;
@@ -88,14 +108,22 @@ declare function getInstanceId(instance: object): number;
 type ComputedInput = string | State<any>;
 
 declare const computeContextKey: AsyncContextKey<ComputeContext | undefined>;
-/** Tracks the currently executing computation and captures dependencies. */
+/**
+ * Tracks the currently executing (or captured) computation and captures dependencies.
+ * A context with a `computed` is a computing context (adds dependant edges); one without
+ * is a capture context (records the last captured Computed only — no edges).
+ */
 declare class ComputeContext {
-    readonly computed: Computed<unknown>;
+    readonly computed: Computed<unknown> | undefined;
+    readonly parent: ComputeContext | undefined;
     private _isCapturing;
-    constructor(computed: Computed<unknown>);
+    private _captured;
+    constructor(computed?: Computed<unknown>, parent?: ComputeContext);
     get isCapturing(): boolean;
+    get captured(): Computed<unknown> | undefined;
     stopCapturing(): void;
     captureDependency(dependency: Computed<unknown>): void;
+    hasKeyInChain(key: unknown): boolean;
     /** Resolve ComputeContext from an AsyncContext (or current). */
     static from(ctx: AsyncContext | undefined): ComputeContext | undefined;
 }
@@ -115,13 +143,14 @@ type ComputeFunctionImpl = (this: any, ...args: unknown[]) => unknown;
 declare class ComputeFunction {
     readonly methodName: string;
     readonly id: string;
+    readonly options: ComputedOptions;
     argToString: (arg: unknown) => string;
     private _impl;
     private _locks;
-    constructor(methodName: string, impl: ComputeFunctionImpl);
+    constructor(methodName: string, impl: ComputeFunctionImpl, options?: ComputedOptions);
     /** Build a string key for the given instance and arguments. */
     buildKey(instance: object, args: unknown[]): string;
-    invoke(instance: object, args: unknown[], prevComputed?: Computed<unknown>): Promise<Computed<unknown>>;
+    invoke(instance: object, args: unknown[]): Promise<Computed<unknown>>;
 }
 
 interface MethodMeta {
@@ -131,43 +160,67 @@ interface MethodMeta {
 }
 /** Read method metadata from a decorated class. */
 declare function getMethodsMeta(cls: abstract new (...args: any[]) => any): Record<string, MethodMeta> | undefined;
-/** Method decorator — wraps a method to route through ComputeFunction for caching and dependency tracking. */
+interface ComputeMethodOptions extends Partial<ComputedOptions> {
+    argCount?: number;
+}
+type ComputeMethodDecorator<This, Args extends unknown[], Return> = (target: (this: This, ...args: Args) => Return, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>) => (this: This, ...args: Args) => Return;
+/**
+ * Method decorator — routes a method through ComputeFunction for caching and dependency
+ * tracking. Usable bare (`@computeMethod`) or with options (`@computeMethod({ argCount })`).
+ */
 declare function computeMethod<This, Args extends unknown[], Return>(target: (this: This, ...args: Args) => Return, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>): (this: This, ...args: Args) => Return;
+declare function computeMethod<This, Args extends unknown[], Return>(options?: ComputeMethodOptions): ComputeMethodDecorator<This, Args, Return>;
 /** Wrap a standalone function as a compute function with caching and .invalidate(). */
 declare function wrapComputeMethod<Args extends unknown[], Return>(fn: (...args: Args) => Return): ((...args: Args) => Promise<Return>) & {
     invalidate: (...args: Args) => void;
 };
 
-/** Controls when state re-computation happens after invalidation. */
-type UpdateDelayer = (abortSignal?: AbortSignal) => Promise<void>;
-/** Re-computes after a fixed delay in milliseconds. */
+/** Controls when state re-computation happens after invalidation, per consecutive-error retryCount. */
+type UpdateDelayer = (retryCount: number, abortSignal?: AbortSignal) => Promise<void>;
+/** Re-computes after a fixed update delay, with RetryDelaySeq backoff for consecutive errors. */
 declare class FixedDelayer {
     static readonly zero: UpdateDelayer;
     private static _cache;
     static get(ms: number): UpdateDelayer;
     readonly ms: number;
+    readonly retryDelays: RetryDelaySeq;
+    readonly minDelay: number;
     readonly delay: UpdateDelayer;
-    constructor(ms: number);
+    constructor(ms: number, retryDelays?: RetryDelaySeq, minDelay?: number);
 }
 declare const defaultUpdateDelayer: UpdateDelayer;
 
-/** Re-computes after a fixed delay, but skips the delay when UIActionTracker is active. */
+/** Re-computes after a delay, but short-circuits while UIActionTracker enables instant updates. */
 declare class UIUpdateDelayer {
     private static _cache;
     static get(ms: number): UpdateDelayer;
+    readonly ms: number;
+    readonly retryDelays: RetryDelaySeq;
+    readonly minDelay: number;
+    readonly delay: UpdateDelayer;
+    constructor(ms: number, retryDelays?: RetryDelaySeq, minDelay?: number);
+    private _delay;
 }
 
 /** Singleton tracking active UI commands — mirrors .NET's UIActionTracker. */
 declare class UIActionTracker {
     private _activeCount;
+    private _lastResultAt;
+    private _errorTimes;
     readonly changed: EventHandlerSet<void>;
     readonly errors: unknown[];
+    instantUpdatePeriod: number;
+    maxDuplicateRecency: number;
+    maxErrors: number;
     get isActive(): boolean;
+    areInstantUpdatesEnabled(): boolean;
     /** Run a command silently — errors are added to the error list but not thrown. */
     run(fn: () => Promise<unknown>): Promise<void>;
     /** Call a command and return the result — errors are added to the error list AND thrown. */
     call<T>(fn: () => Promise<T>): Promise<T>;
     dismissError(index: number): void;
+    private _onCompleted;
+    private _addError;
 }
 declare const uiActions: UIActionTracker;
 
@@ -185,26 +238,19 @@ declare class ComputedState<T> extends State<T> {
     private _disposeController;
     private _cancelDelaySource;
     private _renewer;
-    private _hasOutput;
     constructor(computer: StateComputer<T>, options?: ComputedStateOptions<T>);
-    get hasValue(): boolean;
-    get hasError(): boolean;
-    get value(): T;
-    get error(): unknown;
-    get valueOrUndefined(): T | undefined;
-    get output(): Result<T>;
-    get computed(): Computed<T>;
-    get isDisposed(): boolean;
     dispose(): void;
     private _updateCycle;
 }
 
 /** Manually-settable reactive state that can participate in the Fusion dependency graph. */
 declare class MutableState<T> extends State<T> {
+    private _nextOutput;
     private _renewer;
     constructor(initialOutput: Result<T> | T);
     use(asyncContext?: AsyncContext): T;
     set(output: Result<T> | T): void;
+    private _wireRenewal;
 }
 
-export { ComputeContext, ComputeFunction, type ComputeFunctionImpl, Computed, type ComputedInput, ComputedRegistry, ComputedState, type ComputedStateOptions, ConsistencyState, FixedDelayer, type FusionLogScope, type MethodMeta, MutableState, State, StateBoundComputed, type StateComputer, UIActionTracker, UIUpdateDelayer, type UpdateDelayer, computeContextKey, computeMethod, defaultUpdateDelayer, getInstanceId, getLogs, getMethodsMeta, uiActions, wrapComputeMethod };
+export { ComputeContext, ComputeFunction, type ComputeFunctionImpl, type ComputeMethodOptions, Computed, type ComputedInput, ComputedOptions, ComputedRegistry, ComputedState, type ComputedStateOptions, ConsistencyState, FixedDelayer, type FusionLogScope, type MethodMeta, MutableState, State, StateBoundComputed, type StateComputer, UIActionTracker, UIUpdateDelayer, type UpdateDelayer, computeContextKey, computeMethod, defaultUpdateDelayer, getInstanceId, getLogs, getMethodsMeta, uiActions, wrapComputeMethod };