@ersbeth/picoflow 1.0.0 → 1.1.0

package/dist/types/flow/base/flowDisposable.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Contract for objects that own resources and must be cleaned up explicitly.
+ *
+ * @remarks
+ * Many PicoFlow primitives expose `dispose()` so you can tear down subscriptions,
+ * listeners, or reactive links when they are no longer needed (e.g., component
+ * unmount, feature teardown, test cleanup).
+ *
+ * Typical options:
+ * - `{ self: true }` — dispose only this instance (dependents decide their own lifecycle).
+ * - `{ self: false }` or omitted — also dispose dependents, if the implementation supports it.
+ *
+ * The exact cascade behavior depends on the concrete primitive; consult its docs.
+ *
+ * @example
+ * ```typescript
+ * const $state = state(0);
+ * const fx = effect((t) => console.log($state.get(t)));
+ *
+ * $state.dispose();          // Common teardown path
+ * $state.dispose({ self: true }); // Dispose only this instance if you want dependents to persist
+ * ```
+ *
+ * @public
+ */
+export interface FlowDisposable {
+    /**
+     * Disposes resources held by this object.
+     *
+     * @param options - Optional disposal behavior.
+     * @param options.self - When true, dispose only this object. When false or
+     * omitted, the implementation may also dispose dependents.
+     *
+     * @remarks
+     * Use `dispose()` during teardown (unmount, test cleanup, feature shutdown).
+     * Calling `dispose()` more than once may throw; behavior is defined by the
+     * concrete implementation.
+     *
+     * @throws Error if the object has already been disposed (implementation-specific).
+     */
+    dispose(options?: {
+        self: boolean;
+    }): void;
+}
+/**
+ * Runtime type guard that checks whether an object is disposable.
+ *
+ * @param obj - Value to test.
+ * @returns `true` if `obj` exposes a callable `dispose`; otherwise `false`.
+ *
+ * @remarks
+ * Use this for defensive cleanup in mixed collections or optional resources.
+ * It performs a runtime shape check; no assumptions about specific types are made.
+ *
+ * @example
+ * ```typescript
+ * function cleanup(items: unknown[]) {
+ *   for (const item of items) {
+ *     if (isDisposable(item)) item.dispose();
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isDisposable(obj: unknown): obj is FlowDisposable;
+//# sourceMappingURL=flowDisposable.d.ts.map

package/dist/types/flow/base/flowDisposable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowDisposable.d.ts","sourceRoot":"","sources":["../../../../src/flow/base/flowDisposable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAMhE"}

package/dist/types/flow/base/flowEffect.d.ts

@@ -0,0 +1,127 @@
+import { FlowTracker } from './flowTracker';
+/**
+ * Runs side-effect code in response to reactive state changes.
+ *
+ * @remarks
+ * A `FlowEffect` is the bridge between reactive data and the outside world
+ * (UI updates, logging, network calls, timers, etc.). It executes a callback
+ * with a tracking context so you can choose which observables/signals should
+ * re-trigger the effect:
+ *
+ * - Use `observable.get(t)` or `signal.watch(t)` to create dependencies.
+ * - Use `observable.pick()` for untracked reads that should not re-run the effect.
+ *
+ * The callback runs immediately when the effect is created and re-runs whenever
+ * any tracked dependency changes. The effect itself is the tracking context
+ * (it implements `FlowTracker`), so `t` in your callback is the effect instance.
+ *
+ * Async callbacks are supported: if the callback returns a promise, the effect
+ * awaits it before finishing the current run. A later change can re-run the
+ * effect even if a previous async run is still pending, so write idempotent
+ * side effects when working with async flows.
+ *
+ * @example
+ * ```typescript
+ * // Mixed tracked/untracked reads
+ * const fx = effect((t) => {
+ *   const tracked = $stateA.get(t);   // tracked -> re-runs when $stateA changes
+ *   const snapshot = $config.pick();  // untracked -> does not re-run on changes
+ *   console.log(tracked, snapshot);
+ * });
+ *
+ * // Async work
+ * const fxAsync = effect(async (t) => {
+ *   const userId = $userId.get(t);
+ *   const profile = await fetchProfile(userId);
+ *   renderProfile(profile);
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare class FlowEffect {
+    private _disposed;
+    private _dependencies;
+    private _apply;
+    settled: Promise<void>;
+    /**
+     * Creates a new effect and runs it once immediately.
+     *
+     * @param apply - Side-effect function receiving the tracking context (`t`).
+     * It can be sync or async (returning `Promise<void>`).
+     *
+     * @remarks
+     * Use `t` to opt-in to reactive tracking:
+     * - `observable.get(t)` / `signal.watch(t)` to re-run when they change
+     * - `observable.pick()` for reads that should not re-run the effect
+     *
+     * The effect schedules its first run during construction. Each subsequent
+     * change to a tracked dependency queues another run.
+     *
+     * @public
+     */
+    constructor(apply: (t: FlowTracker) => void | Promise<void>);
+    /**
+     * Stops the effect and detaches it from all tracked dependencies.
+     *
+     * @remarks
+     * Call this when the effect's work is no longer needed (e.g., component
+     * unmount, teardown of a feature). After disposal:
+     * - The effect will not re-run.
+     * - All dependency links are removed.
+     * - Calling `dispose()` again throws an error.
+     *
+     * @example
+     * ```typescript
+     * const fx = effect((t) => $signal.watch(t));
+     * // ... later
+     * fx.dispose();
+     * ```
+     *
+     * @public
+     */
+    dispose(): void;
+    /**
+     * Whether the effect has been disposed.
+     *
+     * @returns `true` once disposal has run; `false` while the effect is active.
+     *
+     * @public
+     */
+    get disposed(): boolean;
+    private _exec;
+}
+/**
+ * Creates a reactive effect that runs now and re-runs when its tracked
+ * dependencies change.
+ *
+ * @param fn - Side-effect function that receives the tracking context (`t`).
+ * @returns A new {@link FlowEffect}.
+ *
+ * @remarks
+ * Use an effect when you need to react to state changes with side effects
+ * (UI updates, logging, network calls, timers). For computing derived values,
+ * prefer derivations; for one-off work, use a normal function.
+ *
+ * - Track dependencies with `observable.get(t)` or `signal.watch(t)`.
+ * - Read without tracking using `observable.pick()`.
+ * - Async callbacks are supported; return a promise if you `await` inside.
+ *
+ * @example
+ * ```typescript
+ * const $count = state(0);
+ *
+ * const fx = effect((t) => {
+ *   console.log("Count is:", $count.get(t));
+ * });
+ *
+ * $count.set(1); // Logs "Count is: 1"
+ * $count.set(2); // Logs "Count is: 2"
+ *
+ * fx.dispose();  // Stop reacting
+ * ```
+ *
+ * @public
+ */
+export declare function effect(fn: (t: FlowTracker) => void): FlowEffect;
+//# sourceMappingURL=flowEffect.d.ts.map

