march-hare 0.6.1 → 0.7.1

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

@@ -1,150 +0,0 @@
-import { Stored, Unset } from '../utils/index.ts';
-export type { Unset } from '../utils/index.ts';
-/**
- * Options accepted by `.if(...)` on a bound resource handle.
- *
- * - `over` – a `Temporal.Duration`, a `DurationLike` object
- *   (e.g. `{ minutes: 5 }`), or an ISO 8601 duration string (`"PT5M"`).
- *   If the most recent successful run resolved longer ago than this
- *   window, the underlying fetcher is called. Otherwise the cached
- *   data is returned without hitting the network.
- *
- * @example
- * ```ts
- * await user.if({ over: { minutes: 5 } });
- * await user.if({ over: "PT5M" });
- * await user.if({ over: Temporal.Duration.from({ minutes: 5 }) });
- * ```
- */
-export type IfOptions = {
-    readonly over: Temporal.DurationLike;
-};
-/**
- * Fetcher signature accepted by `Resource`. Receives the optional
- * `AbortSignal` first (threaded from the action handler's
- * `context.task.controller.signal`) and the call-site `params` second.
- * Side-effects (dispatching broadcasts, analytics, etc.) belong in the
- * calling `useAction` handler, not inside the fetcher.
- */
-export type ResourceFetcher<T, P extends object = Record<never, never>> = (signal: AbortSignal | undefined, params: P) => Promise<T>;
-/**
- * Module-scope handle returned by `Resource`. Pass to `useResource` to
- * obtain the bound, component-scoped callable.
- *
- * Every call to the underlying fetcher fires its own request. The most
- * recent successful response is cached in a module-level `WeakMap`
- * keyed by the fetcher itself, so `.if(...)` and `.else(...)` on the
- * bound handle have something to read from.
- */
-export type ResourceHandle<T, P extends object = Record<never, never>> = {
-    /** @internal */
-    readonly run: (signal: AbortSignal | undefined, params: P) => Promise<T>;
-    /**
-     * Most recent successfully-resolved payload, or the shared `unset`
-     * sentinel if no successful run has happened yet.
-     * @internal
-     */
-    readonly data: T | Unset;
-    /** @internal */
-    readonly at: Temporal.Instant | null;
-    /**
-     * Populates the cache slot with `data` and `at` without invoking the
-     * fetcher. Used by the bound handle's `.else(stored)` overload to
-     * hydrate the cache from a {@link Stored} fallback (typically the
-     * return value of `Store.get(key)` after a page reload).
-     * @internal
-     */
-    readonly seed: (data: T, at: Temporal.Instant) => void;
-};
-/**
- * Component-bound handle returned by `useResource`. The handle is itself
- * the fetch callable &mdash; `await user(signal?, params?)` triggers a
- * request &mdash; with attached read accessors and methods:
- *
- * - `.if({ over }, signal?, params?)` &mdash; fetch only if the cached
- *   payload is older than the supplied freshness window; otherwise
- *   return the cached payload synchronously.
- * - `.else(fallback)` &mdash; synchronous read of the cached payload,
- *   falling back to the supplied default when nothing has resolved
- *   successfully yet. Accepts either a value (terminal, returns
- *   `T | U`) or a {@link Stored} (chainable, seeds the cache from the
- *   Stored's data/at when the cache is empty and returns the same bound
- *   handle for further chaining).
- * - `.snapshot()` &mdash; returns a {@link Stored} wrapping the current
- *   cache state, symmetric with `Store.get(key)`. Pass straight to
- *   `Store.set(key, ...)` to persist the latest successful payload.
- * - `.data` and `.at` &mdash; the underlying cache fields. Reading
- *   `.snapshot()` is usually clearer.
- *
- * Call signature: `(signal?)` for resources with no params, or
- * `(signal: AbortSignal | null, params: P)` for parameterised
- * resources &mdash; pass `null` as the first argument when you have
- * params but no signal to thread.
- */
-export type BoundResourceHandle<T, P extends object> = [keyof P] extends [never] ? {
-    (signal?: AbortSignal): Promise<T>;
-    /**
-     * Calls the underlying fetcher if the most recent successful run
-     * resolved longer ago than `options.over`. Otherwise returns the
-     * cached data without hitting the network.
-     */
-    readonly if: (options: IfOptions, signal?: AbortSignal) => Promise<T>;
-    /**
-     * Overloaded fallback accessor.
-     *
-     * - `(fallback: U)` terminal &mdash; returns the cached payload, or
-     *   `fallback` when nothing has resolved yet. Cached `null` values
-     *   are returned verbatim.
-     * - `(stored: Stored<T>)` chainable &mdash; if the cache is empty
-     *   and the Stored carries data and a timestamp, seeds the cache
-     *   from it before returning the same bound handle so further
-     *   `.else(...)` calls compose. Used to hydrate the cache on first
-     *   render after a page reload, allowing `.if({ over })` to
-     *   short-circuit on the persisted timestamp.
-     */
-    readonly else: {
-        (stored: Stored<T>): BoundResourceHandle<T, P>;
-        <U>(fallback: U): T | U;
-    };
-    /**
-     * Snapshot of the current cache state in the shared {@link Stored}
-     * shape. Empty (`data === unset`, `at === null`) until a fetcher
-     * resolves; otherwise carries the most recent payload and the
-     * instant it resolved. Pass directly to `Store.set(key, ...)`.
-     */
-    readonly snapshot: () => Stored<T>;
-    /** Direct read of the cache payload. Prefer `.snapshot()`. */
-    readonly data: T | Unset;
-    /** Instant the cache was last populated, or `null` if empty. */
-    readonly at: Temporal.Instant | null;
-} : {
-    (signal: AbortSignal | null, params: P): Promise<T>;
-    /**
-     * Calls the underlying fetcher if the most recent successful run
-     * resolved longer ago than `options.over`. Otherwise returns the
-     * cached data without hitting the network.
-     */
-    readonly if: (options: IfOptions, signal: AbortSignal | null, params: P) => Promise<T>;
-    /**
-     * Overloaded fallback accessor.
-     *
-     * - `(fallback: U)` terminal &mdash; returns the cached payload, or
-     *   `fallback` when nothing has resolved yet.
-     * - `(stored: Stored<T>)` chainable &mdash; if the cache is empty
-     *   and the Stored carries data and a timestamp, seeds the cache
-     *   from it before returning the same bound handle.
-     */
-    readonly else: {
-        (stored: Stored<T>): BoundResourceHandle<T, P>;
-        <U>(fallback: U): T | U;
-    };
-    /**
-     * Snapshot of the current cache state in the shared {@link Stored}
-     * shape. Pass directly to `Store.set(key, ...)`.
-     */
-    readonly snapshot: () => Stored<T>;
-    /** Direct read of the cache payload. Prefer `.snapshot()`. */
-    readonly data: T | Unset;
-    /** Instant the cache was last populated, or `null` if empty. */
-    readonly at: Temporal.Instant | null;
-};

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

