@foir/sdk 0.9.0 → 0.10.0

package/dist/live/resync.d.ts

@@ -0,0 +1,59 @@
+import type { FoirRequestError } from '../transport/foir-http';
+/**
+ * live/resync.ts — when the cache has to admit it cannot be repaired.
+ *
+ * # There is no gap to detect, and that is the point
+ *
+ * The obvious design for "did I miss a message" is a contiguous counter, and it
+ * does not work on this stream: `seq` is the project's clock and record changes
+ * are only some of what advances it, so two consecutive `recordChanged`
+ * messages are LEGITIMATELY non-adjacent. "I missed one" and "nothing else
+ * happened" are indistinguishable by counting.
+ *
+ * A cursor needs only ordering, which `seq` has. So the subscription hands back
+ * the highest seq it applied and the server replays what came after it — a drop
+ * anywhere upstream is repaired by the next connect rather than noticed by a
+ * counter, and there is no gap signal to act on because there is no gap.
+ *
+ * # What is left is the two refusals
+ *
+ * The server refuses a cursor it cannot honour rather than replaying part of it,
+ * because a cache handed a partial backlog believes it is caught up — which is
+ * exactly the silent staleness the cursor removes. Those refusals are the only
+ * "your cache is unreliable now" the client ever gets, and each is a HARD
+ * RESYNC: throw the cache away and refetch, because there is no way to know what
+ * was missed.
+ */
+/**
+ * `cursor_expired` — the cursor is older than the log's retention window.
+ * `backlog_too_large` — the cursor is further behind than the surface will page.
+ *
+ * Both arrive as a graphql-ws `error` frame with the code in `extensions`, and
+ * both are refusals to HANDLE rather than failures to report. Branch on the
+ * code, never on the message: the sentence is documentation and will be
+ * reworded, the code is the contract.
+ */
+export declare const FOIR_RESYNC_ERROR_CODES: readonly ["cursor_expired", "backlog_too_large"];
+export type FoirResyncErrorCode = (typeof FOIR_RESYNC_ERROR_CODES)[number];
+/**
+ * Whether a terminal subscription error means the cache must be thrown away.
+ *
+ * Anything else is a refusal about THIS subscription — a missing scope, an
+ * unwatchable model, a transport that gave up — and says nothing about whether
+ * what is already cached is still true. Resyncing on those would turn a
+ * permission error into a full refetch storm on every reconnect attempt.
+ */
+export declare function foirRequiresResync(error: Pick<FoirRequestError, 'code'>): boolean;
+/**
+ * The cursor to resume from after a refusal, when the server named one.
+ *
+ * `cursor_expired` carries `resumeFrom` — one below the oldest event still
+ * retained, so resuming from it loses nothing that still exists. Resuming there
+ * is only sound AFTER a resync: it skips everything that fell out of the window,
+ * and a cache that kept its entries would keep them wrong forever.
+ *
+ * `backlog_too_large` names no resume position on purpose. The honest recovery
+ * is to refetch and start from the seq that read reports, which is a value the
+ * client obtains from the response rather than from the refusal.
+ */
+export declare function foirResumeCursor(error: Pick<FoirRequestError, 'graphQLErrors'>): number | null;

package/dist/live/store.d.ts

