march-hare 0.6.0

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

@@ -0,0 +1,89 @@
+import { ChanneledAction, AnyAction } from '../types/index.ts';
+import { ActionId } from '../boundary/components/tasks/types.ts';
+/**
+ * Extracts the underlying symbol from an action or channeled action.
+ * This symbol is used as the event emitter key for dispatching.
+ *
+ * @param action The action or channeled action to extract the symbol from.
+ * @returns The underlying symbol, or the action itself if it's already a symbol/string.
+ *
+ * @example
+ * ```typescript
+ * const Increment = Action<number>("Increment");
+ * getActionSymbol(Increment); // Symbol(march-hare.action/Increment)
+ * getActionSymbol(Increment({ UserId: 5 })); // Symbol(march-hare.action/Increment)
+ * ```
+ */
+export declare function getActionSymbol(action: AnyAction): ActionId;
+/**
+ * Checks whether an action is a broadcast action.
+ * Broadcast actions are sent to all mounted components that have defined a handler for them.
+ *
+ * @param action The action to check.
+ * @returns True if the action is a broadcast action, false otherwise.
+ */
+export declare function isBroadcastAction(action: AnyAction): boolean;
+/**
+ * Extracts the action name from an action.
+ *
+ * Parses both regular actions (`march-hare.action/Name`) and
+ * distributed actions (`march-hare.action/distributed/Name`)
+ * to extract just the name portion.
+ *
+ * @param action The action to extract the name from.
+ * @returns The extracted action name, or "unknown" if parsing fails.
+ *
+ * @example
+ * ```typescript
+ * const Increment = Action("Increment");
+ * getName(Increment); // "Increment"
+ *
+ * const SignedOut = Action("SignedOut", Distribution.Broadcast);
+ * getName(SignedOut); // "SignedOut"
+ * ```
+ */
+export declare function getName(action: AnyAction): string;
+/**
+ * Checks if the given action is a channeled action (result of calling `Action(channel)`).
+ *
+ * @param action - The action to check
+ * @returns `true` if the action is a channeled action with a channel property, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * const UserUpdated = Action<User, { UserId: number }>("UserUpdated");
+ *
+ * isChanneledAction(UserUpdated); // false
+ * isChanneledAction(UserUpdated({ UserId: 1 })); // true
+ * ```
+ */
+export declare function isChanneledAction(action: AnyAction): action is ChanneledAction;
+/**
+ * Extracts the lifecycle type from an action's symbol description.
+ *
+ * Returns the lifecycle name (`"Mount"`, `"Unmount"`, `"Error"`, `"Update"`)
+ * when the action symbol's description starts with the lifecycle prefix, or
+ * `null` for non-lifecycle actions.
+ *
+ * @param action The action to inspect.
+ * @returns The lifecycle name, or `null` if not a lifecycle action.
+ *
+ * @example
+ * ```typescript
+ * class Actions {
+ *   static Mount = Lifecycle.Mount();
+ * }
+ *
+ * getLifecycleType(Actions.Mount); // "Mount"
+ * getLifecycleType(Action("Increment")); // null
+ * ```
+ */
+export declare function getLifecycleType(action: AnyAction): string | null;
+/**
+ * Checks whether an action is a multicast action.
+ * Multicast actions are dispatched to all components within a named scope boundary.
+ *
+ * @param action The action to check.
+ * @returns True if the action is a multicast action, false otherwise.
+ */
+export declare function isMulticastAction(action: AnyAction): boolean;

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

@@ -0,0 +1,25 @@
+import { Operation } from 'immertation';
+/**
+ * Wraps a value with an operation annotation for use in initial model definitions.
+ * When passed as part of the initial model to `useActions`, the annotation is
+ * registered during hydration so that `actions.inspect` reports the field as pending
+ * from the very first render.
+ *
+ * @param value - The value to annotate.
+ * @param operation - The operation type (defaults to {@link Operation.Update}).
+ * @returns The annotated value (typed as T for assignment compatibility).
+ *
+ * @example
+ * ```ts
+ * import { annotate } from "march-hare";
+ *
+ * type Model = { user: User | null };
+ *
+ * const model: Model = {
+ *   user: annotate(null),
+ * };
+ *
+ * // actions.inspect.user.pending() === true from the first render
+ * ```
+ */
+export declare function annotate<T>(value: T, operation?: Operation): T;

