@orpc/contract 0.0.0-next.dcc6c29 → 0.0.0-next.dd8de86
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 +18 -22
- package/dist/index.d.mts +320 -7
- package/dist/index.d.ts +320 -7
- package/dist/index.mjs +107 -4
- package/package.json +7 -6
package/README.md
CHANGED
|
@@ -21,28 +21,24 @@
|
|
|
21
21
|
|
|
22
22
|
<h3 align="center">Typesafe APIs Made Simple 🪄</h3>
|
|
23
23
|
|
|
24
|
-
**oRPC is a powerful combination of RPC and OpenAPI**, makes it easy to build APIs that are end-to-end type-safe and adhere to OpenAPI standards
|
|
24
|
+
**oRPC is a powerful combination of RPC and OpenAPI**, makes it easy to build APIs that are end-to-end type-safe and adhere to OpenAPI standards
|
|
25
25
|
|
|
26
26
|
---
|
|
27
27
|
|
|
28
28
|
## Highlights
|
|
29
29
|
|
|
30
|
-
-
|
|
31
|
-
-
|
|
32
|
-
-
|
|
33
|
-
-
|
|
34
|
-
-
|
|
35
|
-
-
|
|
36
|
-
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
-
|
|
41
|
-
-
|
|
42
|
-
- **Reusability 🔄**: Write once and reuse your code across multiple purposes effortlessly.
|
|
43
|
-
- **Extendability 🔌**: Easily enhance oRPC with plugins, middleware, and interceptors.
|
|
44
|
-
- **Reliability 🛡️**: Well-tested, fully TypeScript, production-ready, and MIT licensed for peace of mind.
|
|
45
|
-
- **Simplicity 💡**: Enjoy straightforward, clean code with no hidden magic.
|
|
30
|
+
- **🔗 End-to-End Type Safety**: Ensure type-safe inputs, outputs, and errors from client to server.
|
|
31
|
+
- **📘 First-Class OpenAPI**: Built-in support that fully adheres to the OpenAPI standard.
|
|
32
|
+
- **📝 Contract-First Development**: Optionally define your API contract before implementation.
|
|
33
|
+
- **🔍 First-Class OpenTelemetry**: Seamlessly integrate with OpenTelemetry for observability.
|
|
34
|
+
- **⚙️ Framework Integrations**: Seamlessly integrate with TanStack Query (React, Vue, Solid, Svelte, Angular), Pinia Colada, and more.
|
|
35
|
+
- **🚀 Server Actions**: Fully compatible with React Server Actions on Next.js, TanStack Start, and other platforms.
|
|
36
|
+
- **🔠 Standard Schema Support**: Works out of the box with Zod, Valibot, ArkType, and other schema validators.
|
|
37
|
+
- **🗃️ Native Types**: Supports native types like Date, File, Blob, BigInt, URL, and more.
|
|
38
|
+
- **⏱️ Lazy Router**: Enhance cold start times with our lazy routing feature.
|
|
39
|
+
- **📡 SSE & Streaming**: Enjoy full type-safe support for SSE and streaming.
|
|
40
|
+
- **🌍 Multi-Runtime Support**: Fast and lightweight on Cloudflare, Deno, Bun, Node.js, and beyond.
|
|
41
|
+
- **🔌 Extendability**: Easily extend functionality with plugins, middleware, and interceptors.
|
|
46
42
|
|
|
47
43
|
## Documentation
|
|
48
44
|
|
|
@@ -53,13 +49,13 @@ You can find the full documentation [here](https://orpc.unnoq.com).
|
|
|
53
49
|
- [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
|
|
54
50
|
- [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
|
|
55
51
|
- [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
|
|
52
|
+
- [@orpc/openapi](https://www.npmjs.com/package/@orpc/openapi): Generate OpenAPI specs and handle OpenAPI requests.
|
|
53
|
+
- [@orpc/otel](https://www.npmjs.com/package/@orpc/otel): [OpenTelemetry](https://opentelemetry.io/) integration for observability.
|
|
54
|
+
- [@orpc/nest](https://www.npmjs.com/package/@orpc/nest): Deeply integrate oRPC with [NestJS](https://nestjs.com/).
|
|
56
55
|
- [@orpc/react](https://www.npmjs.com/package/@orpc/react): Utilities for integrating oRPC with React and React Server Actions.
|
|
57
|
-
- [@orpc/
|
|
58
|
-
- [@orpc/vue-query](https://www.npmjs.com/package/@orpc/vue-query): Integration with [Vue Query](https://tanstack.com/query/latest/docs/framework/vue/overview).
|
|
59
|
-
- [@orpc/solid-query](https://www.npmjs.com/package/@orpc/solid-query): Integration with [Solid Query](https://tanstack.com/query/latest/docs/framework/solid/overview).
|
|
60
|
-
- [@orpc/svelte-query](https://www.npmjs.com/package/@orpc/svelte-query): Integration with [Svelte Query](https://tanstack.com/query/latest/docs/framework/svelte/overview).
|
|
56
|
+
- [@orpc/tanstack-query](https://www.npmjs.com/package/@orpc/tanstack-query): [TanStack Query](https://tanstack.com/query/latest) integration.
|
|
61
57
|
- [@orpc/vue-colada](https://www.npmjs.com/package/@orpc/vue-colada): Integration with [Pinia Colada](https://pinia-colada.esm.dev/).
|
|
62
|
-
- [@orpc/
|
|
58
|
+
- [@orpc/hey-api](https://www.npmjs.com/package/@orpc/hey-api): [Hey API](https://heyapi.dev/) integration.
|
|
63
59
|
- [@orpc/zod](https://www.npmjs.com/package/@orpc/zod): More schemas that [Zod](https://zod.dev/) doesn't support yet.
|
|
64
60
|
- [@orpc/valibot](https://www.npmjs.com/package/@orpc/valibot): OpenAPI spec generation from [Valibot](https://valibot.dev/).
|
|
65
61
|
- [@orpc/arktype](https://www.npmjs.com/package/@orpc/arktype): OpenAPI spec generation from [ArkType](https://arktype.io/).
|
package/dist/index.d.mts
CHANGED
|
@@ -3,6 +3,8 @@ export { HTTPMethod, HTTPPath, ORPCError } from '@orpc/client';
|
|
|
3
3
|
import { Promisable, IsEqual, ThrowableError } from '@orpc/shared';
|
|
4
4
|
export { Registry, ThrowableError } from '@orpc/shared';
|
|
5
5
|
import { StandardSchemaV1 } from '@standard-schema/spec';
|
|
6
|
+
import { OpenAPIV3_1 } from 'openapi-types';
|
|
7
|
+
export { OpenAPIV3_1 as OpenAPI } from 'openapi-types';
|
|
6
8
|
|
|
7
9
|
type Schema<TInput, TOutput> = StandardSchemaV1<TInput, TOutput>;
|
|
8
10
|
type AnySchema = Schema<any, any>;
|
|
@@ -10,12 +12,23 @@ type SchemaIssue = StandardSchemaV1.Issue;
|
|
|
10
12
|
type InferSchemaInput<T extends AnySchema> = T extends StandardSchemaV1<infer UInput, any> ? UInput : never;
|
|
11
13
|
type InferSchemaOutput<T extends AnySchema> = T extends StandardSchemaV1<any, infer UOutput> ? UOutput : never;
|
|
12
14
|
type TypeRest<TInput, TOutput> = [map: (input: TInput) => Promisable<TOutput>] | (IsEqual<TInput, TOutput> extends true ? [] : never);
|
|
15
|
+
/**
|
|
16
|
+
* The schema for things can be trust without validation.
|
|
17
|
+
* If the TInput and TOutput are different, you need pass a map function.
|
|
18
|
+
*
|
|
19
|
+
* @see {@link https://orpc.unnoq.com/docs/procedure#type-utility Type Utility Docs}
|
|
20
|
+
*/
|
|
13
21
|
declare function type<TInput, TOutput = TInput>(...[map]: TypeRest<TInput, TOutput>): Schema<TInput, TOutput>;
|
|
14
22
|
|
|
15
23
|
interface ValidationErrorOptions extends ErrorOptions {
|
|
16
24
|
message: string;
|
|
17
25
|
issues: readonly SchemaIssue[];
|
|
18
26
|
}
|
|
27
|
+
/**
|
|
28
|
+
* This errors usually used for ORPCError.cause when the error is a validation error.
|
|
29
|
+
*
|
|
30
|
+
* @see {@link https://orpc.unnoq.com/docs/advanced/validation-errors Validation Errors Docs}
|
|
31
|
+
*/
|
|
19
32
|
declare class ValidationError extends Error {
|
|
20
33
|
readonly issues: readonly SchemaIssue[];
|
|
21
34
|
constructor(options: ValidationErrorOptions);
|
|
@@ -41,21 +54,69 @@ declare function mergeMeta<T extends Meta>(meta1: T, meta2: T): T;
|
|
|
41
54
|
type InputStructure = 'compact' | 'detailed';
|
|
42
55
|
type OutputStructure = 'compact' | 'detailed';
|
|
43
56
|
interface Route {
|
|
57
|
+
/**
|
|
58
|
+
* The HTTP method of the procedure.
|
|
59
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
60
|
+
*
|
|
61
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
62
|
+
*/
|
|
44
63
|
method?: HTTPMethod;
|
|
64
|
+
/**
|
|
65
|
+
* The HTTP path of the procedure.
|
|
66
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
67
|
+
*
|
|
68
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
69
|
+
*/
|
|
45
70
|
path?: HTTPPath;
|
|
71
|
+
/**
|
|
72
|
+
* The operation ID of the endpoint.
|
|
73
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
74
|
+
*
|
|
75
|
+
* @default Concatenation of router segments
|
|
76
|
+
*/
|
|
77
|
+
operationId?: string;
|
|
78
|
+
/**
|
|
79
|
+
* The summary of the procedure.
|
|
80
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
81
|
+
*
|
|
82
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
|
|
83
|
+
*/
|
|
46
84
|
summary?: string;
|
|
85
|
+
/**
|
|
86
|
+
* The description of the procedure.
|
|
87
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
88
|
+
*
|
|
89
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
|
|
90
|
+
*/
|
|
47
91
|
description?: string;
|
|
92
|
+
/**
|
|
93
|
+
* Marks the procedure as deprecated.
|
|
94
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
95
|
+
*
|
|
96
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
|
|
97
|
+
*/
|
|
48
98
|
deprecated?: boolean;
|
|
99
|
+
/**
|
|
100
|
+
* The tags of the procedure.
|
|
101
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
102
|
+
*
|
|
103
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
|
|
104
|
+
*/
|
|
49
105
|
tags?: readonly string[];
|
|
50
106
|
/**
|
|
51
107
|
* The status code of the response when the procedure is successful.
|
|
108
|
+
* The status code must be in the 200-399 range.
|
|
109
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
52
110
|
*
|
|
111
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
53
112
|
* @default 200
|
|
54
113
|
*/
|
|
55
114
|
successStatus?: number;
|
|
56
115
|
/**
|
|
57
116
|
* The description of the response when the procedure is successful.
|
|
117
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
58
118
|
*
|
|
119
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
|
|
59
120
|
* @default 'OK'
|
|
60
121
|
*/
|
|
61
122
|
successDescription?: string;
|
|
@@ -78,6 +139,7 @@ interface Route {
|
|
|
78
139
|
* }
|
|
79
140
|
* ```
|
|
80
141
|
*
|
|
142
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
81
143
|
* @default 'compact'
|
|
82
144
|
*/
|
|
83
145
|
inputStructure?: InputStructure;
|
|
@@ -85,24 +147,33 @@ interface Route {
|
|
|
85
147
|
* Determines how the response should be structured based on the output.
|
|
86
148
|
*
|
|
87
149
|
* @option 'compact'
|
|
88
|
-
*
|
|
150
|
+
* The output data is directly returned as the response body.
|
|
89
151
|
*
|
|
90
152
|
* @option 'detailed'
|
|
91
|
-
*
|
|
92
|
-
* - `
|
|
93
|
-
* - `
|
|
153
|
+
* Return an object with optional properties:
|
|
154
|
+
* - `status`: The response status (must be in 200-399 range) if not set fallback to `successStatus`.
|
|
155
|
+
* - `headers`: Custom headers to merge with the response headers (`Record<string, string | string[] | undefined>`)
|
|
156
|
+
* - `body`: The response body.
|
|
94
157
|
*
|
|
95
158
|
* Example:
|
|
96
159
|
* ```ts
|
|
97
160
|
* const output = {
|
|
161
|
+
* status: 201,
|
|
98
162
|
* headers: { 'x-custom-header': 'value' },
|
|
99
163
|
* body: { message: 'Hello, world!' },
|
|
100
164
|
* };
|
|
101
165
|
* ```
|
|
102
166
|
*
|
|
167
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
103
168
|
* @default 'compact'
|
|
104
169
|
*/
|
|
105
170
|
outputStructure?: OutputStructure;
|
|
171
|
+
/**
|
|
172
|
+
* Override entire auto-generated OpenAPI Operation Object Specification.
|
|
173
|
+
*
|
|
174
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata Operation Metadata Docs}
|
|
175
|
+
*/
|
|
176
|
+
spec?: OpenAPIV3_1.OperationObject | ((current: OpenAPIV3_1.OperationObject) => OpenAPIV3_1.OperationObject);
|
|
106
177
|
}
|
|
107
178
|
declare function mergeRoute(a: Route, b: Route): Route;
|
|
108
179
|
declare function prefixRoute(route: Route, prefix: HTTPPath): Route;
|
|
@@ -122,23 +193,55 @@ interface ContractProcedureDef<TInputSchema extends AnySchema, TOutputSchema ext
|
|
|
122
193
|
outputSchema?: TOutputSchema;
|
|
123
194
|
errorMap: TErrorMap;
|
|
124
195
|
}
|
|
196
|
+
/**
|
|
197
|
+
* This class represents a contract procedure.
|
|
198
|
+
*
|
|
199
|
+
* @see {@link https://orpc.unnoq.com/docs/contract-first/define-contract#procedure-contract Contract Procedure Docs}
|
|
200
|
+
*/
|
|
125
201
|
declare class ContractProcedure<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap, TMeta extends Meta> {
|
|
202
|
+
/**
|
|
203
|
+
* This property holds the defined options for the contract procedure.
|
|
204
|
+
*/
|
|
126
205
|
'~orpc': ContractProcedureDef<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
127
206
|
constructor(def: ContractProcedureDef<TInputSchema, TOutputSchema, TErrorMap, TMeta>);
|
|
128
207
|
}
|
|
129
208
|
type AnyContractProcedure = ContractProcedure<any, any, any, any>;
|
|
130
209
|
declare function isContractProcedure(item: unknown): item is AnyContractProcedure;
|
|
131
210
|
|
|
211
|
+
/**
|
|
212
|
+
* Represents a contract router, which defines a hierarchical structure of contract procedures.
|
|
213
|
+
*
|
|
214
|
+
* @info A contract procedure is a contract router too.
|
|
215
|
+
* @see {@link https://orpc.unnoq.com/docs/contract-first/define-contract#contract-router Contract Router Docs}
|
|
216
|
+
*/
|
|
132
217
|
type ContractRouter<TMeta extends Meta> = ContractProcedure<any, any, any, TMeta> | {
|
|
133
218
|
[k: string]: ContractRouter<TMeta>;
|
|
134
219
|
};
|
|
135
220
|
type AnyContractRouter = ContractRouter<any>;
|
|
221
|
+
/**
|
|
222
|
+
* Infer all inputs of the contract router.
|
|
223
|
+
*
|
|
224
|
+
* @info A contract procedure is a contract router too.
|
|
225
|
+
* @see {@link https://orpc.unnoq.com/docs/contract-first/define-contract#utilities Contract Utilities Docs}
|
|
226
|
+
*/
|
|
136
227
|
type InferContractRouterInputs<T extends AnyContractRouter> = T extends ContractProcedure<infer UInputSchema, any, any, any> ? InferSchemaInput<UInputSchema> : {
|
|
137
228
|
[K in keyof T]: T[K] extends AnyContractRouter ? InferContractRouterInputs<T[K]> : never;
|
|
138
229
|
};
|
|
230
|
+
/**
|
|
231
|
+
* Infer all outputs of the contract router.
|
|
232
|
+
*
|
|
233
|
+
* @info A contract procedure is a contract router too.
|
|
234
|
+
* @see {@link https://orpc.unnoq.com/docs/contract-first/define-contract#utilities Contract Utilities Docs}
|
|
235
|
+
*/
|
|
139
236
|
type InferContractRouterOutputs<T extends AnyContractRouter> = T extends ContractProcedure<any, infer UOutputSchema, any, any> ? InferSchemaOutput<UOutputSchema> : {
|
|
140
237
|
[K in keyof T]: T[K] extends AnyContractRouter ? InferContractRouterOutputs<T[K]> : never;
|
|
141
238
|
};
|
|
239
|
+
/**
|
|
240
|
+
* Infer all errors of the contract router.
|
|
241
|
+
*
|
|
242
|
+
* @info A contract procedure is a contract router too.
|
|
243
|
+
* @see {@link https://orpc.unnoq.com/docs/contract-first/define-contract#utilities Contract Utilities Docs}
|
|
244
|
+
*/
|
|
142
245
|
type InferContractRouterErrorMap<T extends AnyContractRouter> = T extends ContractProcedure<any, any, infer UErrorMap, any> ? UErrorMap : {
|
|
143
246
|
[K in keyof T]: T[K] extends AnyContractRouter ? InferContractRouterErrorMap<T[K]> : never;
|
|
144
247
|
}[keyof T];
|
|
@@ -152,59 +255,254 @@ interface EnhanceContractRouterOptions<TErrorMap extends ErrorMap> extends Enhan
|
|
|
152
255
|
errorMap: TErrorMap;
|
|
153
256
|
}
|
|
154
257
|
declare function enhanceContractRouter<T extends AnyContractRouter, TErrorMap extends ErrorMap>(router: T, options: EnhanceContractRouterOptions<TErrorMap>): EnhancedContractRouter<T, TErrorMap>;
|
|
258
|
+
/**
|
|
259
|
+
* Minify a contract router into a smaller object.
|
|
260
|
+
*
|
|
261
|
+
* You should export the result to a JSON file. On the client side, you can import this JSON file and use it as a contract router.
|
|
262
|
+
* This reduces the size of the contract and helps prevent leaking internal details of the router to the client.
|
|
263
|
+
*
|
|
264
|
+
* @see {@link https://orpc.unnoq.com/docs/contract-first/router-to-contract#minify-export-the-contract-router-for-the-client Router to Contract Docs}
|
|
265
|
+
*/
|
|
266
|
+
declare function minifyContractRouter(router: AnyContractRouter): AnyContractRouter;
|
|
155
267
|
|
|
156
268
|
interface ContractProcedureBuilder<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap, TMeta extends Meta> extends ContractProcedure<TInputSchema, TOutputSchema, TErrorMap, TMeta> {
|
|
269
|
+
/**
|
|
270
|
+
* Adds type-safe custom errors to the contract.
|
|
271
|
+
* The provided errors are spared-merged with any existing errors in the contract.
|
|
272
|
+
*
|
|
273
|
+
* @see {@link https://orpc.unnoq.com/docs/error-handling#type%E2%80%90safe-error-handling Type-Safe Error Handling Docs}
|
|
274
|
+
*/
|
|
157
275
|
errors<U extends ErrorMap>(errors: U): ContractProcedureBuilder<TInputSchema, TOutputSchema, MergedErrorMap<TErrorMap, U>, TMeta>;
|
|
276
|
+
/**
|
|
277
|
+
* Sets or updates the metadata for the contract.
|
|
278
|
+
* The provided metadata is spared-merged with any existing metadata in the contract.
|
|
279
|
+
*
|
|
280
|
+
* @see {@link https://orpc.unnoq.com/docs/metadata Metadata Docs}
|
|
281
|
+
*/
|
|
158
282
|
meta(meta: TMeta): ContractProcedureBuilder<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
283
|
+
/**
|
|
284
|
+
* Sets or updates the route definition for the contract.
|
|
285
|
+
* The provided route is spared-merged with any existing route in the contract.
|
|
286
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
287
|
+
*
|
|
288
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
289
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
290
|
+
*/
|
|
159
291
|
route(route: Route): ContractProcedureBuilder<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
292
|
+
/**
|
|
293
|
+
* Defines the input validation schema for the contract.
|
|
294
|
+
*
|
|
295
|
+
* @see {@link https://orpc.unnoq.com/docs/procedure#input-output-validation Input Validation Docs}
|
|
296
|
+
*/
|
|
160
297
|
input<U extends AnySchema>(schema: U): ContractProcedureBuilderWithInput<U, TOutputSchema, TErrorMap, TMeta>;
|
|
298
|
+
/**
|
|
299
|
+
* Defines the output validation schema for the contract.
|
|
300
|
+
*
|
|
301
|
+
* @see {@link https://orpc.unnoq.com/docs/procedure#input-output-validation Output Validation Docs}
|
|
302
|
+
*/
|
|
161
303
|
output<U extends AnySchema>(schema: U): ContractProcedureBuilderWithOutput<TInputSchema, U, TErrorMap, TMeta>;
|
|
162
304
|
}
|
|
163
305
|
interface ContractProcedureBuilderWithInput<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap, TMeta extends Meta> extends ContractProcedure<TInputSchema, TOutputSchema, TErrorMap, TMeta> {
|
|
306
|
+
/**
|
|
307
|
+
* Adds type-safe custom errors to the contract.
|
|
308
|
+
* The provided errors are spared-merged with any existing errors in the contract.
|
|
309
|
+
*
|
|
310
|
+
* @see {@link https://orpc.unnoq.com/docs/error-handling#type%E2%80%90safe-error-handling Type-Safe Error Handling Docs}
|
|
311
|
+
*/
|
|
164
312
|
errors<U extends ErrorMap>(errors: U): ContractProcedureBuilderWithInput<TInputSchema, TOutputSchema, MergedErrorMap<TErrorMap, U>, TMeta>;
|
|
313
|
+
/**
|
|
314
|
+
* Sets or updates the metadata for the contract.
|
|
315
|
+
* The provided metadata is spared-merged with any existing metadata in the contract.
|
|
316
|
+
*
|
|
317
|
+
* @see {@link https://orpc.unnoq.com/docs/metadata Metadata Docs}
|
|
318
|
+
*/
|
|
165
319
|
meta(meta: TMeta): ContractProcedureBuilderWithInput<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
320
|
+
/**
|
|
321
|
+
* Sets or updates the route definition for the contract.
|
|
322
|
+
* The provided route is spared-merged with any existing route in the contract.
|
|
323
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
324
|
+
*
|
|
325
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
326
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
327
|
+
*/
|
|
166
328
|
route(route: Route): ContractProcedureBuilderWithInput<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
329
|
+
/**
|
|
330
|
+
* Defines the output validation schema for the contract.
|
|
331
|
+
*
|
|
332
|
+
* @see {@link https://orpc.unnoq.com/docs/procedure#input-output-validation Output Validation Docs}
|
|
333
|
+
*/
|
|
167
334
|
output<U extends AnySchema>(schema: U): ContractProcedureBuilderWithInputOutput<TInputSchema, U, TErrorMap, TMeta>;
|
|
168
335
|
}
|
|
169
336
|
interface ContractProcedureBuilderWithOutput<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap, TMeta extends Meta> extends ContractProcedure<TInputSchema, TOutputSchema, TErrorMap, TMeta> {
|
|
337
|
+
/**
|
|
338
|
+
* Adds type-safe custom errors to the contract.
|
|
339
|
+
* The provided errors are spared-merged with any existing errors in the contract.
|
|
340
|
+
*
|
|
341
|
+
* @see {@link https://orpc.unnoq.com/docs/error-handling#type%E2%80%90safe-error-handling Type-Safe Error Handling Docs}
|
|
342
|
+
*/
|
|
170
343
|
errors<U extends ErrorMap>(errors: U): ContractProcedureBuilderWithOutput<TInputSchema, TOutputSchema, MergedErrorMap<TErrorMap, U>, TMeta>;
|
|
344
|
+
/**
|
|
345
|
+
* Sets or updates the metadata for the contract.
|
|
346
|
+
* The provided metadata is spared-merged with any existing metadata in the contract.
|
|
347
|
+
*
|
|
348
|
+
* @see {@link https://orpc.unnoq.com/docs/metadata Metadata Docs}
|
|
349
|
+
*/
|
|
171
350
|
meta(meta: TMeta): ContractProcedureBuilderWithOutput<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
351
|
+
/**
|
|
352
|
+
* Sets or updates the route definition for the contract.
|
|
353
|
+
* The provided route is spared-merged with any existing route in the contract.
|
|
354
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
355
|
+
*
|
|
356
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
357
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
358
|
+
*/
|
|
172
359
|
route(route: Route): ContractProcedureBuilderWithOutput<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
360
|
+
/**
|
|
361
|
+
* Defines the input validation schema for the contract.
|
|
362
|
+
*
|
|
363
|
+
* @see {@link https://orpc.unnoq.com/docs/procedure#input-output-validation Input Validation Docs}
|
|
364
|
+
*/
|
|
173
365
|
input<U extends AnySchema>(schema: U): ContractProcedureBuilderWithInputOutput<U, TOutputSchema, TErrorMap, TMeta>;
|
|
174
366
|
}
|
|
175
367
|
interface ContractProcedureBuilderWithInputOutput<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap, TMeta extends Meta> extends ContractProcedure<TInputSchema, TOutputSchema, TErrorMap, TMeta> {
|
|
368
|
+
/**
|
|
369
|
+
* Adds type-safe custom errors to the contract.
|
|
370
|
+
* The provided errors are spared-merged with any existing errors in the contract.
|
|
371
|
+
*
|
|
372
|
+
* @see {@link https://orpc.unnoq.com/docs/error-handling#type%E2%80%90safe-error-handling Type-Safe Error Handling Docs}
|
|
373
|
+
*/
|
|
176
374
|
errors<U extends ErrorMap>(errors: U): ContractProcedureBuilderWithInputOutput<TInputSchema, TOutputSchema, MergedErrorMap<TErrorMap, U>, TMeta>;
|
|
375
|
+
/**
|
|
376
|
+
* Sets or updates the metadata for the contract.
|
|
377
|
+
* The provided metadata is spared-merged with any existing metadata in the contract.
|
|
378
|
+
*
|
|
379
|
+
* @see {@link https://orpc.unnoq.com/docs/metadata Metadata Docs}
|
|
380
|
+
*/
|
|
177
381
|
meta(meta: TMeta): ContractProcedureBuilderWithInputOutput<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
382
|
+
/**
|
|
383
|
+
* Sets or updates the route definition for the contract.
|
|
384
|
+
* The provided route is spared-merged with any existing route in the contract.
|
|
385
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
386
|
+
*
|
|
387
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
388
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
389
|
+
*/
|
|
178
390
|
route(route: Route): ContractProcedureBuilderWithInputOutput<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
179
391
|
}
|
|
180
392
|
interface ContractRouterBuilder<TErrorMap extends ErrorMap, TMeta extends Meta> {
|
|
393
|
+
/**
|
|
394
|
+
* This property holds the defined options for the contract router.
|
|
395
|
+
*/
|
|
181
396
|
'~orpc': EnhanceContractRouterOptions<TErrorMap>;
|
|
397
|
+
/**
|
|
398
|
+
* Adds type-safe custom errors to the contract.
|
|
399
|
+
* The provided errors are spared-merged with any existing errors in the contract.
|
|
400
|
+
*
|
|
401
|
+
* @see {@link https://orpc.unnoq.com/docs/error-handling#type%E2%80%90safe-error-handling Type-Safe Error Handling Docs}
|
|
402
|
+
*/
|
|
182
403
|
'errors'<U extends ErrorMap>(errors: U): ContractRouterBuilder<MergedErrorMap<TErrorMap, U>, TMeta>;
|
|
404
|
+
/**
|
|
405
|
+
* Prefixes all procedures in the contract router.
|
|
406
|
+
* The provided prefix is post-appended to any existing router prefix.
|
|
407
|
+
*
|
|
408
|
+
* @note This option does not affect procedures that do not define a path in their route definition.
|
|
409
|
+
*
|
|
410
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing#route-prefixes OpenAPI Route Prefixes Docs}
|
|
411
|
+
*/
|
|
183
412
|
'prefix'(prefix: HTTPPath): ContractRouterBuilder<TErrorMap, TMeta>;
|
|
413
|
+
/**
|
|
414
|
+
* Adds tags to all procedures in the contract router.
|
|
415
|
+
* This helpful when you want to group procedures together in the OpenAPI specification.
|
|
416
|
+
*
|
|
417
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
|
|
418
|
+
*/
|
|
184
419
|
'tag'(...tags: string[]): ContractRouterBuilder<TErrorMap, TMeta>;
|
|
420
|
+
/**
|
|
421
|
+
* Applies all of the previously defined options to the specified contract router.
|
|
422
|
+
*
|
|
423
|
+
* @see {@link https://orpc.unnoq.com/docs/router#extending-router Extending Router Docs}
|
|
424
|
+
*/
|
|
185
425
|
'router'<T extends ContractRouter<TMeta>>(router: T): EnhancedContractRouter<T, TErrorMap>;
|
|
186
426
|
}
|
|
187
427
|
|
|
188
428
|
interface ContractBuilderDef<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap, TMeta extends Meta> extends ContractProcedureDef<TInputSchema, TOutputSchema, TErrorMap, TMeta>, EnhanceContractRouterOptions<TErrorMap> {
|
|
189
429
|
}
|
|
190
430
|
declare class ContractBuilder<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap, TMeta extends Meta> extends ContractProcedure<TInputSchema, TOutputSchema, TErrorMap, TMeta> {
|
|
431
|
+
/**
|
|
432
|
+
* This property holds the defined options for the contract.
|
|
433
|
+
*/
|
|
191
434
|
'~orpc': ContractBuilderDef<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
192
435
|
constructor(def: ContractBuilderDef<TInputSchema, TOutputSchema, TErrorMap, TMeta>);
|
|
193
436
|
/**
|
|
194
|
-
*
|
|
437
|
+
* Sets or overrides the initial meta.
|
|
438
|
+
*
|
|
439
|
+
* @see {@link https://orpc.unnoq.com/docs/metadata Metadata Docs}
|
|
195
440
|
*/
|
|
196
441
|
$meta<U extends Meta>(initialMeta: U): ContractBuilder<TInputSchema, TOutputSchema, TErrorMap, U & Record<never, never>>;
|
|
197
442
|
/**
|
|
198
|
-
*
|
|
443
|
+
* Sets or overrides the initial route.
|
|
444
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
445
|
+
*
|
|
446
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
447
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
199
448
|
*/
|
|
200
449
|
$route(initialRoute: Route): ContractBuilder<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
450
|
+
/**
|
|
451
|
+
* Adds type-safe custom errors to the contract.
|
|
452
|
+
* The provided errors are spared-merged with any existing errors in the contract.
|
|
453
|
+
*
|
|
454
|
+
* @see {@link https://orpc.unnoq.com/docs/error-handling#type%E2%80%90safe-error-handling Type-Safe Error Handling Docs}
|
|
455
|
+
*/
|
|
201
456
|
errors<U extends ErrorMap>(errors: U): ContractBuilder<TInputSchema, TOutputSchema, MergedErrorMap<TErrorMap, U>, TMeta>;
|
|
457
|
+
/**
|
|
458
|
+
* Sets or updates the metadata for the contract.
|
|
459
|
+
* The provided metadata is spared-merged with any existing metadata in the contract.
|
|
460
|
+
*
|
|
461
|
+
* @see {@link https://orpc.unnoq.com/docs/metadata Metadata Docs}
|
|
462
|
+
*/
|
|
202
463
|
meta(meta: TMeta): ContractProcedureBuilder<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
464
|
+
/**
|
|
465
|
+
* Sets or updates the route definition for the contract.
|
|
466
|
+
* The provided route is spared-merged with any existing route in the contract.
|
|
467
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
468
|
+
*
|
|
469
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
470
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
471
|
+
*/
|
|
203
472
|
route(route: Route): ContractProcedureBuilder<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
473
|
+
/**
|
|
474
|
+
* Defines the input validation schema for the contract.
|
|
475
|
+
*
|
|
476
|
+
* @see {@link https://orpc.unnoq.com/docs/procedure#input-output-validation Input Validation Docs}
|
|
477
|
+
*/
|
|
204
478
|
input<U extends AnySchema>(schema: U): ContractProcedureBuilderWithInput<U, TOutputSchema, TErrorMap, TMeta>;
|
|
479
|
+
/**
|
|
480
|
+
* Defines the output validation schema for the contract.
|
|
481
|
+
*
|
|
482
|
+
* @see {@link https://orpc.unnoq.com/docs/procedure#input-output-validation Output Validation Docs}
|
|
483
|
+
*/
|
|
205
484
|
output<U extends AnySchema>(schema: U): ContractProcedureBuilderWithOutput<TInputSchema, U, TErrorMap, TMeta>;
|
|
485
|
+
/**
|
|
486
|
+
* Prefixes all procedures in the contract router.
|
|
487
|
+
* The provided prefix is post-appended to any existing router prefix.
|
|
488
|
+
*
|
|
489
|
+
* @note This option does not affect procedures that do not define a path in their route definition.
|
|
490
|
+
*
|
|
491
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing#route-prefixes OpenAPI Route Prefixes Docs}
|
|
492
|
+
*/
|
|
206
493
|
prefix(prefix: HTTPPath): ContractRouterBuilder<TErrorMap, TMeta>;
|
|
494
|
+
/**
|
|
495
|
+
* Adds tags to all procedures in the contract router.
|
|
496
|
+
* This helpful when you want to group procedures together in the OpenAPI specification.
|
|
497
|
+
*
|
|
498
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
|
|
499
|
+
*/
|
|
207
500
|
tag(...tags: string[]): ContractRouterBuilder<TErrorMap, TMeta>;
|
|
501
|
+
/**
|
|
502
|
+
* Applies all of the previously defined options to the specified contract router.
|
|
503
|
+
*
|
|
504
|
+
* @see {@link https://orpc.unnoq.com/docs/router#extending-router Extending Router Docs}
|
|
505
|
+
*/
|
|
208
506
|
router<T extends ContractRouter<TMeta>>(router: T): EnhancedContractRouter<T, TErrorMap>;
|
|
209
507
|
}
|
|
210
508
|
declare const oc: ContractBuilder<Schema<unknown, unknown>, Schema<unknown, unknown>, Record<never, never>, Record<never, never>>;
|
|
@@ -222,13 +520,28 @@ interface EventIteratorSchemaDetails {
|
|
|
222
520
|
yields: AnySchema;
|
|
223
521
|
returns?: AnySchema;
|
|
224
522
|
}
|
|
523
|
+
/**
|
|
524
|
+
* Define schema for an event iterator.
|
|
525
|
+
*
|
|
526
|
+
* @see {@link https://orpc.unnoq.com/docs/event-iterator#validate-event-iterator Validate Event Iterator Docs}
|
|
527
|
+
*/
|
|
225
528
|
declare function eventIterator<TYieldIn, TYieldOut, TReturnIn = unknown, TReturnOut = unknown>(yields: Schema<TYieldIn, TYieldOut>, returns?: Schema<TReturnIn, TReturnOut>): Schema<AsyncIteratorObject<TYieldIn, TReturnIn, void>, AsyncIteratorObject<TYieldOut, TReturnOut, void>>;
|
|
226
529
|
declare function getEventIteratorSchemaDetails(schema: AnySchema | undefined): undefined | EventIteratorSchemaDetails;
|
|
227
530
|
|
|
531
|
+
/**
|
|
532
|
+
* Help RPCLink automatically send requests using the specified HTTP method in the contract.
|
|
533
|
+
*
|
|
534
|
+
* @see {@link https://orpc.unnoq.com/docs/client/rpc-link#custom-request-method RPCLink Custom Request Method}
|
|
535
|
+
*/
|
|
536
|
+
declare function inferRPCMethodFromContractRouter(contract: AnyContractRouter): (options: unknown, path: readonly string[]) => Exclude<HTTPMethod, 'HEAD'>;
|
|
537
|
+
|
|
228
538
|
type ContractProcedureClient<TClientContext extends ClientContext, TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap> = Client<TClientContext, InferSchemaInput<TInputSchema>, InferSchemaOutput<TOutputSchema>, ErrorFromErrorMap<TErrorMap>>;
|
|
229
539
|
|
|
230
540
|
type ContractRouterClient<TRouter extends AnyContractRouter, TClientContext extends ClientContext = Record<never, never>> = TRouter extends ContractProcedure<infer UInputSchema, infer UOutputSchema, infer UErrorMap, any> ? ContractProcedureClient<TClientContext, UInputSchema, UOutputSchema, UErrorMap> : {
|
|
231
541
|
[K in keyof TRouter]: TRouter[K] extends AnyContractRouter ? ContractRouterClient<TRouter[K], TClientContext> : never;
|
|
232
542
|
};
|
|
233
543
|
|
|
234
|
-
|
|
544
|
+
declare function isSchemaIssue(issue: unknown): issue is SchemaIssue;
|
|
545
|
+
|
|
546
|
+
export { ContractBuilder, ContractProcedure, ValidationError, enhanceContractRouter, enhanceRoute, eventIterator, fallbackContractConfig, getContractRouter, getEventIteratorSchemaDetails, inferRPCMethodFromContractRouter, isContractProcedure, isSchemaIssue, mergeErrorMap, mergeMeta, mergePrefix, mergeRoute, mergeTags, minifyContractRouter, oc, prefixRoute, type, unshiftTagRoute };
|
|
547
|
+
export type { AnyContractProcedure, AnyContractRouter, AnySchema, ContractBuilderDef, ContractConfig, ContractProcedureBuilder, ContractProcedureBuilderWithInput, ContractProcedureBuilderWithInputOutput, ContractProcedureBuilderWithOutput, ContractProcedureClient, ContractProcedureDef, ContractRouter, ContractRouterBuilder, ContractRouterClient, EnhanceContractRouterOptions, EnhanceRouteOptions, EnhancedContractRouter, ErrorFromErrorMap, ErrorMap, ErrorMapItem, EventIteratorSchemaDetails, InferContractRouterErrorMap, InferContractRouterInputs, InferContractRouterMeta, InferContractRouterOutputs, InferSchemaInput, InferSchemaOutput, InputStructure, MergedErrorMap, Meta, ORPCErrorFromErrorMap, OutputStructure, Route, Schema, SchemaIssue, TypeRest, ValidationErrorOptions };
|
package/dist/index.d.ts
CHANGED
|
@@ -3,6 +3,8 @@ export { HTTPMethod, HTTPPath, ORPCError } from '@orpc/client';
|
|
|
3
3
|
import { Promisable, IsEqual, ThrowableError } from '@orpc/shared';
|
|
4
4
|
export { Registry, ThrowableError } from '@orpc/shared';
|
|
5
5
|
import { StandardSchemaV1 } from '@standard-schema/spec';
|
|
6
|
+
import { OpenAPIV3_1 } from 'openapi-types';
|
|
7
|
+
export { OpenAPIV3_1 as OpenAPI } from 'openapi-types';
|
|
6
8
|
|
|
7
9
|
type Schema<TInput, TOutput> = StandardSchemaV1<TInput, TOutput>;
|
|
8
10
|
type AnySchema = Schema<any, any>;
|
|
@@ -10,12 +12,23 @@ type SchemaIssue = StandardSchemaV1.Issue;
|
|
|
10
12
|
type InferSchemaInput<T extends AnySchema> = T extends StandardSchemaV1<infer UInput, any> ? UInput : never;
|
|
11
13
|
type InferSchemaOutput<T extends AnySchema> = T extends StandardSchemaV1<any, infer UOutput> ? UOutput : never;
|
|
12
14
|
type TypeRest<TInput, TOutput> = [map: (input: TInput) => Promisable<TOutput>] | (IsEqual<TInput, TOutput> extends true ? [] : never);
|
|
15
|
+
/**
|
|
16
|
+
* The schema for things can be trust without validation.
|
|
17
|
+
* If the TInput and TOutput are different, you need pass a map function.
|
|
18
|
+
*
|
|
19
|
+
* @see {@link https://orpc.unnoq.com/docs/procedure#type-utility Type Utility Docs}
|
|
20
|
+
*/
|
|
13
21
|
declare function type<TInput, TOutput = TInput>(...[map]: TypeRest<TInput, TOutput>): Schema<TInput, TOutput>;
|
|
14
22
|
|
|
15
23
|
interface ValidationErrorOptions extends ErrorOptions {
|
|
16
24
|
message: string;
|
|
17
25
|
issues: readonly SchemaIssue[];
|
|
18
26
|
}
|
|
27
|
+
/**
|
|
28
|
+
* This errors usually used for ORPCError.cause when the error is a validation error.
|
|
29
|
+
*
|
|
30
|
+
* @see {@link https://orpc.unnoq.com/docs/advanced/validation-errors Validation Errors Docs}
|
|
31
|
+
*/
|
|
19
32
|
declare class ValidationError extends Error {
|
|
20
33
|
readonly issues: readonly SchemaIssue[];
|
|
21
34
|
constructor(options: ValidationErrorOptions);
|
|
@@ -41,21 +54,69 @@ declare function mergeMeta<T extends Meta>(meta1: T, meta2: T): T;
|
|
|
41
54
|
type InputStructure = 'compact' | 'detailed';
|
|
42
55
|
type OutputStructure = 'compact' | 'detailed';
|
|
43
56
|
interface Route {
|
|
57
|
+
/**
|
|
58
|
+
* The HTTP method of the procedure.
|
|
59
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
60
|
+
*
|
|
61
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
62
|
+
*/
|
|
44
63
|
method?: HTTPMethod;
|
|
64
|
+
/**
|
|
65
|
+
* The HTTP path of the procedure.
|
|
66
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
67
|
+
*
|
|
68
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
69
|
+
*/
|
|
45
70
|
path?: HTTPPath;
|
|
71
|
+
/**
|
|
72
|
+
* The operation ID of the endpoint.
|
|
73
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
74
|
+
*
|
|
75
|
+
* @default Concatenation of router segments
|
|
76
|
+
*/
|
|
77
|
+
operationId?: string;
|
|
78
|
+
/**
|
|
79
|
+
* The summary of the procedure.
|
|
80
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
81
|
+
*
|
|
82
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
|
|
83
|
+
*/
|
|
46
84
|
summary?: string;
|
|
85
|
+
/**
|
|
86
|
+
* The description of the procedure.
|
|
87
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
88
|
+
*
|
|
89
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
|
|
90
|
+
*/
|
|
47
91
|
description?: string;
|
|
92
|
+
/**
|
|
93
|
+
* Marks the procedure as deprecated.
|
|
94
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
95
|
+
*
|
|
96
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
|
|
97
|
+
*/
|
|
48
98
|
deprecated?: boolean;
|
|
99
|
+
/**
|
|
100
|
+
* The tags of the procedure.
|
|
101
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
102
|
+
*
|
|
103
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
|
|
104
|
+
*/
|
|
49
105
|
tags?: readonly string[];
|
|
50
106
|
/**
|
|
51
107
|
* The status code of the response when the procedure is successful.
|
|
108
|
+
* The status code must be in the 200-399 range.
|
|
109
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
52
110
|
*
|
|
111
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
53
112
|
* @default 200
|
|
54
113
|
*/
|
|
55
114
|
successStatus?: number;
|
|
56
115
|
/**
|
|
57
116
|
* The description of the response when the procedure is successful.
|
|
117
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
58
118
|
*
|
|
119
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
|
|
59
120
|
* @default 'OK'
|
|
60
121
|
*/
|
|
61
122
|
successDescription?: string;
|
|
@@ -78,6 +139,7 @@ interface Route {
|
|
|
78
139
|
* }
|
|
79
140
|
* ```
|
|
80
141
|
*
|
|
142
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
81
143
|
* @default 'compact'
|
|
82
144
|
*/
|
|
83
145
|
inputStructure?: InputStructure;
|
|
@@ -85,24 +147,33 @@ interface Route {
|
|
|
85
147
|
* Determines how the response should be structured based on the output.
|
|
86
148
|
*
|
|
87
149
|
* @option 'compact'
|
|
88
|
-
*
|
|
150
|
+
* The output data is directly returned as the response body.
|
|
89
151
|
*
|
|
90
152
|
* @option 'detailed'
|
|
91
|
-
*
|
|
92
|
-
* - `
|
|
93
|
-
* - `
|
|
153
|
+
* Return an object with optional properties:
|
|
154
|
+
* - `status`: The response status (must be in 200-399 range) if not set fallback to `successStatus`.
|
|
155
|
+
* - `headers`: Custom headers to merge with the response headers (`Record<string, string | string[] | undefined>`)
|
|
156
|
+
* - `body`: The response body.
|
|
94
157
|
*
|
|
95
158
|
* Example:
|
|
96
159
|
* ```ts
|
|
97
160
|
* const output = {
|
|
161
|
+
* status: 201,
|
|
98
162
|
* headers: { 'x-custom-header': 'value' },
|
|
99
163
|
* body: { message: 'Hello, world!' },
|
|
100
164
|
* };
|
|
101
165
|
* ```
|
|
102
166
|
*
|
|
167
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
103
168
|
* @default 'compact'
|
|
104
169
|
*/
|
|
105
170
|
outputStructure?: OutputStructure;
|
|
171
|
+
/**
|
|
172
|
+
* Override entire auto-generated OpenAPI Operation Object Specification.
|
|
173
|
+
*
|
|
174
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata Operation Metadata Docs}
|
|
175
|
+
*/
|
|
176
|
+
spec?: OpenAPIV3_1.OperationObject | ((current: OpenAPIV3_1.OperationObject) => OpenAPIV3_1.OperationObject);
|
|
106
177
|
}
|
|
107
178
|
declare function mergeRoute(a: Route, b: Route): Route;
|
|
108
179
|
declare function prefixRoute(route: Route, prefix: HTTPPath): Route;
|
|
@@ -122,23 +193,55 @@ interface ContractProcedureDef<TInputSchema extends AnySchema, TOutputSchema ext
|
|
|
122
193
|
outputSchema?: TOutputSchema;
|
|
123
194
|
errorMap: TErrorMap;
|
|
124
195
|
}
|
|
196
|
+
/**
|
|
197
|
+
* This class represents a contract procedure.
|
|
198
|
+
*
|
|
199
|
+
* @see {@link https://orpc.unnoq.com/docs/contract-first/define-contract#procedure-contract Contract Procedure Docs}
|
|
200
|
+
*/
|
|
125
201
|
declare class ContractProcedure<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap, TMeta extends Meta> {
|
|
202
|
+
/**
|
|
203
|
+
* This property holds the defined options for the contract procedure.
|
|
204
|
+
*/
|
|
126
205
|
'~orpc': ContractProcedureDef<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
127
206
|
constructor(def: ContractProcedureDef<TInputSchema, TOutputSchema, TErrorMap, TMeta>);
|
|
128
207
|
}
|
|
129
208
|
type AnyContractProcedure = ContractProcedure<any, any, any, any>;
|
|
130
209
|
declare function isContractProcedure(item: unknown): item is AnyContractProcedure;
|
|
131
210
|
|
|
211
|
+
/**
|
|
212
|
+
* Represents a contract router, which defines a hierarchical structure of contract procedures.
|
|
213
|
+
*
|
|
214
|
+
* @info A contract procedure is a contract router too.
|
|
215
|
+
* @see {@link https://orpc.unnoq.com/docs/contract-first/define-contract#contract-router Contract Router Docs}
|
|
216
|
+
*/
|
|
132
217
|
type ContractRouter<TMeta extends Meta> = ContractProcedure<any, any, any, TMeta> | {
|
|
133
218
|
[k: string]: ContractRouter<TMeta>;
|
|
134
219
|
};
|
|
135
220
|
type AnyContractRouter = ContractRouter<any>;
|
|
221
|
+
/**
|
|
222
|
+
* Infer all inputs of the contract router.
|
|
223
|
+
*
|
|
224
|
+
* @info A contract procedure is a contract router too.
|
|
225
|
+
* @see {@link https://orpc.unnoq.com/docs/contract-first/define-contract#utilities Contract Utilities Docs}
|
|
226
|
+
*/
|
|
136
227
|
type InferContractRouterInputs<T extends AnyContractRouter> = T extends ContractProcedure<infer UInputSchema, any, any, any> ? InferSchemaInput<UInputSchema> : {
|
|
137
228
|
[K in keyof T]: T[K] extends AnyContractRouter ? InferContractRouterInputs<T[K]> : never;
|
|
138
229
|
};
|
|
230
|
+
/**
|
|
231
|
+
* Infer all outputs of the contract router.
|
|
232
|
+
*
|
|
233
|
+
* @info A contract procedure is a contract router too.
|
|
234
|
+
* @see {@link https://orpc.unnoq.com/docs/contract-first/define-contract#utilities Contract Utilities Docs}
|
|
235
|
+
*/
|
|
139
236
|
type InferContractRouterOutputs<T extends AnyContractRouter> = T extends ContractProcedure<any, infer UOutputSchema, any, any> ? InferSchemaOutput<UOutputSchema> : {
|
|
140
237
|
[K in keyof T]: T[K] extends AnyContractRouter ? InferContractRouterOutputs<T[K]> : never;
|
|
141
238
|
};
|
|
239
|
+
/**
|
|
240
|
+
* Infer all errors of the contract router.
|
|
241
|
+
*
|
|
242
|
+
* @info A contract procedure is a contract router too.
|
|
243
|
+
* @see {@link https://orpc.unnoq.com/docs/contract-first/define-contract#utilities Contract Utilities Docs}
|
|
244
|
+
*/
|
|
142
245
|
type InferContractRouterErrorMap<T extends AnyContractRouter> = T extends ContractProcedure<any, any, infer UErrorMap, any> ? UErrorMap : {
|
|
143
246
|
[K in keyof T]: T[K] extends AnyContractRouter ? InferContractRouterErrorMap<T[K]> : never;
|
|
144
247
|
}[keyof T];
|
|
@@ -152,59 +255,254 @@ interface EnhanceContractRouterOptions<TErrorMap extends ErrorMap> extends Enhan
|
|
|
152
255
|
errorMap: TErrorMap;
|
|
153
256
|
}
|
|
154
257
|
declare function enhanceContractRouter<T extends AnyContractRouter, TErrorMap extends ErrorMap>(router: T, options: EnhanceContractRouterOptions<TErrorMap>): EnhancedContractRouter<T, TErrorMap>;
|
|
258
|
+
/**
|
|
259
|
+
* Minify a contract router into a smaller object.
|
|
260
|
+
*
|
|
261
|
+
* You should export the result to a JSON file. On the client side, you can import this JSON file and use it as a contract router.
|
|
262
|
+
* This reduces the size of the contract and helps prevent leaking internal details of the router to the client.
|
|
263
|
+
*
|
|
264
|
+
* @see {@link https://orpc.unnoq.com/docs/contract-first/router-to-contract#minify-export-the-contract-router-for-the-client Router to Contract Docs}
|
|
265
|
+
*/
|
|
266
|
+
declare function minifyContractRouter(router: AnyContractRouter): AnyContractRouter;
|
|
155
267
|
|
|
156
268
|
interface ContractProcedureBuilder<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap, TMeta extends Meta> extends ContractProcedure<TInputSchema, TOutputSchema, TErrorMap, TMeta> {
|
|
269
|
+
/**
|
|
270
|
+
* Adds type-safe custom errors to the contract.
|
|
271
|
+
* The provided errors are spared-merged with any existing errors in the contract.
|
|
272
|
+
*
|
|
273
|
+
* @see {@link https://orpc.unnoq.com/docs/error-handling#type%E2%80%90safe-error-handling Type-Safe Error Handling Docs}
|
|
274
|
+
*/
|
|
157
275
|
errors<U extends ErrorMap>(errors: U): ContractProcedureBuilder<TInputSchema, TOutputSchema, MergedErrorMap<TErrorMap, U>, TMeta>;
|
|
276
|
+
/**
|
|
277
|
+
* Sets or updates the metadata for the contract.
|
|
278
|
+
* The provided metadata is spared-merged with any existing metadata in the contract.
|
|
279
|
+
*
|
|
280
|
+
* @see {@link https://orpc.unnoq.com/docs/metadata Metadata Docs}
|
|
281
|
+
*/
|
|
158
282
|
meta(meta: TMeta): ContractProcedureBuilder<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
283
|
+
/**
|
|
284
|
+
* Sets or updates the route definition for the contract.
|
|
285
|
+
* The provided route is spared-merged with any existing route in the contract.
|
|
286
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
287
|
+
*
|
|
288
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
289
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
290
|
+
*/
|
|
159
291
|
route(route: Route): ContractProcedureBuilder<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
292
|
+
/**
|
|
293
|
+
* Defines the input validation schema for the contract.
|
|
294
|
+
*
|
|
295
|
+
* @see {@link https://orpc.unnoq.com/docs/procedure#input-output-validation Input Validation Docs}
|
|
296
|
+
*/
|
|
160
297
|
input<U extends AnySchema>(schema: U): ContractProcedureBuilderWithInput<U, TOutputSchema, TErrorMap, TMeta>;
|
|
298
|
+
/**
|
|
299
|
+
* Defines the output validation schema for the contract.
|
|
300
|
+
*
|
|
301
|
+
* @see {@link https://orpc.unnoq.com/docs/procedure#input-output-validation Output Validation Docs}
|
|
302
|
+
*/
|
|
161
303
|
output<U extends AnySchema>(schema: U): ContractProcedureBuilderWithOutput<TInputSchema, U, TErrorMap, TMeta>;
|
|
162
304
|
}
|
|
163
305
|
interface ContractProcedureBuilderWithInput<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap, TMeta extends Meta> extends ContractProcedure<TInputSchema, TOutputSchema, TErrorMap, TMeta> {
|
|
306
|
+
/**
|
|
307
|
+
* Adds type-safe custom errors to the contract.
|
|
308
|
+
* The provided errors are spared-merged with any existing errors in the contract.
|
|
309
|
+
*
|
|
310
|
+
* @see {@link https://orpc.unnoq.com/docs/error-handling#type%E2%80%90safe-error-handling Type-Safe Error Handling Docs}
|
|
311
|
+
*/
|
|
164
312
|
errors<U extends ErrorMap>(errors: U): ContractProcedureBuilderWithInput<TInputSchema, TOutputSchema, MergedErrorMap<TErrorMap, U>, TMeta>;
|
|
313
|
+
/**
|
|
314
|
+
* Sets or updates the metadata for the contract.
|
|
315
|
+
* The provided metadata is spared-merged with any existing metadata in the contract.
|
|
316
|
+
*
|
|
317
|
+
* @see {@link https://orpc.unnoq.com/docs/metadata Metadata Docs}
|
|
318
|
+
*/
|
|
165
319
|
meta(meta: TMeta): ContractProcedureBuilderWithInput<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
320
|
+
/**
|
|
321
|
+
* Sets or updates the route definition for the contract.
|
|
322
|
+
* The provided route is spared-merged with any existing route in the contract.
|
|
323
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
324
|
+
*
|
|
325
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
326
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
327
|
+
*/
|
|
166
328
|
route(route: Route): ContractProcedureBuilderWithInput<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
329
|
+
/**
|
|
330
|
+
* Defines the output validation schema for the contract.
|
|
331
|
+
*
|
|
332
|
+
* @see {@link https://orpc.unnoq.com/docs/procedure#input-output-validation Output Validation Docs}
|
|
333
|
+
*/
|
|
167
334
|
output<U extends AnySchema>(schema: U): ContractProcedureBuilderWithInputOutput<TInputSchema, U, TErrorMap, TMeta>;
|
|
168
335
|
}
|
|
169
336
|
interface ContractProcedureBuilderWithOutput<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap, TMeta extends Meta> extends ContractProcedure<TInputSchema, TOutputSchema, TErrorMap, TMeta> {
|
|
337
|
+
/**
|
|
338
|
+
* Adds type-safe custom errors to the contract.
|
|
339
|
+
* The provided errors are spared-merged with any existing errors in the contract.
|
|
340
|
+
*
|
|
341
|
+
* @see {@link https://orpc.unnoq.com/docs/error-handling#type%E2%80%90safe-error-handling Type-Safe Error Handling Docs}
|
|
342
|
+
*/
|
|
170
343
|
errors<U extends ErrorMap>(errors: U): ContractProcedureBuilderWithOutput<TInputSchema, TOutputSchema, MergedErrorMap<TErrorMap, U>, TMeta>;
|
|
344
|
+
/**
|
|
345
|
+
* Sets or updates the metadata for the contract.
|
|
346
|
+
* The provided metadata is spared-merged with any existing metadata in the contract.
|
|
347
|
+
*
|
|
348
|
+
* @see {@link https://orpc.unnoq.com/docs/metadata Metadata Docs}
|
|
349
|
+
*/
|
|
171
350
|
meta(meta: TMeta): ContractProcedureBuilderWithOutput<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
351
|
+
/**
|
|
352
|
+
* Sets or updates the route definition for the contract.
|
|
353
|
+
* The provided route is spared-merged with any existing route in the contract.
|
|
354
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
355
|
+
*
|
|
356
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
357
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
358
|
+
*/
|
|
172
359
|
route(route: Route): ContractProcedureBuilderWithOutput<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
360
|
+
/**
|
|
361
|
+
* Defines the input validation schema for the contract.
|
|
362
|
+
*
|
|
363
|
+
* @see {@link https://orpc.unnoq.com/docs/procedure#input-output-validation Input Validation Docs}
|
|
364
|
+
*/
|
|
173
365
|
input<U extends AnySchema>(schema: U): ContractProcedureBuilderWithInputOutput<U, TOutputSchema, TErrorMap, TMeta>;
|
|
174
366
|
}
|
|
175
367
|
interface ContractProcedureBuilderWithInputOutput<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap, TMeta extends Meta> extends ContractProcedure<TInputSchema, TOutputSchema, TErrorMap, TMeta> {
|
|
368
|
+
/**
|
|
369
|
+
* Adds type-safe custom errors to the contract.
|
|
370
|
+
* The provided errors are spared-merged with any existing errors in the contract.
|
|
371
|
+
*
|
|
372
|
+
* @see {@link https://orpc.unnoq.com/docs/error-handling#type%E2%80%90safe-error-handling Type-Safe Error Handling Docs}
|
|
373
|
+
*/
|
|
176
374
|
errors<U extends ErrorMap>(errors: U): ContractProcedureBuilderWithInputOutput<TInputSchema, TOutputSchema, MergedErrorMap<TErrorMap, U>, TMeta>;
|
|
375
|
+
/**
|
|
376
|
+
* Sets or updates the metadata for the contract.
|
|
377
|
+
* The provided metadata is spared-merged with any existing metadata in the contract.
|
|
378
|
+
*
|
|
379
|
+
* @see {@link https://orpc.unnoq.com/docs/metadata Metadata Docs}
|
|
380
|
+
*/
|
|
177
381
|
meta(meta: TMeta): ContractProcedureBuilderWithInputOutput<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
382
|
+
/**
|
|
383
|
+
* Sets or updates the route definition for the contract.
|
|
384
|
+
* The provided route is spared-merged with any existing route in the contract.
|
|
385
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
386
|
+
*
|
|
387
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
388
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
389
|
+
*/
|
|
178
390
|
route(route: Route): ContractProcedureBuilderWithInputOutput<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
179
391
|
}
|
|
180
392
|
interface ContractRouterBuilder<TErrorMap extends ErrorMap, TMeta extends Meta> {
|
|
393
|
+
/**
|
|
394
|
+
* This property holds the defined options for the contract router.
|
|
395
|
+
*/
|
|
181
396
|
'~orpc': EnhanceContractRouterOptions<TErrorMap>;
|
|
397
|
+
/**
|
|
398
|
+
* Adds type-safe custom errors to the contract.
|
|
399
|
+
* The provided errors are spared-merged with any existing errors in the contract.
|
|
400
|
+
*
|
|
401
|
+
* @see {@link https://orpc.unnoq.com/docs/error-handling#type%E2%80%90safe-error-handling Type-Safe Error Handling Docs}
|
|
402
|
+
*/
|
|
182
403
|
'errors'<U extends ErrorMap>(errors: U): ContractRouterBuilder<MergedErrorMap<TErrorMap, U>, TMeta>;
|
|
404
|
+
/**
|
|
405
|
+
* Prefixes all procedures in the contract router.
|
|
406
|
+
* The provided prefix is post-appended to any existing router prefix.
|
|
407
|
+
*
|
|
408
|
+
* @note This option does not affect procedures that do not define a path in their route definition.
|
|
409
|
+
*
|
|
410
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing#route-prefixes OpenAPI Route Prefixes Docs}
|
|
411
|
+
*/
|
|
183
412
|
'prefix'(prefix: HTTPPath): ContractRouterBuilder<TErrorMap, TMeta>;
|
|
413
|
+
/**
|
|
414
|
+
* Adds tags to all procedures in the contract router.
|
|
415
|
+
* This helpful when you want to group procedures together in the OpenAPI specification.
|
|
416
|
+
*
|
|
417
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
|
|
418
|
+
*/
|
|
184
419
|
'tag'(...tags: string[]): ContractRouterBuilder<TErrorMap, TMeta>;
|
|
420
|
+
/**
|
|
421
|
+
* Applies all of the previously defined options to the specified contract router.
|
|
422
|
+
*
|
|
423
|
+
* @see {@link https://orpc.unnoq.com/docs/router#extending-router Extending Router Docs}
|
|
424
|
+
*/
|
|
185
425
|
'router'<T extends ContractRouter<TMeta>>(router: T): EnhancedContractRouter<T, TErrorMap>;
|
|
186
426
|
}
|
|
187
427
|
|
|
188
428
|
interface ContractBuilderDef<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap, TMeta extends Meta> extends ContractProcedureDef<TInputSchema, TOutputSchema, TErrorMap, TMeta>, EnhanceContractRouterOptions<TErrorMap> {
|
|
189
429
|
}
|
|
190
430
|
declare class ContractBuilder<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap, TMeta extends Meta> extends ContractProcedure<TInputSchema, TOutputSchema, TErrorMap, TMeta> {
|
|
431
|
+
/**
|
|
432
|
+
* This property holds the defined options for the contract.
|
|
433
|
+
*/
|
|
191
434
|
'~orpc': ContractBuilderDef<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
192
435
|
constructor(def: ContractBuilderDef<TInputSchema, TOutputSchema, TErrorMap, TMeta>);
|
|
193
436
|
/**
|
|
194
|
-
*
|
|
437
|
+
* Sets or overrides the initial meta.
|
|
438
|
+
*
|
|
439
|
+
* @see {@link https://orpc.unnoq.com/docs/metadata Metadata Docs}
|
|
195
440
|
*/
|
|
196
441
|
$meta<U extends Meta>(initialMeta: U): ContractBuilder<TInputSchema, TOutputSchema, TErrorMap, U & Record<never, never>>;
|
|
197
442
|
/**
|
|
198
|
-
*
|
|
443
|
+
* Sets or overrides the initial route.
|
|
444
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
445
|
+
*
|
|
446
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
447
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
199
448
|
*/
|
|
200
449
|
$route(initialRoute: Route): ContractBuilder<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
450
|
+
/**
|
|
451
|
+
* Adds type-safe custom errors to the contract.
|
|
452
|
+
* The provided errors are spared-merged with any existing errors in the contract.
|
|
453
|
+
*
|
|
454
|
+
* @see {@link https://orpc.unnoq.com/docs/error-handling#type%E2%80%90safe-error-handling Type-Safe Error Handling Docs}
|
|
455
|
+
*/
|
|
201
456
|
errors<U extends ErrorMap>(errors: U): ContractBuilder<TInputSchema, TOutputSchema, MergedErrorMap<TErrorMap, U>, TMeta>;
|
|
457
|
+
/**
|
|
458
|
+
* Sets or updates the metadata for the contract.
|
|
459
|
+
* The provided metadata is spared-merged with any existing metadata in the contract.
|
|
460
|
+
*
|
|
461
|
+
* @see {@link https://orpc.unnoq.com/docs/metadata Metadata Docs}
|
|
462
|
+
*/
|
|
202
463
|
meta(meta: TMeta): ContractProcedureBuilder<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
464
|
+
/**
|
|
465
|
+
* Sets or updates the route definition for the contract.
|
|
466
|
+
* The provided route is spared-merged with any existing route in the contract.
|
|
467
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
468
|
+
*
|
|
469
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
470
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
471
|
+
*/
|
|
203
472
|
route(route: Route): ContractProcedureBuilder<TInputSchema, TOutputSchema, TErrorMap, TMeta>;
|
|
473
|
+
/**
|
|
474
|
+
* Defines the input validation schema for the contract.
|
|
475
|
+
*
|
|
476
|
+
* @see {@link https://orpc.unnoq.com/docs/procedure#input-output-validation Input Validation Docs}
|
|
477
|
+
*/
|
|
204
478
|
input<U extends AnySchema>(schema: U): ContractProcedureBuilderWithInput<U, TOutputSchema, TErrorMap, TMeta>;
|
|
479
|
+
/**
|
|
480
|
+
* Defines the output validation schema for the contract.
|
|
481
|
+
*
|
|
482
|
+
* @see {@link https://orpc.unnoq.com/docs/procedure#input-output-validation Output Validation Docs}
|
|
483
|
+
*/
|
|
205
484
|
output<U extends AnySchema>(schema: U): ContractProcedureBuilderWithOutput<TInputSchema, U, TErrorMap, TMeta>;
|
|
485
|
+
/**
|
|
486
|
+
* Prefixes all procedures in the contract router.
|
|
487
|
+
* The provided prefix is post-appended to any existing router prefix.
|
|
488
|
+
*
|
|
489
|
+
* @note This option does not affect procedures that do not define a path in their route definition.
|
|
490
|
+
*
|
|
491
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing#route-prefixes OpenAPI Route Prefixes Docs}
|
|
492
|
+
*/
|
|
206
493
|
prefix(prefix: HTTPPath): ContractRouterBuilder<TErrorMap, TMeta>;
|
|
494
|
+
/**
|
|
495
|
+
* Adds tags to all procedures in the contract router.
|
|
496
|
+
* This helpful when you want to group procedures together in the OpenAPI specification.
|
|
497
|
+
*
|
|
498
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
|
|
499
|
+
*/
|
|
207
500
|
tag(...tags: string[]): ContractRouterBuilder<TErrorMap, TMeta>;
|
|
501
|
+
/**
|
|
502
|
+
* Applies all of the previously defined options to the specified contract router.
|
|
503
|
+
*
|
|
504
|
+
* @see {@link https://orpc.unnoq.com/docs/router#extending-router Extending Router Docs}
|
|
505
|
+
*/
|
|
208
506
|
router<T extends ContractRouter<TMeta>>(router: T): EnhancedContractRouter<T, TErrorMap>;
|
|
209
507
|
}
|
|
210
508
|
declare const oc: ContractBuilder<Schema<unknown, unknown>, Schema<unknown, unknown>, Record<never, never>, Record<never, never>>;
|
|
@@ -222,13 +520,28 @@ interface EventIteratorSchemaDetails {
|
|
|
222
520
|
yields: AnySchema;
|
|
223
521
|
returns?: AnySchema;
|
|
224
522
|
}
|
|
523
|
+
/**
|
|
524
|
+
* Define schema for an event iterator.
|
|
525
|
+
*
|
|
526
|
+
* @see {@link https://orpc.unnoq.com/docs/event-iterator#validate-event-iterator Validate Event Iterator Docs}
|
|
527
|
+
*/
|
|
225
528
|
declare function eventIterator<TYieldIn, TYieldOut, TReturnIn = unknown, TReturnOut = unknown>(yields: Schema<TYieldIn, TYieldOut>, returns?: Schema<TReturnIn, TReturnOut>): Schema<AsyncIteratorObject<TYieldIn, TReturnIn, void>, AsyncIteratorObject<TYieldOut, TReturnOut, void>>;
|
|
226
529
|
declare function getEventIteratorSchemaDetails(schema: AnySchema | undefined): undefined | EventIteratorSchemaDetails;
|
|
227
530
|
|
|
531
|
+
/**
|
|
532
|
+
* Help RPCLink automatically send requests using the specified HTTP method in the contract.
|
|
533
|
+
*
|
|
534
|
+
* @see {@link https://orpc.unnoq.com/docs/client/rpc-link#custom-request-method RPCLink Custom Request Method}
|
|
535
|
+
*/
|
|
536
|
+
declare function inferRPCMethodFromContractRouter(contract: AnyContractRouter): (options: unknown, path: readonly string[]) => Exclude<HTTPMethod, 'HEAD'>;
|
|
537
|
+
|
|
228
538
|
type ContractProcedureClient<TClientContext extends ClientContext, TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap> = Client<TClientContext, InferSchemaInput<TInputSchema>, InferSchemaOutput<TOutputSchema>, ErrorFromErrorMap<TErrorMap>>;
|
|
229
539
|
|
|
230
540
|
type ContractRouterClient<TRouter extends AnyContractRouter, TClientContext extends ClientContext = Record<never, never>> = TRouter extends ContractProcedure<infer UInputSchema, infer UOutputSchema, infer UErrorMap, any> ? ContractProcedureClient<TClientContext, UInputSchema, UOutputSchema, UErrorMap> : {
|
|
231
541
|
[K in keyof TRouter]: TRouter[K] extends AnyContractRouter ? ContractRouterClient<TRouter[K], TClientContext> : never;
|
|
232
542
|
};
|
|
233
543
|
|
|
234
|
-
|
|
544
|
+
declare function isSchemaIssue(issue: unknown): issue is SchemaIssue;
|
|
545
|
+
|
|
546
|
+
export { ContractBuilder, ContractProcedure, ValidationError, enhanceContractRouter, enhanceRoute, eventIterator, fallbackContractConfig, getContractRouter, getEventIteratorSchemaDetails, inferRPCMethodFromContractRouter, isContractProcedure, isSchemaIssue, mergeErrorMap, mergeMeta, mergePrefix, mergeRoute, mergeTags, minifyContractRouter, oc, prefixRoute, type, unshiftTagRoute };
|
|
547
|
+
export type { AnyContractProcedure, AnyContractRouter, AnySchema, ContractBuilderDef, ContractConfig, ContractProcedureBuilder, ContractProcedureBuilderWithInput, ContractProcedureBuilderWithInputOutput, ContractProcedureBuilderWithOutput, ContractProcedureClient, ContractProcedureDef, ContractRouter, ContractRouterBuilder, ContractRouterClient, EnhanceContractRouterOptions, EnhanceRouteOptions, EnhancedContractRouter, ErrorFromErrorMap, ErrorMap, ErrorMapItem, EventIteratorSchemaDetails, InferContractRouterErrorMap, InferContractRouterInputs, InferContractRouterMeta, InferContractRouterOutputs, InferSchemaInput, InferSchemaOutput, InputStructure, MergedErrorMap, Meta, ORPCErrorFromErrorMap, OutputStructure, Route, Schema, SchemaIssue, TypeRest, ValidationErrorOptions };
|
package/dist/index.mjs
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { isORPCErrorStatus, mapEventIterator, ORPCError } from '@orpc/client';
|
|
2
2
|
export { ORPCError } from '@orpc/client';
|
|
3
|
-
import { isAsyncIteratorObject } from '@orpc/shared';
|
|
3
|
+
import { isAsyncIteratorObject, get, isTypescriptObject, isPropertyKey } from '@orpc/shared';
|
|
4
4
|
|
|
5
5
|
class ValidationError extends Error {
|
|
6
6
|
issues;
|
|
@@ -18,6 +18,9 @@ function mergeMeta(meta1, meta2) {
|
|
|
18
18
|
}
|
|
19
19
|
|
|
20
20
|
class ContractProcedure {
|
|
21
|
+
/**
|
|
22
|
+
* This property holds the defined options for the contract procedure.
|
|
23
|
+
*/
|
|
21
24
|
"~orpc";
|
|
22
25
|
constructor(def) {
|
|
23
26
|
if (def.route?.successStatus && isORPCErrorStatus(def.route.successStatus)) {
|
|
@@ -100,6 +103,23 @@ function enhanceContractRouter(router, options) {
|
|
|
100
103
|
}
|
|
101
104
|
return enhanced;
|
|
102
105
|
}
|
|
106
|
+
function minifyContractRouter(router) {
|
|
107
|
+
if (isContractProcedure(router)) {
|
|
108
|
+
const procedure = {
|
|
109
|
+
"~orpc": {
|
|
110
|
+
errorMap: {},
|
|
111
|
+
meta: router["~orpc"].meta,
|
|
112
|
+
route: router["~orpc"].route
|
|
113
|
+
}
|
|
114
|
+
};
|
|
115
|
+
return procedure;
|
|
116
|
+
}
|
|
117
|
+
const json = {};
|
|
118
|
+
for (const key in router) {
|
|
119
|
+
json[key] = minifyContractRouter(router[key]);
|
|
120
|
+
}
|
|
121
|
+
return json;
|
|
122
|
+
}
|
|
103
123
|
|
|
104
124
|
class ContractBuilder extends ContractProcedure {
|
|
105
125
|
constructor(def) {
|
|
@@ -108,7 +128,9 @@ class ContractBuilder extends ContractProcedure {
|
|
|
108
128
|
this["~orpc"].tags = def.tags;
|
|
109
129
|
}
|
|
110
130
|
/**
|
|
111
|
-
*
|
|
131
|
+
* Sets or overrides the initial meta.
|
|
132
|
+
*
|
|
133
|
+
* @see {@link https://orpc.unnoq.com/docs/metadata Metadata Docs}
|
|
112
134
|
*/
|
|
113
135
|
$meta(initialMeta) {
|
|
114
136
|
return new ContractBuilder({
|
|
@@ -117,7 +139,11 @@ class ContractBuilder extends ContractProcedure {
|
|
|
117
139
|
});
|
|
118
140
|
}
|
|
119
141
|
/**
|
|
120
|
-
*
|
|
142
|
+
* Sets or overrides the initial route.
|
|
143
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
144
|
+
*
|
|
145
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
146
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
121
147
|
*/
|
|
122
148
|
$route(initialRoute) {
|
|
123
149
|
return new ContractBuilder({
|
|
@@ -125,48 +151,97 @@ class ContractBuilder extends ContractProcedure {
|
|
|
125
151
|
route: initialRoute
|
|
126
152
|
});
|
|
127
153
|
}
|
|
154
|
+
/**
|
|
155
|
+
* Adds type-safe custom errors to the contract.
|
|
156
|
+
* The provided errors are spared-merged with any existing errors in the contract.
|
|
157
|
+
*
|
|
158
|
+
* @see {@link https://orpc.unnoq.com/docs/error-handling#type%E2%80%90safe-error-handling Type-Safe Error Handling Docs}
|
|
159
|
+
*/
|
|
128
160
|
errors(errors) {
|
|
129
161
|
return new ContractBuilder({
|
|
130
162
|
...this["~orpc"],
|
|
131
163
|
errorMap: mergeErrorMap(this["~orpc"].errorMap, errors)
|
|
132
164
|
});
|
|
133
165
|
}
|
|
166
|
+
/**
|
|
167
|
+
* Sets or updates the metadata for the contract.
|
|
168
|
+
* The provided metadata is spared-merged with any existing metadata in the contract.
|
|
169
|
+
*
|
|
170
|
+
* @see {@link https://orpc.unnoq.com/docs/metadata Metadata Docs}
|
|
171
|
+
*/
|
|
134
172
|
meta(meta) {
|
|
135
173
|
return new ContractBuilder({
|
|
136
174
|
...this["~orpc"],
|
|
137
175
|
meta: mergeMeta(this["~orpc"].meta, meta)
|
|
138
176
|
});
|
|
139
177
|
}
|
|
178
|
+
/**
|
|
179
|
+
* Sets or updates the route definition for the contract.
|
|
180
|
+
* The provided route is spared-merged with any existing route in the contract.
|
|
181
|
+
* This option is typically relevant when integrating with OpenAPI.
|
|
182
|
+
*
|
|
183
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
|
|
184
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
|
|
185
|
+
*/
|
|
140
186
|
route(route) {
|
|
141
187
|
return new ContractBuilder({
|
|
142
188
|
...this["~orpc"],
|
|
143
189
|
route: mergeRoute(this["~orpc"].route, route)
|
|
144
190
|
});
|
|
145
191
|
}
|
|
192
|
+
/**
|
|
193
|
+
* Defines the input validation schema for the contract.
|
|
194
|
+
*
|
|
195
|
+
* @see {@link https://orpc.unnoq.com/docs/procedure#input-output-validation Input Validation Docs}
|
|
196
|
+
*/
|
|
146
197
|
input(schema) {
|
|
147
198
|
return new ContractBuilder({
|
|
148
199
|
...this["~orpc"],
|
|
149
200
|
inputSchema: schema
|
|
150
201
|
});
|
|
151
202
|
}
|
|
203
|
+
/**
|
|
204
|
+
* Defines the output validation schema for the contract.
|
|
205
|
+
*
|
|
206
|
+
* @see {@link https://orpc.unnoq.com/docs/procedure#input-output-validation Output Validation Docs}
|
|
207
|
+
*/
|
|
152
208
|
output(schema) {
|
|
153
209
|
return new ContractBuilder({
|
|
154
210
|
...this["~orpc"],
|
|
155
211
|
outputSchema: schema
|
|
156
212
|
});
|
|
157
213
|
}
|
|
214
|
+
/**
|
|
215
|
+
* Prefixes all procedures in the contract router.
|
|
216
|
+
* The provided prefix is post-appended to any existing router prefix.
|
|
217
|
+
*
|
|
218
|
+
* @note This option does not affect procedures that do not define a path in their route definition.
|
|
219
|
+
*
|
|
220
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/routing#route-prefixes OpenAPI Route Prefixes Docs}
|
|
221
|
+
*/
|
|
158
222
|
prefix(prefix) {
|
|
159
223
|
return new ContractBuilder({
|
|
160
224
|
...this["~orpc"],
|
|
161
225
|
prefix: mergePrefix(this["~orpc"].prefix, prefix)
|
|
162
226
|
});
|
|
163
227
|
}
|
|
228
|
+
/**
|
|
229
|
+
* Adds tags to all procedures in the contract router.
|
|
230
|
+
* This helpful when you want to group procedures together in the OpenAPI specification.
|
|
231
|
+
*
|
|
232
|
+
* @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
|
|
233
|
+
*/
|
|
164
234
|
tag(...tags) {
|
|
165
235
|
return new ContractBuilder({
|
|
166
236
|
...this["~orpc"],
|
|
167
237
|
tags: mergeTags(this["~orpc"].tags, tags)
|
|
168
238
|
});
|
|
169
239
|
}
|
|
240
|
+
/**
|
|
241
|
+
* Applies all of the previously defined options to the specified contract router.
|
|
242
|
+
*
|
|
243
|
+
* @see {@link https://orpc.unnoq.com/docs/router#extending-router Extending Router Docs}
|
|
244
|
+
*/
|
|
170
245
|
router(router) {
|
|
171
246
|
return enhanceContractRouter(router, this["~orpc"]);
|
|
172
247
|
}
|
|
@@ -234,6 +309,19 @@ function getEventIteratorSchemaDetails(schema) {
|
|
|
234
309
|
return schema["~standard"][EVENT_ITERATOR_DETAILS_SYMBOL];
|
|
235
310
|
}
|
|
236
311
|
|
|
312
|
+
function inferRPCMethodFromContractRouter(contract) {
|
|
313
|
+
return (_, path) => {
|
|
314
|
+
const procedure = get(contract, path);
|
|
315
|
+
if (!isContractProcedure(procedure)) {
|
|
316
|
+
throw new Error(
|
|
317
|
+
`[inferRPCMethodFromContractRouter] No valid procedure found at path "${path.join(".")}". This may happen when the contract router is not properly configured.`
|
|
318
|
+
);
|
|
319
|
+
}
|
|
320
|
+
const method = fallbackContractConfig("defaultMethod", procedure["~orpc"].route.method);
|
|
321
|
+
return method === "HEAD" ? "GET" : method;
|
|
322
|
+
};
|
|
323
|
+
}
|
|
324
|
+
|
|
237
325
|
function type(...[map]) {
|
|
238
326
|
return {
|
|
239
327
|
"~standard": {
|
|
@@ -249,4 +337,19 @@ function type(...[map]) {
|
|
|
249
337
|
};
|
|
250
338
|
}
|
|
251
339
|
|
|
252
|
-
|
|
340
|
+
function isSchemaIssue(issue) {
|
|
341
|
+
if (!isTypescriptObject(issue) || typeof issue.message !== "string") {
|
|
342
|
+
return false;
|
|
343
|
+
}
|
|
344
|
+
if (issue.path !== void 0) {
|
|
345
|
+
if (!Array.isArray(issue.path)) {
|
|
346
|
+
return false;
|
|
347
|
+
}
|
|
348
|
+
if (!issue.path.every((segment) => isPropertyKey(segment) || isTypescriptObject(segment) && isPropertyKey(segment.key))) {
|
|
349
|
+
return false;
|
|
350
|
+
}
|
|
351
|
+
}
|
|
352
|
+
return true;
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
export { ContractBuilder, ContractProcedure, ValidationError, enhanceContractRouter, enhanceRoute, eventIterator, fallbackContractConfig, getContractRouter, getEventIteratorSchemaDetails, inferRPCMethodFromContractRouter, isContractProcedure, isSchemaIssue, mergeErrorMap, mergeMeta, mergePrefix, mergeRoute, mergeTags, minifyContractRouter, oc, prefixRoute, type, unshiftTagRoute };
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@orpc/contract",
|
|
3
3
|
"type": "module",
|
|
4
|
-
"version": "0.0.0-next.
|
|
4
|
+
"version": "0.0.0-next.dd8de86",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"homepage": "https://orpc.unnoq.com",
|
|
7
7
|
"repository": {
|
|
@@ -25,13 +25,14 @@
|
|
|
25
25
|
],
|
|
26
26
|
"dependencies": {
|
|
27
27
|
"@standard-schema/spec": "^1.0.0",
|
|
28
|
-
"
|
|
29
|
-
"@orpc/client": "0.0.0-next.
|
|
28
|
+
"openapi-types": "^12.1.3",
|
|
29
|
+
"@orpc/client": "0.0.0-next.dd8de86",
|
|
30
|
+
"@orpc/shared": "0.0.0-next.dd8de86"
|
|
30
31
|
},
|
|
31
32
|
"devDependencies": {
|
|
32
|
-
"arktype": "2.1.
|
|
33
|
-
"valibot": "1.
|
|
34
|
-
"zod": "^
|
|
33
|
+
"arktype": "2.1.20",
|
|
34
|
+
"valibot": "^1.1.0",
|
|
35
|
+
"zod": "^4.0.17"
|
|
35
36
|
},
|
|
36
37
|
"scripts": {
|
|
37
38
|
"build": "unbuild",
|