@kuindji/reactive 1.1.0 → 1.3.0

package/dist/react/listenerOptionsEqual.d.ts

@@ -14,6 +14,20 @@ export declare function areTagsEqual(a?: string[], b?: string[]): boolean;
  * compare by reference, and `tags` use order-insensitive set comparison.
  */
 export declare function areListenerOptionsEqual(a?: ListenerOptions | null, b?: ListenerOptions | null): boolean;
+/**
+ * Expand a listener's options into a fully-populated set of the soft fields
+ * that {@link ListenerOptions} reconciliation updates in place, filling every
+ * omitted field with its default.
+ *
+ * `event.updateListenerOptions` uses partial-merge semantics (only fields
+ * present in the passed object change), but the React reconciliation layer is
+ * declarative: the options object fully describes the desired listener state,
+ * so a field dropped between renders must reset to its default. Passing this
+ * normalized object makes partial-merge behave as a full reset for exactly the
+ * soft fields — without disturbing `signal` (identity-managed by the abort
+ * wiring) or `context` (identity, handled by resubscribe).
+ */
+export declare function fillListenerUpdateDefaults(options?: ListenerOptions | null): ListenerOptions;
 /**
  * Domain-specific comparator for {@link EventOptions}. Primitives compare after
  * default semantics; `filter`/`filterContext` compare by reference.

package/dist/react/listenerOptionsEqual.js

@@ -70,6 +70,32 @@ export function areListenerOptionsEqual(a, b) {
     }
     return true;
 }
+/**
+ * Expand a listener's options into a fully-populated set of the soft fields
+ * that {@link ListenerOptions} reconciliation updates in place, filling every
+ * omitted field with its default.
+ *
+ * `event.updateListenerOptions` uses partial-merge semantics (only fields
+ * present in the passed object change), but the React reconciliation layer is
+ * declarative: the options object fully describes the desired listener state,
+ * so a field dropped between renders must reset to its default. Passing this
+ * normalized object makes partial-merge behave as a full reset for exactly the
+ * soft fields — without disturbing `signal` (identity-managed by the abort
+ * wiring) or `context` (identity, handled by resubscribe).
+ */
+export function fillListenerUpdateDefaults(options) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const o = options !== null && options !== void 0 ? options : {};
+    return {
+        limit: (_a = o.limit) !== null && _a !== void 0 ? _a : 0,
+        start: (_b = o.start) !== null && _b !== void 0 ? _b : 1,
+        tags: (_c = o.tags) !== null && _c !== void 0 ? _c : [],
+        extraData: (_d = o.extraData) !== null && _d !== void 0 ? _d : null,
+        alwaysFirst: (_e = o.alwaysFirst) !== null && _e !== void 0 ? _e : false,
+        alwaysLast: (_f = o.alwaysLast) !== null && _f !== void 0 ? _f : false,
+        async: (_g = o.async) !== null && _g !== void 0 ? _g : null,
+    };
+}
 /**
  * Domain-specific comparator for {@link EventOptions}. Primitives compare after
  * default semantics; `filter`/`filterContext` compare by reference.

package/dist/react/useActionBusStatus.d.ts

@@ -0,0 +1,13 @@
+import type { ActionStatus } from "../action.js";
+import type { BaseActionBus } from "../actionBus.js";
+import type { KeyOf } from "../lib/types.js";
+import { type AsyncActionState } from "./useAsyncAction.js";
+export type { ActionStatus, AsyncActionState };
+/**
+ * Subscribes to the status of a named action on an ActionBus and returns
+ * `{ loading, error, response }` for driving `loading`/`disabled` UI. This is
+ * the primary path for apps that route mutations through one shared ActionBus.
+ *
+ * An unregistered name reports an idle status and is safe to subscribe to.
+ */
+export declare function useActionBusStatus<TBus extends BaseActionBus, TName extends KeyOf<TBus["__type"]["actions"]>>(bus: TBus, name: TName): AsyncActionState<TBus["__type"]["actions"][TName]["actionReturnType"]>;

