@trpc/server 11.22.2-canary.9.85bcf328a → 11.23.0

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 (114) hide show
  1. package/README.md +0 -8
  2. package/dist/adapters/aws-lambda/index.cjs +1 -1
  3. package/dist/adapters/aws-lambda/index.d.cts.map +1 -1
  4. package/dist/adapters/aws-lambda/index.d.mts.map +1 -1
  5. package/dist/adapters/aws-lambda/index.mjs +1 -1
  6. package/dist/adapters/aws-lambda/index.mjs.map +1 -1
  7. package/dist/adapters/express.cjs +1 -1
  8. package/dist/adapters/express.mjs +1 -1
  9. package/dist/adapters/express.mjs.map +1 -1
  10. package/dist/adapters/fastify/index.cjs +3 -3
  11. package/dist/adapters/fastify/index.mjs +3 -3
  12. package/dist/adapters/fetch/index.cjs +1 -1
  13. package/dist/adapters/fetch/index.mjs +1 -1
  14. package/dist/adapters/next-app-dir.mjs.map +1 -1
  15. package/dist/adapters/next.cjs +1 -1
  16. package/dist/adapters/next.mjs +1 -1
  17. package/dist/adapters/next.mjs.map +1 -1
  18. package/dist/adapters/node-http/index.cjs +1 -1
  19. package/dist/adapters/node-http/index.mjs +1 -1
  20. package/dist/adapters/standalone.cjs +9 -3
  21. package/dist/adapters/standalone.d.cts +0 -1
  22. package/dist/adapters/standalone.d.cts.map +1 -1
  23. package/dist/adapters/standalone.d.mts +0 -1
  24. package/dist/adapters/standalone.d.mts.map +1 -1
  25. package/dist/adapters/standalone.mjs +9 -3
  26. package/dist/adapters/standalone.mjs.map +1 -1
  27. package/dist/adapters/ws.cjs +1 -1
  28. package/dist/adapters/ws.mjs +1 -1
  29. package/dist/asyncGeneratorDelegate-FcEJT04i.mjs.map +1 -1
  30. package/dist/codes-C9N0z0an.mjs.map +1 -1
  31. package/dist/getErrorShape-zlj81BiC.mjs.map +1 -1
  32. package/dist/http.cjs +1 -1
  33. package/dist/http.mjs +1 -1
  34. package/dist/initTRPC-RMeQIy9H.mjs.map +1 -1
  35. package/dist/{node-http-B5jkpWn7.mjs → node-http-ChhZEv1k.mjs} +2 -2
  36. package/dist/node-http-ChhZEv1k.mjs.map +1 -0
  37. package/dist/{node-http-BZ0HlzkC.cjs → node-http-X8RiQEuH.cjs} +1 -1
  38. package/dist/parseTRPCMessage-CJ4DJVBp.mjs.map +1 -1
  39. package/dist/{resolveResponse-b9D_SrLs.cjs → resolveResponse-CoGjFxK0.cjs} +8 -4
  40. package/dist/{resolveResponse-DH5L33sC.mjs → resolveResponse-DksrxZ2k.mjs} +9 -5
  41. package/dist/resolveResponse-DksrxZ2k.mjs.map +1 -0
  42. package/dist/unstable-core-do-not-import-B8epiErP.d.cts.map +1 -1
  43. package/dist/unstable-core-do-not-import-Dbo98mkh.d.mts.map +1 -1
  44. package/dist/unstable-core-do-not-import.cjs +1 -1
  45. package/dist/unstable-core-do-not-import.mjs +1 -1
  46. package/dist/unstable-core-do-not-import.mjs.map +1 -1
  47. package/dist/{ws-83TNWW-W.cjs → ws-7qWW7Uec.cjs} +2 -2
  48. package/dist/{ws-DJ2SSChC.mjs → ws-BYfo-HED.mjs} +3 -3
  49. package/dist/ws-BYfo-HED.mjs.map +1 -0
  50. package/package.json +9 -12
  51. package/skills/adapter-aws-lambda/SKILL.md +152 -134
  52. package/skills/adapter-express/SKILL.md +127 -113
  53. package/skills/adapter-fastify/SKILL.md +228 -136
  54. package/skills/adapter-fetch/SKILL.md +388 -111
  55. package/skills/adapter-standalone/SKILL.md +184 -94
  56. package/skills/auth/SKILL.md +327 -202
  57. package/skills/auth/references/client-cors.md +29 -0
  58. package/skills/caching/SKILL.md +58 -148
  59. package/skills/error-handling/SKILL.md +280 -174
  60. package/skills/middlewares/SKILL.md +320 -121
  61. package/skills/non-json-content-types/SKILL.md +149 -168
  62. package/skills/server-setup/SKILL.md +355 -253
  63. package/skills/server-setup/references/server-context.md +219 -0
  64. package/skills/server-setup/references/server-merging-routers.md +141 -0
  65. package/skills/server-setup/references/server-metadata.md +105 -0
  66. package/skills/server-setup/references/server-procedures.md +172 -0
  67. package/skills/server-setup/references/server-routers.md +123 -0
  68. package/skills/server-side-calls/SKILL.md +247 -152
  69. package/skills/service-oriented-architecture/SKILL.md +81 -177
  70. package/skills/subscriptions/SKILL.md +341 -297
  71. package/skills/subscriptions/references/client-links-httpSubscriptionLink.md +404 -0
  72. package/skills/subscriptions/references/client-links-wsLink.md +122 -0
  73. package/skills/subscriptions/references/server-websockets.md +297 -0
  74. package/skills/trpc-router/SKILL.md +156 -86
  75. package/skills/validators/SKILL.md +384 -128
  76. package/src/adapters/aws-lambda/getPlanner.ts +4 -3
  77. package/src/adapters/aws-lambda/index.ts +2 -1
  78. package/src/adapters/express.ts +1 -1
  79. package/src/adapters/next-app-dir/nextAppDirCaller.ts +4 -4
  80. package/src/adapters/next-app-dir/rethrowNextErrors.ts +1 -1
  81. package/src/adapters/next.ts +1 -1
  82. package/src/adapters/node-http/incomingMessageToRequest.ts +1 -1
  83. package/src/adapters/node-http/nodeHTTPRequestHandler.ts +1 -1
  84. package/src/adapters/node-http/types.ts +1 -1
  85. package/src/adapters/node-http/writeResponse.ts +1 -1
  86. package/src/adapters/standalone.ts +12 -6
  87. package/src/adapters/ws.ts +5 -5
  88. package/src/unstable-core-do-not-import/clientish/inferrable.ts +4 -1
  89. package/src/unstable-core-do-not-import/clientish/serialize.ts +4 -4
  90. package/src/unstable-core-do-not-import/error/TRPCError.ts +3 -3
  91. package/src/unstable-core-do-not-import/http/formDataToObject.ts +1 -1
  92. package/src/unstable-core-do-not-import/http/getHTTPStatusCode.ts +1 -1
  93. package/src/unstable-core-do-not-import/http/resolveResponse.ts +13 -2
  94. package/src/unstable-core-do-not-import/procedure.ts +5 -2
  95. package/src/unstable-core-do-not-import/procedureBuilder.ts +3 -2
  96. package/src/unstable-core-do-not-import/rootConfig.ts +2 -2
  97. package/src/unstable-core-do-not-import/router.ts +5 -2
  98. package/src/unstable-core-do-not-import/rpc/envelopes.ts +3 -2
  99. package/src/unstable-core-do-not-import/stream/jsonl.ts +2 -1
  100. package/src/unstable-core-do-not-import/stream/sse.types.ts +1 -1
  101. package/src/unstable-core-do-not-import/stream/utils/asyncIterable.ts +1 -1
  102. package/src/unstable-core-do-not-import/stream/utils/createDeferred.ts +1 -1
  103. package/src/unstable-core-do-not-import/stream/utils/disposable.ts +6 -6
  104. package/src/unstable-core-do-not-import/stream/utils/mergeAsyncIterables.ts +2 -2
  105. package/src/unstable-core-do-not-import/stream/utils/withPing.ts +3 -1
  106. package/src/unstable-core-do-not-import/transformer.ts +4 -1
  107. package/src/unstable-core-do-not-import/types.ts +3 -2
  108. package/src/unstable-core-do-not-import/utils.ts +1 -1
  109. package/src/vendor/standard-schema-v1/spec.ts +2 -2
  110. package/src/vendor/unpromise/unpromise.ts +1 -1
  111. package/bin/intent.js +0 -20
  112. package/dist/node-http-B5jkpWn7.mjs.map +0 -1
  113. package/dist/resolveResponse-DH5L33sC.mjs.map +0 -1
  114. package/dist/ws-DJ2SSChC.mjs.map +0 -1
