import { Dispatch, LocalResourceHandle, 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 { Fetcher, Invocation, LocalInvocation, LocalResourceHandle, ResourceHandle, } from './types.js'; /** * 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. * * When called via `context.actions.resource.nuke(...)`, the calling * boundary's `dispatch` is threaded through so each evicted slot fires * a `null` broadcast on its Resource's `.action()` — subscribers * inside that boundary see the eviction as a `null` payload with the * evicted params as the channel. * * @internal Public surface lives on `context.actions.resource.nuke(...)`. */ export declare function nuke(where?: object, dispatch?: Dispatch): void; /** * Defines a remote resource — declared at module scope and used * 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-`` 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 — reach for `app.Resource` when persistence is required. * * 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. * @template T The payload type the fetcher resolves to. * @template P The call-time params type. * * @example * ```ts * import { shared } from "march-hare"; * * type WebEnv = { session: Session | null }; * * export const user = shared.Resource((context) => * ky * .get(`users/${context.params.id}`, { * headers: context.env.session * ? { Authorization: `Bearer ${context.env.session.accessToken}` } * : {}, * signal: context.controller.signal, * }) * .json(), * ); * ``` * * Calling `Resource()` with **no fetcher** declares a **local * Resource** — the same cache, sync `.get(params)`, `.action()` * auto-broadcast, eviction, and persistence machinery, but with the * app as the only writer: values enter exclusively through * `context.actions.resource(resource.draft(params)).set(value)`. One * write path per variant — a fetched Resource's cache is only * ever written by its fetcher, a local Resource's only ever by * `.set(...)` — so the origin of a cached value is always * unambiguous. Local invocations are not awaitable and carry no * `.exceeds(...)`/`.isolated()` chain. * * @example * ```ts * import { shared } from "march-hare"; * * export const draft = shared.Resource(); * * actions.useAction(Actions.Save, (context, { id, draft: value }) => { * context.actions.resource(draft({ id })).set(value); * }); * ``` * * @internal The optional `cache` argument is reserved for `app.Resource` * — consumers should use `App({ cache })` instead of passing it * directly. */ export declare function Resource<_E extends object, T, P extends object = Record>(): LocalResourceHandle; export declare function Resource>(ƒ: AppFetcher, cache?: Cache, getEnv?: () => Env | undefined): ResourceHandle; export declare function Resource<_E extends object, T, P extends object = Record>(ƒ: undefined, cache?: Cache, getEnv?: () => Env | undefined): LocalResourceHandle;