package/dist/react/useActionBusStatus.js

@@ -0,0 +1,23 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { toAsyncActionState } from "./useAsyncAction.js";
+/**
+ * Subscribes to the status of a named action on an ActionBus and returns
+ * `{ loading, error, response }` for driving `loading`/`disabled` UI. This is
+ * the primary path for apps that route mutations through one shared ActionBus.
+ *
+ * An unregistered name reports an idle status and is safe to subscribe to.
+ */
+export function useActionBusStatus(bus, name) {
+    const subscribe = useCallback((onChange) => {
+        const listener = () => {
+            onChange();
+        };
+        bus.onStatusChange(name, listener);
+        return () => {
+            bus.removeStatusListener(name, listener);
+        };
+    }, [bus, name]);
+    const getSnapshot = useCallback(() => bus.getStatus(name), [bus, name]);
+    const status = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    return toAsyncActionState(status);
+}

package/dist/react/useAsyncAction.d.ts

@@ -0,0 +1,26 @@
+import type { ActionResponse, ActionStatus } from "../action.js";
+import type { BaseHandler } from "../lib/types.js";
+export type { ActionResponse, ActionStatus };
+export type AsyncActionState<Response = any> = {
+    loading: boolean;
+    error: Error | null;
+    response: Response | null;
+};
+/**
+ * Project an action's {@link ActionStatus} into the {@link AsyncActionState}
+ * shape consumed by the status hooks (`pending` -> `loading`). Shared so
+ * `useAsyncAction` and `useActionBusStatus` stay in lockstep.
+ */
+export declare function toAsyncActionState<Response>(status: ActionStatus<Response>): AsyncActionState<Response>;
+/**
+ * Wraps a function in an action and exposes its in-flight status, so a
+ * component can drive `loading`/`disabled` without a hand-rolled
+ * `useState(false)`. Returns `[invoke, { loading, error, response }]`.
+ *
+ * For the common app pattern (one shared ActionBus) prefer
+ * `useActionBusStatus`. This hook is for a standalone, component-local action.
+ */
+export declare function useAsyncAction<Fn extends BaseHandler>(fn: Fn): readonly [
+    (...args: Parameters<Fn>) => Promise<ActionResponse<Awaited<ReturnType<Fn>>, Parameters<Fn>>>,
+    AsyncActionState<Awaited<ReturnType<Fn>>>
+];

package/dist/react/useAsyncAction.js

@@ -0,0 +1,61 @@
+import { useCallback, useLayoutEffect, useMemo, useRef, useSyncExternalStore, } from "react";
+import { createAction } from "../action.js";
+/**
+ * Project an action's {@link ActionStatus} into the {@link AsyncActionState}
+ * shape consumed by the status hooks (`pending` -> `loading`). Shared so
+ * `useAsyncAction` and `useActionBusStatus` stay in lockstep.
+ */
+export function toAsyncActionState(status) {
+    return {
+        loading: status.pending,
+        error: status.error,
+        response: status.response,
+    };
+}
+/**
+ * Wraps a function in an action and exposes its in-flight status, so a
+ * component can drive `loading`/`disabled` without a hand-rolled
+ * `useState(false)`. Returns `[invoke, { loading, error, response }]`.
+ *
+ * For the common app pattern (one shared ActionBus) prefer
+ * `useActionBusStatus`. This hook is for a standalone, component-local action.
+ */
+export function useAsyncAction(fn) {
+    // Keep the latest fn in a ref. The action wraps a stable indirection that
+    // always calls fnRef.current, so it invokes the current fn even from a
+    // consumer layout effect that runs after a rerender but before this hook's
+    // passive effects — which a useEffect+setAction swap would miss, invoking
+    // the previous fn. The ref is updated in a layout effect (commit phase),
+    // not during render: a render-phase mutation would leak a fn from a
+    // suspended or abandoned concurrent render that never commits into the
+    // currently committed UI. Layout effects run only for committed renders,
+    // and this one runs before any consumer layout effect declared after the
+    // hook call, so consumers still observe the latest fn.
+    const fnRef = useRef(fn);
+    useLayoutEffect(() => {
+        fnRef.current = fn;
+    });
+    const action = useMemo(() => {
+        const action = createAction(((...args) => fnRef.current(...args)));
+        // Without an error listener a throwing fn re-throws out of invoke
+        // (an unhandled rejection) instead of surfacing through status.
+        action.addErrorListener(() => { });
+        return action;
+    }, []);
+    const subscribe = useCallback((onChange) => {
+        const listener = () => {
+            onChange();
+        };
+        action.onStatusChange(listener);
+        return () => {
+            action.removeStatusListener(listener);
+        };
+    }, [action]);
+    const getSnapshot = useCallback(() => action.getStatus(), [action]);
+    const status = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    const invoke = useCallback((...args) => action.invoke(...args), [action]);
+    return [
+        invoke,
+        toAsyncActionState(status),
+    ];
+}

