@kuindji/reactive 1.1.0 → 1.2.0

package/dist/react/useActionBusStatus.js

@@ -0,0 +1,26 @@
+import { useCallback, useSyncExternalStore } from "react";
+/**
+ * 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 {
+        loading: status.pending,
+        error: status.error,
+        response: status.response,
+    };
+}

package/dist/react/useAsyncAction.d.ts

@@ -0,0 +1,20 @@
+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;
+};
+/**
+ * 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,53 @@
+import { useCallback, useLayoutEffect, useMemo, useRef, useSyncExternalStore, } from "react";
+import { createAction } from "../action.js";
+/**
+ * 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,
+        {
+            loading: status.pending,
+            error: status.error,
+            response: status.response,
+        },
+    ];
+}

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,144 @@
+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) => {
+        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

@@ -9,10 +9,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;