@trpc/server 11.23.0 → 11.23.1-canary.10.8a0997add

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (215) hide show
  1. package/dist/adapters/aws-lambda/index.cjs +12 -2
  2. package/dist/adapters/aws-lambda/index.d.cts +24 -1
  3. package/dist/adapters/aws-lambda/index.d.cts.map +1 -1
  4. package/dist/adapters/aws-lambda/index.d.mts +24 -1
  5. package/dist/adapters/aws-lambda/index.d.mts.map +1 -1
  6. package/dist/adapters/aws-lambda/index.mjs +12 -2
  7. package/dist/adapters/aws-lambda/index.mjs.map +1 -1
  8. package/dist/adapters/express.cjs +8 -3
  9. package/dist/adapters/express.d.cts +12 -2
  10. package/dist/adapters/express.d.cts.map +1 -1
  11. package/dist/adapters/express.d.mts +12 -2
  12. package/dist/adapters/express.d.mts.map +1 -1
  13. package/dist/adapters/express.mjs +8 -3
  14. package/dist/adapters/express.mjs.map +1 -1
  15. package/dist/adapters/fastify/index.cjs +20 -4
  16. package/dist/adapters/fastify/index.d.cts +38 -4
  17. package/dist/adapters/fastify/index.d.cts.map +1 -1
  18. package/dist/adapters/fastify/index.d.mts +38 -4
  19. package/dist/adapters/fastify/index.d.mts.map +1 -1
  20. package/dist/adapters/fastify/index.mjs +20 -4
  21. package/dist/adapters/fastify/index.mjs.map +1 -1
  22. package/dist/adapters/fetch/index.cjs +13 -2
  23. package/dist/adapters/fetch/index.d.cts +26 -1
  24. package/dist/adapters/fetch/index.d.cts.map +1 -1
  25. package/dist/adapters/fetch/index.d.mts +26 -1
  26. package/dist/adapters/fetch/index.d.mts.map +1 -1
  27. package/dist/adapters/fetch/index.mjs +13 -2
  28. package/dist/adapters/fetch/index.mjs.map +1 -1
  29. package/dist/adapters/next-app-dir.cjs +19 -9
  30. package/dist/adapters/next-app-dir.d.cts +21 -11
  31. package/dist/adapters/next-app-dir.d.cts.map +1 -1
  32. package/dist/adapters/next-app-dir.d.mts +21 -11
  33. package/dist/adapters/next-app-dir.d.mts.map +1 -1
  34. package/dist/adapters/next-app-dir.mjs +19 -9
  35. package/dist/adapters/next-app-dir.mjs.map +1 -1
  36. package/dist/adapters/next.cjs +10 -4
  37. package/dist/adapters/next.d.cts +13 -2
  38. package/dist/adapters/next.d.cts.map +1 -1
  39. package/dist/adapters/next.d.mts +13 -2
  40. package/dist/adapters/next.d.mts.map +1 -1
  41. package/dist/adapters/next.mjs +10 -4
  42. package/dist/adapters/next.mjs.map +1 -1
  43. package/dist/adapters/node-http/index.cjs +1 -1
  44. package/dist/adapters/node-http/index.d.cts +1 -1
  45. package/dist/adapters/node-http/index.d.mts +1 -1
  46. package/dist/adapters/node-http/index.mjs +1 -1
  47. package/dist/adapters/standalone.cjs +19 -3
  48. package/dist/adapters/standalone.d.cts +32 -6
  49. package/dist/adapters/standalone.d.cts.map +1 -1
  50. package/dist/adapters/standalone.d.mts +32 -6
  51. package/dist/adapters/standalone.d.mts.map +1 -1
  52. package/dist/adapters/standalone.mjs +19 -3
  53. package/dist/adapters/standalone.mjs.map +1 -1
  54. package/dist/adapters/ws.cjs +1 -1
  55. package/dist/adapters/ws.d.cts +2 -2
  56. package/dist/adapters/ws.d.mts +2 -2
  57. package/dist/adapters/ws.mjs +1 -1
  58. package/dist/{asyncGeneratorDelegate-FcEJT04i.mjs → asyncGeneratorDelegate-Bl41FGB5.mjs} +41 -8
  59. package/dist/asyncGeneratorDelegate-Bl41FGB5.mjs.map +1 -0
  60. package/dist/{asyncGeneratorDelegate-Dj-8tGhf.cjs → asyncGeneratorDelegate-CPV0O1Hn.cjs} +40 -7
  61. package/dist/{codes-HK4UsP07.cjs → codes-Be-DrYMh.cjs} +8 -4
  62. package/dist/{codes-C9N0z0an.mjs → codes-nbrm_zWY.mjs} +9 -5
  63. package/dist/codes-nbrm_zWY.mjs.map +1 -0
  64. package/dist/{contentTypeParsers-B1e2ZNvN.cjs → contentTypeParsers-BTdoZrqN.cjs} +12 -0
  65. package/dist/contentTypeParsers-D1EBkFFY.mjs +26 -0
  66. package/dist/contentTypeParsers-D1EBkFFY.mjs.map +1 -0
  67. package/dist/{getErrorShape-hncV8cPE.cjs → getErrorShape-8t0oLscZ.cjs} +16 -5
  68. package/dist/{getErrorShape-zlj81BiC.mjs → getErrorShape-B6z8u8q0.mjs} +17 -6
  69. package/dist/getErrorShape-B6z8u8q0.mjs.map +1 -0
  70. package/dist/http.cjs +3 -3
  71. package/dist/http.d.cts +1 -1
  72. package/dist/http.d.mts +1 -1
  73. package/dist/http.mjs +3 -3
  74. package/dist/{index-BI3Qi_F-.d.cts → index-BGYvuCEh.d.cts} +68 -8
  75. package/dist/index-BGYvuCEh.d.cts.map +1 -0
  76. package/dist/{index-BI3Qi_F-.d.mts → index-BGYvuCEh.d.mts} +68 -8
  77. package/dist/index-BGYvuCEh.d.mts.map +1 -0
  78. package/dist/{index-Tpw5OCTF.d.cts → index-CTfJHk7_.d.cts} +41 -29
  79. package/dist/index-CTfJHk7_.d.cts.map +1 -0
  80. package/dist/{index-CtkOmZzm.d.mts → index-DD2oXVyh.d.mts} +41 -29
  81. package/dist/index-DD2oXVyh.d.mts.map +1 -0
  82. package/dist/index.cjs +3 -3
  83. package/dist/index.d.cts +3 -3
  84. package/dist/index.d.mts +3 -3
  85. package/dist/index.mjs +3 -3
  86. package/dist/{initTRPC-RMeQIy9H.mjs → initTRPC-JhlmAV6P.mjs} +31 -22
  87. package/dist/initTRPC-JhlmAV6P.mjs.map +1 -0
  88. package/dist/{initTRPC-DP-s8c4t.cjs → initTRPC-jn7uHFOx.cjs} +30 -21
  89. package/dist/{node-http-X8RiQEuH.cjs → node-http-CCpTZ1zd.cjs} +13 -6
  90. package/dist/{node-http-ChhZEv1k.mjs → node-http-DTcc6qM4.mjs} +14 -7
  91. package/dist/node-http-DTcc6qM4.mjs.map +1 -0
  92. package/dist/observable/index.cjs +2 -2
  93. package/dist/observable/index.d.cts +1 -1
  94. package/dist/observable/index.d.mts +1 -1
  95. package/dist/observable/index.mjs +2 -2
  96. package/dist/{observable-C-LvH26G.cjs → observable-B8nn0anr.cjs} +27 -4
  97. package/dist/{observable-yEyhfXUI.mjs → observable-CdPmrXKY.mjs} +28 -5
  98. package/dist/observable-CdPmrXKY.mjs.map +1 -0
  99. package/dist/{observable-CkXWrCsV.mjs → observable-F1Nt_3e4.mjs} +16 -4
  100. package/dist/observable-F1Nt_3e4.mjs.map +1 -0
  101. package/dist/{observable-xBsJ11Ns.cjs → observable-N4F1yT7s.cjs} +15 -3
  102. package/dist/{parseTRPCMessage-CJ4DJVBp.mjs → parseTRPCMessage-BO1-cCsX.mjs} +7 -3
  103. package/dist/parseTRPCMessage-BO1-cCsX.mjs.map +1 -0
  104. package/dist/{parseTRPCMessage-CPEfSSFx.cjs → parseTRPCMessage-BsPr5reh.cjs} +6 -2
  105. package/dist/{resolveResponse-DksrxZ2k.mjs → resolveResponse-B2MQmLSr.mjs} +17 -5
  106. package/dist/resolveResponse-B2MQmLSr.mjs.map +1 -0
  107. package/dist/{resolveResponse-CoGjFxK0.cjs → resolveResponse-BQcrvKyB.cjs} +16 -4
  108. package/dist/rpc.cjs +2 -2
  109. package/dist/rpc.d.cts +1 -1
  110. package/dist/rpc.d.mts +1 -1
  111. package/dist/rpc.mjs +2 -2
  112. package/dist/shared.cjs +1 -1
  113. package/dist/shared.d.cts +1 -1
  114. package/dist/shared.d.mts +1 -1
  115. package/dist/shared.mjs +1 -1
  116. package/dist/{unstable-core-do-not-import-B8epiErP.d.cts → unstable-core-do-not-import-DYnAWlN7.d.cts} +517 -161
  117. package/dist/unstable-core-do-not-import-DYnAWlN7.d.cts.map +1 -0
  118. package/dist/{unstable-core-do-not-import-Dbo98mkh.d.mts → unstable-core-do-not-import-hC2_7K-s.d.mts} +517 -161
  119. package/dist/unstable-core-do-not-import-hC2_7K-s.d.mts.map +1 -0
  120. package/dist/unstable-core-do-not-import.cjs +7 -7
  121. package/dist/unstable-core-do-not-import.d.cts +1 -1
  122. package/dist/unstable-core-do-not-import.d.mts +1 -1
  123. package/dist/unstable-core-do-not-import.mjs +7 -7
  124. package/dist/{ws-BYfo-HED.mjs → ws-B9v4J-4P.mjs} +30 -11
  125. package/dist/ws-B9v4J-4P.mjs.map +1 -0
  126. package/dist/ws-DVHbmgfC.d.mts +95 -0
  127. package/dist/ws-DVHbmgfC.d.mts.map +1 -0
  128. package/dist/ws-JzZs-0Zd.d.cts +95 -0
  129. package/dist/ws-JzZs-0Zd.d.cts.map +1 -0
  130. package/dist/{ws-7qWW7Uec.cjs → ws-_SClUVOu.cjs} +29 -10
  131. package/package.json +2 -2
  132. package/skills/adapter-aws-lambda/SKILL.md +1 -1
  133. package/skills/adapter-express/SKILL.md +1 -1
  134. package/skills/adapter-fastify/SKILL.md +1 -1
  135. package/skills/adapter-fetch/SKILL.md +1 -1
  136. package/skills/adapter-standalone/SKILL.md +1 -1
  137. package/skills/auth/SKILL.md +1 -1
  138. package/skills/caching/SKILL.md +2 -2
  139. package/skills/error-handling/SKILL.md +1 -1
  140. package/skills/middlewares/SKILL.md +1 -1
  141. package/skills/non-json-content-types/SKILL.md +1 -1
  142. package/skills/server-setup/SKILL.md +1 -1
  143. package/skills/server-side-calls/SKILL.md +1 -1
  144. package/skills/service-oriented-architecture/SKILL.md +1 -1
  145. package/skills/subscriptions/SKILL.md +1 -1
  146. package/skills/trpc-router/SKILL.md +1 -1
  147. package/skills/validators/SKILL.md +1 -1
  148. package/src/@trpc/server/index.ts +2 -2
  149. package/src/adapters/aws-lambda/index.ts +23 -0
  150. package/src/adapters/express.ts +10 -0
  151. package/src/adapters/fastify/fastifyRequestHandler.ts +5 -0
  152. package/src/adapters/fastify/fastifyTRPCPlugin.ts +30 -1
  153. package/src/adapters/fetch/fetchRequestHandler.ts +11 -0
  154. package/src/adapters/fetch/types.ts +14 -0
  155. package/src/adapters/next-app-dir/nextAppDirCaller.ts +8 -4
  156. package/src/adapters/next-app-dir/notFound.ts +3 -1
  157. package/src/adapters/next-app-dir/redirect.ts +6 -4
  158. package/src/adapters/next-app-dir/rethrowNextErrors.ts +5 -1
  159. package/src/adapters/next.ts +13 -1
  160. package/src/adapters/node-http/incomingMessageToRequest.ts +6 -1
  161. package/src/adapters/node-http/nodeHTTPRequestHandler.ts +3 -1
  162. package/src/adapters/node-http/types.ts +30 -25
  163. package/src/adapters/standalone.ts +30 -4
  164. package/src/adapters/ws.ts +42 -8
  165. package/src/adapters/wsEncoder.ts +5 -6
  166. package/src/observable/behaviorSubject.ts +6 -2
  167. package/src/observable/observable.ts +31 -5
  168. package/src/observable/operators.ts +12 -0
  169. package/src/observable/types.ts +18 -0
  170. package/src/unstable-core-do-not-import/clientish/inference.ts +22 -1
  171. package/src/unstable-core-do-not-import/clientish/inferrable.ts +5 -2
  172. package/src/unstable-core-do-not-import/createProxy.ts +4 -4
  173. package/src/unstable-core-do-not-import/error/TRPCError.ts +19 -0
  174. package/src/unstable-core-do-not-import/error/formatter.ts +15 -2
  175. package/src/unstable-core-do-not-import/error/getErrorShape.ts +2 -0
  176. package/src/unstable-core-do-not-import/http/contentTypeParsers.ts +15 -2
  177. package/src/unstable-core-do-not-import/http/getHTTPStatusCode.ts +9 -0
  178. package/src/unstable-core-do-not-import/http/parseConnectionParams.ts +8 -0
  179. package/src/unstable-core-do-not-import/http/resolveResponse.ts +4 -0
  180. package/src/unstable-core-do-not-import/http/types.ts +55 -27
  181. package/src/unstable-core-do-not-import/initTRPC.ts +51 -27
  182. package/src/unstable-core-do-not-import/middleware.ts +25 -5
  183. package/src/unstable-core-do-not-import/procedure.ts +28 -2
  184. package/src/unstable-core-do-not-import/procedureBuilder.ts +56 -35
  185. package/src/unstable-core-do-not-import/rootConfig.ts +28 -19
  186. package/src/unstable-core-do-not-import/router.ts +71 -11
  187. package/src/unstable-core-do-not-import/rpc/codes.ts +13 -5
  188. package/src/unstable-core-do-not-import/rpc/envelopes.ts +45 -9
  189. package/src/unstable-core-do-not-import/rpc/parseTRPCMessage.ts +5 -1
  190. package/src/unstable-core-do-not-import/stream/tracked.ts +17 -5
  191. package/src/unstable-core-do-not-import/transformer.ts +12 -1
  192. package/src/unstable-core-do-not-import/types.ts +2 -0
  193. package/src/unstable-core-do-not-import/utils.ts +4 -1
  194. package/dist/asyncGeneratorDelegate-FcEJT04i.mjs.map +0 -1
  195. package/dist/codes-C9N0z0an.mjs.map +0 -1
  196. package/dist/contentTypeParsers-Bb-9hUEf.mjs +0 -14
  197. package/dist/contentTypeParsers-Bb-9hUEf.mjs.map +0 -1
  198. package/dist/getErrorShape-zlj81BiC.mjs.map +0 -1
  199. package/dist/index-BI3Qi_F-.d.cts.map +0 -1
  200. package/dist/index-BI3Qi_F-.d.mts.map +0 -1
  201. package/dist/index-CtkOmZzm.d.mts.map +0 -1
  202. package/dist/index-Tpw5OCTF.d.cts.map +0 -1
  203. package/dist/initTRPC-RMeQIy9H.mjs.map +0 -1
  204. package/dist/node-http-ChhZEv1k.mjs.map +0 -1
  205. package/dist/observable-CkXWrCsV.mjs.map +0 -1
  206. package/dist/observable-yEyhfXUI.mjs.map +0 -1
  207. package/dist/parseTRPCMessage-CJ4DJVBp.mjs.map +0 -1
  208. package/dist/resolveResponse-DksrxZ2k.mjs.map +0 -1
  209. package/dist/unstable-core-do-not-import-B8epiErP.d.cts.map +0 -1
  210. package/dist/unstable-core-do-not-import-Dbo98mkh.d.mts.map +0 -1
  211. package/dist/ws-BYfo-HED.mjs.map +0 -1
  212. package/dist/ws-DD1ukLuC.d.cts +0 -61
  213. package/dist/ws-DD1ukLuC.d.cts.map +0 -1
  214. package/dist/ws-DT37N43e.d.mts +0 -61
  215. package/dist/ws-DT37N43e.d.mts.map +0 -1