package/dist/react/useReconciledListener.js

@@ -1,5 +1,5 @@
 import { useEffect, useRef } from "react";
-import { areListenerOptionsEqual } from "./listenerOptionsEqual.js";
+import { areListenerOptionsEqual, fillListenerUpdateDefaults, } from "./listenerOptionsEqual.js";
 /**
  * Reconciles a single reactive listener across renders without relying on the
  * identity of the options object.
@@ -37,7 +37,16 @@ export function useReconciledListener({ keyDeps, options, subscribe, unsubscribe
             return;
         }
         if (!areListenerOptionsEqual(committedRef.current, options)) {
-            update(context, options);
+            // Normalize to a full soft-option set so a field dropped since the
+            // last render resets to its default: updateListenerOptions is
+            // partial-merge, but the React path is declarative (see
+            // fillListenerUpdateDefaults). Carry `signal` through only when
+            // present (matching the old whole-options pass), so its abort wiring
+            // is rebound/cleared exactly as before; `context` is passed
+            // separately and not read from the options object.
+            update(context, Object.assign(Object.assign({}, fillListenerUpdateDefaults(options)), ((options === null || options === void 0 ? void 0 : options.signal) !== undefined
+                ? { signal: options.signal }
+                : {})));
         }
         committedRef.current = options;
     });

package/dist/react/useStoreSelector.d.ts

@@ -0,0 +1,35 @@
+import type { KeyOf } from "../lib/types.js";
+import type { BaseStore } from "../store.js";
+export type EqualityFn<T> = (a: T, b: T) => boolean;
+/**
+ * Subscribes to a derived slice of a store with custom equality. Selector
+ * re-execution is gated on the raw input (dep values, or a shallow compare of
+ * the full state), so a selector that builds a fresh object each call returns a
+ * stable cached reference while its input is unchanged — safe even without an
+ * equality fn (an un-gated fresh reference on every getSnapshot call would loop
+ * forever). The optional equality fn additionally bails React re-renders when a
+ * recompute produces an equal-but-fresh result.
+ *
+ * Two forms:
+ *   useStoreSelector(store, (s) => `${s.first} ${s.last}`, shallowEqual?)
+ *   useStoreSelector(store, ["first", "last"], (first, last) => …, eqFn?)
+ *
+ * The deps-keyed form recomputes only when the change batch touches its keys.
+ *
+ * Prefer the deps-keyed form for narrow reads. The selector form (no deps)
+ * subscribes to every store change and rebuilds the whole state via getData()
+ * on each one, re-running the selector even for unrelated writes (the equality
+ * fn still bails React re-renders, but the recompute itself is not filtered).
+ * The deps-keyed form both filters the subscription to its keys and avoids
+ * materializing the full state, so reach for it when selecting a few slices of
+ * a large or frequently-written store.
+ *
+ * Concurrent-safe: the selection is memoized in a render-phase `useMemo` (an
+ * abandoned concurrent render discards it rather than leaking it into the
+ * committed tree) and the committed value is recorded in an effect, not during
+ * render. This mirrors React's own `useSyncExternalStoreWithSelector`.
+ */
+export declare function useStoreSelector<TStore extends BaseStore, R>(store: TStore, selector: (state: TStore["__type"]["propTypes"]) => R, equalityFn?: EqualityFn<R>): R;
+export declare function useStoreSelector<TStore extends BaseStore, const D extends readonly KeyOf<TStore["__type"]["propTypes"]>[], R>(store: TStore, deps: D, selector: (...values: {
+    [I in keyof D]: TStore["__type"]["propTypes"][D[I]];
+}) => R, equalityFn?: EqualityFn<R>): R;

