orpc-fn 0.4.0 → 0.5.0

package/dist/react.js

@@ -0,0 +1,156 @@
+import { focusManager, hashKey, keepPreviousData, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { createInvalidationCoordinator, createStreamScope, createSubscriptionRunner, seedQueryFn } from './realtime.js';
+const subscribeFocus = (listener) => focusManager.subscribe(listener);
+const getFocus = () => focusManager.isFocused();
+/** Whether the app is focused, from TanStack's `focusManager`. */
+function useIsFocused() {
+    return useSyncExternalStore(subscribeFocus, getFocus, getFocus);
+}
+/**
+ * An oRPC event iterator with backoff reconnects that closes while the app is
+ * backgrounded. A changed input (compared as JSON) reconnects with a fresh
+ * retry budget.
+ */
+export function useOrpcSubscription(input, subscribe, options = {}) {
+    const { enabled = true, pauseWhenUnfocused = true } = options;
+    const focused = useIsFocused();
+    const shouldRun = enabled && (!pauseWhenUnfocused || focused);
+    const [status, setStatus] = useState('idle');
+    const latest = useRef({ input, subscribe, options, shouldRun });
+    latest.current = { input, subscribe, options, shouldRun };
+    const runnerRef = useRef(null);
+    if (!runnerRef.current) {
+        let openedInput = input;
+        runnerRef.current = createSubscriptionRunner({
+            open: (signal) => {
+                openedInput = latest.current.input;
+                return latest.current.subscribe(openedInput, { signal });
+            },
+            canConnect: () => latest.current.shouldRun,
+            shouldReconnect: () => latest.current.shouldRun,
+            onStatus: setStatus,
+            onEvent: (event, connectionId) => latest.current.options.onEvent?.(event, {
+                connectionId,
+                input: openedInput
+            }),
+            onConnect: (id) => latest.current.options.onConnect?.(id),
+            onError: (error) => latest.current.options.onError?.(error),
+            onClose: () => latest.current.options.onClose?.()
+        });
+    }
+    const runner = runnerRef.current;
+    const serializedInput = JSON.stringify(input);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: a changed input resubscribes
+    useEffect(() => {
+        if (!shouldRun)
+            return;
+        void runner.start();
+        return () => void runner.disconnect();
+    }, [runner, shouldRun, serializedInput]);
+    return { status };
+}
+export function useLiveQuery(input, queryOptionsFn, subscribe, options = {}) {
+    const queryClient = useQueryClient();
+    const focused = useIsFocused();
+    const [scope] = useState(createStreamScope);
+    // oRPC query options are plain objects; `queryFn` is read through one shape.
+    const raw = queryOptionsFn(input);
+    const keyHash = hashKey(raw.queryKey);
+    const latest = useRef({ raw, keyHash, options });
+    latest.current = { raw, keyHash, options };
+    const { status } = useOrpcSubscription((options.subscriptionInput === undefined
+        ? input
+        : options.subscriptionInput), subscribe, {
+        enabled: options.enabled,
+        pauseWhenUnfocused: options.pauseWhenUnfocused,
+        onError: options.onError,
+        onConnect: (connectionId) => scope.open(connectionId, latest.current.keyHash),
+        onEvent: (event, { connectionId }) => {
+            const current = latest.current;
+            // The consumer callback must not see an event for a scope no longer shown.
+            if (!scope.owns(connectionId, current.keyHash))
+                return;
+            // Without `applyEvent` the stream event is the cache type (the first overload).
+            const applyEvent = current.options.applyEvent ??
+                ((streamEvent) => streamEvent);
+            const key = current.raw.queryKey;
+            const next = applyEvent(event, queryClient.getQueryData(key));
+            if (next !== undefined)
+                queryClient.setQueryData(key, next);
+            current.options.onEvent?.(event, { connectionId });
+        }
+    });
+    const wrapsSeed = options.select || options.mergeSeed;
+    const queryFn = raw.queryFn && wrapsSeed
+        ? seedQueryFn(raw.queryFn, {
+            input,
+            readCache: () => queryClient.getQueryData(raw.queryKey),
+            select: options.select,
+            onSeed: options.onSeed,
+            mergeSeed: options.mergeSeed
+        })
+        : raw.queryFn;
+    const runs = options.enabled !== false && focused;
+    const query = useQuery({
+        ...raw,
+        ...(queryFn ? { queryFn } : {}),
+        enabled: runs ? (raw.enabled ?? true) : false,
+        ...(options.keepPreviousData === false
+            ? {}
+            : { placeholderData: keepPreviousData }),
+        staleTime: Number.POSITIVE_INFINITY,
+        meta: { ...raw.meta, live: true }
+    });
+    return Object.assign(query, { liveStatus: status });
+}
+/**
+ * One app-wide stream of `{ domain }` change events that keeps list and count
+ * queries fresh: each event invalidates its domain's query keys (debounced),
+ * and a reconnect that proves healthy invalidates every domain to cover
+ * events lost while it was down. Mount once, in the signed-in shell.
+ *
+ * ```ts
+ * useInvalidationStream({}, client.realtime.subscribeChanges, {
+ *   enabled: signedIn,
+ *   domains: { order: { debounceMs: 100, queryKeys: [orpc.order.key()] } }
+ * })
+ * ```
+ */
+export function useInvalidationStream(input, subscribe, options) {
+    const queryClient = useQueryClient();
+    const latestOptions = useRef(options);
+    latestOptions.current = options;
+    // `domains`, `refetchType` and `logger` are read on mount; `onEvent` stays current.
+    const [coordinator] = useState(() => createInvalidationCoordinator(queryClient, {
+        ...options,
+        onEvent: (event) => latestOptions.current.onEvent?.(event)
+    }));
+    useEffect(() => coordinator.dispose, [coordinator]);
+    return useOrpcSubscription(input, subscribe, {
+        enabled: options.enabled,
+        pauseWhenUnfocused: options.pauseWhenUnfocused,
+        onEvent: coordinator.event,
+        onConnect: coordinator.connect,
+        onError: coordinator.lost,
+        onClose: coordinator.lost
+    });
+}
+/**
+ * Clear the query cache when the signed-in owner of the cached data changes
+ * (another user, another organization), so the next one never sees it.
+ * `null` means signed out: signing in starts from the cache sign-out emptied.
+ * Pass the same owner as the persister's `buster` so a saved cache from
+ * someone else is discarded on the next launch too.
+ */
+export function useQueryCacheOwner(owner) {
+    const queryClient = useQueryClient();
+    const previous = useRef(owner);
+    useEffect(() => {
+        const before = previous.current;
+        previous.current = owner;
+        if (owner !== before && before !== null)
+            queryClient.clear();
+    }, [owner, queryClient]);
+}
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\tfocusManager,\n\thashKey,\n\tkeepPreviousData,\n\ttype QueryKey,\n\ttype UseQueryOptions,\n\ttype UseQueryResult,\n\tuseQuery,\n\tuseQueryClient\n} from '@tanstack/react-query'\nimport { useEffect, useRef, useState, useSyncExternalStore } from 'react'\nimport {\n\tcreateInvalidationCoordinator,\n\tcreateStreamScope,\n\tcreateSubscriptionRunner,\n\ttype InvalidationStreamOptions,\n\ttype LiveConnectionStatus,\n\ttype SubscriptionRunner,\n\tseedQueryFn\n} from './realtime.js'\n\nexport type { InvalidationDomain, LiveConnectionStatus } from './realtime.js'\n\n/** An oRPC client procedure fits: `client.order.watch`. */\nexport type SubscribeFn<TInput, TEvent> = (\n\tinput: TInput,\n\toptions: { signal: AbortSignal }\n) => Promise<AsyncIterable<TEvent>>\n\nexport type UseOrpcSubscriptionOptions<TInput, TEvent> = {\n\t/** Run the stream (default: true). */\n\tenabled?: boolean | undefined\n\tonEvent?: (\n\t\tevent: TEvent,\n\t\tmeta: { connectionId: number; input: TInput }\n\t) => void\n\t/** Every successful connect; `connectionId > 1` is a reconnect. */\n\tonConnect?: (connectionId: number) => void\n\tonError?: ((error: Error) => void) | undefined\n\tonClose?: () => void\n\t/**\n\t * Close the stream while the app is not focused (default: true). Focus is\n\t * TanStack's `focusManager`: on React Native, wire it to `AppState` once.\n\t */\n\tpauseWhenUnfocused?: boolean | undefined\n}\n\nconst subscribeFocus = (listener: () => void) =>\n\tfocusManager.subscribe(listener)\nconst getFocus = () => focusManager.isFocused()\n\n/** Whether the app is focused, from TanStack's `focusManager`. */\nfunction useIsFocused(): boolean {\n\treturn useSyncExternalStore(subscribeFocus, getFocus, getFocus)\n}\n\n/**\n * An oRPC event iterator with backoff reconnects that closes while the app is\n * backgrounded. A changed input (compared as JSON) reconnects with a fresh\n * retry budget.\n */\nexport function useOrpcSubscription<TInput, TEvent>(\n\tinput: TInput,\n\tsubscribe: SubscribeFn<TInput, TEvent>,\n\toptions: UseOrpcSubscriptionOptions<TInput, TEvent> = {}\n): { status: LiveConnectionStatus } {\n\tconst { enabled = true, pauseWhenUnfocused = true } = options\n\tconst focused = useIsFocused()\n\tconst shouldRun = enabled && (!pauseWhenUnfocused || focused)\n\tconst [status, setStatus] = useState<LiveConnectionStatus>('idle')\n\n\tconst latest = useRef({ input, subscribe, options, shouldRun })\n\tlatest.current = { input, subscribe, options, shouldRun }\n\n\tconst runnerRef = useRef<SubscriptionRunner | null>(null)\n\tif (!runnerRef.current) {\n\t\tlet openedInput = input\n\t\trunnerRef.current = createSubscriptionRunner<TEvent>({\n\t\t\topen: (signal) => {\n\t\t\t\topenedInput = latest.current.input\n\t\t\t\treturn latest.current.subscribe(openedInput, { signal })\n\t\t\t},\n\t\t\tcanConnect: () => latest.current.shouldRun,\n\t\t\tshouldReconnect: () => latest.current.shouldRun,\n\t\t\tonStatus: setStatus,\n\t\t\tonEvent: (event, connectionId) =>\n\t\t\t\tlatest.current.options.onEvent?.(event, {\n\t\t\t\t\tconnectionId,\n\t\t\t\t\tinput: openedInput\n\t\t\t\t}),\n\t\t\tonConnect: (id) => latest.current.options.onConnect?.(id),\n\t\t\tonError: (error) => latest.current.options.onError?.(error),\n\t\t\tonClose: () => latest.current.options.onClose?.()\n\t\t})\n\t}\n\tconst runner = runnerRef.current\n\tconst serializedInput = JSON.stringify(input)\n\n\t// biome-ignore lint/correctness/useExhaustiveDependencies: a changed input resubscribes\n\tuseEffect(() => {\n\t\tif (!shouldRun) return\n\t\tvoid runner.start()\n\t\treturn () => void runner.disconnect()\n\t}, [runner, shouldRun, serializedInput])\n\n\treturn { status }\n}\n\ntype ApplyEvent<TStreamEvent, TData> = (\n\tevent: TStreamEvent,\n\tprevious: TData | undefined\n) => TData | undefined\n\ntype LiveQueryOptions<\n\tTInput,\n\tTRouteData,\n\tTStreamEvent,\n\tTData,\n\tTSubscriptionInput\n> = {\n\t/** Run the query and its stream (default: true). */\n\tenabled?: boolean | undefined\n\t/** Input for the stream when it differs from the query's. */\n\tsubscriptionInput?: TSubscriptionInput | undefined\n\t/**\n\t * Convert the route output once at fetch time into a differently typed\n\t * cache; `applyEvent` then reduces stream events into that cache.\n\t */\n\tselect?: (data: TRouteData) => TData\n\t/** The raw route output of a seed, before `select` drops fields. */\n\tonSeed?: (data: TRouteData, input: TInput) => void\n\t/**\n\t * Fold a stream event into the cached data. Required when the stream sends\n\t * something other than the cached type (an `fnLive` patch route, or a\n\t * `select`ed cache). Return `undefined` to skip the write.\n\t */\n\tapplyEvent?: ApplyEvent<TStreamEvent, NoInfer<TData>>\n\tonEvent?: (event: TStreamEvent, meta: { connectionId: number }) => void\n\tonError?: ((error: Error) => void) | undefined\n\t/**\n\t * Reconcile a fetched seed with what the stream already wrote. The HTTP\n\t * request can resolve last, so a plain overwrite would drop events that\n\t * arrived while it was in flight. Default: take the fetched value.\n\t */\n\tmergeSeed?: (\n\t\tfetched: NoInfer<TData>,\n\t\tcached: NoInfer<TData> | undefined\n\t) => NoInfer<TData>\n\t/** Show the previous key's data while a new key loads (default: true). */\n\tkeepPreviousData?: boolean\n\t/** Close the stream while the app is not focused (default: true). */\n\tpauseWhenUnfocused?: boolean | undefined\n}\n\ntype LiveQueryOptionsFn<TInput, TData, TError> = (\n\tinput: TInput\n) => UseQueryOptions<TData, TError, TData, QueryKey>\n\ntype LiveQueryResult<TData, TError> = UseQueryResult<TData, TError> & {\n\tliveStatus: LiveConnectionStatus\n}\n\n/**\n * The client half of `fnLive`: the HTTP query seeds the cache, and the live\n * route's stream writes each snapshot into the same cache entry. Marked\n * `meta.live`, so invalidation streams leave it alone.\n *\n * ```tsx\n * const order = useLiveQuery({ id }, (input) => orpc.order.get.queryOptions({ input }), client.order.watch)\n * ```\n *\n * One signature, not overloads: TypeScript fixes an untyped callback's\n * parameters at the first overload it tries, which made valid calls fail.\n */\nexport function useLiveQuery<\n\tTInput,\n\tTRouteData,\n\tTStreamEvent,\n\tTData = TRouteData,\n\tTError = Error,\n\tTSubscriptionInput = TInput\n>(\n\tinput: TInput,\n\tqueryOptionsFn: LiveQueryOptionsFn<TInput, TRouteData, TError>,\n\tsubscribe: SubscribeFn<NoInfer<TSubscriptionInput>, TStreamEvent>,\n\t...options: [TStreamEvent] extends [TData]\n\t\t? [\n\t\t\t\toptions?: LiveQueryOptions<\n\t\t\t\t\tTInput,\n\t\t\t\t\tTRouteData,\n\t\t\t\t\tTStreamEvent,\n\t\t\t\t\tTData,\n\t\t\t\t\tTSubscriptionInput\n\t\t\t\t>\n\t\t\t]\n\t\t: [\n\t\t\t\toptions: LiveQueryOptions<\n\t\t\t\t\tTInput,\n\t\t\t\t\tTRouteData,\n\t\t\t\t\tTStreamEvent,\n\t\t\t\t\tTData,\n\t\t\t\t\tTSubscriptionInput\n\t\t\t\t> & { applyEvent: ApplyEvent<TStreamEvent, NoInfer<TData>> }\n\t\t\t]\n): LiveQueryResult<TData, TError>\nexport function useLiveQuery<\n\tTInput,\n\tTRouteData,\n\tTStreamEvent,\n\tTData,\n\tTError,\n\tTSubscriptionInput\n>(\n\tinput: TInput,\n\tqueryOptionsFn: LiveQueryOptionsFn<TInput, TRouteData, TError>,\n\tsubscribe: SubscribeFn<TSubscriptionInput, TStreamEvent>,\n\toptions: LiveQueryOptions<\n\t\tTInput,\n\t\tTRouteData,\n\t\tTStreamEvent,\n\t\tTData,\n\t\tTSubscriptionInput\n\t> = {}\n): LiveQueryResult<TData, TError> {\n\tconst queryClient = useQueryClient()\n\tconst focused = useIsFocused()\n\tconst [scope] = useState(createStreamScope)\n\n\t// oRPC query options are plain objects; `queryFn` is read through one shape.\n\tconst raw = queryOptionsFn(input) as unknown as {\n\t\tqueryKey: QueryKey\n\t\tqueryFn?: (context: unknown) => Promise<TRouteData>\n\t\tenabled?: UseQueryOptions['enabled']\n\t\tmeta?: Record<string, unknown>\n\t} & Record<string, unknown>\n\tconst keyHash = hashKey(raw.queryKey)\n\tconst latest = useRef({ raw, keyHash, options })\n\tlatest.current = { raw, keyHash, options }\n\n\tconst { status } = useOrpcSubscription(\n\t\t(options.subscriptionInput === undefined\n\t\t\t? input\n\t\t\t: options.subscriptionInput) as TSubscriptionInput,\n\t\tsubscribe,\n\t\t{\n\t\t\tenabled: options.enabled,\n\t\t\tpauseWhenUnfocused: options.pauseWhenUnfocused,\n\t\t\tonError: options.onError,\n\t\t\tonConnect: (connectionId) =>\n\t\t\t\tscope.open(connectionId, latest.current.keyHash),\n\t\t\tonEvent: (event, { connectionId }) => {\n\t\t\t\tconst current = latest.current\n\t\t\t\t// The consumer callback must not see an event for a scope no longer shown.\n\t\t\t\tif (!scope.owns(connectionId, current.keyHash)) return\n\t\t\t\t// Without `applyEvent` the stream event is the cache type (the first overload).\n\t\t\t\tconst applyEvent =\n\t\t\t\t\tcurrent.options.applyEvent ??\n\t\t\t\t\t((streamEvent: TStreamEvent) => streamEvent as unknown as TData)\n\t\t\t\tconst key = current.raw.queryKey\n\t\t\t\tconst next = applyEvent(event, queryClient.getQueryData<TData>(key))\n\t\t\t\tif (next !== undefined) queryClient.setQueryData(key, next)\n\t\t\t\tcurrent.options.onEvent?.(event, { connectionId })\n\t\t\t}\n\t\t}\n\t)\n\n\tconst wrapsSeed = options.select || options.mergeSeed\n\tconst queryFn =\n\t\traw.queryFn && wrapsSeed\n\t\t\t? seedQueryFn(raw.queryFn, {\n\t\t\t\t\tinput,\n\t\t\t\t\treadCache: () => queryClient.getQueryData<TData>(raw.queryKey),\n\t\t\t\t\tselect: options.select,\n\t\t\t\t\tonSeed: options.onSeed,\n\t\t\t\t\tmergeSeed: options.mergeSeed\n\t\t\t\t})\n\t\t\t: raw.queryFn\n\tconst runs = options.enabled !== false && focused\n\tconst query = useQuery({\n\t\t...raw,\n\t\t...(queryFn ? { queryFn } : {}),\n\t\tenabled: runs ? (raw.enabled ?? true) : false,\n\t\t...(options.keepPreviousData === false\n\t\t\t? {}\n\t\t\t: { placeholderData: keepPreviousData }),\n\t\tstaleTime: Number.POSITIVE_INFINITY,\n\t\tmeta: { ...raw.meta, live: true }\n\t} as UseQueryOptions<TData, TError, TData, QueryKey>)\n\n\treturn Object.assign(query, { liveStatus: status })\n}\n\n/**\n * One app-wide stream of `{ domain }` change events that keeps list and count\n * queries fresh: each event invalidates its domain's query keys (debounced),\n * and a reconnect that proves healthy invalidates every domain to cover\n * events lost while it was down. Mount once, in the signed-in shell.\n *\n * ```ts\n * useInvalidationStream({}, client.realtime.subscribeChanges, {\n *   enabled: signedIn,\n *   domains: { order: { debounceMs: 100, queryKeys: [orpc.order.key()] } }\n * })\n * ```\n */\nexport function useInvalidationStream<\n\tTInput,\n\tTEvent extends { domain: string }\n>(\n\tinput: TInput,\n\tsubscribe: SubscribeFn<TInput, TEvent>,\n\toptions: InvalidationStreamOptions<TEvent> &\n\t\tPick<\n\t\t\tUseOrpcSubscriptionOptions<TInput, TEvent>,\n\t\t\t'enabled' | 'pauseWhenUnfocused'\n\t\t>\n): { status: LiveConnectionStatus } {\n\tconst queryClient = useQueryClient()\n\tconst latestOptions = useRef(options)\n\tlatestOptions.current = options\n\t// `domains`, `refetchType` and `logger` are read on mount; `onEvent` stays current.\n\tconst [coordinator] = useState(() =>\n\t\tcreateInvalidationCoordinator<TEvent>(queryClient, {\n\t\t\t...options,\n\t\t\tonEvent: (event) => latestOptions.current.onEvent?.(event)\n\t\t})\n\t)\n\tuseEffect(() => coordinator.dispose, [coordinator])\n\n\treturn useOrpcSubscription<TInput, TEvent>(input, subscribe, {\n\t\tenabled: options.enabled,\n\t\tpauseWhenUnfocused: options.pauseWhenUnfocused,\n\t\tonEvent: coordinator.event,\n\t\tonConnect: coordinator.connect,\n\t\tonError: coordinator.lost,\n\t\tonClose: coordinator.lost\n\t})\n}\n\n/**\n * Clear the query cache when the signed-in owner of the cached data changes\n * (another user, another organization), so the next one never sees it.\n * `null` means signed out: signing in starts from the cache sign-out emptied.\n * Pass the same owner as the persister's `buster` so a saved cache from\n * someone else is discarded on the next launch too.\n */\nexport function useQueryCacheOwner(owner: string | null): void {\n\tconst queryClient = useQueryClient()\n\tconst previous = useRef(owner)\n\tuseEffect(() => {\n\t\tconst before = previous.current\n\t\tprevious.current = owner\n\t\tif (owner !== before && before !== null) queryClient.clear()\n\t}, [owner, queryClient])\n}\n"]}

package/dist/realtime.d.ts

@@ -0,0 +1,114 @@
+import type { FnLogger } from './logger.js';
+export type LiveConnectionStatus = 'idle' | 'connecting' | 'connected' | 'error' | 'closed';
+/**
+ * Backoff for attempt N (1-based): exponential from 1s capped at 15s, plus
+ * 0-25% jitter so a fleet of clients doesn't thundering-herd a recovering
+ * server. The delay is capped, never the attempts: a dead network keeps
+ * retrying at the ceiling instead of killing the stream for good.
+ */
+export declare function nextReconnectDelayMs(errorCount: number, random?: () => number): number;
+type SubscriptionRunnerOptions<TEvent> = {
+    open: (signal: AbortSignal) => Promise<AsyncIterable<TEvent>>;
+    onEvent: (event: TEvent, connectionId: number) => void;
+    onStatus: (status: LiveConnectionStatus) => void;
+    onConnect?: ((connectionId: number) => void) | undefined;
+    onError?: ((error: Error) => void) | undefined;
+    onClose?: (() => void) | undefined;
+    /** May a stream run at all right now (e.g. the app is in the foreground)? */
+    canConnect: () => boolean;
+    /** Reconnect with backoff after an unexpected end? Checked when scheduling and firing. */
+    shouldReconnect: () => boolean;
+};
+export type SubscriptionRunner = ReturnType<typeof createSubscriptionRunner>;
+/**
+ * One oRPC event-iterator stream with generation-guarded connects, abortable
+ * teardown and backoff reconnects. Every connect claims a new connection id;
+ * a superseded attempt closes its own iterator and never reports events.
+ */
+export declare function createSubscriptionRunner<TEvent>(options: SubscriptionRunnerOptions<TEvent>): {
+    connect: () => Promise<void>;
+    disconnect: () => Promise<void>;
+    /** Connect with a fresh retry budget (input change, foreground, re-enable). */
+    start(): Promise<void>;
+    /** Connected, connecting, or waiting to reconnect. */
+    isLive: () => boolean;
+    getStatus: () => LiveConnectionStatus;
+    dispose(): Promise<void>;
+};
+type QueryKeyLike = readonly unknown[];
+/** The part of a TanStack `QueryClient` the coordinator uses. */
+type InvalidatingQueryClient = {
+    invalidateQueries(filters: {
+        queryKey: QueryKeyLike;
+        refetchType?: 'active' | 'inactive' | 'all' | 'none';
+        predicate?: (query: {
+            meta?: Record<string, unknown> | undefined;
+        }) => boolean;
+    }): Promise<unknown>;
+};
+export type InvalidationDomain = {
+    /**
+     * Batch a burst of events into one invalidation (ms). The window runs from
+     * the first event, so a steady stream cannot postpone the refresh forever.
+     */
+    debounceMs?: number;
+    queryKeys: readonly QueryKeyLike[];
+};
+export type InvalidationStreamOptions<TEvent extends {
+    domain: string;
+}> = {
+    /** Query keys to invalidate per event `domain`. Unmapped domains are ignored. */
+    domains: {
+        [K in TEvent['domain']]?: InvalidationDomain;
+    };
+    /**
+     * Passed to `invalidateQueries`. Default: TanStack's `'active'`, which marks
+     * inactive queries stale so they refetch on their next use. `'all'` also
+     * refetches every cached query of the domain now, on each event.
+     */
+    refetchType?: 'active' | 'inactive' | 'all' | 'none';
+    /** Every event, after its domain is invalidated (alerts, chimes). */
+    onEvent?: (event: TEvent) => void;
+    /** Receives one `invalidation_stream.disconnected` warning per minute at most. */
+    logger?: Pick<FnLogger, 'warn'>;
+};
+/**
+ * Turns a stream of `{ domain }` change events into debounced
+ * `invalidateQueries` calls. Live queries (`meta.live`) are skipped: their own
+ * stream keeps them current. Events published while the stream was down are
+ * lost, so a reconnect that proves healthy invalidates every mapped domain.
+ */
+export declare function createInvalidationCoordinator<TEvent extends {
+    domain: string;
+}>(queryClient: InvalidatingQueryClient, options: InvalidationStreamOptions<TEvent>): {
+    event(event: TEvent): void;
+    connect(connectionId: number): void;
+    lost(): void;
+    dispose(): void;
+};
+/**
+ * Which connection and query key the open live stream belongs to. An event
+ * counts only while both still match: the input changes synchronously but the
+ * stream is torn down asynchronously, so a frame in flight from the previous
+ * subscription would otherwise land in the new key (and, with
+ * `staleTime: Infinity`, stay there).
+ */
+export declare function createStreamScope(): {
+    open(connectionId: number, keyHash: string): void;
+    owns: (connectionId: number, keyHash: string) => boolean;
+};
+/**
+ * Wrap a live query's HTTP `queryFn`: report the raw seed, convert it with
+ * `select`, and reconcile it with what the stream already wrote. The cache is
+ * read after the request resolves, because stream events can arrive while it
+ * is in flight.
+ */
+export declare function seedQueryFn<TRouteData, TData, TInput>(queryFn: (context: unknown) => Promise<TRouteData>, options: {
+    input: TInput;
+    readCache: () => TData | undefined;
+    select?: ((data: TRouteData) => TData) | undefined;
+    onSeed?: ((data: TRouteData, input: TInput) => void) | undefined;
+    mergeSeed?: ((fetched: TData, cached: TData | undefined) => TData) | undefined;
+}): (context: unknown) => Promise<TData>;
+export {};
+//# sourceMappingURL=realtime.d.ts.map

package/dist/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"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"}