@@ -56,6 +56,11 @@ export function getCauseFromUnknown(cause: unknown): Error | undefined {
56
56
  return undefined;
57
57
  }
58
58
 
59
+ /**
60
+ * Turns anything thrown into a `TRPCError`. A `TRPCError` is returned as
61
+ * is; anything else becomes an `INTERNAL_SERVER_ERROR` with it as the
62
+ * cause.
63
+ */
59
64
  export function getTRPCErrorFromUnknown(cause: unknown): TRPCError {
60
65
  if (cause instanceof TRPCError) {
61
66
  return cause;
@@ -78,15 +83,29 @@ export function getTRPCErrorFromUnknown(cause: unknown): TRPCError {
78
83
  return trpcError;
79
84
  }
80
85
 
86
+ /**
87
+ * An error with a tRPC error code, which sets the HTTP status and the code
88
+ * the client sees. Throw it from resolvers and middlewares.
89
+ * @example
90
+ * ```ts
91
+ * throw new TRPCError({ code: 'NOT_FOUND', message: 'No such post' });
92
+ * ```
93
+ * @see https://trpc.io/docs/server/error-handling#throwing-errors
94
+ */
81
95
  export class TRPCError extends Error {
82
96
  // oxlint-disable-next-line typescript/ban-ts-comment
83
97
  // @ts-ignore override doesn't work in all environments due to "This member cannot have an 'override' modifier because it is not declared in the base class 'Error'"
98
+ /** The error this one wraps, if any. */
84
99
  public override readonly cause?: Error;
100
+ /** The tRPC error code, such as `'NOT_FOUND'`. */
85
101
  public readonly code;
86
102
 
87
103
  constructor(opts: {
104
+ /** Defaults to the cause's message, or else the code. */
88
105
  message?: string;
106
+ /** @see https://trpc.io/docs/server/error-handling#error-codes */
89
107
  code: TRPC_ERROR_CODE_KEY;
108
+ /** The original error. Anything that isn't an `Error` is wrapped in one. */
90
109
  cause?: unknown;
91
110
  }) {
92
111
  const cause = getCauseFromUnknown(opts.cause);
@@ -10,18 +10,25 @@ import type { Overwrite, Simplify } from '../types';
10
10
  import type { TRPCError } from './TRPCError';
11
11
 
12
12
  /**
13
+ * What an error formatter gets.
14
+ * @see https://trpc.io/docs/server/error-formatting#all-properties-sent-to-errorformatter
13
15
  * @internal
14
16
  */
15
17
  export interface ErrorFormatterOptions<TContext> {
16
18
  error: TRPCError;
17
19
  type: ProcedureType | 'unknown';
20
+ /** The procedure's path, if the error came from one. */
18
21
  path: string | undefined;
19
22
  input: unknown;
23
+ /** The context, if it was created before the error. */
20
24
  ctx: TContext;
25
+ /** The shape tRPC sends by default, to extend or replace. */
21
26
  shape: DefaultErrorShape;
22
27
  }
23
28
 
24
29
  /**
30
+ * Shapes the errors a router sends to the client.
31
+ * @see https://trpc.io/docs/server/error-formatting
25
32
  * @internal
26
33
  */
27
34
  export type ErrorFormatter<TContext, TShape extends TRPCErrorShape> = (
@@ -29,6 +36,9 @@ export type ErrorFormatter<TContext, TShape extends TRPCErrorShape> = (
29
36
  ) => TShape;
30
37
 
31
38
  /**
39
+ * An error formatter for one procedure, as `.errors()` takes it. Return
40
+ * `undefined` to leave the error to the next formatter.
41
+ * @see https://trpc.io/docs/server/error-formatting#per-procedure-error-formatting
32
42
  * @internal
33
43
  */
34
44
  export type ProcedureErrorFormatter<
@@ -45,22 +55,25 @@ export type ProcedureErrorFormatter<
45
55
  export type AnyProcedureErrorFormatter = ProcedureErrorFormatter<any, any, any>;
46
56
 
47
57
  /**
58
+ * The `data` of the default error shape.
48
59
  * @internal
49
60
  */
50
61
  export type DefaultErrorData = {
51
62
  code: TRPC_ERROR_CODE_KEY;
52
63
  httpStatus: number;
53
64
  /**
54
- * Path to the procedure that threw the error
65
+ * The path of the procedure that threw.
55
66
  */
56
67
  path?: string;
57
68
  /**
58
- * Stack trace of the error (only in development)
69
+ * The error's stack trace, only when `isDev` is set.
59
70
  */
60
71
  stack?: string;
61
72
  };
62
73
 
63
74
  /**
75
+ * The error shape tRPC sends when there's no error formatter.
76
+ * @see https://trpc.io/docs/server/error-formatting
64
77
  * @internal
65
78
  */
66
79
  export interface DefaultErrorShape extends TRPCErrorShape<DefaultErrorData> {
@@ -4,6 +4,8 @@ import { getDefaultErrorShape, getFormattedErrorShape } from './formatter';
4
4
  import type { TRPCError } from './TRPCError';
5
5
 
6
6
  /**
7
+ * The shape of an error as the client gets it: from a procedure's
8
+ * `.errors()` formatter if one ran, or else from the root error formatter.
7
9
  * @internal
8
10
  */
9
11
  export function getErrorShape<TRoot extends AnyRootTypes>(opts: {
@@ -1,6 +1,7 @@
1
1
  import type { ParserZodEsque } from '../parser';
2
2
 
3
3
  /**
4
+ * A validator tRPC ships for a special input type.
4
5
  * @internal
5
6
  */
6
7
  export type UtilityParser<TInput, TOutput> = ParserZodEsque<TInput, TOutput> & {
@@ -10,19 +11,31 @@ export type UtilityParser<TInput, TOutput> = ParserZodEsque<TInput, TOutput> & {
10
11
  // Should be the same possible types as packages/client/src/links/internals/contentTypes.ts isOctetType
11
12
 
12
13
  /**
14
+ * A `File`. Node 18 has no `File` type, but a `File` is always a `Blob`.
13
15
  * @internal
14
- *
15
- * File is only available from Node19+ but it always extends Blob so we can use that as a type until we eventually drop Node18
16
16
  */
17
17
  export interface FileLike extends Blob {
18
18
  readonly name: string;
19
19
  }
20
20
 
21
21
  /**
22
+ * The binary inputs a client can send with `octetInputParser`.
22
23
  * @internal
23
24
  */
24
25
  export type OctetInput = Blob | Uint8Array | FileLike;
25
26
 
27
+ /**
28
+ * An input validator for binary data, such as a `File` or `Blob`. The
29
+ * resolver gets the input as a `ReadableStream`.
30
+ * @example
31
+ * ```ts
32
+ * t.procedure.input(octetInputParser).mutation(async ({ input }) => {
33
+ * const bytes = await new Response(input).arrayBuffer();
34
+ * return { size: bytes.byteLength };
35
+ * });
36
+ * ```
37
+ * @see https://trpc.io/docs/server/non-json-content-types#file-and-other-binary-type-inputs
38
+ */
26
39
  export const octetInputParser: UtilityParser<OctetInput, ReadableStream> = {
27
40
  _input: null as any as OctetInput,
28
41
  _output: null as any as ReadableStream,
@@ -68,6 +68,11 @@ export function getStatusKeyFromCode(
68
68
  return HTTP_CODE_TO_JSONRPC2[code] ?? 'INTERNAL_SERVER_ERROR';
69
69
  }
70
70
 
71
+ /**
72
+ * The HTTP status for a response, or for a batch of them: `207` when the
73
+ * responses' statuses differ.
74
+ * @see https://trpc.io/docs/rpc#error-codes---http-status
75
+ */
71
76
  export function getHTTPStatusCode(json: TRPCResponse | TRPCResponse[]) {
72
77
  const arr = Array.isArray(json) ? json : [json];
73
78
  const httpStatuses = new Set<number>(
@@ -93,6 +98,10 @@ export function getHTTPStatusCode(json: TRPCResponse | TRPCResponse[]) {
93
98
  return httpStatus!;
94
99
  }
95
100
 
101
+ /**
102
+ * The HTTP status of a `TRPCError`'s code.
103
+ * @see https://trpc.io/docs/rpc#error-codes---http-status
104
+ */
96
105
  export function getHTTPStatusCodeFromError(error: TRPCError) {
97
106
  return getStatusCodeFromKey(error.code);
98
107
  }
@@ -2,6 +2,10 @@ import { TRPCError } from '../error/TRPCError';
2
2
  import { isObject } from '../utils';
3
3
  import type { TRPCRequestInfo } from './types';
4
4
 
5
+ /**
6
+ * Checks that connection params are an object of strings, or `null`.
7
+ * Throws a `PARSE_ERROR` if they aren't.
8
+ */
5
9
  export function parseConnectionParamsFromUnknown(
6
10
  parsed: unknown,
7
11
  ): TRPCRequestInfo['connectionParams'] {
@@ -32,6 +36,10 @@ export function parseConnectionParamsFromUnknown(
32
36
  });
33
37
  }
34
38
  }
39
+ /**
40
+ * Parses connection params from JSON, as `parseConnectionParamsFromUnknown`
41
+ * checks them.
42
+ */
35
43
  export function parseConnectionParamsFromString(
36
44
  str: string,
37
45
  ): TRPCRequestInfo['connectionParams'] {
@@ -258,6 +258,10 @@ function isDataStream(v: unknown) {
258
258
 
259
259
  type ResultTuple<T> = [undefined, T] | [TRPCError, undefined];
260
260
 
261
+ /**
262
+ * Handles a Fetch API `Request` for a router and returns its `Response`.
263
+ * Every adapter uses it; call it to write your own.
264
+ */
261
265
  export async function resolveResponse<TRouter extends AnyRouter>(
262
266
  opts: ResolveHTTPRequestOptions<TRouter>,
263
267
  ): Promise<Response> {
@@ -13,60 +13,74 @@ import type { TRPCResponse } from '../rpc';
13
13
  import type { Dict } from '../types';
14
14
 
15
15
  /**
16
- * @deprecated use `Headers` instead, this will be removed in v12
16
+ * @deprecated Use `Headers` instead. This will be removed in v12.
17
17
  */
18
18
  type HTTPHeaders = Dict<string[] | string>;
19
19
 
20
+ /**
21
+ * The status and headers `responseMeta` sets on a response.
22
+ * @see https://trpc.io/docs/server/caching#using-responsemeta-to-cache-responses
23
+ */
20
24
  export interface ResponseMeta {
25
+ /** The HTTP status. Defaults to the one tRPC picks from the results. */
21
26
  status?: number;
27
+ /** Headers to add to the response. */
22
28
  headers?: Headers | HTTPHeaders;
23
29
  }
24
30
 
25
31
  /**
32
+ * Sets a response's status and headers from the request and its results.
33
+ * @see https://trpc.io/docs/server/caching#using-responsemeta-to-cache-responses
26
34
  * @internal
27
35
  */
28
36
  export type ResponseMetaFn<TRouter extends AnyRouter> = (opts: {
29
37
  data: TRPCResponse<unknown, inferRouterError<TRouter>>[];
30
38
  ctx?: inferRouterContext<TRouter>;
31
39
  /**
32
- * The different tRPC paths requested
33
- * @deprecated use `info` instead, this will be removed in v12
40
+ * The paths of the procedures called.
41
+ * @deprecated Use `info` instead. This will be removed in v12.
34
42
  **/
35
43
  paths: readonly string[] | undefined;
44
+ /** The request, if it could be parsed. */
36
45
  info: TRPCRequestInfo | undefined;
37
46
  type: ProcedureType | 'unknown';
47
+ /** The errors the calls threw. */
38
48
  errors: TRPCError[];
39
49
  /**
40
- * `true` if the `ResponseMeta` is being generated without knowing the response data (e.g. for streamed requests).
50
+ * `true` when it's called before the results are known, as for streamed
51
+ * responses.
41
52
  */
42
53
  eagerGeneration: boolean;
43
54
  }) => ResponseMeta;
44
55
 
45
56
  /**
46
- * Base interface for anything using HTTP
57
+ * The options every HTTP adapter takes.
47
58
  */
48
59
  export interface HTTPBaseHandlerOptions<
49
60
  TRouter extends AnyRouter,
50
61
  TRequest,
51
62
  > extends BaseHandlerOptions<TRouter, TRequest> {
52
63
  /**
53
- * Add handler to be called before response is sent to the user
54
- * Useful for setting cache headers
55
- * @see https://trpc.io/docs/v11/caching
64
+ * Sets the response's status and headers before it's sent, for example
65
+ * to cache it.
66
+ * @see https://trpc.io/docs/server/caching#using-responsemeta-to-cache-responses
56
67
  */
57
68
  responseMeta?: ResponseMetaFn<TRouter>;
58
69
  }
59
70
 
71
+ /** The `trpc-accept` header's value for a streamed response. */
60
72
  export type TRPCAcceptHeader = 'application/jsonl';
61
73
 
74
+ /** One procedure call in a request. */
62
75
  export interface TRPCRequestInfoProcedureCall {
63
76
  path: string;
64
77
  /**
65
- * Read the raw input (deduped and memoized)
78
+ * Reads the call's input as the client sent it. It's read once, however
79
+ * often it's called.
66
80
  */
67
81
  getRawInput: () => Promise<unknown>;
68
82
  /**
69
- * Get already parsed inputs - won't trigger reading the body or parsing the inputs
83
+ * The input if it was read already. Doesn't read the body.
70
84
  */
71
85
  result: () => unknown;
72
86
  /**
@@ -81,43 +95,46 @@ export interface TRPCRequestInfoProcedureCall {
81
95
  }
82
96
 
83
97
  /**
84
- * Information about the incoming request
98
+ * What tRPC knows about a request, which `createContext` gets as `info`.
99
+ * @see https://trpc.io/docs/server/context#creating-the-context
85
100
  * @public
86
101
  */
87
102
  export interface TRPCRequestInfo {
88
103
  /**
89
- * The `trpc-accept` header
104
+ * The `trpc-accept` header.
90
105
  */
91
106
  accept: TRPCAcceptHeader | null;
92
107
  /**
93
- * The type of the request
108
+ * The type of the procedures called.
94
109
  */
95
110
  type: ProcedureType | 'unknown';
96
111
  /**
97
- * If the content type handler has detected that this is a batch call
112
+ * Whether the request is a batch.
98
113
  */
99
114
  isBatchCall: boolean;
100
115
  /**
101
- * The calls being made
116
+ * The procedure calls in the request.
102
117
  */
103
118
  calls: TRPCRequestInfoProcedureCall[];
104
119
  /**
105
- * Connection params when using `httpSubscriptionLink` or `createWSClient`
120
+ * The connection params the client sent with `httpSubscriptionLink` or
121
+ * `createWSClient`.
106
122
  */
107
123
  connectionParams: Dict<string> | null;
108
124
  /**
109
- * Signal when the request is aborted
110
- * Can be used to abort async operations during the request, e.g. `fetch()`-requests
125
+ * Aborts when the request does. Pass it on to work the request starts,
126
+ * such as `fetch()` calls.
111
127
  */
112
128
  signal: AbortSignal;
113
129
  /**
114
- * The URL of the request if available
130
+ * The request's URL, if known.
115
131
  */
116
132
  url: URL | null;
117
133
  }
118
134
 
119
135
  /**
120
- * Inner createContext function for `resolveResponse` used to forward `TRPCRequestInfo` to `createContext`
136
+ * The `createContext` that `resolveResponse` takes: it gets the request's
137
+ * `info`.
121
138
  * @internal
122
139
  */
123
140
  export type ResolveHTTPRequestOptionsContextFn<TRouter extends AnyRouter> =
@@ -130,6 +147,9 @@ interface HTTPErrorHandlerOptions<
130
147
  req: TRequest;
131
148
  }
132
149
  /**
150
+ * Called with each error a procedure throws. With streamed responses the
151
+ * response may have started already, so don't rely on setting headers.
152
+ * @see https://trpc.io/docs/server/error-handling#handling-errors
133
153
  * @internal
134
154
  */
135
155
  export type HTTPErrorHandler<TRouter extends AnyRouter, TRequest> = (
@@ -137,13 +157,17 @@ export type HTTPErrorHandler<TRouter extends AnyRouter, TRequest> = (
137
157
  ) => void;
138
158
 
139
159
  /**
140
- * Base interface for any response handler
160
+ * The options every adapter takes.
141
161
  * @internal
142
162
  */
143
163
  export interface BaseHandlerOptions<TRouter extends AnyRouter, TRequest> {
164
+ /**
165
+ * Called with each error a procedure throws, for example to log it.
166
+ * @see https://trpc.io/docs/server/error-handling#handling-errors
167
+ */
144
168
  onError?: HTTPErrorHandler<TRouter, TRequest>;
145
169
  /**
146
- * @deprecated use `allowBatching` instead, this will be removed in v12
170
+ * @deprecated Use `allowBatching` instead. This will be removed in v12.
147
171
  */
148
172
  batching?: {
149
173
  /**
@@ -151,21 +175,25 @@ export interface BaseHandlerOptions<TRouter extends AnyRouter, TRequest> {
151
175
  */
152
176
  enabled: boolean;
153
177
  };
178
+ /** The router to serve. */
154
179
  router: TRouter;
155
180
  /**
156
- * Allow method override - will skip the method check
181
+ * Lets clients call queries and subscriptions with POST as well as GET.
182
+ * Mutations always use POST.
183
+ * @see https://trpc.io/docs/rpc#overriding-the-default-http-method
157
184
  * @default false
158
185
  */
159
186
  allowMethodOverride?: boolean;
160
187
  /**
161
- * Allow request batching
188
+ * Whether clients can batch calls into one request.
189
+ * @see https://trpc.io/docs/client/links/httpBatchLink#disabling-request-batching
162
190
  * @default true
163
191
  */
164
192
  allowBatching?: boolean;
165
193
  /**
166
- * Restrict the maximum size of a batch call, invalid requests will be rejected with a 400 error
167
- *
168
- * @important Ensure you set the same or lower limit on your client batch link
194
+ * The most calls a batch can have. Larger batches get a 400 error. Set
195
+ * the client's `maxItems` to the same or a lower number.
196
+ * @see https://trpc.io/docs/client/links/httpBatchLink#limiting-batch-size
169
197
  * @default unlimited
170
198
  */
171
199
  maxBatchSize?: number;
@@ -27,7 +27,10 @@ import type { UnsetMarker } from './utils';
27
27
 
28
28
  type inferErrorFormatterShape<TType> =
29
29
  TType extends ErrorFormatter<any, infer TShape> ? TShape : DefaultErrorShape;
30
- /** @internal */
30
+ /**
31
+ * The options `initTRPC.create()` takes.
32
+ * @internal
33
+ */
31
34
  export interface RuntimeConfigOptions<
32
35
  TContext extends object,
33
36
  TMeta extends object,
@@ -43,14 +46,20 @@ export interface RuntimeConfigOptions<
43
46
  >
44
47
  > {
45
48
  /**
46
- * Use a data transformer
47
- * @see https://trpc.io/docs/v11/data-transformers
49
+ * Serializes inputs and outputs, so they can carry types JSON can't, such
50
+ * as `Date`. The client's links must use the same transformer.
51
+ * @see https://trpc.io/docs/server/data-transformers
48
52
  */
49
53
  transformer?: DataTransformerOptions;
50
54
  }
51
55
 
52
56
  type ContextCallback = (...args: any[]) => object | Promise<object>;
53
57
 
58
+ /**
59
+ * What `initTRPC.create()` returns: the builders for your procedures,
60
+ * middlewares and routers. Create it once per backend.
61
+ * @see https://trpc.io/docs/server/routers#initialize-trpc
62
+ */
54
63
  export interface TRPCRootObject<
55
64
  TContext extends object,
56
65
  TMeta extends object,
@@ -65,14 +74,15 @@ export interface TRPCRootObject<
65
74
  },
66
75
  > {
67
76
  /**
68
- * Your router config
77
+ * The config the root object was created with.
69
78
  * @internal
70
79
  */
71
80
  _config: RootConfig<$Root>;
72
81
 
73
82
  /**
74
- * Builder object for creating procedures
75
- * @see https://trpc.io/docs/v11/server/procedures
83
+ * The base procedure builder. Add inputs, middlewares and a resolver to
84
+ * make a query, mutation or subscription.
85
+ * @see https://trpc.io/docs/server/procedures
76
86
  */
77
87
  procedure: ProcedureBuilder<
78
88
  TContext,
@@ -87,38 +97,45 @@ export interface TRPCRootObject<
87
97
  >;
88
98
 
89
99
  /**
90
- * Create reusable middlewares
91
- * @see https://trpc.io/docs/v11/server/middlewares
100
+ * Creates a middleware you can reuse across procedures with `.use()`.
101
+ * @see https://trpc.io/docs/server/middlewares
92
102
  */
93
103
  middleware: <$ContextOverrides>(
94
104
  fn: MiddlewareFunction<TContext, TMeta, object, $ContextOverrides, unknown>,
95
105
  ) => MiddlewareBuilder<TContext, TMeta, $ContextOverrides, unknown>;
96
106
 
97
107
  /**
98
- * Create a router
99
- * @see https://trpc.io/docs/v11/server/routers
108
+ * Creates a router from a record of procedures and sub-routers.
109
+ * @see https://trpc.io/docs/server/routers
100
110
  */
101
111
  router: RouterBuilder<$Root>;
102
112
 
103
113
  /**
104
- * Merge Routers
105
- * @see https://trpc.io/docs/v11/server/merging-routers
114
+ * Merges routers into one, flattening their procedures into the same
115
+ * namespace.
116
+ * @see https://trpc.io/docs/server/merging-routers#merging-with-tmergerouters
106
117
  */
107
118
  mergeRouters: <TRouters extends AnyRouter[]>(
108
119
  ...routerList: [...TRouters]
109
120
  ) => MergeRouters<TRouters>;
110
121
 
111
122
  /**
112
- * Create a server-side caller for a router
113
- * @see https://trpc.io/docs/v11/server/server-side-calls
123
+ * Creates a factory for callers, which call a router's procedures
124
+ * directly on the server, without HTTP.
125
+ * @see https://trpc.io/docs/server/server-side-calls
114
126
  */
115
127
  createCallerFactory: RouterCallerFactory<$Root>;
116
128
  }
117
129
 
130
+ /**
131
+ * The type of `initTRPC`. Chain `.context()` and `.meta()` to set their
132
+ * types, then call `.create()`.
133
+ */
118
134
  class TRPCBuilder<TContext extends object, TMeta extends object> {
119
135
  /**
120
- * Add a context shape as a generic to the root object
121
- * @see https://trpc.io/docs/v11/server/context
136
+ * Sets the type of the context every procedure gets. Pass the type, or
137
+ * the type of your `createContext` function.
138
+ * @see https://trpc.io/docs/server/context#defining-the-context-type
122
139
  */
123
140
  context<TNewContext extends object | ContextCallback>() {
124
141
  return new TRPCBuilder<
@@ -128,16 +145,17 @@ class TRPCBuilder<TContext extends object, TMeta extends object> {
128
145
  }
129
146
 
130
147
  /**
131
- * Add a meta shape as a generic to the root object
132
- * @see https://trpc.io/docs/v11/quickstart
148
+ * Sets the type of the metadata procedures can set with `.meta()`.
149
+ * @see https://trpc.io/docs/server/metadata
133
150
  */
134
151
  meta<TNewMeta extends object>() {
135
152
  return new TRPCBuilder<TContext, TNewMeta>();
136
153
  }
137
154
 
138
155
  /**
139
- * Create the root object
140
- * @see https://trpc.io/docs/v11/server/routers#initialize-trpc
156
+ * Creates the root object, which holds the builders for your procedures,
157
+ * middlewares and routers.
158
+ * @see https://trpc.io/docs/server/routers#initialize-trpc
141
159
  */
142
160
  create<TOptions extends RuntimeConfigOptions<TContext, TMeta>>(
143
161
  opts?: ValidateShape<TOptions, RuntimeConfigOptions<TContext, TMeta>>,
@@ -183,7 +201,7 @@ class TRPCBuilder<TContext extends object, TMeta extends object> {
183
201
  _config: config,
184
202
  /**
185
203
  * Builder object for creating procedures
186
- * @see https://trpc.io/docs/v11/server/procedures
204
+ * @see https://trpc.io/docs/server/procedures
187
205
  */
188
206
  procedure: createBuilder<
189
207
  $Root['ctx'],
@@ -195,22 +213,22 @@ class TRPCBuilder<TContext extends object, TMeta extends object> {
195
213
  }),
196
214
  /**
197
215
  * Create reusable middlewares
198
- * @see https://trpc.io/docs/v11/server/middlewares
216
+ * @see https://trpc.io/docs/server/middlewares
199
217
  */
200
218
  middleware: createMiddlewareFactory<$Root['ctx'], $Root['meta']>(),
201
219
  /**
202
220
  * Create a router
203
- * @see https://trpc.io/docs/v11/server/routers
221
+ * @see https://trpc.io/docs/server/routers
204
222
  */
205
223
  router: createRouterFactory<$Root>(config),
206
224
  /**
207
225
  * Merge Routers
208
- * @see https://trpc.io/docs/v11/server/merging-routers
226
+ * @see https://trpc.io/docs/server/merging-routers
209
227
  */
210
228
  mergeRouters,
211
229
  /**
212
230
  * Create a server-side caller for a router
213
- * @see https://trpc.io/docs/v11/server/server-side-calls
231
+ * @see https://trpc.io/docs/server/server-side-calls
214
232
  */
215
233
  createCallerFactory: createCallerFactory<$Root>(),
216
234
  };
@@ -218,8 +236,14 @@ class TRPCBuilder<TContext extends object, TMeta extends object> {
218
236
  }
219
237
 
220
238
  /**
221
- * Builder to initialize the tRPC root object - use this exactly once per backend
222
- * @see https://trpc.io/docs/v11/quickstart
239
+ * The starting point of every tRPC backend. Call it once.
240
+ * @example
241
+ * ```ts
242
+ * const t = initTRPC.context<Context>().create();
243
+ * export const router = t.router;
244
+ * export const publicProcedure = t.procedure;
245
+ * ```
246
+ * @see https://trpc.io/docs/server/routers#initialize-trpc
223
247
  */
224
248
  export const initTRPC = new TRPCBuilder();
225
249
  export type { TRPCBuilder };