march-hare 0.11.1 → 0.13.0

package/dist/resource/index.d.ts

@@ -1,39 +1,64 @@
-import { Fetcher, PendingCall, ResourceHandle } from './types';
+import { ResourceHandle } from './types';
 import { Cache } from './utils';
-export type { Coalesce, Fetcher, PendingCall, ResourceHandle, } from './types';
+import { AppFetcher } from '../app/types';
+export type { Coalesce, Fetcher, Invocation, ResourceHandle } from './types';
 /**
- * Reads and clears the slot populated by the most recent resource
- * invocation. Throws when the slot is empty — the public
- * `.resource(...)` shape requires a fresh `resource.cat(params)` call
- * as its argument.
+ * Evicts cache entries across every Resource constructed in the
+ * current process. Resources register themselves on declaration, so
+ * `nuke` covers both `app.Resource` and `shared.Resource`. Pass a
+ * `where` pattern to drop only slots whose stored params satisfy the
+ * pattern's keys (partial match — extra keys in the stored
+ * params are ignored). Pass nothing to clear every known slot.
  *
- * @internal
+ * @internal Public surface lives on `context.actions.resource.nuke(...)`.
  */
-export declare function consumePending(): PendingCall;
+export declare function nuke(where?: object): void;
 /**
  * Defines a remote resource — 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.
+ * directly. Exported as `shared.Resource` and (via the app factory) as
+ * `app.Resource`. Calling the returned handle with `params` produces an
+ * {@link Invocation} suitable for `context.actions.resource(...)` (fetch
+ * path) or `context.actions.resource(...).evict(where?)` (partial-match
+ * invalidation). Use `.get(params)` on the handle for a synchronous
+ * cache read returning `T | null`. Persistence happens automatically
+ * when the App is declared with `App({ cache })`.
+ *
+ * Takes the **Env shape `E` as a mandatory first generic** —
+ * `context.env` inside the fetcher is typed as `E`. Pass a union of
+ * every App's Env if the resource is shared across reusable
+ * components. For single-app resources, prefer `app.Resource` —
+ * the Env is captured from `app` automatically and you only need the
+ * payload generic.
  *
  * The fetcher receives a single `context` argument carrying `env`,
  * `controller`, `params`, and a broadcast/multicast-only `dispatch`.
- * `env` is a live handle — dot reads inside the fetcher
- * always see the latest per-`<Boundary>` Env, even after `await`
- * boundaries. Every successful fetch writes through to a per-resource
- * in-memory cache; pair with {@link Resource.Cachable} to persist
- * across reloads.
+ * `env` is a live handle &mdash; dot reads inside the fetcher always
+ * see the latest per-`<Boundary>` Env, even after `await` boundaries.
+ *
+ * Cache behaviour is decided at the App level: when `App({ cache })`
+ * is supplied, every `app.Resource` declaration on that App writes
+ * through to (and seeds from) the shared cache, isolated per resource
+ * by a stable module-order namespace. When the App is constructed
+ * without a `cache`, every resource keeps its own in-memory slot.
+ * Standalone `shared.Resource` declarations always use an in-memory
+ * cache &mdash; reach for `app.Resource` when persistence is required.
  *
  * Concurrent calls fire fresh requests by default. Opt in to in-flight
  * sharing per call via `.coalesce(key)` on the thenable returned from
  * `context.actions.resource(...)`.
  *
+ * @template E The Env shape (or union) the fetcher's `context.env` is
+ *   typed against.
+ * @template T The payload type the fetcher resolves to.
+ * @template P The call-time params type.
+ *
  * @example
  * ```ts
- * import { Resource } from "march-hare";
+ * import { shared } from "march-hare";
  *
- * export const user = Resource<User, { id: number }>((context) =>
+ * type WebEnv = { session: Session | null };
+ *
+ * export const user = shared.Resource<WebEnv, User, { id: number }>((context) =>
  *   ky
  *     .get(`users/${context.params.id}`, {
  *       headers: context.env.session
@@ -44,36 +69,9 @@ export declare function consumePending(): PendingCall;
  *     .json<User>(),
  * );
  * ```
+ *
+ * @internal The optional `cache` argument is reserved for `app.Resource`
+ *   &mdash; consumers should use `App({ cache })` instead of passing it
+ *   directly.
  */
