@kuindji/reactive 1.1.0 → 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,9 +171,10 @@ 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`) **in place**, preserving its `called`/`count` counters. 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.
+- `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)
@@ -197,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
@@ -522,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
@@ -571,6 +595,8 @@ const result = await fetchUserAction.invoke("user123");
   - **Aliases**: `un()`, `off()`, `remove()`, `unsubscribe()`
 - `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
 
@@ -578,6 +604,30 @@ const result = await fetchUserAction.invoke("user123");
 - `removeErrorListener(handler, context?)` - Remove error listener
 - `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
@@ -703,6 +753,17 @@ const user = await actionBus.invoke("fetchUser", "user123");
 - `removeListener(name, handler, context?, tag?)` - Remove listener
   - **Aliases**: `un()`, `off()`, `remove()`, `unsubscribe()`
 - `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
 
@@ -761,9 +822,12 @@ 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()` - Clear store data
+- `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
 
@@ -784,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
@@ -965,6 +1063,31 @@ 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

package/dist/action.d.ts

@@ -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,10 +33,17 @@ 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 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.js").ListenerOptions) => void;

package/dist/action.js

@@ -14,10 +14,86 @@ export function createAction(action) {
     // 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, } = 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();
+    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 beforeResponse = triggerBeforeAction(...args);
             const beforeResults = isPromiseLike(beforeResponse)
@@ -25,12 +101,22 @@ export function createAction(action) {
                 : 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;
                 }
             }
@@ -38,16 +124,33 @@ export function createAction(action) {
             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 = {
@@ -55,23 +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,

package/dist/actionBus.d.ts

@@ -21,6 +21,11 @@ export declare function createActionBus<ActionsMap extends BaseActionsMap>(initi
     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.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;