@orpc/contract 1.14.11 → 1.14.12

package/dist/index.mjs

@@ -1,200 +1,346 @@
-import { isTypescriptObject, toArray, get, set, ORPC_NAME, isAsyncIteratorObject, isPropertyKey } from '@orpc/shared';
-import { P as ProcedureContract, r as resolveMetaPlugins, m as mergeErrorMap, a as augmentContractRouter, V as ValidationError } from './shared/contract.CW-2wl1i.mjs';
-export { d as defineMeta, g as getProcedureContractOrThrow, b as getRouterContract, c as minifyRouterContract, e as reconcileORPCError } from './shared/contract.CW-2wl1i.mjs';
-import { createORPCClient, wrapAsyncIteratorPreservingEventMeta, ORPCError } from '@orpc/client';
+import { i as isContractProcedure, C as ContractProcedure, m as mergeErrorMap, V as ValidationError } from './shared/contract.D_dZrO__.mjs';
+export { v as validateORPCError } from './shared/contract.D_dZrO__.mjs';
+import { toHttpPath } from '@orpc/client/standard';
+import { toArray, isAsyncIteratorObject, get, isTypescriptObject, isPropertyKey } from '@orpc/shared';
+export { AsyncIteratorClass } from '@orpc/shared';
+import { mapEventIterator, ORPCError } from '@orpc/client';
+export { ORPCError } from '@orpc/client';
 