package/dist/realtime.js

@@ -0,0 +1,316 @@
+const BASE_RECONNECT_DELAY_MS = 1000;
+const MAX_RECONNECT_DELAY_MS = 15_000;
+/**
+ * Backoff for attempt N (1-based): exponential from 1s capped at 15s, plus
+ * 0-25% jitter so a fleet of clients doesn't thundering-herd a recovering
+ * server. The delay is capped, never the attempts: a dead network keeps
+ * retrying at the ceiling instead of killing the stream for good.
+ */
+export function nextReconnectDelayMs(errorCount, random = Math.random) {
+    const attempt = Math.max(1, errorCount);
+    const base = Math.min(BASE_RECONNECT_DELAY_MS * 2 ** (attempt - 1), MAX_RECONNECT_DELAY_MS);
+    return Math.round(base + base * 0.25 * random());
+}
+/**
+ * One oRPC event-iterator stream with generation-guarded connects, abortable
+ * teardown and backoff reconnects. Every connect claims a new connection id;
+ * a superseded attempt closes its own iterator and never reports events.
+ */
+export function createSubscriptionRunner(options) {
+    let status = 'idle';
+    let abortController = null;
+    let iterator = null;
+    let connectPromise = null;
+    let activeConnectionId = 0;
+    /** Set by deliberate teardown so stream-end does not schedule a retry. */
+    let intentionalDisconnect = false;
+    let errorCount = 0;
+    let reconnectTimer = null;
+    let disposed = false;
+    const setStatus = (next) => {
+        status = next;
+        options.onStatus(next);
+    };
+    function clearReconnectTimer() {
+        if (reconnectTimer === null)
+            return;
+        clearTimeout(reconnectTimer);
+        reconnectTimer = null;
+    }
+    function scheduleReconnect() {
+        if (intentionalDisconnect || disposed || reconnectTimer !== null)
+            return;
+        if (!options.shouldReconnect())
+            return;
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = null;
+            if (disposed || intentionalDisconnect || !options.shouldReconnect())
+                return;
+            void connect();
+        }, nextReconnectDelayMs(errorCount));
+    }
+    function handleUnexpectedEnd(error) {
+        errorCount += 1;
+        // Close the socket of a failed stream; on React Native an unaborted
+        // expo/fetch request keeps holding a connection from the device's pool.
+        abortController?.abort();
+        abortController = null;
+        iterator = null;
+        if (error) {
+            setStatus('error');
+            options.onError?.(error);
+        }
+        else {
+            setStatus('closed');
+            options.onClose?.();
+        }
+        scheduleReconnect();
+    }
+    async function connect() {
+        if (disposed || !options.canConnect())
+            return;
+        if (connectPromise)
+            return connectPromise;
+        if (status === 'connected' || reconnectTimer !== null)
+            return;
+        intentionalDisconnect = false;
+        const thisConnect = (async () => {
+            setStatus('connecting');
+            // Claim the generation and controller before awaiting, so a
+            // disconnect while opening supersedes this attempt.
+            const controller = new AbortController();
+            abortController = controller;
+            const connectionId = ++activeConnectionId;
+            try {
+                const iterable = await options.open(controller.signal);
+                const localIterator = iterable[Symbol.asyncIterator]();
+                if (connectionId !== activeConnectionId || controller.signal.aborted) {
+                    await closeIterator(localIterator);
+                    return;
+                }
+                iterator = localIterator;
+                setStatus('connected');
+                options.onConnect?.(connectionId);
+                void consume(localIterator, connectionId);
+            }
+            catch (error) {
+                if (connectionId !== activeConnectionId || controller.signal.aborted)
+                    return;
+                handleUnexpectedEnd(toError(error));
+            }
+        })();
+        connectPromise = thisConnect;
+        try {
+            await thisConnect;
+        }
+        finally {
+            if (connectPromise === thisConnect)
+                connectPromise = null;
+        }
+    }
+    async function consume(localIterator, connectionId) {
+        try {
+            while (status === 'connected' && connectionId === activeConnectionId) {
+                const result = await localIterator.next();
+                if (status !== 'connected' || connectionId !== activeConnectionId)
+                    return;
+                if (result.done) {
+                    // Proxy or idle end after a live connect: recoverable.
+                    if (!intentionalDisconnect)
+                        handleUnexpectedEnd(null);
+                    return;
+                }
+                // Reset backoff only once the stream delivers. A server that accepts
+                // and then dies before yielding must keep escalating.
+                errorCount = 0;
+                options.onEvent(result.value, connectionId);
+            }
+        }
+        catch (error) {
+            if (connectionId !== activeConnectionId)
+                return;
+            if (abortController?.signal.aborted || intentionalDisconnect) {
+                setStatus('closed');
+                options.onClose?.();
+                return;
+            }
+            handleUnexpectedEnd(toError(error));
+        }
+    }
+    async function disconnect() {
+        intentionalDisconnect = true;
+        clearReconnectTimer();
+        if (status === 'idle')
+            return;
+        activeConnectionId++;
+        abortController?.abort();
+        // A fresh connect() may start while the superseded attempt winds down.
+        connectPromise = null;
+        const localIterator = iterator;
+        iterator = null;
+        abortController = null;
+        if (status !== 'closed') {
+            setStatus('closed');
+            options.onClose?.();
+        }
+        await closeIterator(localIterator);
+    }
+    return {
+        connect,
+        disconnect,
+        /** Connect with a fresh retry budget (input change, foreground, re-enable). */
+        start() {
+            errorCount = 0;
+            intentionalDisconnect = false;
+            return connect();
+        },
+        /** Connected, connecting, or waiting to reconnect. */
+        isLive: () => status === 'connected' ||
+            status === 'connecting' ||
+            reconnectTimer !== null,
+        getStatus: () => status,
+        dispose() {
+            disposed = true;
+            return disconnect();
+        }
+    };
+}
+async function closeIterator(iterator) {
+    try {
+        await iterator?.return?.(undefined);
+    }
+    catch {
+        // Cleanup errors are not the caller's concern.
+    }
+}
+const toError = (error) => error instanceof Error ? error : new Error(String(error));
+/**
+ * How long a reconnected stream must stay up, having delivered nothing, before
+ * it counts as working. Waiting for an event alone would leave a quiet
+ * reconnect stale until the next change; not waiting at all lets a stream that
+ * dies the instant it opens refetch everything once per retry.
+ */
+const SETTLE_MS = 1_500;
+const DISCONNECT_LOG_INTERVAL_MS = 60_000;
+/**
+ * Turns a stream of `{ domain }` change events into debounced
+ * `invalidateQueries` calls. Live queries (`meta.live`) are skipped: their own
+ * stream keeps them current. Events published while the stream was down are
+ * lost, so a reconnect that proves healthy invalidates every mapped domain.
+ */
+export function createInvalidationCoordinator(queryClient, options) {
+    const timers = new Map();
+    let settleTimer = null;
+    let catchUpPending = false;
+    let lastLostLogAt = Number.NEGATIVE_INFINITY;
+    const domainConfig = (domain) => Object.hasOwn(options.domains, domain)
+        ? options.domains[domain]
+        : undefined;
+    function invalidate(config) {
+        for (const queryKey of config.queryKeys) {
+            void queryClient.invalidateQueries({
+                queryKey,
+                ...(options.refetchType ? { refetchType: options.refetchType } : {}),
+                predicate: (query) => query.meta?.live !== true
+            });
+        }
+    }
+    function invalidateAll() {
+        for (const config of Object.values(options.domains)) {
+            if (config)
+                invalidate(config);
+        }
+    }
+    function clearSettleTimer() {
+        if (settleTimer === null)
+            return;
+        clearTimeout(settleTimer);
+        settleTimer = null;
+    }
+    function markHealthy() {
+        clearSettleTimer();
+        if (!catchUpPending)
+            return;
+        catchUpPending = false;
+        invalidateAll();
+    }
+    return {
+        event(event) {
+            // A delivered event proves the connection; no need to wait it out.
+            markHealthy();
+            // The stream is typed, but a JavaScript caller or a newer server may send anything.
+            const domain = event?.domain;
+            if (typeof domain !== 'string')
+                return;
+            const config = domainConfig(domain);
+            const delay = config?.debounceMs ?? 0;
+            if (config && delay <= 0) {
+                invalidate(config);
+            }
+            else if (config && !timers.has(domain)) {
+                const timer = setTimeout(() => {
+                    timers.delete(domain);
+                    invalidate(config);
+                }, delay);
+                timers.set(domain, timer);
+            }
+            options.onEvent?.(event);
+        },
+        connect(connectionId) {
+            clearSettleTimer();
+            catchUpPending ||= connectionId > 1;
+            settleTimer = setTimeout(markHealthy, SETTLE_MS);
+        },
+        lost() {
+            // Reconnecting is the subscription's job; this connection can no longer settle.
+            clearSettleTimer();
+            const now = Date.now();
+            if (now - lastLostLogAt < DISCONNECT_LOG_INTERVAL_MS)
+                return;
+            lastLostLogAt = now;
+            options.logger?.warn('invalidation_stream.disconnected');
+        },
+        dispose() {
+            clearSettleTimer();
+            for (const timer of timers.values())
+                clearTimeout(timer);
+            timers.clear();
+            catchUpPending = false;
+        }
+    };
+}
+/**
+ * Which connection and query key the open live stream belongs to. An event
+ * counts only while both still match: the input changes synchronously but the
+ * stream is torn down asynchronously, so a frame in flight from the previous
+ * subscription would otherwise land in the new key (and, with
+ * `staleTime: Infinity`, stay there).
+ */
+export function createStreamScope() {
+    let openConnectionId = null;
+    let openKeyHash = null;
+    return {
+        open(connectionId, keyHash) {
+            openConnectionId = connectionId;
+            openKeyHash = keyHash;
+        },
+        owns: (connectionId, keyHash) => connectionId === openConnectionId && keyHash === openKeyHash
+    };
+}
+/**
+ * Wrap a live query's HTTP `queryFn`: report the raw seed, convert it with
+ * `select`, and reconcile it with what the stream already wrote. The cache is
+ * read after the request resolves, because stream events can arrive while it
+ * is in flight.
+ */
+export function seedQueryFn(queryFn, options) {
+    const { select, onSeed, mergeSeed } = options;
+    return async (context) => {
+        const fetched = await queryFn(context);
+        onSeed?.(fetched, options.input);
+        // Without `select` the route output is the cache type.
+        const data = select ? select(fetched) : fetched;
+        return mergeSeed ? mergeSeed(data, options.readCache()) : data;
+    };
+}
+//# sourceMappingURL=realtime.js.map