package/dist/types/flow/base/flowEffect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowEffect.d.ts","sourceRoot":"","sources":["../../../../src/flow/base/flowEffect.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,UAAU;IACtB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,MAAM,CAA2C;IACzD,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;;;;;;;;;;;;OAeG;gBACS,KAAK,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3D;;;;;;;;;;;;;;;;;;OAkBG;IACI,OAAO,IAAI,IAAI;IAQtB;;;;;;OAMG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;YAiBa,KAAK;CAUnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,UAAU,CAE/D"}

package/dist/types/flow/base/flowGraph.d.ts

@@ -0,0 +1,97 @@
+import { FlowEffect } from './flowEffect';
+/**
+ * Coordinates reactive operations (reads, writes, triggers, effects).
+ *
+ * @remarks
+ * FlowGraph manages the execution order of reactive operations to ensure
+ * consistent state updates. It queues operations and processes them in a
+ * controlled sequence, executing effects after state changes complete.
+ *
+ * Most users will not interact with FlowGraph directly; reactive primitives
+ * use it internally. The `clear()` method may be useful for testing scenarios
+ * where you need to reset the internal state between tests.
+ *
+ * @public
+ */
+export declare class FlowGraph {
+    private static _effectsQueue;
+    private static _actionQueue;
+    private static _processingActionQueue;
+    /**
+     * Resets all internal queues and processing state.
+     *
+     * @remarks
+     * Use this method primarily for testing scenarios where you need to ensure
+     * a clean state between test runs. It clears pending effects and queued
+     * operations.
+     *
+     * @example
+     * ```typescript
+     * beforeEach(() => {
+     *   FlowGraph.clear();
+     * });
+     * ```
+     *
+     * @public
+     */
+    static clear(): void;
+    /**
+     * Queues a trigger notification for processing.
+     *
+     * @param notify - Function to call when the trigger is processed.
+     * @returns A promise that resolves after the trigger is processed.
+     *
+     * @remarks
+     * This method is used internally by reactive primitives to coordinate
+     * signal triggers. The promise resolves after all associated effects
+     * have been executed.
+     *
+     * @public
+     */
+    static requestTrigger(notify: () => void): Promise<void>;
+    /**
+     * Queues a read operation for processing.
+     *
+     * @param read - Function that performs the read operation.
+     * @returns A promise that resolves with the read value.
+     *
+     * @remarks
+     * This method is used internally by reactive primitives to coordinate
+     * read operations. The read function is executed and its result (or promise)
+     * is returned.
+     *
+     * @public
+     */
+    static requestRead<T>(read: () => T | Promise<T>): Promise<T>;
+    /**
+     * Queues a write operation with update logic for processing.
+     *
+     * @param notify - Function to call if the update succeeds.
+     * @param update - Function that performs the update and returns whether
+     * it changed the value.
+     * @returns A promise that resolves after the write is processed.
+     *
+     * @remarks
+     * This method is used internally by reactive primitives to coordinate
+     * write operations. The update function is executed, and if it returns true
+     * (or a promise resolving to true), the notify function is called to
+     * trigger dependent effects.
+     *
+     * @public
+     */
+    static requestWrite(notify: () => void, update: () => boolean | Promise<boolean>): Promise<void>;
+    /**
+     * Queues effects for execution after the current operation completes.
+     *
+     * @param effects - Array of effects to queue for execution.
+     *
+     * @remarks
+     * This method is used internally by reactive primitives to schedule effect
+     * execution. Effects are executed after the current read/write/trigger
+     * operation completes, ensuring proper ordering of reactive updates.
+     *
+     * @public
+     */
+    static pushEffects(effects: FlowEffect[]): void;
+}
+//# sourceMappingURL=flowGraph.d.ts.map

