@trpc/tanstack-react-query 11.6.1-canary.5 → 11.7.0

package/src/internals/subscriptionOptions.ts

@@ -6,11 +6,13 @@ import type { Unsubscribable } from '@trpc/server/observable';
 import type { inferAsyncIterableYield } from '@trpc/server/unstable-core-do-not-import';
 import * as React from 'react';
 import type {
+  DefaultFeatureFlags,
+  FeatureFlags,
   ResolverDef,
   TRPCQueryKey,
   TRPCQueryOptionsResult,
 } from './types';
-import { createTRPCOptionsResult } from './utils';
+import { createTRPCOptionsResult, readQueryKey } from './utils';
 
 interface BaseTRPCSubscriptionOptionsIn<TOutput, TError> {
   enabled?: boolean;
@@ -27,17 +29,23 @@ interface UnusedSkipTokenTRPCSubscriptionOptionsIn<TOutput, TError> {
   onConnectionStateChange?: (state: TRPCConnectionState<TError>) => void;
 }
 
-interface TRPCSubscriptionOptionsOut<TOutput, TError>
-  extends UnusedSkipTokenTRPCSubscriptionOptionsIn<TOutput, TError>,
+interface TRPCSubscriptionOptionsOut<
+  TOutput,
+  TError,
+  TFeatureFlags extends FeatureFlags,
+> extends UnusedSkipTokenTRPCSubscriptionOptionsIn<TOutput, TError>,
     TRPCQueryOptionsResult {
   enabled: boolean;
-  queryKey: TRPCQueryKey;
+  queryKey: TRPCQueryKey<TFeatureFlags['keyPrefix']>;
   subscribe: (
     innerOpts: UnusedSkipTokenTRPCSubscriptionOptionsIn<TOutput, TError>,
   ) => Unsubscribable;
 }
 
-export interface TRPCSubscriptionOptions<TDef extends ResolverDef> {
+export interface TRPCSubscriptionOptions<
+  TDef extends ResolverDef,
+  TFeatureFlags extends FeatureFlags = DefaultFeatureFlags,
+> {
   (
     input: TDef['input'],
     opts?: UnusedSkipTokenTRPCSubscriptionOptionsIn<
@@ -46,7 +54,8 @@ export interface TRPCSubscriptionOptions<TDef extends ResolverDef> {
     >,
   ): TRPCSubscriptionOptionsOut<
     inferAsyncIterableYield<TDef['output']>,
-    TRPCClientErrorLike<TDef>
+    TRPCClientErrorLike<TDef>,
+    TFeatureFlags
   >;
   (
     input: TDef['input'] | SkipToken,
@@ -56,7 +65,8 @@ export interface TRPCSubscriptionOptions<TDef extends ResolverDef> {
     >,
   ): TRPCSubscriptionOptionsOut<
     inferAsyncIterableYield<TDef['output']>,
-    TRPCClientErrorLike<TDef>
+    TRPCClientErrorLike<TDef>,
+    TFeatureFlags
   >;
 }
 export type TRPCSubscriptionStatus =
@@ -113,27 +123,27 @@ type AnyTRPCSubscriptionOptionsIn =
   | BaseTRPCSubscriptionOptionsIn<unknown, unknown>
   | UnusedSkipTokenTRPCSubscriptionOptionsIn<unknown, unknown>;
 
-type AnyTRPCSubscriptionOptionsOut = TRPCSubscriptionOptionsOut<
-  unknown,
-  unknown
->;
+type AnyTRPCSubscriptionOptionsOut<TFeatureFlags extends FeatureFlags> =
+  TRPCSubscriptionOptionsOut<unknown, unknown, TFeatureFlags>;
 
 /**
  * @internal
  */
-export const trpcSubscriptionOptions = (args: {
+export const trpcSubscriptionOptions = <
+  TFeatureFlags extends FeatureFlags,
+>(args: {
   subscribe: typeof TRPCUntypedClient.prototype.subscription;
-  path: readonly string[];
-  queryKey: TRPCQueryKey;
+  path: string[];
+  queryKey: TRPCQueryKey<TFeatureFlags['keyPrefix']>;
   opts?: AnyTRPCSubscriptionOptionsIn;
-}): AnyTRPCSubscriptionOptionsOut => {
+}): AnyTRPCSubscriptionOptionsOut<TFeatureFlags> => {
   const { subscribe, path, queryKey, opts = {} } = args;
-  const input = queryKey[1]?.input;
+  const input = readQueryKey(queryKey)?.args?.input;
   const enabled = 'enabled' in opts ? !!opts.enabled : input !== skipToken;
 
-  const _subscribe: ReturnType<TRPCSubscriptionOptions<any>>['subscribe'] = (
-    innerOpts,
-  ) => {
+  const _subscribe: ReturnType<
+    TRPCSubscriptionOptions<any, TFeatureFlags>
+  >['subscribe'] = (innerOpts) => {
     return subscribe(path.join('.'), input ?? undefined, innerOpts);
   };
 
@@ -147,7 +157,7 @@ export const trpcSubscriptionOptions = (args: {
 };
 
 export function useSubscription<TOutput, TError>(
-  opts: TRPCSubscriptionOptionsOut<TOutput, TError>,
+  opts: TRPCSubscriptionOptionsOut<TOutput, TError, any>,
 ): TRPCSubscriptionResult<TOutput, TError> {
   type $Result = TRPCSubscriptionResult<TOutput, TError>;
 

package/src/internals/types.ts

@@ -17,6 +17,7 @@ export type ResolverDef = {
   output: any;
   transformer: boolean;
   errorShape: any;
+  featureFlags: FeatureFlags;
 };
 
 /**
@@ -83,12 +84,82 @@ export type QueryType = 'any' | 'infinite' | 'query';
 /**
  * @public
  */
-export type TRPCQueryKey = [
-  readonly string[],
-  { input?: unknown; type?: Exclude<QueryType, 'any'> }?,
+export type TRPCQueryKeyWithoutPrefix = [
+  path: string[],
+  opts?: { input?: unknown; type?: Exclude<QueryType, 'any'> },
 ];
 
 /**
  * @public
  */
-export type TRPCMutationKey = [readonly string[]]; // = [TRPCQueryKey[0]]
+export type TRPCQueryKeyWithPrefix = [
+  prefix: string[],
+  ...TRPCQueryKeyWithoutPrefix,
+];
+
+export type TRPCQueryKey<TPrefixEnabled extends boolean = false> =
+  TPrefixEnabled extends true
+    ? TRPCQueryKeyWithPrefix
+    : TRPCQueryKeyWithoutPrefix;
+
+export type AnyTRPCQueryKey =
+  | TRPCQueryKeyWithoutPrefix
+  | TRPCQueryKeyWithPrefix;
+
+/**
+ * @public
+ */
+export type TRPCMutationKeyWithPrefix = [
+  prefix: string[],
+  ...TRPCMutationKeyWithoutPrefix,
+];
+
+/**
+ * @public
+ */
+export type TRPCMutationKeyWithoutPrefix = [path: string[]];
+
+export type AnyTRPCMutationKey =
+  | TRPCMutationKeyWithoutPrefix
+  | TRPCMutationKeyWithPrefix;
+
+/**
+ * @public
+ */
+export type TRPCMutationKey<TPrefixEnabled extends boolean = false> =
+  TPrefixEnabled extends true
+    ? TRPCMutationKeyWithPrefix
+    : TRPCMutationKeyWithoutPrefix;
+
+/**
+ * Feature flags for configuring tRPC behavior
+ * @public
+ */
+export type FeatureFlags = { keyPrefix: boolean };
+
+/**
+ * @internal
+ */
+export type ofFeatureFlags<T extends FeatureFlags> = T;
+
+/**
+ * @internal
+ */
+export type KeyPrefixOptions<TFeatureFlags extends FeatureFlags> =
+  TFeatureFlags['keyPrefix'] extends true
+    ? {
+        keyPrefix: string;
+      }
+    : {
+        /**
+         * In order to use a query key prefix, you have to initialize the context with the `keyPrefix`
+         */
+        keyPrefix?: never;
+      };
+/**
+ * Default feature flags with query key prefix disabled
+ * @public
+ */
+export type DefaultFeatureFlags = ofFeatureFlags<{
+  keyPrefix: false;
+}>;

package/src/internals/utils.ts

@@ -1,9 +1,18 @@
 import { skipToken, type QueryClient } from '@tanstack/react-query';
-import { isFunction, isObject } from '@trpc/server/unstable-core-do-not-import';
+import {
+  isFunction,
+  isObject,
+  run,
+} from '@trpc/server/unstable-core-do-not-import';
 import type {
+  AnyTRPCMutationKey,
+  AnyTRPCQueryKey,
+  FeatureFlags,
   QueryType,
-  TRPCMutationKey,
+  TRPCMutationKeyWithoutPrefix,
   TRPCQueryKey,
+  TRPCQueryKeyWithoutPrefix,
+  TRPCQueryKeyWithPrefix,
   TRPCQueryOptionsResult,
 } from './types';
 
@@ -11,7 +20,7 @@ import type {
  * @internal
  */
 export function createTRPCOptionsResult(value: {
-  path: readonly string[];
+  path: string[];
 }): TRPCQueryOptionsResult['trpc'] {
   const path = value.path.join('.');
 
@@ -20,38 +29,65 @@ export function createTRPCOptionsResult(value: {
   };
 }
 
+export function isPrefixedQueryKey(
+  queryKey: TRPCQueryKey<any>,
+): queryKey is TRPCQueryKeyWithPrefix {
+  return queryKey.length >= 3;
+}
+
+export function readQueryKey(queryKey: AnyTRPCQueryKey) {
+  if (isPrefixedQueryKey(queryKey)) {
+    return {
+      type: 'prefixed' as const,
+      prefix: queryKey[0],
+      path: queryKey[1],
+      args: queryKey[2],
+    };
+  } else {
+    return {
+      type: 'unprefixed' as const,
+      prefix: undefined,
+      path: queryKey[0],
+      args: queryKey[1],
+    };
+  }
+}
+
 /**
  * @internal
  */
-export function getClientArgs<TOptions>(
-  queryKey: TRPCQueryKey,
+export function getClientArgs<TOptions, TFeatureFlags extends FeatureFlags>(
+  queryKey: TRPCQueryKey<TFeatureFlags['keyPrefix']>,
   opts: TOptions,
   infiniteParams?: {
     pageParam: any;
     direction: 'forward' | 'backward';
   },
 ) {
-  const path = queryKey[0];
-  let input = queryKey[1]?.input;
+  const queryKeyData = readQueryKey(queryKey);
+
+  let input = queryKeyData.args?.input;
   if (infiniteParams) {
     input = {
-      ...(input ?? {}),
+      ...(queryKeyData.args?.input ?? {}),
       ...(infiniteParams.pageParam !== undefined
         ? { cursor: infiniteParams.pageParam }
         : {}),
       direction: infiniteParams.direction,
     };
   }
-  return [path.join('.'), input, (opts as any)?.trpc] as const;
+  return [queryKeyData.path.join('.'), input, (opts as any)?.trpc] as const;
 }
 
 /**
  * @internal
  */
-export async function buildQueryFromAsyncIterable(
+export async function buildQueryFromAsyncIterable<
+  TQueryKey extends TRPCQueryKey<any>,
+>(
   asyncIterable: AsyncIterable<unknown>,
   queryClient: QueryClient,
-  queryKey: TRPCQueryKey,
+  queryKey: TQueryKey,
 ) {
   const queryCache = queryClient.getQueryCache();
 
@@ -82,65 +118,81 @@ export async function buildQueryFromAsyncIterable(
  *
  * @internal
  */
-export function getQueryKeyInternal(
-  path: readonly string[],
-  input?: unknown,
-  type?: QueryType,
-): TRPCQueryKey {
-  // Construct a query key that is easy to destructure and flexible for
-  // partial selecting etc.
-  // https://github.com/trpc/trpc/issues/3128
-
-  // some parts of the path may be dot-separated, split them up
-  const splitPath = path.flatMap((part) => part.split('.'));
+export function getQueryKeyInternal(opts: {
+  path: string[];
+  input?: unknown;
+  type: QueryType;
+  prefix: string | undefined;
+}): AnyTRPCQueryKey {
+  const key = run((): TRPCQueryKeyWithoutPrefix => {
+    const { input, type } = opts;
+
+    // Construct a query key that is easy to destructure and flexible for
+    // partial selecting etc.
+    // https://github.com/trpc/trpc/issues/3128
+
+    // some parts of the path may be dot-separated, split them up
+    const splitPath = opts.path.flatMap((part) => part.split('.'));
+
+    if (!input && type === 'any') {
+      // this matches also all mutations (see `getMutationKeyInternal`)
+
+      // for `utils.invalidate()` to match all queries (including vanilla react-query)
+      // we don't want nested array if path is empty, i.e. `[]` instead of `[[]]`
+      return splitPath.length ? [splitPath] : ([] as unknown as TRPCQueryKey);
+    }
+
+    if (
+      type === 'infinite' &&
+      isObject(input) &&
+      ('direction' in input || 'cursor' in input)
+    ) {
+      const {
+        cursor: _,
+        direction: __,
+        ...inputWithoutCursorAndDirection
+      } = input;
+      return [
+        splitPath,
+        {
+          input: inputWithoutCursorAndDirection,
+          type: 'infinite',
+        },
+      ];
+    }
 
-  if (!input && (!type || type === 'any')) {
-    // this matches also all mutations (see `getMutationKeyInternal`)
-
-    // for `utils.invalidate()` to match all queries (including vanilla react-query)
-    // we don't want nested array if path is empty, i.e. `[]` instead of `[[]]`
-    return splitPath.length ? [splitPath] : ([] as unknown as TRPCQueryKey);
-  }
-
-  if (
-    type === 'infinite' &&
-    isObject(input) &&
-    ('direction' in input || 'cursor' in input)
-  ) {
-    const {
-      cursor: _,
-      direction: __,
-      ...inputWithoutCursorAndDirection
-    } = input;
     return [
       splitPath,
       {
-        input: inputWithoutCursorAndDirection,
-        type: 'infinite',
+        ...(typeof input !== 'undefined' &&
+          input !== skipToken && { input: input }),
+        ...(type && type !== 'any' && { type: type }),
       },
     ];
-  }
+  });
 
-  return [
-    splitPath,
-    {
-      ...(typeof input !== 'undefined' &&
-        input !== skipToken && { input: input }),
-      ...(type && type !== 'any' && { type: type }),
-    },
-  ];
+  if (opts.prefix) {
+    key.unshift([opts.prefix]);
+  }
+  return key;
 }
 
 /**
  * @internal
  */
-export function getMutationKeyInternal(
-  path: readonly string[],
-): TRPCMutationKey {
+export function getMutationKeyInternal(opts: {
+  prefix: string | undefined;
+  path: string[];
+}): AnyTRPCMutationKey {
   // some parts of the path may be dot-separated, split them up
-  const splitPath = path.flatMap((part) => part.split('.'));
+  const key: TRPCMutationKeyWithoutPrefix = [
+    opts.path.flatMap((part) => part.split('.')),
+  ];
 
-  return splitPath.length ? [splitPath] : ([] as unknown as TRPCMutationKey);
+  if (opts.prefix) {
+    key.unshift([opts.prefix]);
+  }
+  return key;
 }
 
 /**