march-hare 0.12.1 → 0.13.1

package/dist/resource/index.d.ts

@@ -1,22 +1,27 @@
-import { PendingCall, ResourceHandle } from './types';
-import { Cache } from './utils';
-import { AppFetcher } from '../app/types';
-export type { Coalesce, Fetcher, PendingCall, ResourceHandle, } from './types';
+import { ResourceHandle } from './types.js';
+import { Cache } from './utils.js';
+import { AppFetcher } from '../app/types.js';
+export type { Coalesce, Fetcher, Invocation, ResourceHandle } from './types.js';
 /**
- * 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. Exported as `shared.Resource`. 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
@@ -29,8 +34,14 @@ export declare function consumePending(): PendingCall;
  * `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.
+ *
+ * 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
@@ -58,49 +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<E extends object, T, P extends object = Record<never, never>>(ƒ: AppFetcher<E, T, P>): ResourceHandle<T, P>;
-export declare namespace Resource {
-    /**
-     * Cache-aware variant of {@link Resource}, exported as
-     * `shared.Resource.Cachable`. The supplied {@link Cache} is the
-     * **second** argument (after the Env generic) &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.
-     *
-     * Takes the same **Env shape `E` as a mandatory first generic** as
-     * {@link Resource}. For single-app resources, prefer
-     * `app.Resource.Cachable(cache, fetcher)` &mdash; the Env is captured
-     * from `app` automatically.
-     *
-     * @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 { Cache, shared } from "march-hare";
-     *
-     * type WebEnv = { session: Session | null };
-     *
-     * 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 = shared.Resource.Cachable<WebEnv, Cat>(cache, async (context) =>
-     *   ky
-     *     .get("https://api.thecatapi.com/v1/images/search", {
-     *       signal: context.controller.signal,
-     *     })
-     *     .json<Cat[]>()
-     *     .then((cats) => cats[0]),
-     * );
-     * ```
-     */
-    function Cachable<E extends object, T, P extends object = Record<never, never>>(cache: Cache, ƒ: AppFetcher<E, 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

@@ -1,6 +1,6 @@
-import { Env } from '../boundary/components/env/index';
-import { Cache } from '../cache/index';
-import { BroadcastPayload, MulticastPayload, Filter } from '../types/index';
+import { Env } from '../boundary/components/env/types.js';
+import { Cache } from '../cache/index.js';
+import { BroadcastPayload, MulticastPayload, Filter } from '../types/index.js';
 /**
  * Dispatch surface exposed on a Resource fetcher's `context`. Restricted
  * to broadcast and multicast actions — unicast targets the calling
@@ -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,6 +1,7 @@
-import { Cache } from '../cache/index';
-import { unset } from '../utils/index';
-export { Cache } from '../cache/index';
+import { Cache } from '../cache/index.js';
+import { unset } from '../utils/utils.js';
+import { Fetcher, ResourceEvictor, ResourceHandle } from './types.js';
+export { Cache } from '../cache/index.js';
 /**
  * Default in-memory `Cache` used when {@link Resource} is constructed
  * without an explicit one. Each fetcher gets its own slot via the
@@ -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,66 +1,6 @@
-import { AppContextHandle, AppResource } from '../app/types';
-import { Actions, Model, Props } from '../types/index';
-import * as React from "react";
-/**
- * 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`.
- *
- * 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.
- *
- * @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.
- *
- * @internal
- */
-export declare function createScope<S extends object, MulticastActions>(): Scope<S, MulticastActions>;
+import { ScopeHandle } from './types.js';
+export type { ScopeHandle } from './types.js';
+export { createScope } from './utils.js';
 /**
  * Standalone counterpart to `app.Scope<MulticastActions>()`, exported
  * as `shared.Scope` &mdash; opens a typed multicast scope without
@@ -95,4 +35,4 @@ export declare function createScope<S extends object, MulticastActions>(): Scope
  * export const scope = shared.Scope<MoodEnv, typeof MulticastActions>();
  * ```
  */
-export declare function Scope<E extends object, A>(): Scope<E, A>;
+export declare function Scope<E extends object, A>(): ScopeHandle<E, A>;

package/dist/scope/types.d.ts

@@ -1,11 +1,11 @@
-import { AppContextHandle, AppResource } from '../app/types';
-import { Actions, Model, Props } from '../types/index';
+import { AppContextHandle, AppResource } from '../app/types.js';
+import { Actions, Model, Props } from '../types/index.js';
 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.js';
+import { ScopeHandle } from './types.js';
+/**
+ * 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

@@ -1,24 +1,15 @@
+import { AppFetcher } from '../app/types.js';
+import { ResourceHandle } from '../resource/types.js';
+export { useContext, useEnv } from '../app/index.js';
+export { Scope } from '../scope/index.js';
 /**
- * `shared` namespace — standalone counterparts to the `app.X`
- * factories returned by `App<E>()`. Each export takes the Env shape
- * `E` as a mandatory first generic so reusable components can run
- * under more than one App without binding to a single `app` import.
+ * 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.
  *
- * Reach for `shared.X` only when a component must support more than
- * one App. Single-app code should keep using `app.X` &mdash; the Env
- * is captured from `app` automatically and the call site is one
- * generic shorter.
- *
- * | Bound to an App                  | Standalone (`shared.X`)                  |
- * | -------------------------------- | ---------------------------------------- |
- * | `app.useContext<M, A, D>()`      | `shared.useContext<E, M, A, D>()`        |
- * | `app.useEnv()`                   | `shared.useEnv<E>()`                     |
- * | `app.Resource<T, P>(...)`        | `shared.Resource<E, T, P>(...)`          |
- * | `app.Resource.Cachable(...)`     | `shared.Resource.Cachable<E, T, P>(...)` |
- * | `app.Scope<A>()`                 | `shared.Scope<E, A>()`                   |
- *
- * @see {@link ./app/index.tsx App}
+ * Always uses an isolated in-memory cache &mdash; persistent caching
+ * is an App-level concern wired through `App({ cache })`, so reach for
+ * `app.Resource` when a resource needs to survive reloads.
  */
-export { useContext, useEnv } from '../app/index';
-export { Scope } from '../scope/index';
-export { Resource } from '../resource/index';
+export declare function Resource<E extends object, T, P extends object = Record<never, never>>(fetcher: AppFetcher<E, T, P>): ResourceHandle<T, P>;