@orpc/nest 0.0.0-next.01ede75

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 oRPC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+<div align="center">
+  <image align="center" src="https://orpc.unnoq.com/logo.webp" width=280 alt="oRPC logo" />
+</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/nest">
+    <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Fnest?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
+
+---
+
+## Highlights
+
+- **🔗 End-to-End Type Safety**: Ensure type-safe inputs, outputs, and errors from client to server.
+- **📘 First-Class OpenAPI**: Built-in support that fully adheres to the OpenAPI standard.
+- **📝 Contract-First Development**: Optionally define your API contract before implementation.
+- **⚙️ Framework Integrations**: Seamlessly integrate with TanStack Query (React, Vue, Solid, Svelte, Angular), Pinia Colada, and more.
+- **🚀 Server Actions**: Fully compatible with React Server Actions on Next.js, TanStack Start, and other platforms.
+- **🔠 Standard Schema Support**: Works out of the box with Zod, Valibot, ArkType, and other schema validators.
+- **🗃️ Native Types**: Supports native types like Date, File, Blob, BigInt, URL, and more.
+- **⏱️ Lazy Router**: Enhance cold start times with our lazy routing feature.
+- **📡 SSE & Streaming**: Enjoy full type-safe support for SSE and streaming.
+- **🌍 Multi-Runtime Support**: Fast and lightweight on Cloudflare, Deno, Bun, Node.js, and beyond.
+- **🔌 Extendability**: Easily extend functionality with plugins, middleware, and interceptors.
+- **🛡️ Reliability**: Well-tested, TypeScript-based, production-ready, and MIT licensed.
+
+## 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/openapi](https://www.npmjs.com/package/@orpc/openapi): Generate OpenAPI specs and handle OpenAPI requests.
+- [@orpc/nest](https://www.npmjs.com/package/@orpc/nest): Deeply integrate oRPC with [NestJS](https://nestjs.com/).
+- [@orpc/react](https://www.npmjs.com/package/@orpc/react): Utilities for integrating oRPC with React and React Server Actions.
+- [@orpc/tanstack-query](https://www.npmjs.com/package/@orpc/tanstack-query): [TanStack Query](https://tanstack.com/query/latest) integration.
+- [@orpc/vue-colada](https://www.npmjs.com/package/@orpc/vue-colada): Integration with [Pinia Colada](https://pinia-colada.esm.dev/).
+- [@orpc/hey-api](https://www.npmjs.com/package/@orpc/hey-api): [Hey API](https://heyapi.dev/) integration.
+- [@orpc/zod](https://www.npmjs.com/package/@orpc/zod): More schemas that [Zod](https://zod.dev/) doesn't support yet.
+- [@orpc/valibot](https://www.npmjs.com/package/@orpc/valibot): OpenAPI spec generation from [Valibot](https://valibot.dev/).
+- [@orpc/arktype](https://www.npmjs.com/package/@orpc/arktype): OpenAPI spec generation from [ArkType](https://arktype.io/).
+
+## `@orpc/nest`
+
+Deeply integrate oRPC with [NestJS](https://nestjs.com/). Read the [documentation](https://orpc.unnoq.com/docs/openapi/integrations/implement-contract-in-nest) for more information.
+
+### Implement Contract
+
+An overview of how to implement an [oRPC contract](https://orpc.unnoq.com/docs/contract-first/define-contract) in NestJS.
+
+```ts
+import { Implement, implement, ORPCError } from '@orpc/nest'
+
+@Controller()
+export class PlanetController {
+  /**
+   * Implement a standalone procedure
+   */
+  @Implement(contract.planet.list)
+  list() {
+    return implement(contract.planet.list).handler(({ input }) => {
+      // Implement logic here
+
+      return []
+    })
+  }
+
+  /**
+   * Implement entire a contract
+   */
+  @Implement(contract.planet)
+  planet() {
+    return {
+      list: implement(contract.planet.list).handler(({ input }) => {
+        // Implement logic here
+        return []
+      }),
+      find: implement(contract.planet.find).handler(({ input }) => {
+        // Implement logic here
+        return {
+          id: 1,
+          name: 'Earth',
+          description: 'The planet Earth',
+        }
+      }),
+      create: implement(contract.planet.create).handler(({ input }) => {
+        // Implement logic here
+        return {
+          id: 1,
+          name: 'Earth',
+          description: 'The planet Earth',
+        }
+      }),
+    }
+  }
+
+  // other handlers...
+}
+```
+
+## Sponsors
+
+<p align="center">
+  <a href="https://cdn.jsdelivr.net/gh/unnoq/unnoq/sponsors.svg">
+    <img src='https://cdn.jsdelivr.net/gh/unnoq/unnoq/sponsors.svg'/>
+  </a>
+</p>
+
+## License
+
+Distributed under the MIT License. See [LICENSE](https://github.com/unnoq/orpc/blob/main/LICENSE) for more information.

package/dist/index.d.mts

@@ -0,0 +1,46 @@
+import { DynamicModule, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { AnySchema, ContractRouter, HTTPPath, AnyContractRouter, ContractProcedure } from '@orpc/contract';
+import { CreateProcedureClientOptions, Router } from '@orpc/server';
+export { ImplementedProcedure, Implementer, ImplementerInternal, ImplementerInternalWithMiddlewares, ORPCError, ProcedureImplementer, RouterImplementer, RouterImplementerWithMiddlewares, implement, onError, onFinish, onStart, onSuccess } from '@orpc/server';
+import { Promisable } from '@orpc/shared';
+import { Observable } from 'rxjs';
+import { SendStandardResponseOptions } from '@orpc/standard-server-node';
+
+declare const ORPC_MODULE_CONFIG_SYMBOL: unique symbol;
+interface ORPCModuleConfig extends CreateProcedureClientOptions<object, AnySchema, object, object, object>, SendStandardResponseOptions {
+}
+declare class ORPCModule {
+    static forRoot(config: ORPCModuleConfig): DynamicModule;
+}
+
+/**
+ * Decorator in controller handler to implement a oRPC contract.
+ *
+ * @see {@link https://orpc.unnoq.com/docs/openapi/integrations/implement-contract-in-nest#implement-your-contract NestJS Implement Contract Docs}
+ */
+declare function Implement<T extends ContractRouter<any>>(contract: T): <U extends Promisable<Router<T, Record<never, never>>>>(target: Record<PropertyKey, any>, propertyKey: string, descriptor: TypedPropertyDescriptor<(...args: any[]) => U>) => void;
+declare class ImplementInterceptor implements NestInterceptor {
+    private readonly config;
+    constructor(config: ORPCModuleConfig | undefined);
+    intercept(ctx: ExecutionContext, next: CallHandler<any>): Observable<any>;
+}
+
+declare function toNestPattern(path: HTTPPath): string;
+type PopulatedContractRouterPaths<T extends AnyContractRouter> = T extends ContractProcedure<infer UInputSchema, infer UOutputSchema, infer UErrors, infer UMeta> ? ContractProcedure<UInputSchema, UOutputSchema, UErrors, UMeta> : {
+    [K in keyof T]: T[K] extends AnyContractRouter ? PopulatedContractRouterPaths<T[K]> : never;
+};
+interface PopulateContractRouterPathsOptions {
+    path?: readonly string[];
+}
+/**
+ * populateContractRouterPaths is completely optional,
+ * because the procedure's path is required for NestJS implementation.
+ * This utility automatically populates any missing paths
+ * Using the router's keys + `/`.
+ *
+ * @see {@link https://orpc.unnoq.com/docs/openapi/integrations/implement-contract-in-nest#define-your-contract NestJS Implement Contract Docs}
+ */
+declare function populateContractRouterPaths<T extends AnyContractRouter>(router: T, options?: PopulateContractRouterPathsOptions): PopulatedContractRouterPaths<T>;
+
+export { Implement as Impl, Implement, ImplementInterceptor, ORPCModule, ORPC_MODULE_CONFIG_SYMBOL, populateContractRouterPaths, toNestPattern };
+export type { ORPCModuleConfig, PopulateContractRouterPathsOptions, PopulatedContractRouterPaths };

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { DynamicModule, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { AnySchema, ContractRouter, HTTPPath, AnyContractRouter, ContractProcedure } from '@orpc/contract';
+import { CreateProcedureClientOptions, Router } from '@orpc/server';
+export { ImplementedProcedure, Implementer, ImplementerInternal, ImplementerInternalWithMiddlewares, ORPCError, ProcedureImplementer, RouterImplementer, RouterImplementerWithMiddlewares, implement, onError, onFinish, onStart, onSuccess } from '@orpc/server';
+import { Promisable } from '@orpc/shared';
+import { Observable } from 'rxjs';
+import { SendStandardResponseOptions } from '@orpc/standard-server-node';
+
+declare const ORPC_MODULE_CONFIG_SYMBOL: unique symbol;
+interface ORPCModuleConfig extends CreateProcedureClientOptions<object, AnySchema, object, object, object>, SendStandardResponseOptions {
+}
+declare class ORPCModule {
+    static forRoot(config: ORPCModuleConfig): DynamicModule;
+}
+
+/**
+ * Decorator in controller handler to implement a oRPC contract.
+ *
+ * @see {@link https://orpc.unnoq.com/docs/openapi/integrations/implement-contract-in-nest#implement-your-contract NestJS Implement Contract Docs}
+ */
+declare function Implement<T extends ContractRouter<any>>(contract: T): <U extends Promisable<Router<T, Record<never, never>>>>(target: Record<PropertyKey, any>, propertyKey: string, descriptor: TypedPropertyDescriptor<(...args: any[]) => U>) => void;
+declare class ImplementInterceptor implements NestInterceptor {
+    private readonly config;
+    constructor(config: ORPCModuleConfig | undefined);
+    intercept(ctx: ExecutionContext, next: CallHandler<any>): Observable<any>;
+}
+
+declare function toNestPattern(path: HTTPPath): string;
+type PopulatedContractRouterPaths<T extends AnyContractRouter> = T extends ContractProcedure<infer UInputSchema, infer UOutputSchema, infer UErrors, infer UMeta> ? ContractProcedure<UInputSchema, UOutputSchema, UErrors, UMeta> : {
+    [K in keyof T]: T[K] extends AnyContractRouter ? PopulatedContractRouterPaths<T[K]> : never;
+};
+interface PopulateContractRouterPathsOptions {
+    path?: readonly string[];
+}
+/**
+ * populateContractRouterPaths is completely optional,
+ * because the procedure's path is required for NestJS implementation.
+ * This utility automatically populates any missing paths
+ * Using the router's keys + `/`.
+ *
+ * @see {@link https://orpc.unnoq.com/docs/openapi/integrations/implement-contract-in-nest#define-your-contract NestJS Implement Contract Docs}
+ */
+declare function populateContractRouterPaths<T extends AnyContractRouter>(router: T, options?: PopulateContractRouterPathsOptions): PopulatedContractRouterPaths<T>;
+
+export { Implement as Impl, Implement, ImplementInterceptor, ORPCModule, ORPC_MODULE_CONFIG_SYMBOL, populateContractRouterPaths, toNestPattern };
+export type { ORPCModuleConfig, PopulateContractRouterPathsOptions, PopulatedContractRouterPaths };

package/dist/index.mjs

@@ -0,0 +1,191 @@
+import { Module, Injectable, Inject, Optional, applyDecorators, Delete, Patch, Put, Post, Get, Head, UseInterceptors } from '@nestjs/common';
+import { toORPCError } from '@orpc/client';
+import { isContractProcedure, ContractProcedure, fallbackContractConfig } from '@orpc/contract';
+import { standardizeHTTPPath, StandardOpenAPISerializer, StandardOpenAPIJsonSerializer, StandardBracketNotationSerializer } from '@orpc/openapi-client/standard';
+import { StandardOpenAPICodec } from '@orpc/openapi/standard';
+import { getRouter, unlazy, isProcedure, createProcedureClient, ORPCError } from '@orpc/server';
+export { ORPCError, implement, onError, onFinish, onStart, onSuccess } from '@orpc/server';
+import { toArray, get } from '@orpc/shared';
+import { flattenHeader } from '@orpc/standard-server';
+import { toStandardLazyRequest, sendStandardResponse } from '@orpc/standard-server-node';
+import { mergeMap } from 'rxjs';
+import { toHttpPath } from '@orpc/client/standard';
+
+var __getOwnPropDesc$1 = Object.getOwnPropertyDescriptor;
+var __decorateClass$1 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$1(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+const ORPC_MODULE_CONFIG_SYMBOL = Symbol("ORPC_MODULE_CONFIG");
+let ORPCModule = class {
+  static forRoot(config) {
+    return {
+      module: ORPCModule,
+      providers: [
+        {
+          provide: ORPC_MODULE_CONFIG_SYMBOL,
+          useValue: config
+        },
+        ImplementInterceptor
+      ],
+      exports: [ORPC_MODULE_CONFIG_SYMBOL, ImplementInterceptor],
+      global: true
+    };
+  }
+};
+ORPCModule = __decorateClass$1([
+  Module({})
+], ORPCModule);
+
+function toNestPattern(path) {
+  return standardizeHTTPPath(path).replace(/\/\{\+([^}]+)\}/g, "/*$1").replace(/\/\{([^}]+)\}/g, "/:$1");
+}
+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;
+  }
+  const populated = {};
+  for (const key in router) {
+    populated[key] = populateContractRouterPaths(router[key], { ...options, path: [...path, key] });
+  }
+  return populated;
+}
+
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+const MethodDecoratorMap = {
+  HEAD: Head,
+  GET: Get,
+  POST: Post,
+  PUT: Put,
+  PATCH: Patch,
+  DELETE: Delete
+};
+function Implement(contract) {
+  if (isContractProcedure(contract)) {
+    const method = fallbackContractConfig("defaultMethod", contract["~orpc"].route.method);
+    const path = contract["~orpc"].route.path;
+    if (path === void 0) {
+      throw new Error(`
+        @Implement decorator requires contract to have a 'path'.
+        Please define one using 'path' property on the '.route' method.
+        Or use "populateContractRouterPaths" utility to automatically fill in any missing paths.
+      `);
+    }
+    return (target, propertyKey, descriptor) => {
+      applyDecorators(
+        MethodDecoratorMap[method](toNestPattern(path)),
+        UseInterceptors(ImplementInterceptor)
+      )(target, propertyKey, descriptor);
+    };
+  }
+  return (target, propertyKey, descriptor) => {
+    for (const key in contract) {
+      let methodName = `${propertyKey}_${key}`;
+      let i = 0;
+      while (methodName in target) {
+        methodName = `${propertyKey}_${key}_${i++}`;
+      }
+      target[methodName] = async function(...args) {
+        const router = await descriptor.value.apply(this, args);
+        return getRouter(router, [key]);
+      };
+      for (const p of Reflect.getOwnMetadataKeys(target, propertyKey)) {
+        Reflect.defineMetadata(p, Reflect.getOwnMetadata(p, target, propertyKey), target, methodName);
+      }
+      for (const p of Reflect.getOwnMetadataKeys(target.constructor, propertyKey)) {
+        Reflect.defineMetadata(p, Reflect.getOwnMetadata(p, target.constructor, propertyKey), target.constructor, methodName);
+      }
+      Implement(get(contract, [key]))(target, methodName, Object.getOwnPropertyDescriptor(target, methodName));
+    }
+  };
+}
+const codec = new StandardOpenAPICodec(
+  new StandardOpenAPISerializer(
+    new StandardOpenAPIJsonSerializer(),
+    new StandardBracketNotationSerializer()
+  )
+);
+let ImplementInterceptor = class {
+  constructor(config) {
+    this.config = config;
+  }
+  intercept(ctx, next) {
+    return next.handle().pipe(
+      mergeMap(async (impl) => {
+        const { default: procedure } = await unlazy(impl);
+        if (!isProcedure(procedure)) {
+          throw new Error(`
+            The return value of the @Implement controller handler must be a corresponding implemented router or procedure.
+          `);
+        }
+        const req = ctx.switchToHttp().getRequest();
+        const res = ctx.switchToHttp().getResponse();
+        const nodeReq = "raw" in req ? req.raw : req;
+        const nodeRes = "raw" in res ? res.raw : res;
+        const standardRequest = toStandardLazyRequest(nodeReq, nodeRes);
+        const fallbackStandardBody = standardRequest.body.bind(standardRequest);
+        standardRequest.body = () => Promise.resolve(req.body ?? fallbackStandardBody());
+        const standardResponse = await (async () => {
+          let isDecoding = false;
+          try {
+            const client = createProcedureClient(procedure, this.config);
+            isDecoding = true;
+            const input = await codec.decode(standardRequest, flattenParams(req.params), procedure);
+            isDecoding = false;
+            const output = await client(input, {
+              signal: standardRequest.signal,
+              lastEventId: flattenHeader(standardRequest.headers["last-event-id"])
+            });
+            return codec.encode(output, procedure);
+          } catch (e) {
+            const error = isDecoding && !(e instanceof ORPCError) ? new ORPCError("BAD_REQUEST", {
+              message: `Malformed request. Ensure the request body is properly formatted and the 'Content-Type' header is set correctly.`,
+              cause: e
+            }) : toORPCError(e);
+            return codec.encodeError(error);
+          }
+        })();
+        await sendStandardResponse(nodeRes, standardResponse, this.config);
+      })
+    );
+  }
+};
+ImplementInterceptor = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(ORPC_MODULE_CONFIG_SYMBOL)),
+  __decorateParam(0, Optional())
+], ImplementInterceptor);
+function flattenParams(params) {
+  const flatten = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (Array.isArray(value)) {
+      flatten[key] = value.join("/");
+    } else {
+      flatten[key] = value;
+    }
+  }
+  return flatten;
+}
+
+export { Implement as Impl, Implement, ImplementInterceptor, ORPCModule, ORPC_MODULE_CONFIG_SYMBOL, populateContractRouterPaths, toNestPattern };

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@orpc/nest",
+  "type": "module",
+  "version": "0.0.0-next.01ede75",
+  "license": "MIT",
+  "homepage": "https://orpc.unnoq.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unnoq/orpc.git",
+    "directory": "packages/nest"
+  },
+  "keywords": [
+    "unnoq",
+    "orpc"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@nestjs/common": ">=11.0.0",
+    "@nestjs/core": ">=11.0.0",
+    "express": ">=5.0.0",
+    "fastify": ">=5.0.0",
+    "rxjs": ">=7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@orpc/client": "0.0.0-next.01ede75",
+    "@orpc/contract": "0.0.0-next.01ede75",
+    "@orpc/openapi-client": "0.0.0-next.01ede75",
+    "@orpc/server": "0.0.0-next.01ede75",
+    "@orpc/shared": "0.0.0-next.01ede75",
+    "@orpc/openapi": "0.0.0-next.01ede75",
+    "@orpc/standard-server-node": "0.0.0-next.01ede75",
+    "@orpc/standard-server": "0.0.0-next.01ede75"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.1.4",
+    "@nestjs/core": "^11.1.4",
+    "@nestjs/platform-express": "^11.1.4",
+    "@nestjs/platform-fastify": "^11.1.4",
+    "@nestjs/testing": "^11.1.4",
+    "@ts-rest/core": "^3.52.1",
+    "@types/express": "^5.0.3",
+    "express": "^5.0.0",
+    "fastify": "^5.4.0",
+    "rxjs": "^7.8.1",
+    "supertest": "^7.1.3",
+    "zod": "^4.0.5"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "build:watch": "pnpm run build --watch",
+    "type:check": "tsc -b",
+    "type:check:test": "tsc -p tsconfig.test.json --noEmit"
+  }
+}