@@ -0,0 +1,134 @@
+import type { FoirRecordChangedEvent } from '../data/subscriptions';
+import { type FoirTagIndex } from './tagIndex';
+/**
+ * live/store.ts — the client's half of the invalidation graph.
+ *
+ * # IT STORES THE RAW WIRE PAYLOAD, and hydration happens at the read boundary
+ *
+ * This is the load-bearing decision in the file and it is forced, not chosen.
+ * `FoirDecimal` is a class with `#`-private fields, and every ordinary cache
+ * reflex breaks on it QUIETLY:
+ *
+ *   - `Object.keys(d)` is `[]`. A structural deep-equal walking own enumerable
+ *     properties sees `{}` for every decimal, so it reports `decimal('1.00')`
+ *     equal to `decimal('999.99')`. That is a false NEGATIVE on change
+ *     detection — the cache serves a stale value and never learns otherwise,
+ *     which is worse than a false positive by every measure.
+ *   - `structuredClone(d)` returns `{}` and DOES NOT THROW. The standard deep
+ *     clone a cache reaches for destroys the value in silence.
+ *   - `[Symbol.toPrimitive]` throws on the number and default hints, so any
+ *     comparison doing `a < b` or `Number(a)` for ordering is a `TypeError`.
+ *   - `toJSON()` emits the canonical string and `JSON.parse` does not revive it,
+ *     so persistence is asymmetric by type.
+ *   - `equals()` is scale-insensitive while `toString()` is scale-preserving, so
+ *     even a correct comparison cannot be reference- or text-based.
+ *
+ * Raw wire JSON has none of those properties, because a decimal there is just a
+ * string. Change detection becomes an exact string compare, persistence is
+ * correct by construction (persist raw, rehydrate through the same path as a
+ * fresh response), and the completeness mask operates on the raw keys `omit`
+ * already operates on.
+ *
+ * So: **never cache hydrated entities.** There is no `structuredClone` and no
+ * generic deep-equal anywhere below, and their absence is the design rather than
+ * an omission.
+ *
+ * # Keys normalise, payloads never do
+ *
+ * The converse hazard, and the more expensive one. Dedupe entities by value and
+ * keep the first instance and you serve `"1.0"` where the server sent `"1.00"` —
+ * a silent change to how a price renders, because trailing zeros are significant
+ * for money. The store never holds a decimal instance at all, so this half falls
+ * out for free. `live/keys.ts` does the normalising, on keys only.
+ */
+/** One cached response, exactly as it came off the wire. */
+export interface FoirLiveEntry {
+    /**
+     * The RAW payload. Not hydrated, not cloned, not normalised — see the file
+     * comment. Treat as immutable: it is handed out by reference, and a consumer
+     * that mutates it corrupts every future read of this key.
+     */
+    payload: unknown;
+    /** The response's dependency set, as the server computed it. */
+    tags: readonly string[];
+    /** The project seq this response resolved under, or `null` for unknown. */
+    seq: number | null;
+    /**
+     * The fields the call asked the server to leave out. The COMPLETENESS MASK.
+     * Empty means the entry is whole.
+     */
+    omitted: readonly string[];
+    /** When it was written, for a consumer applying its own staleness floor. */
+    storedAt: number;
+}
+export interface FoirLiveWrite {
+    payload: unknown;
+    tags?: readonly string[];
+    seq?: number | null;
+    /** The call's `omit`, verbatim. */
+    omit?: readonly string[];
+}
+export interface FoirLiveReadOptions {
+    /**
+     * Fields this read needs present. An entry that declares any of them omitted
+     * is a MISS rather than a partial answer.
+     */
+    needs?: readonly string[];
+}
+/** What changed, so a consumer can act on it without diffing the store. */
+export interface FoirLiveInvalidation {
+    /** The keys dropped by this event. */
+    keys: string[];
+    /** The tags the event resolved to. */
+    tags: string[];
+    /** True when the event was ignored as already applied. */
+    ignored: boolean;
+}
+/**
+ * The write half of one in-flight request, handed to the function that issues
+ * it.
+ *
+ * It exists because the fence CANNOT be established at write time. A write that
+ * belongs to a request issued before a resync has to be recognisable as such
+ * when it lands, and by then the store looks exactly as it does for a fresh one
+ * — so the moment that has to be captured is the moment the request STARTS.
+ * Handing the fence to the running function is what makes that unforgettable:
+ * the natural way to store a response is through the object you were given.
+ */
+export interface FoirWriteFence {
+    /** Write this request's response, unless the store has resynced since. */
+    write(write: FoirLiveWrite): boolean;
+    /** Whether this request is still current. */
+    readonly current: boolean;
+}
+export interface FoirLiveStore {
+    /** Read an entry, honouring the completeness mask. */
+    read(key: string, options?: FoirLiveReadOptions): FoirLiveEntry | undefined;
+    /**
+     * Write a response, UNFENCED. Refuses a result older than the one already
+     * applied, but knows nothing about resyncs — use the fence `dedupe` hands the
+     * running function for anything that came off the network.
+     */
+    write(key: string, write: FoirLiveWrite): boolean;
+    /** Drop one key. */
+    drop(key: string): void;
+    /**
+     * Share one in-flight request between concurrent callers of the same key, and
+     * hand the runner a fence bound to this request's epoch.
+     */
+    dedupe<T>(key: string, run: (fence: FoirWriteFence) => Promise<T>): Promise<T>;
+    /** Apply a record change: drop everything that depended on it. */
+    applyRecordChange(event: FoirRecordChangedEvent): FoirLiveInvalidation;
+    /** Throw everything away, and fence anything already in flight. */
+    resync(): void;
+    /** Called after every invalidation and every resync. */
+    onInvalidate(listener: (invalidation: FoirLiveInvalidation) => void): () => void;
+    readonly size: number;
+    /** Test seam and introspection: the graph itself. */
+    readonly tags: FoirTagIndex;
+}
+export interface FoirLiveStoreOptions {
+    /** Clock, injectable so a test can pin `storedAt`. */
+    now?: () => number;
+}
+export declare function createFoirLiveStore(options?: FoirLiveStoreOptions): FoirLiveStore;