package/dist/types/flow/base/flowGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowGraph.d.ts","sourceRoot":"","sources":["../../../../src/flow/base/flowGraph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAmE/C;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAS;IACrB,OAAO,CAAC,MAAM,CAAC,aAAa,CAAoB;IAChD,OAAO,CAAC,MAAM,CAAC,YAAY,CAAuB;IAClD,OAAO,CAAC,MAAM,CAAC,sBAAsB,CAAS;IAE9C;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;IAMpB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxD;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAW7D;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,YAAY,CAClB,MAAM,EAAE,MAAM,IAAI,EAClB,MAAM,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC;IAYhB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,IAAI;CAuF/C"}

package/dist/types/flow/base/flowSignal.d.ts

@@ -0,0 +1,134 @@
+import { FlowDisposable } from './flowDisposable';
+import { FlowEffect } from './flowEffect';
+import { FlowTracker } from './flowTracker';
+/**
+ * Event-like reactive primitive with no payload.
+ *
+ * @remarks
+ * A signal is used to broadcast that “something happened” (refresh, invalidate,
+ * notify). It does not carry data; it only notifies dependents that they should
+ * react. Track it with `watch(t)` inside an effect or derivation to re-run when
+ * the signal is triggered.
+ *
+ * Signals can be triggered and disposed. Once disposed, further interaction
+ * throws an error.
+ *
+ * @public
+ */
+export declare class FlowSignal implements FlowDisposable, FlowTracker {
+    /**
+     * Triggers the signal and notifies all dependents.
+     *
+     * @remarks
+     * Any effect/derivation that called `watch(t)` on this signal will re-run.
+     * Returns a promise that settles after notifications complete.
+     *
+     * @throws Error if the signal is disposed.
+     *
+     * @example
+     * ```typescript
+     * const $tick = signal();
+     *
+     * effect((t) => {
+     *   $tick.watch(t);
+     *   console.log("tick");
+     * });
+     *
+     * $tick.trigger(); // logs "tick"
+     * ```
+     *
+     * @public
+     */
+    trigger(): Promise<void>;
+    /**
+     * Registers this signal as a dependency in the current tracking context.
+     *
+     * @param context - The tracking context (`t`) provided to effects/derivations.
+     *
+     * @remarks
+     * Signals have no value to read; calling `watch(t)` simply means “re-run me
+     * when this signal is triggered.” Call this inside an effect/derivation
+     * callback where a tracking context is available.
+     *
+     * @throws Error if the signal has been disposed.
+     *
+     * @example
+     * ```typescript
+     * const $refresh = signal();
+     *
+     * effect((t) => {
+     *   $refresh.watch(t);
+     *   console.log("refresh triggered");
+     * });
+     *
+     * $refresh.trigger(); // logs "refresh triggered"
+     * ```
+     *
+     * @public
+     */
+    watch(caller: FlowTracker): void;
+    /**
+     * Disposes the signal and cleans up its dependencies/listeners.
+     *
+     * @remarks
+     * After disposal the signal must not be used; calling `trigger` or `watch`
+     * will throw. If `options?.self` is true, only this signal is disposed; when
+     * false or omitted, dependents may also be disposed depending on the
+     * implementation.
+     *
+     * @throws Error if the signal is already disposed.
+     *
+     * @example
+     * ```typescript
+     * const $refresh = signal();
+     * // ... use it
+     * $refresh.dispose();
+     * ```
+     *
+     * @public
+     */
+    dispose(options?: {
+        self: boolean;
+    }): void;
+    /**
+     * Whether the signal has been disposed.
+     *
+     * @returns `true` if disposed; `false` while active.
+     *
+     * @remarks Use to guard operations or avoid double disposal.
+     *
+     * @public
+     */
+    get disposed(): boolean;
+    protected _disposed: boolean;
+    protected _dependencies: Set<FlowSignal>;
+    protected _listeners: Set<FlowSignal>;
+    protected _effects: Set<FlowEffect>;
+    protected _notify(): void;
+}
+/**
+ * Creates a new signal for event-like notifications.
+ *
+ * @returns A new instance of {@link FlowSignal}.
+ *
+ * @remarks
+ * Use signals to announce “something happened” when no payload is needed. Track
+ * them with `watch(t)` inside effects/derivations and trigger them to re-run
+ * dependents.
+ *
+ * @example
+ * ```typescript
+ * const $ready = signal();
+ *
+ * effect((t) => {
+ *   $ready.watch(t);
+ *   console.log("ready!");
+ * });
+ *
+ * $ready.trigger(); // logs "ready!"
+ * ```
+ *
+ * @public
+ */
+export declare function signal(): FlowSignal;
+//# sourceMappingURL=flowSignal.d.ts.map