package/dist/src/library/boundary/components/broadcast/index.d.ts

@@ -0,0 +1,12 @@
+import { Props } from './types.ts';
+import * as React from "react";
+export { useBroadcast, BroadcastEmitter } from './utils.ts';
+/**
+ * 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 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/src/library/boundary/components/broadcast/types.d.ts

@@ -0,0 +1,19 @@
+import { BroadcastEmitter } from './utils.ts';
+import * as React from "react";
+/**
+ * The broadcast context is a BroadcastEmitter used for distributed actions across components.
+ * Extends EventEmitter with a per-action value cache so late-mounting components can replay
+ * broadcast values even without a Partition (from `stream()`).
+ */
+export type BroadcastContext = BroadcastEmitter;
+/**
+ * Return type for the useBroadcast hook.
+ * Provides access to the shared BroadcastEmitter for emitting and subscribing to distributed actions.
+ */
+export type UseBroadcast = BroadcastContext;
+/**
+ * Props for the Broadcaster provider component.
+ */
+export type Props = {
+    children: React.ReactNode;
+};

package/dist/src/library/boundary/components/broadcast/utils.d.ts

@@ -0,0 +1,39 @@
+import { default as EventEmitter } from 'eventemitter3';
+import * as React from "react";
+/**
+ * EventEmitter subclass that caches the latest payload per event.
+ *
+ * When a broadcast or multicast action is dispatched, the payload is
+ * stored so that late-mounting components can replay it via
+ * {@link useLifecycles} and handlers can read it via
+ * `context.actions.resolution()`.
+ */
+export declare class BroadcastEmitter extends EventEmitter {
+    private cache;
+    emit(event: string | symbol, ...args: unknown[]): boolean;
+    /**
+     * Cache a value for a given event without emitting to listeners.
+     * Used by {@link emitAsync} to preserve caching when bypassing `emit()`.
+     */
+    setCache(event: string | symbol, value: unknown): void;
+    /**
+     * Retrieve the last emitted payload for a given event.
+     */
+    getCached(event: string | symbol): unknown;
+    /**
+     * Emit without caching the payload. Used by the framework to publish
+     * fire-and-forget events (such as `Lifecycle.Fault`) where late-mounting
+     * subscribers must not replay a stale value.
+     */
+    fire(event: string | symbol, ...args: unknown[]): boolean;
+}
+/**
+ * React context for broadcasting distributed actions across components.
+ */
+export declare const Context: React.Context<BroadcastEmitter>;
+/**
+ * Hook to access the broadcast EventEmitter for emitting and listening to distributed actions.
+ *
+ * @returns The BroadcastEmitter instance for distributed actions.
+ */
+export declare function useBroadcast(): BroadcastEmitter;

package/dist/src/library/boundary/components/consumer/components/partition/index.d.ts

@@ -0,0 +1,27 @@
+import { Props } from './types.ts';
+import * as React from "react";
+/**
+ * Renders output for the `stream()` method by subscribing to distributed action events.
+ *
+ * This component manages a subscription to the broadcast emitter for distributed actions,
+ * storing the latest dispatched value in the Consumer context. When a new value arrives,
+ * all mounted Partition instances for that action re-render with the updated value.
+ *
+ * On mount, if a value was previously dispatched for this action, it renders immediately
+ * with that cached value. If no value exists yet, it renders `null` until the first dispatch.
+ *
+ * Uses Immertation's State class internally to manage consumed values, providing real
+ * annotation tracking through the `inspect` proxy. When a payload containing annotated
+ * values is dispatched, the annotations are preserved and accessible via `inspect`.
+ *
+ * The renderer callback receives two arguments:
+ * - `value`: The latest dispatched payload
+ * - `inspect`: A proxy for checking annotation status (pending, is, draft, settled, etc.)
+ *
+ * @template T - The payload type for the action (must be an object type)
+ * @param props.action - The distributed action symbol to subscribe to
+ * @param props.renderer - Callback that receives value and inspect, returns React nodes
+ * @returns The result of calling renderer, or null if no value exists
+ * @internal
+ */
+export declare function Partition<T extends object>({ action, renderer, }: Props<T>): React.ReactNode;

