@kuindji/reactive 1.0.24 → 1.2.0

package/README.md

@@ -9,8 +9,8 @@ A JavaScript/TypeScript utility library for building reactive applications with
 ## Features
 
 - **Event System**: Event emitter with subscriber/dispatcher and collector modes
-- **Action System**: Async action handling with error management and response tracking
-- **Store System**: Reactive state management with change tracking and validation
+- **Action System**: Async action handling with error management, response tracking and loading/error/response status
+- **Store System**: Reactive state management with change tracking, validation and computed/derived values
 - **EventBus**: Centralized event management for complex applications
 - **ActionBus & ActionMap**: Organized action management with error handling
 - **React Integration**: Full React hooks support with error boundaries
@@ -99,9 +99,21 @@ event.addListener(handler, {
     tags: string[], // Listener tags for filtering; default undefined
     async: booleantrue, // Call this listener asynchronously; default false
     extraData: object, // Custom data will be passed to filter()
+    signal: AbortSignal, // Auto-remove the listener when this signal aborts
 });
 ```
 
+When a `signal` is provided, the listener is removed automatically once the
+signal aborts (and is not added at all if the signal is already aborted). The
+abort subscription is cleaned up if the listener is removed first, so there is no
+dangling reference into a still-live signal:
+
+```typescript
+const controller = new AbortController();
+event.addListener(handler, { signal: controller.signal });
+controller.abort(); // handler is now removed
+```
+
 ### Collector
 
 Collector allows you to gather data from listeners.
@@ -159,13 +171,16 @@ const value = event.pipe(1); // value = 4
 
 - `addListener(listener, options?)` - Add event listener
   - **Aliases**: `on()`, `listen()`, `subscribe()`
+- `once(listener, options?)` - Add a listener that is removed after a single call (sugar for `addListener(listener, { ...options, limit: 1 })`)
 - `removeListener(listener, context?, tag?)` - Remove specific listener
   - **Aliases**: `un()`, `off()`, `remove()`, `unsubscribe()`
+- `updateListenerOptions(listener, context?, nextOptions?)` - Update a registered listener's soft options (`limit`, `start`, `async`, `tags`, `extraData`, `alwaysFirst`/`alwaysLast`, `signal`) **in place**, preserving its `called`/`count` counters. This is a **partial update**: only fields explicitly present in `nextOptions` change; any omitted field keeps its current value. Pass a field explicitly to clear it (e.g. `limit: 0` for unlimited, `signal: null` to drop abort wiring). Matches the listener by `listener` + `context`. Returns `true` if a listener was found. `context` is an identity field and is not updated here (resubscribe to change it); `first` is insertion-time only and ignored. Lowering `limit` to at/below the current `called` removes the listener immediately.
 - `hasListener(listener?, context?, tag?)` - Check if listener exists
   - **Aliases**: `has()`
 - `removeAllListeners(tag?)` - Remove all listeners (optionally by tag)
 - `trigger(...args)` - Trigger the event
   - **Aliases**: `emit()`, `dispatch()`
+- `setOptions(options)` - Update event options in place. Accepts any `EventOptions` field (`async`, `limit`, `autoTrigger`, `filter`, `filterContext`, `maxListeners`). Does not reset the internal `triggered` count.
 
 #### Collector Methods
 
@@ -195,8 +210,17 @@ const value = event.pipe(1); // value = 4
 - `suspend(withQueue?: boolean)` - Suspend event triggering; When `withQueue=true`, all trigger calls will be queued and replayed after resume()
 - `resume()` - Resume event triggering
 - `reset()` - Reset event state
+- `destroy()` - Tear down the event: remove all listeners (unwinding any `AbortSignal` subscriptions) and mark it dead. After `destroy()`, `trigger()` and `addListener()` throw rather than silently no-op.
+- `isDestroyed()` - Returns `true` once `destroy()` has been called
 - `withTags(tags: string[], callback: () => CallbackResponse) => CallbackResponse` - Execute callback with specific tags
 
+#### Introspection
+
+- `listenerCount(tag?)` - Number of registered listeners, optionally filtered by tag
+- `triggeredCount()` - How many times the event has been triggered
+- `lastTriggerArgs()` - The most recent trigger arguments (a copy), or `null` if never triggered
+- `getListeners()` - Read-only projection of registered listeners (`handler`, `context`, `tags`, `limit`, `start`, `called`, `count`, `async`, ordering flags, `extraData`). Mutating the returned objects does not affect the event.
+
 ## EventBus
 
 ### Description
@@ -481,10 +505,12 @@ customSource.trigger("appStart");
 - `once(name, handler, options?)` - Add one-time listener
 - `removeListener(name, handler, context?, tag?)` - Remove listener
   - **Aliases**: `un()`, `off()`, `remove()`, `unsubscribe()`
+- `updateListenerOptions(name, handler, context?, nextOptions?)` - Update a registered listener's soft options in place (see Event's `updateListenerOptions`). Returns `false` if the event does not exist.
 - `trigger(name, ...args)` - Trigger specific event
   - **Aliases**: `emit()`, `dispatch()`
 - `get(name)` - Get event instance by name
 - `add(name, options?)` - Add new event to bus
+- `setOptions(options?)` - Update bus options. Present per-event entries in `eventOptions` are applied to already-created events via `event.setOptions`, and future events use the latest stored options. A removed event-name entry leaves the existing event unchanged.
 
 #### Collector Methods
 
@@ -518,7 +544,9 @@ customSource.trigger("appStart");
 - `removeEventSource(source)` - Remove event source
 - `suspendAll(withQueue?)` - Suspend all events
 - `resumeAll()` - Resume all events
-- `reset()` - Reset all events
+- `reset()` - Reset all events: unrelay all relays and remove all event sources (detaching their external listeners), then clear every owned event and interception/tag state. The bus stays usable afterwards.
+- `destroy()` - Tear down the bus: unrelay all relays, remove all event sources (detaching their external listeners), destroy every owned event, and mark the bus dead. After `destroy()`, `trigger()`/`on()` throw.
+- `isDestroyed()` - Returns `true` once `destroy()` has been called
 - `withTags(tags, callback)` - Execute callback with specific tags
 
 ## Action
@@ -560,27 +588,57 @@ const result = await fetchUserAction.invoke("user123");
 #### Core Methods
 
 - `invoke(...args)` - Execute the action
+- `setAction(fn)` - Replace the action function in place. Subsequent `invoke()` calls use the new function; all response, before-action and error listeners are preserved (they live in separate events). The replacement must keep a compatible signature.
 - `addListener(handler, options?)` - Add response listener
   - **Aliases**: `on()`, `listen()`, `subscribe()`
 - `removeListener(handler, context?, tag?)` - Remove listener
   - **Aliases**: `un()`, `off()`, `remove()`, `unsubscribe()`
-- `hasListener(handler?, context?, tag?)` - Check if listener exists
-  - **Aliases**: `has()`
+- `updateListenerOptions(handler, context?, nextOptions?)` - Update a response listener's soft options in place (see Event's `updateListenerOptions`)
 - `removeAllListeners(tag?)` - Remove all listeners
+- `destroy()` - Tear down the action: destroy its response, before-action, error and status events and mark it dead. After `destroy()`, `invoke()`/`addListener()` throw.
+- `isDestroyed()` - Returns `true` once `destroy()` has been called
 
 #### Error Handling
 
 - `addErrorListener(handler, context?)` - Add error listener
 - `removeErrorListener(handler, context?)` - Remove error listener
-- `hasErrorListeners()` - Check if error listeners exist
 - `removeAllErrorListeners(tag?)` - Remove all error listeners
 
+#### Status (loading / error / response)
+
+An action tracks the status of its `invoke` lifecycle so UI can drive
+`loading`/`disabled` without a hand-rolled `useState(false)`. `pending` is true
+while one or more invocations are in flight; `response`/`error` hold the last
+settled outcome (a before-action veto settles to neither). This is **not** a
+cache — `response` is just the last value.
+
+- `getStatus()` - Returns `{ pending: boolean, error: Error | null, response: T | null }`. The reference is stable while unchanged (safe for `useSyncExternalStore`).
+- `onStatusChange(handler)` - Subscribe to status changes
+- `removeStatusListener(handler)` - Remove a status listener
+
+```typescript
+const saveAction = createAction(async (data: FormData) => save(data));
+
+saveAction.onStatusChange(({ pending, error }) => {
+    button.disabled = pending;
+});
+
+await saveAction.invoke(form); // pending -> true, then false on settle
+```
+
+In React, prefer the `useAsyncAction` / `useActionBusStatus` hooks (see React Hooks).
+
 #### Utility Methods
 
 - `promise(options?)` - Get promise for next invocation
-- `suspend(withQueue?)` - Suspend action execution
-- `resume()` - Resume action execution
-- `reset()` - Reset action state
+- `beforeActionPromise(options?)` - Get promise for the next before-action call
+- `errorPromise(options?)` - Get promise for the next action error
+
+#### Before Action Methods
+
+- `addBeforeActionListener(handler, options?)` - Add listener that runs before invocation
+- `removeBeforeActionListener(handler, context?, tag?)` - Remove before-action listener
+- `removeAllBeforeActionListeners(tag?)` - Remove all before-action listeners
 
 ## ActionMap
 
@@ -683,7 +741,10 @@ const user = await actionBus.invoke("fetchUser", "user123");
 
 #### Core Methods
 
-- `add(name, action)` - Add action to bus
+- `add(name, action)` - Add action to bus (no-op if it already exists)
+- `replace(name, action)` - Replace an existing action's function in place via `setAction` (preserving its listeners and the bus error-forwarding listener); adds it if the name is new
+- `removeAction(name)` - Remove an action from the bus (named `removeAction` because `remove` is an alias for `removeListener`). Afterwards `invoke`/`on`/`un` for that name throw `Action <name> not found`.
+- `has(name)` - Check if action exists
 - `get(name)` - Get action by name
 - `invoke(name, ...args)` - Invoke action by name
 - `addListener(name, handler, options?)` - Add listener to action
@@ -691,8 +752,18 @@ const user = await actionBus.invoke("fetchUser", "user123");
 - `once(name, handler, options?)` - Add one-time listener
 - `removeListener(name, handler, context?, tag?)` - Remove listener
   - **Aliases**: `un()`, `off()`, `remove()`, `unsubscribe()`
-- `has(name)` - Check if action exists
-- `remove(name)` - Remove action
+- `updateListenerOptions(name, handler, context?, nextOptions?)` - Update a response listener's soft options in place (see Event's `updateListenerOptions`)
+- `destroy()` - Tear down the bus: destroy every owned action and the error event, then drop them all. After `destroy()`, `invoke()`/`on()` throw.
+- `isDestroyed()` - Returns `true` once `destroy()` has been called
+
+#### Status (loading / error / response)
+
+Delegates to the underlying action's status (see Action → Status). This is the
+primary path for apps that route mutations through one shared ActionBus.
+
+- `getStatus(name)` - Status for a named action; an unregistered name reports an idle status
+- `onStatusChange(name, handler)` - Subscribe to a named action's status. Subscribing before the action is registered is retained and attached automatically once it is added (and re-attached if the action is later removed and re-added)
+- `removeStatusListener(name, handler)` - Remove a status listener (also clears a subscription retained before registration)
 
 #### Error Handling
 
@@ -751,13 +822,18 @@ const userData = userStore.get([ "name", "email" ]); // { name: string, email: s
 - `asyncSet(data)` - Async set multiple properties
 - `get(key)` - Get single property
 - `get(keys)` - Get multiple properties
+- `computed(key, deps, fn)` - Register a derived value (see Computed values)
 - `isEmpty()` - Check if store is empty
 - `getData()` - Get all store data
-- `reset()` - Reset store to initial state
+- `reset()` - Clear store data. Computed keys are re-seeded from the cleared dependencies (so they stay consistent with `fn(deps)` rather than going stale) and remain live.
+- `destroy()` - Tear down the store: destroy the underlying change/pipe/control buses and drop all data. After `destroy()`, `set()`/`get()` throw.
+- `isDestroyed()` - Returns `true` once `destroy()` has been called
 
 #### Event Methods
 
-- `onChange(key, handler)` - Listen to property changes
+- `onChange(key, handler, options?)` - Listen to property changes
+- `removeOnChange(key, handler, context?, tag?)` - Remove a change listener
+- `updateOnChangeOptions(key, handler, context?, nextOptions?)` - Update a change listener's soft options in place (see Event's `updateListenerOptions`)
 - `pipe(key, handler)` - Add data transformation pipeline
 - `control(event, handler)` - Control store events
 
@@ -772,6 +848,40 @@ const userData = userStore.get([ "name", "email" ]); // { name: string, email: s
 
 - `batch(fn)` - Batch multiple changes
 
+#### Computed values
+
+Declare a derived key in the store type, then attach its derivation with
+`computed(key, deps, fn)`. It recomputes automatically when any dependency
+changes and notifies like any other key — `get`, `getData`, `onChange`,
+`useStoreState` and `useStoreSelector` all see it transparently. Computed keys
+are read-only: calling `set` on one throws. Computed-of-computed chains are
+supported, and a cyclic computed throws rather than looping.
+
+```typescript
+type UserStore = {
+    first: string;
+    last: string;
+    fullName: string; // declared in the type, registered as computed
+};
+
+const store = createStore<UserStore>({ first: "Jane", last: "Doe" });
+
+store.computed("fullName", [ "first", "last" ], (first, last) => `${first} ${last}`);
+
+store.get("fullName");        // "Jane Doe"
+store.onChange("fullName", (v) => console.log(v));
+store.set("first", "John");   // fullName recomputes -> "John Doe"
+store.set("fullName", "x");   // throws: computed is read-only
+```
+
+> **Note:** recompute is registration-order, not topologically sorted, so a
+> chained or diamond-shaped computed may recompute internally more than once per
+> change. This is invisible to consumers: a single `set(...)`/`set({...})`/`batch`
+> coalesces the `onChange` stream, so each computed fires `onChange` once with
+> its settled value and the correct previous value. The final value is always
+> correct. Registering base computeds before dependents reduces redundant
+> internal recomputes.
+
 ## React Hooks
 
 ### Description
@@ -953,6 +1063,42 @@ useListenToStoreChanges(
 )
 ```
 
