@ersbeth/picoflow 2.3.1 → 3.0.0

package/dist/shared.d.ts

@@ -0,0 +1,361 @@
+//#region src/core/api/base/flowDisposable.d.ts
+/**
+ * Contract for resources that can be explicitly released to prevent memory leaks.
+ *
+ * All reactive primitives in PicoFlow implement this interface, allowing manual cleanup of subscriptions
+ * and dependencies. Once disposed, the resource cannot be reused: reads and mutations throw, while
+ * `dispose()` itself is idempotent.
+ * Call `dispose()` when you no longer need a reactive primitive to free its resources.
+ *
+ * To ask whether something has been released, read its `status` — `"disposed"` on a value, signal or
+ * collection, and on the effect returned by `subscribe()`. There is no separate `disposed` flag: one
+ * piece of state with two spellings is what A1-L8 removed. `status` is declared by those interfaces
+ * rather than by this one, which every disposable implements — including `FlowTracker`, which has no
+ * status to report.
+ *
+ * Extends the standard `Disposable` protocol, so every primitive works with `using` (A2-ARCH-2).
+ * Note that this covers the primitives, not everything in the library that can be released: the
+ * handle returned by `enableTrace()` has a `dispose()` but does not implement the protocol, so
+ * `isDisposable()` accepts it while `using` does not.
+ *
+ * @public
+ */
+interface FlowDisposable extends Disposable {
+  /**
+   * Releases all resources held by this disposable object.
+   *
+   * Cleans up all subscriptions, dependencies, and internal state. After calling this method, the
+   * resource enters a disposed state and cannot be reused: subsequent reads and mutations throw,
+   * and its `status` reads `"disposed"`. Disposal itself is idempotent — calling this a second
+   * time is a no-op — so a teardown path needs no guard. This method should be called when you no
+   * longer need the reactive primitive, to prevent memory leaks.
+   *
+   * Primitives also implement the standard `Disposable` protocol, so a primitive whose lifetime
+   * matches a block can be declared with `using` and released automatically on exit.
+   */
+  dispose(): void;
+}
+/**
+ * Type guard to check if an object implements the FlowDisposable interface.
+ *
+ * Useful for conditionally disposing objects that may or may not be disposable,
+ * such as when cleaning up mixed collections of values. Returns true if the object
+ * has a `dispose` method, providing type-safe access to disposal functionality.
+ *
+ * @param obj - The object to check
+ * @returns True if the object implements FlowDisposable, false otherwise
+ *
+ * @public
+ */
+declare function isDisposable(obj: unknown): obj is FlowDisposable;
+//#endregion
+//#region src/core/base/observer.d.ts
+/**
+ * Lifecycle of an observer: idle (has run, nothing pending), queued (a dependency changed and the
+ * next flush will run it), or disposed (released).
+ *
+ * Deliberately distinct from {@link ObservableStatus} rather than shared with it: `resolved`,
+ * `pending`, `error` and `dirty` describe the state of a *computed value*, and an effect has no
+ * value — reusing them would name states that do not exist here (A2-ARCH-11).
+ *
+ * @public
+ */
+type ObserverStatus = "idle" | "queued" | "disposed";
+//#endregion
+//#region src/core/base/observable.d.ts
+/**
+ * Status of an observable: resolved (has value), pending (async in progress), error (failed), dirty
+ * (needs recomputation), or disposed (released — the getter reports this instead of throwing, so a
+ * debugger or a `console.log` can inspect a released primitive, A2-ARCH-2).
+ *
+ * `disposed` is never stored in `_status`; it is derived by the `status` getter from the disposal
+ * flag, so every read path that guards on disposal before switching on the status cannot observe it.
+ */
+type ObservableStatus = "resolved" | "pending" | "error" | "dirty" | "disposed";
+//#endregion
+//#region src/core/api/nodes/flowEffect.d.ts
+/**
+ * Options accepted when creating an effect.
+ *
+ * Deliberately not `FlowPrimitiveOptions`: `equals` and `eager` describe how a *value* is computed
+ * and compared, and an effect has no value — offering them here would name settings that do nothing.
+ *
+ * @public
+ */
+interface FlowEffectOptions {
+  /**
+   * Name for this effect, used wherever it has to be identified: the disposed-effect error, and
+   * introspection dumps, where an unnamed effect can only be labelled `effect#12` (#50).
+   *
+   * An effect is the node this matters most for. A value primitive can often be recognised from
+   * its value, while every effect looks alike from the outside — so naming the ones an
+   * application keeps for its lifetime is what makes a dump readable.
+   */
+  name?: string;
+}
+/**
+ * Handle to a reactive effect that automatically tracks dependencies and re-executes when they change.
+ *
+ * Effects run immediately upon creation and then reactively respond to changes in any reactive values
+ * accessed during execution. Call `dispose()` to stop the effect and clean up its subscriptions.
+ *
+ * @public
+ */
+interface FlowEffect extends FlowDisposable {
+  /**
+   * Reports where this effect stands: `"idle"` once it has run with nothing pending, `"queued"`
+   * between a dependency change and the flush that re-runs it, or `"disposed"` once released.
+   *
+   * Reading it never throws, so it is safe from a debugger or a `console.log` on a disposed
+   * effect. Note that writes are flushed in a later task, so an effect observed immediately
+   * after a dependency write reads `"queued"`, not `"idle"` (A2-ARCH-11).
+   */
+  get status(): ObserverStatus;
+}
+/**
+ * Creates a reactive effect that runs immediately and automatically re-runs when dependencies change.
+ *
+ * The effect function tracks any reactive values accessed and subscribes to their changes.
+ * When any tracked value changes, the effect re-executes with the new values.
+ * Optional callbacks handle errors and pending async states.
+ *
+ * @param data - Function that accesses reactive dependencies and returns data
+ * @param onData - Callback invoked with the computed data on each execution
+ * @param onError - Optional callback for handling errors during execution
+ * @param onPending - Optional callback invoked when async dependencies are pending
+ * @param options - Optional settings; `name` identifies the effect in errors and inspection dumps
+ * @returns A FlowEffect handle with a `dispose()` method to stop the effect
+ *
+ * @public
+ */
+declare function subscribe<T>(data: FlowDataTracker<T>, onData: FlowOnDataListener<T>, onError?: FlowOnErrorListener, onPending?: FlowOnPendingListener, options?: FlowEffectOptions): FlowEffect;
+//#endregion
+//#region src/core/api/base/flowTracker.d.ts
+/**
+ * The brand that makes {@link FlowTracker} nominal. Declared, never defined: it has no runtime
+ * existence, and no value can be produced for it outside this library (A2-TYPE-3).
+ *
+ * This symbol must SHIP in the declarations even though it is not part of the documented API. Tag it
+ * for internal-stripping and `stripInternal` deletes this line while leaving the `[tracker]`
+ * reference in {@link FlowTracker} behind, so every consumer gets a `TS2304: Cannot find name`
+ * error and the whole public surface fails to type-check. `@hidden` keeps it out of the
+ * generated documentation without touching the emit, which is all that was wanted.
+ *
+ * Note the wording above avoids spelling that tag out: `stripInternal` matches the tag anywhere in a
+ * doc comment, so even prose explaining its absence is enough to trigger it.
+ *
+ * @hidden
+ */
+declare const tracker: unique symbol;
+/**
+ * Contract for reactive computations that track dependencies and react to changes in the reactivity graph.
+ *
+ * Opaque: a tracker is obtained, never constructed. The only one that exists is the `t` passed to a
+ * derivation, computation or effect callback, and passing it to `get(t)` is what registers the
+ * dependency edge. An opaque brand makes that a type-level fact rather than a convention — an object
+ * that merely looks like a tracker is rejected, where this interface was previously empty and so
+ * accepted anything disposable (A2-TYPE-3).
+ *
+ * This is a compile-time closure only. The runtime still calls whatever `registerDependency` it is
+ * handed, so a duck-typed tracker keeps working as A2-RT-3 measured; it simply no longer type-checks.
+ *
+ * @public
+ */
+interface FlowTracker extends FlowDisposable {
+  /**
+   * The brand itself. Carries no information — its presence is the whole point, and the prose above
+   * is what a reader needs — so it is kept out of the generated reference rather than rendering as
+   * an undescribed property a consumer might try to supply.
+   *
+   * @hidden
+   */
+  readonly [tracker]: true;
+}
+//#endregion
+//#region src/core/api/base/flowSubscribable.d.ts
+/**
+ * Function that tracks reactive dependencies and returns data.
+ *
+ * This function is called during effect execution with a tracker parameter that automatically
+ * records any reactive values accessed. The tracker enables automatic dependency tracking without
+ * explicit subscriptions. The returned data is passed to the `onData` callback.
+ *
+ * @param t - Tracker object that records dependencies when reactive values are accessed
+ * @returns The computed data of type T
+ *
+ * @public
+ */
+type FlowDataTracker<T> = (t: FlowTracker) => T;
+/**
+ * Callback invoked when new data is available.
+ *
+ * This callback runs each time the effect executes successfully, receiving the data returned
+ * by the tracker function. It's called immediately on effect creation and then on every reactive
+ * re-execution. Use this callback to perform side effects with the computed data.
+ *
+ * @param data - The computed data from the tracker function
+ * @returns Always returns undefined (callbacks are for side effects)
+ *
+ * @public
+ */
+type FlowOnDataListener<T> = (data: T) => void;
+/**
+ * Callback invoked when an error occurs during effect execution.
+ *
+ * If provided, this callback handles any errors thrown by the tracker function (except PendingError).
+ * Without this callback, errors propagate and may crash the application. Use this for error logging,
+ * recovery, or user feedback. The effect remains active and will retry on the next reactive trigger.
+ *
+ * @param error - The error that occurred, always normalized to an Error instance
+ * @returns Always returns undefined (callbacks are for side effects)
+ *
+ * @public
+ */
+type FlowOnErrorListener = (error: Error) => void;
+/**
+ * Callback invoked when an async computation is pending.
+ *
+ * This callback is triggered when the tracker function throws a PendingError, indicating that
+ * async dependencies are still resolving. Use this to show loading states or pending indicators.
+ * The effect will automatically re-execute once the async values settle.
+ *
+ * @returns Always returns undefined (callbacks are for side effects)
+ *
+ * @public
+ */
+type FlowOnPendingListener = () => void;
+/**
+ * Contract for observables that can be subscribed to with lifecycle callbacks.
+ *
+ * This interface enables imperative subscription to reactive values, allowing manual control over
+ * when effects run. The subscribe method returns a disposal function to stop the subscription.
+ * Useful for integrating with non-reactive code or frameworks that manage subscriptions differently.
+ *
+ * @public
+ */
+interface FlowSubscribable<T> {
+  /**
+   * Subscribes to this observable with lifecycle callbacks.
+   *
+   * Creates an active subscription that executes immediately and then re-executes whenever
+   * the observable's dependencies change. The subscription remains active until the returned
+   * disposal function is called. The `onData` callback receives the computed value, while
+   * `onError` handles errors and `onPending` signals async operations in progress.
+   *
+   * @param onData - Callback invoked with the computed data on each execution
+   * @param onError - Optional callback for handling errors during execution
+   * @param onPending - Optional callback invoked when async dependencies are pending
+   * @param options - Optional settings; `name` identifies the resulting effect in errors and
+   * inspection dumps
+   * @returns A function to dispose the subscription and stop receiving updates
+   */
+  subscribe(onData: FlowOnDataListener<T>, onError?: FlowOnErrorListener, onPending?: FlowOnPendingListener, options?: FlowEffectOptions): FlowEffect;
+}
+//#endregion
+//#region src/core/api/base/flowObservable.d.ts
+/**
+ * Contract for reactive primitives that emit changes and notify their dependents in the reactivity graph.
+ * @public
+ */
+interface FlowObservable<T> extends FlowDisposable, FlowSubscribable<T> {
+  /**
+   * Reports where this primitive stands: `"resolved"` when it holds a value, `"pending"` while an
+   * async computation is in flight, `"error"` when the last computation threw, `"dirty"` when it
+   * needs recomputing, or `"disposed"` once released.
+   *
+   * Reading it never throws, so it is safe from a debugger or a `console.log` on a disposed
+   * primitive — and it is how you ask whether something has been released (A2-ARCH-2, A1-L8).
+   * A value read alongside a status of `"pending"` or `"dirty"` is a stale cache, not the
+   * current value.
+   */
+  get status(): ObservableStatus;
+  /**
+   * Establishes a reactive dependency without reading the value.
+   *
+   * Registers this observable as a dependency of the given tracker, allowing it to be notified
+   * when changes occur. This enables dependency tracking without accessing the actual value.
+   *
+   * @param tracker - Tracker that records this observable as a dependency
+   */
+  watch(tracker: FlowTracker): void;
+}
+//#endregion
+//#region src/core/api/nodes/flowValue.d.ts
+/**
+ * A synchronous, passive snapshot of a {@link FlowValue}, discriminated on its `status`
+ * (A2-ARCH-10, #80).
+ *
+ * `data` exists only when the status is `"resolved"`: in any other state the cached value is stale or
+ * absent and reading it without its status would be misleading, so the snapshot carries the status
+ * alone — plus the `error` when the last computation threw. Narrow on `status` to reach `data`:
+ *
+ * ```ts
+ * const snapshot = $user.value;
+ * if (snapshot.status === "resolved") render(snapshot.data);
+ * ```
+ *
+ * @public
+ */
+type FlowSnapshot<T> = {
+  status: "resolved";
+  data: T;
+} | {
+  status: "error";
+  error: Error;
+} | {
+  status: Exclude<ObservableStatus, "resolved" | "error">;
+};
+/**
+ * Base interface for reactive values that can be read synchronously or asynchronously.
+ *
+ * FlowValue extends FlowObservable with methods to access the current value. Use `get()` to read
+ * the value reactively (establishing a dependency), or `pick()` to read it non-reactively. All
+ * value-based primitives (state, derivation, constant, and their async variants) implement this
+ * interface, providing a consistent API for value access across the reactive system.
+ *
+ * @public
+ */
+interface FlowValue<T> extends FlowObservable<T> {
+  /**
+   * Gets the current value and establishes a reactive dependency.
+   *
+   * When called from within a reactive computation, this method registers the value as a dependency,
+   * ensuring the computation re-executes when the value changes. The value is computed on first access
+   * (if lazy) and then cached. For async values, throws PendingError while the value is resolving.
+   *
+   * @param tracker - Tracker that records this value as a dependency
+   * @returns The current value
+   */
+  get(tracker: FlowTracker): T;
+  /**
+   * Asynchronously gets the current value without establishing a reactive dependency.
+   *
+   * This method reads the value non-reactively, meaning it won't trigger re-execution of the calling
+   * computation when the value changes. The value is computed on first access (if lazy) and then cached.
+   * For async values, the promise resolves once the value is available.
+   *
+   * @returns Promise that resolves with the current value
+   */
+  pick(): Promise<T>;
+  /**
+   * Synchronous, passive snapshot of this value: its current {@link FlowObservable.status}, with
+   * `data` only when resolved and `error` only when the last computation threw.
+   *
+   * Reading it never computes a lazy derivation, never throws — not even on a disposed primitive —
+   * and never registers a dependency. It is the read meant for an event handler, a debugger or a
+   * dev panel that wants to look without taking part in the graph; use {@link get} to depend on the
+   * value and {@link pick} to wait for it (A2-ARCH-10, #80).
+   */
+  get value(): FlowSnapshot<T>;
+  /**
+   * The last resolved value, or `undefined` if none was ever computed — regardless of the current
+   * status. Like {@link value}, it never computes, throws or tracks.
+   *
+   * This is deliberately a stale read: while the status is `"pending"` or `"dirty"` it still
+   * returns the previous value, which is what a stale-while-revalidate display wants. Check
+   * {@link FlowObservable.status} (or read {@link value}) whenever freshness matters (A2-ARCH-10, #80).
+   */
+  get latest(): T | undefined;
+}
+//#endregion
+export { isDisposable as _, FlowOnDataListener as a, FlowSubscribable as c, FlowEffect as d, FlowEffectOptions as f, FlowDisposable as g, ObserverStatus as h, FlowDataTracker as i, FlowTracker as l, ObservableStatus as m, FlowValue as n, FlowOnErrorListener as o, subscribe as p, FlowObservable as r, FlowOnPendingListener as s, FlowSnapshot as t, tracker as u };