import { Env } from '../boundary/components/env/types.js';
import { Cache } from '../cache/index.js';
import { BroadcastPayload, MulticastPayload, BroadcastChanneled, ChanneledAction, Filter } from '../types/index.js';
/**
* Channel shape accepted by {@link ResourceHandle.action}: a partial of
* the resource's params. Keys not declared on `P` are rejected at
* compile time, so `.action({ unknownKey: ... })` fails to type-check
* — including the params-less case, where the channel collapses
* to an object whose only legal value for any key is `never`.
*/
export type ActionChannel
= [keyof P] extends [never] ? Record : Partial;
/**
* Dispatch surface exposed on a Resource fetcher's `context`. Restricted
* to broadcast and multicast actions — unicast targets the calling
* component, which a Resource fetcher does not have. Channeled
* dispatches (e.g. `dispatch(action({ UserId: 5 }), payload)`) are
* accepted on the same overloads — the routing layer reads the
* action's underlying distribution off its symbol.
*/
export type Dispatch = {
(action: BroadcastPayload | MulticastPayload | ChanneledAction): Promise;
(action: BroadcastPayload
| MulticastPayload
| ChanneledAction
, payload: P): Promise;
};
/**
* `context` object passed to every {@link Fetcher}.
*
* - `env` — live read-only handle to the per-`` Env.
* Dot reads always reflect the latest value, even across `await`
* boundaries inside the fetcher — the handle is a `Proxy`
* that delegates property access to the live ref, identical to
* the `context.env` exposed to action handlers.
* - `controller` — the `AbortController` auto-threaded from the
* calling handler's `context.task.controller`. Pass
* `controller.signal` to `fetch`/`ky`/`EventSource`, or call
* `controller.abort()` to fail fast.
* - `params` — the call-site params object. Defaults to `{}`.
* - `dispatch` — fire broadcast or multicast actions from inside
* the fetcher. Unicast is rejected at compile time.
*
* @internal
*/
export type Args> = {
readonly env: Env;
readonly controller: AbortController;
readonly params: P;
readonly dispatch: Dispatch;
};
/**
* Fetcher signature accepted by `Resource`. Receives a single `context`
* argument carrying a live Env handle, the abort controller, params,
* and a broadcast/multicast-only `dispatch`.
*/
export type Fetcher> = (context: Args) => Promise;
/**
* Config form accepted by `Resource`. The fetcher shorthand
* `Resource(fetcher)` is equivalent to `Resource({ fetch: fetcher })`.
*
* - `fetch` — the fetcher.
* - `cache` — persist successful payloads via a {@link Cache}
* wired to an `Adapter` (localStorage, MMKV, etc). Omit for an
* in-memory cache scoped to this Resource.
*/
export type Config> = {
readonly fetch: Fetcher;
readonly cache?: Cache;
};
/**
* 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)` — 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 Invocation> = {
readonly run: (env: Env, controller: AbortController, params: object, dispatch: Dispatch) => Promise;
readonly read: (params: object) => {
data: T | symbol;
at: Temporal.Instant | null;
};
readonly evict: (where: object, dispatch?: Dispatch) => void;
readonly params: P;
};
/**
* Descriptor produced by calling a local (fetcherless) Resource handle.
* Carries the per-call `params` together with the closures
* `context.actions.resource(...)` needs to write, read, or evict the
* slot. There is deliberately no `run` — a local Resource has no
* fetcher, so the invocation is not awaitable and the fetch-path
* chain (`.exceeds(...)`, `.isolated()`) does not exist on the
* resulting handle. `.set(value)` is the only write path.
*
* @internal
*/
export type LocalInvocation> = {
readonly write: (env: Env, params: object, value: T, dispatch: Dispatch) => void;
readonly read: (params: object) => {
data: T | symbol;
at: Temporal.Instant | null;
};
readonly evict: (where: object, dispatch?: Dispatch) => void;
readonly params: P;
};
/**
* 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})` — sync read, returns `T | null`.
* - `context.actions.resource(resource.cat({id: 5}))` — fetch.
* - `context.actions.resource(resource.cat({id: 5})).evict()` —
* drop the `{id: 5}` slot.
* - `context.actions.resource(resource.cat()).evict({name: "Adam"})`
* — evict every cached `cat` entry whose stored params include
* `name: "Adam"`, regardless of other keys.
* - `context.actions.resource.nuke({id: 5})` — 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.get({ id: 5 }) }
*
* // Fetch with `.exceeds(...)` for cache-aware refresh.
* await context.actions
* .resource(resource.cat({ id: 5 }))
* .exceeds({ minutes: 5 });
*
* // Evict the {id: 5} slot.
* context.actions.resource(resource.cat({ id: 5 })).evict();
* ```
*/
export type ResourceHandle> = ([
keyof P
] extends [never] ? (params?: Record) => Invocation : (params: P) => Invocation) & {
readonly get: [keyof P] extends [never] ? (params?: Record) => 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 — 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 — 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 — the cache is only written on
* success (see resource/utils.ts), and the broadcast follows the same
* gate.
*
* Eviction fires the same broadcast with a `null` payload: every
* call to `.evict(where?)` (via `context.actions.resource(...).evict`)
* or `context.actions.resource.nuke(where?)` walks the matching cache
* slots and dispatches `action(evictedParams)` with `null` for each,
* so the payload type is `T | null`.
*
* ```ts
* actions.useAction(user.action(), (context, value) => {
* if (value === null) return;
* });
* actions.useAction(user.action({ id: 5 }), (context, value) => { ... });
* actions.stream(user.action({ id: 5 }), (value) => {value?.name});
* ```
*/
readonly action: (channel?: ActionChannel) => BroadcastChanneled>;
};
/**
* Handle returned by a fetcherless `Resource()` declaration (or its
* `app.Resource()` / `shared.Resource()` counterparts). A local
* Resource holds app-written values rather than endpoint payloads:
* where a fetched Resource's cache is a materialised view of its
* fetcher's results, a local Resource's cache is written exclusively
* through `context.actions.resource(resource.draft(params)).set(value)`
* — one write path per variant, so a cached value's origin is
* always unambiguous.
*
* Everything else matches the fetched handle: `.get(params)` reads the
* slot synchronously, `.action(channel?)` is the auto-broadcast fired
* with the written value after every `.set(...)` (and with `null` on
* every eviction), subscribers replay from the broadcast cache on late
* mount, and slots participate in `.evict(where?)` and
* `context.actions.resource.nuke(where?)`. Persistence follows the
* same rule as fetched Resources — declare through `app.Resource`
* on an `App({ cache })` to survive reloads; `shared.Resource()` is
* always in-memory.
*
* Calling the handle produces a {@link LocalInvocation}, which is not
* awaitable — there is no fetcher to run, so `.exceeds(...)` and
* `.isolated()` do not exist on the resulting chain.
*/
export type LocalResourceHandle> = ([
keyof P
] extends [never] ? (params?: Record) => LocalInvocation : (params: P) => LocalInvocation) & {
readonly get: [keyof P] extends [never] ? (params?: Record) => T | null : (params: P) => T | null;
/**
* Broadcast channeled action fired automatically after every
* `.set(...)` on this Resource, with the written value as the
* payload and the call-site params as the channel. Eviction fires
* the same broadcast with a `null` payload, so the payload type is
* `T | null` — identical semantics to a fetched Resource's
* `.action()`, letting subscribers stay agnostic about whether the
* value was fetched or written locally.
*/
readonly action: (channel?: ActionChannel) => BroadcastChanneled>;
};
/**
* Drops cache slots whose stored params match the supplied `where`
* pattern, and — when a `dispatch` is provided — fires a
* `null` broadcast on the Resource's `.action()` for each removed
* slot, using the slot's stored params as the channel. Each Resource
* registers one of these on declaration so `nuke(where)` can iterate
* them.
*
* @internal
*/
export type ResourceEvictor = (where: object, dispatch?: Dispatch) => void;