chizu 0.2.42 → 0.2.44

package/README.md

@@ -17,11 +17,14 @@ 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)
 1. [Referential equality](#referential-equality)
 1. [Action regulator](#action-regulator)
+1. [Context providers](#context-providers)
 
 ## Benefits
 
@@ -280,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.
 
@@ -304,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
@@ -320,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:
@@ -650,7 +690,7 @@ function useSearchActions(props: Props) {
 
 ## Action regulator
 
-The `Regulator` class is accessed via `context.actions.regulator` inside your action handlers. It provides fine-grained control over asynchronous actions by managing `AbortController` instances and action policies. You can programmatically allow or disallow actions, and abort running actions either globally or by type.
+The regulator is accessed via `context.regulator` inside your action handlers. It provides fine-grained control over asynchronous actions by managing `AbortController` instances and action policies. You can programmatically allow or disallow actions, and abort running actions across all components in the context.
 
 ### Usage
 
@@ -658,10 +698,7 @@ The `Regulator` class is accessed via `context.actions.regulator` inside your ac
 const fetchAction = useAction<Model, typeof Actions, "Fetch">(
   async (context) => {
     // Disallow future dispatches of these actions
-    context.actions.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
@@ -671,10 +708,7 @@ const fetchAction = useAction<Model, typeof Actions, "Fetch">(
 const resetAction = useAction<Model, typeof Actions, "Reset">(
   async (context) => {
     // Allow the actions again
-    context.actions.regulator.policy.allow.matching(
-      Actions.Fetch,
-      Actions.Save,
-    );
+    context.regulator.policy.allow.matching([Actions.Fetch, Actions.Save]);
   },
 );
 ```
@@ -682,19 +716,85 @@ const resetAction = useAction<Model, typeof Actions, "Reset">(
 You can also abort running actions:
 
 ```ts
-context.actions.regulator.abort.matching(Actions.Fetch);
-context.actions.regulator.abort.all();
+// Abort specific actions across all components
+context.regulator.abort.matching([Actions.Fetch]);
+
+// Abort all actions across all components
+context.regulator.abort.all();
+
+// Abort only the current action instance
+context.regulator.abort.self();
 ```
 
 ### API
 
-- `add(action: Action, controller: AbortController): void` — Registers an AbortController for a given action.
-- `controller(action: Action): AbortController` — Creates and registers an AbortController for an action, aborting immediately if disallowed by policy.
-- `abort.all(): void` — Aborts all controllers and removes them.
-- `abort.matching(...actions: Action[]): void` — Aborts controllers for specific actions and removes them.
-- `policy.allow.all(...actions: Action[]): void` — Allows one or more actions.
-- `policy.allow.matching(...actions: Action[]): void` — Allows specific actions.
-- `policy.disallow.all(...actions: Action[]): void` — Disallows one or more actions.
-- `policy.disallow.matching(...actions: Action[]): void` — Disallows specific actions.
+**Abort methods:**
+
+- `abort.all()` — Aborts all running actions across all components in the context.
+- `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 (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 (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.
+
+## Context providers
+
+Chizu provides context providers for advanced use cases where you need isolated contexts. These are edge cases &ndash; most applications don't need them.
+
+### `Broadcaster`
+
+Creates an isolated broadcast context for distributed actions. Useful for libraries that want their own broadcast context without interfering with the host application:
+
+```tsx
+import { Broadcaster } from "chizu";
+
+function MyLibraryRoot({ children }) {
+  return <Broadcaster>{children}</Broadcaster>;
+}
+```
+
+Components inside `<Broadcaster>` have their own isolated broadcast channel. Distributed actions dispatched inside won't reach components outside, and vice versa.
+
+### `Regulators`
+
+Creates an isolated regulator context. All regulator operations (`abort.all()`, `policy.disallow.matching()`, etc.) only affect components within the same `Regulators` provider:
+
+```tsx
+import { Regulators } from "chizu";
+
+function Example({ children }) {
+  return <Regulators>{children}</Regulators>;
+}
+```
+
+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.
 
-The `Regulator` class 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.
+**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,21 +1,44 @@
-import { Action, 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.