orpc-fn 0.3.0 → 0.5.0

package/dist/react.d.ts

@@ -0,0 +1,116 @@
+import { type QueryKey, type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query';
+import { type InvalidationStreamOptions, type LiveConnectionStatus } from './realtime.js';
+export type { InvalidationDomain, LiveConnectionStatus } from './realtime.js';
+/** An oRPC client procedure fits: `client.order.watch`. */
+export type SubscribeFn<TInput, TEvent> = (input: TInput, options: {
+    signal: AbortSignal;
+}) => Promise<AsyncIterable<TEvent>>;
+export type UseOrpcSubscriptionOptions<TInput, TEvent> = {
+    /** Run the stream (default: true). */
+    enabled?: boolean | undefined;
+    onEvent?: (event: TEvent, meta: {
+        connectionId: number;
+        input: TInput;
+    }) => void;
+    /** Every successful connect; `connectionId > 1` is a reconnect. */
+    onConnect?: (connectionId: number) => void;
+    onError?: ((error: Error) => void) | undefined;
+    onClose?: () => void;
+    /**
+     * Close the stream while the app is not focused (default: true). Focus is
+     * TanStack's `focusManager`: on React Native, wire it to `AppState` once.
+     */
+    pauseWhenUnfocused?: boolean | undefined;
+};
+/**
+ * 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 declare function useOrpcSubscription<TInput, TEvent>(input: TInput, subscribe: SubscribeFn<TInput, TEvent>, options?: UseOrpcSubscriptionOptions<TInput, TEvent>): {
+    status: LiveConnectionStatus;
+};
+type ApplyEvent<TStreamEvent, TData> = (event: TStreamEvent, previous: TData | undefined) => TData | undefined;
+type LiveQueryOptions<TInput, TRouteData, TStreamEvent, TData, TSubscriptionInput> = {
+    /** Run the query and its stream (default: true). */
+    enabled?: boolean | undefined;
+    /** Input for the stream when it differs from the query's. */
+    subscriptionInput?: TSubscriptionInput | undefined;
+    /**
+     * Convert the route output once at fetch time into a differently typed
+     * cache; `applyEvent` then reduces stream events into that cache.
+     */
+    select?: (data: TRouteData) => TData;
+    /** The raw route output of a seed, before `select` drops fields. */
+    onSeed?: (data: TRouteData, input: TInput) => void;
+    /**
+     * Fold a stream event into the cached data. Required when the stream sends
+     * something other than the cached type (an `fnLive` patch route, or a
+     * `select`ed cache). Return `undefined` to skip the write.
+     */
+    applyEvent?: ApplyEvent<TStreamEvent, NoInfer<TData>>;
+    onEvent?: (event: TStreamEvent, meta: {
+        connectionId: number;
+    }) => void;
+    onError?: ((error: Error) => void) | undefined;
+    /**
+     * Reconcile a fetched seed with what the stream already wrote. The HTTP
+     * request can resolve last, so a plain overwrite would drop events that
+     * arrived while it was in flight. Default: take the fetched value.
+     */
+    mergeSeed?: (fetched: NoInfer<TData>, cached: NoInfer<TData> | undefined) => NoInfer<TData>;
+    /** Show the previous key's data while a new key loads (default: true). */
+    keepPreviousData?: boolean;
+    /** Close the stream while the app is not focused (default: true). */
+    pauseWhenUnfocused?: boolean | undefined;
+};
+type LiveQueryOptionsFn<TInput, TData, TError> = (input: TInput) => UseQueryOptions<TData, TError, TData, QueryKey>;
+type LiveQueryResult<TData, TError> = UseQueryResult<TData, TError> & {
+    liveStatus: LiveConnectionStatus;
+};
+/**
+ * The client half of `fnLive`: the HTTP query seeds the cache, and the live
+ * route's stream writes each snapshot into the same cache entry. Marked
+ * `meta.live`, so invalidation streams leave it alone.
+ *
+ * ```tsx
+ * const order = useLiveQuery({ id }, (input) => orpc.order.get.queryOptions({ input }), client.order.watch)
+ * ```
+ *
+ * One signature, not overloads: TypeScript fixes an untyped callback's
+ * parameters at the first overload it tries, which made valid calls fail.
+ */
+export declare function useLiveQuery<TInput, TRouteData, TStreamEvent, TData = TRouteData, TError = Error, TSubscriptionInput = TInput>(input: TInput, queryOptionsFn: LiveQueryOptionsFn<TInput, TRouteData, TError>, subscribe: SubscribeFn<NoInfer<TSubscriptionInput>, TStreamEvent>, ...options: [TStreamEvent] extends [TData] ? [
+    options?: LiveQueryOptions<TInput, TRouteData, TStreamEvent, TData, TSubscriptionInput>
+] : [
+    options: LiveQueryOptions<TInput, TRouteData, TStreamEvent, TData, TSubscriptionInput> & {
+        applyEvent: ApplyEvent<TStreamEvent, NoInfer<TData>>;
+    }
+]): LiveQueryResult<TData, TError>;
+/**
+ * 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 declare function useInvalidationStream<TInput, TEvent extends {
+    domain: string;
+}>(input: TInput, subscribe: SubscribeFn<TInput, TEvent>, options: InvalidationStreamOptions<TEvent> & Pick<UseOrpcSubscriptionOptions<TInput, TEvent>, 'enabled' | 'pauseWhenUnfocused'>): {
+    status: LiveConnectionStatus;
+};
+/**
+ * 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 declare function useQueryCacheOwner(owner: string | null): void;
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

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

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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"}