+Select a derived slice with equality (bails out of re-renders while the result
+is unchanged). Two forms — a selector over the whole state, or a deps-keyed form
+that recomputes only when the listed keys change:
+
+```typescript
+// selector form (default equality is Object.is)
+const label = useStoreSelector(store, (s) => `${s.first} ${s.last}`, shallowEqual?);
+
+// deps-keyed form
+const anyLoading = useStoreSelector(store, [ "a", "b", "c" ], (a, b, c) => a || b || c);
+```
+
+Drive `loading`/`disabled` from an action's status. `useActionBusStatus` is the
+primary path for apps built around one shared ActionBus; `useAsyncAction` wraps a
+standalone function:
+
+```typescript
+// shared ActionBus
+const { loading, error, response } = useActionBusStatus(appActions, "user/login");
+
+// standalone action
+const [ submit, { loading, error } ] = useAsyncAction(saveProfileFn);
+// <Button loading={loading} disabled={loading} onClick={() => submit(form)} />
+```
+
+### Reconciliation across renders
+
+Hook inputs are reconciled on every render using semantic comparison, so you
+can safely pass inline objects (e.g. `{ tags: [tag] }`) without object identity
+forcing a resubscribe:
+
+- **Listener options** (`useListenToEvent`/`useListenToEventBus`/`useListenToActionBus`/`useListenToStoreChanges`) are compared field by field (`tags` is an order-insensitive set). A semantically equal object is a no-op. A changed soft option updates the live listener **in place**, preserving its `called`/`count` counters. Changing `context` (an identity field) resubscribes using the old context.
+- **`useEvent` event options** and **`useEventBus` options** are reconciled via `setOptions` instead of being ignored (and `useEventBus` no longer throws when options change).
+- **`useAction`/`useActionBus`/`useActionMap` action functions** are replaced in place via `setAction` (compared by reference), preserving all listeners; `useActionBus` also adds/removes actions as its map changes. The `useActionMap` key set is fixed by its type contract — a runtime key-set change throws.
+- **`useStore` config** (`onChange`/`pipes`/`control`) is reconciled by category + key (functions compared by reference); only handlers added by the hook are touched. **`initialData` is seed-only** — it initializes the store once and later changes are intentionally ignored (live data is owned by `set`/`useStoreState`).
+
 ## ErrorBoundary
 
 ### Description

