@trpc/server 11.23.0 → 11.23.1-canary.14.507382d73

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 +13 -4
  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
@@ -26,41 +26,39 @@ import type {
26
26
  MaybePromise,
27
27
  } from '../../unstable-core-do-not-import';
28
28
 
29
+ /** A Node.js HTTP/1 or HTTP/2 request, as the Node.js adapters take it. */
29
30
  export type NodeHTTPRequest = DistributiveOmit<
30
31
  http.IncomingMessage | http2.Http2ServerRequest,
31
32
  'socket'
32
33
  > & {
33
34
  /**
34
- * Many adapters will add a `body` property to the incoming message and pre-parse the body
35
+ * The body, if a framework or middleware parsed it already. tRPC reads
36
+ * it instead of the stream.
35
37
  */
36
38
  body?: unknown;
37
39
  /**
38
- * Socket is not always available in all deployments, so we need to make it optional
39
- * @see https://github.com/trpc/trpc/issues/6341
40
- * The socket object provided in the request does not fully implement the expected Node.js Socket interface.
41
- * @see https://github.com/trpc/trpc/pull/6358
40
+ * Optional, and maybe partial: some hosts don't give a full Node.js
41
+ * socket (https://github.com/trpc/trpc/issues/6341).
42
42
  */
43
43
  socket?:
44
44
  | Partial<http.IncomingMessage['socket']>
45
45
  | Partial<http2.Http2ServerRequest['socket']>;
46
46
  };
47
47
 
48
+ /** A Node.js HTTP/1 or HTTP/2 response, as the Node.js adapters take it. */
48
49
  export type NodeHTTPResponse = DistributiveOmit<
49
50
  http.ServerResponse | http2.Http2ServerResponse,
50
51
  'write'
51
52
  > & {
52
53
  /**
53
- * Force the partially-compressed response to be flushed to the client.
54
- *
55
- * Added by compression middleware
56
- * (depending on the environment,
57
- * e.g. Next 12 and below,
58
- * e.g. Express w/ `compression()`)
54
+ * Sends what a compression middleware (such as Express's `compression()`)
55
+ * has buffered so far. tRPC calls it while streaming.
59
56
  */
60
57
  flush?: () => void;
61
58
 
62
59
  write: (chunk: string | Uint8Array) => boolean;
63
60
  };
61
+ /** The Node.js adapters' `createContext` option. */
64
62
  export type NodeHTTPCreateContextOption<
65
63
  TRouter extends AnyRouter,
66
64
  TRequest,
@@ -82,31 +80,32 @@ type ConnectMiddleware<
82
80
  // `opts` into an object literal merges the new properties into the trailing
83
81
  // non-generic member, which makes `{ ...opts, req, res, path }` unassignable
84
82
  // to `NodeHTTPRequestHandlerOptions` (https://github.com/trpc/trpc/issues/6057)
83
+ /** The options of the Node.js adapters. */
85
84
  export type NodeHTTPHandlerOptions<
86
85
  TRouter extends AnyRouter,
87
86
  TRequest extends NodeHTTPRequest,
88
87
  TResponse extends NodeHTTPResponse,
89
88
  > = HTTPBaseHandlerOptions<TRouter, TRequest> & {
90
89
  /**
91
- * By default, http `OPTIONS` requests are not handled, and CORS headers are not returned.
92
- *
93
- * This can be used to handle them manually or via the `cors` npm package: https://www.npmjs.com/package/cors
94
- *
90
+ * A Connect-style middleware that runs before tRPC. tRPC doesn't answer
91
+ * `OPTIONS` requests or set CORS headers, so use this for `cors()`.
92
+ * @example
95
93
  * ```ts
96
- * import cors from 'cors'
97
- *
98
- * nodeHTTPRequestHandler({
99
- * middleware: cors()
100
- * })
94
+ * createHTTPServer({ middleware: cors(), router: appRouter });
101
95
  * ```
102
- *
103
- * You can also use it for other needs which a connect/node.js compatible middleware can solve,
104
- * though you might wish to consider an alternative solution like the Express adapter if your needs are complex.
96
+ * @see https://trpc.io/docs/server/adapters/standalone#handling-cors--options
105
97
  */
106
98
  middleware?: ConnectMiddleware<TRequest, TResponse>;
99
+ /**
100
+ * The largest request body, in bytes. A larger one gets a
101
+ * `PAYLOAD_TOO_LARGE` error. It only applies to bodies tRPC reads from
102
+ * the stream; if a body-parsing middleware sets `req.body`, limit the
103
+ * size there.
104
+ */
107
105
  maxBodySize?: number;
108
106
  } & NodeHTTPCreateContextOption<TRouter, TRequest, TResponse>;
