chizu 0.2.43 → 0.2.44

package/README.md

@@ -17,6 +17,8 @@ Strongly typed React framework using generators and efficiently updated views al
 1. [Model annotations](#model-annotations)
 1. [Lifecycle actions](#lifecycle-actions)
 1. [Distributed actions](#distributed-actions)
+1. [Consuming actions](#consuming-actions)
+1. [Stateful props](#stateful-props)
 1. [Action decorators](#action-decorators)
 1. [Real-time applications](#real-time-applications)
 1. [Utility functions](#utility-functions)
@@ -281,7 +283,7 @@ class {
 - **`Lifecycle.Mount`** – Triggered once when the component mounts (`useLayoutEffect`).
 - **`Lifecycle.Node`** – Triggered after the component renders (`useEffect`).
 - **`Lifecycle.Error`** – Triggered when an action throws an error. Receives `ErrorDetails` as payload.
-- **`Lifecycle.Unmount`** – Triggered when the component unmounts.
+- **`Lifecycle.Unmount`** – Triggered when the component unmounts. All in-flight actions are automatically aborted before this handler runs.
 
 **Note:** Actions should ideally be self-contained and handle expected errors internally using patterns like [Option](https://mobily.github.io/ts-belt/api/option) or [Result](https://mobily.github.io/ts-belt/api/result) types to update the model accordingly. `Lifecycle.Error` is intended for timeouts, aborts, and uncaught catastrophic errors – not routine error handling.
 
@@ -305,6 +307,8 @@ export class Actions extends DistributedActions {
 }
 ```
 
+`createDistributedAction()` returns a `DistributedPayload<T>` type, which is distinct from the `Payload<T>` returned by `createAction()`. This enables compile-time enforcement &ndash; only distributed actions can be passed to `actions.consume()`.
+
 Any component that defines a handler for `DistributedActions.SignedOut` will receive the action when it's dispatched from any other component. For direct access to the broadcast emitter, use `useBroadcast()`:
 
 ```ts
@@ -321,6 +325,41 @@ broadcast.on(DistributedActions.SignedOut, (payload) => {
 });
 ```
 
+## Consuming actions
+
+The `consume()` method subscribes to a distributed action and re-renders content whenever a new value is dispatched, making it ideal for global context scenarios where you want to fetch data once and access it throughout your app without prop drilling. The callback receives a `Box<T>` from [Immertation](https://github.com/Wildhoney/Immertation) containing the `value` and an `inspect` proxy for checking annotation status.
+
+```tsx
+export default function Visitor(): React.ReactElement {
+  const [model, actions] = useVisitorActions();
+
+  return (
+    <div>
+      {actions.consume(Actions.Visitor, (visitor) =>
+        visitor.inspect.pending() ? <>Loading&hellip;</> : visitor.value.name,
+      )}
+    </div>
+  );
+}
+```
+
+> **Important:** The `consume()` method only accepts distributed actions created with `createDistributedAction()`. Attempting to pass a local action created with `createAction()` will result in a TypeScript error. This is enforced at compile-time to prevent confusion &ndash; local actions are scoped to a single component and cannot be consumed across the application.
+
+> **Note:** When a component mounts, `consume()` displays the most recent value for that action, even if it was dispatched before the component mounted. This is managed by the `Consumer` context provider. If no value has been dispatched yet, `consume()` renders `null` until the first dispatch occurs.
+
+## Stateful props
+
+Chizu uses the `Box<T>` type from [Immertation](https://github.com/Wildhoney/Immertation) to wrap values with metadata about their async state. Passing `Box<T>` to React components allows them to observe an object's state &ndash; checking if a value is pending, how many operations are in flight, and what the optimistic draft value is &ndash; all without additional state management.
+
+The `Box<T>` type has two properties:
+
+- **`box.value`** &ndash; The payload (e.g., `Country` object with `name`, `flag`, etc.).
+- **`box.inspect`** &ndash; An `Inspect<T>` proxy for checking annotation status:
+  - `box.inspect.pending()` &ndash; Returns `true` if any pending annotations exist.
+  - `box.inspect.remaining()` &ndash; Returns the count of pending annotations.
+  - `box.inspect.draft()` &ndash; Returns the draft value from the latest annotation.
+  - `box.inspect.is(Op.Update)` &ndash; Checks if the annotation matches a specific operation.
+
 ## Action decorators
 
 Chizu provides decorators to add common functionality to your actions. Import `use` from Chizu and apply decorators to action properties:
@@ -659,7 +698,7 @@ The regulator is accessed via `context.regulator` inside your action handlers. I
 const fetchAction = useAction<Model, typeof Actions, "Fetch">(
   async (context) => {
     // Disallow future dispatches of these actions
-    context.regulator.policy.disallow.matching(Actions.Fetch, Actions.Save);
+    context.regulator.policy.disallow.matching([Actions.Fetch, Actions.Save]);
 
     // Future dispatches via useAction will be aborted immediately
     // and the error handler will receive Reason.Disallowed
@@ -669,7 +708,7 @@ const fetchAction = useAction<Model, typeof Actions, "Fetch">(
 const resetAction = useAction<Model, typeof Actions, "Reset">(
   async (context) => {
     // Allow the actions again
-    context.regulator.policy.allow.matching(Actions.Fetch, Actions.Save);
+    context.regulator.policy.allow.matching([Actions.Fetch, Actions.Save]);
   },
 );
 ```
@@ -678,7 +717,7 @@ You can also abort running actions:
 
 ```ts
 // Abort specific actions across all components
-context.regulator.abort.matching(Actions.Fetch);
+context.regulator.abort.matching([Actions.Fetch]);
 
 // Abort all actions across all components
 context.regulator.abort.all();
@@ -692,20 +731,23 @@ context.regulator.abort.self();
 **Abort methods:**
 
 - `abort.all()` — Aborts all running actions across all components in the context.
-- `abort.matching(...actions)` — Aborts specific actions across all components.
+- `abort.matching(actions)` — Aborts specific actions (array) across all components.
 - `abort.self()` — Aborts only the current action instance.
+- `abort.own()` — Aborts all actions belonging to the current component only (called automatically on unmount).
 
 **Allow methods:**
 
 - `policy.allow.all()` — Clears all disallow policies across all components.
-- `policy.allow.matching(...actions)` — Allows specific actions across all components.
+- `policy.allow.matching(actions)` — Allows specific actions (array) across all components.
 - `policy.allow.self()` — Allows the current action.
+- `policy.allow.own()` — Clears all disallow policies belonging to the current component only.
 
 **Disallow methods:**
 
 - `policy.disallow.all()` — Clears all allow policies across all components.
-- `policy.disallow.matching(...actions)` — Disallows specific actions across all components.
+- `policy.disallow.matching(actions)` — Disallows specific actions (array) across all components.
 - `policy.disallow.self()` — Disallows the current action.
+- `policy.disallow.own()` — Clears all allow policies belonging to the current component only.
 
 The regulator is useful for advanced scenarios where you need to centrally manage cancellation and permission of asynchronous actions, such as rate limiting, feature toggling, or global aborts.
 
@@ -740,3 +782,19 @@ function Example({ children }) {
 ```
 
 This is useful for libraries that need action control without affecting the host application's actions. An `abort.all()` inside the provider won't abort actions outside it.
+
+### `Consumer`
+
+Creates an isolated consumer context for storing distributed action values. The Consumer stores the latest payload for each distributed action, enabling the `consume()` method to display the most recent value even when components mount after the action was dispatched:
+
+```tsx
+import { Consumer } from "chizu";
+
+function MyLibraryRoot({ children }) {
+  return <Consumer>{children}</Consumer>;
+}
+```
+
+Components inside `<Consumer>` have their own isolated value store. Actions consumed inside won't see values dispatched outside, and vice versa. This is useful for libraries that want to use `consume()` without interfering with the host application's consumed values.
+
+**Note:** In most applications, you don't need to provide a `Consumer` &ndash; one is created automatically at the default context level. Only use `<Consumer>` when you need isolation for library boundaries or testing.

package/dist/action/index.d.ts

@@ -1,22 +1,44 @@
-import { Payload } from '../types/index.ts';
+import { Payload, DistributedPayload } from '../types/index.ts';
 import { Action } from '../regulator/types.ts';
 /**
- * Defines a new action with a given payload type.
+ * Defines a new local action with a given payload type.
+ * Local actions are scoped to the component that defines them and cannot be consumed
+ * by other components. Use `createDistributedAction()` for actions that need to be
+ * shared across components via `actions.consume()`.
  *
  * @template T The type of the payload that the action will carry.
  * @param name An optional name for the action, used for debugging purposes.
  * @returns A new action symbol.
+ *
+ * @example
+ * ```ts
+ * const Increment = createAction<number>("Increment");
+ *
+ * // Dispatch within the same component
+ * actions.dispatch(Increment, 5);
+ * ```
  */
 export declare function createAction<T = never>(name?: string): Payload<T>;
 /**
  * Defines a new distributed action with a given payload type.
  * Distributed actions are broadcast to all mounted components that have defined a handler for them.
  *
+ * Returns a `DistributedPayload<T>` which is required by `actions.consume()`. Local actions
+ * created with `createAction()` cannot be consumed &ndash; this is enforced at compile-time.
+ *
  * @template T The type of the payload that the action will carry.
  * @param name An optional name for the action, used for debugging purposes.
- * @returns A new distributed action symbol.
+ * @returns A new distributed action symbol that can be used with `consume()`.
+ *
+ * @example
+ * ```ts
+ * const SignedOut = createDistributedAction<User>("SignedOut");
+ *
+ * // Can be consumed across components
+ * actions.consume(SignedOut, (box) => <div>{box.value.name}</div>);
+ * ```
  */
-export declare function createDistributedAction<T = never>(name?: string): Payload<T>;
+export declare function createDistributedAction<T = never>(name?: string): DistributedPayload<T>;
 /**
  * Checks whether an action is a distributed action.
  * Distributed actions are broadcast to all mounted components that have defined a handler for them.