@orpc/contract 0.0.0-next.68378b4 → 0.0.0-next.683f2ee

package/dist/index.mjs

@@ -1,41 +1,15 @@
+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';
-import { isAsyncIteratorObject } from '@orpc/shared';
-
-class ValidationError extends Error {
-  issues;
-  constructor(options) {
-    super(options.message, options);
-    this.issues = options.issues;
-  }
-}
-function mergeErrorMap(errorMap1, errorMap2) {
-  return { ...errorMap1, ...errorMap2 };
-}
 
 function mergeMeta(meta1, meta2) {
   return { ...meta1, ...meta2 };
 }
 
-class ContractProcedure {
-  "~orpc";
-  constructor(def) {
-    if (def.route?.successStatus && (def.route.successStatus < 200 || def.route?.successStatus > 299)) {
-      throw new Error("[ContractProcedure] The successStatus must be between 200 and 299");
-    }
-    if (Object.values(def.errorMap).some((val) => val && val.status && (val.status < 400 || val.status > 599))) {
-      throw new Error("[ContractProcedure] The error status code must be in the 400-599 range.");
-    }
-    this["~orpc"] = def;
-  }
-}
-function isContractProcedure(item) {
-  if (item instanceof ContractProcedure) {
-    return true;
-  }
-  return (typeof item === "object" || typeof item === "function") && item !== null && "~orpc" in item && typeof item["~orpc"] === "object" && item["~orpc"] !== null && "inputSchema" in item["~orpc"] && "outputSchema" in item["~orpc"] && "errorMap" in item["~orpc"] && "route" in item["~orpc"] && "meta" in item["~orpc"];
-}
-
 function mergeRoute(a, b) {
   return { ...a, ...b };
 }
