@orpc/contract 0.0.0-next.cba521d → 0.0.0-next.cc4cb21

package/README.md

@@ -0,0 +1,101 @@
+<div align="center">
+  <image align="center" src="https://orpc.unnoq.com/logo.webp" width=280 />
+</div>
+
+<h1></h1>
+
+<div align="center">
+  <a href="https://codecov.io/gh/unnoq/orpc">
+    <img alt="codecov" src="https://codecov.io/gh/unnoq/orpc/branch/main/graph/badge.svg">
+  </a>
+  <a href="https://www.npmjs.com/package/@orpc/contract">
+    <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Fcontract?logo=npm" />
+  </a>
+  <a href="https://github.com/unnoq/orpc/blob/main/LICENSE">
+    <img alt="MIT License" src="https://img.shields.io/github/license/unnoq/orpc?logo=open-source-initiative" />
+  </a>
+  <a href="https://discord.gg/TXEbwRBvQn">
+    <img alt="Discord" src="https://img.shields.io/discord/1308966753044398161?color=7389D8&label&logo=discord&logoColor=ffffff" />
+  </a>
+</div>
+
+<h3 align="center">Typesafe APIs Made Simple 🪄</h3>
+
+**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, ensuring a smooth and enjoyable developer experience.
+
+---
+
+## Highlights
+
+- **End-to-End Type Safety 🔒**: Ensure complete type safety from inputs to outputs and errors, bridging server and client seamlessly.
+- **First-Class OpenAPI 📄**: Adheres to the OpenAPI standard out of the box, ensuring seamless integration and comprehensive API documentation.
+- **Contract-First Development 📜**: (Optional) Define your API contract upfront and implement it with confidence.
+- **Exceptional Developer Experience ✨**: Enjoy a streamlined workflow with robust typing and clear, in-code documentation.
+- **Multi-Runtime Support 🌍**: Run your code seamlessly on Cloudflare, Deno, Bun, Node.js, and more.
+- **Framework Integrations 🧩**: Supports Tanstack Query (React, Vue), Pinia Colada, and more.
+- **Server Actions ⚡️**: Fully compatible with React Server Actions on Next.js, TanStack Start, and more.
+- **Standard Schema Support 🗂️**: Effortlessly work with Zod, Valibot, ArkType, and others right out of the box.
+- **Fast & Lightweight 💨**: Built on native APIs across all runtimes – optimized for speed and efficiency.
+- **Native Types 📦**: Enjoy built-in support for Date, File, Blob, BigInt, URL and more with no extra setup.
+- **Lazy Router ⏱️**: Improve cold start times with our lazy routing feature.
+- **SSE & Streaming 📡**: Provides SSE and streaming features – perfect for real-time notifications and AI-powered streaming responses.
+- **Reusability 🔄**: Write once and reuse your code across multiple purposes effortlessly.
+- **Extendability 🔌**: Easily enhance oRPC with plugins, middleware, and interceptors.
+- **Reliability 🛡️**: Well-tested, fully TypeScript, production-ready, and MIT licensed for peace of mind.
+- **Simplicity 💡**: Enjoy straightforward, clean code with no hidden magic.
+
+## Documentation
+
+You can find the full documentation [here](https://orpc.unnoq.com).
+
+## Packages
+
+- [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
+- [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
+- [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
+- [@orpc/react-query](https://www.npmjs.com/package/@orpc/react-query): Integration with [React Query](https://tanstack.com/query/latest/docs/framework/react/overview).
+- [@orpc/vue-query](https://www.npmjs.com/package/@orpc/vue-query): Integration with [Vue Query](https://tanstack.com/query/latest/docs/framework/vue/overview).
+- [@orpc/vue-colada](https://www.npmjs.com/package/@orpc/vue-colada): Integration with [Pinia Colada](https://pinia-colada.esm.dev/).
+- [@orpc/openapi](https://www.npmjs.com/package/@orpc/openapi): Generate OpenAPI specs and handle OpenAPI requests.
+- [@orpc/zod](https://www.npmjs.com/package/@orpc/zod): More schemas that [Zod](https://zod.dev/) doesn't support yet.
+
+## `@orpc/contract`
+
+Build your API contract. Read the [documentation](https://orpc.unnoq.com/docs/contract-first/define-contract) for more information.
+
+```ts
+export const PlanetSchema = z.object({
+  id: z.number().int().min(1),
+  name: z.string(),
+  description: z.string().optional(),
+})
+
+export const listPlanetContract = oc
+  .input(
+    z.object({
+      limit: z.number().int().min(1).max(100).optional(),
+      cursor: z.number().int().min(0).default(0),
+    }),
+  )
+  .output(z.array(PlanetSchema))
+
+export const findPlanetContract = oc
+  .input(PlanetSchema.pick({ id: true }))
+  .output(PlanetSchema)
+
+export const createPlanetContract = oc
+  .input(PlanetSchema.omit({ id: true }))
+  .output(PlanetSchema)
+
+export const contract = {
+  planet: {
+    list: listPlanetContract,
+    find: findPlanetContract,
+    create: createPlanetContract,
+  },
+}
+```
+
+## License
+
+Distributed under the MIT License. See [LICENSE](https://github.com/unnoq/orpc/blob/main/LICENSE) for more information.

package/dist/index.js

@@ -1,12 +1,28 @@
+// src/error.ts
+var ValidationError = class extends Error {
+  issues;
+  constructor(options) {
+    super(options.message, options);
+    this.issues = options.issues;
+  }
+};
+function mergeErrorMap(errorMap1, errorMap2) {
+  return { ...errorMap1, ...errorMap2 };
+}
+
+// src/meta.ts
+function mergeMeta(meta1, meta2) {
+  return { ...meta1, ...meta2 };
+}
+
 // src/procedure.ts
 var ContractProcedure = class {
-  "~type" = "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))) {
+    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;
@@ -16,311 +32,140 @@ function isContractProcedure(item) {
   if (item instanceof ContractProcedure) {
     return true;
   }
-  return (typeof item === "object" || typeof item === "function") && item !== null && "~type" in item && item["~type"] === "ContractProcedure" && "~orpc" in item && typeof item["~orpc"] === "object" && item["~orpc"] !== null && "InputSchema" in item["~orpc"] && "OutputSchema" in item["~orpc"] && "errorMap" in item["~orpc"];
+  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"];
 }
 
-// src/procedure-decorated.ts
-var DecoratedContractProcedure = class _DecoratedContractProcedure extends ContractProcedure {
-  static decorate(procedure) {
-    if (procedure instanceof _DecoratedContractProcedure) {
-      return procedure;
-    }
-    return new _DecoratedContractProcedure(procedure["~orpc"]);
+// src/route.ts
+function mergeRoute(a, b) {
+  return { ...a, ...b };
+}
+function prefixRoute(route, prefix) {
+  if (!route.path) {
+    return route;
   }
-  route(route) {
-    return new _DecoratedContractProcedure({
-      ...this["~orpc"],
-      route: {
-        ...this["~orpc"].route,
-        ...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 adaptRoute(route, options) {
+  let router = route;
+  if (options.prefix) {
+    router = prefixRoute(router, options.prefix);
+  }
+  if (options.tags) {
+    router = unshiftTagRoute(router, options.tags);
+  }
+  return router;
+}
+
+// src/router.ts
+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)
     });
+    return adapted2;
   }
-  prefix(prefix) {
-    return new _DecoratedContractProcedure({
+  const adapted = {};
+  for (const key in contract) {
+    adapted[key] = adaptContractRouter(contract[key], options);
+  }
+  return adapted;
+}
+
+// src/builder.ts
+var ContractBuilder = class _ContractBuilder extends ContractProcedure {
+  constructor(def) {
+    super(def);
+    this["~orpc"].prefix = def.prefix;
+    this["~orpc"].tags = def.tags;
+  }
+  /**
+   * Reset initial meta
+   */
+  $meta(initialMeta) {
+    return new _ContractBuilder({
       ...this["~orpc"],
-      ...this["~orpc"].route?.path ? {
-        route: {
-          ...this["~orpc"].route,
-          path: `${prefix}${this["~orpc"].route.path}`
-        }
-      } : void 0
+      meta: initialMeta
     });
   }
-  unshiftTag(...tags) {
-    return new _DecoratedContractProcedure({
+  /**
+   * Reset initial route
+   */
+  $route(initialRoute) {
+    return new _ContractBuilder({
       ...this["~orpc"],
-      route: {
-        ...this["~orpc"].route,
-        tags: [
-          ...tags,
-          ...this["~orpc"].route?.tags?.filter((tag) => !tags.includes(tag)) ?? []
-        ]
-      }
+      route: initialRoute
     });
   }
-  input(schema, example) {
-    return new _DecoratedContractProcedure({
+  errors(errors) {
+    return new _ContractBuilder({
       ...this["~orpc"],
-      InputSchema: schema,
-      inputExample: example
+      errorMap: mergeErrorMap(this["~orpc"].errorMap, errors)
     });
   }
-  output(schema, example) {
-    return new _DecoratedContractProcedure({
+  meta(meta) {
+    return new _ContractBuilder({
       ...this["~orpc"],
-      OutputSchema: schema,
-      outputExample: example
+      meta: mergeMeta(this["~orpc"].meta, meta)
     });
   }
-  errors(errorMap) {
-    return new _DecoratedContractProcedure({
+  route(route) {
+    return new _ContractBuilder({
       ...this["~orpc"],
-      errorMap
+      route: mergeRoute(this["~orpc"].route, route)
     });
   }
-};
-
-// src/router-builder.ts
-var ContractRouterBuilder = class _ContractRouterBuilder {
-  "~type" = "ContractProcedure";
-  "~orpc";
-  constructor(def) {
-    this["~orpc"] = def;
-  }
-  prefix(prefix) {
-    return new _ContractRouterBuilder({
+  input(schema) {
+    return new _ContractBuilder({
       ...this["~orpc"],
-      prefix: `${this["~orpc"].prefix ?? ""}${prefix}`
+      inputSchema: schema
     });
   }
-  tag(...tags) {
-    return new _ContractRouterBuilder({
+  output(schema) {
+    return new _ContractBuilder({
       ...this["~orpc"],
-      tags: [...this["~orpc"].tags ?? [], ...tags]
+      outputSchema: schema
     });
   }
-  router(router) {
-    if (isContractProcedure(router)) {
-      let decorated = DecoratedContractProcedure.decorate(router);
-      if (this["~orpc"].tags) {
-        decorated = decorated.unshiftTag(...this["~orpc"].tags);
-      }
-      if (this["~orpc"].prefix) {
-        decorated = decorated.prefix(this["~orpc"].prefix);
-      }
-      return decorated;
-    }
-    const adapted = {};
-    for (const key in router) {
-      adapted[key] = this.router(router[key]);
-    }
-    return adapted;
-  }
-};
-
-// src/builder.ts
-var ContractBuilder = class {
   prefix(prefix) {
-    return new ContractRouterBuilder({
-      prefix
+    return new _ContractBuilder({
+      ...this["~orpc"],
+      prefix: mergePrefix(this["~orpc"].prefix, prefix)
     });
   }
   tag(...tags) {
-    return new ContractRouterBuilder({
-      tags
-    });
-  }
-  route(route) {
-    return new DecoratedContractProcedure({
-      route,
-      InputSchema: void 0,
-      OutputSchema: void 0,
-      errorMap: void 0
-    });
-  }
-  input(schema, example) {
-    return new DecoratedContractProcedure({
-      InputSchema: schema,
-      inputExample: example,
-      OutputSchema: void 0,
-      errorMap: void 0
-    });
-  }
-  output(schema, example) {
-    return new DecoratedContractProcedure({
-      OutputSchema: schema,
-      outputExample: example,
-      InputSchema: void 0,
-      errorMap: void 0
-    });
-  }
-  errors(errorMap) {
-    return new DecoratedContractProcedure({
-      InputSchema: void 0,
-      OutputSchema: void 0,
-      errorMap
+    return new _ContractBuilder({
+      ...this["~orpc"],
+      tags: mergeTags(this["~orpc"].tags, tags)
     });
   }
   router(router) {
-    return router;
+    return adaptContractRouter(router, this["~orpc"]);
   }
 };
-
-// src/error-orpc.ts
-import { isPlainObject } from "@orpc/shared";
-var COMMON_ORPC_ERROR_DEFS = {
-  BAD_REQUEST: {
-    status: 400,
-    message: "Bad Request"
-  },
-  UNAUTHORIZED: {
-    status: 401,
-    message: "Unauthorized"
-  },
-  FORBIDDEN: {
-    status: 403,
-    message: "Forbidden"
-  },
-  NOT_FOUND: {
-    status: 404,
-    message: "Not Found"
-  },
-  METHOD_NOT_SUPPORTED: {
-    status: 405,
-    message: "Method Not Supported"
-  },
-  NOT_ACCEPTABLE: {
-    status: 406,
-    message: "Not Acceptable"
-  },
-  TIMEOUT: {
-    status: 408,
-    message: "Request Timeout"
-  },
-  CONFLICT: {
-    status: 409,
-    message: "Conflict"
-  },
-  PRECONDITION_FAILED: {
-    status: 412,
-    message: "Precondition Failed"
-  },
-  PAYLOAD_TOO_LARGE: {
-    status: 413,
-    message: "Payload Too Large"
-  },
-  UNSUPPORTED_MEDIA_TYPE: {
-    status: 415,
-    message: "Unsupported Media Type"
-  },
-  UNPROCESSABLE_CONTENT: {
-    status: 422,
-    message: "Unprocessable Content"
-  },
-  TOO_MANY_REQUESTS: {
-    status: 429,
-    message: "Too Many Requests"
-  },
-  CLIENT_CLOSED_REQUEST: {
-    status: 499,
-    message: "Client Closed Request"
-  },
-  INTERNAL_SERVER_ERROR: {
-    status: 500,
-    message: "Internal Server Error"
-  },
-  NOT_IMPLEMENTED: {
-    status: 501,
-    message: "Not Implemented"
-  },
-  BAD_GATEWAY: {
-    status: 502,
-    message: "Bad Gateway"
-  },
-  SERVICE_UNAVAILABLE: {
-    status: 503,
-    message: "Service Unavailable"
-  },
-  GATEWAY_TIMEOUT: {
-    status: 504,
-    message: "Gateway Timeout"
-  }
-};
-function fallbackORPCErrorStatus(code, status) {
-  return status ?? COMMON_ORPC_ERROR_DEFS[code]?.status ?? 500;
-}
-function fallbackORPCErrorMessage(code, message) {
-  return message || COMMON_ORPC_ERROR_DEFS[code]?.message || code;
-}
-var ORPCError = class extends Error {
-  defined;
-  code;
-  status;
-  data;
-  constructor(options) {
-    if (options.status && (options.status < 400 || options.status >= 600)) {
-      throw new Error("[ORPCError] The error status code must be in the 400-599 range.");
-    }
-    const message = fallbackORPCErrorMessage(options.code, options.message);
-    super(message, options);
-    this.code = options.code;
-    this.status = fallbackORPCErrorStatus(options.code, options.status);
-    this.defined = options.defined ?? false;
-    this.data = options.data;
-  }
-  toJSON() {
-    return {
-      defined: this.defined,
-      code: this.code,
-      status: this.status,
-      message: this.message,
-      data: this.data
-    };
-  }
-  static isValidJSON(json) {
-    return isPlainObject(json) && "defined" in json && typeof json.defined === "boolean" && "code" in json && typeof json.code === "string" && "status" in json && typeof json.status === "number" && "message" in json && typeof json.message === "string";
-  }
-};
-function isDefinedError(error) {
-  return error instanceof ORPCError && error.defined;
-}
-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({ defined: false, code, status, message, data, cause }) : error;
-  }
-  if (!config.data) {
-    return defined ? error : new ORPCError({ defined: true, code, status, message, data, cause });
-  }
-  const validated = await config.data["~standard"].validate(error.data);
-  if (validated.issues) {
-    return defined ? new ORPCError({ defined: false, code, status, message, data, cause }) : error;
-  }
-  return new ORPCError({
-    defined: true,
-    code,
-    status,
-    message,
-    data: validated.value,
-    cause
-  });
-}
-
-// src/client-utils.ts
-async function safe(promise) {
-  try {
-    const output = await promise;
-    return [output, void 0, false];
-  } catch (e) {
-    const error = e;
-    if (isDefinedError(error)) {
-      return [void 0, error, true];
-    }
-    return [void 0, error, false];
-  }
-}
+var oc = new ContractBuilder({
+  errorMap: {},
+  inputSchema: void 0,
+  outputSchema: void 0,
+  route: {},
+  meta: {}
+});
 
 // src/config.ts
 var DEFAULT_CONFIG = {
@@ -330,51 +175,96 @@ var DEFAULT_CONFIG = {
   defaultInputStructure: "compact",
   defaultOutputStructure: "compact"
 };
-var GLOBAL_CONFIG_REF = { value: DEFAULT_CONFIG };
-function configGlobal(config) {
-  if (config.defaultSuccessStatus !== void 0 && (config.defaultSuccessStatus < 200 || config.defaultSuccessStatus > 299)) {
-    throw new Error("[configGlobal] The defaultSuccessStatus must be between 200 and 299");
-  }
-  GLOBAL_CONFIG_REF.value = config;
-}
-function fallbackToGlobalConfig(key, value) {
+function fallbackContractConfig(key, value) {
   if (value === void 0) {
-    const fallback = GLOBAL_CONFIG_REF.value[key];
-    if (fallback === void 0) {
-      return DEFAULT_CONFIG[key];
-    }
-    return fallback;
+    return DEFAULT_CONFIG[key];
   }
   return value;
 }
 
-// src/error.ts
-var ValidationError = class extends Error {
-  issues;
-  constructor(options) {
-    super(options.message, options);
-    this.issues = options.issues;
+// src/event-iterator.ts
+import { mapEventIterator, ORPCError } from "@orpc/client";
+import { isAsyncIteratorObject } from "@orpc/shared";
+var EVENT_ITERATOR_SCHEMA_SYMBOL = Symbol("ORPC_EVENT_ITERATOR_SCHEMA");
+function eventIterator(yields, returns) {
+  return {
+    "~standard": {
+      [EVENT_ITERATOR_SCHEMA_SYMBOL]: { yields, returns },
+      vendor: "orpc",
+      version: 1,
+      validate(iterator) {
+        if (!isAsyncIteratorObject(iterator)) {
+          return { issues: [{ message: "Expect event source iterator", path: [] }] };
+        }
+        const mapped = mapEventIterator(iterator, {
+          async value(value, done) {
+            const schema = done ? returns : yields;
+            if (!schema) {
+              return value;
+            }
+            const result = await schema["~standard"].validate(value);
+            if (result.issues) {
+              throw new ORPCError("EVENT_ITERATOR_VALIDATION_FAILED", {
+                message: "Event source iterator validation failed",
+                cause: new ValidationError({
+                  issues: result.issues,
+                  message: "Event source iterator validation failed"
+                })
+              });
+            }
+            return result.value;
+          },
+          error: async (error) => error
+        });
+        return { value: mapped };
+      }
+    }
+  };
+}
+function getEventIteratorSchemaDetails(schema) {
+  if (schema === void 0) {
+    return void 0;
   }
-};
+  return schema["~standard"][EVENT_ITERATOR_SCHEMA_SYMBOL];
+}
+
+// src/schema.ts
+function type(...[map]) {
+  return {
+    "~standard": {
+      vendor: "custom",
+      version: 1,
+      async validate(value) {
+        if (map) {
+          return { value: await map(value) };
+        }
+        return { value };
+      }
+    }
+  };
+}
 
 // src/index.ts
-var oc = new ContractBuilder();
+import { ORPCError as ORPCError2 } from "@orpc/client";
 export {
-  COMMON_ORPC_ERROR_DEFS,
   ContractBuilder,
   ContractProcedure,
-  ContractRouterBuilder,
-  DecoratedContractProcedure,
-  ORPCError,
+  ORPCError2 as ORPCError,
   ValidationError,
-  configGlobal,
-  fallbackORPCErrorMessage,
-  fallbackORPCErrorStatus,
-  fallbackToGlobalConfig,
+  adaptContractRouter,
+  adaptRoute,
+  eventIterator,
+  fallbackContractConfig,
+  getEventIteratorSchemaDetails,
   isContractProcedure,
-  isDefinedError,
+  mergeErrorMap,
+  mergeMeta,
+  mergePrefix,
+  mergeRoute,
+  mergeTags,
   oc,
-  safe,
-  validateORPCError
+  prefixRoute,
+  type,
+  unshiftTagRoute
 };
 //# sourceMappingURL=index.js.map