march-hare 0.16.0 → 0.17.0

package/dist/resource/types.d.ts

@@ -1,14 +1,24 @@
 import { Env } from '../boundary/components/env/types.js';
 import { Cache } from '../cache/index.js';
-import { BroadcastPayload, MulticastPayload, Filter } from '../types/index.js';
+import { BroadcastPayload, MulticastPayload, ChanneledAction, Filter } from '../types/index.js';
+/**
+ * Helper that constrains `Partial<P>` to a {@link Filter}-compatible
+ * shape. Resource params hold primitive leaves by convention, so the
+ * auto-broadcast {@link ResourceHandle.action} can use them directly as
+ * a channel filter.
+ */
+export type ActionChannel<P extends object> = Partial<P> & Filter;
 /**
  * Dispatch surface exposed on a Resource fetcher's `context`. Restricted
  * to broadcast and multicast actions &mdash; unicast targets the calling
- * component, which a Resource fetcher does not have.
+ * component, which a Resource fetcher does not have. Channeled
+ * dispatches (e.g. `dispatch(action({ UserId: 5 }), payload)`) are
+ * accepted on the same overloads &mdash; the routing layer reads the
+ * action's underlying distribution off its symbol.
  */
 export type Dispatch = {
-    <C extends Filter = never>(action: BroadcastPayload<never, C> | MulticastPayload<never, C>): Promise<void>;
-    <P, C extends Filter = never>(action: BroadcastPayload<P, C> | MulticastPayload<P, C>, payload: P): Promise<void>;
+    <C extends Filter = never>(action: BroadcastPayload<never, C> | MulticastPayload<never, C> | ChanneledAction<never, C>): Promise<void>;
+    <P, C extends Filter = never>(action: BroadcastPayload<P, C> | MulticastPayload<P, C> | ChanneledAction<P, C>, payload: P): Promise<void>;
 };
 /**
  * `context` object passed to every {@link Fetcher}.
@@ -107,6 +117,31 @@ export type ResourceHandle<T, P extends object = Record<never, never>> = ([
     keyof P
 ] 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;
+    /**
+     * Broadcast channeled action fired automatically after every successful
+     * fetch of this Resource. Always invoke before subscribing: pass no
+     * arguments to match every fetch, or a partial-params object to narrow.
+     * Matching follows the subscriber-as-filter rule &mdash; every key on the
+     * subscriber's channel must equal the same key on the dispatch channel,
+     * and adding keys progressively narrows the filter.
+     *
+     * Late-mounting subscribers replay every cached entry whose channel
+     * satisfies their filter &mdash; the broadcast cache is sharded by
+     * `(action, channel)`, so a partial subscriber that mounts after
+     * several distinct fetches catches up with all of them rather than
+     * just the most recent.
+     *
+     * Failures do not broadcast &mdash; the cache is only written on
+     * success (see resource/utils.ts), and the broadcast follows the same
+     * gate.
+     *
+     * ```ts
+     * actions.useAction(user.action(), (context, value) => { ... });
+     * actions.useAction(user.action({ id: 5 }), (context, value) => { ... });
+     * actions.stream(user.action({ id: 5 }), (value) => <span>{value.name}</span>);
+     * ```
+     */
+    readonly action: (channel?: ActionChannel<P>) => ChanneledAction<T, ActionChannel<P>>;
 };
 /**
  * Drops cache slots whose stored params match the supplied `where`

package/dist/resource/utils.d.ts

@@ -1,5 +1,4 @@
 import { Cache } from '../cache/index.js';
-import { unset } from '../utils/utils.js';
 import { Env } from '../boundary/components/env/types.js';
 import { Fetcher, ResourceEvictor, ResourceHandle } from './types.js';
 export { Cache } from '../cache/index.js';
@@ -29,14 +28,6 @@ export declare function defaultCache(fetcher: object): Cache;
  * @internal
  */
 export declare function key(params: object): string;
