march-hare 0.6.1 → 0.7.0

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

@@ -6,24 +6,28 @@ export { getActionSymbol, getLifecycleType, isBroadcastAction, isMulticastAction
 type ActionFactory = {
     /**
      * Creates a new unicast action with the given name.
+     *
+     * `K` is the literal type of the action name and is captured as a phantom
+     * brand so `Action("A")` and `Action("B")` produce structurally-distinct
+     * types. **Note:** when the caller supplies any explicit generic
+     * (`Action<P>("Name")`), TypeScript fills `K` from its default and the
+     * literal is lost. The Name brand still helps for `Action("Name")` calls
+     * (e.g. lifecycle / no-payload actions) which is the most common source of
+     * foreign-class collisions.
+     *
      * @template P The payload type for the action.
-     * @template C The channel type for channeled dispatches (defaults to never).
-     * @param name The action name, used for debugging purposes.
-     * @returns A typed action object.
+     * @template C The channel type for channeled dispatches.
+     * @template K The literal type of the action name (inferred when no other
+     *   generics are supplied; defaults to `string` otherwise).
      */
-    <P = never, C extends Filter = never>(name: string): HandlerPayload<P, C>;
+    <P = never, C extends Filter = never, K extends string = string>(name: K): HandlerPayload<P, C, K>;
     /**
      * Creates a new action with the specified distribution mode.
-     * @template P The payload type for the action.
-     * @template C The channel type for channeled dispatches (defaults to never).
-     * @param name The action name, used for debugging purposes.
-     * @param distribution The distribution mode (Unicast, Broadcast, or Multicast).
-     * @returns A typed action object (BroadcastPayload if Broadcast, MulticastPayload if Multicast).
      */
-    <P = never, C extends Filter = never>(name: string, distribution: Distribution.Broadcast): BroadcastPayload<P, C>;
-    <P = never, C extends Filter = never>(name: string, distribution: Distribution.Multicast): MulticastPayload<P, C>;
-    <P = never, C extends Filter = never>(name: string, distribution: Distribution.Unicast): HandlerPayload<P, C>;
-    <P = never, C extends Filter = never>(name: string, distribution: Distribution): HandlerPayload<P, C> | BroadcastPayload<P, C> | MulticastPayload<P, C>;
+    <P = never, C extends Filter = never, K extends string = string>(name: K, distribution: Distribution.Broadcast): BroadcastPayload<P, C, K>;
+    <P = never, C extends Filter = never, K extends string = string>(name: K, distribution: Distribution.Multicast): MulticastPayload<P, C, K>;
+    <P = never, C extends Filter = never, K extends string = string>(name: K, distribution: Distribution.Unicast): HandlerPayload<P, C, K>;
+    <P = never, C extends Filter = never, K extends string = string>(name: K, distribution: Distribution): HandlerPayload<P, C, K> | BroadcastPayload<P, C, K> | MulticastPayload<P, C, K>;
 };
 /**
  * Creates a new action with a given payload type, optional channel type, and optional distribution mode.

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

@@ -0,0 +1,41 @@
+import { Props } from './types.ts';
+import * as React from "react";
+export { useStore } from './utils.ts';
+/**
+ * App-wide store of cross-cutting, mutable state. The interface is
+ * declared empty here and **augmented** by consumer code via module
+ * augmentation:
+ *
+ * @example
+ * ```ts
+ * declare module "march-hare" {
+ *   interface Store {
+ *     session: Session | null;
+ *     locale: string;
+ *     featureFlags: Record<string, boolean>;
+ *   }
+ * }
+ * ```
+ *
+ * Every key declared here flows into:
+ *
+ * - `useStore()` &mdash; the per-`<Boundary>` handle for reads and writes.
+ * - `context.store` inside `useActions` handlers.
+ * - The `store` field on every `Resource` fetcher's args object.
+ *
+ * The Store is **not** reactive. Mutating it does not re-render. Drive
+ * view state through the model; use the Store for cross-handler
+ * coordination, session tokens, locale, feature flags, etc.
+ */
+export interface Store {
+}
+/**
+ * Provides a per-Boundary {@link Store} value to every component inside
+ * the boundary. Usually wired in via the `<Boundary store={initial}>`
+ * prop rather than used directly.
+ *
+ * The Store is **not** reactive. Mutating it does not trigger a
+ * re-render. Drive view state through the model; use the Store for
+ * cross-handler coordination.
+ */
+export declare function Store({ initial, children }: Props): React.ReactNode;

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

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+import { Store } from './index.tsx';
+export type { Store } from './index.tsx';
+/**
+ * Props for the Store provider component. Accepts the initial Store
+ * value that satisfies the augmented {@link Store} interface.
+ */
+export type Props = {
+    initial: Store;
+    children: ReactNode;
+};

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

@@ -0,0 +1,64 @@
+import { RefObject } from 'react';
+import { Store } from './index.tsx';
+import * as React from "react";
+/**
+ * React context exposing the per-Boundary Store ref. The ref itself is
+ * stable across renders — readers grab `.current` at call time.
+ *
+ * @internal
+ */
+export declare const Context: React.Context<React.RefObject<Store>>;
+/**
+ * Hook that returns a read-only handle to the per-Boundary {@link Store}.
+ * Reads use plain dot notation (`store.session`) and always reflect the
+ * latest value, even after `await` boundaries &mdash; the handle is a
+ * `Proxy` that delegates property access to the live ref.
+ *
+ * Writes are not exposed here. Mutate the Store inside an action handler
+ * via `context.actions.produce(({ model, store }) => { store.x = ... })`
+ * &mdash; the same Immer-style recipe used for the model. Mutations do
+ * **not** trigger a re-render; drive view state through the model.
+ *
+ * The Store's shape is declared via module augmentation on the library's
+ * {@link Store} interface, so dot reads are fully typed at every call
+ * site.
+ *
+ * @example
+ * ```ts
+ * declare module "march-hare" {
+ *   interface Store {
+ *     session: Session | null;
+ *     locale: string;
+ *   }
+ * }
+ *
+ * function useAuthActions() {
+ *   const store = useStore();
+ *   const actions = useActions<void, typeof Actions>();
+ *
+ *   actions.useAction(Actions.SignIn, async (context, credentials) => {
+ *     const result = await context.actions.resource(signIn(credentials));
+ *     context.actions.produce(({ store }) => {
+ *       store.session = result;
+ *     });
+ *   });
+ *
+ *   actions.useAction(Actions.Refresh, async (context) => {
+ *     if (store.session === null) return;
+ *     // ...
+ *   });
+ *
+ *   return actions;
+ * }
+ * ```
+ */
+export declare function useStore(): Store;
+/**
+ * Internal accessor for the per-Boundary Store ref &mdash; used by the
+ * Resource layer to pass a fresh snapshot to each fetcher invocation
+ * and by the action layer to write through `context.actions.produce`.
+ * Not exported from the library.
+ *
+ * @internal
+ */
+export declare function useStoreRef(): RefObject<Store>;

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

@@ -27,9 +27,9 @@ export type ActionId = symbol | string;
  * ```
  */
 export type Task<P = unknown> = {
-    controller: AbortController;
-    action: ActionId;
-    payload: P;
+    readonly controller: AbortController;
+    readonly action: ActionId;
+    readonly payload: P;
 };
 /**
  * A set of running tasks ordered by creation time (oldest first).

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

@@ -2,19 +2,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.
+ * Wraps children with Broadcaster, Store, 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.
+ * 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.
+ * Pass the `store` prop with the initial Store value (session, locale,
+ * feature flags, etc.) — the shape is determined by module
+ * augmentation on the library's `Store` interface.
  *
  * @example
  * ```tsx
- * <Boundary>
+ * <Boundary store={{ session: null, locale: "en-GB" }}>
  *   <App />
  * </Boundary>
  * ```
  */
-export declare function Boundary({ children }: Props): React.ReactNode;
+export declare function Boundary({ store, children }: Props): React.ReactNode;

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

@@ -1,4 +1,22 @@
+import { Store } from './components/store/types.ts';
 import type * as React from "react";
 export type Props = {
+    /**
+     * Initial value of the per-Boundary {@link Store}. The shape is
+     * derived from module augmentation — declare the keys your
+     * application needs once via:
+     *
+     * ```ts
+     * declare module "march-hare" {
+     *   interface Store {
+     *     session: Session | null;
+     *     locale: string;
+     *   }
+     * }
+     * ```
+     *
+     * Optional only when the augmented Store has no required keys.
+     */
+    store?: Store;
     children: React.ReactNode;
 };

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

@@ -0,0 +1,44 @@
+import { Adapter, Stored } from './types.ts';
+export type { Adapter, Encoded } from './types.ts';
+/**
+ * Persistence-aware cache for a single {@link Resource}. Wraps a
+ * synchronous {@link Adapter} (localStorage, MMKV, chrome.storage with a
+ * sync facade, etc.) and traffics in {@link Stored} envelopes —
+ * storage entries serialise as {@link Encoded}`<T>` so the
+ * `Temporal.Instant` timestamp survives the string round-trip and
+ * `.exceeds({...})` can short-circuit on the persisted timestamp after
+ * a reload.
+ *
+ * Call with no arguments for an in-memory cache scoped to this
+ * instance &mdash; useful for tests, ephemeral state, or when you want a
+ * first-class cache object to share between Resources without
+ * persistence. Pass an {@link Adapter} to back the cache with a
+ * persistent store.
+ *
+ * @example
+ * ```ts
+ * // In-memory, scoped to this instance.
+ * const cache = Cache();
+ *
+ * // Persisted via localStorage.
+ * const cache = Cache({
+ *   get: (key) => localStorage.getItem(key),
+ *   set: (key, value) => localStorage.setItem(key, value),
+ *   remove: (key) => localStorage.removeItem(key),
+ *   clear: () => localStorage.clear(),
+ * });
+ *
+ * // Wired into a Resource — successful runs write through automatically.
+ * export const cat = Resource(
+ *   async ({ controller }) => fetchCat(controller.signal),
+ *   cache,
+ * );
+ * ```
+ */
+export type Cache = {
+    get<T>(key: string): Stored<T>;
+    set<T>(key: string, value: Stored<T>): boolean;
+    remove(key: string): void;
+    clear(): void;
+};
+export declare function Cache(adapter?: Adapter): Cache;

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

@@ -0,0 +1,54 @@
+export type { Stored } from '../utils/types.ts';
+/**
+ * On-disk JSON shape of a `Stored` envelope. The Cache wrapper
+ * encodes a populated Stored as `{ data, at: at.toString() }` so the
+ * `Temporal.Instant` survives the string round-trip, and decodes via
+ * `Temporal.Instant.from(...)` on read. Adapters never see this shape
+ * directly — they shuttle the already-stringified JSON.
+ *
+ * @template T The payload type carried by the matching {@link Stored}.
+ */
+export type Encoded<T> = {
+    readonly data: T;
+    readonly at: string;
+};
+/**
+ * Adapter contract for synchronous key/value storage. Implement once per
+ * backend (localStorage, MMKV on React Native, chrome.storage with a sync
+ * facade, etc.) and pass to {@link Cache}. The adapter shuttles raw
+ * strings; JSON encoding and `Temporal.Instant` round-tripping happen
+ * inside the Cache wrapper, so adapters stay trivial.
+ */
+export type Adapter = {
+    /**
+     * Return the raw string stored under `key`, or `null` when no entry
+     * exists. The Cache wrapper handles JSON parsing and `Temporal.Instant`
+     * round-tripping, so this stays a plain string getter. Treat any
+     * read-time error (decryption, IPC, etc.) as "not found" and return
+     * `null` &mdash; the Cache falls through to its next fallback rather
+     * than crashing the render.
+     */
+    readonly get: (key: string) => string | null;
+    /**
+     * Persist the raw string `value` under `key`. The Cache guarantees
+     * `value` is a JSON-encoded `{ data, at }` envelope produced by a
+     * resolved snapshot &mdash; never a placeholder. Throwing is fine on
+     * quota, private mode, sandboxed iframes, etc.; the Cache catches and
+     * swallows so a write failure can't poison an already-resolved fetch.
+     */
+    readonly set: (key: string, value: string) => void;
+    /**
+     * Drop the entry at `key`. Idempotent &mdash; calling `remove` for a
+     * key that isn't present must not throw.
+     */
+    readonly remove: (key: string) => void;
+    /**
+     * Wipe every entry this adapter can see. On a shared backend such as
+     * `localStorage` this means the whole origin &mdash; third-party SDK
+     * state, dismissed banners, route hints, etc. all go with it. Adapter
+     * authors should either delegate to the backend's native clear
+     * (accepting that scope) or namespace by key prefix and remove only
+     * their own.
+     */
+    readonly clear: () => void;
+};

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

@@ -5,13 +5,15 @@ 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 { useStore } from './boundary/components/store/index.tsx';
+export type { Store } from './boundary/components/store/index.tsx';
 export { useActions, With } from './hooks/index.ts';
-export { Resource, useResource } from './resource/index.ts';
-export type { ResourceHandle, ResourceFetcher, BoundResourceHandle, IfOptions, } from './resource/index.ts';
+export { Resource } from './resource/index.ts';
+export type { Fetcher } from './resource/index.ts';
+export { Cache } from './cache/index.ts';
+export type { Adapter, Encoded } from './cache/index.ts';
 export * as utils from './utils/index.ts';
-export type { Stored, Unset, Adapter, Store } from './utils/index.ts';
+export type { Stored, Unset } 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';
+export type { Pk, Task, Tasks, Handlers, Handler, LeafActions, Dispatchable, Subscribable, } from './types/index.ts';

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

@@ -1,65 +1,102 @@
-import { ResourceFetcher, ResourceHandle, BoundResourceHandle } from './types.ts';
-export type { IfOptions, ResourceFetcher, ResourceHandle, BoundResourceHandle, } from './types.ts';
+import { Fetcher } from './types.ts';
+import { Cache } from './utils.ts';
+import { Store } from '../boundary/components/store/index.tsx';
+export type { Fetcher } from './types.ts';
 /**
- * Defines a remote resource — declared at module scope and
- * consumed via {@link useResource}.
+ * Snapshot of the most recent resource invocation. `cat(params)` writes
+ * one of these into a module-scope slot; the next
+ * `context.actions.resource(...)` / `.set(...)` call consumes it via
+ * {@link consumePending}.
  *
- * The fetcher receives the optional `AbortSignal` first and the
- * `params` object second (defaults to `{}`). Resources do **not**
- * carry any callbacks – side-effects (broadcasting, logging,
- * model updates) belong in the `useAction` handler that called
- * `await handle(...)`.
+ * @internal
+ */
+export type PendingCall = {
+    readonly run: (store: Store, controller: AbortController, params: object) => Promise<unknown>;
+    readonly read: (params: object) => {
+        data: unknown;
+        at: Temporal.Instant | null;
+    };
+    readonly seed: (params: object, data: unknown, at: Temporal.Instant) => void;
+    readonly params: object;
+};
+/**
+ * Reads and clears the slot populated by the most recent resource
+ * invocation. Throws when the slot is empty &mdash; the public
+ * `.resource(...)` shape requires a fresh `cat(params)` call as its
+ * argument.
  *
- * Every call fires its own request. The most recent successful
- * payload is cached in a module-level `WeakMap` keyed by the fetcher,
- * so `.if(...)` and `.else(...)` on the bound handle behave
- * consistently across all components that share the same Resource.
+ * @internal
+ */
+export declare function consumePending(): PendingCall;
+/**
+ * Resource handle returned by `Resource(...)`. Call it with `params` to
+ * read the per-params cache slot synchronously and prime the slot
+ * consumed by `context.actions.resource(...)` for a follow-up fetch or
+ * `context.actions.resource.set(...)` for an out-of-band write.
  *
- * @example
  * ```ts
- * import { Resource } from "march-hare";
+ * // Sync cache read in a model literal.
+ * { cat: cat({ id: 5 }) }
  *
- * // `T` is inferred from the fetcher's return type.
- * export const user = Resource((signal) =>
- *   ky.get("user", { signal }).json<User>(),
- * );
+ * // Fetch with `.exceeds(...)` for cache-aware refresh.
+ * await context.actions.resource(cat({ id: 5 })).exceeds({ minutes: 5 });
  *
- * // Annotate `params` when destructuring so `P` is inferred.
- * export const updateUser = Resource(
- *   (signal, { id, body }: { id: number; body: { name: string } }) =>
- *     ky.patch(`users/${id}`, { json: body, signal }).json<User>(),
- * );
+ * // Write through to the per-params cache slot.
+ * context.actions.resource.set(cat({ id: 5 }), data);
  * ```
  */
-export declare function Resource<T, P extends object = Record<never, never>>(fetcher: ResourceFetcher<T, P>): ResourceHandle<T, P>;
+export type Resource<T, P extends object = Record<never, never>> = [
+    keyof P
+] extends [never] ? (params?: P) => T | null : (params: P) => T | null;
 /**
- * Binds a module-scope {@link ResourceHandle} to the component, returning
- * the fetch callable with `.if`, `.else`, `.snapshot`, `.data`, and `.at`
- * attached. The hook is standalone &ndash; call it *before* `useActions`
- * when you want to seed the initial model from the cache via
- * `.else(fallback)`.
+ * Defines a remote resource &mdash; declared at module scope and used
+ * directly. Calling the returned handle with `params` returns the sync
+ * cache value (`T | null`) and primes the slot consumed by
+ * `context.actions.resource(...)` / `.set(...)` for fetch and write
+ * paths.
+ *
+ * The fetcher receives a single args object `{ store, controller, params }`:
+ *
+ * - `store` &ndash; snapshot of the per-`<Boundary>` Store (session,
+ *   locale, feature flags, etc.). Reads only; writes go through
+ *   `context.actions.produce(({ store }) => ...)` in handlers.
+ * - `controller` &ndash; the `AbortController` auto-threaded from the
+ *   calling handler's `context.task.controller`. Pass `controller.signal`
+ *   to `fetch`/`ky`, or call `controller.abort()` to fail fast.
+ * - `params` &ndash; the call-site params object (defaults to `{}`).
  *
- * Pass `context.task.controller.signal` as the first argument to thread
- * cancellation from the surrounding action handler through to the
- * fetcher. For parameterised resources, pass `null` as the first arg
- * when you have params but no signal.
+ * Resources do **not** carry any callbacks &ndash; side-effects
+ * (broadcasting, logging, model updates) belong in the `useAction`
+ * handler that awaited `context.actions.resource(...)`.
+ *
+ * Every successful fetch writes through to the per-fetcher {@link Cache}
+ * (in-memory by default, persistent when an adapter is supplied via the
+ * second argument).
  *
  * @example
  * ```ts
- * const cat = useResource(resources.cat);
- * const actions = useActions<Model, typeof Actions, Data>(
- *   { cat: cat.else(store.get(Snapshots.Cat)).else(null) },
- *   () => ({ index, router }),
+ * import { Resource, Cache } from "march-hare";
+ *
+ * export const user = Resource<User, { id: number }>(
+ *   ({ store, controller, params }) =>
+ *     ky.get(`users/${params.id}`, {
+ *       headers: store.session
+ *         ? { Authorization: `Bearer ${store.session.accessToken}` }
+ *         : {},
+ *       signal: controller.signal,
+ *     }).json<User>(),
  * );
  *
+ * // Sync cache read at module scope or in the model literal.
+ * const cached: User | null = user({ id: 5 });
+ *
+ * // Fetch inside a handler — controller and Store auto-threaded.
  * actions.useAction(Actions.Mount, async (context) => {
- *   const fresh = await cat.if(
- *     { over: { minutes: 5 } },
- *     context.task.controller.signal,
- *   );
- *   store.set(Snapshots.Cat, cat.snapshot());
- *   context.actions.produce(({ model }) => void (model.cat = fresh));
+ *   const data = await context.actions
+ *     .resource(user({ id: 5 }))
+ *     .exceeds({ minutes: 5 });
+ *   context.actions.produce(({ model }) => void (model.user = data));
  * });
  * ```
  */
-export declare function useResource<T, P extends object>(resource: ResourceHandle<T, P>): BoundResourceHandle<T, P>;
+export declare function Resource<T, P extends object = Record<never, never>>(fetcher: Fetcher<T, P>, cache?: Cache): Resource<T, P>;