package/dist/src/library/boundary/components/consumer/components/partition/types.d.ts

@@ -0,0 +1,9 @@
+import { ConsumerRenderer } from '../../types.ts';
+/**
+ * Props for the Partition component.
+ * @internal
+ */
+export type Props<T> = {
+    action: symbol;
+    renderer: ConsumerRenderer<T>;
+};

package/dist/src/library/boundary/components/consumer/index.d.ts

@@ -0,0 +1,19 @@
+import { Props } from './types.ts';
+import * as React from "react";
+export { useConsumer } from './utils.ts';
+export { Partition } from './components/partition/index.tsx';
+export type { Props as PartitionProps } from './components/partition/types.ts';
+export type { ConsumerRenderer, Entry, ConsumerContext } from './types.ts';
+/**
+ * Creates a new consumer context for storing distributed action values. Only needed if you
+ * want to isolate a consumer context, useful for libraries that want to provide
+ * their own consumer context without interfering with the app's consumer context.
+ *
+ * The Consumer stores the latest value for each distributed action, allowing components
+ * that mount later to access values that were dispatched before they mounted. This enables
+ * the `stream()` method to render the most recent value immediately.
+ *
+ * @param props.children - The children to render within the consumer context.
+ * @returns The children wrapped in a consumer context provider.
+ */
+export declare function Consumer({ children }: Props): React.ReactNode;

package/dist/src/library/boundary/components/consumer/types.d.ts

@@ -0,0 +1,37 @@
+import { Inspect, State } from 'immertation';
+import { ActionId } from '../tasks/types.ts';
+import * as React from "react";
+/**
+ * Callback function for the stream() method.
+ * Receives the dispatched value and an inspect proxy for annotation tracking.
+ *
+ * @template T - The payload type
+ */
+export type ConsumerRenderer<T> = (value: T, inspect: Inspect<T>) => React.ReactNode;
+/**
+ * Model for consumed values.
+ * Allows Immertation's State to manage the value with real inspect capabilities.
+ * @template T - The payload type
+ */
+export type Model<T> = {
+    value: T;
+};
+/**
+ * Entry storing the latest value and listeners for an action.
+ * Uses Immertation's State to provide real inspect functionality for consumed values.
+ * @template T - The payload type
+ */
+export type Entry<T = unknown> = {
+    state: State<Model<T>>;
+    listeners: Set<() => void>;
+};
+/**
+ * The consumer context is a Map storing entries keyed by action.
+ */
+export type ConsumerContext = Map<ActionId, Entry>;
+/**
+ * Props for the Consumer provider component.
+ */
+export type Props = {
+    children: React.ReactNode;
+};

package/dist/src/library/boundary/components/consumer/utils.d.ts

@@ -0,0 +1,13 @@
+import { ConsumerContext } from './types.ts';
+import * as React from "react";
+/**
+ * React context for the consumer store.
+ * Stores the latest value for each distributed action with full annotation support.
+ */
+export declare const Context: React.Context<ConsumerContext>;
+/**
+ * Hook to access the consumer store from context.
+ *
+ * @returns The Map of action symbols to their State entries.
+ */
+export declare function useConsumer(): ConsumerContext;

package/dist/src/library/boundary/components/mode/index.d.ts

@@ -0,0 +1,15 @@
+import { Props } from './types.ts';
+import * as React from "react";
+export { useMode } from './utils.ts';
+export type { ModeHandle } from './utils.ts';
+/**
+ * Provides a single mutable mode handle to every component inside the
+ * boundary. Components opt in by calling {@link useMode} and threading the
+ * returned handle through {@link useActions}'s `data` callback.
+ *
+ * Mode is **not** reactive — mutating it does not trigger a re-render.
+ * Use it for cross-handler coordination (e.g. flagging an in-progress
+ * sign-out) when you do not want the value showing up as render-time UI
+ * state.
+ */
+export declare function Mode({ children }: Props): React.ReactNode;