package/dist/types/flow/base/flowSignal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowSignal.d.ts","sourceRoot":"","sources":["../../../../src/flow/base/flowSignal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,qBAAa,UAAW,YAAW,cAAc,EAAE,WAAW;IAC7D;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,OAAO;IAKpB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACI,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAKvC;;;;;;;;;;;;;;;;;;;OAmBG;IACI,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAuBjD;;;;;;;;OAQG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAID,SAAS,CAAC,SAAS,UAAS;IAE5B,SAAS,CAAC,aAAa,kBAAyB;IAEhD,SAAS,CAAC,UAAU,kBAAyB;IAE7C,SAAS,CAAC,QAAQ,kBAAyB;IAE3C,SAAS,CAAC,OAAO,IAAI,IAAI;CAiCzB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,MAAM,IAAI,UAAU,CAEnC"}

package/dist/types/flow/base/flowTracker.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tracking context passed to reactive callbacks.
+ *
+ * @remarks
+ * Effects and derivations receive an instance of `FlowTracker` as the `t`
+ * parameter. Use it inside your callback to register dependencies (for example
+ * via APIs that accept `t`) so the callback can re-run when those dependencies
+ * change. Typical users do not implement this interface directly; it is
+ * implemented by the reactive primitives themselves.
+ *
+ * @public
+ */
+export interface FlowTracker {
+}
+//# sourceMappingURL=flowTracker.d.ts.map

