march-hare 0.6.0

package/dist/src/library/error/utils.d.ts

@@ -0,0 +1,15 @@
+import { Reason } from './types.ts';
+/**
+ * Determines the error reason based on what was thrown.
+ *
+ * @param error - The value that was thrown.
+ * @returns The appropriate Reason enum value.
+ */
+export declare function getReason(error: unknown): Reason;
+/**
+ * Gets an Error instance from a thrown value.
+ *
+ * @param error - The value that was thrown.
+ * @returns An Error instance (original if already Error, wrapped otherwise).
+ */
+export declare function getError(error: unknown): Error;

package/dist/src/library/hooks/index.d.ts

@@ -0,0 +1,43 @@
+import { Data } from './types.ts';
+import { Model, Props, Actions, UseActions } from '../types/index.ts';
+export { With } from './utils.ts';
+/**
+ * A hook for managing state with actions.
+ *
+ * Call `useActions` first, then use `actions.useAction` to bind handlers
+ * to action symbols. Types are pre-baked from the generic parameters, so
+ * no additional type annotations are needed on handler calls.
+ *
+ * The hook returns a result containing:
+ * 1. The current model state
+ * 2. An actions object with `dispatch`, `inspect`, and `useAction`
+ *
+ * The `inspect` property provides access to Immertation's annotation system,
+ * allowing you to check for pending operations on model properties.
+ *
+ * @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.
+ * @param initialModel The initial model state.
+ * @param getData Optional function that returns reactive values as data.
+ *   Values returned are accessible via `context.data` in action handlers,
+ *   always reflecting the latest values even after await operations.
+ * @returns A result `[model, actions]` with pre-typed `useAction` method.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const actions = useActions<Model, typeof Actions>(model);
+ *
+ * // Without a model (actions-only)
+ * const actions = useActions<void, typeof Actions>();
+ *
+ * // With reactive data
+ * const actions = useActions<Model, typeof Actions, { query: string }>(
+ *   model,
+ *   () => ({ query: props.query }),
+ * );
+ * ```
+ */
+export declare function useActions<_M extends void = void, A extends Actions | void = void, D extends Props = Props>(getData?: Data<D>): UseActions<void, A, D>;
+export declare function useActions<M extends Model, A extends Actions | void = void, D extends Props = Props>(initialModel: M, getData?: Data<D>): UseActions<M, A, D>;

package/dist/src/library/hooks/types.d.ts

