@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
@@ -40,6 +40,8 @@ interface MiddlewareErrorResult<
40
40
  }
41
41
 
42
42
  /**
43
+ * What a middleware's `next()` returns, and what the middleware must
44
+ * return in turn.
43
45
  * @internal
44
46
  */
45
47
  export type MiddlewareResult<_TContextOverride> =
@@ -47,6 +49,8 @@ export type MiddlewareResult<_TContextOverride> =
47
49
  | MiddlewareOKResult<_TContextOverride>;
48
50
 
49
51
  /**
52
+ * A reusable middleware, as `t.middleware()` returns it.
53
+ * @see https://trpc.io/docs/server/middlewares
50
54
  * @internal
51
55
  */
52
56
  export interface MiddlewareBuilder<
@@ -56,7 +60,9 @@ export interface MiddlewareBuilder<
56
60
  TInputOut,
57
61
  > {
58
62
  /**
59
- * Create a new builder based on the current middleware builder
63
+ * Returns a new middleware that runs this one, then `fn`, which sees the
64
+ * context this one set.
65
+ * @see https://trpc.io/docs/server/middlewares#extending-middlewares
60
66
  */
61
67
  unstable_pipe<$ContextOverridesOut>(
62
68
  fn:
@@ -81,7 +87,7 @@ export interface MiddlewareBuilder<
81
87
  >;
82
88
 
83
89
  /**
84
- * List of middlewares within this middleware builder
90
+ * The middlewares this builder runs, in order.
85
91
  */
86
92
  _middlewares: MiddlewareFunction<
87
93
  TContext,
@@ -93,6 +99,9 @@ export interface MiddlewareBuilder<
93
99
  }
94
100
 
95
101
  /**
102
+ * A middleware: it gets the call's options and must return the result of
103
+ * calling `next()`, optionally with a new `ctx` or `input`.
104
+ * @see https://trpc.io/docs/server/middlewares
96
105
  * @internal
97
106
  */
98
107
  export type MiddlewareFunction<
@@ -105,15 +114,23 @@ export type MiddlewareFunction<
105
114
  (opts: {
106
115
  ctx: Simplify<Overwrite<TContext, TContextOverridesIn>>;
107
116
  type: ProcedureType;
117
+ /** The procedure's path, such as `post.byId`. */
108
118
  path: string;
119
+ /** The input, as the validators that ran before this middleware left it. */
109
120
  input: TInputOut;
121
+ /** Reads the input as the client sent it, before any validator ran. */
110
122
  getRawInput: GetRawInputFn;
111
123
  meta: TMeta | undefined;
124
+ /** Aborts when the client cancels the request or disconnects. */
112
125
  signal: AbortSignal | undefined;
113
126
  /**
114
127
  * The index of this call in a batch request.
115
128
  */
116
129
  batchIndex: number;
130
+ /**
131
+ * Runs the next middleware, or the resolver. Pass `ctx` to add to the
132
+ * context, or `input` to replace the input.
133
+ */
117
134
  next: {
118
135
  (): Promise<MiddlewareResult<TContextOverridesIn>>;
119
136
  <$ContextOverride>(opts: {
@@ -128,7 +145,9 @@ export type MiddlewareFunction<
128
145
  _type?: string | undefined;
129
146
  };
130
147
 
148
+ /** Any middleware function, for use in generic constraints. */
131
149
  export type AnyMiddlewareFunction = MiddlewareFunction<any, any, any, any, any>;
150
+ /** Any middleware builder, for use in generic constraints. */
132
151
  export type AnyMiddlewareBuilder = MiddlewareBuilder<any, any, any, any>;
133
152
  /**
134
153
  * @internal
@@ -170,9 +189,10 @@ export function createMiddlewareFactory<
170
189
  }
171
190
 
172
191
  /**
173
- * Create a standalone middleware
174
- * @see https://trpc.io/docs/v11/server/middlewares#experimental-standalone-middlewares
175
- * @deprecated use `.concat()` instead
192
+ * Creates a middleware that isn't tied to a root object, for the context,
193
+ * metadata and input types you give it.
194
+ * @deprecated Use `.concat()` with a procedure builder instead.
195
+ * @see https://trpc.io/docs/server/middlewares#concat
176
196
  */
177
197
  export const experimental_standaloneMiddleware = <
178
198
  TCtx extends {
@@ -5,6 +5,7 @@ import type { inferAsyncIterableYield } from './types';
5
5
 
6
6
  export const procedureTypes = ['query', 'mutation', 'subscription'] as const;
7
7
  /**
8
+ * A procedure's kind: `'query'`, `'mutation'` or `'subscription'`.
8
9
  * @public
9
10
  */
10
11
  export type ProcedureType = (typeof procedureTypes)[number];
@@ -17,7 +18,7 @@ interface BuiltProcedureDef {
17
18
  }
18
19
 
19
20
  /**
20
- *
21
+ * A built procedure, as a router holds it.
21
22
  * @internal
22
23
  */
23
24
  export interface Procedure<
@@ -54,20 +55,24 @@ export interface Procedure<
54
55
  (opts: ProcedureCallOptions<unknown>): Promise<TDef['output']>;
55
56
  }
56
57
 
58
+ /** A built query procedure. */
57
59
  export interface QueryProcedure<
58
60
  TDef extends BuiltProcedureDef,
59
61
  > extends Procedure<'query', TDef> {}
60
62
 
63
+ /** A built mutation procedure. */
61
64
  export interface MutationProcedure<
62
65
  TDef extends BuiltProcedureDef,
63
66
  > extends Procedure<'mutation', TDef> {}
64
67
 
68
+ /** A built subscription procedure. */
65
69
  export interface SubscriptionProcedure<
66
70
  TDef extends BuiltProcedureDef,
67
71
  > extends Procedure<'subscription', TDef> {}
68
72
 
69
73
  /**
70
- * @deprecated
74
+ * A subscription procedure that returns an observable.
75
+ * @deprecated Return an async generator from `.subscription()` instead.
71
76
  */
72
77
  export interface LegacyObservableSubscriptionProcedure<
73
78
  TDef extends BuiltProcedureDef,
@@ -75,32 +80,53 @@ export interface LegacyObservableSubscriptionProcedure<
75
80
  _observable: true;
76
81
  }
77
82
 
83
+ /** Any query procedure, for use in generic constraints. */
78
84
  export type AnyQueryProcedure = QueryProcedure<any>;
85
+ /** Any mutation procedure, for use in generic constraints. */
79
86
  export type AnyMutationProcedure = MutationProcedure<any>;
87
+ /** Any subscription procedure, for use in generic constraints. */
80
88
  export type AnySubscriptionProcedure =
81
89
  | SubscriptionProcedure<any>
82
90
  | LegacyObservableSubscriptionProcedure<any>;
83
91
 
92
+ /** Any procedure, for use in generic constraints. */
84
93
  export type AnyProcedure =
85
94
  | AnyQueryProcedure
86
95
  | AnyMutationProcedure
87
96
  | AnySubscriptionProcedure;
88
97
 
98
+ /**
99
+ * The input type a procedure takes, before its validators run.
100
+ * @see https://trpc.io/docs/client/vanilla/infer-types#inferring-individual-procedure-types
101
+ */
89
102
  export type inferProcedureInput<TProcedure extends AnyProcedure> =
90
103
  undefined extends inferProcedureParams<TProcedure>['$types']['input']
91
104
  ? void | inferProcedureParams<TProcedure>['$types']['input']
92
105
  : inferProcedureParams<TProcedure>['$types']['input'];
93
106
 
107
+ /** @internal */
94
108
  export type inferProcedureParams<TProcedure> = TProcedure extends AnyProcedure
95
109
  ? TProcedure['_def']
96
110
  : never;
111
+ /**
112
+ * The output type a procedure returns, after its output validator runs.
113
+ * @see https://trpc.io/docs/client/vanilla/infer-types#inferring-individual-procedure-types
114
+ */
97
115
  export type inferProcedureOutput<TProcedure> =
98
116
  inferProcedureParams<TProcedure>['$types']['output'];
99
117
 
118
+ /**
119
+ * The input type a subscription procedure takes.
120
+ * @see https://trpc.io/docs/client/vanilla/infer-types#inferring-individual-procedure-types
121
+ */
100
122
  export type inferSubscriptionInput<
101
123
  TProcedure extends AnySubscriptionProcedure,
102
124
  > = inferProcedureInput<TProcedure>;
103
125
 
126
+ /**
127
+ * The type of each event a subscription procedure emits.
128
+ * @see https://trpc.io/docs/client/vanilla/infer-types#inferring-individual-procedure-types
129
+ */
104
130
  export type inferSubscriptionOutput<
105
131
  TProcedure extends AnySubscriptionProcedure,
106
132
  > =
@@ -102,7 +102,8 @@ type ProcedureBuilderDef<TMeta> = {
102
102
  type AnyProcedureBuilderDef = ProcedureBuilderDef<any>;
103
103
 
104
104
  /**
105
- * Procedure resolver options (what the `.query()`, `.mutation()`, and `.subscription()` functions receive)
105
+ * What a resolver passed to `.query()`, `.mutation()` or `.subscription()`
106
+ * gets.
106
107
  * @internal
107
108
  */
108
109
  export interface ProcedureResolverOptions<
@@ -111,19 +112,24 @@ export interface ProcedureResolverOptions<
111
112
  TContextOverridesIn,
112
113
  TInputOut,
113
114
  > {
115
+ /** The context, after middlewares have added to or changed it. */
114
116
  ctx: Simplify<Overwrite<TContext, TContextOverridesIn>>;
117
+ /**
118
+ * The input, after the validators and any middleware that replaced it
119
+ * with `next({ input })`.
120
+ */
115
121
  input: TInputOut extends UnsetMarker ? undefined : TInputOut;
116
122
  /**
117
- * The AbortSignal of the request
123
+ * Aborts when the client cancels the request or disconnects.
118
124
  */
119
125
  signal: AbortSignal | undefined;
120
126
  /**
121
- * The path of the procedure
127
+ * The procedure's path, such as `post.byId`.
122
128
  */
123
129
  path: string;
124
130
  /**
125
- * The index of this call in a batch request.
126
- * Will be set when the procedure is called as part of a batch.
131
+ * The call's zero-based index in its batch. A call that wasn't batched
132
+ * gets `0`.
127
133
  */
128
134
  batchIndex?: number;
129
135
  }
@@ -159,8 +165,9 @@ export type AnyProcedureBuilder = ProcedureBuilder<
159
165
  >;
160
166
 
161
167
  /**
162
- * Infer the context type from a procedure builder
163
- * Useful to create common helper functions for different procedures
168
+ * The options a resolver built from this procedure builder gets: its
169
+ * `ctx`, `input` and so on. Use it to type helpers that resolvers call.
170
+ * @see https://trpc.io/docs/server/procedures#inferProcedureBuilderResolverOptions
164
171
  */
165
172
  export type inferProcedureBuilderResolverOptions<
166
173
  TProcedureBuilder extends AnyProcedureBuilder,
@@ -196,6 +203,11 @@ export type inferProcedureBuilderResolverOptions<
196
203
  >
197
204
  : never;
198
205
 
206
+ /**
207
+ * Builds a procedure step by step. Each method returns a new builder, so a
208
+ * builder can be the base of many procedures.
209
+ * @see https://trpc.io/docs/server/procedures
210
+ */
199
211
  export interface ProcedureBuilder<
200
212
  TContext,
201
213
  TMeta,
@@ -214,8 +226,8 @@ export interface ProcedureBuilder<
214
226
  TErrorShape = unknown,
215
227
  > {
216
228
  /**
217
- * Add an input parser to the procedure.
218
- * @see https://trpc.io/docs/v11/server/validators
229
+ * Adds a validator for the input. Chain several to merge object inputs.
230
+ * @see https://trpc.io/docs/server/validators#input-validators
219
231
  */
220
232
  input<$Parser extends Parser>(
221
233
  schema: TInputOut extends UnsetMarker
@@ -241,8 +253,9 @@ export interface ProcedureBuilder<
241
253
  TErrorShape
242
254
  >;
243
255
  /**
244
- * Add an output parser to the procedure.
245
- * @see https://trpc.io/docs/v11/server/validators
256
+ * Adds a validator for the output, which checks what the resolver
257
+ * returns.
258
+ * @see https://trpc.io/docs/server/validators#output-validators
246
259
  */
247
260
  output<$Parser extends Parser>(
248
261
  schema: $Parser,
@@ -258,8 +271,9 @@ export interface ProcedureBuilder<
258
271
  TErrorShape
259
272
  >;
260
273
  /**
261
- * Add a meta data to the procedure.
262
- * @see https://trpc.io/docs/v11/server/metadata
274
+ * Sets the procedure's metadata, which middlewares can read. It's
275
+ * shallow-merged with any metadata set before.
276
+ * @see https://trpc.io/docs/server/metadata
263
277
  */
264
278
  meta(
265
279
  meta: TMeta,
@@ -275,12 +289,12 @@ export interface ProcedureBuilder<
275
289
  TErrorShape
276
290
  >;
277
291
  /**
278
- * Add per procedure error formatters.
279
- *
280
- * An error will bubble until a `.errors()` handler returns a shape
281
- * or it reaches the global errorFormatter
282
- *
283
- * @see https://trpc.io/docs/v11/server/error-formatting
292
+ * Adds an error formatter for this procedure. An error goes to the last
293
+ * `.errors()` formatter first, and on to earlier ones and the root
294
+ * `errorFormatter` until one returns a shape. A formatter only sees
295
+ * errors from the steps after it, so put `.errors()` before `.input()`
296
+ * to format input errors.
297
+ * @see https://trpc.io/docs/server/error-formatting#per-procedure-error-formatting
284
298
  */
285
299
  errors<$Shape extends TRPCErrorShape | undefined | void>(
286
300
  formatter: ProcedureErrorFormatter<TContext, TContextOverrides, $Shape>,
@@ -296,8 +310,9 @@ export interface ProcedureBuilder<
296
310
  FoldErrorShape<TErrorShape, $Shape>
297
311
  >;
298
312
  /**
299
- * Add a middleware to the procedure.
300
- * @see https://trpc.io/docs/v11/server/middlewares
313
+ * Adds a middleware, which runs before the resolver and can change the
314
+ * context.
315
+ * @see https://trpc.io/docs/server/middlewares
301
316
  */
302
317
  use<$ContextOverridesOut>(
303
318
  fn:
@@ -327,7 +342,7 @@ export interface ProcedureBuilder<
327
342
  >;
328
343
 
329
344
  /**
330
- * @deprecated use {@link concat} instead
345
+ * @deprecated Use {@link concat} instead.
331
346
  */
332
347
  unstable_concat<
333
348
  $Context,
@@ -367,7 +382,9 @@ export interface ProcedureBuilder<
367
382
  >;
368
383
 
369
384
  /**
370
- * Combine two procedure builders
385
+ * Adds another procedure builder's inputs, middlewares and context to
386
+ * this one. Useful for plugins that ship their own procedure builder.
387
+ * @see https://trpc.io/docs/server/middlewares#concat
371
388
  */
372
389
  concat<
373
390
  $Context,
@@ -406,8 +423,8 @@ export interface ProcedureBuilder<
406
423
  FoldErrorShape<TErrorShape, $ErrorShape>
407
424
  >;
408
425
  /**
409
- * Query procedure
410
- * @see https://trpc.io/docs/v11/concepts#vocabulary
426
+ * Ends the builder with a query: a procedure that reads data.
427
+ * @see https://trpc.io/docs/server/procedures#writing-procedures
411
428
  */
412
429
  query<$Output>(
413
430
  resolver: ProcedureResolver<
@@ -430,8 +447,8 @@ export interface ProcedureBuilder<
430
447
  }>;
431
448
 
432
449
  /**
433
- * Mutation procedure
434
- * @see https://trpc.io/docs/v11/concepts#vocabulary
450
+ * Ends the builder with a mutation: a procedure that changes data.
451
+ * @see https://trpc.io/docs/server/procedures#writing-procedures
435
452
  */
436
453
  mutation<$Output>(
437
454
  resolver: ProcedureResolver<
@@ -454,8 +471,9 @@ export interface ProcedureBuilder<
454
471
  }>;
455
472
 
456
473
  /**
457
- * Subscription procedure
458
- * @see https://trpc.io/docs/v11/server/subscriptions
474
+ * Ends the builder with a subscription: a procedure that streams events
475
+ * from an async iterable, such as an async generator.
476
+ * @see https://trpc.io/docs/server/subscriptions
459
477
  */
460
478
  subscription<$Output extends AsyncIterable<any, void, any>>(
461
479
  resolver: ProcedureResolver<
@@ -475,9 +493,10 @@ export interface ProcedureBuilder<
475
493
  errorShape: TErrorShape;
476
494
  }>;
477
495
  /**
478
- * @deprecated Using subscriptions with an observable is deprecated. Use an async generator instead.
479
- * This feature will be removed in v12 of tRPC.
480
- * @see https://trpc.io/docs/v11/server/subscriptions
496
+ * Ends the builder with a subscription that returns an observable.
497
+ * @deprecated Return an async generator instead. Observable subscriptions
498
+ * will be removed in v12.
499
+ * @see https://trpc.io/docs/server/subscriptions
481
500
  */
482
501
  subscription<$Output extends Observable<any, any>>(
483
502
  resolver: ProcedureResolver<
@@ -497,8 +516,9 @@ export interface ProcedureBuilder<
497
516
  errorShape: TErrorShape;
498
517
  }>;
499
518
  /**
500
- * Overrides the way a procedure is invoked
501
- * Do not use this unless you know what you're doing - this is an experimental API
519
+ * Replaces how the procedure is called, for example to make it a server
520
+ * action. Experimental: it may change in any release.
521
+ * @see https://trpc.io/docs/client/nextjs/server-actions#1-define-a-base-procedure-with-experimental_caller
502
522
  */
503
523
  experimental_caller(
504
524
  caller: CallerOverride<TContext>,
@@ -677,6 +697,7 @@ function createResolver(
677
697
  }
678
698
 
679
699
  /**
700
+ * What calling a procedure takes.
680
701
  * @internal
681
702
  */
682
703
  export interface ProcedureCallOptions<TContext> {
@@ -694,7 +715,7 @@ export interface ProcedureCallOptions<TContext> {
694
715
 
695
716
  const codeblock = `
696
717
  This is a client-only function.
697
- If you want to call this function on the server, see https://trpc.io/docs/v11/server/server-side-calls
718
+ If you want to call this function on the server, see https://trpc.io/docs/server/server-side-calls
698
719
  `.trim();
699
720
 
700
721
  // run the middlewares recursively with the resolver as the last one
@@ -56,7 +56,8 @@ export function isDevDefault(): boolean {
56
56
  }
57
57
 
58
58
  /**
59
- * The tRPC root config
59
+ * The config of a tRPC root object, with the defaults filled in.
60
+ * @see https://trpc.io/docs/server/routers#runtime-configuration
60
61
  * @internal
61
62
  */
62
63
  export interface RootConfig<TTypes extends RootTypes> {
@@ -66,43 +67,45 @@ export interface RootConfig<TTypes extends RootTypes> {
66
67
  */
67
68
  $types: TTypes;
68
69
  /**
69
- * Use a data transformer
70
- * @see https://trpc.io/docs/v11/data-transformers
70
+ * Serializes inputs and outputs, so they can carry types JSON can't.
71
+ * @see https://trpc.io/docs/server/data-transformers
71
72
  */
72
73
  transformer: CombinedDataTransformer;
73
74
  /**
74
- * Use custom error formatting
75
- * @see https://trpc.io/docs/v11/error-formatting
75
+ * Shapes the errors sent to the client.
76
+ * @see https://trpc.io/docs/server/error-formatting
76
77
  */
77
78
  errorFormatter: ErrorFormatter<TTypes['ctx'], TTypes['errorShape']>;
78
79
  /**
79
- * Allow `@trpc/server` to run in non-server environments
80
- * @warning **Use with caution**, this should likely mainly be used within testing.
80
+ * Lets `@trpc/server` run outside a server, such as in a browser. Meant
81
+ * for tests.
81
82
  * @default false
82
83
  */
83
84
  allowOutsideOfServer: boolean;
84
85
  /**
85
- * Is this a server environment?
86
- * @warning **Use with caution**, this should likely mainly be used within testing.
86
+ * Whether this is a server. Meant for tests.
87
87
  * @default typeof window === 'undefined' || 'Deno' in window || process.env.NODE_ENV === 'test'
88
88
  */
89
89
  isServer: boolean;
90
90
  /**
91
- * Is this development?
92
- * Will be used to decide if the API should return stack traces
91
+ * Whether this is development. Errors include stack traces when it is.
93
92
  * @default process.env.NODE_ENV !== 'production'
94
93
  */
95
94
  isDev: boolean;
96
95
 
96
+ /**
97
+ * The metadata every procedure starts with.
98
+ * @see https://trpc.io/docs/server/metadata#default-meta-chaining-and-shallow-merging
99
+ */
97
100
  defaultMeta?: TTypes['meta'] extends object ? TTypes['meta'] : never;
98
101
 
99
102
  /**
100
- * Options for server-sent events (SSE) subscriptions
101
- * @see https://trpc.io/docs/client/links/httpSubscriptionLink
103
+ * Options for subscriptions over server-sent events (SSE).
104
+ * @see https://trpc.io/docs/client/links/httpSubscriptionLink#sse-options-on-the-server
102
105
  */
103
106
  sse?: {
104
107
  /**
105
- * Enable server-sent events (SSE) subscriptions
108
+ * Whether subscriptions can be served over SSE.
106
109
  * @default true
107
110
  */
108
111
  enabled?: boolean;
@@ -112,18 +115,23 @@ export interface RootConfig<TTypes extends RootTypes> {
112
115
  >;
113
116
 
114
117
  /**
115
- * Options for batch stream
116
- * @see https://trpc.io/docs/client/links/httpBatchStreamLink
118
+ * Options for streamed batch responses, which `httpBatchStreamLink`
119
+ * reads.
120
+ * @see https://trpc.io/docs/client/links/httpBatchStreamLink#configure-jsonl-streaming-options
117
121
  */
118
122
  jsonl?: JSONLConfig;
123
+ /** Experimental options. None right now. */
119
124
  experimental?: {};
120
125
  }
121
126
 
122
127
  /**
128
+ * The root types: context, metadata, error shape and whether there's a
129
+ * transformer.
123
130
  * @internal
124
131
  */
125
132
  export type CreateRootTypes<TGenerics extends RootTypes> = TGenerics;
126
133
 
134
+ /** Any root types, for use in generic constraints. */
127
135
  export type AnyRootTypes = CreateRootTypes<{
128
136
  ctx: any;
129
137
  meta: any;
@@ -136,8 +144,8 @@ type PartialIf<TCondition extends boolean, TType> = TCondition extends true
136
144
  : TType;
137
145
 
138
146
  /**
139
- * Adds a `createContext` option with a given callback function
140
- * If context is the default value, then the `createContext` option is optional
147
+ * Adds a `createContext` option to an adapter's options. It's optional
148
+ * when the context is an empty object.
141
149
  */
142
150
  export type CreateContextCallback<
143
151
  TContext,
@@ -146,7 +154,8 @@ export type CreateContextCallback<
146
154
  object extends TContext ? true : false,
147
155
  {
148
156
  /**
149
- * @see https://trpc.io/docs/v11/context
157
+ * Creates the context for each request.
158
+ * @see https://trpc.io/docs/server/context#creating-the-context
150
159
  **/
151
160
  createContext: TFunction;
152
161
  }