@orpc/nest 0.0.0 → 0.0.2

package/README.md

@@ -63,7 +63,61 @@ You can find the full documentation [here](https://orpc.unnoq.com).
 
 ## `@orpc/nest`
 
-Deeply integrate oRPC with [NestJS](https://nestjs.com/).
+Deeply integrate oRPC with [NestJS](https://nestjs.com/). Read the [documentation](https://orpc.unnoq.com/docs/openapi/nest/implement-contract) 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
 

package/dist/index.d.mts

@@ -1,17 +1,36 @@
-import { AnyContractProcedure, HTTPPath, AnyContractRouter } from '@orpc/contract';
-import { BuilderConfig, ImplementerInternal } from '@orpc/server';
-export { ORPCError } from '@orpc/server';
 import { NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { ContractRouter, HTTPPath, AnyContractRouter, ContractProcedure } from '@orpc/contract';
+import { Router } from '@orpc/server';
+export { ImplementedProcedure, Implementer, ImplementerInternal, ImplementerInternalWithMiddlewares, ORPCError, ProcedureImplementer, RouterImplementer, RouterImplementerWithMiddlewares, implement } from '@orpc/server';
+import { Promisable } from '@orpc/shared';
 import { Observable } from 'rxjs';
 
-declare function Implement(contract: AnyContractProcedure): MethodDecorator;
-
+/**
+ * Decorator in controller handler to implement a oRPC contract.
+ *
+ * @see {@link https://orpc.unnoq.com/docs/openapi/nest/implement-contract#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 {
     intercept(ctx: ExecutionContext, next: CallHandler<any>): Observable<any>;
 }
 
-declare function toFastifyPattern(path: HTTPPath): string;
-
-declare function implement<T extends AnyContractRouter>(contract: T, config?: BuilderConfig): ImplementerInternal<T, Record<never, never>, Record<never, never>>;
+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/nest/implement-contract#define-your-contract NestJS Implement Contract Docs}
+ */
+declare function populateContractRouterPaths<T extends AnyContractRouter>(router: T, options?: PopulateContractRouterPathsOptions): PopulatedContractRouterPaths<T>;
 
-export { Implement, ImplementInterceptor, implement, toFastifyPattern };
+export { Implement as Impl, Implement, ImplementInterceptor, populateContractRouterPaths, toNestPattern };
+export type { PopulateContractRouterPathsOptions, PopulatedContractRouterPaths };

package/dist/index.d.ts

@@ -1,17 +1,36 @@
-import { AnyContractProcedure, HTTPPath, AnyContractRouter } from '@orpc/contract';
-import { BuilderConfig, ImplementerInternal } from '@orpc/server';
-export { ORPCError } from '@orpc/server';
 import { NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { ContractRouter, HTTPPath, AnyContractRouter, ContractProcedure } from '@orpc/contract';
+import { Router } from '@orpc/server';
+export { ImplementedProcedure, Implementer, ImplementerInternal, ImplementerInternalWithMiddlewares, ORPCError, ProcedureImplementer, RouterImplementer, RouterImplementerWithMiddlewares, implement } from '@orpc/server';
+import { Promisable } from '@orpc/shared';
 import { Observable } from 'rxjs';
 
-declare function Implement(contract: AnyContractProcedure): MethodDecorator;
-
+/**
+ * Decorator in controller handler to implement a oRPC contract.
+ *
+ * @see {@link https://orpc.unnoq.com/docs/openapi/nest/implement-contract#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 {
     intercept(ctx: ExecutionContext, next: CallHandler<any>): Observable<any>;
 }
 
-declare function toFastifyPattern(path: HTTPPath): string;
-
-declare function implement<T extends AnyContractRouter>(contract: T, config?: BuilderConfig): ImplementerInternal<T, Record<never, never>, Record<never, never>>;
+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/nest/implement-contract#define-your-contract NestJS Implement Contract Docs}
+ */
+declare function populateContractRouterPaths<T extends AnyContractRouter>(router: T, options?: PopulateContractRouterPathsOptions): PopulatedContractRouterPaths<T>;
 
-export { Implement, ImplementInterceptor, implement, toFastifyPattern };
+export { Implement as Impl, Implement, ImplementInterceptor, populateContractRouterPaths, toNestPattern };
+export type { PopulateContractRouterPathsOptions, PopulatedContractRouterPaths };

package/dist/index.mjs

@@ -1,133 +1,87 @@
-import { call, ORPCError as ORPCError$1, implementerInternal } from '@orpc/server';
-export { ORPCError } from '@orpc/server';
-import { applyDecorators, Get, Head, Put, Patch, Delete, Post, UseInterceptors } from '@nestjs/common';
-import { fallbackContractConfig } from '@orpc/contract';
-import { StandardOpenAPISerializer, StandardOpenAPIJsonSerializer, StandardBracketNotationSerializer, standardizeHTTPPath } from '@orpc/openapi-client/standard';
+import { 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 } 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 '@orpc/shared';
+import { toHttpPath } from '@orpc/client/standard';
 
-const 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;
+function toNestPattern(path) {
+  return standardizeHTTPPath(path).replace(/\/\{\+([^}]+)\}/g, "/*$1").replace(/\/\{([^}]+)\}/g, "/:$1");
 }
-class ORPCError extends Error {
-  defined;
-  code;
-  status;
-  data;
-  constructor(code, ...[options]) {
-    if (options?.status && !isORPCErrorStatus(options.status)) {
-      throw new Error("[ORPCError] Invalid error status code.");
+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)
+        }
+      });
     }
-    const message = fallbackORPCErrorMessage(code, options?.message);
-    super(message, options);
-    this.code = code;
-    this.status = fallbackORPCErrorStatus(code, options?.status);
-    this.defined = options?.defined ?? false;
-    this.data = options?.data;
+    return router;
   }