@@ -0,0 +1,72 @@
+import { default as EventEmitter } from 'eventemitter3';
+import { RefObject } from 'react';
+import { Model, HandlerContext, Actions, Props, Tasks, ActionId, Phase, Filter } from '../types/index.ts';
+import { BroadcastEmitter } from '../boundary/components/broadcast/utils.ts';
+import { ScopeContext } from '../boundary/components/scope/types.ts';
+/**
+ * Function signature for action handlers registered via `useAction`.
+ * Receives the reactive context and payload, returning void or a promise/generator.
+ *
+ * @template M - The model type
+ * @template A - The actions class type
+ * @template D - The data props type
+ */
+export type Handler<M extends Model | void = Model, A extends Actions | void = Actions, D extends Props = Props> = (context: HandlerContext<M, A, D>, payload: unknown) => void | Promise<void> | AsyncGenerator | Generator;
+/**
+ * Entry for an action handler with a reactive channel getter.
+ * When getChannel returns undefined, the handler fires for all dispatches.
+ * When getChannel returns a channel, dispatches must match.
+ */
+export type HandlerEntry<M extends Model | void = Model, A extends Actions | void = Actions, D extends Props = Props> = {
+    handler: Handler<M, A, D>;
+    getChannel: () => Filter | undefined;
+};
+/**
+ * Internal scope for tracking registered action handlers.
+ * Maps action IDs to sets of handler entries (with optional channels).
+ *
+ * @template M - The model type
+ * @template A - The actions class type
+ * @template D - The data props type
+ */
+export type Scope<M extends Model | void = Model, A extends Actions | void = Actions, D extends Props = Props> = {
+    /** All handlers for each action, with optional channels */
+    handlers: Map<ActionId, Set<HandlerEntry<M, A, D>>>;
+};
+/**
+ * Function type for the data snapshot passed to useActions.
+ * Returns the current reactive values to be captured in the context.
+ *
+ * @template D - The data props type
+ */
+export type Data<D extends Props = Props> = () => D;
+/**
+ * Return type for useDispatchers hook.
+ */
+export type Dispatchers = {
+    /** Set of registered broadcast action IDs */
+    broadcast: Set<ActionId>;
+    /** Set of registered multicast action IDs */
+    multicast: Set<ActionId>;
+};
+/**
+ * Configuration for {@link useLifecycles}.
+ */
+export type LifecycleConfig = {
+    /** Component-local event emitter for unicast action dispatch */
+    unicast: EventEmitter;
+    /** Shared broadcast emitter with cached values for cross-component events */
+    broadcast: BroadcastEmitter;
+    /** Global set of all in-flight tasks across components */
+    tasks: Tasks;
+    /** Tracked broadcast and multicast action sets for cached replay on mount */
+    dispatchers: Dispatchers;
+    /** Scope context for multicast cached replay (null when outside any scope) */
+    scope: ScopeContext;
+    /** Mutable ref tracking the component's current lifecycle phase */
+    phase: RefObject<Phase>;
+    /** Current snapshot of reactive data props for change detection */
+    data: Props;
+    /** Handler registry for lifecycle action discovery */
+    handlers: Map<ActionId, Set<unknown>>;
+};

package/dist/src/library/hooks/utils.d.ts