package/dist/react/useStoreSelector.js

@@ -0,0 +1,153 @@
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useSyncExternalStore, } from "react";
+import { ChangeEventName } from "../store.js";
+// Shallow per-entry equality for two state objects (enumerable own keys
+// compared with Object.is). Used to gate selector re-execution in the
+// no-deps form, whose input is rebuilt fresh by getData() on every call.
+function shallowEqualObject(a, b) {
+    if (a === b) {
+        return true;
+    }
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length) {
+        return false;
+    }
+    for (const key of aKeys) {
+        if (!Object.prototype.hasOwnProperty.call(b, key)
+            || !Object.is(a[key], b[key])) {
+            return false;
+        }
+    }
+    return true;
+}
+export function useStoreSelector(store, arg2, arg3, arg4) {
+    var _a;
+    const deps = Array.isArray(arg2) ? arg2 : null;
+    const selector = (deps ? arg3 : arg2);
+    const equalityFn = (_a = (deps ? arg4 : arg3)) !== null && _a !== void 0 ? _a : Object.is;
+    // Committed selection cache. Written ONLY in an effect (commit phase) so an
+    // abandoned concurrent render cannot leak its selection into the committed
+    // tree (which a render-phase write to this cache would).
+    const instRef = useRef(null);
+    if (instRef.current === null) {
+        instRef.current = { hasValue: false, value: null };
+    }
+    const inst = instRef.current;
+    // Latest deps for the subscribe filter. Updated in a layout effect (commit
+    // phase), not during render, and read only inside the change listener (which
+    // fires after commit), so the subscription always filters on committed deps.
+    const depsRef = useRef(deps);
+    useLayoutEffect(() => {
+        depsRef.current = deps;
+    });
+    // The memoized selection getter. Built during render, but the useMemo result
+    // is part of the fiber's memoized state: an abandoned concurrent render
+    // discards it, so no closure leaks. Rebuilt only when the store, selector,
+    // equality, or deps identity changes. The committed `inst.value` is read
+    // (never written) here, so a re-render with an equal result bails out to the
+    // committed reference.
+    const getSelection = useMemo(() => {
+        let hasMemo = false;
+        let memoizedInput = [];
+        let memoized;
+        // Read the raw selector input (dep values, or the full state). On a
+        // destroyed store, read via getData() (which returns {} without
+        // asserting) instead of store.get() (which throws): getSnapshot can
+        // run for a still-mounted component after the store is destroyed
+        // (e.g. a provider torn down first), and must not throw out of
+        // render. Returns the input as an arg array so it can be both
+        // shallow-compared and spread into the selector.
+        const readInput = () => {
+            if (deps) {
+                if (store.isDestroyed()) {
+                    const snapshot = store.getData();
+                    return deps.map((d) => snapshot[d]);
+                }
+                return deps.map((d) => store.get(d));
+            }
+            return [store.getData()];
+        };
+        // Compare two raw inputs. The deps form holds dep values, compared
+        // by identity (the store replaces values on change, so identity
+        // tracks change). The selector form holds a single full-state
+        // object rebuilt fresh by getData() on every call, so it must be
+        // shallow-compared by entries rather than reference.
+        const inputsEqual = (a, b) => {
+            if (deps) {
+                if (a.length !== b.length) {
+                    return false;
+                }
+                for (let i = 0; i < a.length; i++) {
+                    if (!Object.is(a[i], b[i])) {
+                        return false;
+                    }
+                }
+                return true;
+            }
+            return shallowEqualObject(a[0], b[0]);
+        };
+        return () => {
+            const input = readInput();
+            if (!hasMemo) {
+                hasMemo = true;
+                memoizedInput = input;
+                const next = selector(...input);
+                if (inst.hasValue && equalityFn(inst.value, next)) {
+                    memoized = inst.value;
+                    return inst.value;
+                }
+                memoized = next;
+                return next;
+            }
+            // Gate selector re-execution on the raw input. getSnapshot must
+            // return a cached reference that only changes when the store
+            // changes; re-running a fresh-object selector on every call (and
+            // relying solely on equalityFn) would return a new reference
+            // each call under the default Object.is and loop forever. When
+            // the input is unchanged we return the cached selection without
+            // re-running the selector — mirroring React's own
+            // useSyncExternalStoreWithSelector, which gates on snapshot
+            // identity (here the store's reads are not stable references, so
+            // we shallow-compare the input instead).
+            if (inputsEqual(memoizedInput, input)) {
+                return memoized;
+            }
+            memoizedInput = input;
+            const next = selector(...input);
+            if (equalityFn(memoized, next)) {
+                return memoized;
+            }
+            memoized = next;
+            return next;
+        };
+    }, [store, selector, equalityFn, deps, inst]);
+    const subscribe = useCallback((onStoreChange) => {
+        // subscribe can run (during commit) for an already-destroyed store
+        // — e.g. a provider torn down before this component mounts, or a
+        // `store` change re-running subscribe. control() reaches the
+        // destroyed control bus's addListener, which throws "EventBus is
+        // destroyed" out of render. Skip subscribing and hand back a no-op
+        // cleanup; getSelection already reads destroyed stores safely.
+        if (store.isDestroyed()) {
+            return () => { };
+        }
+        const listener = (names) => {
+            const currentDeps = depsRef.current;
+            if (currentDeps
+                && !names.some((n) => currentDeps.indexOf(n) !== -1)) {
+                return;
+            }
+            onStoreChange();
+        };
+        store.control(ChangeEventName, listener);
+        return () => {
+            store.removeControl(ChangeEventName, listener);
+        };
+    }, [store]);
+    const value = useSyncExternalStore(subscribe, getSelection, getSelection);
+    useEffect(() => {
+        inst.hasValue = true;
+        inst.value = value;
+    }, [value, inst]);
+    return value;
+}

