march-hare 0.13.10 → 0.14.0

package/dist/resource/index.d.ts

@@ -2,7 +2,7 @@ import { ResourceHandle } from './types.js';
 import { Cache } from './utils.js';
 import { AppFetcher } from '../app/types.js';
 import { Env } from '../boundary/components/env/types.js';
-export type { Coalesce, Fetcher, Invocation, ResourceHandle } from './types.js';
+export type { Fetcher, Invocation, ResourceHandle } from './types.js';
 /**
  * Evicts cache entries across every Resource constructed in the
  * current process. Resources register themselves on declaration, so
@@ -44,9 +44,13 @@ export declare function nuke(where?: object): void;
  * Standalone `shared.Resource` declarations always use an in-memory
  * cache — 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(...)`.
+ * Concurrent calls with the same `(Resource, params)` share a single
+ * in-flight fetch by default — one network request, every caller
+ * resolves with the same payload. The underlying work is refcounted: if
+ * every caller aborts, the shared `AbortController` is aborted too.
+ * Chain `.isolated()` on the thenable returned from
+ * `context.actions.resource(...)` to opt out (own controller, own
+ * request) for the rare cases that need it.
  *
  * @template E The Env shape (or union) the fetcher's `context.env` is
  *   typed against.

package/dist/resource/types.d.ts

@@ -40,14 +40,6 @@ export type Args<P extends object = Record<never, never>> = {
  * and a broadcast/multicast-only `dispatch`.
  */
 export type Fetcher<T, P extends object = Record<never, never>> = (context: Args<P>) => Promise<T>;
