@kuindji/reactive 1.1.0 → 1.2.0

package/dist/actionBus.js

@@ -3,16 +3,44 @@ import { createEvent } from "./event.js";
 export function createActionBus(initialActions = {}, errorListener) {
     const actions = new Map();
     const errorEvent = createEvent();
+    let destroyed = false;
+    // The error-forwarding listener attached to each action's error event is
+    // retained per name so removeAction can detach it. Otherwise a held action
+    // reference keeps forwarding errors into the bus after removal, and — since
+    // the forwarder counts as an error listener — its invoke resolves with an
+    // error response instead of rejecting.
+    const errorForwarders = new Map();
+    // Status subscriptions for actions that are not registered yet. They are
+    // recorded here so a later add()/replace() can attach them — otherwise a
+    // hook subscribing before registration (e.g. useActionBusStatus) would stay
+    // unsubscribed forever. Kept after attach so a re-added action reattaches.
+    const pendingStatusListeners = new Map();
     if (errorListener) {
         errorEvent.addListener(errorListener);
     }
     const add = (name, action) => {
+        if (destroyed) {
+            throw new Error("ActionBus is destroyed");
+        }
         if (!actions.has(name)) {
             const a = createAction(action);
-            a.addErrorListener(({ error, args }) => {
-                errorEvent.emit({ name, error, args, type: "action" });
-            });
+            // Preserve the original error type (e.g. "action-status") rather
+            // than hardcoding "action", so consumers can distinguish a failed
+            // invocation from a throwing status listener.
+            const forwarder = ({ error, args, type }) => {
+                errorEvent.emit({ name, error, args, type });
+            };
+            errorForwarders.set(name, forwarder);
+            a.addErrorListener(forwarder);
             actions.set(name, a);
+            // Attach any status subscriptions that were registered before this
+            // action existed.
+            const pending = pendingStatusListeners.get(name);
+            if (pending) {
+                pending.forEach((handler) => {
+                    a.onStatusChange(handler);
+                });
+            }
         }
     };
     Object.entries(initialActions).forEach(([name, action]) => {
@@ -28,6 +56,9 @@ export function createActionBus(initialActions = {}, errorListener) {
     // its listeners and the bus error-forwarding listener, which is attached to
     // the action's error event, not the function); otherwise add it.
     const replace = (name, action) => {
+        if (destroyed) {
+            throw new Error("ActionBus is destroyed");
+        }
         const existing = actions.get(name);
         if (existing) {
             existing.setAction(action);
@@ -40,9 +71,60 @@ export function createActionBus(initialActions = {}, errorListener) {
     // removeListener. The removed action's listeners and its error-forwarding
     // listener are dropped with it (they lived on the action's own events).
     const removeAction = (name) => {
-        actions.delete(name);
+        const action = actions.get(name);
+        const existed = actions.delete(name);
+        // Detach the bus error-forwarding listener from the removed action so a
+        // held reference no longer feeds the bus error event (and so its invoke
+        // rejects rather than resolving via the forwarder acting as an error
+        // listener). A later re-add() installs a fresh forwarder.
+        const forwarder = errorForwarders.get(name);
+        if (forwarder) {
+            action === null || action === void 0 ? void 0 : action.removeErrorListener(forwarder);
+            errorForwarders.delete(name);
+        }
+        // getStatus() now reports idle for this name, but status subscribers
+        // (e.g. useActionBusStatus via useSyncExternalStore) were attached to
+        // the removed action's own status event and will never be notified of
+        // the drop. Detach each retained subscription from the removed action
+        // (otherwise invoking a held action reference keeps notifying a
+        // listener that bus.removeStatusListener can no longer reach), then push
+        // an idle status so they re-read and clear stale state. Subscriptions
+        // stay in pendingStatusListeners so a later re-add() reattaches them.
+        if (existed) {
+            const pending = pendingStatusListeners.get(name);
+            pending === null || pending === void 0 ? void 0 : pending.forEach((handler) => {
+                action === null || action === void 0 ? void 0 : action.removeStatusListener(handler);
+                // Isolate each notify: one throwing subscriber must not abort
+                // the loop and leave the remaining subscribers attached and
+                // un-notified. Route the failure to the bus error event.
+                try {
+                    handler(idleStatus);
+                }
+                catch (error) {
+                    // The error forwarding must not re-escape either: a throwing
+                    // bus error listener would abort the loop and leave later
+                    // subscribers attached and un-notified.
+                    try {
+                        errorEvent.emit({
+                            name,
+                            error: error instanceof Error
+                                ? error
+                                : new Error(String(error)),
+                            args: [],
+                            type: "action-status",
+                        });
+                    }
+                    catch (_a) {
+                        // Nothing left to route to; swallow to keep the loop going.
+                    }
+                }
+            });
+        }
     };
     const invoke = (name, ...args) => {
+        if (destroyed) {
+            throw new Error("ActionBus is destroyed");
+        }
         const action = get(name);
         if (!action) {
             throw new Error(`Action ${name} not found`);
@@ -50,6 +132,9 @@ export function createActionBus(initialActions = {}, errorListener) {
         return action.invoke(...args);
     };
     const on = (name, handler, options) => {
+        if (destroyed) {
+            throw new Error("ActionBus is destroyed");
+        }
         const action = get(name);
         if (!action) {
             throw new Error(`Action ${name} not found`);
@@ -57,6 +142,9 @@ export function createActionBus(initialActions = {}, errorListener) {
         return action.addListener(handler, options);
     };
     const once = (name, handler, options) => {
+        if (destroyed) {
+            throw new Error("ActionBus is destroyed");
+        }
         options = options || {};
         options.limit = 1;
         const action = get(name);
@@ -66,6 +154,9 @@ export function createActionBus(initialActions = {}, errorListener) {
         return action.addListener(handler, options);
     };
     const un = (name, handler, context, tag) => {
+        if (destroyed) {
+            throw new Error("ActionBus is destroyed");
+        }
         const action = get(name);
         if (!action) {
             throw new Error(`Action ${name} not found`);
@@ -73,12 +164,80 @@ export function createActionBus(initialActions = {}, errorListener) {
         return action.removeListener(handler, context, tag);
     };
     const updateListenerOptions = (name, handler, context, nextOptions) => {
+        if (destroyed) {
+            throw new Error("ActionBus is destroyed");
+        }
         const action = get(name);
         if (!action) {
             return false;
         }
         return action.updateListenerOptions(handler, context, nextOptions);
     };
+    // Frozen and shared: getStatus() hands this single object to every missing
+    // action, so a consumer mutating it would corrupt all future idle snapshots
+    // (e.g. leaving a hook reporting false loading). Matches action status,
+    // whose snapshots are also frozen.
+    const idleStatus = Object.freeze({
+        pending: false,
+        error: null,
+        response: null,
+    });
+    // Status lives on the underlying action (the single in-flight point);
+    // the bus just delegates per name. An unregistered name reports idle and
+    // is a no-op to (un)subscribe.
+    const getStatus = (name) => {
+        const action = get(name);
+        if (!action) {
+            return idleStatus;
+        }
+        return action.getStatus();
+    };
+    const onStatusChange = (name, handler) => {
+        if (destroyed) {
+            throw new Error("ActionBus is destroyed");
+        }
+        // Record the subscription so it survives (re)registration, then attach
+        // to the action now if it already exists.
+        let pending = pendingStatusListeners.get(name);
+        if (!pending) {
+            pending = new Set();
+            pendingStatusListeners.set(name, pending);
+        }
+        pending.add(handler);
+        const action = get(name);
+        if (!action) {
+            return;
+        }
+        return action.onStatusChange(handler);
+    };
+    const removeStatusListener = (name, handler) => {
+        const pending = pendingStatusListeners.get(name);
+        if (pending) {
+            pending.delete(handler);
+            if (pending.size === 0) {
+                pendingStatusListeners.delete(name);
+            }
+        }
+        const action = get(name);
+        if (!action) {
+            return;
+        }
+        return action.removeStatusListener(handler);
+    };
+    // One-call teardown: destroy each owned action and the error event, then
+    // drop them all. Post-destroy invoke/addListener throw rather than silently
+    // no-op.
+    const destroy = () => {
+        actions.forEach((action) => {
+            action.destroy();
+        });
+        actions.clear();
+        pendingStatusListeners.clear();
+        errorForwarders.clear();
+        errorEvent.destroy();
+        destroyed = true;
+    };
+    const isDestroyed = () => destroyed;
     const api = {
         add,
         replace,
@@ -86,6 +245,11 @@ export function createActionBus(initialActions = {}, errorListener) {
         has,
         get,
         invoke,
+        destroy,
+        isDestroyed,
+        getStatus,
+        onStatusChange,
+        removeStatusListener,
         addListener: on,
         /** @alias addListener */
         on,

package/dist/actionMap.d.ts

@@ -5,6 +5,11 @@ export type { ActionResponse, BaseActionsMap, ErrorListenerSignature, ErrorRespo
 export declare function createActionMap<M extends BaseActionsMap>(actions: M, onAnyError?: ErrorListenerSignature<any[]> | ErrorListenerSignature<any[]>[]): { [key in KeyOf<M>]: {
     readonly invoke: (...args: Parameters<M[key]>) => Promise<ActionResponse<Awaited<ReturnType<M[key]>>, Parameters<M[key]>>>;
     readonly setAction: (nextAction: M[key]) => void;
+    readonly destroy: () => void;
+    readonly isDestroyed: () => boolean;
+    readonly getStatus: () => import("./action.js").ActionStatus<Awaited<ReturnType<M[key]>>>;
+    readonly onStatusChange: (handler: import("./action.js").StatusListenerSignature<M[key]>, listenerOptions?: import("./event.js").ListenerOptions) => void;
+    readonly removeStatusListener: (handler: import("./action.js").StatusListenerSignature<M[key]>, context?: object | null, tag?: string | null) => boolean;
     readonly addListener: (handler: import("./action.js").ListenerSignature<M[key]>, listenerOptions?: import("./event.js").ListenerOptions) => void;
     readonly on: (handler: import("./action.js").ListenerSignature<M[key]>, listenerOptions?: import("./event.js").ListenerOptions) => void;
     readonly subscribe: (handler: import("./action.js").ListenerSignature<M[key]>, listenerOptions?: import("./event.js").ListenerOptions) => void;

package/dist/event.d.ts

@@ -44,13 +44,39 @@ export interface ListenerOptions extends BaseOptions {
      * You can pass any additional fields here. They will be passed back to TriggerFilter
      */
     extraData?: any;
+    /**
+     * When provided, the listener is auto-removed once the signal aborts. If the
+     * signal is already aborted the listener is not added at all.
+     */
+    signal?: AbortSignal | null;
 }
-interface ListenerPrototype<Handler extends BaseHandler> extends Required<ListenerOptions> {
+interface ListenerPrototype<Handler extends BaseHandler> extends Required<Omit<ListenerOptions, "signal">> {
     handler: Handler;
     called: number;
     count: number;
     index: number;
     start: number;
+    abortCleanup: (() => void) | null;
+}
+/**
+ * Read-only projection of a registered listener, returned by `getListeners()`.
+ * Carries the listener's options plus its live `called`/`count` counters but
+ * none of the mutable internals — mutating this object does not affect the
+ * event.
+ */
+export interface ListenerInfo<Handler extends BaseHandler = BaseHandler> {
+    handler: Handler;
+    context: object | null;
+    tags: string[];
+    limit: number;
+    start: number;
+    called: number;
+    count: number;
+    async: boolean | number | null;
+    first: boolean;
+    alwaysFirst: boolean;
+    alwaysLast: boolean;
+    extraData: any;
 }
 export interface EventOptions<ListenerSignature extends BaseHandler> extends BaseOptions {
     /**
@@ -92,6 +118,7 @@ export declare function createEvent<ListenerSignature extends BaseHandler>(event
     readonly listen: (handler: ListenerSignature, listenerOptions?: ListenerOptions) => void;
     /** @alias addListener */
     readonly subscribe: (handler: ListenerSignature, listenerOptions?: ListenerOptions) => void;
+    readonly once: (handler: ListenerSignature, listenerOptions?: ListenerOptions) => void;
     readonly removeListener: (handler: ListenerSignature, context?: object | null, tag?: string | null) => boolean;
     readonly updateListenerOptions: (handler: ListenerSignature, context?: object | null, nextOptions?: ListenerOptions) => boolean;
     /** @alias removeListener */
@@ -117,8 +144,14 @@ export declare function createEvent<ListenerSignature extends BaseHandler>(event
     readonly resume: () => void;
     readonly setOptions: (eventOptions: Partial<EventOptions<ListenerSignature>>) => void;
     readonly reset: () => void;
+    readonly destroy: () => void;
+    readonly isDestroyed: () => boolean;
     readonly isSuspended: () => boolean;
     readonly isQueued: () => boolean;
+    readonly listenerCount: (tag?: string | null) => number;
+    readonly triggeredCount: () => number;
+    readonly lastTriggerArgs: () => Parameters<ListenerSignature> | null;
+    readonly getListeners: () => ListenerInfo<ListenerSignature>[];
     readonly withTags: <R>(tags: string[], callback: () => R) => R;
     readonly promise: (options?: ListenerOptions) => Promise<Parameters<ListenerSignature>>;
     readonly first: (...args: Parameters<ListenerSignature>) => ReturnType<ListenerSignature> | undefined;