package/dist/types/flow/base/flowTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowTracker.d.ts","sourceRoot":"","sources":["../../../../src/flow/base/flowTracker.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;CAE3B"}

package/dist/types/flow/base/index.d.ts

@@ -0,0 +1,7 @@
+export * from './flowDisposable';
+export * from './flowEffect';
+export * from './flowGraph';
+export * from './flowSignal';
+export * from './flowTracker';
+export * from './utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/flow/base/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/flow/base/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC"}

package/dist/types/flow/base/utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Excludes `Promise` types from `T`, returning `never` if `T` is a promise.
+ *
+ * @remarks
+ * Use `NotPromise<T>` to constrain generics to synchronous values. It is helpful
+ * when an API must reject promise inputs while accepting other types unchanged.
+ *
+ * @example
+ * ```typescript
+ * function useSync<T>(value: NotPromise<T>) {
+ *   // value cannot be a Promise
+ *   return value;
+ * }
+ *
+ * useSync(123);           // ok
+ * // useSync(Promise.resolve(1)); // type error
+ * ```
+ */
+export type NotPromise<T> = T extends Promise<unknown> ? never : T;
+//# sourceMappingURL=utils.d.ts.map

package/dist/types/flow/base/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../src/flow/base/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC"}

package/dist/types/{advanced/array.d.ts → flow/collections/flowArray.d.ts}

@@ -1,4 +1,4 @@
-import { FlowObservable, FlowState } from '../basic';
+import { FlowNode, FlowState } from '../nodes';
 /**
  * Represents the actions that can be performed on a FlowArray.
  * @public
@@ -7,7 +7,7 @@ export type FlowArrayAction<T> = {
     type: "set";
     items: T[];
 } | {
-    type: "setItem";
+    type: "update";
     index: number;
     item: T;
 } | {
@@ -32,12 +32,13 @@ export type FlowArrayAction<T> = {
  * Represents a reactive array.
  * @public
  */
