import { Operation, Process, Inspect as ImmInspect, Box } from 'immertation'; import { ActionId, Task, Tasks, CurrentTask } from '../boundary/components/tasks/types.js'; import { Fault } from '../error/types.js'; import { Env } from '../boundary/components/env/types.js'; import { Invocation, LocalInvocation } from '../resource/types.js'; import { WithHandle } from '../with/types.js'; import * as React from "react"; /** * Bounded recursion depths for {@link Inspect}. Matches Immertation's * `DepthLimiter` shape so the two stay in lock-step. */ type DepthLimiter = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8]; /** Union of all keys across each arm of `T`. */ type UnionKeys = T extends unknown ? keyof T : never; /** The value at `K` for each arm of `T`, falling back to `undefined` if `K` is absent on that arm. */ type ValueAt = T extends unknown ? K extends keyof T ? T[K] : undefined : never; /** * March-hare's `Inspect` wraps Immertation's so that property * navigation works when `T` is a discriminated union (e.g. the App's * Env union). For each key that appears on **any** union arm, the * resulting Inspect is `Inspect>` — arms missing * the key contribute `undefined`, so optional chaining stays sound. * * For a single concrete `T`, the wrapper is transparent. */ export type Inspect = ImmInspect & ([D] extends [0] ? object : { [K in UnionKeys as ValueAt extends (...args: unknown[]) => unknown ? never : K]: Inspect, DepthLimiter[D]>; }); /** * Fetch-configured chain returned from `.exceeds(...)` and * `.isolated()`. Awaiting the chain runs the fetch with whichever * options are set; `.evict()` is intentionally absent because the * "configured a fetch then evicted instead" sequence has no coherent * meaning — eviction is always available off the bare * `context.actions.resource(...)` call. * * Concurrent callers with the same `(Resource, params)` automatically * share a single in-flight fetch — one network request, every * caller resolves with the same payload. The shared fetch runs on a * detached `AbortController` so one caller's abort never cancels work * other callers are still waiting on; when every caller has released * (their `context.task.controller` aborted) the shared controller is * aborted too. Chain `.isolated()` to opt out for the rare case that * needs an independent request. */ export type ResourceFetch = PromiseLike & { /** * Skip the fetch when the cached payload is within `duration`. * Accepts a `Temporal.Duration`, a `DurationLike` object * (`{ minutes: 5 }`), or an ISO 8601 string (`"PT5M"`). */ readonly exceeds: (duration: Temporal.DurationLike) => ResourceFetch; /** * Opt this call out of the default `(Resource, params)` coalesce * path. The fetch fires as an independent network request against * the caller's own `context.task.controller` — no joining of * any in-flight fetch, no refcounted detached controller. Aborting * the caller's task cancels the network exactly as a regular fetch * would. * * Reach for this only when two callers need parallel fetches with * byte-identical params and the difference in intent genuinely can't * be modelled by differing params. The default is almost always * what you want. */ readonly isolated: () => ResourceFetch; }; /** * Chainable handle returned from `context.actions.resource(invocation)`. * Either resolve to the fetched value (`.exceeds`/`.isolated` + await) * or drop the cache slot (`.evict`) — the two paths are mutually * exclusive, so once `.exceeds` or `.isolated` runs the chain narrows * to {@link ResourceFetch} and `.evict` is no longer available. */ /** * Handle returned from `context.actions.resource(invocation)` when the * invocation came from a local (fetcherless) Resource. There is no * fetch to await and no freshness window to configure, so the handle * is not thenable and carries no `.exceeds(...)`/`.isolated()` — * only the two cache transitions a local Resource supports. */ export type LocalResourceCall = { /** * Write `value` into the slot addressed by the originating call's * params, then fire the Resource's `.action()` auto-broadcast with * the value as the payload and the params as the channel — the * same cache-write-then-broadcast sequence a successful fetch * performs on a fetched Resource. Synchronous; subscribers observe a * warm cache. * * ```ts * context.actions.resource(resource.draft({ id: 5 })).set(draft); * ``` */ readonly set: (value: T) => void; /** * Drop cache entries for the primed resource. Identical semantics to * the fetched variant's `.evict` — partial-match on the stored * params, `null` broadcast per evicted slot. */ readonly evict: (where?: Record) => void; }; /** * Dispatch surface exposed as `context.actions.resource`. Overloaded on * the invocation's origin: a local (fetcherless) invocation resolves to * a {@link LocalResourceCall} (`.set`/`.evict` only), a fetched * invocation to a {@link ResourceCall} (awaitable fetch chain plus * `.evict`). `.nuke(where?)` spans every Resource in the process. */ export type ResourceDispatcher = ((invocation: LocalInvocation) => LocalResourceCall) & ((invocation: Invocation) => ResourceCall) & { nuke(where?: Record): void; }; export type ResourceCall = ResourceFetch & { /** * Drop cache entries for the primed resource without fetching. With * no argument, uses the params from the originating call as the * pattern. With an argument, evicts every stored entry whose params * satisfy the pattern's keys (partial match — extra keys in * the stored params are ignored). * * Strictly synchronous — the Adapter contract is sync, so the * warm-start `Map` and the user adapter both settle in the current * tick. Async backends fire-and-forget their underlying delete from * inside the adapter body; the call site doesn't `await` anything. * * The `where` pattern is typed as `Record` rather * than `Partial

` because the resource's params type `P` isn't * threaded through the chain. Pass the literal you'd pass to the * underlying fetcher — TypeScript won't catch typos in pattern * keys, so prefer the no-argument form when possible. * * ```ts * // Drop the {id: 5} slot. * context.actions.resource(resource.user({ id: 5 })).evict(); * * // Drop every user slot whose stored params include name "Adam". * context.actions.resource(resource.user()).evict({ name: "Adam" }); * ``` */ readonly evict: (where?: Record) => void; }; export type { ActionId, Box, Task, Tasks, CurrentTask }; /** * Type for objects with a Brand.Action symbol property. * Used for type-safe access to the action symbol. */ export type BrandedAction = { readonly [K in typeof Brand.Action]: symbol; }; /** * Type for objects with a Brand.Broadcast symbol property. * Used for type-safe access to the broadcast flag. */ export type BrandedBroadcast = { readonly [K in typeof Brand.Broadcast]: boolean; }; /** * Type for objects with a Brand.Multicast symbol property. * Used for type-safe access to the multicast flag. */ export type BrandedMulticast = { readonly [K in typeof Brand.Multicast]: boolean; }; /** * Base type for any object that may contain branded symbol properties. * Used as a permissive input type for action utilities. */ export type BrandedObject = { readonly [x: symbol]: unknown; }; /** * Recursive readonly. Locks every nested property so that read-only * projections on `context` (model, data, env) reject direct assignment * — mutation must go through `context.actions.produce(...)`. * * Function types pass through untouched so method calls (e.g. * `AbortController#abort`) remain callable. Built-in mutable containers * are mapped to their readonly counterparts. * * @internal */ export type DeepReadonly = T extends (...args: never) => unknown ? T : T extends ReadonlyArray ? ReadonlyArray> : T extends ReadonlyMap ? ReadonlyMap, DeepReadonly> : T extends ReadonlySet ? ReadonlySet> : T extends object ? { readonly [K in keyof T]: DeepReadonly; } : T; /** * Union type representing any valid action that can be passed to action utilities. * Covers raw ActionIds (symbol/string), branded action values (`Action()` / * `Lifecycle.*()` results carrying `Brand.Action`), and any other symbol-keyed * branded object. */ export type AnyAction = ActionId | BrandedAction | BrandedObject; /** * Internal symbols used as brand keys to distinguish typed objects at runtime. * These enable TypeScript to differentiate between HandlerPayload, BroadcastPayload, * and channeled actions through branded types. * @internal */ export declare class Brand { /** Brand key for HandlerPayload type */ static readonly Payload: unique symbol; /** Brand key for BroadcastPayload type */ static readonly Broadcast: unique symbol; /** Brand key for MulticastPayload type */ static readonly Multicast: unique symbol; /** * Brand key for OmnicastPayload type. Carries the action's runtime * schema (or `null` for payloadless events) so the SSE bridge can * validate incoming envelopes before dispatching them. */ static readonly Omnicast: unique symbol; /** Access the underlying symbol from an action */ static readonly Action: unique symbol; /** Identifies channeled actions (result of calling Action(channel)) */ static readonly Channel: unique symbol; /** * Phantom brand carrying the action's literal name. Used purely at the * type level to make `Action("X")` and `Action("Y")` produce * structurally-distinct types so `dispatch`/`useAction` can reject * symbols imported from a class outside `AC`. */ static readonly Name: unique symbol; /** * Phantom brand identifying lifecycle actions returned by * `Lifecycle.Mount()`, `Lifecycle.Paint()`, `Lifecycle.Unmount()`, * `Lifecycle.Error()`, and `Lifecycle.Update()`. Carries the lifecycle's * literal kind so that `useAction` can pick distinct overloads — in * particular, * `Lifecycle.Update` resolves its payload to `Partial>` * against the surrounding `useActions` data generic instead of the * factory-level `Record` placeholder. Without this * brand a user-defined `Action

("Update")` would collide with the * lifecycle overload. */ static readonly Lifecycle: unique symbol; /** * Identifies reactive bindings — the result of calling a * `Lifecycle.Reactive` static with a value at the `useAction` site * (e.g. `Actions.User(user)`). The binding carries the observed value * so the registration can diff it between renders and dispatch through * the standard handler pipeline when it changes. */ static readonly Reactive: unique symbol; } /** * Internal symbol for the global `Lifecycle.Fault` broadcast. Exposed so the * dispatch pipeline can fire faults without depending on the `Lifecycle` * class at runtime. * * @internal */ export declare const FaultSymbol: unique symbol; /** * Internal symbol for the global `Lifecycle.Env` broadcast. The env * mutation path in `useActions` fires this symbol whenever a * `produce({ env })` call changes the slot reference. * * @internal */ export declare const EnvSymbol: unique symbol; /** * Factory functions for lifecycle actions. * * Each call returns a **unique** action symbol so that each component can * subscribe independently. Assign the result as a static property in your * Actions class: * * @example * ```ts * export class Actions { * static Mount = Lifecycle.Mount(); * static Paint = Lifecycle.Paint(); * static Unmount = Lifecycle.Unmount(); * static Error = Lifecycle.Error(); * static Update = Lifecycle.Update(); * * static Increment = Action("Increment"); * } * ``` * * `Lifecycle.Fault` and `Lifecycle.Env` are singleton broadcasts (not * factories). All components subscribe to the same shared symbol — * `Fault` delivers global fault notifications, `Env` delivers per-`Boundary` * env-change notifications. */ export declare class Lifecycle { /** Creates a Mount lifecycle action. Triggered once on component mount (`useLayoutEffect`). */ static Mount(): LifecyclePayload; /** * Creates a Paint lifecycle action. Triggered once after the browser has * committed the first frame (`useEffect`). Pairs with {@link Lifecycle.Mount} * (pre-paint) — use Paint for work that should not delay the first * paint: analytics “viewed” events, focus management, scroll-into-view, * non-blocking prefetch, etc. */ static Paint(): LifecyclePayload; /** Creates an Unmount lifecycle action. Triggered when the component unmounts. */ static Unmount(): LifecyclePayload; /** Creates an Error lifecycle action. Triggered when an action throws. Receives `Fault` as payload. */ static Error(): LifecyclePayload; /** * Creates an Update lifecycle action. Fires once on mount — with the * initial data keys, or `{}` when there is no data — then on every * subsequent `context.data` change. The handler payload is typed as * `Partial>` at the subscription site: only the keys whose * values changed since the previous render are present. The mount fire runs * while `context.phase` is `Mounting`. */ static Update(): LifecyclePayload, never, "Update">; /** * Creates a Reactive lifecycle action. Declare it as a static, then bind * an external value at the `useAction` site by calling the static with * it — the handler fires through the standard dispatch pipeline * whenever the bound value changes between renders, receiving the latest * value as its payload: * * ```ts * export class Actions { * static User = Lifecycle.Reactive("User"); * } * * const { data: user } = useQuery({ queryKey: ["user"], queryFn: fetchUser }); * * actions.useAction(Actions.User(user), async (context, user) => { * context.actions.produce(({ model }) => void (model.profile = user)); * }); * ``` * * Changes are detected with `Object.is` against the last-dispatched * value. The handler fires once on mount with the bound value — * whether defined (e.g. a hydrated React Query cache) or `undefined` * — then again on every change. Like `Lifecycle.Update`, mount is * treated as the first change. * * Subscribing with the uncalled static (`useAction(Actions.User, * handler)`) receives every reactive dispatch of the action, and * `dispatch(Actions.User, value)` re-fires all handlers manually. * * @param name Optional name surfaced in taps and fault reports. */ static Reactive

(name?: string): ReactivePayload

; /** * Global fault broadcast. Receives a `Fault` whenever any action in the * `` errors, times out, or is supplanted. Subscribe via * `actions.useAction(Lifecycle.Fault, handler)`. * * Unlike the per-component `Lifecycle.Error()` factory, `Fault` is a single * shared broadcast — every subscriber points at the same symbol. * * @example * ```tsx * const actions = useActions(); * * actions.useAction(Lifecycle.Fault, (context, fault) => { * if (fault.reason === Reason.Errored) { * console.error(`Action "${fault.action}" failed`, fault.error); * } * }); * ``` */ static Fault: BroadcastPayload; /** * Global env-change broadcast. Receives the latest {@link Env} * snapshot whenever a `context.actions.produce(({ env }) => ...)` call * mutates the slot. Subscribe via * `actions.useAction(Lifecycle.Env, handler)` — or render against * it directly with `actions.stream(Lifecycle.Env, (env) => ...)`. * * Like `Lifecycle.Fault`, this is a singleton broadcast (not a factory): * every subscriber points at the same shared symbol. The latest value is * cached on the broadcast emitter so that late-mounting handlers and * streams receive the current env on mount. * * @example * ```tsx * actions.useAction(Lifecycle.Env, (context, env) => { * console.log("env changed", env); * }); * * // In JSX: * {actions.stream(Lifecycle.Env, (env) => ( * {env.locale} * ))} * ``` */ static Env: BroadcastPayload; } /** * Distribution modes for actions. * * - **Unicast** – Action is scoped to the component that defines it and cannot be * consumed by other components. This is the default behaviour. * - **Broadcast** – Action is distributed to all mounted components that have * defined a handler for it. Values are cached for late-mounting components. * - **Multicast** – Action defines its own scope. Components reach it by * rendering inside a `` produced by `app.Scope()`. * * @example * ```ts * export class MulticastActions { * static Mood = Action("Mood", Distribution.Multicast); * } * * export const scope = app.Scope(); * * // Wrap the subtree where the scope applies. * export default function Mood() { * return ( * * * * * ); * } * * // Dispatch / subscribe — no extra options. * actions.dispatch(MulticastActions.Mood, mood); * actions.useAction(MulticastActions.Mood, (context, mood) => { ... }); * ``` */ export declare enum Distribution { /** Action is scoped to the component that defines it. This is the default. */ Unicast = "unicast", /** Action is broadcast to all mounted components and can be consumed. */ Broadcast = "broadcast", /** Action is multicast to every component inside its ``. */ Multicast = "multicast" } /** * Marker produced by `Distribution.Omnicast(schema?)` and consumed by the * `Action` factory. Carries the runtime schema (or `null` for payloadless * events) that omnicast dispatches validate against — the payload * type `T` is inferred from the schema at the declaration site. */ export type OmnicastDistribution = { readonly [Brand.Omnicast]: null | Schema; readonly [Brand.Channel]?: C; }; export declare namespace Distribution { /** * Declares an action as omnicast — broadcast within its own * ``, and additionally carried to every other connected client * when the App is configured with an `sse` endpoint. The payload type is * inferred from the supplied Zod-style schema (any object exposing a * `parse(value)` method), so the compile-time type and the runtime * validator can never drift apart. Envelopes arriving over the wire are * validated with `parse` and rejected when invalid (`Reason.Rejected` * through `Lifecycle.Error` / `Lifecycle.Fault`); omit the schema for * payloadless events. * * For channeled omnicast actions, supply both generics explicitly — * the payload type alias and the channel shape. Channel values must be * JSON-serialisable primitives (`string`, `number`, `boolean`) as they * travel inside the wire envelope. * * @example * ```ts * export class Cat { * static Adopted = Action("Cat.Adopted", Distribution.Omnicast(Payload.Adoption)); * * static Renamed = Action( * "Cat.Renamed", * Distribution.Omnicast(Payload.Cat), * ); * } * * export class Cattery { * static Opened = Action("Cattery.Opened", Distribution.Omnicast()); * } * ``` */ function Omnicast(): OmnicastDistribution; function Omnicast(schema: Schema): OmnicastDistribution; } /** * Lifecycle phase of a component using useActions. * Tracks whether the component is in the process of mounting, fully mounted, * unmounting, or completely unmounted. * * @example * ```ts * actions.useAction(Actions.Counter, (context, payload) => { * if (context.phase === Phase.Mounting) { * // Handler called during mount (e.g., cached distributed action value) * } else if (context.phase === Phase.Mounted) { * // Handler called after component is fully mounted * } * }); * ``` */ export declare enum Phase { /** Component is in the process of mounting (before useLayoutEffect completes). */ Mounting = "mounting", /** Component has fully mounted (after useLayoutEffect). */ Mounted = "mounted", /** Component is in the process of unmounting. */ Unmounting = "unmounting", /** Component has fully unmounted. */ Unmounted = "unmounted" } /** * Primary key type for identifying entities in collections. * Can be undefined (not yet assigned), a symbol (temporary/local), or a concrete value T. * * @template T - The concrete primary key type (e.g., string, number) */ export type Pk = undefined | symbol | T; /** * Maybe-present field type — a value that may be a concrete `T`, * or `null` / `undefined` while loading, awaiting a fetch, or before * upstream data has arrived. Use this for model fields whose presence * is determined by async or external state. * * @template T - The concrete value type */ export type Maybe = T | null | undefined; /** * Base constraint type for model state objects. * Models must be plain objects with string keys. * * @template M - The specific model shape */ export type Model> = M; /** * Branded type for action objects created with `Action()`. * The phantom type parameters carry the payload and channel types at the type level. * * Actions wrap an internal symbol (used as event emitter keys) in a callable object. * When a channel type is specified, the action can be called to create a channeled dispatch. * * @template P - The payload type for the action * @template C - The channel type for channeled dispatches (defaults to never = no channel) * * @example * ```ts * // Action without channel support * const Increment = Action("Increment"); * dispatch(Increment, 5); * * // Action with channel support * const UserUpdated = Action("UserUpdated"); * dispatch(UserUpdated, user); // broadcast to all handlers * dispatch(UserUpdated({ UserId: 5 }), user); // channeled dispatch * ``` */ export type HandlerPayload