-/**
- * Re-export of the shared `unset` sentinel from {@link "../utils/index.ts"}.
- *
- * @internal
- */
-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

package/dist/types/index.d.ts

@@ -550,20 +550,22 @@ export type Payload<A> = A extends {
  * By convention, use uppercase keys (e.g., `{UserId: 4}` not `{userId: 4}`)
  * to distinguish filter keys from payload properties.
  *
- * When dispatching, handlers are invoked if ALL properties in the dispatch filter
- * match the corresponding properties in the registered filter.
+ * **Matching direction:** the subscriber's filter is the constraint;
+ * every key the subscriber supplies must be present and equal on the
+ * dispatch channel. Extra keys on the dispatch channel are ignored, so a
+ * dispatcher is free to be more specific than any single subscriber
+ * needs. A subscriber that supplies no keys (uncalled action or empty
+ * filter) matches every dispatch.
  *
  * @example
  * ```ts
- * // Register a handler for a specific user
- * actions.useAction([Actions.User, { UserId: 1 }], handler);
- *
- * // Dispatch matches if all dispatch properties match registered properties
- * dispatch([Actions.User, { UserId: 1 }], payload);              // Matches
- * dispatch([Actions.User, { UserId: 2 }], payload);              // No match
- * dispatch([Actions.User, { UserId: 1, Role: "admin" }], payload); // Matches
- * dispatch([Actions.User, {}], payload);                         // Matches all
- * dispatch(Actions.User, payload);                               // Matches ALL handlers
+ * actions.useAction(Actions.User({ UserId: 1 }), handler);
+ *
+ * actions.dispatch(Actions.User({ UserId: 1 }), payload);                       // Matches (exact)
+ * actions.dispatch(Actions.User({ UserId: 2 }), payload);                       // No match (UserId mismatch)
+ * actions.dispatch(Actions.User({ UserId: 1, Role: "admin" }), payload);        // Matches (extra dispatch keys ignored)
+ * actions.dispatch(Actions.User({}), payload);                                  // No match (subscriber asked for UserId)
+ * actions.dispatch(Actions.User, payload);                                      // Matches ALL handlers (uncalled bypasses channel filtering)
  * ```
  */
 export type Filter = Record<string, string | number | bigint | boolean | symbol>;

package/dist/utils/utils.d.ts

@@ -5,6 +5,23 @@ import { Stored } from './types.js';
  * recorded" from "a legitimately stored null".
  */
 export declare const unset: unique symbol;
+/**
+ * Internal configuration shared across the Resource and Cache layers.
+ *
+ * - `unset` — re-export of the shared sentinel so consumers can pull
+ *   both fields from a single object.
+ * - `storageNamespace` — global prefix the Cache layer prepends to
+ *   every key it persists. Lets `Cache.clear()` and the partial-match
+ *   evictors scope themselves to the library's own entries on shared
+ *   backends (`localStorage`, `chrome.storage.local`, MMKV) without
+ *   nuking third-party state on the same origin.
+ *
+ * @internal
+ */
+export declare const config: {
+    readonly unset: typeof unset;
+    readonly storageNamespace: "mh:";
+};
 /**
  * Returns a function to force a component re-render. Useful when state is
  * managed externally (e.g., refs) but the UI needs updating.

package/dist/utils.d.ts

@@ -17,8 +17,6 @@ export declare const describe: {
     cache: (name?: string) => string;
     /** Lifecycle action description. `describe.lifecycle("Mount")` → `"march-hare.action.lifecycle/Mount"` */
     lifecycle: (name?: string) => string;
-    /** Mount replay sentinel description. Used to create the {@link replay} symbol. */
-    replay: (name?: string) => string;
 };
 /**
  * Flat record used for shallow property comparison in {@link changes}.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "march-hare",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "type": "module",
   "license": "MIT",
   "packageManager": "yarn@1.22.22",