-const HIDDEN_META_PLUGINS_SYMBOL = Symbol.for("ORPC_HIDDEN_META_PLUGINS");
-function getHiddenMetaPlugins(container) {
-  if (!isTypescriptObject(container)) {
-    return void 0;
+function mergeMeta(meta1, meta2) {
+  return { ...meta1, ...meta2 };
+}
+
+function mergeRoute(a, b) {
+  return { ...a, ...b };
+}
+function prefixRoute(route, prefix) {
+  if (!route.path) {
+    return route;
+  }
+  return {
+    ...route,
+    path: `${prefix}${route.path}`
+  };
+}
+function unshiftTagRoute(route, tags) {
+  return {
+    ...route,
+    tags: [...tags, ...route.tags ?? []]
+  };
+}
+function mergePrefix(a, b) {
+  return a ? `${a}${b}` : b;
+}
+function mergeTags(a, b) {
+  return a ? [...a, ...b] : b;
+}
+function enhanceRoute(route, options) {
+  let router = route;
+  if (options.prefix) {
+    router = prefixRoute(router, options.prefix);
+  }
+  if (options.tags?.length) {
+    router = unshiftTagRoute(router, options.tags);
+  }
+  return router;
+}
+
+function getContractRouter(router, path) {
+  let current = router;
+  for (let i = 0; i < path.length; i++) {
+    const segment = path[i];
+    if (!current) {
+      return void 0;
+    }
+    if (isContractProcedure(current)) {
+      return void 0;
+    }
+    if (typeof current !== "object") {
+      return void 0;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+function enhanceContractRouter(router, options) {
+  if (isContractProcedure(router)) {
+    const enhanced2 = new ContractProcedure({
+      ...router["~orpc"],
+      errorMap: mergeErrorMap(options.errorMap, router["~orpc"].errorMap),
+      route: enhanceRoute(router["~orpc"].route, options)
+    });
+    return enhanced2;
+  }
+  if (typeof router !== "object" || router === null) {
+    return router;
+  }
+  const enhanced = {};
+  for (const key in router) {
+    enhanced[key] = enhanceContractRouter(router[key], options);
   }
-  return container[HIDDEN_META_PLUGINS_SYMBOL];
+  return enhanced;
 }
-function setHiddenMetaPlugins(container, metaPlugins) {
-  container[HIDDEN_META_PLUGINS_SYMBOL] = metaPlugins;
+function minifyContractRouter(router) {
+  if (isContractProcedure(router)) {
+    const procedure = {
+      "~orpc": {
+        errorMap: {},
+        meta: router["~orpc"].meta,
+        route: router["~orpc"].route
+      }
+    };
+    return procedure;
+  }
+  if (typeof router !== "object" || router === null) {
+    return router;
+  }
+  const json = {};
+  for (const key in router) {
+    json[key] = minifyContractRouter(router[key]);
+  }
+  return json;
+}
+function populateContractRouterPaths(router, options = {}) {
+  const path = toArray(options.path);
+  if (isContractProcedure(router)) {
+    if (router["~orpc"].route.path === void 0) {
+      return new ContractProcedure({
+        ...router["~orpc"],
+        route: {
+          ...router["~orpc"].route,
+          path: toHttpPath(path)
+        }
+      });
+    }
+    return router;
+  }
+  if (typeof router !== "object" || router === null) {
+    return router;
+  }
+  const populated = {};
+  for (const key in router) {
+    populated[key] = populateContractRouterPaths(router[key], { ...options, path: [...path, key] });
+  }
+  return populated;
 }
 
-class ContractBuilder extends ProcedureContract {
+class ContractBuilder extends ContractProcedure {
+  constructor(def) {
+    super(def);
+    this["~orpc"].prefix = def.prefix;
+    this["~orpc"].tags = def.tags;
+  }
   /**
-   * Private constructor to prevent direct instantiation.
-   * Use the static `create` method to initialize a new instance with a safe initial definition.
+   * Sets or overrides the initial meta.
+   *
+   * @see {@link https://orpc.dev/docs/metadata Metadata Docs}
    */
-  constructor(definition) {
-    super(definition);
+  $meta(initialMeta) {
+    return new ContractBuilder({
+      ...this["~orpc"],
+      meta: initialMeta
+    });
   }
-  static create() {
+  /**
+   * Sets or overrides the initial route.
+   * This option is typically relevant when integrating with OpenAPI.
+   *
+   * @see {@link https://orpc.dev/docs/openapi/routing OpenAPI Routing Docs}
+   * @see {@link https://orpc.dev/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
+   */
+  $route(initialRoute) {
     return new ContractBuilder({
-      errorMap: {},
-      meta: {}
+      ...this["~orpc"],
+      route: initialRoute
     });
   }
-  meta(...plugins) {
-    const [meta, metaPlugins] = resolveMetaPlugins(
-      this["~orpc"].meta,
-      this["~orpc"].metaPlugins,
-      plugins
-    );
+  /**
+   * Sets or overrides the initial input schema.
+   *
+   * @see {@link https://orpc.dev/docs/procedure#initial-configuration Initial Procedure Configuration Docs}
+   */
+  $input(initialInputSchema) {
     return new ContractBuilder({
       ...this["~orpc"],
-      meta,
-      metaPlugins
+      inputSchema: initialInputSchema
     });
   }
+  /**
+   * Adds type-safe custom errors to the contract.
+   * The provided errors are spared-merged with any existing errors in the contract.
+   *
+   * @see {@link https://orpc.dev/docs/error-handling#type%E2%80%90safe-error-handling Type-Safe Error Handling Docs}
+   */
   errors(errors) {
-    let result = new ContractBuilder({
+    return new ContractBuilder({
       ...this["~orpc"],
       errorMap: mergeErrorMap(this["~orpc"].errorMap, errors)
     });
-    const plugins = getHiddenMetaPlugins(errors);
-    if (plugins) {
-      result = result.meta(...plugins);
-    }
-    return result;
   }
+  /**
+   * Sets or updates the metadata for the contract.
+   * The provided metadata is spared-merged with any existing metadata in the contract.
+   *
+   * @see {@link https://orpc.dev/docs/metadata Metadata Docs}
+   */
+  meta(meta) {
+    return new ContractBuilder({
+      ...this["~orpc"],
+      meta: mergeMeta(this["~orpc"].meta, meta)
+    });
+  }
+  /**
+   * Sets or updates the route definition for the contract.
+   * The provided route is spared-merged with any existing route in the contract.
+   * This option is typically relevant when integrating with OpenAPI.
+   *
+   * @see {@link https://orpc.dev/docs/openapi/routing OpenAPI Routing Docs}
+   * @see {@link https://orpc.dev/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
+   */
+  route(route) {
+    return new ContractBuilder({
+      ...this["~orpc"],
+      route: mergeRoute(this["~orpc"].route, route)
+    });
+  }
+  /**
+   * Defines the input validation schema for the contract.
+   *
+   * @see {@link https://orpc.dev/docs/procedure#input-output-validation Input Validation Docs}
+   */
   input(schema) {
-    let result = new ContractBuilder({
+    return new ContractBuilder({
       ...this["~orpc"],
-      inputSchemas: [...toArray(this["~orpc"].inputSchemas), schema]
+      inputSchema: schema
     });
-    const plugins = getHiddenMetaPlugins(schema);
-    if (plugins) {
-      result = result.meta(...plugins);
-    }
-    return result;
   }
+  /**
+   * Defines the output validation schema for the contract.
+   *
+   * @see {@link https://orpc.dev/docs/procedure#input-output-validation Output Validation Docs}
+   */
   output(schema) {
-    let result = new ContractBuilder({
+    return new ContractBuilder({
       ...this["~orpc"],
-      outputSchemas: [...toArray(this["~orpc"].outputSchemas), schema]
+      outputSchema: schema
+    });
+  }
+  /**
+   * Prefixes all procedures in the contract router.
+   * The provided prefix is post-appended to any existing router prefix.
+   *
+   * @note This option does not affect procedures that do not define a path in their route definition.
+   *
+   * @see {@link https://orpc.dev/docs/openapi/routing#route-prefixes OpenAPI Route Prefixes Docs}
+   */
+  prefix(prefix) {
+    return new ContractBuilder({
+      ...this["~orpc"],
+      prefix: mergePrefix(this["~orpc"].prefix, prefix)
+    });
+  }
+  /**
+   * Adds tags to all procedures in the contract router.
+   * This helpful when you want to group procedures together in the OpenAPI specification.
+   *
+   * @see {@link https://orpc.dev/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
+   */
+  tag(...tags) {
+    return new ContractBuilder({
+      ...this["~orpc"],
+      tags: mergeTags(this["~orpc"].tags, tags)
     });
-    const plugins = getHiddenMetaPlugins(schema);
-    if (plugins) {
-      result = result.meta(...plugins);
-    }
-    return result;
   }
+  /**
+   * Applies all of the previously defined options to the specified contract router.
+   *
+   * @see {@link https://orpc.dev/docs/router#extending-router Extending Router Docs}
+   */
   router(router) {
-    return augmentContractRouter(router, this["~orpc"]);
+    return enhanceContractRouter(router, this["~orpc"]);
   }
 }
-const oc = ContractBuilder.create();
+const oc = new ContractBuilder({
+  errorMap: {},
+  route: {},
+  meta: {}
+});
 
-const meta = {
-  path(path) {
-    return {
-      name: "~path",
-      init(meta2) {
-        return {
-          ...meta2,
-          "~path": path
-        };
-      }
-    };
-  }
+const DEFAULT_CONFIG = {
+  defaultMethod: "POST",
+  defaultSuccessStatus: 200,
+  defaultSuccessDescription: "OK",
+  defaultInputStructure: "compact",
+  defaultOutputStructure: "compact"
 };
-function getPathMeta(procedureOrLazy) {
-  return procedureOrLazy["~orpc"].meta["~path"];
-}
-function resolveBasePathMeta(contract, currentPath = []) {
-  if (contract instanceof ProcedureContract) {
-    const path = getPathMeta(contract);
-    if (!path) {
-      return void 0;
-    }
-    const base = path.slice(0, Math.max(0, path.length - currentPath.length));
-    if (currentPath.some((key, i) => path[base.length + i] !== key)) {
-      throw new TypeError(
-        `Procedure contract at "${currentPath.join(".")}" defines meta.path "${path.join(".")}" that does not match its path inside the given router contract.`
-      );
-    }
-    return base;
+function fallbackContractConfig(key, value) {
+  if (value === void 0) {
+    return DEFAULT_CONFIG[key];
   }
-  if (isTypescriptObject(contract)) {
-    for (const key in contract) {
-      const base = resolveBasePathMeta(contract[key], [...currentPath, key]);
-      if (base !== void 0) {
-        return base;
-      }
-    }
-  }
-  return void 0;
+  return value;
 }
 
-function createContractClientFactory(link, options = {}) {
-  const factory = (contract) => {
-    const path = resolveBasePathMeta(contract);
-    if (path === void 0) {
-      throw new TypeError(
-        "ContractClientFactory: procedure contract must define `meta.path` that matches its path in the root router contract."
-      );
-    }
-    const contractRef = options.contractRef;
-    if (contractRef) {
-      const register = (contract2, path2) => {
-        if (contract2 instanceof ProcedureContract) {
-          set(contractRef, [...path2, "~orpc"], contract2["~orpc"]);
-          return;
-        }
-        if (isTypescriptObject(contract2)) {
-          for (const [key, value] of Object.entries(contract2)) {
-            register(value, [...path2, key]);
-          }
-        }
-      };
-      register(contract, path);
-    }
-    return createORPCClient(link, { ...options, scoped: get(options.scoped, path), path });
-  };
-  return factory;
-}
-
-const ASYNC_ITERATOR_OBJECT_SCHEMA_DETAILS_SYMBOL = Symbol.for("ORPC_ASYNC_ITERATOR_OBJECT_SCHEMA_DETAILS");
-function asyncIteratorObject(yieldSchema, returnSchema) {
+const EVENT_ITERATOR_DETAILS_SYMBOL = Symbol("ORPC_EVENT_ITERATOR_DETAILS");
+function eventIterator(yields, returns) {
   return {
     "~standard": {
-      [ASYNC_ITERATOR_OBJECT_SCHEMA_DETAILS_SYMBOL]: { yieldSchema, returnSchema },
-      vendor: ORPC_NAME,
+      [EVENT_ITERATOR_DETAILS_SYMBOL]: { yields, returns },
+      vendor: "orpc",
       version: 1,
       validate(iterator) {
         if (!isAsyncIteratorObject(iterator)) {
-          return { issues: [{ message: "Expect AsyncIteratorObject", path: [] }] };
+          return { issues: [{ message: "Expect event iterator", path: [] }] };
         }
-        const mapped = wrapAsyncIteratorPreservingEventMeta(iterator, {
-          async mapResult(result) {
-            const schema = result.done ? returnSchema : yieldSchema;
+        const mapped = mapEventIterator(iterator, {
+          async value(value, done) {
+            const schema = done ? returns : yields;
             if (!schema) {
-              return result;
+              return value;
             }
-            const validated = await schema["~standard"].validate(result.value);
-            if (validated.issues) {
-              throw new ORPCError("ASYNC_ITERATOR_OBJECT_VALIDATION_FAILED", {
-                message: "AsyncIteratorObject validation failed",
+            const result = await schema["~standard"].validate(value);
+            if (result.issues) {
+              throw new ORPCError("EVENT_ITERATOR_VALIDATION_FAILED", {
+                message: "Event iterator validation failed",
                 cause: new ValidationError({
-                  issues: validated.issues,
-                  message: "AsyncIteratorObject validation failed",
-                  invalidData: result.value
+                  issues: result.issues,
+                  message: "Event iterator validation failed",
+                  data: value
                 })
               });
             }
-            return { done: result.done, value: validated.value };
-          }
+            return result.value;
+          },
+          error: async (error) => error
         });
         return { value: mapped };
       }
     }
   };
 }
-function getAsyncIteratorObjectSchemaDetails(schema) {
+function getEventIteratorSchemaDetails(schema) {
   if (schema === void 0) {
     return void 0;
   }
-  return schema["~standard"][ASYNC_ITERATOR_OBJECT_SCHEMA_DETAILS_SYMBOL];
+  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": {
-      vendor: ORPC_NAME,
+      vendor: "custom",
       version: 1,
       async validate(value) {
         if (map) {
@@ -205,6 +351,7 @@ function type(...[map]) {
     }
   };
 }
+
 function isSchemaIssue(issue) {
   if (!isTypescriptObject(issue) || typeof issue.message !== "string") {
     return false;
@@ -220,4 +367,4 @@ function isSchemaIssue(issue) {
   return true;
 }
 
-export { ContractBuilder, HIDDEN_META_PLUGINS_SYMBOL, ProcedureContract, ValidationError, asyncIteratorObject, augmentContractRouter, createContractClientFactory, asyncIteratorObject as eventIterator, getAsyncIteratorObjectSchemaDetails, getHiddenMetaPlugins, getPathMeta, isSchemaIssue, mergeErrorMap, meta, oc, resolveBasePathMeta, resolveMetaPlugins, setHiddenMetaPlugins, type };
+export { ContractBuilder, ContractProcedure, ValidationError, enhanceContractRouter, enhanceRoute, eventIterator, fallbackContractConfig, getContractRouter, getEventIteratorSchemaDetails, inferRPCMethodFromContractRouter, isContractProcedure, isSchemaIssue, mergeErrorMap, mergeMeta, mergePrefix, mergeRoute, mergeTags, minifyContractRouter, oc, populateContractRouterPaths, prefixRoute, type, unshiftTagRoute };

package/dist/plugins/index.d.mts

@@ -1,38 +1,43 @@
 import { ClientContext } from '@orpc/client';
 import { StandardLinkPlugin, StandardLinkOptions } from '@orpc/client/standard';
-import { R as RouterContract } from '../shared/contract.Do92aRJ4.mjs';
+import { A as AnyContractRouter } from '../shared/contract.TuRtB1Ca.mjs';
 import '@orpc/shared';
 import '@standard-schema/spec';
+import 'openapi-types';
 
-interface RequestValidationLinkPluginOptions<_T extends ClientContext> {
-    /**
-     * Forwards the locally validated/transformed input downstream.
-     *
-     * Disabled by default because some schema transforms produce a locally valid
-     * value that cannot be validated successfully again by the server.
-     * Keeping the original input as the flow input is the safer default.
-     *
-     * @default false
-     */
-    forwardValidatedInput?: boolean | undefined;
+declare class RequestValidationPluginError extends Error {
 }
 /**
- * Validates client request input against contract schemas before the request is encoded.
+ * A link plugin that validates client requests against your contract schema,
+ * ensuring that data sent to your server matches the expected types defined in your contract.
+ *
+ * @throws {ORPCError} with code `BAD_REQUEST` (same as server side) if input doesn't match the expected schema
+ * @see {@link https://orpc.dev/docs/plugins/request-validation Request Validation Plugin Docs}
  */
-declare class RequestValidationLinkPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
+declare class RequestValidationPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
     private readonly contract;
-    name: string;
-    private readonly forwardValidatedInput;
-    constructor(contract: RouterContract, options?: RequestValidationLinkPluginOptions<T>);
-    init(options: StandardLinkOptions<T>): StandardLinkOptions<T>;
+    constructor(contract: AnyContractRouter);
+    init(options: StandardLinkOptions<T>): void;
 }
 
-declare class ResponseValidationLinkPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
+/**
+ * A link plugin that validates server responses against your contract schema,
+ * ensuring that data returned from your server matches the expected types defined in your contract.
+ *
+ * - Throws `ValidationError` if output doesn't match the expected schema
+ * - Converts mismatched defined errors to normal `ORPCError` instances
+ *
+ * @see {@link https://orpc.dev/docs/plugins/response-validation Response Validation Plugin Docs}
+ */
+declare class ResponseValidationPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
     private readonly contract;
-    name: string;
-    constructor(contract: RouterContract);
-    init(options: StandardLinkOptions<T>): StandardLinkOptions<T>;
+    constructor(contract: AnyContractRouter);
+    /**
+     * run before (validate after) retry plugin, because validation failed can't be retried
+     * run before (validate after) durable iterator plugin, because we expect durable iterator to validation (if user use it)
+     */
+    order: number;
+    init(options: StandardLinkOptions<T>): void;
 }
 
-export { RequestValidationLinkPlugin, ResponseValidationLinkPlugin };
-export type { RequestValidationLinkPluginOptions };
+export { RequestValidationPlugin, RequestValidationPluginError, ResponseValidationPlugin };

package/dist/plugins/index.d.ts

@@ -1,38 +1,43 @@
 import { ClientContext } from '@orpc/client';
 import { StandardLinkPlugin, StandardLinkOptions } from '@orpc/client/standard';
-import { R as RouterContract } from '../shared/contract.Do92aRJ4.js';
+import { A as AnyContractRouter } from '../shared/contract.TuRtB1Ca.js';
 import '@orpc/shared';
 import '@standard-schema/spec';
+import 'openapi-types';
 
-interface RequestValidationLinkPluginOptions<_T extends ClientContext> {
-    /**
-     * Forwards the locally validated/transformed input downstream.
-     *
-     * Disabled by default because some schema transforms produce a locally valid
-     * value that cannot be validated successfully again by the server.
-     * Keeping the original input as the flow input is the safer default.
-     *
-     * @default false
-     */
-    forwardValidatedInput?: boolean | undefined;
+declare class RequestValidationPluginError extends Error {
 }
 /**
- * Validates client request input against contract schemas before the request is encoded.
+ * A link plugin that validates client requests against your contract schema,
+ * ensuring that data sent to your server matches the expected types defined in your contract.
+ *
+ * @throws {ORPCError} with code `BAD_REQUEST` (same as server side) if input doesn't match the expected schema
+ * @see {@link https://orpc.dev/docs/plugins/request-validation Request Validation Plugin Docs}
  */
-declare class RequestValidationLinkPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
+declare class RequestValidationPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
     private readonly contract;
-    name: string;
-    private readonly forwardValidatedInput;
-    constructor(contract: RouterContract, options?: RequestValidationLinkPluginOptions<T>);
-    init(options: StandardLinkOptions<T>): StandardLinkOptions<T>;
+    constructor(contract: AnyContractRouter);
+    init(options: StandardLinkOptions<T>): void;
 }
 
-declare class ResponseValidationLinkPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
+/**
+ * A link plugin that validates server responses against your contract schema,
+ * ensuring that data returned from your server matches the expected types defined in your contract.
+ *
+ * - Throws `ValidationError` if output doesn't match the expected schema
+ * - Converts mismatched defined errors to normal `ORPCError` instances
+ *
+ * @see {@link https://orpc.dev/docs/plugins/response-validation Response Validation Plugin Docs}
+ */
+declare class ResponseValidationPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
     private readonly contract;
-    name: string;
-    constructor(contract: RouterContract);
-    init(options: StandardLinkOptions<T>): StandardLinkOptions<T>;
+    constructor(contract: AnyContractRouter);
+    /**
+     * run before (validate after) retry plugin, because validation failed can't be retried
+     * run before (validate after) durable iterator plugin, because we expect durable iterator to validation (if user use it)
+     */
+    order: number;
+    init(options: StandardLinkOptions<T>): void;
 }
 
-export { RequestValidationLinkPlugin, ResponseValidationLinkPlugin };
-export type { RequestValidationLinkPluginOptions };
+export { RequestValidationPlugin, RequestValidationPluginError, ResponseValidationPlugin };