-export declare function Resource<T, P extends object = Record<never, never>>(ƒ: Fetcher<T, P>): ResourceHandle<T, P>;
-export declare namespace Resource {
-    /**
-     * Cache-aware variant of {@link Resource}. The supplied {@link Cache}
-     * is the **first** argument &mdash; persistence is the headline of
-     * this form, the fetcher is the operation. Every successful fetch
-     * writes through to the cache; first reads via the call form
-     * auto-seed from the cache's adapter.
-     *
-     * @example
-     * ```ts
-     * import { Cache, Resource } from "march-hare";
-     *
-     * const cache = Cache({
-     *   get: (key) => localStorage.getItem(key),
-     *   set: (key, value) => localStorage.setItem(key, value),
-     *   remove: (key) => localStorage.removeItem(key),
-     *   clear: () => localStorage.clear(),
-     * });
-     *
-     * export const cat = Resource.Cachable(cache, async (context) =>
-     *   ky
-     *     .get("https://api.thecatapi.com/v1/images/search", {
-     *       signal: context.controller.signal,
-     *     })
-     *     .json<Cat[]>()
-     *     .then((cats) => cats[0]),
-     * );
-     * ```
-     */
-    function Cachable<T, P extends object = Record<never, never>>(cache: Cache, ƒ: Fetcher<T, P>): ResourceHandle<T, P>;
-}
+export declare function Resource<E extends object, T, P extends object = Record<never, never>>(ƒ: AppFetcher<E, T, P>, cache?: Cache): ResourceHandle<T, P>;

package/dist/resource/types.d.ts

@@ -62,42 +62,65 @@ export type Config<T, P extends object = Record<never, never>> = {
     readonly cache?: Cache;
 };
 /**
- * Snapshot of the most recent resource invocation. `resource.cat(params)`
- * writes one of these into a module-scope slot; the next
- * `context.actions.resource(...)` / `.set(...)` call consumes it via
- * `consumePending` and then clears the slot.
+ * Descriptor produced by calling a Resource handle. Carries the per-call
+ * `params` together with the closures `context.actions.resource(...)`
+ * needs to run, read, or evict the slot. Pass it straight to
+ * `context.actions.resource(invocation)` &mdash; no module-level state
+ * sits between the producer and the consumer, so two synchronous calls
+ * to the same Resource are independent values that can be stored,
+ * deferred, or passed across `await` boundaries safely.
  *
  * @internal
  */