package/dist/live/tagIndex.d.ts

@@ -0,0 +1,29 @@
+/**
+ * live/tagIndex.ts — the dependency graph, both ways round.
+ *
+ * The server already knows which records and collections every response depends
+ * on; it has to, to invalidate its own cache. This is that graph held on the
+ * client: `key → tags` so an entry can be un-indexed when it is dropped, and
+ * `tag → keys` so an event can name what it invalidates without walking the
+ * store.
+ *
+ * Both directions, because keeping only one turns the other question into a
+ * linear scan of everything cached — and the read side runs on every response
+ * while the write side runs on every event. It is the same reason a database
+ * keeps an index rather than sorting on demand.
+ */
+export interface FoirTagIndex {
+    /** Replace the tag set for one key. */
+    set(key: string, tags: readonly string[]): void;
+    /** Forget a key entirely. */
+    remove(key: string): void;
+    /** The tags recorded for a key. */
+    tagsFor(key: string): readonly string[];
+    /** Every key that carries any of `tags`, deduped. */
+    keysForTags(tags: readonly string[]): string[];
+    /** Forget everything. */
+    clear(): void;
+    /** How many keys are indexed. */
+    readonly size: number;
+}
+export declare function createFoirTagIndex(): FoirTagIndex;

package/dist/live/tanstack.d.ts