@@ -60,31 +34,94 @@ function mergePrefix(a, b) {
 function mergeTags(a, b) {
   return a ? [...a, ...b] : b;
 }
-function adaptRoute(route, options) {
+function enhanceRoute(route, options) {
   let router = route;
   if (options.prefix) {
     router = prefixRoute(router, options.prefix);
   }
-  if (options.tags) {
+  if (options.tags?.length) {
     router = unshiftTagRoute(router, options.tags);
   }
   return router;
 }
 
-function adaptContractRouter(contract, options) {
-  if (isContractProcedure(contract)) {
-    const adapted2 = new ContractProcedure({
-      ...contract["~orpc"],
-      errorMap: mergeErrorMap(options.errorMap, contract["~orpc"].errorMap),
-      route: adaptRoute(contract["~orpc"].route, options)
+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 adapted2;
+    return enhanced2;
+  }
+  if (typeof router !== "object" || router === null) {
+    return router;
+  }
+  const enhanced = {};
+  for (const key in router) {
+    enhanced[key] = enhanceContractRouter(router[key], options);
+  }
+  return enhanced;
+}
+function minifyContractRouter(router) {
+  if (isContractProcedure(router)) {
+    const procedure = {
+      "~orpc": {
+        errorMap: {},
+        meta: router["~orpc"].meta,
+        route: router["~orpc"].route
+      }
+    };
+    return procedure;
   }
-  const adapted = {};
-  for (const key in contract) {
-    adapted[key] = adaptContractRouter(contract[key], options);
+  if (typeof router !== "object" || router === null) {
+    return router;
   }
-  return adapted;
+  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 ContractProcedure {
@@ -94,7 +131,9 @@ class ContractBuilder extends ContractProcedure {
     this["~orpc"].tags = def.tags;
   }
   /**
-   * Reset initial meta
+   * Sets or overrides the initial meta.
+   *
+   * @see {@link https://orpc.dev/docs/metadata Metadata Docs}
    */
   $meta(initialMeta) {
     return new ContractBuilder({
@@ -103,7 +142,11 @@ class ContractBuilder extends ContractProcedure {
     });
   }
   /**
-   * Reset initial route
+   * 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({
@@ -111,56 +154,114 @@ class ContractBuilder extends ContractProcedure {
       route: initialRoute
     });
   }
+  /**
+   * 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"],
+      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) {
     return new ContractBuilder({
       ...this["~orpc"],
       errorMap: mergeErrorMap(this["~orpc"].errorMap, errors)
     });
   }
+  /**
+   * 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) {
     return new ContractBuilder({
       ...this["~orpc"],
       inputSchema: schema
     });
   }
+  /**
+   * Defines the output validation schema for the contract.
+   *
+   * @see {@link https://orpc.dev/docs/procedure#input-output-validation Output Validation Docs}
+   */
   output(schema) {
     return new ContractBuilder({
       ...this["~orpc"],
       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)
     });
   }
+  /**
+   * 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 adaptContractRouter(router, this["~orpc"]);
+    return enhanceContractRouter(router, this["~orpc"]);
   }
 }
 const oc = new ContractBuilder({
   errorMap: {},
-  inputSchema: void 0,
-  outputSchema: void 0,
   route: {},
   meta: {}
 });
@@ -179,11 +280,11 @@ function fallbackContractConfig(key, value) {
   return value;
 }
 
-const EVENT_ITERATOR_SCHEMA_SYMBOL = Symbol("ORPC_EVENT_ITERATOR_SCHEMA");
+const EVENT_ITERATOR_DETAILS_SYMBOL = Symbol("ORPC_EVENT_ITERATOR_DETAILS");
 function eventIterator(yields, returns) {
   return {
     "~standard": {
-      [EVENT_ITERATOR_SCHEMA_SYMBOL]: { yields, returns },
+      [EVENT_ITERATOR_DETAILS_SYMBOL]: { yields, returns },
       vendor: "orpc",
       version: 1,
       validate(iterator) {
@@ -202,7 +303,8 @@ function eventIterator(yields, returns) {
                 message: "Event iterator validation failed",
                 cause: new ValidationError({
                   issues: result.issues,
-                  message: "Event iterator validation failed"
+                  message: "Event iterator validation failed",
+                  data: value
                 })
               });
             }
@@ -219,7 +321,20 @@ function getEventIteratorSchemaDetails(schema) {
   if (schema === void 0) {
     return void 0;
   }
-  return schema["~standard"][EVENT_ITERATOR_SCHEMA_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]) {
@@ -237,4 +352,19 @@ function type(...[map]) {
   };
 }
 
-export { ContractBuilder, ContractProcedure, ValidationError, adaptContractRouter, adaptRoute, eventIterator, fallbackContractConfig, getEventIteratorSchemaDetails, isContractProcedure, mergeErrorMap, mergeMeta, mergePrefix, mergeRoute, mergeTags, oc, prefixRoute, type, unshiftTagRoute };
+function isSchemaIssue(issue) {
+  if (!isTypescriptObject(issue) || typeof issue.message !== "string") {
+    return false;
+  }
+  if (issue.path !== void 0) {
+    if (!Array.isArray(issue.path)) {
+      return false;
+    }
+    if (!issue.path.every((segment) => isPropertyKey(segment) || isTypescriptObject(segment) && isPropertyKey(segment.key))) {
+      return false;
+    }
+  }
+  return true;
+}
+
+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

@@ -0,0 +1,43 @@
+import { ClientContext } from '@orpc/client';
+import { StandardLinkPlugin, StandardLinkOptions } from '@orpc/client/standard';
+import { A as AnyContractRouter } from '../shared/contract.TuRtB1Ca.mjs';
+import '@orpc/shared';
+import '@standard-schema/spec';
+import 'openapi-types';
+
+declare class RequestValidationPluginError extends Error {
+}
+/**
+ * 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 RequestValidationPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
+    private readonly contract;
+    constructor(contract: AnyContractRouter);
+    init(options: StandardLinkOptions<T>): void;
+}
+
+/**
+ * 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;
+    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 { RequestValidationPlugin, RequestValidationPluginError, ResponseValidationPlugin };

package/dist/plugins/index.d.ts

@@ -0,0 +1,43 @@
+import { ClientContext } from '@orpc/client';
+import { StandardLinkPlugin, StandardLinkOptions } from '@orpc/client/standard';
+import { A as AnyContractRouter } from '../shared/contract.TuRtB1Ca.js';
+import '@orpc/shared';
+import '@standard-schema/spec';
+import 'openapi-types';
+
+declare class RequestValidationPluginError extends Error {
+}
+/**
+ * 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 RequestValidationPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
+    private readonly contract;
+    constructor(contract: AnyContractRouter);
+    init(options: StandardLinkOptions<T>): void;
+}
+
+/**
+ * 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;
+    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 { RequestValidationPlugin, RequestValidationPluginError, ResponseValidationPlugin };

package/dist/plugins/index.mjs

@@ -0,0 +1,81 @@
+import { ORPCError } from '@orpc/client';
+import { get } from '@orpc/shared';
+import { i as isContractProcedure, V as ValidationError, v as validateORPCError } from '../shared/contract.D_dZrO__.mjs';
+
+class RequestValidationPluginError extends Error {
+}
+class RequestValidationPlugin {
+  constructor(contract) {
+    this.contract = contract;
+  }
+  init(options) {
+    options.interceptors ??= [];
+    options.interceptors.push(async ({ next, path, input }) => {
+      const procedure = get(this.contract, path);
+      if (!isContractProcedure(procedure)) {
+        throw new RequestValidationPluginError(`No valid procedure found at path "${path.join(".")}", this may happen when the contract router is not properly configured.`);
+      }
+      const inputSchema = procedure["~orpc"].inputSchema;
+      if (inputSchema) {
+        const result = await inputSchema["~standard"].validate(input);
+        if (result.issues) {
+          throw new ORPCError("BAD_REQUEST", {
+            message: "Input validation failed",
+            data: {
+              issues: result.issues
+            },
+            cause: new ValidationError({
+              message: "Input validation failed",
+              issues: result.issues,
+              data: input
+            })
+          });
+        }
+      }
+      return await next();
+    });
+  }
+}
+
+class ResponseValidationPlugin {
+  constructor(contract) {
+    this.contract = contract;
+  }
+  /**
+   * 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 = 12e5;
+  init(options) {
+    options.interceptors ??= [];
+    options.interceptors.push(async ({ next, path }) => {
+      const procedure = get(this.contract, path);
+      if (!isContractProcedure(procedure)) {
+        throw new Error(`[ResponseValidationPlugin] no valid procedure found at path "${path.join(".")}", this may happen when the contract router is not properly configured.`);
+      }
+      try {
+        const output = await next();
+        const outputSchema = procedure["~orpc"].outputSchema;
+        if (!outputSchema) {
+          return output;
+        }
+        const result = await outputSchema["~standard"].validate(output);
+        if (result.issues) {
+          throw new ValidationError({
+            message: "Server response output does not match expected schema",
+            issues: result.issues,
+            data: output
+          });
+        }
+        return result.value;
+      } catch (e) {
+        if (e instanceof ORPCError) {
+          throw await validateORPCError(procedure["~orpc"].errorMap, e);
+        }
+        throw e;
+      }
+    });
+  }
+}
+
+export { RequestValidationPlugin, RequestValidationPluginError, ResponseValidationPlugin };

package/dist/shared/contract.D_dZrO__.mjs

@@ -0,0 +1,53 @@
+import { fallbackORPCErrorStatus, ORPCError, isORPCErrorStatus } from '@orpc/client';
+
+class ValidationError extends Error {
+  issues;
+  data;
+  constructor(options) {
+    super(options.message, options);
+    this.issues = options.issues;
+    this.data = options.data;
+  }
+}
+function mergeErrorMap(errorMap1, errorMap2) {
+  return { ...errorMap1, ...errorMap2 };
+}
+async function validateORPCError(map, error) {
+  const { code, status, message, data, cause, defined } = error;
+  const config = map?.[error.code];
+  if (!config || fallbackORPCErrorStatus(error.code, config.status) !== error.status) {
+    return defined ? new ORPCError(code, { defined: false, status, message, data, cause }) : error;
+  }
+  if (!config.data) {
+    return defined ? error : new ORPCError(code, { defined: true, status, message, data, cause });
+  }
+  const validated = await config.data["~standard"].validate(error.data);
+  if (validated.issues) {
+    return defined ? new ORPCError(code, { defined: false, status, message, data, cause }) : error;
+  }
+  return new ORPCError(code, { defined: true, status, message, data: validated.value, cause });
+}
+
+class ContractProcedure {
+  /**
+   * This property holds the defined options for the contract procedure.
+   */
+  "~orpc";
+  constructor(def) {
+    if (def.route?.successStatus && isORPCErrorStatus(def.route.successStatus)) {
+      throw new Error("[ContractProcedure] Invalid successStatus.");
+    }
+    if (Object.values(def.errorMap).some((val) => val && val.status && !isORPCErrorStatus(val.status))) {
+      throw new Error("[ContractProcedure] Invalid error status code.");
+    }
+    this["~orpc"] = def;
+  }
+}
+function isContractProcedure(item) {
+  if (item instanceof ContractProcedure) {
+    return true;
+  }
+  return (typeof item === "object" || typeof item === "function") && item !== null && "~orpc" in item && typeof item["~orpc"] === "object" && item["~orpc"] !== null && "errorMap" in item["~orpc"] && "route" in item["~orpc"] && "meta" in item["~orpc"];
+}
+
+export { ContractProcedure as C, ValidationError as V, isContractProcedure as i, mergeErrorMap as m, validateORPCError as v };