package/dist/action.d.ts

@@ -1,4 +1,4 @@
-import type { ApiType, BaseHandler, ErrorListenerSignature, ErrorResponse } from "./lib/types";
+import type { ApiType, BaseHandler, ErrorListenerSignature, ErrorResponse } from "./lib/types.js";
 export type ActionResponse<Response = any, Args extends unknown[] = unknown[]> = {
     response: Response;
     error: null;
@@ -9,6 +9,18 @@ export type ActionResponse<Response = any, Args extends unknown[] = unknown[]> =
     args: Args;
 };
 export type ListenerSignature<ActionSignature extends BaseHandler> = (arg: ActionResponse<Awaited<ReturnType<ActionSignature>>, Parameters<ActionSignature>>) => void;
+/**
+ * Status of an action's `invoke` lifecycle, suitable for driving
+ * `loading`/`disabled` UI. `pending` is true while one or more invocations are
+ * in flight; `response`/`error` hold the last settled outcome (a before-veto
+ * settles to neither). This is not a cache — `response` is just the last value.
+ */
+export type ActionStatus<Response = any> = {
+    pending: boolean;
+    error: Error | null;
+    response: Response | null;
+};
+export type StatusListenerSignature<ActionSignature extends BaseHandler> = (status: ActionStatus<Awaited<ReturnType<ActionSignature>>>) => void;
 export type BeforeActionSignature<ActionSignature extends BaseHandler> = (...args: Parameters<ActionSignature>) => false | void | Promise<false | void>;
 export type ActionDefinitionHelper<A extends BaseHandler> = {
     actionSignature: A;
@@ -21,16 +33,24 @@ export type ActionDefinitionHelper<A extends BaseHandler> = {
     beforeActionSignature: BeforeActionSignature<A>;
     errorListenerArgument: ErrorResponse<Parameters<A>>;
     errorListenerSignature: ErrorListenerSignature<Parameters<A>>;
+    statusType: ActionStatus<Awaited<ReturnType<A>>>;
+    statusListenerSignature: StatusListenerSignature<A>;
 };
 export declare function createAction<A extends BaseHandler>(action: A): ApiType<ActionDefinitionHelper<A>, {
     readonly invoke: (...args: Parameters<A>) => Promise<ActionResponse<Awaited<ReturnType<A>>, Parameters<A>>>;
-    readonly addListener: (handler: ListenerSignature<A>, listenerOptions?: import("./event").ListenerOptions) => void;
+    readonly setAction: (nextAction: A) => void;
+    readonly destroy: () => void;
+    readonly isDestroyed: () => boolean;
+    readonly getStatus: () => ActionStatus<Awaited<ReturnType<A>>>;
+    readonly onStatusChange: (handler: StatusListenerSignature<A>, listenerOptions?: import("./event.js").ListenerOptions) => void;
+    readonly removeStatusListener: (handler: StatusListenerSignature<A>, context?: object | null, tag?: string | null) => boolean;
+    readonly addListener: (handler: ListenerSignature<A>, listenerOptions?: import("./event.js").ListenerOptions) => void;
     /** @alias addListener */
-    readonly on: (handler: ListenerSignature<A>, listenerOptions?: import("./event").ListenerOptions) => void;
+    readonly on: (handler: ListenerSignature<A>, listenerOptions?: import("./event.js").ListenerOptions) => void;
     /** @alias addListener */
-    readonly subscribe: (handler: ListenerSignature<A>, listenerOptions?: import("./event").ListenerOptions) => void;
+    readonly subscribe: (handler: ListenerSignature<A>, listenerOptions?: import("./event.js").ListenerOptions) => void;
     /** @alias addListener */
-    readonly listen: (handler: ListenerSignature<A>, listenerOptions?: import("./event").ListenerOptions) => void;
+    readonly listen: (handler: ListenerSignature<A>, listenerOptions?: import("./event.js").ListenerOptions) => void;
     readonly removeAllListeners: (tag?: string) => void;
     readonly removeListener: (handler: ListenerSignature<A>, context?: object | null, tag?: string | null) => boolean;
     /** @alias removeListener */
@@ -41,15 +61,16 @@ export declare function createAction<A extends BaseHandler>(action: A): ApiType<
     readonly remove: (handler: ListenerSignature<A>, context?: object | null, tag?: string | null) => boolean;
     /** @alias removeListener */
     readonly unsubscribe: (handler: ListenerSignature<A>, context?: object | null, tag?: string | null) => boolean;
-    readonly promise: (options?: import("./event").ListenerOptions) => Promise<[arg: ActionResponse<Awaited<ReturnType<A>>, Parameters<A>>]>;
-    readonly addErrorListener: (handler: ErrorListenerSignature<Parameters<A>>, listenerOptions?: import("./event").ListenerOptions) => void;
+    readonly updateListenerOptions: (handler: ListenerSignature<A>, context?: object | null, nextOptions?: import("./event.js").ListenerOptions) => boolean;
+    readonly promise: (options?: import("./event.js").ListenerOptions) => Promise<[arg: ActionResponse<Awaited<ReturnType<A>>, Parameters<A>>]>;
+    readonly addErrorListener: (handler: ErrorListenerSignature<Parameters<A>>, listenerOptions?: import("./event.js").ListenerOptions) => void;
     readonly removeAllErrorListeners: (tag?: string) => void;
     readonly removeErrorListener: (handler: ErrorListenerSignature<Parameters<A>>, context?: object | null, tag?: string | null) => boolean;
-    readonly errorPromise: (options?: import("./event").ListenerOptions) => Promise<[errorResponse: ErrorResponse<Parameters<A>>]>;
-    readonly addBeforeActionListener: (handler: BeforeActionSignature<A>, listenerOptions?: import("./event").ListenerOptions) => void;
+    readonly errorPromise: (options?: import("./event.js").ListenerOptions) => Promise<[errorResponse: ErrorResponse<Parameters<A>>]>;
+    readonly addBeforeActionListener: (handler: BeforeActionSignature<A>, listenerOptions?: import("./event.js").ListenerOptions) => void;
     readonly removeAllBeforeActionListeners: (tag?: string) => void;
     readonly removeBeforeActionListener: (handler: BeforeActionSignature<A>, context?: object | null, tag?: string | null) => boolean;
-    readonly beforeActionPromise: (options?: import("./event").ListenerOptions) => Promise<Parameters<A>>;
+    readonly beforeActionPromise: (options?: import("./event.js").ListenerOptions) => Promise<Parameters<A>>;
 }>;
 export type BaseActionDefinition = ActionDefinitionHelper<(...args: [any]) => any>;
 export type BaseAction = ReturnType<typeof createAction<(...args: [any]) => any>>;

package/dist/action.js

@@ -7,42 +7,150 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { createEvent } from "./event";
+import { createEvent } from "./event.js";
+import isPromiseLike from "./lib/isPromiseLike.js";
 export function createAction(action) {
-    const { trigger, addListener, removeAllListeners, removeListener, promise, } = createEvent();
-    const { all: triggerBeforeAction, addListener: addBeforeActionListener, removeAllListeners: removeAllBeforeActionListeners, removeListener: removeBeforeActionListener, promise: beforeActionPromise, } = createEvent();
-    const { trigger: triggerError, addListener: addErrorListener, removeAllListeners: removeAllErrorListeners, removeListener: removeErrorListener, promise: errorPromise, hasListener: hasErrorListeners, } = createEvent();
+    // The action function is held in a mutable variable so it can be swapped in
+    // place via setAction without disturbing any listeners (response, before
+    // and error listeners live in separate events independent of the function).
+    let actionFn = action;
+    const { trigger, addListener, removeAllListeners, removeListener, updateListenerOptions, promise, destroy: destroyResponseEvent, } = createEvent();
+    const { all: triggerBeforeAction, addListener: addBeforeActionListener, removeAllListeners: removeAllBeforeActionListeners, removeListener: removeBeforeActionListener, promise: beforeActionPromise, destroy: destroyBeforeEvent, } = createEvent();
+    const { trigger: triggerError, addListener: addErrorListener, removeAllListeners: removeAllErrorListeners, removeListener: removeErrorListener, promise: errorPromise, hasListener: hasErrorListeners, destroy: destroyErrorEvent, } = createEvent();
+    // Status is a side channel over the invoke lifecycle: a dedicated event so
+    // a React hook can subscribe through useSyncExternalStore. The status
+    // object reference is kept stable and only rebuilt when a field actually
+    // changes, which is required for useSyncExternalStore to bail out of
+    // redundant renders.
+    const { trigger: triggerStatus, addListener: addStatusListener, removeListener: removeStatusListener, destroy: destroyStatusEvent, } = createEvent();
+    let destroyed = false;
+    let inFlight = 0;
+    let lastResponse = null;
+    let lastError = null;
+    // Frozen so getStatus() can hand out the live reference (required for
+    // useSyncExternalStore to bail out of redundant renders) without a consumer
+    // being able to mutate it — a tampered `pending` would make updateStatus()
+    // believe nothing changed and suppress the next notification.
+    let currentStatus = Object.freeze({
+        pending: false,
+        error: null,
+        response: null,
+    });
+    const updateStatus = () => {
+        const pending = inFlight > 0;
+        if (currentStatus.pending === pending
+            && currentStatus.error === lastError
+            && currentStatus.response === lastResponse) {
+            return;
+        }
+        currentStatus = Object.freeze({
+            pending,
+            error: lastError,
+            response: lastResponse,
+        });
+        // The status event may have been torn down while an invocation was in
+        // flight. Still reconcile `currentStatus` above (so getStatus() does not
+        // strand `pending: true` after a mid-flight destroy), but skip emitting
+        // onto the dead event, which would throw and mask the real outcome.
+        if (destroyed) {
+            return;
+        }
+        // Status is a side channel. A throwing status listener must not corrupt
+        // the invoke lifecycle: if it propagated here it would, depending on the
+        // call site, abort execution or skip the inFlight decrement and strand
+        // `pending: true`. Isolate it and surface it via the error event.
+        try {
+            triggerStatus(currentStatus);
+        }
+        catch (error) {
+            // Surface the failure via the error event, but a throwing error
+            // listener must not re-escape either: this runs before invoke()
+            // enters its try/finally, so any escape would strand pending:true
+            // and skip execution entirely.
+            try {
+                triggerError({
+                    error: error instanceof Error
+                        ? error
+                        : new Error(String(error)),
+                    args: [],
+                    type: "action-status",
+                });
+            }
+            catch (_a) {
+                // Nothing left to route to; swallow to protect the lifecycle.
+            }
+        }
+    };
+    const getStatus = () => currentStatus;
     const invoke = (...args) => __awaiter(this, void 0, void 0, function* () {
+        if (destroyed) {
+            throw new Error("Action is destroyed");
+        }
+        // Snapshot whether error listeners existed at invocation start. The
+        // catch below ORs this with a live re-check: the snapshot guards against
+        // destroy() tearing listeners down mid-flight (which must not flip a
+        // handled failure into a rejection), while the live check still routes
+        // the error to a listener registered after invoke() began.
+        const handlesErrors = hasErrorListeners();
+        inFlight++;
+        updateStatus();
         try {
-            const beforeResults = triggerBeforeAction(...args);
-            for (let before of beforeResults) {
-                if (before instanceof Promise) {
-                    before = yield before;
-                }
+            const beforeResponse = triggerBeforeAction(...args);
+            const beforeResults = isPromiseLike(beforeResponse)
+                ? yield Promise.resolve(beforeResponse)
+                : beforeResponse;
+            for (const before of beforeResults) {
                 if (before === false) {
+                    // A before-veto is a no-op for the caller, not a settlement:
+                    // leave lastResponse/lastError untouched so a vetoed
+                    // invocation cannot wipe the status of a concurrent (or
+                    // prior) real invocation. A fresh action still reads idle
+                    // because both start null.
                     const response = {
                         response: null,
                         error: "Action cancelled",
                         args: args,
                     };
-                    trigger(response);
+                    // Skip emitting if destroyed mid-flight: the caller still
+                    // gets its settled response, but the torn-down event is not
+                    // triggered (which would throw "Event is destroyed").
+                    if (!destroyed) {
+                        trigger(response);
+                    }
                     return response;
                 }
             }
-            let result = action(...args);
-            if (result instanceof Promise) {
-                result = yield result;
+            let result = actionFn(...args);
+            if (isPromiseLike(result)) {
+                result = yield Promise.resolve(result);
             }
+            lastResponse = result;
+            lastError = null;
             const response = {
                 response: result,
                 error: null,
                 args: args,
             };
-            trigger(response);
+            // A successful invocation must still resolve with its result even if
+            // the action was destroyed while awaiting; only skip the emit.
+            if (!destroyed) {
+                trigger(response);
+            }
             return response;
         }
         catch (error) {
-            if (!hasErrorListeners()) {
+            // Record the failure before the re-throw branch so status is
+            // correct even when invoke re-throws (no error listener).
+            lastError = error instanceof Error
+                ? error
+                : new Error(error);
+            lastResponse = null;
+            // Handle the error if listeners existed at invoke start OR were
+            // registered while the invocation was in flight. The start-of-invoke
+            // snapshot is retained (rather than relying solely on the live check)
+            // so that destroy() tearing the listeners down mid-flight cannot flip
+            // a previously-handled failure into a rejection.
+            if (!handlesErrors && !hasErrorListeners()) {
                 throw error;
             }
             const response = {
@@ -50,19 +158,43 @@ export function createAction(action) {
                 error: error instanceof Error ? error.message : error,
                 args: args,
             };
-            trigger(response);
-            triggerError({
-                error: error instanceof Error
-                    ? error
-                    : new Error(error),
-                args: args,
-                type: "action",
-            });
+            if (!destroyed) {
+                trigger(response);
+                triggerError({
+                    error: lastError,
+                    args: args,
+                    type: "action",
+                });
+            }
             return response;
         }
+        finally {
+            inFlight--;
+            updateStatus();
+        }
     });
+    const setAction = (nextAction) => {
+        actionFn = nextAction;
+    };
+    // One-call teardown: destroy the underlying response/before/error/status
+    // events and mark the action dead. Post-destroy invoke/addListener throw
+    // rather than silently no-op.
+    const destroy = () => {
+        destroyResponseEvent();
+        destroyBeforeEvent();
+        destroyErrorEvent();
+        destroyStatusEvent();
+        destroyed = true;
+    };
+    const isDestroyed = () => destroyed;
     const api = {
         invoke,
+        setAction,
+        destroy,
+        isDestroyed,
+        getStatus,
+        onStatusChange: addStatusListener,
+        removeStatusListener,
         addListener,
         /** @alias addListener */
         on: addListener,
@@ -80,6 +212,7 @@ export function createAction(action) {
         remove: removeListener,
         /** @alias removeListener */
         unsubscribe: removeListener,
+        updateListenerOptions,
         promise,
         addErrorListener,
         removeAllErrorListeners,

package/dist/actionBus.d.ts

@@ -1,6 +1,6 @@
-import { ActionDefinitionHelper, createAction } from "./action";
-import { ListenerOptions } from "./event";
-import type { ApiType, BaseHandler, ErrorListenerSignature, KeyOf, MapKey } from "./lib/types";
+import { ActionDefinitionHelper, createAction } from "./action.js";
+import { ListenerOptions } from "./event.js";
+import type { ApiType, BaseHandler, ErrorListenerSignature, KeyOf, MapKey } from "./lib/types.js";
 export interface BaseActionsMap {
     [key: MapKey]: BaseHandler;
 }
@@ -16,8 +16,16 @@ export type ActionBusDefinitionHelper<ActionsMap extends BaseActionsMap> = {
 };
 export declare function createActionBus<ActionsMap extends BaseActionsMap>(initialActions?: ActionsMap, errorListener?: ErrorListenerSignature<any[]>): ApiType<ActionBusDefinitionHelper<ActionsMap>, {
     readonly add: (name: MapKey, action: BaseHandler) => void;
+    readonly replace: (name: MapKey, action: BaseHandler) => void;
+    readonly removeAction: (name: MapKey) => void;
+    readonly has: (name: MapKey) => boolean;
     readonly get: <K extends KeyOf<GetActionDefinitionsMap<ActionsMap>>>(name: K) => GetActionTypesMap<ActionsMap>[K];
-    readonly invoke: <K extends KeyOf<GetActionDefinitionsMap<ActionsMap>>>(name: K, ...args: GetActionDefinitionsMap<ActionsMap>[K]["actionArguments"]) => Promise<import("./action").ActionResponse<Awaited<ReturnType<ActionsMap[K]>>, Parameters<ActionsMap[K]>>>;
+    readonly invoke: <K extends KeyOf<GetActionDefinitionsMap<ActionsMap>>>(name: K, ...args: GetActionDefinitionsMap<ActionsMap>[K]["actionArguments"]) => Promise<import("./action.js").ActionResponse<Awaited<ReturnType<ActionsMap[K]>>, Parameters<ActionsMap[K]>>>;
+    readonly destroy: () => void;
+    readonly isDestroyed: () => boolean;
+    readonly getStatus: <K extends KeyOf<GetActionDefinitionsMap<ActionsMap>>>(name: K) => GetActionDefinitionsMap<ActionsMap>[K]["statusType"];
+    readonly onStatusChange: <K extends KeyOf<GetActionDefinitionsMap<ActionsMap>>>(name: K, handler: GetActionDefinitionsMap<ActionsMap>[K]["statusListenerSignature"]) => void;
+    readonly removeStatusListener: <K extends KeyOf<GetActionDefinitionsMap<ActionsMap>>>(name: K, handler: GetActionDefinitionsMap<ActionsMap>[K]["statusListenerSignature"]) => boolean | undefined;
     readonly addListener: <K extends KeyOf<GetActionDefinitionsMap<ActionsMap>>>(name: K, handler: GetActionDefinitionsMap<ActionsMap>[K]["listenerSignature"], options?: ListenerOptions) => void;
     /** @alias addListener */
     readonly on: <K extends KeyOf<GetActionDefinitionsMap<ActionsMap>>>(name: K, handler: GetActionDefinitionsMap<ActionsMap>[K]["listenerSignature"], options?: ListenerOptions) => void;
@@ -35,6 +43,7 @@ export declare function createActionBus<ActionsMap extends BaseActionsMap>(initi
     readonly un: <K extends KeyOf<GetActionDefinitionsMap<ActionsMap>>>(name: K, handler: GetActionDefinitionsMap<ActionsMap>[K]["listenerSignature"], context?: object | null, tag?: string | null) => boolean;
     /** @alias removeListener */
     readonly unsubscribe: <K extends KeyOf<GetActionDefinitionsMap<ActionsMap>>>(name: K, handler: GetActionDefinitionsMap<ActionsMap>[K]["listenerSignature"], context?: object | null, tag?: string | null) => boolean;
+    readonly updateListenerOptions: <K extends KeyOf<GetActionDefinitionsMap<ActionsMap>>>(name: K, handler: GetActionDefinitionsMap<ActionsMap>[K]["listenerSignature"], context?: object | null, nextOptions?: ListenerOptions) => boolean;
     readonly addErrorListener: (handler: ErrorListenerSignature<any[]>, listenerOptions?: ListenerOptions) => void;
     readonly removeErrorListener: (handler: ErrorListenerSignature<any[]>, context?: object | null, tag?: string | null) => boolean;
 }>;