@@ -0,0 +1,127 @@
+import type { FoirRecordChangedEvent } from '../data/subscriptions';
+import { type FoirLiveCall } from './keys';
+/**
+ * live/tanstack.ts — the adapter, and it is deliberately an adapter.
+ *
+ * Users keep the query library they already have. What is exported here is the
+ * query-key derivation and the rule for what a record change does to loaded
+ * pages; we own nothing of the rendering layer and no part of the cache.
+ *
+ * The differentiation is entirely in the invalidation graph, and an adapter
+ * captures all of it. A store of our own would add a permanent React support
+ * surface for no differentiated gain.
+ *
+ * ## Structurally typed, so `@tanstack/react-query` is not a dependency
+ *
+ * The three methods below are the whole of what this needs from a query client.
+ * A real `QueryClient` satisfies the interface, and the SDK neither imports nor
+ * pins a version of it — the same reason the Next adapter takes `cacheTag` as a
+ * function.
+ */
+export interface FoirQueryClientLike {
+    invalidateQueries(filters: {
+        queryKey: readonly unknown[];
+        exact?: boolean;
+    }): unknown;
+    getQueriesData(filters: {
+        queryKey: readonly unknown[];
+    }): Array<[readonly unknown[], unknown]>;
+    setQueriesData(filters: {
+        queryKey: readonly unknown[];
+    }, updater: (previous: unknown) => unknown): unknown;
+}
+/** The root every Foir query key starts with, so a filter can reach all of them. */
+export declare const FOIR_QUERY_KEY_ROOT: "foir";
+/**
+ * The query key for one call.
+ *
+ * An ARRAY, because that is what a query library filters on hierarchically:
+ * `['foir']` reaches every Foir query, `['foir', 'product']` reaches one model's,
+ * and the full key reaches one call. The last segment is `foirQueryKey`'s
+ * string, which is where the real work is — stable ordering, `undefined` kept
+ * distinct from absent, and decimals canonicalised so `1.0` and `1.00` are one
+ * entry rather than two.
+ */
+export declare function foirQueryKeys(call: FoirLiveCall): readonly unknown[];
+/** Every query for one model. */
+export declare function foirModelQueryKey(modelKey: string): readonly unknown[];
+/**
+ * How live a query is.
+ *
+ * `auto` — apply the full rule below.
+ * `notify` — never touch the data; report that something changed and let the UI
+ *   decide. The honest setting for a reader mid-scroll.
+ * `off` — ignore the stream entirely.
+ */
+export type FoirLiveMode = 'auto' | 'notify' | 'off';
+/** What one record change did, so a UI can render the parts it cannot do itself. */
+export interface FoirLiveEffect {
+    /** Queries whose data was refetched (an `updated` record they hold). */
+    invalidated: ReadonlyArray<readonly unknown[]>;
+    /** Queries a row was removed from without any fetch (a `deleted` record). */
+    removed: ReadonlyArray<readonly unknown[]>;
+    /**
+     * The model gained a record. NOT applied to any query — see below for why a
+     * create cannot be spliced — so a UI shows "N new" and refetches on a click.
+     */
+    created: boolean;
+    /** `totalCount` on this model's loaded queries is now approximate. */
+    totalCountStale: boolean;
+}
+export interface FoirApplyOptions {
+    mode?: FoirLiveMode;
+    /**
+     * The field a record's id arrives under. `_id` is the platform's own
+     * spelling and is what the generated types emit.
+     */
+    idField?: string;
+    /**
+     * Where an `updated` invalidation goes. Defaults to calling the query client
+     * straight away.
+     *
+     * The seam exists so a burst can be COALESCED: fifty writes on one model fire
+     * fifty invalidations, and refetching each one turns the exact screen a burst
+     * is most likely to be watched from into nothing but refetching. The
+     * coalescer takes the key here and runs one refetch per key per window.
+     *
+     * Only the update path is routed through it. A delete is applied in memory
+     * with no fetch at all, and a create deliberately fetches nothing — neither
+     * has anything to coalesce.
+     */
+    invalidate?: (queryKey: readonly unknown[]) => void;
+}
+/**
+ * Apply one record change to the loaded queries for its model.
+ *
+ * # Pagination, decided — and the three cases are handled ASYMMETRICALLY
+ * # because that is what the data supports
+ *
+ * Foir is pure Relay cursor pagination with no `offset` or `skip`, so loaded
+ * pages keep their relative order and `endCursor` stays correct. Only three
+ * things actually break:
+ *
+ *   - **`deleted` → remove the row by id, with NO FETCH.** The event carries
+ *     the id, so this is instantly correct and costs a round trip nothing.
+ *   - **`created` → expose a COUNT, do not refetch.** A create cannot be
+ *     spliced: record events carry no body, and even with one you could not
+ *     place the row without knowing the query's sort. Refetching the head page
+ *     instead was considered and rejected — it prepends under a reader
+ *     mid-scroll, which is the exact disruption this avoids.
+ *   - **`updated` → refetch the queries holding that record.** Membership is
+ *     unchanged, so the cursors hold.
+ *
+ * `totalCount` goes stale on any membership change and is flagged rather than
+ * corrected: correcting it would need a refetch, which is the thing being
+ * avoided.
+ *
+ * # Mutable sort keys are a DOCUMENTED LIMITATION, not a bug to fix
+ *
+ * A query ordered by `updatedAt`, or by a `position` a user drags, can have a
+ * record move between pages on update — appearing twice, or vanishing. There is
+ * no detection here and there should not be: it needs client-side knowledge of
+ * the sort fields, and the fully-correct alternative turns a routine edit into
+ * an N-page refetch on most feeds. Say it in the docs; do not build for it.
+ */
+export declare function applyFoirRecordChange(queryClient: FoirQueryClientLike, event: FoirRecordChangedEvent, options?: FoirApplyOptions): FoirLiveEffect;
+/** The tags one change would invalidate, for a consumer driving its own cache. */
+export declare function foirTagsForQueryInvalidation(event: FoirRecordChangedEvent): string[];