package/dist/react/useStoreState.js

@@ -1,6 +1,15 @@
 import { useCallback, useSyncExternalStore } from "react";
 export function useStoreState(store, key) {
     const subscribe = useCallback((onStoreChange) => {
+        // subscribe can run (during commit) for a store that was already
+        // destroyed — e.g. a provider torn down before this component
+        // mounts, or a `key`/`store` change re-running subscribe. onChange
+        // reaches the destroyed changes event's addListener, which throws
+        // "Event is destroyed" out of render. Skip subscribing and hand back
+        // a no-op cleanup; getSnapshot already reads destroyed stores safely.
+        if (store.isDestroyed()) {
+            return () => { };
+        }
         const listener = () => {
             onStoreChange();
         };
@@ -9,10 +18,22 @@ export function useStoreState(store, key) {
             store.removeOnChange(key, listener);
         };
     }, [store, key]);
-    const getSnapshot = useCallback(() => store.get(key), [store, key]);
+    const getSnapshot = useCallback(
+    // getSnapshot can run for a still-mounted component after the store is
+    // destroyed (e.g. a provider torn down first), and must not throw out of
+    // render. On a destroyed store read via getData() (returns {} without
+    // asserting) instead of get() (which throws). Mirrors useStoreSelector.
+    () => (store.isDestroyed()
+        ? store.getData()[key]
+        : store.get(key)), [store, key]);
     const value = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
     const setter = useCallback((value) => {
         if (typeof value === "function") {
+            // The cast is required by tsc (the typeof-narrowed `value` is
+            // `Setter | (ValueType & Function)`, not all callable), even
+            // though no-unnecessary-type-assertion disagrees on this TS
+            // version.
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
             store.set(key, value(store.get(key)));
         }
         else {

package/dist/react.d.ts

@@ -1,6 +1,8 @@
 export * from "./react/ErrorBoundary.js";
 export * from "./react/useAction.js";
 export * from "./react/useActionBus.js";
+export * from "./react/useActionBusStatus.js";
+export * from "./react/useAsyncAction.js";
 export * from "./react/useActionMap.js";
 export * from "./react/useEvent.js";
 export * from "./react/useEventBus.js";
@@ -10,4 +12,5 @@ export * from "./react/useListenToEvent.js";
 export * from "./react/useListenToEventBus.js";
 export * from "./react/useListenToStoreChanges.js";
 export * from "./react/useStore.js";
+export * from "./react/useStoreSelector.js";
 export * from "./react/useStoreState.js";

package/dist/react.js

@@ -1,6 +1,8 @@
 export * from "./react/ErrorBoundary.js";
 export * from "./react/useAction.js";
 export * from "./react/useActionBus.js";
+export * from "./react/useActionBusStatus.js";
+export * from "./react/useAsyncAction.js";
 export * from "./react/useActionMap.js";
 export * from "./react/useEvent.js";
 export * from "./react/useEventBus.js";
@@ -10,4 +12,5 @@ export * from "./react/useListenToEvent.js";
 export * from "./react/useListenToEventBus.js";
 export * from "./react/useListenToStoreChanges.js";
 export * from "./react/useStore.js";
+export * from "./react/useStoreSelector.js";
 export * from "./react/useStoreState.js";

package/dist/store.d.ts

@@ -42,8 +42,11 @@ export declare function createStore<PropMap extends BasePropMap = BasePropMap>(i
         <K extends KeyOf<PropMap>>(key: K, value: PropMap[K] | undefined): void;
         (key: Partial<PropMap>): void;
     };
+    readonly computed: <K extends KeyOf<PropMap>, const D extends readonly KeyOf<PropMap>[]>(key: K, deps: D, fn: (...values: { [I in keyof D]: PropMap[D[I]] | undefined; }) => PropMap[K]) => void;
     readonly isEmpty: () => boolean;
     readonly reset: () => void;
+    readonly destroy: () => void;
+    readonly isDestroyed: () => boolean;
     readonly onChange: <K extends KeyOf<import("./eventBus.js").GetEventsMap<StoreChangeEvents<PropMap>>>, H extends import("./eventBus.js").GetEventsMap<StoreChangeEvents<PropMap>>[K]["signature"]>(name: K, handler: H, options?: import("./event.js").ListenerOptions) => void;
     readonly removeOnChange: <K extends KeyOf<import("./eventBus.js").GetEventsMap<StoreChangeEvents<PropMap>>>, H extends import("./eventBus.js").GetEventsMap<StoreChangeEvents<PropMap>>[K]["signature"]>(name: K, handler: H, context?: object | null, tag?: string | null) => void;
     readonly updateOnChangeOptions: <K extends KeyOf<import("./eventBus.js").GetEventsMap<StoreChangeEvents<PropMap>>>, H extends import("./eventBus.js").GetEventsMap<StoreChangeEvents<PropMap>>[K]["signature"]>(name: K, handler: H, context?: object | null, nextOptions?: import("./event.js").ListenerOptions) => boolean;