109
107
 
108
+ /** The options of `nodeHTTPRequestHandler`. */
110
109
  export type NodeHTTPRequestHandlerOptions<
111
110
  TRouter extends AnyRouter,
112
111
  TRequest extends NodeHTTPRequest,
@@ -115,17 +114,23 @@ export type NodeHTTPRequestHandlerOptions<
115
114
  req: TRequest;
116
115
  res: TResponse;
117
116
  /**
118
- * The tRPC path to handle requests for
119
- * @example 'post.all'
117
+ * The procedure path to handle, such as `post.all`, or several joined by
118
+ * commas for a batch.
120
119
  */
121
120
  path: string;
122
121
  };
123
122
 
123
+ /**
124
+ * What `createContext` gets in the Node.js adapters: `req`, `res` and the
125
+ * request's `info`.
126
+ * @see https://trpc.io/docs/server/context#creating-the-context
127
+ */
124
128
  export type NodeHTTPCreateContextFnOptions<TRequest, TResponse> = {
125
129
  req: TRequest;
126
130
  res: TResponse;
127
131
  info: TRPCRequestInfo;
128
132
  };
133
+ /** The `createContext` function the Node.js adapters take. */
129
134
  export type NodeHTTPCreateContextFn<
130
135
  TRouter extends AnyRouter,
131
136
  TRequest,
@@ -41,19 +41,24 @@ type StandaloneHandlerOptions<
41
41
  TResponse extends NodeHTTPResponse,
42
42
  > = NodeHTTPHandlerOptions<TRouter, TRequest, TResponse> & {
43
43
  /**
44
- * The base path to handle requests for.
45
- * This will be sliced from the beginning of the request path
44
+ * The path the router is served at, such as `/trpc/`. It's cut from the
45
+ * start of each request's path.
46
46
  * @default '/'
47
- * @example '/trpc/'
48
- * @example '/trpc/api/'
47
+ * @see https://trpc.io/docs/server/adapters/standalone#custom-basePath
49
48
  */
50
49
  basePath?: string;
51
50
  };
52
51
 
53
52
  // --- http1 ---
53
+ /** The options of `createHTTPServer` and `createHTTPHandler`. */
54
54
  export type CreateHTTPHandlerOptions<TRouter extends AnyRouter> =
55
55
  StandaloneHandlerOptions<TRouter, http.IncomingMessage, http.ServerResponse>;
56
56
 
57
+ /**
58
+ * What `createContext` gets in the standalone adapter: `req`, `res` and
59
+ * the request's `info`.
60
+ * @see https://trpc.io/docs/server/adapters/standalone#2-use-the-standalone-adapter
61
+ */
57
62
  export type CreateHTTPContextOptions = NodeHTTPCreateContextFnOptions<
58
63
  http.IncomingMessage,
59
64
  http.ServerResponse
@@ -95,6 +100,9 @@ function createHandler<
95
100
  }
96
101
 
97
102
  /**
103
+ * Creates a Node.js request listener for a router, to use with your own
104
+ * `http.createServer()`.
105
+ * @see https://trpc.io/docs/server/adapters/standalone#adding-a-handler-to-a-custom-http-server
98
106
  * @internal
99
107
  */
