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