@orpc/contract 1.3.0 → 1.4.0

package/dist/index.d.mts

@@ -3,6 +3,8 @@ export { HTTPMethod, HTTPPath, ORPCError } from '@orpc/client';
 import { Promisable, IsEqual, ThrowableError } from '@orpc/shared';
 export { Registry, ThrowableError } from '@orpc/shared';
 import { StandardSchemaV1 } from '@standard-schema/spec';
+import { OpenAPIV3_1 } from 'openapi-types';
+export { OpenAPIV3_1 as OpenAPI } from 'openapi-types';
 
 type Schema<TInput, TOutput> = StandardSchemaV1<TInput, TOutput>;
 type AnySchema = Schema<any, any>;
@@ -159,6 +161,12 @@ interface Route {
      * @default 'compact'
      */
     outputStructure?: OutputStructure;
+    /**
+     * Override entire auto-generated OpenAPI Operation Object Specification.
+     *
+     * @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata Operation Metadata Docs}
+     */
+    spec?: OpenAPIV3_1.OperationObject;
 }
 declare function mergeRoute(a: Route, b: Route): Route;
 declare function prefixRoute(route: Route, prefix: HTTPPath): Route;
@@ -240,6 +248,15 @@ interface EnhanceContractRouterOptions<TErrorMap extends ErrorMap> extends Enhan
     errorMap: TErrorMap;
 }
 declare function enhanceContractRouter<T extends AnyContractRouter, TErrorMap extends ErrorMap>(router: T, options: EnhanceContractRouterOptions<TErrorMap>): EnhancedContractRouter<T, TErrorMap>;