package/dist/src/library/boundary/components/mode/types.d.ts

@@ -0,0 +1,7 @@
+import { ReactNode } from 'react';
+/**
+ * Props for the Mode provider component.
+ */
+export type Props = {
+    children: ReactNode;
+};

package/dist/src/library/boundary/components/mode/utils.d.ts

@@ -0,0 +1,55 @@
+import * as React from "react";
+/**
+ * React context exposing the per-Boundary mode handle. The handle itself
+ * is stable across renders — readers grab `.current` at call time.
+ *
+ * @internal
+ */
+export declare const Context: React.Context<React.RefObject<unknown>>;
+/**
+ * Handle returned by {@link useMode}. Reads always reflect the latest
+ * write, even after `await` boundaries.
+ */
+export type ModeHandle<T> = {
+    read(): T | null;
+    update(value: T | null): void;
+};
+/**
+ * Hook that returns a `{ read, update }` handle to the per-Boundary mode
+ * value.
+ *
+ * Mode is a single mutable value shared across every component inside the
+ * surrounding `<Boundary>`. It is **not** reactive &mdash; mutating it does
+ * not trigger a re-render. Use it for coordinating between async action
+ * handlers (e.g. short-circuiting refreshes during sign-out).
+ *
+ * Pass the handle through the {@link useActions} `data` callback so it
+ * shows up under `context.data` inside handlers, fully typed.
+ *
+ * @example
+ * ```ts
+ * enum Mode {
+ *   Idle,
+ *   SigningOut,
+ * }
+ *
+ * function useSignOutActions() {
+ *   const mode = useMode<Mode>();
+ *   const actions = useActions<Model, typeof Actions>(model, () => ({ mode }));
+ *
+ *   actions.useAction(Actions.SignOut, async (context) => {
+ *     context.data.mode.update(Mode.SigningOut);
+ *     await api.signOut();
+ *     context.data.mode.update(Mode.Idle);
+ *   });
+ *
+ *   actions.useAction(Actions.Refresh, async (context) => {
+ *     if (context.data.mode.read() === Mode.SigningOut) return;
+ *     // ...
+ *   });
+ *
+ *   return actions;
+ * }
+ * ```
+ */
+export declare function useMode<T>(): ModeHandle<T>;

package/dist/src/library/boundary/components/scope/index.d.ts

@@ -0,0 +1,40 @@
+import { MulticastPayload } from '../../../types/index.ts';
+import { ComponentType, ReactNode } from 'react';
+export { useScope, getScope } from './utils.ts';
+export type { ScopeEntry, ScopeContext } from './types.ts';
+/**
+ * Higher-order component that opens a multicast scope keyed by the supplied
+ * multicast action. Components rendered inside the wrapped tree (and any
+ * descendants) participate in the scope: every dispatch of `action` reaches
+ * every subscriber inside this boundary.
+ *
+ * Each multicast action defines its own scope — pass the same action you
+ * declared with `Distribution.Multicast` to both `withScope` and
+ * `actions.dispatch`.
+ *
+ * Multicast caches the most recent dispatched value per scope so late-mounted
+ * components can read it via `context.actions.resolution()`.
+ *
+ * @param action - The multicast action that opens this scope.
+ * @param Component - The component to wrap.
+ * @returns A component that renders the original inside a fresh scope boundary.
+ *
+ * @example
+ * ```tsx
+ * export class Scope {
+ *   static Mood = Action<Mood>("Mood", Distribution.Multicast);
+ * }
+ *
+ * function Mood() {
+ *   return (
+ *     <>
+ *       <Happy />
+ *       <Sad />
+ *     </>
+ *   );
+ * }
+ *
+ * export default withScope(Scope.Mood, Mood);
+ * ```
+ */
+export declare function withScope<P extends object, T = unknown>(action: MulticastPayload<T>, Component: ComponentType<P>): (props: P) => ReactNode;

package/dist/src/library/boundary/components/scope/types.d.ts