-export declare class FlowArray<T> extends FlowObservable<T[]> {
+export declare class FlowArray<T> extends FlowNode<T[]> {
     /**
      * Last action performed on the FlowArray.
      * @public
      */
     $lastAction: FlowState<FlowArrayAction<T>>;
+    protected _value: T[];
     /**
      * Creates an instance of FlowArray.
      * @param value - Initial array value.
@@ -55,36 +56,36 @@ export declare class FlowArray<T> extends FlowObservable<T[]> {
      * @param items - The new array of items.
      * @public
      */
-    set(items: T[]): void;
+    set(items: T[]): Promise<void>;
     /**
      * Replaces an item at a specific index.
      * @param index - The index of the item to replace.
      * @param item - The new item.
      * @public
      */
-    setItem(index: number, item: T): void;
+    update(index: number, item: T): Promise<void>;
     /**
      * Appends an item to the end of the array.
      * @param item - The item to append.
      * @public
      */
-    push(item: T): void;
+    push(item: T): Promise<void>;
     /**
      * Removes the last item from the array.
      * @public
      */
-    pop(): void;
+    pop(): Promise<void>;
     /**
      * Inserts an item at the beginning of the array.
      * @param item - The item to insert.
      * @public
      */
-    unshift(item: T): void;
+    unshift(item: T): Promise<void>;
     /**
      * Removes the first item from the array.
      * @public
      */
-    shift(): void;
+    shift(): Promise<void>;
     /**
      * Changes the content of the array.
      * @param start - The starting index.
@@ -92,12 +93,12 @@ export declare class FlowArray<T> extends FlowObservable<T[]> {
      * @param newItems - New items to add.
      * @public
      */
-    splice(start: number, deleteCount: number, ...newItems: T[]): void;
+    splice(start: number, deleteCount: number, ...newItems: T[]): Promise<void>;
     /**
      * Clears all items from the array.
      * @public
      */
-    clear(): void;
+    clear(): Promise<void>;
     /**
      * Disposes the FlowArray and its items.
      * @param options - Disposal options.
@@ -107,4 +108,41 @@ export declare class FlowArray<T> extends FlowObservable<T[]> {
         self: boolean;
     }): void;
 }
-//# sourceMappingURL=array.d.ts.map
+/**
+ * Creates a new reactive array with mutation methods and fine-grained action tracking.
+ *
+ * @typeParam T - The type of the array elements.
+ * @param initial - An optional array of initial values.
+ * @returns A new instance of {@link FlowArray}.
+ *
+ * @remarks
+ * A reactive array provides array-like mutation methods (push, pop, shift, unshift, splice)
+ * and tracks the last operation performed via `$lastAction`. This enables both whole-array
+ * reactivity and fine-grained tracking of specific mutations.
+ *
+ * The array automatically disposes disposable items when they are removed (if they implement
+ * the FlowDisposable interface).
+ *
+ * @example
+ * ```typescript
+ * const $items = array([1, 2, 3]);
+ *
+ * // Track the whole array
+ * effect((t) => {
+ *   console.log('Items:', $items.get(t));
+ * });
+ *
+ * // Track the last action
+ * effect((t) => {
+ *   const action = $items.$lastAction.get(t);
+ *   console.log('Action:', action.type);
+ * });
+ *
+ * $items.push(4); // Logs action: "push"
+ * $items.pop();   // Logs action: "pop"
+ * ```
+ *
+ * @public
+ */
+export declare function array<T>(initial?: T[]): FlowArray<T>;
+//# sourceMappingURL=flowArray.d.ts.map

package/dist/types/flow/collections/flowArray.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowArray.d.ts","sourceRoot":"","sources":["../../../../src/flow/collections/flowArray.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,KAAK,SAAS,EAAS,MAAM,UAAU,CAAC;AAE3D;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAC1B;IACA,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,CAAC,EAAE,CAAC;CACV,GACD;IACA,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,CAAC,CAAC;CACP,GACD;IACA,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,CAAC,CAAC;CACP,GACD;IACA,IAAI,EAAE,KAAK,CAAC;CACX,GACD;IACA,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,CAAC,CAAC;CACP,GACD;IACA,IAAI,EAAE,OAAO,CAAC;CACb,GACD;IACA,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,EAAE,CAAC;CACV,GACD;IACA,IAAI,EAAE,OAAO,CAAC;CACb,CAAC;AAEL;;;GAGG;AACH,qBAAa,SAAS,CAAC,CAAC,CAAE,SAAQ,QAAQ,CAAC,CAAC,EAAE,CAAC;IAC9C;;;OAGG;IACH,WAAW,EAAE,SAAS,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3C,UAAkB,MAAM,EAAE,CAAC,EAAE,CAAC;IAE9B;;;;OAIG;gBACS,KAAK,GAAE,CAAC,EAAO;IAQ3B;;;;OAIG;IACH,IAAI,MAAM,IAAI,MAAM,CAGnB;IAWD;;;;OAIG;IACY,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA+B7C;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAmCnD;;;;OAIG;IACG,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBlC;;;OAGG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA8B1B;;;;OAIG;IACG,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBrC;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA6B5B;;;;;;OAMG;IACG,MAAM,CACX,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,GAAG,QAAQ,EAAE,CAAC,EAAE,GACd,OAAO,CAAC,IAAI,CAAC;IA+BhB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B5B;;;;OAIG;IACM,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;CASnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAEpD"}