-export type PendingCall = {
-    readonly run: (env: Env, controller: AbortController, params: object, dispatch: Dispatch) => Promise<unknown>;
+export type Invocation<T, P extends object = Record<never, never>> = {
+    readonly run: (env: Env, controller: AbortController, params: object, dispatch: Dispatch) => Promise<T>;
     readonly read: (params: object) => {
-        data: unknown;
+        data: T | symbol;
         at: Temporal.Instant | null;
     };
-    readonly seed: (params: object, data: unknown, at: Temporal.Instant) => void;
-    readonly params: object;
+    readonly evict: (where: object) => void;
+    readonly params: P;
 };
 /**
- * Resource handle returned by `Resource(...)` or `Resource.Cachable(...)`.
- * 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.
+ * Resource handle returned by `Resource(...)` (or its `app.Resource` /
+ * `shared.Resource` counterparts). Call it with `params` to produce an
+ * {@link Invocation} suitable for `context.actions.resource(...)`. Use
+ * `.get(params)` for a synchronous cache read.
+ *
+ * - `resource.cat.get({id: 5})` &mdash; sync read, returns `T | null`.
+ * - `context.actions.resource(resource.cat({id: 5}))` &mdash; fetch.
+ * - `context.actions.resource(resource.cat({id: 5})).evict()` &mdash;
+ *   drop the `{id: 5}` slot.
+ * - `context.actions.resource(resource.cat()).evict({name: "Adam"})`
+ *   &mdash; evict every cached `cat` entry whose stored params include
+ *   `name: "Adam"`, regardless of other keys.
+ * - `context.actions.resource.nuke({id: 5})` &mdash; partial-match
+ *   eviction across every resource on the App; nuke with no argument
+ *   clears every known slot.
  *
  * ```ts
  * // Sync cache read in a model literal.
- * { cat: resource.cat({ id: 5 }) }
+ * { cat: resource.cat.get({ id: 5 }) }
  *
  * // Fetch with `.exceeds(...)` for cache-aware refresh.
  * await context.actions
  *   .resource(resource.cat({ id: 5 }))
  *   .exceeds({ minutes: 5 });
  *
- * // Write through to the per-params cache slot.
- * context.actions.resource.set(resource.cat({ id: 5 }), data);
+ * // Evict the {id: 5} slot.
+ * context.actions.resource(resource.cat({ id: 5 })).evict();
  * ```
  */
-export type ResourceHandle<T, P extends object = Record<never, never>> = [
+export type ResourceHandle<T, P extends object = Record<never, never>> = ([
     keyof P
-] extends [never] ? (params?: P) => T | null : (params: P) => T | null;
+] extends [never] ? (params?: P) => Invocation<T, P> : (params: P) => Invocation<T, P>) & {
+    readonly get: [keyof P] extends [never] ? (params?: P) => T | null : (params: P) => T | null;
+};
+/**
+ * Drops cache slots whose stored params match the supplied `where`
+ * pattern. Each Resource registers one of these on declaration so
+ * `nuke(where)` can iterate them.
+ *
+ * @internal
+ */
+export type ResourceEvictor = (where: object) => void;

package/dist/resource/utils.d.ts

@@ -1,5 +1,6 @@
 import { Cache } from '../cache/index';
-import { unset } from '../utils/index';
+import { unset } from '../utils/utils';
+import { Fetcher, ResourceEvictor, ResourceHandle } from './types';
 export { Cache } from '../cache/index';
 /**
  * Default in-memory `Cache` used when {@link Resource} is constructed
@@ -35,3 +36,30 @@ export declare function key(params: object): string;
 export declare const config: {
     readonly unset: typeof unset;
 };
+/**
+ * Per-Resource eviction callbacks. Each `Resource` declaration registers
+ * one entry on construction; the public `nuke(...)` (defined in
+ * {@link "./index.ts"}) iterates them to drop cache slots across every
+ * Resource in the process.
+ *
+ * @internal
+ */
+export declare const evictors: Array<ResourceEvictor>;
+/**
+ * Mints the next namespace id for an app-shared cache. Each `app.Resource`
+ * declaration consumes one id so the shared {@link Cache} can keep
+ * resource-specific slots from colliding on shared params keys.
+ *
+ * @internal
+ */
+export declare function nextResourceId(fetcher: object): string;
+/**
+ * Allocates the per-Resource closure shared by `app.Resource` and
+ * `shared.Resource`. The returned callable produces an
+ * {@link Invocation} on every call &mdash; pass it to
+ * `context.actions.resource(...)` for fetch/evict. `.get(params)` reads
+ * the per-params cache slot synchronously.
+ *
+ * @internal
+ */
+export declare function build<T, P extends object>(ƒ: Fetcher<T, P>, backing: Cache, namespace: string | null): ResourceHandle<T, P>;

package/dist/scope/index.d.ts

@@ -1,63 +1,38 @@
-import { AppContextHandle, AppResource } from '../app/types';
-import { Actions, Model, Props } from '../types/index';
-import * as React from "react";
+import { ScopeHandle } from './types';
+export type { ScopeHandle } from './types';
+export { createScope } from './utils';
 /**
- * Handle returned by `app.Scope<MulticastActions>()`. Mirrors the {@link App}
- * surface (`Boundary`, `useContext`, `useEnv`, `Resource`) but typed
- * against a specific multicast action surface `MulticastActions` and the
- * enclosing App's Env shape `S`.
+ * Standalone counterpart to `app.Scope<MulticastActions>()`, exported
+ * as `shared.Scope` &mdash; opens a typed multicast scope without
+ * going through an `App` handle. Takes the **Env shape `E` as a
+ * mandatory first generic**, mirroring the other standalone exports
+ * (`shared.useContext`, `shared.useEnv`, `shared.Resource`). The Env
+ * carried by `scope.useContext()` is typed as `E`.
  *
- * Notably absent: a nested `Scope` method. Nesting scopes is supported
- * at the React-tree level &mdash; just render two `<scope.Boundary>`s
- * &mdash; but each scope must come from a distinct
- * `app.Scope<MulticastActions>()` call so that its multicast surface is
- * declared up-front.
+ * Use this in reusable feature modules that need to open their own
+ * multicast scope without binding to one App's `app.Scope` factory.
+ * For single-app code, prefer `app.Scope<MulticastActions>()` &mdash;
+ * the Env is captured from `app` automatically.
  *
- * @template S The enclosing App's Env shape.
- * @template MulticastActions The multicast Actions class (or union of
- *  classes) this scope's `useContext().actions.dispatch` is allowed
- *  to fire.
- */
-export type Scope<S extends object, MulticastActions> = {
-    /**
-     * Boundary component. Wrap a subtree to open a fresh multicast scope
-     * &mdash; every `Distribution.Multicast` action dispatched inside this
-     * subtree routes through this boundary's emitter, and every handler
-     * subscribed via `scope.useContext().useActions(...)` on that subtree
-     * receives the event.
-     *
-     * Each render of `<scope.Boundary>` opens a distinct scope instance;
-     * unmounting tears the emitter down.
-     */
-    readonly Boundary: React.FC<{
-        children: React.ReactNode;
-    }>;
-    /**
-     * Hook returning a stable `Context` handle. Identical to
-     * `app.useContext` except `actions.dispatch` accepts the multicast
-     * surface `MulticastActions` in addition to the local `AC` &mdash; mirroring
-     * the way `Actions.Broadcast = BroadcastActions` already widens the
-     * dispatch surface for broadcasts.
-     */
-    readonly useContext: <LocalModel extends Model | void = void, AC extends Actions | void = void, D extends Props = Props>() => AppContextHandle<LocalModel, MulticastActions extends Actions ? AC extends Actions ? AC & MulticastActions : MulticastActions : AC, D, S>;
-    /**
-     * Read-only Proxy over the enclosing App's Env. Identical to
-     * `app.useEnv` &mdash; the Scope does not introduce its own Env;
-     * scopes are about multicast routing, not ambient state.
-     */
-    readonly useEnv: () => Readonly<S>;
-    /**
-     * Resource factory bound to the enclosing App's Env. Identical to
-     * `app.Resource`; provided on the scope handle for convenience so a
-     * scoped feature can keep all its primitives in one place.
-     */
-    readonly Resource: AppResource<S>;
-};
-/**
- * Internal constructor for a {@link Scope} handle. Called from inside
- * `App<S>()` so the enclosing Env shape `S` is captured at the type
- * level.
+ * @template E The Env shape (or union) the scope's `useContext` types
+ *   `context.env` against.
+ * @template A The multicast Actions class (or union of classes) the
+ *   scope's dispatch surface is widened to include.
+ *
+ * @example
+ * ```tsx
+ * import { Action, Distribution, shared } from "march-hare";
+ *
+ * class MulticastActions {
+ *   static Mood = Action<"happy" | "sad">(
+ *     "Mood",
+ *     Distribution.Multicast,
+ *   );
+ * }
+ *
+ * type MoodEnv = { tracker: string };
  *
- * @internal
+ * export const scope = shared.Scope<MoodEnv, typeof MulticastActions>();
+ * ```
  */
-export declare function createScope<S extends object, MulticastActions>(): Scope<S, MulticastActions>;
+export declare function Scope<E extends object, A>(): ScopeHandle<E, A>;

package/dist/scope/types.d.ts

@@ -5,7 +5,7 @@ import type * as React from "react";
  * Handle returned by `app.Scope<MulticastActions>()`. Mirrors the
  * `App` surface (`Boundary`, `useContext`, `useEnv`, `Resource`) but
  * typed against a specific multicast action surface `MulticastActions`
- * and the enclosing App's Env shape `S`.
+ * and the enclosing App's Env shape `E`.
  *
  * Notably absent: a nested `Scope` method. Nesting scopes is supported
  * at the React-tree level &mdash; just render two `<scope.Boundary>`s
@@ -13,12 +13,12 @@ import type * as React from "react";
  * `app.Scope<MulticastActions>()` call so that its multicast surface is
  * declared up-front.
  *
- * @template S The enclosing App's Env shape.
+ * @template E The enclosing App's Env shape.
  * @template MulticastActions The multicast Actions class (or union of
  *  classes) this scope's `useContext().actions.dispatch` is allowed
  *  to fire.
  */
-export type Scope<S extends object, MulticastActions> = {
+export type ScopeHandle<E extends object, MulticastActions> = {
     /**
      * Boundary component. Wrap a subtree to open a fresh multicast scope
      * &mdash; every `Distribution.Multicast` action dispatched inside this
@@ -39,17 +39,17 @@ export type Scope<S extends object, MulticastActions> = {
      * mirroring the way `Actions.Broadcast = BroadcastActions` already
      * widens the dispatch surface for broadcasts.
      */
-    readonly useContext: <LocalModel extends Model | void = void, AC extends Actions | void = void, D extends Props = Props>() => AppContextHandle<LocalModel, MulticastActions extends Actions ? AC extends Actions ? AC & MulticastActions : MulticastActions : AC, D, S>;
+    readonly useContext: <LocalModel extends Model | void = void, AC extends Actions | void = void, D extends Props = Props>() => AppContextHandle<LocalModel, MulticastActions extends Actions ? AC extends Actions ? AC & MulticastActions : MulticastActions : AC, D, E>;
     /**
      * Read-only Proxy over the enclosing App's Env. Identical to
      * `app.useEnv` &mdash; the Scope does not introduce its own Env;
      * scopes are about multicast routing, not ambient state.
      */
-    readonly useEnv: () => Readonly<S>;
+    readonly useEnv: () => Readonly<E>;
     /**
      * Resource factory bound to the enclosing App's Env. Identical to
      * `app.Resource`; provided on the scope handle for convenience so a
      * scoped feature can keep all its primitives in one place.
      */
-    readonly Resource: AppResource<S>;
+    readonly Resource: AppResource<E>;
 };

package/dist/scope/utils.d.ts

@@ -0,0 +1,12 @@
+import { Cache } from '../cache/index';
+import { ScopeHandle } from './types';
+/**
+ * Internal constructor for a {@link ScopeHandle}. Called from inside
+ * `App<E>()` so the enclosing Env shape `E` is captured at the type
+ * level. The optional `cache` is the same value `App({ cache })` was
+ * constructed with &mdash; resources declared via `scope.Resource`
+ * share that cache.
+ *
+ * @internal
+ */
+export declare function createScope<E extends object, MulticastActions>(cache?: Cache): ScopeHandle<E, MulticastActions>;

package/dist/shared/index.d.ts

@@ -0,0 +1,15 @@
+import { AppFetcher } from '../app/types';
+import { ResourceHandle } from '../resource/types';
+export { useContext, useEnv } from '../app/index';
+export { Scope } from '../scope/index';
+/**
+ * Standalone counterpart to `app.Resource`, exported as
+ * `shared.Resource`. Takes the **Env shape `E` as a mandatory first
+ * generic** so the fetcher's `context.env` is typed even when the
+ * resource isn't bound to a single App.
+ *
+ * Always uses an isolated in-memory cache — persistent caching
+ * is an App-level concern wired through `App({ cache })`, so reach for
+ * `app.Resource` when a resource needs to survive reloads.
+ */
+export declare function Resource<E extends object, T, P extends object = Record<never, never>>(fetcher: AppFetcher<E, T, P>): ResourceHandle<T, P>;