@@ -0,0 +1,20 @@
+import { BroadcastEmitter } from '../broadcast/utils.ts';
+import { ActionId } from '../tasks/types.ts';
+/**
+ * Represents a single scope in the ancestor chain. The scope key is the
+ * action id of the multicast action that opens the scope; each multicast
+ * action defines its own scope.
+ */
+export type ScopeEntry = {
+    /** The action id that opened this scope */
+    action: ActionId;
+    /** BroadcastEmitter for multicast events within this scope (caches last payload per event) */
+    emitter: BroadcastEmitter;
+};
+/**
+ * The scope context is a flattened map of ancestor scopes keyed by the
+ * multicast action that opened each scope. Each `withScope` merges its entry
+ * with the parent's map, building up a complete lookup table for O(1)
+ * retrieval. null indicates no scope ancestor.
+ */
+export type ScopeContext = Map<ActionId, ScopeEntry> | null;

package/dist/src/library/boundary/components/scope/utils.d.ts

@@ -0,0 +1,19 @@
+import { ScopeContext, ScopeEntry } from './types.ts';
+import { ActionId } from '../tasks/types.ts';
+import * as React from "react";
+/**
+ * React context for the scope chain.
+ * Starts as null (no scopes).
+ */
+export declare const Context: React.Context<ScopeContext>;
+/**
+ * Hook to access the scope context from the nearest ancestor.
+ *
+ * @returns The scope context chain, or null if not inside any scope.
+ */
+export declare function useScope(): ScopeContext;
+/**
+ * Looks up the scope opened by the given multicast action.
+ * O(1) lookup from the flattened scope map.
+ */
+export declare function getScope(context: ScopeContext, action: ActionId): ScopeEntry | null;

package/dist/src/library/boundary/components/tasks/index.d.ts

@@ -0,0 +1,14 @@
+import { Props } from './types.ts';
+import * as React from "react";
+export type { Task } from './types.ts';
+/**
+ * Creates a new tasks context for action control. Only needed if you
+ * want to isolate a tasks context, useful for libraries that want to provide
+ * their own tasks context without interfering with the app's tasks context.
+ *
+ * Tasks added within this context are isolated from tasks in other contexts.
+ *
+ * @param props.children - The children to render within the tasks context.
+ * @returns The children wrapped in a tasks context provider.
+ */
+export declare function Tasks({ children }: Props): React.ReactNode;

package/dist/src/library/boundary/components/tasks/types.d.ts

@@ -0,0 +1,43 @@
+import * as React from "react";
+/**
+ * An action identifier - either a symbol (including branded HandlerPayload) or string.
+ */
+export type ActionId = symbol | string;
+/**
+ * Represents a running task with its associated metadata.
+ * Tasks are stored in a Set ordered by creation time (oldest first).
+ *
+ * @template P - The payload type for this task
+ * @property controller - The AbortController to cancel this task
+ * @property action - The action identifier that triggered this task
+ * @property payload - The payload passed when the action was dispatched
+ *
+ * @example
+ * ```ts
+ * // Abort all tasks for a specific action
+ * for (const runningTask of context.tasks) {
+ *   if (runningTask.action === Actions.Fetch) {
+ *     runningTask.controller.abort();
+ *   }
+ * }
+ *
+ * // Abort the oldest task
+ * const oldest = context.tasks.values().next().value;
+ * oldest?.controller.abort();
+ * ```
+ */
+export type Task<P = unknown> = {
+    controller: AbortController;
+    action: ActionId;
+    payload: P;
+};
+/**
+ * A set of running tasks ordered by creation time (oldest first).
+ */
+export type Tasks = Set<Task>;
+/**
+ * Props for the Tasks provider component.
+ */
+export type Props = {
+    children: React.ReactNode;
+};

package/dist/src/library/boundary/components/tasks/utils.d.ts