-/**
- * Per-call coalescing token. Two callers with the same Resource, same
- * structural params, and equal `Coalesce` value share a single in-flight
- * promise; different tokens (or different params) fire independent
- * fetches. Primitives compose naturally via stringification; objects
- * are serialised with `JSON.stringify`.
- */
-export type Coalesce = string | number | bigint | boolean | symbol | object;
 /**
  * Config form accepted by `Resource`. The fetcher shorthand
  * `Resource(fetcher)` is equivalent to `Resource({ fetch: fetcher })`.

package/dist/types/index.d.ts

@@ -2,7 +2,7 @@ import { Operation, Process, Inspect as ImmInspect, Box } from 'immertation';
 import { ActionId, Task, Tasks } from '../boundary/components/tasks/types.js';
 import { Fault } from '../error/types.js';
 import { Env } from '../boundary/components/env/types.js';
-import { Coalesce, Invocation } from '../resource/types.js';
+import { Invocation } from '../resource/types.js';
 import { WithHandle } from '../with/types.js';
 import * as React from "react";
 /**
@@ -26,25 +26,22 @@ type ValueAt<T, K extends PropertyKey> = T extends unknown ? K extends keyof T ?
 export type Inspect<T, D extends number = 8> = ImmInspect<T> & ([D] extends [0] ? object : {
     [K in UnionKeys<T> as ValueAt<T, K> extends (...args: unknown[]) => unknown ? never : K]: Inspect<ValueAt<T, K>, DepthLimiter[D]>;
 });
-/**
- * Chainable handle returned from `context.actions.resource(invocation)`.
- *
- * - `.exceeds(duration)` short-circuits the fetch when the per-params
- *   cache age is within the supplied freshness window.
- * - `.coalesce(token)` opts the call into in-flight sharing: any other
- *   caller with the same Resource, same structural params, and equal
- *   `token` joins the same promise.
- *
- * Awaiting the handle (`await context.actions.resource(...)`) triggers
- * the fetch with whichever options have been set on the chain.
- */
 /**
  * Fetch-configured chain returned from `.exceeds(...)` and
- * `.coalesce(...)`. Awaiting the chain runs the fetch with whichever
+ * `.isolated()`. Awaiting the chain runs the fetch with whichever
  * options are set; `.evict()` is intentionally absent because the
  * "configured a fetch then evicted instead" sequence has no coherent
  * meaning &mdash; eviction is always available off the bare
  * `context.actions.resource(...)` call.
+ *
+ * Concurrent callers with the same `(Resource, params)` automatically
+ * share a single in-flight fetch &mdash; one network request, every
+ * caller resolves with the same payload. The shared fetch runs on a
+ * detached `AbortController` so one caller's abort never cancels work
+ * other callers are still waiting on; when every caller has released
+ * (their `context.task.controller` aborted) the shared controller is
+ * aborted too. Chain `.isolated()` to opt out for the rare case that
+ * needs an independent request.
  */
 export type ResourceFetch<T> = PromiseLike<T> & {
     /**
@@ -54,22 +51,25 @@ export type ResourceFetch<T> = PromiseLike<T> & {
      */
     readonly exceeds: (duration: Temporal.DurationLike) => ResourceFetch<T>;
     /**
-     * Join an in-flight fetch for the same `(resource, params, token)`
-     * tuple. The shared fetch runs against a detached `AbortController`
-     * so a single caller's abort never cancels work other callers are
-     * waiting on; each caller still sees its own `context.task.controller`
-     * abort as a rejection of its personal await.
+     * Opt this call out of the default `(Resource, params)` coalesce
+     * path. The fetch fires as an independent network request against
+     * the caller's own `context.task.controller` &mdash; no joining of
+     * any in-flight fetch, no refcounted detached controller. Aborting
+     * the caller's task cancels the network exactly as a regular fetch
+     * would.
      *
-     * `token` is optional &mdash; omit it to share with every other
-     * untokened caller for the same `(resource, params)` slot.
+     * Reach for this only when two callers need parallel fetches with
+     * byte-identical params and the difference in intent genuinely can't
+     * be modelled by differing params. The default is almost always
+     * what you want.
      */
-    readonly coalesce: (token?: Coalesce) => ResourceFetch<T>;
+    readonly isolated: () => ResourceFetch<T>;
 };
 /**
  * Chainable handle returned from `context.actions.resource(invocation)`.
- * Either resolve to the fetched value (`.exceeds`/`.coalesce` + await)
+ * Either resolve to the fetched value (`.exceeds`/`.isolated` + await)
  * or drop the cache slot (`.evict`) &mdash; the two paths are mutually
- * exclusive, so once `.exceeds` or `.coalesce` runs the chain narrows
+ * exclusive, so once `.exceeds` or `.isolated` runs the chain narrows
  * to {@link ResourceFetch} and `.evict` is no longer available.
  */
 export type ResourceCall<T> = ResourceFetch<T> & {
@@ -175,9 +175,10 @@ export declare class Brand {
     static readonly Name: unique symbol;
     /**
      * Phantom brand identifying lifecycle actions returned by
-     * `Lifecycle.Mount()`, `Lifecycle.Unmount()`, `Lifecycle.Error()`, and
-     * `Lifecycle.Update()`. Carries the lifecycle's literal kind so that
-     * `useAction` can pick distinct overloads &mdash; in particular,
+     * `Lifecycle.Mount()`, `Lifecycle.Paint()`, `Lifecycle.Unmount()`,
+     * `Lifecycle.Error()`, and `Lifecycle.Update()`. Carries the lifecycle's
+     * literal kind so that `useAction` can pick distinct overloads &mdash; in
+     * particular,
      * `Lifecycle.Update` resolves its payload to `Partial<DeepReadonly<D>>`
      * against the surrounding `useActions` data generic instead of the
      * factory-level `Record<string, unknown>` placeholder. Without this
@@ -213,6 +214,7 @@ export declare const EnvSymbol: unique symbol;
  * ```ts
  * export class Actions {
  *   static Mount = Lifecycle.Mount();
+ *   static Paint = Lifecycle.Paint();
  *   static Unmount = Lifecycle.Unmount();
  *   static Error = Lifecycle.Error();
  *   static Update = Lifecycle.Update();
@@ -229,6 +231,14 @@ export declare const EnvSymbol: unique symbol;
 export declare class Lifecycle {
     /** Creates a Mount lifecycle action. Triggered once on component mount (`useLayoutEffect`). */
     static Mount(): LifecyclePayload<never, never, "Mount">;
+    /**
+     * Creates a Paint lifecycle action. Triggered once after the browser has
+     * committed the first frame (`useEffect`). Pairs with {@link Lifecycle.Mount}
+     * (pre-paint) &mdash; use Paint for work that should not delay the first
+     * paint: analytics &ldquo;viewed&rdquo; events, focus management, scroll-into-view,
+     * non-blocking prefetch, etc.
+     */
+    static Paint(): LifecyclePayload<never, never, "Paint">;
     /** Creates an Unmount lifecycle action. Triggered when the component unmounts. */
     static Unmount(): LifecyclePayload<never, never, "Unmount">;
     /** Creates an Error lifecycle action. Triggered when an action throws. Receives `Fault` as payload. */
@@ -407,20 +417,21 @@ export type HandlerPayload<P = unknown, C extends Filter = never, Name extends s
     (channel: C): ChanneledAction<P, C, Name>;
 });
 /**
- * Branded type returned by `Lifecycle.Mount`, `Lifecycle.Unmount`,
- * `Lifecycle.Error`, and `Lifecycle.Update`. Structurally identical to a
- * `HandlerPayload` but carries a phantom `Brand.Lifecycle` brand whose value
- * is the lifecycle's literal kind. The brand is what lets `useAction` and
- * `Handlers` resolve `Lifecycle.Update`'s payload to `Partial<DeepReadonly<D>>`
- * (against the surrounding `useActions` data generic) instead of the
- * factory-level `Record<string, unknown>` placeholder &mdash; a user-defined
- * `Action<P>("Update")` would have `Name = "Update"` but no `Brand.Lifecycle`,
- * so it falls into the generic payload overload as expected.
+ * Branded type returned by `Lifecycle.Mount`, `Lifecycle.Paint`,
+ * `Lifecycle.Unmount`, `Lifecycle.Error`, and `Lifecycle.Update`.
+ * Structurally identical to a `HandlerPayload` but carries a phantom
+ * `Brand.Lifecycle` brand whose value is the lifecycle's literal kind. The
+ * brand is what lets `useAction` and `Handlers` resolve `Lifecycle.Update`'s
+ * payload to `Partial<DeepReadonly<D>>` (against the surrounding `useActions`
+ * data generic) instead of the factory-level `Record<string, unknown>`
+ * placeholder &mdash; a user-defined `Action<P>("Update")` would have
+ * `Name = "Update"` but no `Brand.Lifecycle`, so it falls into the generic
+ * payload overload as expected.
  *
  * @template P Payload type for the lifecycle.
  * @template C Channel filter (always `never` for lifecycles &mdash; they are
  *   not channeled).
- * @template Name Literal name (`"Mount"`, `"Unmount"`, `"Error"`, `"Update"`).
+ * @template Name Literal name (`"Mount"`, `"Paint"`, `"Unmount"`, `"Error"`, `"Update"`).
  */
 export type LifecyclePayload<P = unknown, C extends Filter = never, Name extends string = string> = HandlerPayload<P, C, Name> & {
     readonly [Brand.Lifecycle]: Name;

package/package.json

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