= { readonly [Brand.Action]: symbol; readonly [Brand.Payload]: P; readonly [Brand.Name]: Name; readonly [Brand.Broadcast]?: boolean; } & ([C] extends [never] ? unknown : { (channel: C): ChanneledAction; }); /** * Branded type returned by `Lifecycle.Mount`, `Lifecycle.Paint`, * `Lifecycle.Unmount`, `Lifecycle.Error`, and `Lifecycle.Update`. * Structurally identical to a `HandlerPayload` but carries a phantom * `Brand.Lifecycle` brand whose value is the lifecycle's literal kind. The * brand is what lets `useAction` and `Handlers` resolve `Lifecycle.Update`'s * payload to `Partial>` (against the surrounding `useActions` * data generic) instead of the factory-level `Record` * placeholder — a user-defined `Action

("Update")` would have * `Name = "Update"` but no `Brand.Lifecycle`, so it falls into the generic * payload overload as expected. * * @template P Payload type for the lifecycle. * @template C Channel filter (always `never` for lifecycles — they are * not channeled). * @template Name Literal name (`"Mount"`, `"Paint"`, `"Unmount"`, `"Error"`, `"Update"`). */ export type LifecyclePayload

= HandlerPayload & { readonly [Brand.Lifecycle]: Name; }; /** * Result of calling a `Lifecycle.Reactive` static with a value at the * `useAction` site (e.g. `Actions.User(user)`). Carries the observed * value alongside the action brands so the registration can diff it * against the previous render and dispatch through the standard handler * pipeline when it changes. * * Mirrors {@link ChanneledAction} — a per-render wrapper produced * by calling the declared static — but binds a payload value rather * than a channel filter. Bindings are subscribe-only: they are admitted * by `useAction` and excluded from `dispatch`. * * @template P The observed value type; also the handler payload type. * @template Name Literal name supplied to `Lifecycle.Reactive(name)`. */ export type ReactiveBinding