@@ -0,0 +1,26 @@
+import { Tasks } from './types.ts';
+import * as React from "react";
+/**
+ * React context for the shared tasks Set.
+ * Tasks are ordered by creation time (oldest first) since Sets maintain insertion order.
+ */
+export declare const Context: React.Context<Tasks>;
+/**
+ * Hook to access the shared tasks Set from context.
+ * Returns the Set of all currently running tasks across all components in the context.
+ *
+ * @returns The Set of Task instances in the current context.
+ *
+ * @example
+ * ```ts
+ * const tasks = useTasks();
+ *
+ * // Abort all tasks for a specific action
+ * for (const task of tasks) {
+ *   if (task.action === Actions.Fetch) {
+ *     task.controller.abort();
+ *   }
+ * }
+ * ```
+ */
+export declare function useTasks(): Tasks;

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

@@ -0,0 +1,20 @@
+import { Props } from './types.ts';
+import * as React from "react";
+/**
+ * Creates a unified context boundary for all March Hare features.
+ * Wraps children with Broadcaster, Mode, and Tasks providers.
+ *
+ * Use this at the root of your application or to create isolated context boundaries
+ * for libraries that need their own March Hare context.
+ *
+ * @param props.children - The children to render within the boundary.
+ * @returns The children wrapped in all required context providers.
+ *
+ * @example
+ * ```tsx
+ * <Boundary>
+ *   <App />
+ * </Boundary>
+ * ```
+ */
+export declare function Boundary({ children }: Props): React.ReactNode;

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

@@ -0,0 +1,4 @@
+import type * as React from "react";
+export type Props = {
+    children: React.ReactNode;
+};

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

@@ -0,0 +1,2 @@
+export { Reason, AbortError, TimeoutError } from './types';
+export type { Fault } from './types';

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

@@ -0,0 +1,75 @@
+import { Task } from '../boundary/components/tasks/types.ts';
+/**
+ * Reasons why an action error occurred.
+ */
+export declare enum Reason {
+    /** Action exceeded its timeout limit. */
+    Timedout = 0,
+    /** Action was cancelled by a newer dispatch. */
+    Supplanted = 1,
+    /** A generic error thrown in the user's action handler. */
+    Errored = 2
+}
+/**
+ * Error thrown when an action is aborted, e.g., when a component unmounts
+ * or when a newer dispatch cancels a previous run. Works across all platforms
+ * including React Native where `DOMException` is unavailable.
+ *
+ * @example
+ * ```ts
+ * throw new AbortError("User cancelled the request");
+ * ```
+ */
+export declare class AbortError extends Error {
+    name: string;
+    constructor(message?: string);
+}
+/**
+ * Error thrown when an action exceeds its timeout limit.
+ * Works across all platforms including React Native where `DOMException` is unavailable.
+ *
+ * @example
+ * ```ts
+ * throw new TimeoutError("Request took too long");
+ * ```
+ */
+export declare class TimeoutError extends Error {
+    name: string;
+    constructor(message?: string);
+}
+/**
+ * Details about an error that occurred during action execution.
+ *
+ * Faults are delivered through the global `Lifecycle.Fault` broadcast.
+ * Subscribe with `actions.useAction(Lifecycle.Fault, handler)` near the
+ * root of your application for app-level concerns (logging, sign-out on
+ * auth failure, abort cascades). For component-local recovery, use a
+ * `Lifecycle.Error()` factory instead.
+ *
+ * @template E Custom error types to include in the union with Error.
+ */
+export type Fault<E extends Error = never> = {
+    /** The reason for the error. */
+    reason: Reason;
+    /** The Error object that was thrown. */
+    error: Error | E;
+    /** The name of the action that caused the error (e.g., "Increment"). */
+    action: string;
+    /** Whether the component has a `Lifecycle.Error()` handler registered. */
+    handled: boolean;
+    /**
+     * All currently running tasks across the application.
+     * Use this to programmatically abort in-flight actions during error recovery
+     * (e.g., on 403/500 responses to prevent cascading failures).
+     *
+     * @example
+     * ```ts
+     * actions.useAction(Lifecycle.Fault, (context, fault) => {
+     *   if (fault.reason === Reason.Errored) {
+     *     for (const task of fault.tasks) task.controller.abort();
+     *   }
+     * });
+     * ```
+     */
+    tasks: ReadonlySet<Task>;
+};