@@ -1,23 +0,0 @@
-import { unset } from '../utils/index.ts';
-/**
- * Module-level cache shared by every `Resource` declaration. Keyed by
- * the fetcher function itself so each module-scope declaration gets a
- * distinct slot — entries are garbage-collected when the fetcher
- * reference is dropped.
- *
- * @internal
- */
-export declare const cache: WeakMap<object, {
-    data: unknown;
-    at: Temporal.Instant;
-}>;
-/**
- * Re-export of the shared `unset` sentinel from {@link "../utils/index.ts"}.
- * Kept under `config` for back-compatibility with existing imports in this
- * module's siblings; new code should import `unset` directly from `utils`.
- *
- * @internal
- */
-export declare const config: {
-    readonly unset: typeof unset;
-};

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

@@ -1,101 +0,0 @@
-import { unset } from './utils.ts';
-/** Nominal type of the {@link unset} sentinel. */
-export type Unset = typeof unset;
-/**
- * On-disk JSON shape of a {@link Stored} envelope. The Store 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;
-};
-/**
- * Common shape for a possibly-present value with a timestamp. Produced by
- * `BoundResourceHandle.snapshot()` (from the in-memory cache) and by
- * `Store.get(key)` (from persistent storage). Both feed into the bound
- * handle's overloaded `.else(...)`, which seeds the cache when given a
- * Stored that carries data and a timestamp.
- *
- * @template T The payload type when present.
- */
-export type Stored<T> = {
-    /** The payload, or {@link unset} when nothing is recorded. */
-    readonly data: T | Unset;
-    /** When the payload was recorded, or `null` when nothing is recorded. */
-    readonly at: Temporal.Instant | null;
-    /**
-     * Returns {@link data} when present, otherwise the supplied fallback.
-     * Symmetric with `BoundResourceHandle.else(...)`'s terminal form.
-     */
-    readonly else: <U>(fallback: U) => T | U;
-};
-/**
- * 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 `store`. The adapter shuttles raw strings;
- * JSON encoding and `Temporal.Instant` round-tripping happen inside the
- * Store wrapper, so adapters stay trivial.
- */
-export type Adapter = {
-    /**
-     * Return the raw string stored under `key`, or `null` when no entry
-     * exists. The Store 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` — the Store 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 Store guarantees
-     * `value` is a JSON-encoded `{ data, at }` envelope produced by a
-     * resolved snapshot — never a placeholder. Throwing is fine on quota,
-     * private mode, sandboxed iframes, etc.; the Store 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 — 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 — 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;
-};
-/**
- * Bound storage instance returned by `store`. Reads return a
- * {@link Stored} handle so the result composes with the Resource bound
- * handle's `.else(...)`; writes accept a Stored and short-circuit on the
- * empty case to avoid persisting placeholder snapshots.
- */
-export type Store = Pick<Adapter, "remove" | "clear"> & {
-    /**
-     * Read the entry at `key` as a {@link Stored} envelope. Returns an
-     * empty Stored (`data: unset`, `at: null`) when nothing is recorded
-     * or when the persisted payload fails to parse — corrupted entries
-     * never reach the caller. The result composes directly with a
-     * Resource bound handle's `.else(...)` for seeding the cache after
-     * a reload.
-     */
-    readonly get: <T>(key: string) => Stored<T>;
-    /**
-     * Persist `value` under `key`. Returns `true` when the entry landed
-     * in the adapter, `false` otherwise. A `false` covers two distinct
-     * cases: the Stored had no payload yet (`data === unset` or
-     * `at === null`), or the adapter threw (quota, private mode, etc.).
-     * Callers that care about quota failures should branch on the
-     * return; callers writing on every dispatch can safely ignore it.
-     */
-    readonly set: <T>(key: string, value: Stored<T>) => boolean;
-};