package/dist/live/writetoken.d.ts

@@ -0,0 +1,86 @@
+import type { FoirHeaderSource } from './headers';
+/**
+ * live/writetoken.ts — read your own write without throwing the cache away.
+ *
+ * # The problem it replaces
+ *
+ * The documented answer for reading your own write used to be
+ * `Cache-Control: no-cache`: skip the entry, resolve fresh, repopulate. It
+ * works, and it discards every warm entry on that path — so a storefront that
+ * does one write makes the next visitor pay a cold read on that query.
+ *
+ * A floor is the precise version. The mutation hands back a token naming where
+ * it committed; a later read carries it; the server serves a cached entry only
+ * if that entry resolved at or above the write's position, and resolves fresh
+ * otherwise. Same guarantee, and entries that are already fresh enough survive.
+ *
+ * # The token is opaque, and it is not a seq
+ *
+ * It names an EVENT, not a position, and the difference is why the mutation does
+ * not have to wait. `seq` is stamped asynchronously, by a different process on a
+ * different tick, so a mutation that waited for its own stamp could not complete
+ * unless a background loop elsewhere was alive and current — trading a
+ * permanently reliable write for a sometimes-faster read.
+ *
+ * So the read path resolves the token instead, and degrades correctly when it
+ * cannot: an unstamped event states no ordering yet, so the read simply resolves
+ * fresh, which is exactly the old `no-cache` behaviour for the tens of
+ * milliseconds before the stamp lands. Nothing here should try to parse it.
+ *
+ * # Why this is a primitive rather than automatic
+ *
+ * Holding "the last write token" is application state — which write, for how
+ * long, and across which of a user's tabs are questions this package cannot
+ * answer, and guessing produces either a floor that expires too early to help or
+ * one that pins reads to origin long after the write stopped mattering.
+ *
+ * So the SDK names the header and reads it; the consumer decides the lifetime.
+ * `readFoirLiveHeaders` takes the same line for the same reason.
+ */
+/**
+ * The header carrying the write token, in BOTH directions: out of a mutation's
+ * response, back in on a read's request.
+ *
+ * One name rather than a pair, because it is one value making a round trip and
+ * two names would be two things to keep in step.
+ *
+ * A header rather than a schema field, deliberately: a field would pull in
+ * foir-proto, a regen, the sync-gen job and the vocabulary mirrors, for a value
+ * that is transport bookkeeping and never part of anyone's data model.
+ */
+export declare const FOIR_WRITE_TOKEN_HEADER = "X-Foir-Write-Token";
+/**
+ * The write token a mutation's response carried, or `null`.
+ *
+ * Absent is the ordinary case for anything that did not write, and for a write
+ * whose emit produced no event. `null` means "no floor to state", never "floor
+ * of zero" — a zero floor would be satisfied by every cached entry ever, which
+ * is silently the opposite of what a caller asking for one wants.
+ *
+ * # It is readable from a browser, and that is not accidental
+ *
+ * A response header is invisible to cross-origin JS unless the server lists it
+ * in `Access-Control-Expose-Headers`, and api-public lists this one — alongside
+ * the matching entry on the ALLOWED REQUEST headers, so the token can also be
+ * sent back. Both halves are needed and the request half is the one that is easy
+ * to forget, because its absence is a preflight failure that names the header
+ * and not the file.
+ *
+ * What can still take it away is a proxy of the consumer's own sitting in front
+ * of the API. Stripped from the response, this returns `null` and looks exactly
+ * like a mutation that emitted nothing; stripped from the request, the floor is
+ * silently never applied.
+ */
+export declare function readFoirWriteToken(headers: FoirHeaderSource): string | null;
+/**
+ * The request headers a floored read should carry, or an empty object.
+ *
+ * Empty rather than a header with an empty value, because the two are different
+ * requests: a header present but blank is a floor the server has to interpret,
+ * and the honest way to say "no floor" is to say nothing.
+ *
+ * Sending this also changes the LANE — see `foirRoute`, which reports `floor`
+ * for a token-bearing read. A floor the shared edge cannot honour is worse than
+ * no floor at all, because it reads as satisfied.
+ */
+export declare function foirWriteTokenHeaders(token: string | null | undefined): Record<string, string>;