@orpc/node 2.0.0-beta.47 → 2.0.0-beta.49

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.
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
  <img alt="codecov" src="https://codecov.io/gh/middleapi/orpc/branch/main/graph/badge.svg">
6
6
  </a>
7
7
  <a href="https://www.npmjs.com/package/@orpc/node">
8
- <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Fnode?logo=npm" />
8
+ <img alt="monthly downloads" src="https://img.shields.io/npm/dm/%40orpc%2Fnode?logo=npm" />
9
9
  </a>
10
10
  <a href="https://app.codspeed.io/middleapi/orpc?utm_source=badge">
11
11
  <img alt="CodSpeed" src="https://img.shields.io/endpoint?url=https://codspeed.io/badge.json" />
@@ -41,10 +41,11 @@ export const router = {
41
41
  Then call them from a client that knows every input and output, without generating anything:
42
42
 
43
43
  ```ts
44
- import type { RouterClient } from '@orpc/server'
45
- import type { router } from './router'
46
44
  import { createORPCClient } from '@orpc/client'
47
45
  import { RPCLink } from '@orpc/client/fetch'
46
+ import type { RouterClient } from '@orpc/server'
47
+
48
+ import type { router } from './router'
48
49
 
49
50
  const link = new RPCLink({ origin: 'http://localhost:3000', url: '/rpc' })
50
51
  const client: RouterClient<typeof router> = createORPCClient(link)
@@ -191,15 +192,14 @@ Like what we build over at [middleapi](https://github.com/middleapi)? You can he
191
192
  <td align="center"><a href="https://kellychan.im/?ref=middleapi&amp;utm_source=middleapi&amp;utm_medium=sponsor" target="_blank" rel="noopener sponsored" title="Kelly Peilin Chan"><img src="https://avatars.githubusercontent.com/u/520852?u=6b0f7105f694e7b5cacf410a3f04c7044b469dc8&amp;v=4" width="139" alt="Kelly Peilin Chan"/><br />Kelly Peilin Chan</a></td>
192
193
  <td align="center"><a href="https://guyariely.com/?ref=middleapi&amp;utm_source=middleapi&amp;utm_medium=sponsor" target="_blank" rel="noopener sponsored" title="Guy Ariely"><img src="https://avatars.githubusercontent.com/u/42813496?u=edb6b7f563bf28e160a290832e7da57c0506f8ca&amp;v=4" width="139" alt="Guy Ariely"/><br />Guy Ariely</a></td>
193
194
  <td align="center"><a href="https://paulsenon.com/?ref=middleapi&amp;utm_source=middleapi&amp;utm_medium=sponsor" target="_blank" rel="noopener sponsored" title="PaulSenon"><img src="https://avatars.githubusercontent.com/u/19531087?u=6385741eb91d200b8c513ec6045482e301767ca6&amp;v=4" width="139" alt="PaulSenon"/><br />PaulSenon</a></td>
194
- <td align="center"><a href="https://nakasyou.how/?ref=middleapi&amp;utm_source=middleapi&amp;utm_medium=sponsor" target="_blank" rel="noopener sponsored" title="Shotaro Nakamura"><img src="https://avatars.githubusercontent.com/u/79000684?u=f644df3f29f0e8677a90967115774564f1d9d6ab&amp;v=4" width="139" alt="Shotaro Nakamura"/><br />Shotaro Nakamura</a></td>
195
+ <td align="center"><a href="https://piscis.dev/?ref=middleapi&amp;utm_source=middleapi&amp;utm_medium=sponsor" target="_blank" rel="noopener sponsored" title="Alex"><img src="https://avatars.githubusercontent.com/u/326163?u=b245f368bd940cf51d08c0b6bf55f8257f359437&amp;v=4" width="139" alt="Alex"/><br />Alex</a></td>
195
196
  </tr>
196
197
  <tr>
197
- <td align="center"><a href="https://piscis.dev/?ref=middleapi&amp;utm_source=middleapi&amp;utm_medium=sponsor" target="_blank" rel="noopener sponsored" title="Alex"><img src="https://avatars.githubusercontent.com/u/326163?u=b245f368bd940cf51d08c0b6bf55f8257f359437&amp;v=4" width="139" alt="Alex"/><br />Alex</a></td>
198
198
  <td align="center"><a href="https://opensource.gubanov.eu/?ref=middleapi&amp;utm_source=middleapi&amp;utm_medium=sponsor" target="_blank" rel="noopener sponsored" title="Andrey Gubanov"><img src="https://avatars.githubusercontent.com/u/1082083?u=c5f2daf7ebece498e85c83367bb37b4e10e2649d&amp;v=4" width="139" alt="Andrey Gubanov"/><br />Andrey Gubanov</a></td>
199
199
  </tr>
200
200
  </table>
201
201
 
202
- With thanks to [39 past sponsors](https://orpc.dev/sponsors#past-sponsors) who helped get oRPC here.
202
+ With thanks to [40 past sponsors](https://orpc.dev/sponsors#past-sponsors) who helped get oRPC here.
203
203
 
204
204
  ## Open Source Programs
205
205
 
@@ -209,7 +209,6 @@ With thanks to [39 past sponsors](https://orpc.dev/sponsors#past-sponsors) who h
209
209
  <tr>
210
210
  <td align="center"><a href="https://claude.com/contact-sales/claude-for-oss" target="_blank" rel="noopener" title="Claude for Open Source"><img src="https://cdn.simpleicons.org/claude" width="64" alt="Claude"/><br />Claude</a></td>
211
211
  <td align="center"><a href="https://pullfrog.com/for-oss" target="_blank" rel="noopener" title="Pullfrog for OSS"><img src="https://avatars.githubusercontent.com/in/1768019?s=128&amp;v=4" width="64" alt="Pullfrog"/><br />Pullfrog</a></td>
212
- <td align="center"><a href="https://macroscope.com/open-source" target="_blank" rel="noopener" title="Macroscope for Open Source"><img src="https://avatars.githubusercontent.com/in/900172?s=128&amp;v=4" width="64" alt="Macroscope"/><br />Macroscope</a></td>
213
212
  </tr>
214
213
  </table>
215
214
 
@@ -0,0 +1,46 @@
1
+ import type { Context } from '@orpc/server';
2
+ import type { StandardHandlerOptions, StandardHandlerPlugin } from '@orpc/server/standard';
3
+ export interface BatchResponseCompressionHandlerPluginOptions {
4
+ /**
5
+ * The compression schemes to use for batch responses.
6
+ * Schemes are prioritized by their order in this array and
7
+ * only applied if the client supports them (via Accept-Encoding).
8
+ *
9
+ * @default ['gzip', 'deflate']
10
+ */
11
+ encodings?: readonly ('gzip' | 'deflate' | 'deflate-raw')[] | undefined;
12
+ /**
13
+ * The minimum response size in bytes required to trigger compression.
14
+ * Responses smaller than this threshold will not be compressed to avoid overhead.
15
+ * A streaming batch response has no size until it ends, so it is always compressed.
16
+ *
17
+ * @default 1024 (1KB)
18
+ */
19
+ threshold?: number | undefined;
20
+ }
21
+ /**
22
+ * Compresses every successful [batch](https://orpc.dev/docs/plugins/batch) response, which the
23
+ * runtime-agnostic {@link https://orpc.dev/docs/plugins/response-compression | Response Compression Plugin}
24
+ * leaves untouched when framed: a batch frames subresponses of mixed content types, so its envelope
25
+ * has none of its own and nothing says whether the contents compress. Registering this plugin
26
+ * states that they do.
27
+ *
28
+ * @remarks
29
+ * Each message is flushed as soon as it is produced, so a streaming batch stays streaming.
30
+ * This is why the plugin lives in the Node.js package: `zlib` can flush mid-stream, while the
31
+ * web `CompressionStream` cannot, and would hold every early message until the batch ends.
32
+ *
33
+ * @see {@link https://orpc.dev/docs/plugins/batch-response-compression | Batch Response Compression Plugin}
34
+ */
35
+ export declare class BatchResponseCompressionHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
36
+ name: string;
37
+ /**
38
+ * Compression should be done after batching, to compress the assembled batch response
39
+ * rather than each subresponse inside it.
40
+ */
41
+ after: string[];
42
+ private readonly encodings;
43
+ private readonly threshold;
44
+ constructor(options?: BatchResponseCompressionHandlerPluginOptions);
45
+ init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
46
+ }
@@ -0,0 +1,129 @@
1
+ import { Duplex } from 'node:stream';
2
+ import { constants, createDeflate, createDeflateRaw, createGzip } from 'node:zlib';
3
+ import { BATCH_HEADER, negotiateResponseCompressionEncoding, toCompressedHeaders, } from '@orpc/server/plugins';
4
+ import { toArray } from '@orpc/shared';
5
+ import { flattenStandardHeader } from '@standard-server/core';
6
+ import { toFetchBody } from '@standard-server/fetch';
7
+ /**
8
+ * Compresses every successful [batch](https://orpc.dev/docs/plugins/batch) response, which the
9
+ * runtime-agnostic {@link https://orpc.dev/docs/plugins/response-compression | Response Compression Plugin}
10
+ * leaves untouched when framed: a batch frames subresponses of mixed content types, so its envelope
11
+ * has none of its own and nothing says whether the contents compress. Registering this plugin
12
+ * states that they do.
13
+ *
14
+ * @remarks
15
+ * Each message is flushed as soon as it is produced, so a streaming batch stays streaming.
16
+ * This is why the plugin lives in the Node.js package: `zlib` can flush mid-stream, while the
17
+ * web `CompressionStream` cannot, and would hold every early message until the batch ends.
18
+ *
19
+ * @see {@link https://orpc.dev/docs/plugins/batch-response-compression | Batch Response Compression Plugin}
20
+ */
21
+ export class BatchResponseCompressionHandlerPlugin {
22
+ name = '~batch-response-compression';
23
+ /**
24
+ * Compression should be done after batching, to compress the assembled batch response
25
+ * rather than each subresponse inside it.
26
+ */
27
+ after = ['~batch'];
28
+ encodings;
29
+ threshold;
30
+ constructor(options = {}) {
31
+ this.encodings = options.encodings ?? ['gzip', 'deflate'];
32
+ this.threshold = options.threshold ?? 1024;
33
+ }
34
+ init(options) {
35
+ const routingInterceptor = async ({ next, ...interceptorOptions }) => {
36
+ const result = await next();
37
+ if (!result.matched) {
38
+ return result;
39
+ }
40
+ /**
41
+ * The batch plugin only engages on a request carrying this header, so a response framed like
42
+ * a batch without it belongs to a procedure serving that content type itself, whose own file
43
+ * semantics must survive untouched.
44
+ */
45
+ if (flattenStandardHeader(interceptorOptions.request.headers[BATCH_HEADER]) === undefined) {
46
+ return result;
47
+ }
48
+ const response = result.response;
49
+ const headers = response.headers;
50
+ const body = response.body;
51
+ /**
52
+ * A batch that failed as a whole answers with a plain message instead of subresponses,
53
+ * so only a successful envelope is a batch payload worth compressing.
54
+ */
55
+ if (response.status >= 400) {
56
+ return result;
57
+ }
58
+ const encoding = negotiateResponseCompressionEncoding(response, interceptorOptions.request.headers, this.encodings);
59
+ if (encoding === undefined) {
60
+ return result;
61
+ }
62
+ let stream;
63
+ /**
64
+ * A framed body is opaque bytes, while a json one still has to be parsed as json,
65
+ * so each keeps the hint that tells the client how to read it.
66
+ */
67
+ let bodyHeaders;
68
+ /**
69
+ * A buffered batch with no binary or stream subresponse stays a plain array of messages, serialized
70
+ * as json by the adapter. The header and status above already say this is a batch envelope,
71
+ * so the array itself is the only thing left to recognise.
72
+ */
73
+ if (Array.isArray(body)) {
74
+ // Serialized here rather than by the adapter, which no longer sees the array
75
+ const [string, jsonHeaders] = toFetchBody(body, headers);
76
+ const json = new Blob([string]);
77
+ if (json.size < this.threshold) {
78
+ return result;
79
+ }
80
+ stream = json.stream();
81
+ bodyHeaders = {
82
+ 'content-type': jsonHeaders['content-type'],
83
+ // An empty hint rather than none, so the adapter does not hint the compressed stream as `octet-stream`
84
+ 'standard-server': jsonHeaders['standard-server'] ?? [],
85
+ };
86
+ }
87
+ // Every other batch body is the length-prefixed framing, buffered into a blob or streamed
88
+ else if (body instanceof Blob || body instanceof ReadableStream) {
89
+ if (body instanceof Blob && Number.isFinite(body.size) && body.size < this.threshold) {
90
+ return result;
91
+ }
92
+ stream = body instanceof Blob ? body.stream() : body;
93
+ bodyHeaders = { 'standard-server': 'octet-stream' };
94
+ }
95
+ else {
96
+ return result;
97
+ }
98
+ return {
99
+ ...result,
100
+ response: {
101
+ ...response,
102
+ body: stream.pipeThrough(createFlushingCompressionStream(encoding)),
103
+ headers: {
104
+ ...toCompressedHeaders(headers, encoding),
105
+ ...bodyHeaders,
106
+ },
107
+ },
108
+ };
109
+ };
110
+ return {
111
+ ...options,
112
+ routingInterceptors: [routingInterceptor, ...toArray(options.routingInterceptors)],
113
+ };
114
+ }
115
+ }
116
+ /**
117
+ * A compressor that ends every write with a sync flush, so each batch message reaches the client
118
+ * as soon as the batch produces it instead of waiting in the compressor for the batch to end.
119
+ * The few bytes each flush costs are what keep a streaming batch streaming.
120
+ */
121
+ function createFlushingCompressionStream(encoding) {
122
+ const zlibOptions = { flush: constants.Z_SYNC_FLUSH };
123
+ const compressor = encoding === 'gzip'
124
+ ? createGzip(zlibOptions)
125
+ : encoding === 'deflate'
126
+ ? createDeflate(zlibOptions)
127
+ : createDeflateRaw(zlibOptions);
128
+ return Duplex.toWeb(compressor);
129
+ }
package/dist/index.d.ts CHANGED
@@ -1,316 +1,3 @@
1
- import { Context } from '@orpc/server';
2
- import { StandardHandlerPlugin, StandardHandlerOptions, StandardHandlerRoutingInterceptorOptions } from '@orpc/server/standard';
3
- import { Value, Promisable } from '@orpc/shared';
4
- import { FilePropertyBag } from 'node:buffer';
5
-
6
- interface BatchResponseCompressionHandlerPluginOptions {
7
- /**
8
- * The compression schemes to use for batch responses.
9
- * Schemes are prioritized by their order in this array and
10
- * only applied if the client supports them (via Accept-Encoding).
11
- *
12
- * @default ['gzip', 'deflate']
13
- */
14
- encodings?: readonly ('gzip' | 'deflate' | 'deflate-raw')[] | undefined;
15
- /**
16
- * The minimum response size in bytes required to trigger compression.
17
- * Responses smaller than this threshold will not be compressed to avoid overhead.
18
- * A streaming batch response has no size until it ends, so it is always compressed.
19
- *
20
- * @default 1024 (1KB)
21
- */
22
- threshold?: number | undefined;
23
- }
24
- /**
25
- * Compresses every successful [batch](https://orpc.dev/docs/plugins/batch) response, which the
26
- * runtime-agnostic {@link https://orpc.dev/docs/plugins/response-compression | Response Compression Plugin}
27
- * leaves untouched when framed: a batch frames subresponses of mixed content types, so its envelope
28
- * has none of its own and nothing says whether the contents compress. Registering this plugin
29
- * states that they do.
30
- *
31
- * @remarks
32
- * Each message is flushed as soon as it is produced, so a streaming batch stays streaming.
33
- * This is why the plugin lives in the Node.js package: `zlib` can flush mid-stream, while the
34
- * web `CompressionStream` cannot, and would hold every early message until the batch ends.
35
- *
36
- * @see {@link https://orpc.dev/docs/plugins/batch-response-compression | Batch Response Compression Plugin}
37
- */
38
- declare class BatchResponseCompressionHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
39
- name: string;
40
- /**
41
- * Compression should be done after batching, to compress the assembled batch response
42
- * rather than each subresponse inside it.
43
- */
44
- after: string[];
45
- private readonly encodings;
46
- private readonly threshold;
47
- constructor(options?: BatchResponseCompressionHandlerPluginOptions);
48
- init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
49
- }
50
-
51
- interface StaticFileHandlerPluginOptions {
52
- /**
53
- * The directory files are served from. Resolved against the working
54
- * directory when relative.
55
- */
56
- rootDir: string;
57
- /**
58
- * The URL path files are served under, appended to the handler prefix
59
- * when one is set.
60
- *
61
- * @default '/'
62
- */
63
- path?: `/${string}` | undefined;
64
- /**
65
- * The file served when the request path resolves to a directory.
66
- * Set to `false` to disable directory index files.
67
- *
68
- * @default 'index.html'
69
- */
70
- indexFile?: string | false | undefined;
71
- /**
72
- * A file served with status 200 when no file matches the request path,
73
- * relative to `rootDir`. Useful for single-page application routing.
74
- *
75
- * @default undefined
76
- */
77
- fallbackFile?: string | undefined;
78
- /**
79
- * The `Cache-Control` response header value. Set to `false` to omit the header.
80
- *
81
- * @default 'public, max-age=0'
82
- */
83
- cacheControl?: string | false | undefined;
84
- /**
85
- * Whether files and directories whose name starts with a dot can be served.
86
- * When disabled, names shaped like 8.3 short names, such as `ENV~1`, are refused too,
87
- * since NTFS and FAT resolve them to dotfiles.
88
- *
89
- * @default false
90
- */
91
- dotfiles?: boolean | undefined;
92
- /**
93
- * Whether precompressed sidecar files (`.br`, `.zst`, `.gz`) can be served
94
- * when the client accepts their encoding and the content type is compressible.
95
- *
96
- * @default false
97
- */
98
- precompressed?: boolean | undefined;
99
- /**
100
- * Whether symbolic links whose target lies outside `rootDir` can be served.
101
- * Enabling this makes every file the links reach publicly readable.
102
- *
103
- * @default false
104
- */
105
- allowSymlinks?: boolean | undefined;
106
- /**
107
- * Content types keyed by lowercase file extension without the dot, taking precedence over
108
- * the type detected from the extension. Values are sent verbatim, so a text type needs its
109
- * own charset. Extensions that neither this nor the detection recognises are served as
110
- * `application/octet-stream`.
111
- */
112
- mimeTypes?: Record<string, string> | undefined;
113
- }
114
- /**
115
- * Serves static files from a directory with standard HTTP semantics:
116
- * `ETag`/`Last-Modified` conditional requests, range requests, index files,
117
- * and directory traversal protection. Files are served as a fallback,
118
- * so matched procedures always win.
119
- *
120
- * @remarks
121
- * Deliberate deviations, all matching `send`, nginx, and Hono: range handling applies to `GET`
122
- * only, so `HEAD` always reports the full length even though `Accept-Ranges` advertises support;
123
- * a suffix range against an empty file answers `416`; and `dotfiles` is a request-path policy,
124
- * so it never applies to a configured `indexFile` or `fallbackFile`.
125
- *
126
- * @see {@link https://orpc.dev/docs/plugins/static-file | Static File Plugin}
127
- */
128
- declare class StaticFileHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
129
- name: string;
130
- /**
131
- * Ensure the request span is available when the interceptor renames it.
132
- */
133
- after: string[];
134
- private readonly rootDir;
135
- /** `rootDir` with a trailing separator, precomputed for the lexical containment check. */
136
- private readonly rootDirPrefix;
137
- /**
138
- * `rootDir` with its own symbolic links resolved, paired with its trailing separator form.
139
- * Resolved once, so a symlinked `rootDir` keeps working and platform links like the macOS
140
- * `/var` to `/private/var` do not reject every file.
141
- */
142
- private readonly rootDirRealPaths;
143
- private readonly path;
144
- private readonly indexFile;
145
- private readonly fallbackFile;
146
- private readonly cacheControl;
147
- private readonly dotfiles;
148
- private readonly precompressed;
149
- private readonly allowSymlinks;
150
- private readonly mimeTypes;
151
- constructor(options: StaticFileHandlerPluginOptions);
152
- init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
153
- /**
154
- * Joins segments under `rootDir` and guarantees the result cannot escape it,
155
- * as a second layer of defense after URL segment validation.
156
- */
157
- private resolveWithinRoot;
158
- /**
159
- * Resolves symbolic links and confirms the target is still inside the root,
160
- * which the lexical `resolveWithinRoot` check cannot see.
161
- */
162
- private resolveContainedRealPath;
163
- private resolveContentType;
164
- private resolveBasePath;
165
- /**
166
- * Resolves segments under `rootDir` and stats the result, rejecting anything that
167
- * escapes the root either lexically or by following a symbolic link.
168
- */
169
- private lookup;
170
- /**
171
- * Normalizes the url path into filesystem segments,
172
- * returning `undefined` when the request can never map to a servable file.
173
- */
174
- private resolveSegments;
175
- private serve;
176
- }
177
-
178
- interface TmpFileUploadHandlerPluginMaxBodySize {
179
- /**
180
- * The maximum size in bytes of request body content buffered into memory:
181
- * JSON, URL-encoded forms, and the fields, part headers, and in-memory files
182
- * of a multipart body in total, and each event of an event stream on its
183
- * own. Exceeding it rejects with `PAYLOAD_TOO_LARGE`, except for uploads,
184
- * which spool to disk instead once they no longer fit. Usually the lowest of
185
- * the three limits, because this content cannot stream anywhere.
186
- */
187
- memory: number;
188
- /**
189
- * The maximum total size in bytes of uploaded file content: file bodies and
190
- * the file parts of a multipart body combined, whether held in memory or
191
- * spooled to temporary files. A larger body rejects the request with
192
- * `PAYLOAD_TOO_LARGE`.
193
- */
194
- file: number;
195
- /**
196
- * The maximum total size in bytes of a request body that is consumed as a
197
- * stream: event streams and raw binary streams. Enforced while the stream is
198
- * consumed, so an oversized stream fails at the reader. Usually the highest
199
- * of the three limits, but keep it finite so no client can stream
200
- * indefinitely.
201
- */
202
- stream: number;
203
- }
204
- interface TmpFileUploadHandlerPluginOptions<T extends Context> {
205
- /**
206
- * The directory temporary files are created under. Each request that spools
207
- * an upload gets its own subdirectory inside it, removed when the request
208
- * finishes.
209
- *
210
- * @default os.tmpdir()
211
- */
212
- tmpDir?: string | undefined;
213
- /**
214
- * The size limit for each kind of request body, either fixed or resolved
215
- * per request, so limits can follow the request itself, such as a larger
216
- * allowance for an authenticated user than for a guest. Every kind is
217
- * required when the option is given, so none is left unbounded by accident;
218
- * set a kind to `Number.POSITIVE_INFINITY` to deliberately leave it
219
- * unlimited.
220
- *
221
- * A resolver runs only when a body is parsed, so a request without one never
222
- * pays for it, and it receives the request as it arrived, before this plugin
223
- * wraps its body resolution.
224
- *
225
- * @default unlimited for every kind
226
- */
227
- maxBodySize?: Value<Promisable<TmpFileUploadHandlerPluginMaxBodySize>, [options: StandardHandlerRoutingInterceptorOptions<T>]> | undefined;
228
- /**
229
- * The size in bytes an uploaded file must exceed before it is spooled to a
230
- * temporary file. Smaller files stay in memory as plain `File`s, counted
231
- * against `maxBodySize.memory`, and spool anyway once they no longer fit.
232
- * Set to `0` to spool every non-empty upload.
233
- *
234
- * @default 64 * 1024
235
- */
236
- spoolThreshold?: number | undefined;
237
- }
238
- /**
239
- * A `File` whose content lives in a temporary file on disk and is read lazily,
240
- * so it can represent an upload far larger than available memory.
241
- *
242
- * @remarks
243
- * Node's `fs.openAsBlob`, which backs this class, has known bugs with files
244
- * over 2 GiB ({@link https://github.com/nodejs/node/issues/52585}): `size` is
245
- * truncated above 4 GiB and `slice()` is unreliable above 2 GiB, while
246
- * whole-file reads like `stream()` stay correct. When size or random access
247
- * matters for such a file, stat or read {@link path} directly.
248
- *
249
- * @see {@link https://orpc.dev/docs/plugins/tmp-file-upload | Tmp File Upload Plugin}
250
- */
251
- declare class TmpFile extends File {
252
- /**
253
- * Absolute path of the temporary file holding this file's content.
254
- * The file is removed when the request finishes, so move or copy it
255
- * to keep the content. The `File` reads from this path, so it must
256
- * not be read after the file is moved or removed.
257
- */
258
- readonly path: string;
259
- constructor(blob: Blob,
260
- /**
261
- * Absolute path of the temporary file holding this file's content.
262
- * The file is removed when the request finishes, so move or copy it
263
- * to keep the content. The `File` reads from this path, so it must
264
- * not be read after the file is moved or removed.
265
- */
266
- path: string, name: string, options?: FilePropertyBag);
267
- }
268
- /**
269
- * Parses file uploads into temporary files instead of memory. Bodies the standard
270
- * body parser would buffer into an in-memory `File`, and multipart file parts, are
271
- * streamed to disk once they outgrow the spool threshold and surfaced as lazily read
272
- * {@link TmpFile} instances, so requests far larger than available memory parse in
273
- * constant memory. Smaller uploads stay in memory as plain `File`s. Every other body is
274
- * left to the standard parser.
275
- *
276
- * Request body sizes are limited per content category: buffered in memory, uploaded
277
- * files, and streamed, each limit fixed or resolved per request. This subsumes the
278
- * request limit plugin while sizing each kind of body to what it actually costs.
279
- *
280
- * @remarks
281
- * Temporary files are removed when the request finishes. A streaming response body,
282
- * an event iterator or a raw stream, keeps them alive until it completes, so
283
- * responses that read the upload while streaming work. Any other response is
284
- * transmitted after removal, so one that embeds the upload itself, as a `File` or
285
- * inside `FormData`, needs the content copied or the file moved first.
286
- *
287
- * @see {@link https://orpc.dev/docs/plugins/tmp-file-upload | Tmp File Upload Plugin}
288
- */
289
- declare class TmpFileUploadHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
290
- name: string;
291
- /**
292
- * Should parse the original request body instead of batched sub-requests.
293
- */
294
- after: string[];
295
- /**
296
- * Should run inside the limit and compression plugins, so spooling receives
297
- * the size-checked, decompressed bytes.
298
- */
299
- before: string[];
300
- private readonly tmpDir;
301
- private readonly maxBodySize;
302
- private readonly spoolThreshold;
303
- constructor(options?: TmpFileUploadHandlerPluginOptions<T>);
304
- init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
305
- private resolveBody;
306
- /**
307
- * Enforces size limits on a body the standard parser handles, counting the
308
- * raw bytes before handing them back for regular parsing.
309
- */
310
- private parseLimitedBody;
311
- private parseFileBody;
312
- private parseMultipartBody;
313
- }
314
-
315
- export { BatchResponseCompressionHandlerPlugin, StaticFileHandlerPlugin, TmpFile, TmpFileUploadHandlerPlugin };
316
- export type { BatchResponseCompressionHandlerPluginOptions, StaticFileHandlerPluginOptions, TmpFileUploadHandlerPluginMaxBodySize, TmpFileUploadHandlerPluginOptions };
1
+ export * from './batch-response-compression-handler-plugin.ts';
2
+ export * from './static-file-handler-plugin.ts';
3
+ export * from './tmp-file-upload-handler-plugin.ts';
package/dist/index.js ADDED
@@ -0,0 +1,3 @@
1
+ export * from './batch-response-compression-handler-plugin.js';
2
+ export * from './static-file-handler-plugin.js';
3
+ export * from './tmp-file-upload-handler-plugin.js';
@@ -0,0 +1,60 @@
1
+ import { Buffer } from 'node:buffer';
2
+ export interface MultipartPart {
3
+ /**
4
+ * The `name` parameter of the part's `Content-Disposition` header, with the
5
+ * serialization escapes of `"`, `\r`, and `\n` decoded.
6
+ */
7
+ name: string;
8
+ /**
9
+ * The `filename` parameter of the part's `Content-Disposition` header,
10
+ * decoded like `name`, or `undefined` when the part is a plain field. An
11
+ * empty string is a file part, matching how browsers submit an empty file
12
+ * input.
13
+ */
14
+ filename: string | undefined;
15
+ /**
16
+ * The part's `Content-Type` header value, if present.
17
+ */
18
+ type: string | undefined;
19
+ /**
20
+ * The size in bytes of the part's header block, including the blank line.
21
+ */
22
+ headerSize: number;
23
+ }
24
+ export interface MultipartPartWriter {
25
+ /**
26
+ * Receives one chunk of the part's body. The chunk is only valid until the
27
+ * returned promise resolves, so it must be consumed or copied synchronously.
28
+ */
29
+ write(chunk: Buffer): void | Promise<void>;
30
+ /**
31
+ * Called once after the part's final chunk.
32
+ */
33
+ end(): void | Promise<void>;
34
+ }
35
+ /**
36
+ * Parses a `multipart/form-data` byte stream part by part, so a part's body can be
37
+ * consumed as it arrives instead of being buffered whole. Bodies are delivered to the
38
+ * writer `onPart` returns, with writer promises awaited for backpressure, so parts are
39
+ * processed strictly one at a time.
40
+ *
41
+ * Line endings are strictly CRLF, every part must carry a `form-data` content
42
+ * disposition with a `name` parameter, and a malformed or truncated body throws a
43
+ * `TypeError`, matching the standard parser's strictness.
44
+ *
45
+ * @see https://www.rfc-editor.org/rfc/rfc7578
46
+ * @see https://www.rfc-editor.org/rfc/rfc2046#section-5.1.1
47
+ */
48
+ export declare function parseMultipart(source: ReadableStream<Uint8Array>, boundary: string, onPart: (part: MultipartPart) => MultipartPartWriter | Promise<MultipartPartWriter>): Promise<void>;
49
+ /**
50
+ * Extracts the `key=value` parameters that follow a header's leading token.
51
+ * The first occurrence of a parameter wins.
52
+ *
53
+ * A backslash inside a quoted value is a literal character rather than an
54
+ * escape, matching the standard parser: the multipart serialization escapes
55
+ * `"` as `%22`, so a quote can never occur inside a value, while filenames
56
+ * with literal backslashes are common and must survive verbatim.
57
+ *
58
+ * @see https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#multipart/form-data-encoding-algorithm
59
+ */
60
+ export declare function parseHeaderParameters(header: string): Map<string, string>;