= { readonly [Brand.Action]: symbol; readonly [Brand.Payload]: P; readonly [Brand.Name]: Name; readonly [Brand.Reactive]: true; readonly value: P; }; /** * Branded type returned by `Lifecycle.Reactive`. Declared as a static on * an Actions class like every other lifecycle, and callable with the * observed value to produce a {@link ReactiveBinding} at the `useAction` * site. The `Brand.Lifecycle` value is always `"Reactive"` (the lifecycle * kind), independent of the user-supplied `Name`. * * @template P The observed value type; also the handler payload type. * @template Name Literal name supplied to `Lifecycle.Reactive(name)`. */ export type ReactivePayload

= HandlerPayload & { readonly [Brand.Lifecycle]: "Reactive"; (value: P): ReactiveBinding; }; /** * Result of calling an action with a channel argument. * Contains the action reference and the channel data for filtered dispatch. * * @template P - The payload type for the action * @template C - The channel type * * @example * ```ts * const UserUpdated = Action("UserUpdated"); * * // UserUpdated({ UserId: 5 }) returns ChanneledAction * dispatch(UserUpdated({ UserId: 5 }), user); * ``` */ export type ChanneledAction

= { readonly [Brand.Action]: symbol; readonly [Brand.Payload]: P; readonly [Brand.Channel]: C; readonly [Brand.Name]: Name; readonly [Brand.Broadcast]?: boolean; readonly channel: C; }; /** * `ChanneledAction` that carries the broadcast brand. Produced by calling * a broadcast `Action` with a channel (e.g. `Resource.action({ id: 5 })`, * or `UserBroadcast({ UserId: 5 })`). Any boundary subscriber can listen * to one, so it's admitted by `Subscribable` regardless of `AC` * — the same carve-out applied to `Lifecycle.Fault` / `Lifecycle.Env`. */ export type BroadcastChanneled