@@ -0,0 +1,198 @@
+import { RefObject } from 'react';
+import { Props, Model, Actions, Filter, ActionId, HandlerPayload, ChanneledAction, HandlerContext } from '../types/index.ts';
+import { default as EventEmitter } from 'eventemitter3';
+import { Dispatchers, LifecycleConfig, Scope } from './types.ts';
+import { isChanneledAction, getActionSymbol } from '../action/index.ts';
+import * as React from "react";
+/**
+ * Creates a new object with getters for each property of the input object.
+ * The getters retrieve the current value from a ref, ensuring that the latest value is always accessed.
+ */
+export declare function withGetters<P extends Props>(a: P, b: RefObject<P>): P;
+/**
+ * Checks if the given result is a generator or async generator object.
+ * Uses `Object.prototype.toString` which reliably returns
+ * `"[object Generator]"` or `"[object AsyncGenerator]"` regardless of
+ * the generator function's name.
+ */
+export declare function isGenerator(result: unknown): result is Generator | AsyncGenerator;
+/**
+ * Sentinel passed as the dispatch channel during mount replay. Channeled
+ * handlers check for this to skip replay &mdash; they require specific
+ * channel context and cannot meaningfully process a replay without it.
+ *
+ * @internal
+ */
+export declare const replay: unique symbol;
+/**
+ * Invokes all listeners for an event and returns a promise that resolves
+ * when every handler has settled. For {@link BroadcastEmitter} instances the
+ * payload is cached before listeners fire so late-mounting components still
+ * see the latest value.
+ *
+ * @internal
+ */
+export declare function emitAsync(emitter: EventEmitter, event: string | symbol, ...args: unknown[]): Promise<void>;
+/**
+ * Emits lifecycle events for component mount and DOM attachment.
+ * Also invokes broadcast action handlers with cached values on mount.
+ * Updates the phase ref to track the component's current lifecycle state.
+ *
+ * The Mount effect skips when `phase` is already `Mounted` — this catches
+ * Strict Mode's dev-only double-invocation. It accepts both `Mounting` (first
+ * mount) and `Unmounted` (re-mount after `<Activity>` show) as entry states
+ * so that hidden-then-shown subtrees correctly re-emit Mount.
+ *
+ * Phase transitions:
+ * - First mount:           Mounting → Mounted
+ * - Activity hide / show:  Mounted → Unmounting → Unmounted → Mounting → Mounted
+ */
+export declare function useLifecycles({ unicast, broadcast, dispatchers, scope, phase, data, handlers, }: LifecycleConfig): void;
+/**
+ * Creates a data proxy for a given object, returning a memoized version.
+ * The proxy provides stable access to the object's properties,
+ * even as the original object changes across renders.
+ *
+ * This is an internal utility used by useActions to provide stable
+ * access to reactive values in async action handlers via `context.data`.
+ *
+ * @template P The type of the object.
+ * @param props The object to create a data proxy for.
+ * @returns A memoized data proxy of the object.
+ */
+export declare function useData<P extends Props>(props: P): P;
+/**
+ * Handler factories that wire an action directly to a model field.
+ *
+ * - {@link With.Update} assigns the dispatched payload to `model[key]`.
+ * - {@link With.Invert} flips a boolean field on `model[key]`.
+ *
+ * Both are typed so the call site fails to compile when `key` is missing or
+ * has an incompatible type.
+ *
+ * @example
+ * ```ts
+ * import { With } from "march-hare";
+ *
+ * type Model = { name: string; sidebar: boolean };
+ *
+ * class Actions {
+ *   static SetName = Action<string>("SetName");
+ *   static ToggleSidebar = Action("ToggleSidebar");
+ * }
+ *
+ * actions.useAction(Actions.SetName, With.Update("name"));
+ * actions.useAction(Actions.ToggleSidebar, With.Invert("sidebar"));
+ * ```
+ */
+export declare const With: {
+    /**
+     * Returns a handler that assigns the action payload to `model[key]`.
+     *
+     * Type-checks at the call site: the payload type must be assignable to
+     * the model property's type, and the key must exist on the model.
+     */
+    Update<K extends string>(key: K): <M extends Model, A extends Actions | void, D extends Props, P extends K extends keyof M ? M[K] : never>(context: HandlerContext<M, A, D>, payload: P) => void;
+    /**
+     * Returns a handler that inverts a boolean field on the model.
+     *
+     * Type-checks at the call site: `model[key]` must be a boolean.
+     */
+    Invert<K extends string>(key: K): <M extends Model & Record<K, boolean>, A extends Actions | void, D extends Props>(context: HandlerContext<M, A, D>) => void;
+};
+/**
+ * Scans a handler registry for a lifecycle action of the given type.
+ *
+ * When lifecycle actions become per-class instances (via `Lifecycle.Mount()`),
+ * each Actions class has its own unique symbol. Emission sites can no longer
+ * emit to a shared singleton — they must discover the component's lifecycle
+ * action by scanning the registry keys for matching lifecycle prefixes.
+ *
+ * Handler maps typically contain 5–15 entries, so the O(n) scan is trivial.
+ *
+ * @param handlers The handler map from a component's scope.
+ * @param type The lifecycle type to find (e.g. `"Mount"`, `"Unmount"`, `"Error"`).
+ * @returns The matching ActionId, or `null` if no lifecycle action of that type is registered.
+ *
+ * @internal
+ */
+export declare function findLifecycleAction(handlers: Map<ActionId, Set<unknown>>, type: string): ActionId | null;
+export { isChanneledAction, getActionSymbol };
+/**
+ * Manages sets of broadcast and multicast action IDs.
+ *
+ * This hook creates stable refs for tracking which actions have been registered
+ * as broadcast or multicast within a component. These sets are used to:
+ * - Replay cached broadcast values on mount
+ * - Track multicast subscriptions for scope-based dispatch
+ *
+ * @returns Object with `broadcast` and `multicast` Sets for action tracking
+ *
+ * @example
+ * ```ts
+ * const actions = useDispatchers();
+ *
+ * // Register a broadcast action
+ * actions.broadcast.add(getActionSymbol(MyBroadcastAction));
+ *
+ * // Check if an action is registered as multicast
+ * if (actions.multicast.has(actionId)) {
+ *   // Handle multicast dispatch
+ * }
+ * ```
+ *
+ * @internal
+ */
+export declare function useDispatchers(): Dispatchers;
+/**
+ * Registers an action handler within a component's scope.
+ *
+ * This hook binds a handler function to an action, supporting both regular and channeled
+ * actions. The handler is wrapped with `useEffectEvent` to ensure it always has access
+ * to the latest closure values while maintaining a stable reference.
+ *
+ * For generator handlers (sync or async), the hook automatically iterates through
+ * all yielded values to completion.
+ *
+ * @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
+ *
+ * @param scope - Ref to the component's handler scope containing registered handlers
+ * @param action - The action to register (ActionId, HandlerPayload, or ChanneledAction)
+ * @param handler - The handler function to invoke when the action is dispatched
+ *
+ * @example
+ * ```ts
+ * useRegisterHandler(scope, Actions.Increment, async (context, payload) => {
+ *   context.actions.produce((draft) => {
+ *     draft.model.count += payload;
+ *   });
+ * });
+ *
+ * // With channeled action
+ * useRegisterHandler(scope, Actions.UserUpdated({ UserId: 5 }), (context, user) => {
+ *   // Only called when UserId matches 5
+ * });
+ * ```
+ *
+ * @internal
+ */
+export declare function useRegisterHandler<M extends Model | void, A extends Actions | void, D extends Props>(scope: React.RefObject<Scope<M, A, D>>, action: ActionId | HandlerPayload | ChanneledAction, handler: (context: HandlerContext<M, A, D>, payload: unknown) => void | Promise<void> | AsyncGenerator | Generator): void;
+/**
+ * Checks if a dispatch channel matches a registered handler channel.
+ * All properties in the dispatch channel must match the corresponding properties in the registered channel.
+ *
+ * @param dispatchChannel - The channel from the dispatch call (from ChanneledAction)
+ * @param registeredChannel - The channel registered with useAction
+ * @returns `true` if all dispatch channel properties match the registered channel
+ *
+ * @example
+ * ```ts
+ * matchesChannel({ UserId: 1 }, { UserId: 1 }); // true
+ * matchesChannel({ UserId: 1 }, { UserId: 2 }); // false
+ * matchesChannel({ UserId: 1 }, { UserId: 1, Role: "admin" }); // true (subset match)
+ * matchesChannel({ UserId: 1, Role: "admin" }, { UserId: 1 }); // false (missing Role)
+ * ```
+ */
+export declare function matchesChannel(dispatchChannel: Filter, registeredChannel: Filter): boolean;