100
108
  export function createHTTPHandler<TRouter extends AnyRouter>(
@@ -103,6 +111,14 @@ export function createHTTPHandler<TRouter extends AnyRouter>(
103
111
  return createHandler(opts);
104
112
  }
105
113
 
114
+ /**
115
+ * Creates a Node.js HTTP server for a router. Call `.listen()` on it.
116
+ * @example
117
+ * ```ts
118
+ * createHTTPServer({ router: appRouter, createContext }).listen(3000);
119
+ * ```
120
+ * @see https://trpc.io/docs/server/adapters/standalone#2-use-the-standalone-adapter
121
+ */
106
122
  export function createHTTPServer<TRouter extends AnyRouter>(
107
123
  opts: CreateHTTPHandlerOptions<TRouter>,
108
124
  ) {
@@ -110,6 +126,7 @@ export function createHTTPServer<TRouter extends AnyRouter>(
110
126
  }
111
127
 
112
128
  // --- http2 ---
129
+ /** The options of `createHTTP2Handler`. */
113
130
  export type CreateHTTP2HandlerOptions<TRouter extends AnyRouter> =
114
131
  StandaloneHandlerOptions<
115
132
  TRouter,
@@ -117,11 +134,20 @@ export type CreateHTTP2HandlerOptions<TRouter extends AnyRouter> =
117
134
  http2.Http2ServerResponse
118
135
  >;
119
136
 
137
+ /**
138
+ * What `createContext` gets in the HTTP/2 standalone adapter.
139
+ * @see https://trpc.io/docs/server/adapters/standalone#http2
140
+ */
120
141
  export type CreateHTTP2ContextOptions = NodeHTTPCreateContextFnOptions<
121
142
  http2.Http2ServerRequest,
122
143
  http2.Http2ServerResponse
123
144
  >;
124
145
 
146
+ /**
147
+ * Creates a request listener for a router, to use with Node.js's
148
+ * `http2.createSecureServer()`.
149
+ * @see https://trpc.io/docs/server/adapters/standalone#http2
150
+ */
125
151
  export function createHTTP2Handler(opts: CreateHTTP2HandlerOptions<AnyRouter>) {
126
152
  return createHandler(opts);
127
153
  }
@@ -49,6 +49,10 @@ import { jsonEncoder } from './wsEncoder';
49
49
  const WEBSOCKET_OPEN = 1; /* ws.WebSocket.OPEN */
50
50
 
51
51
  /**
52
+ * What `createContext` gets in the WebSocket adapter: the upgrade request
53
+ * as `req`, the socket as `res`, and `info`. It's called once per
54
+ * connection.
55
+ * @see https://trpc.io/docs/server/websockets#creating-a-websocket-server
52
56
  * @public
53
57
  */
54
58
  export type CreateWSSContextFnOptions = NodeHTTPCreateContextFnOptions<
@@ -57,12 +61,14 @@ export type CreateWSSContextFnOptions = NodeHTTPCreateContextFnOptions<
57
61
  >;
58
62
 
59
63
  /**
64
+ * The `createContext` function the WebSocket adapter takes.
60
65
  * @public
61
66
  */
62
67
  export type CreateWSSContextFn<TRouter extends AnyRouter> = (
63
68
  opts: CreateWSSContextFnOptions,
64
69
  ) => MaybePromise<inferRouterContext<TRouter>>;
65
70
 
71
+ /** The options of `getWSConnectionHandler`. */
66
72
  export type WSConnectionHandlerOptions<TRouter extends AnyRouter> =
67
73
  BaseHandlerOptions<TRouter, IncomingMessage> &
68
74
  CreateContextCallback<
@@ -71,42 +77,54 @@ export type WSConnectionHandlerOptions<TRouter extends AnyRouter> =
71
77
  >;
72
78
 
73
79
  /**
74
- * Web socket server handler
80
+ * The options of `applyWSSHandler`.
81
+ * @see https://trpc.io/docs/server/websockets#creating-a-websocket-server
75
82
  */
76
83
  export type WSSHandlerOptions<TRouter extends AnyRouter> =
77
84
  WSConnectionHandlerOptions<TRouter> & {
85
+ /** The `ws` server to serve the router on. */
78
86
  wss: WebSocketServer;
87
+ /** Only connections whose URL starts with this are served. */
79
88
  prefix?: string;
89
+ /**
90
+ * Sends pings to each client and closes connections that stop
91
+ * answering.
92
+ */
80
93
  keepAlive?: {
81
94
  /**
82
- * Enable heartbeat messages
95
+ * Whether to send pings.
83
96
  * @default false
84
97
  */
85
98
  enabled: boolean;
86
99
  /**
87
- * Heartbeat interval in milliseconds
100
+ * How long a connection can be quiet before a ping, in milliseconds.
88
101
  * @default 30_000
89
102
  */
90
103
  pingMs?: number;
91
104
  /**
92
- * Terminate the WebSocket if no pong is received after this many milliseconds
105
+ * How long to wait for a pong before closing the connection, in
106
+ * milliseconds.
93
107
  * @default 5_000
94
108
  */
95
109
  pongWaitMs?: number;
96
110
  };
97
111
  /**
98
- * Disable responding to ping messages from the client
99
- * **Not recommended** - this is mainly used for testing
112
+ * Stops answering clients' pings. Meant for tests.
100
113
  * @default false
101
114
  */
102
115
  dangerouslyDisablePong?: boolean;
103
116
  /**
104
- * Custom encoder for wire encoding (e.g. custom binary formats)
117
+ * Encodes and decodes messages, for formats other than JSON.
118
+ * Experimental: it may change in any release.
105
119
  * @default jsonEncoder
106
120
  */
107
121
  experimental_encoder?: Encoder;
108
122
  };
109
123
 
124
+ /**
125
+ * Returns a `ws` connection listener that serves a router. `applyWSSHandler`
126
+ * uses it; call it to attach tRPC to your own WebSocket server.
127
+ */
110
128
  export function getWSConnectionHandler<TRouter extends AnyRouter>(
111
129
  opts: WSSHandlerOptions<TRouter>,
112
130
  ) {
@@ -572,7 +590,8 @@ export function getWSConnectionHandler<TRouter extends AnyRouter>(
572
590
  }
573
591
 
574
592
  /**
575
- * Handle WebSocket keep-alive messages
593
+ * Pings a client after `pingMs` of quiet, and closes the connection if no
594
+ * message comes within `pongWaitMs`.
576
595
  */
577
596
  export function handleKeepAlive(
578
597
  client: WsWebSocket,
@@ -612,6 +631,21 @@ export function handleKeepAlive(
612
631
  schedulePing();
613
632
  }
614
633
 
634
+ /**
635
+ * Serves a router on a `ws` WebSocket server. Returns
636
+ * `broadcastReconnectNotification()`, which tells every client to
637
+ * reconnect, for example before a deploy.
638
+ * @example
639
+ * ```ts
640
+ * const wss = new WebSocketServer({ port: 3001 });
641
+ * const handler = applyWSSHandler({ wss, router: appRouter, createContext });
642
+ * process.on('SIGTERM', () => {
643
+ * handler.broadcastReconnectNotification();
644
+ * wss.close();
645
+ * });
646
+ * ```
647
+ * @see https://trpc.io/docs/server/websockets#creating-a-websocket-server
648
+ */
615
649
  export function applyWSSHandler<TRouter extends AnyRouter>(
616
650
  opts: WSSHandlerOptions<TRouter>,
617
651
  ) {
@@ -1,6 +1,6 @@
1
1
  /**
2
- * Encoder for WebSocket wire format.
3
- * Encodes outgoing messages and decodes incoming messages.
2
+ * Encodes the messages a WebSocket server sends and decodes the ones it
3
+ * gets. The client's `experimental_encoder` must match.
4
4
  *
5
5
  * @example
6
6
  * ```ts
@@ -11,15 +11,14 @@
11
11
  * ```
12
12
  */
13
13
  export interface Encoder {
14
- /** Encode data for transmission over the wire */
14
+ /** Encodes a message to send. */
15
15
  encode(data: unknown): string | Uint8Array<ArrayBuffer>;
16
- /** Decode data received from the wire */
16
+ /** Decodes a received message. */
17
17
  decode(data: string | ArrayBuffer | Uint8Array): unknown;
18
18
  }
19
19
 
20
20
  /**
21
- * Default JSON encoder - used when no encoder is specified.
22
- * This maintains backwards compatibility with existing behavior.
21
+ * The default encoder: JSON in text frames.
23
22
  */
24
23
  export const jsonEncoder: Encoder = {
25
24
  encode: (data) => JSON.stringify(data),
@@ -1,21 +1,25 @@
1
1
  import { observable } from './observable';
2
2
  import type { Observable, Observer } from './types';
3
3
 
4
+ /** An observable that holds a current value. */
4
5
  export interface BehaviorSubject<TValue> extends Observable<TValue, never> {
5
6
  observable: Observable<TValue, never>;
7
+ /** Sets the value and sends it to subscribers, if it changed. */
6
8
  next: (value: TValue) => void;
9
+ /** The current value. */
7
10
  get: () => TValue;
8
11
  }
9
12
 
13
+ /** A `BehaviorSubject` that can't be set. */
10
14
  export interface ReadonlyBehaviorSubject<TValue> extends Omit<
11
15
  BehaviorSubject<TValue>,
12
16
  'next'
13
17
  > {}
14
18
 
15
19
  /**
20
+ * Creates an observable that holds a current value. New subscribers get
21
+ * it right away, unless it's `undefined`.
16
22
  * @internal
17
- * An observable that maintains and provides a "current value" to subscribers
18
- * @see https://www.learnrxjs.io/learn-rxjs/subjects/behaviorsubject
19
23
  */
20
24
  export function behaviorSubject<TValue>(
21
25
  initialValue: TValue,
@@ -8,16 +8,34 @@ import type {
8
8
  Unsubscribable,
9
9
  } from './types';
10
10
 
11
- /** @public */
11
+ /**
12
+ * The type of the values an observable emits.
13
+ * @public
14
+ */
12
15
  export type inferObservableValue<TObservable> =
13
16
  TObservable extends Observable<infer TValue, unknown> ? TValue : never;
14
17
 
15
- /** @public */
18
+ /**
19
+ * Whether a value is an observable: an object with `subscribe`.
20
+ * @public
21
+ */
16
22
  export function isObservable(x: unknown): x is Observable<unknown, unknown> {
17
23
  return typeof x === 'object' && x !== null && 'subscribe' in x;
18
24
  }
19
25
 
20
- /** @public */
26
+ /**
27
+ * Creates an observable. `subscribe` runs for each subscriber, and can
28
+ * return a function that cleans up when it unsubscribes.
29
+ * @example
30
+ * ```ts
31
+ * const ticks = observable<number>((observer) => {
32
+ * const timer = setInterval(() => observer.next(Date.now()), 1000);
33
+ * return () => clearInterval(timer);
34
+ * });
35
+ * ```
36
+ * @see https://trpc.io/docs/client/links#creating-a-custom-link
37
+ * @public
38
+ */
21
39
  export function observable<TValue, TError = unknown>(
22
40
  subscribe: (observer: Observer<TValue, TError>) => TeardownLogic,
23
41
  ): Observable<TValue, TError> {
@@ -87,7 +105,11 @@ function pipeReducer(prev: any, fn: UnaryFunction<any, any>) {
87
105
  return fn(prev);
88
106
  }
89
107
 
90
- /** @internal */
108
+ /**
109
+ * Resolves with an observable's first value. Rejects if it errors or
110
+ * completes first. It doesn't unsubscribe after the first value.
111
+ * @internal
112
+ */
91
113
  export function observableToPromise<TValue>(
92
114
  observable: Observable<TValue, unknown>,
93
115
  ) {
@@ -164,7 +186,11 @@ function observableToReadableStream<TValue>(
164
186
  });
165
187
  }
166
188
 
167
- /** @internal */
189
+ /**
190
+ * Turns an observable into an async iterable. Aborting `signal`
191
+ * unsubscribes from the observable but doesn't end a pending `next()`.
192
+ * @internal
193
+ */
168
194
  export function observableToAsyncIterable<TValue>(
169
195
  observable: Observable<TValue, unknown>,
170
196
  signal: AbortSignal,
@@ -6,6 +6,7 @@ import type {
6
6
  Unsubscribable,
7
7
  } from './types';
8
8
 
9
+ /** Maps each value with `project`. */
9
10
  export function map<TValueBefore, TError, TValueAfter>(
10
11
  project: (value: TValueBefore, index: number) => TValueAfter,
11
12
  ): OperatorFunction<TValueBefore, TError, TValueAfter, TError> {
@@ -29,6 +30,10 @@ export function map<TValueBefore, TError, TValueAfter>(
29
30
  }
30
31
 
31
32
  interface ShareConfig {}
33
+ /**
34
+ * Shares one subscription to the source between all subscribers. It
35
+ * starts with the first subscriber and ends when the last unsubscribes.
36
+ */
32
37
  export function share<TValue, TError>(
33
38
  _opts?: ShareConfig,
34
39
  ): MonoTypeOperatorFunction<TValue, TError> {
@@ -131,6 +136,7 @@ export function share<TValue, TError>(
131
136
  };
132
137
  }
133
138
 
139
+ /** Calls `observer` with each value, error and completion, and passes them on unchanged. */
134
140
  export function tap<TValue, TError>(
135
141
  observer: Partial<Observer<TValue, TError>>,
136
142
  ): MonoTypeOperatorFunction<TValue, TError> {
@@ -155,6 +161,7 @@ export function tap<TValue, TError>(
155
161
  }
156
162
 
157
163
  const distinctUnsetMarker = Symbol();
164
+ /** Skips values equal to the one before, by `compare` (`===` by default). */
158
165
  export function distinctUntilChanged<TValue, TError>(
159
166
  compare: (a: TValue, b: TValue) => boolean = (a, b) => a === b,
160
167
  ): MonoTypeOperatorFunction<TValue, TError> {
@@ -194,6 +201,11 @@ const isDeepEqual = <T>(a: T, b: T): boolean => {
194
201
  Object.entries(a).every(([k, v]) => isDeepEqual(v, b[k as keyof T]))
195
202
  );
196
203
  };
204
+ /**
205
+ * Skips values equal to the one before, comparing objects and arrays by
206
+ * their own enumerable keys. Objects without such keys, like two `Date`s,
207
+ * always count as equal.
208
+ */
197
209
  export function distinctUntilDeepChanged<
198
210
  TValue,
199
211
  TError,
@@ -1,14 +1,24 @@
1
+ /** What `subscribe()` returns: call `unsubscribe()` to stop. */
1
2
  export interface Unsubscribable {
3
+ /** Stops the subscription and runs its teardown. */
2
4
  unsubscribe(): void;
3
5
  }
6
+ /** Stops a subscription. */
4
7
  export type UnsubscribeFn = () => void;
5
8
  interface Subscribable<TValue, TError> {
9
+ /** Starts the observable, sending what it emits to `observer`. */
6
10
  subscribe(observer: Partial<Observer<TValue, TError>>): Unsubscribable;
7
11
  }
12
+ /**
13
+ * A stream of values, which starts when you subscribe to it. Links pass
14
+ * results along as observables.
15
+ * @see https://trpc.io/docs/client/links#creating-a-custom-link
16
+ */
8
17
  export interface Observable<TValue, TError> extends Subscribable<
9
18
  TValue,
10
19
  TError
11
20
  > {
21
+ /** Returns an observable with the operators applied, in order. */
12
22
  pipe(): Observable<TValue, TError>;
13
23
  pipe<TValue1, TError1>(
14
24
  op1: OperatorFunction<TValue, TError, TValue1, TError1>,
@@ -48,18 +58,25 @@ export interface Observable<TValue, TError> extends Subscribable<
48
58
  ): Observable<TValue2, TError2>;
49
59
  }
50
60
 
61
+ /** Gets an observable's values, its error, and its end. */
51
62
  export interface Observer<TValue, TError> {
63
+ /** Gets each value. */
52
64
  next: (value: TValue) => void;
65
+ /** Gets the error the observable ends with. */
53
66
  error: (err: TError) => void;
67
+ /** Called when the observable ends without an error. */
54
68
  complete: () => void;
55
69
  }
56
70
 
71
+ /** What the function passed to `observable()` returns to clean up on unsubscribe. */
57
72
  export type TeardownLogic =
58
73
  // | SubscriptionLike
59
74
  Unsubscribable | UnsubscribeFn | void;
60
75
 
76
+ /** A function of one argument. */
61
77
  export type UnaryFunction<TSource, TReturn> = (source: TSource) => TReturn;
62
78
 
79
+ /** Turns one observable into another, for `pipe()`. */
63
80
  export type OperatorFunction<
64
81
  TValueBefore,
65
82
  TErrorBefore,
@@ -70,6 +87,7 @@ export type OperatorFunction<
70
87
  Subscribable<TValueAfter, TErrorAfter>
71
88
  >;
72
89
 
90
+ /** An operator that keeps the value and error types. */
73
91
  export type MonoTypeOperatorFunction<TValue, TError> = OperatorFunction<
74
92
  TValue,
75
93
  TError,
@@ -13,6 +13,8 @@ import type {
13
13
  import type { Serialize } from './serialize';
14
14
 
15
15
  /**
16
+ * A procedure's output as the client gets it: as is with a transformer,
17
+ * or as it comes out of JSON without one.
16
18
  * @internal
17
19
  */
18
20
  export type inferTransformedProcedureOutput<
@@ -23,6 +25,8 @@ export type inferTransformedProcedureOutput<
23
25
  : inferProcedureOutput<TProcedure>;
24
26
 
25
27
  /**
28
+ * The error shapes a procedure's errors can have: the router's shape, plus
29
+ * one for each `.errors()` call.
26
30
  * @internal
27
31
  */
28
32
  export type inferProcedureErrorShape<
@@ -34,7 +38,10 @@ export type inferProcedureErrorShape<
34
38
  : $Shape
35
39
  : never;
36
40
 
37
- /** @internal */
41
+ /**
42
+ * A subscription's events as the client gets them.
43
+ * @internal
44
+ */
38
45
  export type inferTransformedSubscriptionOutput<
39
46
  TInferrable extends InferrableClientTypes,
40
47
  TProcedure extends AnyProcedure,
@@ -42,6 +49,7 @@ export type inferTransformedSubscriptionOutput<
42
49
  ? Serialize<inferObservableValue<inferProcedureOutput<TProcedure>>>
43
50
  : inferObservableValue<inferProcedureOutput<TProcedure>>;
44
51
 
52
+ /** @internal */
45
53
  export type GetInferenceHelpers<
46
54
  TType extends 'input' | 'output',
47
55
  TRoot extends AnyClientTypes,
@@ -58,12 +66,25 @@ export type GetInferenceHelpers<
58
66
  : never;
59
67
  };
60
68
 
69
+ /**
70
+ * The input types of every procedure in a router, by path.
71
+ * @example
72
+ * ```ts
73
+ * type PostByIdInput = inferRouterInputs<AppRouter>['post']['byId'];
74
+ * ```
75
+ * @see https://trpc.io/docs/client/vanilla/infer-types#inferring-input--output-types
76
+ */
61
77
  export type inferRouterInputs<TRouter extends AnyRouter> = GetInferenceHelpers<
62
78
  'input',
63
79
  TRouter['_def']['_config']['$types'],
64
80
  TRouter['_def']['record']
65
81
  >;
66
82
 
83
+ /**
84
+ * The output types of every procedure in a router, by path, as the client
85
+ * gets them.
86
+ * @see https://trpc.io/docs/client/vanilla/infer-types#inferring-input--output-types
87
+ */
67
88
  export type inferRouterOutputs<TRouter extends AnyRouter> = GetInferenceHelpers<
68
89
  'output',
69
90
  TRouter['_def']['_config']['$types'],
@@ -1,5 +1,6 @@
1
1
  import type { AnyRootTypes } from '../rootConfig';
2
2
 
3
+ /** The root types a client needs: the error shape and whether there's a transformer. */
3
4
  export type AnyClientTypes = Pick<AnyRootTypes, 'errorShape' | 'transformer'>;
4
5
 
5
6
  /**
@@ -26,7 +27,8 @@ type RootConfigLike = {
26
27
  };
27
28
 
28
29
  /**
29
- * Anything that can be inferred to the root config types needed for a TRPC client
30
+ * Anything a client's root types can be read from: a router, a root
31
+ * object, a root config or the types themselves.
30
32
  */
31
33
  export type InferrableClientTypes =
32
34
  | RouterLike
@@ -39,7 +41,8 @@ type PickTypes<T extends AnyClientTypes> = {
39
41
  errorShape: T['errorShape'];
40
42
  };
41
43
  /**
42
- * Infer the root types from a InferrableClientTypes
44
+ * The root types a client needs, read from a router, a root object or a
45
+ * root config.
43
46
  */
44
47
  export type inferClientTypes<TInferrable extends InferrableClientTypes> =
45
48
  TInferrable extends AnyClientTypes
@@ -72,8 +72,8 @@ function createInnerProxy(
72
72
  }
73
73
 
74
74
  /**
75
- * Creates a proxy that calls the callback with the path and arguments
76
- *
75
+ * Creates a proxy that records the property path it's accessed with, and
76
+ * calls `callback` with the path and arguments when it's called.
77
77
  * @internal
78
78
  */
79
79
  export const createRecursiveProxy = <TFaux = unknown>(
@@ -81,8 +81,8 @@ export const createRecursiveProxy = <TFaux = unknown>(
81
81
  ): TFaux => createInnerProxy(callback, [], emptyObject()) as TFaux;
82
82
 
83
83
  /**
84
- * Used in place of `new Proxy` where each handler will map 1 level deep to another value.
85
- *
84
+ * Creates a proxy that maps each property to `callback(name)`, one level
85
+ * deep. It's not thenable.
86
86
  * @internal
87
87
  */
88
88
  export const createFlatProxy = <TFaux>(