= ChanneledAction & { readonly [Brand.Broadcast]: true; }; /** * Branded type for broadcast action objects created with `Action()` and `Distribution.Broadcast`. * Broadcast actions are sent to all mounted components. Values are cached so that * late-mounting components receive the most recent payload. * * Late-mounting components receive the most recent cached payload via their * `useAction` handler during mount. Use `peek()` in a `Lifecycle.Mount` handler * to check whether a cached value exists before performing default fetches. * * This type extends `HandlerPayload` with an additional brand to enforce at compile-time * that only broadcast actions can be passed to `context.actions.final()`. * * @template P - The payload type for the action * @template C - The channel type for channeled dispatches (defaults to never) * * @example * ```ts * const SignedOut = Action("SignedOut", Distribution.Broadcast); * * // Resolve the latest value inside a handler * const user = await context.actions.final(SignedOut); * ``` */ export type BroadcastPayload

= HandlerPayload & { readonly [Brand.Broadcast]: true; }; /** * Branded type for multicast action objects created with `Action()` and `Distribution.Multicast`. * Multicast actions are dispatched to all components within a named scope boundary. * * When dispatching a multicast action, you MUST provide the scope name as the third argument: * ```ts * actions.dispatch(Actions.Multicast.Update, payload, { scope: Actions.Multicast.Scope }); * ``` * * Components receive multicast events only if they are descendants of a ``. * * @template P - The payload type for the action * @template C - The channel type for channeled dispatches (defaults to never) * * @example * ```tsx * export enum Scope { * Counter = "counter", * } * * class MulticastActions { * static Update = Action("Update", Distribution.Multicast(Scope.Counter)); * } * * // Reference from component-level Actions * class Actions { * static Multicast = MulticastActions; * } * * // Wrap the subtree where the scope applies via the withScope HOC. * export default withScope(Scope.Counter, function Counters() { * return ( * <> * * * * ); * }); * * // Dispatch — the scope is read from the action itself. * actions.dispatch(Actions.Multicast.Update, 42); * ``` */ export type MulticastPayload