@@ -0,0 +1,29 @@
1
+ # Send cookies cross-origin
2
+
3
+ From https://trpc.io/docs/client/cors
4
+
5
+ If your API resides on a different origin than your front-end and you wish to send cookies to it, you will need to enable [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) on your server and send cookies with your requests by providing the option `{credentials: "include"}` to fetch.
6
+
7
+ The arguments provided to the fetch function used by tRPC can be modified as follows.
8
+
9
+ ```ts no-check title="app.ts"
10
+ import { createTRPCClient, httpBatchLink } from '@trpc/client';
11
+ import type { AppRouter } from './server';
12
+
13
+ const client = createTRPCClient<AppRouter>({
14
+ links: [
15
+ httpBatchLink({
16
+ url: 'YOUR_SERVER_URL',
17
+ fetch(url, options) {
18
+ return fetch(url, {
19
+ ...options,
20
+ credentials: 'include',
21
+ });
22
+ },
23
+ }),
24
+ ],
25
+ });
26
+ ```
27
+
28
+ > [!NOTE] Info
29
+ > You also need to enable CORS on your server by modifying your [adapter](https://trpc.io/docs/server/adapters), or the HTTP server which fronts your API. The best way to do this varies adapter-by-adapter and based on your hosting infrastructure, and individual adapters generally document this process where applicable.
@@ -1,77 +1,93 @@
1
1
  ---
2
2
  name: caching
3
- description: >
4
- Set HTTP cache headers on tRPC query responses via responseMeta callback for
5
- CDN and browser caching. Configure Cache-Control, s-maxage,
6
- stale-while-revalidate. Handle caching with batching and authenticated requests.
7
- Avoid caching mutations, errors, and authenticated responses.
8
- type: core
9
- library: trpc
10
- library_version: '11.16.0'
3
+ description: Set HTTP cache headers on tRPC query responses via the adapter's responseMeta callback (info, ctx, type, errors, eagerGeneration) for CDN and browser caching. Configure Cache-Control, s-maxage, stale-while-revalidate. Handle caching with batching, streaming and authenticated requests. Avoid caching mutations, errors, and authenticated responses.
11
4
  requires:
12
5
  - server-setup
13
6
  sources:
14
- - 'trpc/trpc:www/docs/server/caching.md'
7
+ - www/v11/docs/server/caching.md
8
+ metadata:
9
+ type: core
10
+ library: trpc
11
+ library_version: 11.23.0
15
12
  ---
16
13
 
17
- # tRPC -- Caching
14
+ <!-- Generated from www/v11/docs/server/caching.md by www/build/skills.ts. Edit the docs instead. -->
18
15
 
19
- ## Setup
16
+ # Response Caching
20
17
 
21
- ```ts
22
- // server/trpc.ts
18
+ From https://trpc.io/docs/server/caching
19
+
20
+ Since all tRPC queries are normal HTTP `GET` requests, you can use standard HTTP cache headers to cache responses. This can make responses snappy, give your database a rest, and help scale your API.
21
+
22
+ > [!NOTE] Info
23
+ > Always be careful with caching - especially if you handle personal information.
24
+ >
25
+ > &nbsp;
26
+ > Since batching is enabled by default, it's recommended to set your cache headers in the `responseMeta` function and make sure that there are not any concurrent calls that may include personal data - or to omit cache headers completely if there is an auth header or cookie.
27
+ >
28
+ > &nbsp;
29
+ > You can also use a [`splitLink`](https://trpc.io/docs/client/links/splitLink) to split your public requests and those that should be private and uncached.
30
+
31
+
32
+ ## Using `responseMeta` to cache responses
33
+
34
+ Most tRPC adapters support a `responseMeta` callback that lets you set HTTP headers (including cache headers) based on the procedures being called.
35
+
36
+ > This works with any hosting provider that supports standard HTTP cache headers (e.g. Vercel, Cloudflare, AWS CloudFront).
37
+
38
+ ```ts no-check title="server.ts"
23
39
  import { initTRPC } from '@trpc/server';
40
+ import { createHTTPServer } from '@trpc/server/adapters/standalone';
24
41
  import type { CreateHTTPContextOptions } from '@trpc/server/adapters/standalone';
25
42
 
26
43
  export const createContext = async (opts: CreateHTTPContextOptions) => {
27
44
  return {
28
45
  req: opts.req,
29
46
  res: opts.res,
30
- user: null as { id: string } | null,
31
47
  };
32
48
  };
33
49
 
34
50
  type Context = Awaited<ReturnType<typeof createContext>>;
35
51
 
36
52
  export const t = initTRPC.context<Context>().create();
37
- export const router = t.router;
38
- export const publicProcedure = t.procedure;
39
- ```
40
53
 
41
- ```ts
42
- // server/appRouter.ts
43
- import { publicProcedure, router } from './trpc';
54
+ const waitFor = async (ms: number) =>
55
+ new Promise((resolve) => setTimeout(resolve, ms));
56
+
57
+ export const appRouter = t.router({
58
+ public: t.router({
59
+ slowQueryCached: t.procedure.query(async (opts) => {
60
+ await waitFor(5000); // wait for 5s
44
61
 
45
- export const appRouter = router({
46
- public: router({
47
- slowQueryCached: publicProcedure.query(async () => {
48
- await new Promise((resolve) => setTimeout(resolve, 5000));
49
- return { lastUpdated: new Date().toJSON() };
62
+ return {
63
+ lastUpdated: new Date().toJSON(),
64
+ };
50
65
  }),
51
66
  }),
52
67
  });
53
68
 
69
+ // Exporting `type AppRouter` only exposes types that can be used for inference
70
+ // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html#type-only-imports-and-export
54
71
  export type AppRouter = typeof appRouter;
55
- ```
56
-
57
- ```ts
58
- // server/index.ts
59
- import { createHTTPServer } from '@trpc/server/adapters/standalone';
60
- import { appRouter } from './appRouter';
61
- import { createContext } from './trpc';
62
72
 
73
+ // export API handler
63
74
  const server = createHTTPServer({
64
75
  router: appRouter,
65
76
  createContext,
66
77
  responseMeta(opts) {
67
- const { paths, errors, type } = opts;
68
-
69
- const allPublic =
70
- paths && paths.every((path) => path.startsWith('public.'));
71
- const allOk = errors.length === 0;
78
+ const { info, errors, type, eagerGeneration } = opts;
79
+ // assuming all your public routes are in the `public` router
80
+ const allPublic = info?.calls.every((call) =>
81
+ call.path.startsWith('public.'),
82
+ );
83
+ // checking that no procedures errored
84
+ // (when streaming, headers are sent before any results are known)
85
+ const allOk = !eagerGeneration && errors.length === 0;
86
+ // checking we're doing a query request
72
87
  const isQuery = type === 'query';
73
88
 
74
89
  if (allPublic && allOk && isQuery) {
90
+ // cache request for 1 day + revalidate once every second
75
91
  const ONE_DAY_IN_SECONDS = 60 * 60 * 24;
76
92
  return {
77
93
  headers: new Headers([
@@ -89,117 +105,11 @@ const server = createHTTPServer({
89
105
  server.listen(3000);
90
106
  ```
91
107
 
92
- ## Core Patterns
93
-
94
- ### Path-based public route caching
95
-
96
- ```ts
97
- import { createHTTPServer } from '@trpc/server/adapters/standalone';
98
- import { appRouter } from './appRouter';
99
- import { createContext } from './trpc';
100
-
101
- const server = createHTTPServer({
102
- router: appRouter,
103
- createContext,
104
- responseMeta({ paths, errors, type }) {
105
- const allPublic =
106
- paths && paths.every((path) => path.startsWith('public.'));
107
- const allOk = errors.length === 0;
108
- const isQuery = type === 'query';
109
-
110
- if (allPublic && allOk && isQuery) {
111
- return {
112
- headers: new Headers([
113
- ['cache-control', 's-maxage=1, stale-while-revalidate=86400'],
114
- ]),
115
- };
116
- }
117
- return {};
118
- },
119
- });
120
- ```
121
-
122
- Name public routes with a `public` prefix (e.g., `public.slowQueryCached`) so `responseMeta` can identify them by path.
123
-
124
- ### Skip caching for authenticated requests
125
-
126
- ```ts
127
- import { createHTTPServer } from '@trpc/server/adapters/standalone';
128
- import { appRouter } from './appRouter';
129
- import { createContext } from './trpc';
130
-
131
- const server = createHTTPServer({
132
- router: appRouter,
133
- createContext,
134
- responseMeta({ ctx, errors, type }) {
135
- if (ctx?.user || errors.length > 0 || type !== 'query') {
136
- return {};
137
- }
138
- return {
139
- headers: new Headers([
140
- ['cache-control', 's-maxage=1, stale-while-revalidate=86400'],
141
- ]),
142
- };
143
- },
144
- });
145
- ```
146
-
147
- ## Common Mistakes
148
-
149
- ### [CRITICAL] Caching authenticated responses
150
-
151
- Wrong:
152
-
153
- ```ts
154
- import { createHTTPServer } from '@trpc/server/adapters/standalone';
155
- import { appRouter } from './appRouter';
156
-
157
- const server = createHTTPServer({
158
- router: appRouter,
159
- responseMeta() {
160
- return {
161
- headers: new Headers([['cache-control', 's-maxage=60']]),
162
- };
163
- },
164
- });
165
- ```
166
-
167
- Correct:
168
-
169
- ```ts
170
- import { createHTTPServer } from '@trpc/server/adapters/standalone';
171
- import { appRouter } from './appRouter';
172
- import { createContext } from './trpc';
173
-
174
- const server = createHTTPServer({
175
- router: appRouter,
176
- createContext,
177
- responseMeta({ ctx, errors, type }) {
178
- if (ctx?.user || errors.length > 0 || type !== 'query') {
179
- return {};
180
- }
181
- return {
182
- headers: new Headers([
183
- ['cache-control', 's-maxage=1, stale-while-revalidate=86400'],
184
- ]),
185
- };
186
- },
187
- });
188
- ```
189
-
190
- With batching enabled by default, a cached response containing personal data could be served to other users; always check for auth context, errors, and request type before setting cache headers.
191
-
192
- Source: www/docs/server/caching.md
193
-
194
- ### [HIGH] Next.js App Router overrides Cache-Control headers
195
-
196
- There is no code fix for this -- Next.js App Router overrides `Cache-Control` headers set by tRPC via `responseMeta`. The documented caching approach using `responseMeta` does not work as expected in App Router. Use Next.js native caching mechanisms (`revalidate`, `unstable_cache`) instead when deploying on App Router.
108
+ `responseMeta` runs once per HTTP response, so with batching it decides the headers for every procedure in the batch: only cache if all of them are public. It also gets the request's `ctx`, e.g. to skip caching for signed-in users. For streamed responses, like those of [`httpBatchStreamLink`](https://trpc.io/docs/client/links/httpBatchStreamLink), the headers are sent before any procedure has finished, so `responseMeta` runs with `eagerGeneration: true` and an empty `errors` array.
197
109
 
198
- Source: https://github.com/trpc/trpc/issues/5625
110
+ > [!TIP]
111
+ > If you are using the deprecated Next.js Pages Router integration (`@trpc/next`), see the [Next.js SSR caching guide](https://trpc.io/docs/client/nextjs/pages-router/ssr#response-caching-with-ssr) for Next.js-specific caching examples using `createTRPCNext` and the Next.js adapter.
199
112
 
200
- ## See Also
113
+ ## Related skills
201
114
 
202
- - `server-setup` -- initTRPC, createContext configuration
203
- - `adapter-standalone` -- responseMeta option on createHTTPServer
204
- - `adapter-fetch` -- responseMeta option on fetchRequestHandler
205
- - `links` -- splitLink to separate public/private requests on the client
115
+ - `server-setup` (https://trpc.io/docs/server/overview): `npx @tanstack/intent@latest load @trpc/server#server-setup`