package/dist/src/library/index.d.ts

@@ -0,0 +1,16 @@
+export { Action } from './action/index.ts';
+export { Distribution, Lifecycle } from './types/index.ts';
+export { Reason, AbortError, TimeoutError } from './error/index.ts';
+export { Operation, Op, State } from 'immertation';
+export { annotate } from './annotate/index.ts';
+export { Boundary } from './boundary/index.tsx';
+export { withScope } from './boundary/components/scope/index.tsx';
+export { useMode } from './boundary/components/mode/index.tsx';
+export type { ModeHandle } from './boundary/components/mode/index.tsx';
+export { useActions, With } from './hooks/index.ts';
+export { Resource } from './resource/index.ts';
+export type { ResourceHandle, ResourceFetcher, BoundRun, IfOptions, } from './resource/index.ts';
+export * as utils from './utils/index.ts';
+export type { Box } from 'immertation';
+export type { Fault } from './error/index.ts';
+export type { Pk, Task, Tasks, Handlers } from './types/index.ts';

package/dist/src/library/resource/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Options accepted by `run.if(...)`.
+ *
+ * - `over` – a `Temporal.Duration`, a `DurationLike` object
+ *   (e.g. `{ minutes: 5 }`), or an ISO 8601 duration string (`"PT5M"`).
+ *   If the most recent successful run resolved longer ago than this
+ *   window, `run(...)` is called. Otherwise the cached data is returned
+ *   without hitting the network.
+ *
+ * @example
+ * ```ts
+ * await user.run.if({ over: { minutes: 5 } });
+ * await user.run.if({ over: "PT5M" });
+ * await user.run.if({ over: Temporal.Duration.from({ minutes: 5 }) });
+ * ```
+ */
+export type IfOptions = {
+    readonly over: Temporal.DurationLike;
+};
+/**
+ * Fetcher signature accepted by {@link Resource}. Receives the
+ * call-site `params` object and returns a `Promise` of the response.
+ * Side-effects (dispatching broadcasts, analytics, etc.) belong in
+ * the calling `useAction` handler, not inside the fetcher.
+ */
+export type ResourceFetcher<T, P extends object = Record<never, never>> = (params: P) => Promise<T>;
+/**
+ * Component-bound `run` callable returned by `actions.useResource`. It
+ * is invokable like the underlying fetcher (`run(params)`) and also
+ * carries an `if` method that triggers the network call only when the
+ * cached data is older than the supplied freshness window.
+ *
+ * The conditional specialisation collapses the call signature when
+ * `P` is empty &mdash; `run()` instead of `run({})`.
+ */
+export type BoundRun<T, P extends object> = [keyof P] extends [never] ? {
+    (): Promise<T>;
+    /**
+     * Calls `run()` if the most recent successful run resolved longer
+     * ago than `options.over`. Otherwise returns the cached data.
+     */
+    readonly if: (options: IfOptions) => Promise<T>;
+} : {
+    (params: P): Promise<T>;
+    /**
+     * Calls `run(params)` if the most recent successful run resolved
+     * longer ago than `options.over`. Otherwise returns the cached data.
+     */
+    readonly if: (options: IfOptions, params: P) => Promise<T>;
+};
+/**
+ * Module-scope handle returned by {@link Resource}. Pass to
+ * `actions.useResource(handle)` inside a component to obtain a
+ * `{ run, data, at }` object.
+ */
+export type ResourceHandle<T, P extends object = Record<never, never>> = {
+    readonly key: string;
+    /** @internal */
+    readonly run: (params: P) => Promise<T>;
+    /** Most recent successful data across all param-sets, or `null`. */
+    readonly data: T | null;
+    /** Instant of the most recent successful run, or `null`. */
+    readonly at: Temporal.Instant | null;
+};
+/**
+ * Defines a remote resource &mdash; declare at module scope and consume
+ * via `actions.useResource(handle)`. Mirrors the {@link Action} factory
+ * pattern: the declaration is a value, not a hook.
+ *
+ * The fetcher takes a single `params` argument (defaults to `{}`) and
+ * returns a `Promise<T>`. Resources do **not** carry any callbacks
+ * &ndash; any side-effects the caller wants on success or failure
+ * (broadcasting, logging, model updates) belong in the `useAction`
+ * handler that called `await user.run(...)`.
+ *
+ * `params` are typed via the second generic and forwarded to every
+ * `run(params)` call site. In-flight dedup keys per params shape, so
+ * `feed.run({ cursor: null })` and `feed.run({ cursor: "abc" })` execute
+ * independently while two concurrent `feed.run({ cursor: "abc" })` calls
+ * share one network request.
+ *
+ * Each call to `run()` always hits the network; `data` and `at`
+ * are read-only snapshots of the most recent successful payload and
+ * the instant it resolved &ndash; not a memoised result.
+ *
+ * @example
+ * ```ts
+ * import { Resource } from "march-hare";
+ *
+ * export const feed = Resource<Page<Item>, { cursor: string | null }>(
+ *   "feed",
+ *   ({ cursor }) =>
+ *     http
+ *       .get("feed", { searchParams: { cursor: cursor ?? "" } })
+ *       .json<Page<Item>>(),
+ * );
+ * ```
+ */
+export declare function Resource<T, P extends object = Record<never, never>>(key: string, fetcher: ResourceFetcher<T, P>): ResourceHandle<T, P>;