= HandlerPayload & { readonly [Brand.Multicast]: true; }; /** * Minimal runtime validator contract satisfied by Zod schemas (and any * library exposing a Zod-style `parse`): given an untrusted value, either * return the typed value or throw. Used by `Omnicast` actions to validate * payloads arriving over the wire before they are dispatched locally. */ export type Schema = { parse(value: unknown): T; }; /** * Branded type for omnicast action objects created with `Action(name, * Distribution.Omnicast(schema?))`. An omnicast action is a broadcast * action that additionally travels between clients when the App is * configured with an `sse` endpoint; the brand carries the runtime schema * used to validate payloads received from the wire, or `null` for * payloadless events. */ export type OmnicastPayload

= ([C] extends [never] ? unknown : { (channel: C): ChanneledAction & { readonly [Brand.Omnicast]: null | Schema

; }; }) & BroadcastPayload & { readonly [Brand.Omnicast]: null | Schema

; }; /** * Extracts the payload type `P` from a `HandlerPayload

` or `ChanneledAction`. * Use this in handler signatures to get the action's payload type. * * Works with both plain actions and channeled actions: * - `Payload>` → `User` * - `Payload>` → `User` * * @template A - The action type (HandlerPayload or ChanneledAction) */ export type Payload = A extends { readonly [Brand.Payload]: infer P; } ? P : never; /** * Filter object for channeled actions. * Must be an object where each value is a non-nullable primitive. * * By convention, use uppercase keys (e.g., `{UserId: 4}` not `{userId: 4}`) * to distinguish filter keys from payload properties. * * **Matching direction:** the subscriber's filter is the constraint; * every key the subscriber supplies must be present and equal on the * dispatch channel. Extra keys on the dispatch channel are ignored, so a * dispatcher is free to be more specific than any single subscriber * needs. A subscriber that supplies no keys (uncalled action or empty * filter) matches every dispatch. * * @example * ```ts * actions.useAction(Actions.User({ UserId: 1 }), handler); * * actions.dispatch(Actions.User({ UserId: 1 }), payload); // Matches (exact) * actions.dispatch(Actions.User({ UserId: 2 }), payload); // No match (UserId mismatch) * actions.dispatch(Actions.User({ UserId: 1, Role: "admin" }), payload); // Matches (extra dispatch keys ignored) * actions.dispatch(Actions.User({}), payload); // No match (subscriber asked for UserId) * actions.dispatch(Actions.User, payload); // Matches ALL handlers (uncalled bypasses channel filtering) * ``` */ export type Filter = Record; /** * Union type representing either a plain action or a channeled action. * Used in `useAction` and `dispatch` signatures to accept both forms. * * @template A - The action type * * @example * ```ts * class Actions { * static UserUpdated = Action("UserUpdated", Distribution.Broadcast); * } * * // Subscribe to updates for a specific user (channeled) * actions.useAction(Actions.UserUpdated({ UserId: props.userId }), (context, user) => { * context.actions.produce((draft) => { * draft.model.user = user; * }); * }); * * // Dispatch to specific user (channeled) * actions.dispatch(Actions.UserUpdated({ UserId: user.id }), user); * * // Dispatch to ALL handlers (plain) * actions.dispatch(Actions.UserUpdated, user); * ``` */ export type ActionOrChanneled = A | ChanneledAction; /** * Type guard that produces a compile-time error if an async function is * passed. Used to enforce synchronous callbacks in `produce()`. * * The `[F]` tuple wrapping prevents distribution over function unions, and * checking the actual signature (`(...args: never[]) => Promise`) * sidesteps TypeScript's lenient `Promise`→`void` assignability that * would otherwise let an async recipe satisfy a `(draft) => void` * constraint. Async F collapses the argument type to `never`, which no * function value can satisfy. * * @internal */ type AssertSync = [F] extends [(...args: never[]) => Promise] ? never : F; /** * Base type for data props passed to useActions. * Represents any object that can be captured as reactive data. */ export type Props = Record; /** * Constraint type for action containers. * Actions are symbols grouped in an object (typically a class with static properties). */ export type Actions = object; /** * Internal result container for tracking Immertation processes during action execution. * @internal */ export type Result = { processes: Set; }; export type HandlerContext = { readonly model: DeepReadonly; readonly phase: Phase; readonly task: CurrentTask; readonly data: DeepReadonly; readonly tasks: ReadonlySet; readonly env: Readonly; readonly actions: { produce>; }) => void>(ƒ: F & AssertSync): void; dispatch(action: NoPayloadActions>>): Promise; dispatch>>>(action: A, payload: Payload): Promise; dispatch(action: NoPayloadActions>>, audience: Audience): Promise; dispatch>>>(action: A, audience: Audience, payload: Payload): Promise; /** * Mutates the SSE connection's tag set, changing which * `Audience.Private(tags)` dispatches this client receives. `add` and * `remove` are variadic and idempotent — only tags that actually * change the set reach the server. The returned promises resolve once * the server has acknowledged the mutation, so awaiting a mutator * before a dependent dispatch guarantees the subscription is * registered ahead of any tag-targeted replies. Mutations are * remembered and re-applied after reconnects. When the App has no * `sse` endpoint configured, the mutators resolve as no-ops. */ tag: { add(...tags: readonly [string, ...string[]]): Promise; remove(...tags: readonly [string, ...string[]]): Promise; /** True when the connection holds **all** of the supplied tags. */ has(...tags: readonly [string, ...string[]]): boolean; clear(): Promise; }; annotate(value: T, operation?: Operation): T; readonly inspect: Readonly>; resource: ResourceDispatcher; final(action: BroadcastPayload | MulticastPayload): Promise; peek(action: BroadcastPayload | MulticastPayload): T | null; }; }; /** * Return type for the useActions hook. * * A tuple containing: * 1. The current model state of type M * 2. An actions object with dispatch and inspect capabilities * 3. The current data snapshot of type D — the same React-owned values * that handlers read via `context.data`, exposed here for JSX consumption * so the view and the handler share a single named source of truth. * * @template M - The model type representing the component's state * @template AC - The actions class containing action definitions * @template D - The data type for reactive external values * * @example * ```tsx * const [model, actions, data] = useActions( * model, * () => ({ user, theme }), * ); * * // Access state * model.count; * * // Dispatch actions * actions.dispatch(Actions.Increment, 5); * * // Read React-owned dependencies in JSX (same values as context.data) * data.user.name; * * // Check pending state * actions.inspect.count.pending(); * ``` */ /** * Utility type for defining a single action handler function. * Use this when you need to type a specific handler directly. * * @template M - The model type * @template AC - The actions class type * @template K - The action key (keyof AC) — determines payload type via lookup * @template D - Optional data/props type (defaults to Props) * * @see {@link Handlers} for the recommended HKT pattern */ export type Handler = (context: HandlerContext, ...args: [Payload>] extends [never] ? [] : [payload: Payload>]) => void | Promise | AsyncGenerator | Generator; /** * String keys of `AC` excluding inherited `prototype` from class constructors. * When action containers are classes (`typeof MyActions`), TypeScript includes * `"prototype"` in `keyof`. Excluding it prevents `prototype` from appearing * as a handler key and avoids recursion into Function internals. */ type OwnKeys = Exclude; /** * Recursively flattens an actions class into the union of its leaf action * types. A "leaf" is any property whose own string keys are empty — the * branded `HandlerPayload` / `BroadcastPayload` / `MulticastPayload` values * produced by `Action(...)` and `Lifecycle.*()`. Nested namespace classes * (e.g. `static Broadcast = BroadcastActions`) are descended into. * * Used to constrain `dispatch` and `useAction` so that only actions owned by * the component's `AC` (plus the global `Lifecycle.Fault` / * `Lifecycle.Env`) can be referenced. */ export type LeafActions = AC extends void ? never : { [K in OwnKeys]: OwnKeys extends never ? AC[K] : LeafActions; }[OwnKeys]; /** * Maps each action in a union to its channeled-call variant, when one exists. * Distributes over unions so a mixed bag of leaf actions produces the union * of their `ChanneledAction` results. */ export type ChanneledOf = A extends OmnicastPayload ? [C] extends [never] ? never : ChanneledAction & { readonly [Brand.Omnicast]: null | Schema

; } : A extends HandlerPayload ? [C] extends [never] ? never : ChanneledAction : never; /** * Everything `dispatch` accepts for a given `AC`: leaf actions on the class * and their channeled-call variants. The shared `Lifecycle.Fault` broadcast * is excluded — it's library-internal and not user-dispatchable. */ export type Dispatchable = LeafActions | ChanneledOf>; /** * Everything `useAction` will subscribe to for a given `AC`. Includes: * * - `Dispatchable` — leaf actions on `AC` plus their channeled * variants. * - `Lifecycle.Fault` / `Lifecycle.Env` — shared boundary broadcasts. * - Any `LifecyclePayload` (`Lifecycle.Mount()`, `Lifecycle.Unmount()`, * etc.) — the runtime scans the handler registry for a matching * lifecycle brand on emit, so a self-declared lifecycle outside `AC` * still fires. * - Any broadcast-branded channeled action — resource auto-broadcasts * (`resource.x.action(...)`) live outside `AC` but any boundary * subscriber can listen to them. * - Any `ReactiveBinding` — the result of calling a * `Lifecycle.Reactive` static with a value (`Actions.User(user)`). * Bindings are subscribe-only, so they appear here but not in * `Dispatchable`. */ export type Subscribable = Dispatchable | typeof Lifecycle.Fault | typeof Lifecycle.Env | LifecyclePayload | BroadcastChanneled | ReactiveBinding; /** * Subset of a union of actions whose payload type is `never`. Used to split * `dispatch`/`useAction` into a no-payload and a with-payload overload so * TypeScript reports a clear "no overload matches" error instead of widening * the inferred action type when constraints don't match. */ export type NoPayloadActions = Extract; /** Subset of a union of actions whose payload type is non-`never`. */ export type WithPayloadActions = Exclude; /** * Subset of a union of actions carrying the omnicast brand. Omnicast * dispatches require an explicit {@link Audience} argument, so `dispatch` * splits its overloads on this boundary. */ export type OmnicastOnly = Extract; }>; /** Subset of a union of actions without the omnicast brand. */ export type WithoutOmnicast = Exclude; }>; /** * Explicit delivery audience for an omnicast dispatch. Omnicast actions * leave the machine, so the audience is a **required** second argument of * `dispatch` (before the payload, when there is one) — there is no * public-by-default. Construct one with `Audience.Public()` or * `Audience.Private(tags)`. */ export type Audience = { readonly tags: null | readonly string[]; }; export declare const Audience: { /** * Declares an omnicast dispatch as deliverable to **every** connected * client. Deliberately explicit — broadcasting to the world should * read as a decision at the call site, not a default. * * @example * ```ts * await context.actions.dispatch( * Actions.Omnicast.Cat.Adopted, * Audience.Public(), * adoption, * ); * ``` */ Public(): Audience; /** * Restricts an omnicast dispatch to clients holding **all** of the * given tags (holding extras is fine). At least one tag is required * — an empty list would silently behave as `Audience.Public()`, * so the parameter type demands a non-empty tuple. * * @example * ```ts * await context.actions.dispatch( * Actions.Omnicast.Cat.Adopted, * Audience.Private(["vip"]), * adoption, * ); * ``` */ Private(tags: readonly [string, ...string[]]): Audience; }; /** * Recursive mapped type for action handlers that mirrors the action class hierarchy. * * For leaf actions (values with no own string keys, i.e. `HandlerPayload`), produces * a handler function signature. For namespace objects (containing nested actions), * produces a nested `Handlers` object. * * Access handlers using bracket notation matching the action structure: * * @template M - The model type * @template AC - The actions class type * @template D - Optional data/props type (defaults to Props) * * @example * ```ts * import { Action, Distribution, type Handlers } from "march-hare"; * * class BroadcastActions { * static PaymentSent = Action("PaymentSent", Distribution.Broadcast); * static PaymentLink = Action( * "PaymentLink", * Distribution.Broadcast, * ); * } * * class Actions { * static SetName = Action("SetName"); * static Broadcast = BroadcastActions; * } * * type H = Handlers; * * // Flat actions * export const handleSetName: H["SetName"] = (context, name) => { ... }; * * // Nested actions use chained bracket notation * export const handlePaymentSent: H["Broadcast"]["PaymentSent"] = (context) => { ... }; * ``` */ export type Handlers = { [K in OwnKeys]: OwnKeys extends never ? AC[K] extends { readonly [Brand.Lifecycle]: "Update"; } ? (context: HandlerContext, changes: Partial>) => void | Promise | AsyncGenerator | Generator : (context: HandlerContext, ...args: [Payload>] extends [never] ? [] : [payload: Payload>]) => void | Promise | AsyncGenerator | Generator : Handlers; }; export type UseActions = [ Readonly, { /** * Dispatches an action with an optional payload. Multicast actions read * their scope from the action declaration, so no extra options are * required at the call site. */ dispatch(action: NoPayloadActions>>): Promise; dispatch>>>(action: A, payload: Payload): Promise; dispatch(action: NoPayloadActions>>, audience: Audience): Promise; dispatch>>>(action: A, audience: Audience, payload: Payload): Promise; inspect: Inspect; /** * Streams broadcast values declaratively in JSX using a render-prop pattern. * * Subscribes to the given broadcast action and re-renders when a new value * is dispatched. Returns `null` until the first dispatch. The renderer * receives the value and an inspect proxy for annotation tracking. * * @param action - The broadcast action to subscribe to. * @param renderer - Callback that receives value and inspect, returns React nodes. * @returns React nodes from the renderer, or null if no value has been dispatched. * * @example * ```tsx * return ( *

* ); * ``` */ stream(action: typeof Lifecycle.Env, renderer: (value: Readonly, inspect: Inspect) => React.ReactNode): React.ReactNode; stream(action: BroadcastPayload | BroadcastChanneled, renderer: (value: T, inspect: Inspect) => React.ReactNode): React.ReactNode; }, DeepReadonly ] & { /** * Dispatches an action with an optional payload — same as * `result[1].dispatch`, exposed on the tuple itself so call sites that * already have `actions` in scope can write `actions.dispatch(...)` * without indexing into `actions[1]`. */ dispatch(action: NoPayloadActions>>): Promise; dispatch>>>(action: A, payload: Payload): Promise; dispatch(action: NoPayloadActions>>, audience: Audience): Promise; dispatch>>>(action: A, audience: Audience, payload: Payload): Promise; /** * Registers an action handler with the current scope. * Types are pre-baked from the `channel.use(...)` call, so no type * parameter is needed. * * Supports two subscription patterns: * 1. **Plain action** - Receives ALL dispatches for that action (including channeled ones) * 2. **Channeled action** `Action(channel)` - Receives only dispatches matching the channel * * @param action - The action or channeled action (e.g., `Action({ UserId: 1 })`) * @param handler - The handler function receiving context and payload * * @example * ```ts * const context = useContext(); * const actions = context.useActions(model); * * // Subscribe to ALL UserUpdated events * actions.useAction(Actions.UserUpdated, (context, user) => { * // Fires for any UserUpdated dispatch * }); * * // Subscribe to UserUpdated for a specific user only (channeled) * actions.useAction(Actions.UserUpdated({ UserId: props.userId }), (context, user) => { * // Only fires when dispatched with matching channel * }); * ``` */ useAction(action: NoPayloadActions>, handler: (context: HandlerContext) => void | Promise | AsyncGenerator | Generator): void; useAction(action: typeof Lifecycle.Env, handler: (context: HandlerContext, env: Readonly) => void | Promise | AsyncGenerator | Generator): void; useAction, { readonly [Brand.Lifecycle]: "Update"; }>>(action: A, handler: (context: HandlerContext, changes: Partial>) => void | Promise | AsyncGenerator | Generator): void; useAction>>(action: A, handler: (context: HandlerContext, payload: Payload) => void | Promise | AsyncGenerator | Generator): void; }; /** * Stable, typed dispatch function for the actions class `AC`. Same call * signatures as `actions.dispatch` returned by `useActions`, available * before the paired `useActions` has run via {@link Context}. */ export type Dispatch = { (action: NoPayloadActions>>): Promise; >>>(action: A, payload: Payload): Promise; (action: NoPayloadActions>>, audience: Audience): Promise; >>>(action: A, audience: Audience, payload: Payload): Promise; }; /** * Handle returned by `useContext()`. Exposes * `dispatch(action, payload?)` and a `useActions` method that materialises * the component-local model and reactive data against the same dispatch * target. Generics are declared on `useContext`; `useActions` inherits * them — the call site does not re-state `Model` / `Actions` / * `Data`. * * Note: this `Context` type is distinct from React's `useContext` / * `React.Context` — it's the March Hare action surface returned by * the `useContext` hook of this library. */ export type Context = { readonly actions: { dispatch: Dispatch; }; /** * Typed bag of handler factories bound to `M`. Methods accept lodash-style * dotted paths with array indices (e.g. `"a.b.c"`, `"items.0.id"`) and * autocomplete from the model. See {@link WithHandle}. */ readonly with: WithHandle; useActions(getData?: () => D): UseActions; useActions(model: M extends void ? never : M, getData?: () => D): UseActions; };