-  toJSON() {
-    return {
-      defined: this.defined,
-      code: this.code,
-      status: this.status,
-      message: this.message,
-      data: this.data
-    };
+  const populated = {};
+  for (const key in router) {
+    populated[key] = populateContractRouterPaths(router[key], { ...options, path: [...path, key] });
   }
-}
-function toORPCError(error) {
-  return error instanceof ORPCError ? error : new ORPCError("INTERNAL_SERVER_ERROR", {
-    message: "Internal server error",
-    cause: error
-  });
-}
-function isORPCErrorStatus(status) {
-  return status < 200 || status >= 400;
+  return populated;
 }
 
+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(),
@@ -137,7 +91,13 @@ const codec = new StandardOpenAPICodec(
 class ImplementInterceptor {
   intercept(ctx, next) {
     return next.handle().pipe(
-      mergeMap(async (procedure) => {
+      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;
@@ -148,13 +108,17 @@ class ImplementInterceptor {
         const standardResponse = await (async () => {
           let isDecoding = false;
           try {
+            const client = createProcedureClient(procedure);
             isDecoding = true;
             const input = await codec.decode(standardRequest, flattenParams(req.params), procedure);
             isDecoding = false;
-            const output = await call(procedure, input);
+            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$1) ? new ORPCError$1("BAD_REQUEST", {
+            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);
@@ -178,30 +142,4 @@ function flattenParams(params) {
   return flatten;
 }
 
-function toFastifyPattern(path) {
-  return standardizeHTTPPath(path).replace(/\/\{\+([^}]+)\}/g, "/*$1").replace(/\/\{([^}]+)\}/g, "/:$1");
-}
-
-function Implement(contract) {
-  const method = fallbackContractConfig("defaultMethod", contract["~orpc"].route.method);
-  const path = contract["~orpc"].route.path;
-  if (path === void 0) {
-    throw new Error(`
-      oRPC Fastify integration requires procedure to have a 'path'.
-      Please define one using 'path' property on the '.route' method.
-    `);
-  }
-  return (target, propertyKey, descriptor) => {
-    const MethodDecorator = method === "GET" ? Get : method === "HEAD" ? Head : method === "PUT" ? Put : method === "PATCH" ? Patch : method === "DELETE" ? Delete : Post;
-    applyDecorators(
-      MethodDecorator(toFastifyPattern(path)),
-      UseInterceptors(ImplementInterceptor)
-    )(target, propertyKey, descriptor);
-  };
-}
-
-function implement(contract, config = {}) {
-  return implementerInternal(contract, config, []);
-}
-
-export { Implement, ImplementInterceptor, implement, toFastifyPattern };
+export { Implement as Impl, Implement, ImplementInterceptor, populateContractRouterPaths, toNestPattern };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@orpc/nest",
   "type": "module",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "license": "MIT",
   "homepage": "https://orpc.unnoq.com",
   "repository": {
@@ -28,8 +28,7 @@
     "@nestjs/core": ">=11.0.0",
     "express": ">=5.0.0",
     "fastify": ">=5.0.0",
-    "rxjs": ">=7.0.0",
-    "@orpc/contract": "1.2.0"
+    "rxjs": ">=7.0.0"
   },
   "peerDependenciesMeta": {
     "express": {
@@ -40,27 +39,33 @@
     }
   },
   "dependencies": {
-    "@orpc/openapi-client": "1.2.0",
-    "@orpc/server": "1.2.0",
     "@orpc/client": "1.2.0",
+    "@orpc/openapi": "1.2.0",
     "@orpc/shared": "1.2.0",
+    "@orpc/contract": "1.2.0",
+    "@orpc/openapi-client": "1.2.0",
+    "@orpc/server": "1.2.0",
     "@orpc/standard-server": "1.2.0",
-    "@orpc/standard-server-node": "1.2.0",
-    "@orpc/openapi": "1.2.0"
+    "@orpc/standard-server-node": "1.2.0"
   },
   "devDependencies": {
-    "@nestjs/common": "^11.0.0",
+    "@nestjs/common": "^11.1.0",
     "@nestjs/core": "^11.0.0",
-    "@nestjs/platform-express": "^11.0.0",
-    "@nestjs/platform-fastify": "^11.0.0",
+    "@nestjs/platform-express": "^11.1.0",
+    "@nestjs/platform-fastify": "^11.1.0",
+    "@nestjs/testing": "^11.1.0",
+    "@ts-rest/core": "^3.52.1",
     "@types/express": "^5.0.1",
     "express": "^5.0.0",
     "fastify": "^5.0.0",
-    "rxjs": "^7.0.0"
+    "rxjs": "^7.0.0",
+    "supertest": "^7.1.0",
+    "zod": "^3.24.4"
   },
   "scripts": {
     "build": "unbuild",
     "build:watch": "pnpm run build --watch",
-    "type:check": "tsc -b"
+    "type:check": "tsc -b",
+    "type:check:test": "tsc -p tsconfig.test.json --noEmit"
   }
 }