chizu 0.2.34 → 0.2.35

package/README.md

@@ -14,9 +14,10 @@ Strongly typed React framework using generators and efficiently updated views al
 1. [Benefits](#benefits)
 1. [Getting started](#getting-started)
 1. [Error handling](#error-handling)
-<!-- 1. [Distributed actions](#distributed-actions)
-1. [Module dispatch](#module-dispatch)
-1. [Associated context](#associated-context) -->
+1. [Model annotations](#model-annotations)
+1. [Lifecycle actions](#lifecycle-actions)
+1. [Distributed actions](#distributed-actions)
+1. [Action decorators](#action-decorators)
 
 ## Benefits
 
@@ -81,17 +82,19 @@ export class Actions {
 }
 
 export default function useNameActions() {
-  const nameAction = useAction<Model, typeof Actions.Name>(async (context) => {
-    context.actions.produce((draft) => {
-      draft.name = null;
-    });
+  const nameAction = useAction<Model, typeof Actions, "Name">(
+    async (context) => {
+      context.actions.produce((draft) => {
+        draft.name = null;
+      });
 
-    const name = await fetch(/* ... */);
+      const name = await fetch(/* ... */);
 
-    context.actions.produce((draft) => {
-      draft.name = name;
-    });
-  });
+      context.actions.produce((draft) => {
+        draft.name = name;
+      });
+    },
+  );
 
   return useActions<Model, typeof Actions>(
     model,
@@ -120,160 +123,127 @@ export default function Profile(props: Props): React.ReactElement {
 
 ## Error handling
 
-Chizu provides a simple way to catch errors that occur within your actions. You can use the `ActionError` component to wrap your application and provide an error handler. This handler will be called whenever an error is thrown in an action.
+Chizu provides a simple way to catch errors that occur within your actions. You can use the `Error` component to wrap your application and provide an error handler. This handler will be called whenever an error is thrown in an action.
 
 ```tsx
-import { ActionError } from "chizu";
+import { Error } from "chizu";
 
 const App = () => (
-  <ActionError handler={(error) => console.error(error)}>
+  <Error handler={(error) => console.error(error)}>
     <Profile />
-  </ActionError>
+  </Error>
 );
 ```
 
-## Handling states
+## Model annotations
+
+Model annotations allow you to track the state of async operations on individual model fields. This is useful for showing loading indicators, optimistic updates, and tracking pending changes.
+
+Use `context.actions.annotate` to mark a value with an operation type. The view can then inspect the field to check if it's pending, get the draft value, or check the operation type:
 
 ```ts
 import { Op } from "chizu";
 
-// Mark a value as pending with an operation
 context.actions.produce((model) => {
   model.name = context.actions.annotate(Op.Update, "New Name");
 });
+```
 
-// Check pending state
-actions.inspect.name.pending(); // true
-
-// Get remaining count of pending operations
-actions.inspect.name.remaining(); // 1 (next: actions.inspect.name.draft())
+In the view, use `actions.inspect` to check the state of annotated fields:
 
-// Check specific operation
-actions.inspect.name.is(Op.Update); // true
+```ts
+actions.inspect.name.pending(); // true if operation is in progress
+actions.inspect.name.remaining(); // count of pending operations
+actions.inspect.name.draft(); // the next value to be applied
+actions.inspect.name.is(Op.Update); // check specific operation type
 ```
 
-<!-- However in the above example where the name is fetched asynchronously, there is no feedback to the user &ndash; we can improve that significantly by using the `module.actions.annotate` and `module.validate` helpers:
+## Lifecycle actions
 
-```tsx
-export default <Actions<Module>>function Actions(module) {
-  return {
-    async *[Action.Name]() {
-      yield module.actions.produce((draft) => {
-        draft.name = module.actions.annotate(null);
-      });
+Chizu provides lifecycle actions that trigger at specific points in a component's lifecycle. Import `Lifecycle` from Chizu:
 
-      const name = await fetch(/* ... */);
-      return module.actions.produce((draft) => {
-        draft.name = name;
-      });
-    },
-  };
-};
-```
+```ts
+import { Lifecycle } from "chizu";
 
-```tsx
-export default function ProfileView(props: Props): React.ReactElement {
-  return (
-    <Scope<Module> using={{ module, actions, props }}>
-      {(module) => (
-        <>
-          <p>Hey {module.model.name}</p>
-
-          {module.validate.name.pending() && <p>Switching profiles&hellip;</p>}
-
-          <button
-            disabled={module.validate.name.is(State.Op.Update)}
-            onClick={() => module.actions.dispatch([Action.Name])}
-          >
-            Switch profile
-          </button>
-        </>
-      )}
-    </Scope>
-  );
+class {
+  [Lifecycle.Mount] = mountAction;
+  [Lifecycle.Node] = nodeAction;
+  [Lifecycle.Unmount] = unmountAction;
 }
 ```
 
-
+- **`Lifecycle.Mount`** &ndash; Triggered once when the component mounts (`useLayoutEffect`).
+- **`Lifecycle.Node`** &ndash; Triggered after the component renders (`useEffect`).
+- **`Lifecycle.Unmount`** &ndash; Triggered when the component unmounts.
 
 ## Distributed actions
 
-Actions can communicate with other mounted actions using the `DistributedActions` approach. You can configure the enum and union type in the root of your application:
+Distributed actions allow different components to communicate with each other. Unlike regular actions which are scoped to a single component, distributed actions are broadcast to all mounted components that have defined a handler for them.
+
+To create a distributed action, use `createDistributedAction` instead of `createAction`. A good pattern is to define distributed actions in a shared class that other action classes can extend:
 
 ```ts
-export enum DistributedAction {
-  SignedOut = "distributed/signed-out",
+import { createAction, createDistributedAction } from "chizu";
+
+export class DistributedActions {
+  static SignedOut = createDistributedAction();
 }
 
-export type DistributedActions = [DistributedAction.SignedOut];
+export class Actions extends DistributedActions {
+  static Increment = createAction();
+}
 ```
 
-Note that you must prefix the enum name with `distributed` for it to behave as a distributed event, otherwise it'll be considered a module event only. Once you have the distributed actions you simply need to augment the module actions union with the `DistributedActions` and use it as you do other actions:
+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
-export type Actions = DistributedActions | [Action.Task, string]; // etc...
-```
-
-## Module dispatch
+## Action decorators
 
-In the eventuality that you have a component but don't want associated actions, models, etc&hellip; but want to still fire actions either the closest module or a distributed action, you can use the `useScoped` hook:
+Chizu provides decorators to add common functionality to your actions. Import `use` from Chizu and apply decorators to action properties:
 
 ```ts
-const module = useScoped<Module>();
-
-// ...
-
-module.actions.dispatch([Action.Task, "My task that needs to be done."]);
+import { use } from "chizu";
 ```
 
-Alternatively you can pass the current module as a prop to your components using the `Scoped` helper:
+### `use.exclusive()`
+
+Ensures only one instance of an action runs at a time. When a new action is dispatched, any previous running instance is automatically aborted. Use `context.signal` to cancel in-flight requests:
 
 ```ts
-export type Props = {
-  module: Scoped<Module>;
-};
+const searchAction = useAction<Model, typeof Actions, "Search">(
+  async (context, query) => {
+    const response = await fetch(`/search?q=${query}`, {
+      signal: context.signal,
+    });
+  },
+);
+
+return useActions<Model, typeof Actions>(
+  model,
+  class {
+    @use.exclusive()
+    [Actions.Search] = searchAction;
+  },
+);
 ```
 
-## Associated context
+### `use.reactive(() => [dependencies])`
 
-In many cases you'll still want to retrieve contextual values from within actions &ndash; which you can do by using the `module.actions.context` function:
+Automatically triggers an action when its dependencies change. Dependencies must be primitives (strings, numbers, booleans, etc.) which means you never have to worry about referential equality:
 
-```tsx
-export default <Actions<Module>>function Actions(module) {
-  const context = module.actions.context({
-    name: NameContext
-  });
-
-  return {
-    [Action.Name](name) {
-      return module.actions.produce((draft) => {
-        draft.name = context.name;
-      });
-    },
-  };
-};
+```ts
+class {
+  @use.reactive(() => [props.userId])
+  [Actions.FetchUser] = fetchUserAction;
+}
 ```
 
-If you need the context values to be reactive and fire the `Lifecycle.Derive` method then simply add it to your `props` definition when you initialise your scoped component:
+### `use.debug()`
 
-```tsx
-export default function Profile(props: Props): React.ReactElement {
-  const name = React.useContext(NameContext);
+Logs detailed timing information for debugging, including when the action started, how many `produce` calls were made, and total duration:
 
-  return (
-    <Scope<Module> using={{ model, actions, props: { ...props, name } }}>
-      {(module) => (
-        <>
-          <p>Hey {module.model.name}</p>
-
-          <button
-            onClick={() => module.actions.dispatch([Action.Name, randomName()])}
-          >
-            Switch profile
-          </button>
-        </>
-      )}
-    </Scope>
-  );
+```ts
+class {
+  @use.debug()
+  [Actions.Submit] = submitAction;
 }
-``` -->
+```

package/dist/action/index.d.ts

@@ -1,19 +1,26 @@
-import { Action, Payload } from '../types';
+import { Action, Payload } from '../types/index.ts';
 /**
  * Defines a new action with a given payload type.
  *
  * @template T The type of the payload that the action will carry.
- * @param {string} [name] An optional name for the action, used for debugging purposes.
- * @returns {Payload<T>} A new action object.
+ * @param name An optional name for the action, used for debugging purposes.
+ * @returns A new action symbol.
  */
 export declare function createAction<T = never>(name?: string): Payload<T>;
 /**
  * Defines a new distributed action with a given payload type.
- * Distributed actions can be shared across different modules.
+ * Distributed actions are broadcast to all mounted components that have defined a handler for them.
  *
  * @template T The type of the payload that the action will carry.
- * @param {string} [name] An optional name for the action, used for debugging purposes.
- * @returns {Payload<T>} A new distributed action object.
+ * @param name An optional name for the action, used for debugging purposes.
+ * @returns A new distributed action symbol.
  */
 export declare function createDistributedAction<T = never>(name?: string): Payload<T>;
+/**
+ * Checks whether an action is a distributed action.
+ * Distributed actions are broadcast to all mounted components that have defined a handler for them.
+ *
+ * @param action The action to check.
+ * @returns True if the action is a distributed action, false otherwise.
+ */
 export declare function isDistributedAction(action: Action): boolean;

package/dist/broadcast/index.d.ts

@@ -1,12 +1,12 @@
-import { BroadcastContext, Props } from './types.ts';
+import { Props } from './types.ts';
 import * as React from "react";
-export declare function useBroadcast(): BroadcastContext;
+export { useBroadcast } from './utils.ts';
 /**
- * Note: only needed if you want to create a new broadcast context, useful for
- * libraries that want to provide their own broadcast context without intefering
- * with the app's broadcast context.
+ * Creates a new broadcast context for distributed actions. Only needed if you
+ * want to isolate a broadcast context, useful for libraries that want to provide
+ * their own broadcast context without interfering with the app's broadcast context.
  *
- * @param param0 - { children }: Props
- * @returns {React.ReactNode}
+ * @param props.children - The children to render within the broadcast context.
+ * @returns The children wrapped in a broadcast context provider.
  */
 export declare function Broadcaster({ children }: Props): React.ReactNode;

package/dist/broadcast/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/broadcast/utils.d.ts

@@ -1,7 +1,12 @@
+import { BroadcastContext } from './types.ts';
+import * as React from "react";
 /**
- * Check if the name is a broadcast action.
+ * React context for broadcasting distributed actions across components.
+ */
+export declare const Context: React.Context<BroadcastContext>;
+/**
+ * Hook to access the broadcast context for emitting and listening to distributed actions.
  *
- * @param name {string}
- * @returns {boolean}
+ * @returns The broadcast context containing the EventEmitter instance.
  */
-export declare function isBroadcastAction(name: string): boolean;
+export declare function useBroadcast(): BroadcastContext;

package/dist/chizu.js

@@ -1,168 +1,252 @@
-import { jsx as h } from "react/jsx-runtime";
-import * as n from "react";
-import { createContext as A, useContext as O } from "react";
-import S from "eventemitter3";
-import { State as P } from "immertation";
-import { Op as Q, Operation as V, State as X } from "immertation";
-const E = A(void 0);
-function k() {
-  return O(E);
-}
-function F({
+import { jsx as x } from "react/jsx-runtime";
+import * as i from "react";
+import { createContext as P, useContext as j } from "react";
+import v from "eventemitter3";
+import { State as _ } from "immertation";
+import { Op as te, Operation as ne, State as oe } from "immertation";
+const C = P(void 0);
+function A() {
+  return j(C);
+}
+function q({
   handler: e,
   children: t
 }) {
-  return /* @__PURE__ */ h(E.Provider, { value: e, children: t });
+  return /* @__PURE__ */ x(C.Provider, { value: e, children: t });
 }
-function N(e = "anonymous") {
+function H(e = "anonymous") {
   return Symbol(`chizu.action/${e}`);
 }
-function T(e = "anonymous") {
+function J(e = "anonymous") {
   return Symbol(`chizu.action/distributed/${e}`);
 }
-function d(e) {
+function w(e) {
   return e.toString().startsWith("Symbol(chizu.action/distributed/");
 }
-class p {
+const $ = Symbol("chizu.action.context");
+class h {
   static Mount = Symbol("lifecycle/mount");
   static Node = Symbol("lifecycle/node");
   static Derive = Symbol("lifecycle/derive");
   static Error = Symbol("lifecycle/error");
   static Unmount = Symbol("lifecycle/unmount");
 }
-function M(e) {
+function D(e) {
   return new Promise((t) => setTimeout(t, e));
 }
-function g(e) {
+function k(e) {
   return e ? !!(e && typeof e != "symbol") : Symbol(`pk.${Date.now()}.${crypto.randomUUID()}`);
 }
-const j = g;
-function x(e) {
-  return (t, r) => {
+const F = k;
+function M(e) {
+  return (t, n) => {
     t.actions.produce((s) => {
-      s[e] = r;
+      s[e] = n;
     });
   };
 }
-const z = x, I = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+const R = M, K = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
   __proto__: null,
-  pk: g,
-  set: x,
-  sleep: M,
-  κ: j,
-  λ: z
-}, Symbol.toStringTag, { value: "Module" })), C = n.createContext({
-  instance: new S()
+  pk: k,
+  set: M,
+  sleep: D,
+  κ: F,
+  λ: R
+}, Symbol.toStringTag, { value: "Module" })), O = i.createContext({
+  instance: new v()
 });
-function D() {
-  return n.useContext(C);
+function G() {
+  return i.useContext(O);
 }
-function W({
+function Q({
   children: e
 }) {
-  const t = n.useMemo(() => ({
-    instance: new S()
+  const t = i.useMemo(() => ({
+    instance: new v()
   }), []);
-  return /* @__PURE__ */ h(C.Provider, { value: t, children: e });
+  return /* @__PURE__ */ x(O.Provider, { value: t, children: e });
 }
-function G(e, t) {
-  return Object.keys(e).reduce((r, s) => (Object.defineProperty(r, s, {
+function I(e, t) {
+  return Object.keys(e).reduce((n, s) => (Object.defineProperty(n, s, {
     get() {
       return t.current[s];
     },
     enumerable: !0
-  }), r), {});
+  }), n), {});
 }
-const R = Symbol("chizu.action.context");
-function q(e) {
-  const t = k();
-  return n.useCallback(async (r, s) => {
+const E = /* @__PURE__ */ new WeakMap(), S = /* @__PURE__ */ new WeakMap();
+function L(e) {
+  return typeof e == "symbol" ? e.description ?? "unknown" : e;
+}
+const V = {
+  /**
+   * Ensures only one instance of an action runs at a time. When dispatched again,
+   * the previous instance is aborted via `context.signal`.
+   *
+   * @returns A decorator function for the action.
+   */
+  exclusive() {
+    return function(e, t) {
+      t.addInitializer(function() {
+        const n = this, s = n[t.name];
+        n[t.name] = async (u) => (E.get(n)?.controller.abort(), E.set(n, u[$]), await s.call(n, u));
+      });
+    };
+  },
+  /**
+   * Automatically triggers an action when its primitive dependencies change.
+   * Dependencies must be primitives (strings, numbers, booleans, etc.) to avoid
+   * referential equality issues.
+   *
+   * @param getDependencies A function returning an array of primitive dependencies.
+   * @returns A decorator function for the action.
+   */
+  reactive(e) {
+    return function(t, n) {
+      n.addInitializer(function() {
+        const s = this, u = S.get(s) ?? [];
+        u.push({
+          action: n.name,
+          getDependencies: e
+        }), S.set(s, u);
+      });
+    };
+  },
+  /**
+   * Logs detailed timing and debugging information for the action, including
+   * start time, produce call timings, and total duration.
+   *
+   * @returns A decorator function for the action.
+   */
+  debug() {
+    return function(e, t) {
+      t.addInitializer(function() {
+        const n = this, s = n[t.name], u = L(t.name);
+        n[t.name] = async (m) => {
+          let p = 0;
+          const f = performance.now(), y = [];
+          console.group(`🔧 Action: ${u}`), console.log("⏱️  Started at:", (/* @__PURE__ */ new Date()).toISOString());
+          const g = m.actions.produce, a = {
+            ...m,
+            actions: {
+              ...m.actions,
+              produce: (o) => {
+                p++;
+                const r = performance.now(), c = g(o), d = performance.now() - r;
+                return y.push(d), console.log(`  📝 produce #${p}: ${d.toFixed(2)}ms`), c;
+              }
+            }
+          };
+          try {
+            const o = await s.call(n, a), c = performance.now() - f;
+            return console.log("─".repeat(40)), console.log(`📊 Summary for ${u}:`), console.log(`   Total produce calls: ${p}`), y.length > 0 && console.log(`   Produce times: ${y.map((l) => l.toFixed(2) + "ms").join(", ")}`), console.log(`   ⏱️  Total duration: ${c.toFixed(2)}ms`), console.groupEnd(), o;
+          } catch (o) {
+            const r = performance.now();
+            throw console.error(`❌ Error in ${u}:`, o), console.log(`   ⏱️  Failed after: ${(r - f).toFixed(2)}ms`), console.groupEnd(), o;
+          }
+        };
+      });
+    };
+  }
+};
+function X(e) {
+  const t = A();
+  return i.useCallback(async (n, s) => {
     try {
       if (e.constructor.name === "GeneratorFunction" || e.constructor.name === "AsyncGeneratorFunction") {
-        const a = e(r, s);
-        for await (const w of a) ;
+        const m = e(n, s);
+        for await (const p of m) ;
       } else
-        await e(r, s);
-    } catch (l) {
+        await e(n, s);
+    } catch (u) {
       console.error(`Chizu
 
-`, l), t?.(l);
+`, u), t?.(u);
     }
   }, [e, t]);
 }
-function H(e, t) {
-  const r = D(), [s, l] = n.useState(e), a = n.useRef(new P(e)), w = _({
+function Y(e, t) {
+  const n = G(), [s, u] = i.useState(e), m = i.useRef(new _(e)), p = T({
     model: s
-  }), m = n.useMemo(() => new S(), []), v = n.useCallback((i) => {
+  }), f = i.useMemo(() => new v(), []), y = i.useRef({
+    previous: /* @__PURE__ */ new Map()
+  }), g = i.useCallback((a) => {
     const o = new AbortController();
     return {
       signal: o.signal,
       actions: {
-        produce(c) {
+        produce(r) {
           if (o.signal.aborted) return;
-          const u = a.current.mutate((f) => c(f));
-          l(a.current.model), i.processes.add(u);
+          const c = m.current.mutate((l) => r(l));
+          u(m.current.model), a.processes.add(c);
         },
-        dispatch(...[c, u]) {
-          o.signal.aborted || (d(c) ? r.instance.emit(c, u) : m.emit(c, u));
+        dispatch(...[r, c]) {
+          o.signal.aborted || (w(r) ? n.instance.emit(r, c) : f.emit(r, c));
         },
-        annotate(c, u) {
-          return a.current.annotate(c, u);
+        annotate(r, c) {
+          return m.current.annotate(r, c);
         }
       },
-      [R]: {
+      [$]: {
         controller: o
       }
     };
-  }, [w.model]);
-  return n.useLayoutEffect(() => {
-    const i = new t();
-    Object.getOwnPropertySymbols(i).forEach((o) => {
-      const c = o;
-      if (d(o))
-        return void r.instance.on(o, async (u) => {
-          const f = {
+  }, [p.model]);
+  return i.useLayoutEffect(() => {
+    const a = new t();
+    Object.getOwnPropertySymbols(a).forEach((o) => {
+      const r = o;
+      if (w(o))
+        return void n.instance.on(o, async (c) => {
+          const l = {
             processes: /* @__PURE__ */ new Set()
-          }, y = Promise.withResolvers();
-          await i[c](v(f), u), f.processes.forEach((b) => a.current.prune(b)), y.resolve();
+          }, d = Promise.withResolvers();
+          await a[r](g(l), c), l.processes.forEach((b) => m.current.prune(b)), d.resolve();
         });
-      m.on(o, async (u) => {
-        const f = {
+      f.on(o, async (c) => {
+        const l = {
           processes: /* @__PURE__ */ new Set()
-        }, y = Promise.withResolvers();
-        await i[c](v(f), u), f.processes.forEach((b) => a.current.prune(b)), y.resolve();
+        }, d = Promise.withResolvers();
+        await a[r](g(l), c), l.processes.forEach((b) => m.current.prune(b)), d.resolve();
       });
     });
-  }, [m]), n.useLayoutEffect(() => (m.emit(p.Mount), () => void m.emit(p.Unmount)), []), n.useEffect(() => {
-    m.emit(p.Node);
-  }, []), n.useMemo(() => [s, {
-    dispatch(...[i, o]) {
-      d(i) ? r.instance.emit(i, o) : m.emit(i, o);
+  }, [f]), i.useEffect(() => {
+    const a = new t();
+    (S.get(a) ?? []).forEach((r) => {
+      const c = r.getDependencies(), l = y.current.previous.get(r.action) ?? [];
+      (c.length !== l.length || c.some((b, z) => !Object.is(b, l[z]))) && (y.current.previous.set(r.action, [...c]), f.emit(r.action));
+    });
+  }), i.useLayoutEffect(() => (f.emit(h.Mount), () => void f.emit(h.Unmount)), []), i.useEffect(() => {
+    f.emit(h.Node);
+  }, []), i.useMemo(() => [s, {
+    dispatch(...[a, o]) {
+      w(a) ? n.instance.emit(a, o) : f.emit(a, o);
     },
     consume() {
     },
     get inspect() {
-      return a.current.inspect;
+      return m.current.inspect;
     }
-  }], [s, m]);
+  }], [s, f]);
 }
-function _(e) {
-  const t = n.useRef(e);
-  return n.useLayoutEffect(() => {
+function T(e) {
+  const t = i.useRef(e);
+  return i.useLayoutEffect(() => {
     t.current = e;
-  }, [e]), n.useMemo(() => G(e, t), [e]);
+  }, [e]), i.useMemo(() => I(e, t), [e]);
 }
 export {
-  F as ActionError,
-  W as Broadcaster,
-  p as Lifecycle,
-  Q as Op,
-  V as Operation,
-  X as State,
-  N as createAction,
-  T as createDistributedAction,
-  q as useAction,
-  H as useActions,
-  _ as useSnapshot,
-  I as utils
+  Q as Broadcaster,
+  q as Error,
+  h as Lifecycle,
+  te as Op,
+  ne as Operation,
+  oe as State,
+  H as createAction,
+  J as createDistributedAction,
+  V as use,
+  X as useAction,
+  Y as useActions,
+  T as useSnapshot,
+  K as utils
 };

package/dist/chizu.umd.cjs

@@ -1,3 +1,3 @@
-(function(t,d){typeof exports=="object"&&typeof module<"u"?d(exports,require("react/jsx-runtime"),require("react"),require("eventemitter3"),require("immertation")):typeof define=="function"&&define.amd?define(["exports","react/jsx-runtime","react","eventemitter3","immertation"],d):(t=typeof globalThis<"u"?globalThis:t||self,d(t.Chizu={},t.jsxRuntime,t.React,t.EventEmitter3,t.Immertation))})(this,(function(t,d,p,h,b){"use strict";function k(e){const n=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(e){for(const r in e)if(r!=="default"){const c=Object.getOwnPropertyDescriptor(e,r);Object.defineProperty(n,r,c.get?c:{enumerable:!0,get:()=>e[r]})}}return n.default=e,Object.freeze(n)}const o=k(p),j=p.createContext(void 0);function z(){return p.useContext(j)}function D({handler:e,children:n}){return d.jsx(j.Provider,{value:e,children:n})}function _(e="anonymous"){return Symbol(`chizu.action/${e}`)}function T(e="anonymous"){return Symbol(`chizu.action/distributed/${e}`)}function w(e){return e.toString().startsWith("Symbol(chizu.action/distributed/")}class S{static Mount=Symbol("lifecycle/mount");static Node=Symbol("lifecycle/node");static Derive=Symbol("lifecycle/derive");static Error=Symbol("lifecycle/error");static Unmount=Symbol("lifecycle/unmount")}function G(e){return new Promise(n=>setTimeout(n,e))}function v(e){return e?!!(e&&typeof e!="symbol"):Symbol(`pk.${Date.now()}.${crypto.randomUUID()}`)}const L=v;function A(e){return(n,r)=>{n.actions.produce(c=>{c[e]=r})}}const q=Object.freeze(Object.defineProperty({__proto__:null,pk:v,set:A,sleep:G,κ:L,λ:A},Symbol.toStringTag,{value:"Module"})),P=o.createContext({instance:new h});function x(){return o.useContext(P)}function B({children:e}){const n=o.useMemo(()=>({instance:new h}),[]);return d.jsx(P.Provider,{value:n,children:e})}function R(e,n){return Object.keys(e).reduce((r,c)=>(Object.defineProperty(r,c,{get(){return n.current[c]},enumerable:!0}),r),{})}const U=Symbol("chizu.action.context");function $(e){const n=z();return o.useCallback(async(r,c)=>{try{if(e.constructor.name==="GeneratorFunction"||e.constructor.name==="AsyncGeneratorFunction"){const f=e(r,c);for await(const E of f);}else await e(r,c)}catch(y){console.error(`Chizu
+(function(o,b){typeof exports=="object"&&typeof module<"u"?b(exports,require("react/jsx-runtime"),require("react"),require("eventemitter3"),require("immertation")):typeof define=="function"&&define.amd?define(["exports","react/jsx-runtime","react","eventemitter3","immertation"],b):(o=typeof globalThis<"u"?globalThis:o||self,b(o.Chizu={},o.jsxRuntime,o.React,o.EventEmitter3,o.Immertation))})(this,(function(o,b,O,j,w){"use strict";function D(e){const t=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(e){for(const n in e)if(n!=="default"){const r=Object.getOwnPropertyDescriptor(e,n);Object.defineProperty(t,n,r.get?r:{enumerable:!0,get:()=>e[n]})}}return t.default=e,Object.freeze(t)}const u=D(O),C=O.createContext(void 0);function x(){return O.useContext(C)}function T({handler:e,children:t}){return b.jsx(C.Provider,{value:e,children:t})}function F(e="anonymous"){return Symbol(`chizu.action/${e}`)}function I(e="anonymous"){return Symbol(`chizu.action/distributed/${e}`)}function E(e){return e.toString().startsWith("Symbol(chizu.action/distributed/")}const $=Symbol("chizu.action.context");class S{static Mount=Symbol("lifecycle/mount");static Node=Symbol("lifecycle/node");static Derive=Symbol("lifecycle/derive");static Error=Symbol("lifecycle/error");static Unmount=Symbol("lifecycle/unmount")}function G(e){return new Promise(t=>setTimeout(t,e))}function M(e){return e?!!(e&&typeof e!="symbol"):Symbol(`pk.${Date.now()}.${crypto.randomUUID()}`)}const L=M;function k(e){return(t,n)=>{t.actions.produce(r=>{r[e]=n})}}const R=Object.freeze(Object.defineProperty({__proto__:null,pk:M,set:k,sleep:G,κ:L,λ:k},Symbol.toStringTag,{value:"Module"})),z=u.createContext({instance:new j});function q(){return u.useContext(z)}function B({children:e}){const t=u.useMemo(()=>({instance:new j}),[]);return b.jsx(z.Provider,{value:t,children:e})}function N(e,t){return Object.keys(e).reduce((n,r)=>(Object.defineProperty(n,r,{get(){return t.current[r]},enumerable:!0}),n),{})}const A=new WeakMap,P=new WeakMap;function U(e){return typeof e=="symbol"?e.description??"unknown":e}const W={exclusive(){return function(e,t){t.addInitializer(function(){const n=this,r=n[t.name];n[t.name]=async a=>(A.get(n)?.controller.abort(),A.set(n,a[$]),await r.call(n,a))})}},reactive(e){return function(t,n){n.addInitializer(function(){const r=this,a=P.get(r)??[];a.push({action:n.name,getDependencies:e}),P.set(r,a)})}},debug(){return function(e,t){t.addInitializer(function(){const n=this,r=n[t.name],a=U(t.name);n[t.name]=async m=>{let y=0;const d=performance.now(),g=[];console.group(`🔧 Action: ${a}`),console.log("⏱️  Started at:",new Date().toISOString());const v=m.actions.produce,l={...m,actions:{...m.actions,produce:c=>{y++;const s=performance.now(),i=v(c),p=performance.now()-s;return g.push(p),console.log(`  📝 produce #${y}: ${p.toFixed(2)}ms`),i}}};try{const c=await r.call(n,l),i=performance.now()-d;return console.log("─".repeat(40)),console.log(`📊 Summary for ${a}:`),console.log(`   Total produce calls: ${y}`),g.length>0&&console.log(`   Produce times: ${g.map(f=>f.toFixed(2)+"ms").join(", ")}`),console.log(`   ⏱️  Total duration: ${i.toFixed(2)}ms`),console.groupEnd(),c}catch(c){const s=performance.now();throw console.error(`❌ Error in ${a}:`,c),console.log(`   ⏱️  Failed after: ${(s-d).toFixed(2)}ms`),console.groupEnd(),c}}})}}};function H(e){const t=x();return u.useCallback(async(n,r)=>{try{if(e.constructor.name==="GeneratorFunction"||e.constructor.name==="AsyncGeneratorFunction"){const m=e(n,r);for await(const y of m);}else await e(n,r)}catch(a){console.error(`Chizu
 
-`,y),n?.(y)}},[e,n])}function N(e,n){const r=x(),[c,y]=o.useState(e),f=o.useRef(new b.State(e)),E=C({model:c}),l=o.useMemo(()=>new h,[]),M=o.useCallback(a=>{const s=new AbortController;return{signal:s.signal,actions:{produce(u){if(s.signal.aborted)return;const i=f.current.mutate(m=>u(m));y(f.current.model),a.processes.add(i)},dispatch(...[u,i]){s.signal.aborted||(w(u)?r.instance.emit(u,i):l.emit(u,i))},annotate(u,i){return f.current.annotate(u,i)}},[U]:{controller:s}}},[E.model]);return o.useLayoutEffect(()=>{const a=new n;Object.getOwnPropertySymbols(a).forEach(s=>{const u=s;if(w(s))return void r.instance.on(s,async i=>{const m={processes:new Set},O=Promise.withResolvers();await a[u](M(m),i),m.processes.forEach(g=>f.current.prune(g)),O.resolve()});l.on(s,async i=>{const m={processes:new Set},O=Promise.withResolvers();await a[u](M(m),i),m.processes.forEach(g=>f.current.prune(g)),O.resolve()})})},[l]),o.useLayoutEffect(()=>(l.emit(S.Mount),()=>void l.emit(S.Unmount)),[]),o.useEffect(()=>{l.emit(S.Node)},[]),o.useMemo(()=>[c,{dispatch(...[a,s]){w(a)?r.instance.emit(a,s):l.emit(a,s)},consume(){},get inspect(){return f.current.inspect}}],[c,l])}function C(e){const n=o.useRef(e);return o.useLayoutEffect(()=>{n.current=e},[e]),o.useMemo(()=>R(e,n),[e])}Object.defineProperty(t,"Op",{enumerable:!0,get:()=>b.Op}),Object.defineProperty(t,"Operation",{enumerable:!0,get:()=>b.Operation}),Object.defineProperty(t,"State",{enumerable:!0,get:()=>b.State}),t.ActionError=D,t.Broadcaster=B,t.Lifecycle=S,t.createAction=_,t.createDistributedAction=T,t.useAction=$,t.useActions=N,t.useSnapshot=C,t.utils=q,Object.defineProperty(t,Symbol.toStringTag,{value:"Module"})}));
+`,a),t?.(a)}},[e,t])}function J(e,t){const n=q(),[r,a]=u.useState(e),m=u.useRef(new w.State(e)),y=_({model:r}),d=u.useMemo(()=>new j,[]),g=u.useRef({previous:new Map}),v=u.useCallback(l=>{const c=new AbortController;return{signal:c.signal,actions:{produce(s){if(c.signal.aborted)return;const i=m.current.mutate(f=>s(f));a(m.current.model),l.processes.add(i)},dispatch(...[s,i]){c.signal.aborted||(E(s)?n.instance.emit(s,i):d.emit(s,i))},annotate(s,i){return m.current.annotate(s,i)}},[$]:{controller:c}}},[y.model]);return u.useLayoutEffect(()=>{const l=new t;Object.getOwnPropertySymbols(l).forEach(c=>{const s=c;if(E(c))return void n.instance.on(c,async i=>{const f={processes:new Set},p=Promise.withResolvers();await l[s](v(f),i),f.processes.forEach(h=>m.current.prune(h)),p.resolve()});d.on(c,async i=>{const f={processes:new Set},p=Promise.withResolvers();await l[s](v(f),i),f.processes.forEach(h=>m.current.prune(h)),p.resolve()})})},[d]),u.useEffect(()=>{const l=new t;(P.get(l)??[]).forEach(s=>{const i=s.getDependencies(),f=g.current.previous.get(s.action)??[];(i.length!==f.length||i.some((h,K)=>!Object.is(h,f[K])))&&(g.current.previous.set(s.action,[...i]),d.emit(s.action))})}),u.useLayoutEffect(()=>(d.emit(S.Mount),()=>void d.emit(S.Unmount)),[]),u.useEffect(()=>{d.emit(S.Node)},[]),u.useMemo(()=>[r,{dispatch(...[l,c]){E(l)?n.instance.emit(l,c):d.emit(l,c)},consume(){},get inspect(){return m.current.inspect}}],[r,d])}function _(e){const t=u.useRef(e);return u.useLayoutEffect(()=>{t.current=e},[e]),u.useMemo(()=>N(e,t),[e])}Object.defineProperty(o,"Op",{enumerable:!0,get:()=>w.Op}),Object.defineProperty(o,"Operation",{enumerable:!0,get:()=>w.Operation}),Object.defineProperty(o,"State",{enumerable:!0,get:()=>w.State}),o.Broadcaster=B,o.Error=T,o.Lifecycle=S,o.createAction=F,o.createDistributedAction=I,o.use=W,o.useAction=H,o.useActions=J,o.useSnapshot=_,o.utils=R,Object.defineProperty(o,Symbol.toStringTag,{value:"Module"})}));

package/dist/error/index.d.ts

@@ -1,4 +1,10 @@
-import { ErrorHandler, Props } from './types';
-export declare const ErrorContext: import('react').Context<ErrorHandler | undefined>;
-export declare function useActionError(): ErrorHandler | undefined;
-export declare function ActionError({ handler, children }: Props): import("react/jsx-runtime").JSX.Element;
+import { Props } from './types';
+export { useError } from './utils';
+/**
+ * Error boundary component for catching and handling errors from actions.
+ *
+ * @param props.handler - The error handler function to call when an error occurs.
+ * @param props.children - The children to render within the error boundary.
+ * @returns The children wrapped in an error context provider.
+ */
+export declare function Error({ handler, children }: Props): import("react/jsx-runtime").JSX.Element;

package/dist/error/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/error/utils.d.ts

@@ -0,0 +1,11 @@
+import { ErrorHandler } from './types.ts';
+/**
+ * React context for handling errors that occur within actions.
+ */
+export declare const ErrorContext: import('react').Context<ErrorHandler | undefined>;
+/**
+ * Hook to access the error handler from the nearest Error provider.
+ *
+ * @returns The error handler function, or undefined if not within an Error provider.
+ */
+export declare function useError(): ErrorHandler | undefined;

package/dist/hooks/index.d.ts

@@ -1,12 +1,12 @@
 import { Context, Model, Payload, Props, ActionsClass, Actions, UseActions } from '../types/index.ts';
 /**
- * Memoizes an action handler for performance optimization.
+ * Creates a memoized action handler.
  *
- * @template Model The type of the model.
- * @template Actions The type of the actions.
- * @template Action The specific action being handled.
- * @param {(context: Context<Model, Actions>, name: Action) => void} action The action handler function.
- * @returns {React.useCallback} The memoized action handler.
+ * @template M The type of the model.
+ * @template AC The type of the actions class.
+ * @template K The specific action key being handled.
+ * @param handler The action handler function that receives context and optional payload.
+ * @returns A memoized async function that executes the handler with error handling.
  */
 export declare function useAction<M extends Model, AC extends ActionsClass<any>, K extends Exclude<keyof AC, "prototype"> | never = never>(handler: (context: Context<M, AC>, payload: [K] extends [never] ? unknown : AC[K] extends Payload<infer P> ? P : unknown) => void | Promise<void> | AsyncGenerator | Generator): (context: Context<M, AC>, payload: [K] extends [never] ? unknown : AC[K] extends Payload<infer P> ? P : unknown) => Promise<void>;
 /**
@@ -44,7 +44,7 @@ export declare function useAction<M extends Model, AC extends ActionsClass<any>,
  *
  * // In your component
  * function Counter() {
- *   const [model, actions] = useActions();
+ *   const [model, actions] = useCounterActions();
  *
  *   return (
  *     <div>

package/dist/hooks/utils.d.ts

@@ -1,5 +1,5 @@
 import { RefObject } from 'react';
-import { Props } from '../types';
+import { Props } from '../types/index.ts';
 /**
  * @name withGetters
  * @description This function creates a new object with getters for each property of the input object.

package/dist/hooks/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { ActionError } from './error/index.tsx';
+export { Error } from './error/index.tsx';
 export { createAction, createDistributedAction } from './action/index.ts';
 export type { Pk, Context, ActionInstance, ActionsClass, UseActions, Actions, } from './types/index.ts';
 export { Lifecycle } from './types/index.ts';
@@ -7,3 +7,4 @@ export { Broadcaster } from './broadcast/index.tsx';
 export { useActions, useAction, useSnapshot } from './hooks/index.ts';
 export { Operation, Op, State } from 'immertation';
 export type { Box } from 'immertation';
+export { use } from './use/index.ts';

package/dist/types/index.d.ts

@@ -1,5 +1,5 @@
 import { Operation, Process, Inspect } from 'immertation';
-import { context } from '../use';
+export declare const context: unique symbol;
 export declare class Lifecycle {
     static Mount: symbol;
     static Node: symbol;
@@ -15,6 +15,8 @@ export type Payload<T = unknown> = symbol & {
     [PayloadKey]: T;
 };
 type PayloadType<A> = A extends Payload<infer P> ? P : never;
+type IsAsync<F> = F extends (...args: any[]) => Promise<any> ? true : false;
+type AssertSync<F> = IsAsync<F> extends true ? "Error: async functions are not allowed in produce" : F;
 type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
 export type Props = Record<string, unknown>;
 export type Action = symbol | string;
@@ -34,7 +36,7 @@ export type Context<M extends Model, AC extends ActionsClass<any>> = {
     model: M;
     signal: AbortSignal;
     actions: {
-        produce(ƒ: (model: M) => void): M;
+        produce<F extends (model: M) => void>(ƒ: F & AssertSync<F>): M;
         dispatch<A extends AC[keyof AC] & Payload<any>>(...args: [PayloadType<A>] extends [never] ? [A] : [A, PayloadType<A>]): void;
         annotate<T>(operation: Operation, value: T): T;
     };

package/dist/use/index.d.ts

@@ -1,5 +1,30 @@
-import { Field } from './types';
-export { context } from './utils';
+import { Field, Primitive } from './types.ts';
+export { context, entries } from './utils.ts';
+/**
+ * Action decorators for adding common functionality to action handlers.
+ */
 export declare const use: {
-    serial(): (_: unknown, field: Field) => void;
+    /**
+     * Ensures only one instance of an action runs at a time. When dispatched again,
+     * the previous instance is aborted via `context.signal`.
+     *
+     * @returns A decorator function for the action.
+     */
+    exclusive(): (_: undefined, field: Field) => void;
+    /**
+     * Automatically triggers an action when its primitive dependencies change.
+     * Dependencies must be primitives (strings, numbers, booleans, etc.) to avoid
+     * referential equality issues.
+     *
+     * @param getDependencies A function returning an array of primitive dependencies.
+     * @returns A decorator function for the action.
+     */
+    reactive(getDependencies: () => Primitive[]): (_: undefined, field: Field) => void;
+    /**
+     * Logs detailed timing and debugging information for the action, including
+     * start time, produce call timings, and total duration.
+     *
+     * @returns A decorator function for the action.
+     */
+    debug(): (_: undefined, field: Field) => void;
 };

package/dist/use/types.d.ts

@@ -1,8 +1,14 @@
-import { ActionsClass, Context, Model, Payload } from '../types';
-export type Field = ClassFieldDecoratorContext<object, Context<Model, ActionsClass<Record<string, Payload>>>>;
+import { ActionsClass, Context, Model, Payload } from '../types/index.ts';
+export type Primitive = string | number | boolean | null | undefined | symbol | bigint;
+export type Field = ClassFieldDecoratorContext<object, (...args: any[]) => any>;
 export type Args = Context<Model, ActionsClass<Record<string, Payload>>>;
 export type Instance = Record<string | symbol, unknown>;
 export type Method = (args: Args) => Promise<unknown>;
-export type ContextValue = {
+export type Internals = {
     controller: AbortController;
 };
+export type Entry = {
+    action: string | symbol;
+    getDependencies(): Primitive[];
+};
+export type Entries = Entry[];

package/dist/use/utils.d.ts

@@ -1,3 +1,12 @@
-import { ContextValue } from './types';
-export declare const contexts: WeakMap<object, ContextValue>;
-export declare const context: unique symbol;
+import { context } from '../types/index.ts';
+import { Internals, Entries } from './types.ts';
+export { context };
+export declare const internals: WeakMap<object, Internals>;
+export declare const entries: WeakMap<object, Entries>;
+/**
+ * Extracts a readable name from an action symbol or string.
+ *
+ * @param name The action name as a symbol or string.
+ * @returns A human-readable string representation of the action name.
+ */
+export declare function actionName(name: string | symbol): string;

package/dist/use/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/index.d.ts

@@ -1,5 +1,11 @@
 import { ActionsClass, Context, Model, Payload, Pk } from '../types/index.ts';
-export { default as sleep } from './sleep/index.ts';
+/**
+ * Returns a promise that resolves after the specified number of milliseconds.
+ *
+ * @param ms The number of milliseconds to sleep.
+ * @returns A promise that resolves after the delay.
+ */
+export declare function sleep(ms: number): Promise<void>;
 /**
  * Generates a unique primary key.
  * @returns A new unique symbol representing the primary key.

package/dist/utils/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chizu",
-  "version": "0.2.34",
+  "version": "0.2.35",
   "type": "module",
   "license": "MIT",
   "main": "./dist/chizu.js",
@@ -44,6 +44,7 @@
     "@faker-js/faker": "^10.1.0",
     "@jest/globals": "^30.2.0",
     "@mobily/ts-belt": "^3.13.1",
+    "@playwright/test": "^1.57.0",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
@@ -64,6 +65,7 @@
     "jest": "^30.2.0",
     "jest-environment-jsdom": "^30.2.0",
     "lucide-react": "^0.555.0",
+    "madge": "^8.0.0",
     "prettier": "^3.7.4",
     "ramda": "^0.32.0",
     "react": "^19.2.1",

package/dist/decorators/index.d.ts

@@ -1,6 +0,0 @@
-export declare function Distributed(): (_value: unknown, context: ClassFieldDecoratorContext) => (initialValue: any) => any;
-declare const _default: {
-    Synchronous(target: any, propertyKey: string): (...args: any[]) => any;
-    Debounce(target: any, propertyKey: string): (...args: any[]) => any;
-};
-export default _default;

package/dist/utils/sleep/index.d.ts

@@ -1 +0,0 @@
-export default function sleep(ms: number): Promise<void>;