+/**
+ * Minify a contract router into a smaller object.
+ *
+ * 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.
+ * This reduces the size of the contract and helps prevent leaking internal details of the router to the client.
+ *
+ * @see {@link https://orpc.unnoq.com/docs/contract-first/router-to-contract#minify-export-the-contract-router-for-the-client Router to Contract Docs}
+ */
+declare function minifyContractRouter(router: AnyContractRouter): AnyContractRouter;
 
 interface ContractProcedureBuilder<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap, TMeta extends Meta> extends ContractProcedure<TInputSchema, TOutputSchema, TErrorMap, TMeta> {
     /**
@@ -504,6 +521,13 @@ interface EventIteratorSchemaDetails {
 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>>;
 declare function getEventIteratorSchemaDetails(schema: AnySchema | undefined): undefined | EventIteratorSchemaDetails;
 
+/**
+ * Help RPCLink automatically send requests using the specified HTTP method in the contract.
+ *
+ * @see {@link https://orpc.unnoq.com/docs/client/rpc-link#custom-request-method RPCLink Custom Request Method}
+ */
+declare function inferRPCMethodFromContractRouter(contract: AnyContractRouter): (options: unknown, path: readonly string[]) => Exclude<HTTPMethod, 'HEAD'>;
+
 type ContractProcedureClient<TClientContext extends ClientContext, TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap> = Client<TClientContext, InferSchemaInput<TInputSchema>, InferSchemaOutput<TOutputSchema>, ErrorFromErrorMap<TErrorMap>>;
 
 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> : {
@@ -512,5 +536,5 @@ type ContractRouterClient<TRouter extends AnyContractRouter, TClientContext exte
 
 declare function isSchemaIssue(issue: unknown): issue is SchemaIssue;
 
-export { ContractBuilder, ContractProcedure, ValidationError, enhanceContractRouter, enhanceRoute, eventIterator, fallbackContractConfig, getContractRouter, getEventIteratorSchemaDetails, isContractProcedure, isSchemaIssue, mergeErrorMap, mergeMeta, mergePrefix, mergeRoute, mergeTags, oc, prefixRoute, type, unshiftTagRoute };
+export { ContractBuilder, ContractProcedure, ValidationError, enhanceContractRouter, enhanceRoute, eventIterator, fallbackContractConfig, getContractRouter, getEventIteratorSchemaDetails, inferRPCMethodFromContractRouter, isContractProcedure, isSchemaIssue, mergeErrorMap, mergeMeta, mergePrefix, mergeRoute, mergeTags, minifyContractRouter, oc, prefixRoute, type, unshiftTagRoute };
 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

@@ -3,6 +3,8 @@ export { HTTPMethod, HTTPPath, ORPCError } from '@orpc/client';
 import { Promisable, IsEqual, ThrowableError } from '@orpc/shared';
 export { Registry, ThrowableError } from '@orpc/shared';
 import { StandardSchemaV1 } from '@standard-schema/spec';
+import { OpenAPIV3_1 } from 'openapi-types';
+export { OpenAPIV3_1 as OpenAPI } from 'openapi-types';
 
 type Schema<TInput, TOutput> = StandardSchemaV1<TInput, TOutput>;
 type AnySchema = Schema<any, any>;
@@ -159,6 +161,12 @@ interface Route {
      * @default 'compact'
      */
     outputStructure?: OutputStructure;
+    /**
+     * Override entire auto-generated OpenAPI Operation Object Specification.
+     *
+     * @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata Operation Metadata Docs}
+     */
+    spec?: OpenAPIV3_1.OperationObject;
 }
 declare function mergeRoute(a: Route, b: Route): Route;
 declare function prefixRoute(route: Route, prefix: HTTPPath): Route;
@@ -240,6 +248,15 @@ interface EnhanceContractRouterOptions<TErrorMap extends ErrorMap> extends Enhan
     errorMap: TErrorMap;
 }
 declare function enhanceContractRouter<T extends AnyContractRouter, TErrorMap extends ErrorMap>(router: T, options: EnhanceContractRouterOptions<TErrorMap>): EnhancedContractRouter<T, TErrorMap>;
+/**
+ * Minify a contract router into a smaller object.
+ *
+ * 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.
+ * This reduces the size of the contract and helps prevent leaking internal details of the router to the client.
+ *
+ * @see {@link https://orpc.unnoq.com/docs/contract-first/router-to-contract#minify-export-the-contract-router-for-the-client Router to Contract Docs}
+ */
+declare function minifyContractRouter(router: AnyContractRouter): AnyContractRouter;
 
 interface ContractProcedureBuilder<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap, TMeta extends Meta> extends ContractProcedure<TInputSchema, TOutputSchema, TErrorMap, TMeta> {
     /**
@@ -504,6 +521,13 @@ interface EventIteratorSchemaDetails {
 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>>;
 declare function getEventIteratorSchemaDetails(schema: AnySchema | undefined): undefined | EventIteratorSchemaDetails;
 
+/**
+ * Help RPCLink automatically send requests using the specified HTTP method in the contract.
+ *
+ * @see {@link https://orpc.unnoq.com/docs/client/rpc-link#custom-request-method RPCLink Custom Request Method}
+ */
+declare function inferRPCMethodFromContractRouter(contract: AnyContractRouter): (options: unknown, path: readonly string[]) => Exclude<HTTPMethod, 'HEAD'>;
+
 type ContractProcedureClient<TClientContext extends ClientContext, TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap> = Client<TClientContext, InferSchemaInput<TInputSchema>, InferSchemaOutput<TOutputSchema>, ErrorFromErrorMap<TErrorMap>>;
 
 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> : {
@@ -512,5 +536,5 @@ type ContractRouterClient<TRouter extends AnyContractRouter, TClientContext exte
 
 declare function isSchemaIssue(issue: unknown): issue is SchemaIssue;
 
-export { ContractBuilder, ContractProcedure, ValidationError, enhanceContractRouter, enhanceRoute, eventIterator, fallbackContractConfig, getContractRouter, getEventIteratorSchemaDetails, isContractProcedure, isSchemaIssue, mergeErrorMap, mergeMeta, mergePrefix, mergeRoute, mergeTags, oc, prefixRoute, type, unshiftTagRoute };
+export { ContractBuilder, ContractProcedure, ValidationError, enhanceContractRouter, enhanceRoute, eventIterator, fallbackContractConfig, getContractRouter, getEventIteratorSchemaDetails, inferRPCMethodFromContractRouter, isContractProcedure, isSchemaIssue, mergeErrorMap, mergeMeta, mergePrefix, mergeRoute, mergeTags, minifyContractRouter, oc, prefixRoute, type, unshiftTagRoute };
 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

@@ -1,6 +1,6 @@
 import { isORPCErrorStatus, mapEventIterator, ORPCError } from '@orpc/client';
 export { ORPCError } from '@orpc/client';
-import { isAsyncIteratorObject, isTypescriptObject, isPropertyKey } from '@orpc/shared';
+import { isAsyncIteratorObject, get, isTypescriptObject, isPropertyKey } from '@orpc/shared';
 
 class ValidationError extends Error {
   issues;
@@ -103,6 +103,23 @@ function enhanceContractRouter(router, options) {
   }
   return enhanced;
 }
+function minifyContractRouter(router) {
+  if (isContractProcedure(router)) {
+    const procedure = {
+      "~orpc": {
+        errorMap: {},
+        meta: router["~orpc"].meta,
+        route: router["~orpc"].route
+      }
+    };
+    return procedure;
+  }
+  const json = {};
+  for (const key in router) {
+    json[key] = minifyContractRouter(router[key]);
+  }
+  return json;
+}
 
 class ContractBuilder extends ContractProcedure {
   constructor(def) {
@@ -292,6 +309,19 @@ function getEventIteratorSchemaDetails(schema) {
   return schema["~standard"][EVENT_ITERATOR_DETAILS_SYMBOL];
 }
 
+function inferRPCMethodFromContractRouter(contract) {
+  return (_, path) => {
+    const procedure = get(contract, path);
+    if (!isContractProcedure(procedure)) {
+      throw new Error(
+        `[inferRPCMethodFromContractRouter] No valid procedure found at path "${path.join(".")}". This may happen when the contract router is not properly configured.`
+      );
+    }
+    const method = fallbackContractConfig("defaultMethod", procedure["~orpc"].route.method);
+    return method === "HEAD" ? "GET" : method;
+  };
+}
+
 function type(...[map]) {
   return {
     "~standard": {
@@ -322,4 +352,4 @@ function isSchemaIssue(issue) {
   return true;
 }
 
-export { ContractBuilder, ContractProcedure, ValidationError, enhanceContractRouter, enhanceRoute, eventIterator, fallbackContractConfig, getContractRouter, getEventIteratorSchemaDetails, isContractProcedure, isSchemaIssue, mergeErrorMap, mergeMeta, mergePrefix, mergeRoute, mergeTags, oc, prefixRoute, type, unshiftTagRoute };
+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

@@ -1,7 +1,7 @@
 {
   "name": "@orpc/contract",
   "type": "module",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "license": "MIT",
   "homepage": "https://orpc.unnoq.com",
   "repository": {
@@ -25,13 +25,14 @@
   ],
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
-    "@orpc/client": "1.3.0",
-    "@orpc/shared": "1.3.0"
+    "openapi-types": "^12.1.3",
+    "@orpc/client": "1.4.0",
+    "@orpc/shared": "1.4.0"
   },
   "devDependencies": {
     "arktype": "2.1.20",
     "valibot": "^1.1.0",
-    "zod": "^3.25.11"
+    "zod": "^3.25.49"
   },
   "scripts": {
     "build": "unbuild",