@ersbeth/picoflow 2.3.2 → 3.0.0

package/dist/index.d.ts

@@ -0,0 +1,767 @@
+/// <reference lib="esnext.disposable" preserve="true" />
+import { _ as isDisposable, a as FlowOnDataListener, c as FlowSubscribable, d as FlowEffect, f as FlowEffectOptions, g as FlowDisposable, h as ObserverStatus, i as FlowDataTracker, l as FlowTracker, m as ObservableStatus, n as FlowValue, o as FlowOnErrorListener, p as subscribe, r as FlowObservable, s as FlowOnPendingListener, t as FlowSnapshot, u as tracker } from "./shared.js";
+import { i as FlowPrimitiveOptions, n as signal, r as FlowEquals, t as FlowSignal } from "./shared2.js";
+import { n as NotPromise, r as PromiseNotAllowed, t as FlowReadonly } from "./shared3.js";
+//#region src/core/api/base/flowConfig.d.ts
+/**
+ * Installs a global handler for errors that escape the reactive flush.
+ *
+ * All reactive work — recomputing derivations, running effects — happens inside an
+ * asynchronous flush. Without this hook, an error escaping the flush (an effect callback
+ * that throws with no `onError`, or a feedback loop between two effects) becomes an
+ * uncaught exception, which terminates a Node process. Installing a handler here makes
+ * that error catchable instead.
+ *
+ * Defaults to `console.error`. The handler replaces any previously installed handler —
+ * it is not additive.
+ *
+ * @param handler - Called with the error that escaped the flush.
+ *
+ * @public
+ */
+export declare function onFlushError(handler: (error: unknown) => void): void;
+/**
+ * Returns the scheduler to its just-started state: both queues emptied, any scheduled flush
+ * cancelled, and the flush error handler back to its `console.error` default.
+ *
+ * Scheduling is process-global, so reactive work left over from one test can still be waiting when
+ * the next one starts, and a handler installed with {@link onFlushError} stays installed. Calling
+ * this from an `afterEach` gives each test a clean scheduler. It is the supported alternative to
+ * reaching into internals, and applications testing their own code need it for the same reason
+ * PicoFlow's own suite does.
+ *
+ * Queued work is **discarded, not run** — this cancels pending reactivity rather than flushing it.
+ * Primitives created before the call stay usable, but any recomputation that was waiting is lost:
+ * those nodes only recompute once something notifies them again. To let pending work complete
+ * instead, `await` a value with `pick()`.
+ *
+ * @public
+ */
+export declare function reset(): void;
+//#endregion
+//#region src/core/base/errors.d.ts
+/**
+ * Base class for picoflow's typed errors, so a consumer can `catch` one with a single
+ * `instanceof PicoFlowError` check instead of matching on message text. Every throw the library
+ * raises is one of its subclasses, and every message carries the `[PicoFlow]` prefix.
+ *
+ * It is never thrown directly: catch it to handle any picoflow failure, and narrow to a subclass to
+ * tell one kind from another.
+ * @public
+ */
+export declare class PicoFlowError extends Error {
+  constructor(message: string);
+}
+/**
+ * Thrown when a disposed primitive (or its underlying scheduler) is read, written, or otherwise
+ * used after `dispose()`.
+ * @public
+ */
+export declare class PicoFlowDisposedError extends PicoFlowError {
+  constructor(message: string);
+}
+/**
+ * Thrown when the reactive flush detects a feedback loop that exceeds the maximum step guard.
+ * @public
+ */
+export declare class PicoFlowCycleError extends PicoFlowError {
+  constructor(message: string);
+}
+/**
+ * Thrown when a node reaches a state its own implementation considers unreachable. Reaching this
+ * indicates a picoflow bug rather than a misuse of the public API.
+ * @public
+ */
+export declare class PicoFlowInternalError extends PicoFlowError {
+  constructor(message: string);
+}
+/**
+ * Thrown when a documented precondition of a public method is violated by the caller: a collection
+ * operation naming an entry that does not exist (or, for `add`, one that already does), and
+ * `from()`'s check on the value it was handed. Reaching this indicates a misuse of the API rather
+ * than a picoflow bug, and the call had no effect (#123).
+ * @public
+ */
+export declare class PicoFlowPreconditionError extends PicoFlowError {
+  constructor(message: string);
+}
+//#endregion
+//#region src/core/api/nodes/async/flowConstantAsync.d.ts
+/**
+ * Function that produces a value asynchronously, the first time it is needed.
+ *
+ * The async counterpart of {@link InitFunction}: it takes no arguments, registers no dependency and
+ * runs once. While the promise is in flight the primitive's status is `"pending"`.
+ *
+ * @public
+ */
+export type InitFunctionAsync<T> = () => Promise<T>;
+/**
+ * Read-only reactive value that resolves once from a promise or async initializer.
+ *
+ * Async constants provide lazy initialization for asynchronous values. The promise or async initializer
+ * runs once on first access, and the resolved value is cached forever. While pending, accessing the value
+ * throws PendingError. Use for async operations that only need to run once, such as loading remote configuration,
+ * fetching initial data, or computing expensive async resources.
+ *
+ * @public
+ */
+export interface FlowConstantAsync<T> extends FlowValue<T> {}
+/**
+ * Creates a constant reactive value from a promise or async initializer that resolves once and never recomputes.
+ *
+ * The promise or async initializer executes once on first access, and the resolved value is cached permanently.
+ * While the promise is pending, any reactive computation that accesses the value will receive PendingError and
+ * automatically retry once the promise resolves. Use for one-time async operations that don't depend on other
+ * reactive values, such as loading configuration or fetching initial data.
+ *
+ * @param value - Promise to resolve, or async function that returns a promise on first access
+ * @param options - Optional settings; `name` identifies this primitive in error messages, `equals` overrides the default `===` change detection
+ * @returns A FlowConstantAsync that provides read-only access to the resolved value
+ *
+ * @public
+ */
+export declare function constantAsync<T>(value: Promise<T>, options?: FlowPrimitiveOptions<NotPromise<T>>): FlowConstantAsync<T>;
+export declare function constantAsync<T>(initializer: InitFunctionAsync<T>, options?: FlowPrimitiveOptions<NotPromise<T>>): FlowConstantAsync<T>;
+//#endregion
+//#region src/core/api/nodes/async/flowDerivationAsync.d.ts
+/**
+ * Function that derives a value asynchronously from its dependencies, and optionally from the value
+ * it last produced.
+ *
+ * The async counterpart of {@link DerivationFunction}, with the same tracking rules. Read every
+ * dependency through the `tracker` *before* the first `await`: reads after it happen outside the
+ * tracked turn and register nothing.
+ *
+ * @public
+ */
+export type DerivationFunctionAsync<T> = (tracker: FlowTracker, previous?: NotPromise<T>) => Promise<T>;
+/**
+ * Read-only reactive value that recomputes asynchronously when dependencies change.
+ *
+ * Async derivations track reactive values accessed during computation and automatically recompute when any
+ * tracked dependency changes. The compute function returns a promise, and the resolved value is cached until
+ * dependencies change. While recomputing, accessing the value throws PendingError. Use for values derived from
+ * async operations like API calls, database queries, or any computation that depends on reactive state and
+ * requires async work.
+ *
+ * @public
+ */
+export interface FlowDerivationAsync<T> extends FlowValue<T> {
+  /**
+   * Forces the derivation to recompute even if dependencies haven't changed.
+   */
+  refresh(): void;
+}
+/**
+ * Creates an async derived value that automatically recomputes when dependencies change.
+ *
+ * The async compute function tracks dependencies and returns a promise. When any tracked dependency changes,
+ * the function runs again and returns a new promise. The resolved value is cached until the next change.
+ * While the promise is pending, reactive computations that access this value receive PendingError and automatically
+ * retry once resolved. Use for derived data from async sources like filtered API results or computed database queries.
+ *
+ * @param compute - Async function that accesses dependencies and returns a promise of the derived value
+ * @param options - Optional settings; `name` identifies this primitive in error messages, `equals` overrides the
+ *   default `===` change detection, `eager` recomputes on dirty instead of on read (#118)
+ * @returns A FlowDerivationAsync that provides read-only access to the resolved computed value
+ *
+ * @public
+ */
+export declare function derivationAsync<T>(compute: DerivationFunctionAsync<T>, options?: FlowPrimitiveOptions<NotPromise<T>>): FlowDerivationAsync<T>;
+//#endregion
+//#region src/core/api/nodes/async/flowStateAsync.d.ts
+/**
+ * Function that derives the next value asynchronously from the current one, for {@link FlowStateAsync.update}.
+ *
+ * `previous` is always a real value: `update()` waits for the node to settle before calling it, and
+ * never calls it while the node holds an error (A2-TYPE-1, #43).
+ *
+ * @public
+ */
+export type UpdateFunctionAsync<T> = (previous: NotPromise<T>) => Promise<T>;
+/**
+ * Writable reactive value that resolves promises and can be updated with new promises.
+ *
+ * Async state is the async equivalent of regular state. Unlike sync state, it accepts promises instead of
+ * direct values. Set new promises or async updater functions to update the state. While a promise is pending,
+ * accessing the value throws PendingError. Use for async data that changes imperatively, such as user-triggered
+ * API calls, async form submissions, or any async operation that updates based on user actions.
+ *
+ * @public
+ */
+export interface FlowStateAsync<T> extends FlowValue<T> {
+  /**
+   * Replaces the value with a new promise and notifies all dependents immediately (they receive
+   * PendingError until it resolves).
+   *
+   * A replacement never looks at the current value: it applies while the node holds an error
+   * (`set()` is how an errored state is recovered) and while a previous promise is still in
+   * flight, which is then discarded. The one case where it is held back is a node waiting on a
+   * pending dependency (an async writable derivation mid-flight): it is then applied once that
+   * computation settles, so the settling computation cannot overwrite it afterwards.
+   *
+   * @param promise - New promise to resolve
+   */
+  set(promise: Promise<T>): void;
+  /**
+   * Derives the next value from the current one and notifies all dependents immediately (they
+   * receive PendingError until the updater's promise resolves).
+   *
+   * The updater receives the *stabilised* current value: if the node has not computed yet it is
+   * computed first; if a computation or a previous `set()` is in flight, the updater waits for it
+   * and applies on its result — dependents never observe the intermediate value. Several queued
+   * updates compose in call order, and a later `set()` discards updates queued before it.
+   *
+   * An errored node is left in error and the updater is never called — deriving from a value that
+   * does not exist propagates the error; use `set()` to recover.
+   *
+   * An updater that throws does not throw back at the caller, whatever the node's status when the
+   * call was made: it fails the node with that error, which then surfaces on the next read and in
+   * `subscribe`'s `onError`. The previous value is still what `latest` reports, and a `set()`
+   * recovers the node as it does from any other failure.
+   *
+   * @param updater - Async function that receives the current value and returns a promise of the next one
+   */
+  update(updater: UpdateFunctionAsync<T>): void;
+  /**
+   * Notifies all dependents without changing the value.
+   *
+   * Every dependent is queued for the next flush and re-runs, even though `===` change detection
+   * would have found nothing to report. It is the escape hatch for a change the reactive system
+   * cannot see — a value mutated in place, or an external source the graph does not model — and
+   * `signal()` is usually the better answer to both.
+   *
+   * Declared on the writable primitives only: forcing a subtree to re-run is a write, whatever it
+   * leaves the value at, so `constant()` and `derivation()` do not carry it (A3-ARCH-1, #132). On a
+   * derivation, `refresh()` is the read-side counterpart — it recomputes, and notifies only if the
+   * result actually changed.
+   */
+  trigger(): void;
+}
+/**
+ * Creates a mutable async reactive state that resolves promises and can be updated imperatively.
+ *
+ * State can be initialized with a direct promise or a lazy async initializer function. Update the state by
+ * calling `set()` with a new promise or an async updater function. Changes propagate automatically to all
+ * reactive computations that depend on this state. Use for async data that changes through user actions or
+ * application logic, such as loading user profiles, fetching search results, or any async state updates.
+ *
+ * @param value - Initial promise to resolve, or lazy async initializer function
+ * @param options - Optional settings; `name` identifies this primitive in error messages, `equals` overrides the default `===` change detection
+ * @returns A FlowStateAsync that can be read and modified with promises
+ *
+ * @public
+ */
+export declare function stateAsync<T>(value: Promise<T>, options?: FlowPrimitiveOptions<NotPromise<T>>): FlowStateAsync<T>;
+export declare function stateAsync<T>(initializer: InitFunctionAsync<T>, options?: FlowPrimitiveOptions<NotPromise<T>>): FlowStateAsync<T>;
+//#endregion
+//#region src/core/api/nodes/async/flowWritableDerivationAsync.d.ts
+/**
+ * Writable reactive value that recomputes asynchronously when dependencies change, but can be manually overridden.
+ *
+ * Async writable derivations combine reactive async computation with manual control. They track dependencies and
+ * recompute asynchronously like regular async derivations, but you can also call `set()` to override the computed
+ * value with a new promise. While recomputing or pending, accessing the value throws PendingError. Use for computed
+ * async values that users can edit, such as formatted async fields, calculated async totals that can be adjusted,
+ * or any async value that is usually derived but sometimes needs manual correction.
+ *
+ * @public
+ */
+export interface FlowWritableDerivationAsync<T> extends FlowStateAsync<T>, FlowDerivationAsync<T> {}
+/**
+ * Creates an async derived value that recomputes automatically but can also be manually overridden.
+ *
+ * The async compute function tracks dependencies and returns a promise. When any tracked dependency changes,
+ * the function runs again and returns a new promise. However, you can also call `set()` to override the computed
+ * value with a new promise. Use for async values that are normally derived but need occasional manual adjustments,
+ * such as editable async calculated fields or user-correctable async totals.
+ *
+ * @param compute - Async function that accesses dependencies and returns a promise of the derived value
+ * @param options - Optional settings; `name` identifies this primitive in error messages, `equals` overrides the
+ *   default `===` change detection, `eager` recomputes on dirty instead of on read (#118)
+ * @returns A FlowWritableDerivationAsync that provides both reactive async computation and manual control
+ *
+ * @public
+ */
+export declare function writableDerivationAsync<T>(compute: DerivationFunctionAsync<T>, options?: FlowPrimitiveOptions<NotPromise<T>>): FlowWritableDerivationAsync<T>;
+//#endregion
+//#region src/core/api/nodes/sync/flowConstant.d.ts
+/**
+ * Function that produces a value the first time it is needed.
+ *
+ * Takes no arguments: an initializer is not a computation, so it registers no dependency and never
+ * re-runs. Use `derivation()` for a value that has to follow its sources.
+ *
+ * @public
+ */
+export type InitFunction<T> = () => NotPromise<T>;
+/**
+ * Read-only reactive value that computes once on initialization and never changes.
+ *
+ * Constants provide lazy initialization - the value isn't computed until first accessed via `get()` or `pick()`.
+ * Once computed, the value is cached forever. Use constants for expensive computations that only need to run once,
+ * such as loading configuration, computing static lookups, or initializing resources.
+ *
+ * @public
+ */
+export interface FlowConstant<T> extends FlowValue<T> {}
+/**
+ * Creates a constant reactive value that initializes lazily and never recomputes.
+ *
+ * The initializer function runs once on first access, and the result is cached permanently.
+ * Unlike state or derivations, constants never react to changes - they represent immutable values
+ * in the reactive graph. Useful for expensive one-time computations or static configuration.
+ *
+ * @param initializer - Function that computes the constant value on first access
+ * @param options - Optional settings; `name` identifies this primitive in error messages, `equals` overrides the default `===` change detection
+ * @returns A FlowConstant that provides read-only access to the cached value
+ *
+ * @public
+ */
+export declare function constant<T>(initializer: InitFunction<T>, options?: FlowPrimitiveOptions<NotPromise<T>>): FlowConstant<T>;
+//#endregion
+//#region src/core/api/nodes/sync/flowState.d.ts
+/**
+ * Function that derives the next value from the current one, for {@link FlowState.update}.
+ *
+ * `previous` is always a real value: `update()` waits for the node to settle before calling it, and
+ * never calls it while the node holds an error (A2-TYPE-1, #43).
+ *
+ * @public
+ */
+export type UpdateFunction<T> = (previous: NotPromise<T>) => NotPromise<T>;
+/**
+ * Writable reactive value that can be updated manually and notifies dependents on changes.
+ *
+ * State is the simplest writable reactive primitive. Unlike derivations, it has no dependencies and never
+ * recomputes automatically - changes only occur when you explicitly call `set()`. Use state for user input,
+ * application state, or any data that changes imperatively. Changes propagate automatically to all dependents.
+ *
+ * @public
+ */
+export interface FlowState<T> extends FlowValue<T> {
+  /**
+   * Replaces the value and notifies all dependents.
+   *
+   * A replacement never looks at the current value, so it applies even while the node holds an
+   * error — `set()` is how an errored state is recovered. It applies immediately, except when the
+   * node is waiting on a pending dependency (a writable derivation mid-flight): it is then held
+   * until that computation settles, so the settling computation cannot overwrite it afterwards.
+   * On a writable derivation that was never read, the computation runs first so its dependencies
+   * are tracked; the override still applies, until the next dependency change (#109).
+   *
+   * @param value - New value to set
+   */
+  set(value: NotPromise<T>): void;
+  /**
+   * Derives the next value from the current one and notifies all dependents.
+   *
+   * The updater receives the *stabilised* current value: if the node has not computed yet (a lazy
+   * initializer, a derivation never read) it is computed first; if a computation or a previous
+   * `set()` is in flight, the updater waits for it and applies on its result. Several queued
+   * updates compose in call order, and a later `set()` discards updates queued before it.
+   *
+   * An errored node is left in error and the updater is never called — deriving from a value that
+   * does not exist propagates the error; use `set()` to recover.
+   *
+   * An updater that throws does not throw back at the caller, whatever the node's status when the
+   * call was made: it fails the node with that error, which then surfaces on the next read and in
+   * `subscribe`'s `onError`. The previous value is still what `latest` reports, and a `set()`
+   * recovers the node as it does from any other failure.
+   *
+   * @param updater - Function that receives the current value and returns the next one
+   */
+  update(updater: UpdateFunction<T>): void;
+  /**
+   * Notifies all dependents without changing the value.
+   *
+   * Every dependent is queued for the next flush and re-runs, even though `===` change detection
+   * would have found nothing to report. It is the escape hatch for a change the reactive system
+   * cannot see — a value mutated in place, or an external source the graph does not model — and
+   * `signal()` is usually the better answer to both.
+   *
+   * Declared on the writable primitives only: forcing a subtree to re-run is a write, whatever it
+   * leaves the value at, so `constant()` and `derivation()` do not carry it (A3-ARCH-1, #132). On a
+   * derivation, `refresh()` is the read-side counterpart — it recomputes, and notifies only if the
+   * result actually changed.
+   */
+  trigger(): void;
+}
+/**
+ * Creates a mutable reactive state that can be read and updated imperatively.
+ *
+ * State can be initialized with a direct value or a lazy initializer function. Changes propagate
+ * automatically to all reactive computations that depend on this state. Use state for data that
+ * changes through user actions, external events, or application logic rather than derived computations.
+ *
+ * @param value - Initial value for the state, or lazy initializer function
+ * @param options - Optional settings; `name` identifies this primitive in error messages, `equals` overrides the default `===` change detection
+ * @returns A FlowState that can be read and modified
+ *
+ * @public
+ */
+export declare function state<T>(value: NotPromise<T>, options?: FlowPrimitiveOptions<NotPromise<T>>): FlowState<T>;
+export declare function state<T>(initializer: InitFunction<T>, options?: FlowPrimitiveOptions<NotPromise<T>>): FlowState<T>;
+//#endregion
+//#region src/core/api/nodes/collections/flowArray.d.ts
+/**
+ * Discriminated union representing all possible array mutation operations.
+ *
+ * Each mutation on a FlowArray emits an action describing what changed. This enables fine-grained
+ * reactive tracking - you can observe the array itself or subscribe to `$lastAction` to react only
+ * to specific mutations. Use this for optimized rendering, undo/redo systems, or any scenario where
+ * you need to know exactly what changed rather than just that something changed.
+ *
+ * @public
+ */
+export type FlowArrayAction<T> = {
+  type: "set";
+  setItems: T[];
+  clearedItems: T[];
+} | {
+  type: "setAt";
+  index: number;
+  setItem: T;
+  clearedItem: T | undefined;
+} | {
+  type: "push";
+  addedItem: T;
+} | {
+  type: "pop";
+  removedItem: T | undefined;
+} | {
+  type: "unshift";
+  addedItem: T;
+} | {
+  type: "shift";
+  removedItem: T | undefined;
+} | {
+  type: "splice";
+  /**
+   * The index the mutation started at. `splice()` rejects a `start` it would otherwise have to
+   * coerce or clamp, so this is both the argument it was called with and the position the store
+   * actually moved at — the two can never disagree (A3-SEC-2).
+   */
+  start: number;
+  /** How many items were removed — for the same reason, exactly the number the call asked for. */
+  deleteCount: number;
+  addedItems: T[];
+  removedItems: T[];
+} | {
+  type: "clear";
+  clearedItems: T[];
+};
+/**
+ * Reactive array with standard mutation methods and fine-grained change tracking.
+ *
+ * FlowArray behaves like a regular array but notifies dependents on mutations. It provides all standard
+ * array mutation methods (push, pop, splice, etc.) and tracks each operation via `$lastAction`, a `FlowState` holding the most recent one.
+ * Every read returns the live backing array as `readonly T[]` — a view, not a copy — so mutate it
+ * through these methods only, and spread it (`[...items]`) when you need an array of your own.
+ * This enables both coarse-grained reactivity (reacting to any change) and fine-grained reactivity (reacting
+ * only to specific mutations). Use for lists that need reactive updates, such as todo lists, data tables,
+ * or any collection that changes over time.
+ *
+ * Methods that remove entries return what they removed (`pop`, `shift`, `splice`, `clear`);
+ * methods that write return nothing. `setAt` throws when the index does not exist, while `pop` and
+ * `shift` on an empty array return `undefined`.
+ *
+ * @public
+ */
+export interface FlowArray<T> extends Omit<FlowState<readonly T[]>, "update" | "set"> {
+  /**
+   * Replaces the whole array.
+   * Emits a "set" action to $lastAction.
+   *
+   * The array is stored by reference and mutated in place by the other methods, which is why it
+   * must be a mutable array: do not keep using it yourself afterwards.
+   *
+   * @param items - The new items
+   */
+  set(items: T[]): void;
+  /**
+   * Replaces the item at a specific index.
+   * Emits a "setAt" action to $lastAction, which carries the previous item as `clearedItem`.
+   *
+   * @param index - The index of the item to replace (must exist)
+   * @param item - The new item
+   */
+  setAt(index: number, item: T): void;
+  /**
+   * Appends an item to the end of the array.
+   * Emits a "push" action to $lastAction.
+   *
+   * @param item - The item to append
+   */
+  push(item: T): void;
+  /**
+   * Removes and returns the last item from the array.
+   * Emits a "pop" action to $lastAction when an item is removed.
+   * If the array is already empty, returns undefined without notifying dependents or updating $lastAction.
+   *
+   * @returns The removed item, or undefined if the array was empty
+   */
+  pop(): T | undefined;
+  /**
+   * Inserts an item at the beginning of the array.
+   * Emits an "unshift" action to $lastAction.
+   *
+   * @param item - The item to insert
+   */
+  unshift(item: T): void;
+  /**
+   * Removes and returns the first item from the array.
+   * Emits a "shift" action to $lastAction when an item is removed.
+   * If the array is already empty, returns undefined without notifying dependents or updating $lastAction.
+   *
+   * @returns The removed item, or undefined if the array was empty
+   */
+  shift(): T | undefined;
+  /**
+   * Changes the content of the array by removing, replacing, or adding items.
+   * Emits a "splice" action to $lastAction, carrying the arguments it was called with.
+   *
+   * Both bounds must address the array as it stands, and are not coerced or clamped the way
+   * `Array.prototype.splice` coerces and clamps them: a fractional, negative or overrunning argument
+   * throws `PicoFlowPreconditionError` rather than mutating at some other index. So `splice(-1, 1)`
+   * does not count from the end — pass `items.length - 1` — and deleting to the end is
+   * `splice(start, items.length - start, …)`, not `splice(start, Infinity)`.
+   *
+   * @param start - Where to splice: an integer from 0 to the array's length inclusive (the length
+   *                itself inserts at the end)
+   * @param deleteCount - Number of items to remove: an integer from 0 to the number of items left
+   *                      after `start`
+   * @param newItems - New items to add at the start position
+   * @returns Array of removed items
+   */
+  splice(start: number, deleteCount: number, ...newItems: T[]): T[];
+  /**
+   * Removes all items from the array.
+   * Emits a "clear" action to $lastAction.
+   *
+   * @returns Array of all removed items
+   */
+  clear(): T[];
+  /**
+   * Reactive state containing the last mutation operation performed on the array.
+   * `.subscribe()` invokes its callback once per mutation (including several in the same tick).
+   * `get()` / `pick()` expose only the latest action snapshot.
+   */
+  readonly $lastAction: FlowState<FlowArrayAction<T>>;
+}
+/**
+ * Creates a reactive array with mutation methods and fine-grained action tracking.
+ *
+ * The array starts with the provided initial items (or empty if none provided). All mutation methods
+ * (push, pop, splice, etc.) notify dependents and emit detailed action information to `$lastAction`.
+ * Use the array itself for coarse-grained reactivity, or subscribe to `$lastAction` for fine-grained
+ * reactivity to specific mutation types. Useful for reactive lists, collections, or any data that
+ * needs array-like operations with automatic change propagation.
+ *
+ * @param initial - Optional initial array of items
+ * @param options - Optional settings; `name` identifies this primitive in error messages
+ * @returns A FlowArray with reactive mutation methods
+ *
+ * @public
+ */
+export declare function array<T>(initial?: T[], options?: FlowPrimitiveOptions): FlowArray<T>;
+//#endregion
+//#region src/core/api/nodes/collections/flowMap.d.ts
+/**
+ * Discriminated union representing all possible map mutation operations.
+ *
+ * Each mutation on a FlowMap emits an action describing what changed. This enables fine-grained
+ * reactive tracking - you can observe the map itself or subscribe to `$lastAction` to react only
+ * to specific mutations. Use this for optimized updates, undo/redo systems, or any scenario where
+ * you need to know exactly what changed rather than just that something changed.
+ *
+ * @public
+ */
+export type FlowMapAction<K, V> = {
+  type: "set";
+  setMap: Map<K, V>;
+  clearedMap: Map<K, V>;
+} | {
+  type: "add";
+  key: K;
+  addedValue: V;
+} | {
+  type: "setAt";
+  key: K;
+  setValue: V;
+  clearedValue: V;
+} | {
+  type: "delete";
+  key: K;
+  removedValue: V;
+} | {
+  type: "clear";
+  clearedMap: Map<K, V>;
+};
+/**
+ * Reactive map with standard mutation methods and fine-grained change tracking.
+ *
+ * FlowMap behaves like a regular Map but notifies dependents on mutations. It provides standard
+ * map operations (add, setAt, delete) and tracks each operation via `$lastAction`, a `FlowState` holding the most recent one.
+ * Every read returns the live backing map as `ReadonlyMap<K, V>` — a view, not a copy — so mutate it
+ * through these methods only, and copy it (`new Map(entries)`) when you need a map of your own.
+ * This enables both coarse-grained reactivity (reacting to any change) and fine-grained reactivity
+ * (reacting only to specific mutations). Use for key-value collections that need reactive updates,
+ * such as entity stores, lookup tables, or any map-based data that changes over time.
+ *
+ * Methods that remove entries return what they removed (`delete`, `clear`); methods that write
+ * return nothing. `add`, `setAt` and `delete` each name a key and throw when it does not exist
+ * (or, for `add`, already exists).
+ *
+ * @public
+ */
+export interface FlowMap<K, V> extends Omit<FlowState<ReadonlyMap<K, V>>, "update" | "set"> {
+  /**
+   * Replaces the whole map.
+   * Emits a "set" action to $lastAction.
+   *
+   * The map is stored by reference and mutated in place by the other methods, which is why it
+   * must be a mutable map: do not keep using it yourself afterwards.
+   *
+   * @param entries - The new entries
+   */
+  set(entries: Map<K, V>): void;
+  /**
+   * Removes a key-value pair from the map.
+   * Emits a "delete" action to $lastAction.
+   *
+   * @param key - The key to delete
+   * @returns The deleted value
+   */
+  delete(key: K): V;
+  /**
+   * Replaces the value of an existing key.
+   * Emits a "setAt" action to $lastAction, which carries the previous value as `clearedValue`.
+   *
+   * @param key - The key to replace the value of (must exist)
+   * @param value - The new value
+   */
+  setAt(key: K, value: V): void;
+  /**
+   * Adds a new key-value pair to the map.
+   * Emits an "add" action to $lastAction.
+   *
+   * @param key - The key to add (must not exist)
+   * @param value - The value to associate with the key
+   */
+  add(key: K, value: V): void;
+  /**
+   * Removes all entries from the map.
+   * Emits a "clear" action to $lastAction.
+   *
+   * @returns Map of all removed entries
+   */
+  clear(): Map<K, V>;
+  /**
+   * Reactive state containing the last mutation operation performed on the map.
+   * `.subscribe()` invokes its callback once per mutation (including several in the same tick).
+   * `get()` / `pick()` expose only the latest action snapshot.
+   */
+  readonly $lastAction: FlowState<FlowMapAction<K, V>>;
+}
+/**
+ * Creates a reactive map with mutation methods and fine-grained action tracking.
+ *
+ * The map starts with the provided initial entries (or empty if none provided). All mutation methods
+ * (add, setAt, delete) notify dependents and emit detailed action information to `$lastAction`.
+ * Use the map itself for coarse-grained reactivity, or subscribe to `$lastAction` for fine-grained
+ * reactivity to specific mutation types. Useful for entity stores, lookup tables, or any key-value
+ * data that needs reactive updates.
+ *
+ * The initial entries come either as a `Map`, whose keys are copied as they are whatever their type,
+ * or as a `Record`, which is read with `Object.entries` and therefore always yields string keys —
+ * which is why that form is constrained to `K extends string` (#124). Seed from a `Map` when the
+ * keys are numbers or symbols.
+ *
+ * @param initial - Optional initial entries: a `Map` with keys of any type, or a `Record` with
+ * string keys
+ * @param options - Optional settings; `name` identifies this primitive in error messages
+ * @returns A FlowMap with reactive mutation methods
+ *
+ * @public
+ */
+export declare function map<K extends string | number | symbol, V>(initial?: Map<K, V>, options?: FlowPrimitiveOptions): FlowMap<K, V>;
+export declare function map<K extends string, V>(initial: Record<K, V>, options?: FlowPrimitiveOptions): FlowMap<K, V>;
+//#endregion
+//#region src/core/api/nodes/sync/flowDerivation.d.ts
+/**
+ * Function that derives a value from its dependencies, and optionally from the value it last
+ * produced.
+ *
+ * Reads through the `tracker` are what register a dependency, so the set is rebuilt on every run — a
+ * source read behind a branch that did not execute is not a dependency of that run. `previous` is
+ * `undefined` on the first run, and carries the last resolved value afterwards, which is what makes
+ * a derivation the place to release a resource it created (close the previous socket before opening
+ * the next).
+ *
+ * @public
+ */
+export type DerivationFunction<T> = (tracker: FlowTracker, previous?: NotPromise<T>) => NotPromise<T>;
+/**
+ * Read-only reactive value that recomputes automatically when dependencies change.
+ *
+ * Derivations track reactive values accessed during computation and automatically recompute when any
+ * tracked dependency changes. The computed value is cached until dependencies change, avoiding unnecessary
+ * recomputations. Use derivations for values derived from other reactive state, such as filtered lists,
+ * computed properties, or aggregated data.
+ *
+ * @public
+ */
+export interface FlowDerivation<T> extends FlowValue<T> {
+  /**
+   * Forces the derivation to recompute even if dependencies haven't changed.
+   */
+  refresh(): void;
+}
+/**
+ * Creates a derived reactive value that automatically recomputes when dependencies change.
+ *
+ * The compute function runs when any tracked dependency changes, and the result is cached until the next change.
+ * Access reactive values within the compute function to establish dependencies automatically. The derivation
+ * computes lazily on first access and then reactively thereafter. Use for derived data that should stay
+ * synchronized with source state.
+ *
+ * @param compute - Function that accesses dependencies and computes the derived value
+ * @param options - Optional settings; `name` identifies this primitive in error messages, `equals` overrides the
+ *   default `===` change detection, `eager` recomputes on dirty instead of on read (#118)
+ * @returns A FlowDerivation that provides read-only access to the computed value
+ *
+ * @public
+ */
+export declare function derivation<T>(compute: DerivationFunction<T>, options?: FlowPrimitiveOptions<NotPromise<T>>): FlowDerivation<T>;
+//#endregion
+//#region src/core/api/nodes/sync/flowWritableDerivation.d.ts
+/**
+ * Writable reactive value that recomputes automatically when dependencies change, but can be manually overridden.
+ *
+ * Writable derivations combine reactive computation with manual control. They track dependencies and recompute
+ * like regular derivations, but you can also call `set()` to override the computed value temporarily. Use this
+ * for computed values that users can edit, such as formatted fields, calculated totals that can be adjusted,
+ * or any value that is usually derived but sometimes needs manual correction.
+ *
+ * @public
+ */
+export interface FlowWritableDerivation<T> extends FlowState<T>, FlowDerivation<T> {}
+/**
+ * Creates a derived value that recomputes automatically but can also be manually overridden.
+ *
+ * The compute function tracks dependencies and recomputes when they change, just like a regular derivation.
+ * However, you can also call `set()` to override the computed value. Use this for values that are normally
+ * derived but need occasional manual adjustments, such as editable calculated fields or user-correctable totals.
+ *
+ * @param compute - Function that accesses dependencies and computes the derived value
+ * @param options - Optional settings; `name` identifies this primitive in error messages, `equals` overrides the
+ *   default `===` change detection, `eager` recomputes on dirty instead of on read (#118)
+ * @returns A FlowWritableDerivation that provides both reactive computation and manual control
+ *
+ * @public
+ */
+export declare function writableDerivation<T>(compute: DerivationFunction<T>, options?: FlowPrimitiveOptions<NotPromise<T>>): FlowWritableDerivation<T>;
+//#endregion
+export { FlowDataTracker, FlowDisposable, FlowEffect, FlowEffectOptions, FlowEquals, FlowObservable, FlowOnDataListener, FlowOnErrorListener, FlowOnPendingListener, FlowPrimitiveOptions, FlowReadonly, FlowSignal, FlowSnapshot, FlowSubscribable, FlowTracker, FlowValue, NotPromise, type ObservableStatus, type ObserverStatus, PromiseNotAllowed, isDisposable, signal, subscribe, tracker };