@hulla/api-nestjs 0.0.0-stage → 2.0.1

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import "reflect-metadata";
+import { CompiledContractRoute, Contract } from "@hulla/api";
+import { AdapterErrorInput, AdapterResponse } from "@hulla/api/adapters";
+import { Awaitable, ServerAdapter, ServerContextInput, ServerExecutableFor } from "@hulla/api/server";
+import { DynamicModule, InjectionToken, ModuleMetadata, Provider, Scope, Type } from "@nestjs/common";
+import { IncomingHttpHeaders, IncomingMessage } from "node:http";
+//#region src/index.d.ts
+/** Common Express/Fastify request fields. Pass native request/response types to nestAdapter for host-specific fields. */
+type NestRequest = {
+  readonly method: string;
+  readonly url: string;
+  readonly headers: IncomingHttpHeaders;
+  readonly params?: Readonly<Record<string, string>>;
+  readonly body?: unknown;
+  readonly raw?: IncomingMessage;
+};
+type NestAdapterContext<Request extends NestRequest = NestRequest, Response = unknown> = {
+  readonly request: Request;
+  readonly response: Response;
+};
+type NestContextInput<ContractType extends Contract = Contract, Request extends NestRequest = NestRequest, Response = unknown> = ServerContextInput<ContractType> & NestAdapterContext<Request, Response>;
+type NestServerErrorInput<Request extends NestRequest = NestRequest, Response = unknown> = Omit<AdapterErrorInput, 'request' | 'hostContext'> & NestAdapterContext<Request, Response>;
+type NestServerOptions<Request extends NestRequest = NestRequest, Response = unknown> = {
+  readonly onError?: (input: NestServerErrorInput<Request, Response>) => Awaitable<AdapterResponse | undefined | void>;
+  readonly controllerDecorators?: readonly ClassDecorator[];
+  readonly routeDecorators?: (route: Pick<CompiledContractRoute, 'key' | 'method' | 'path'>) => readonly MethodDecorator[];
+};
+type NestFactoryOptions<ContractType extends Contract, Context extends object, Dependencies extends unknown[], Request extends NestRequest, Response> = NestServerOptions<Request, Response> & {
+  readonly imports?: ModuleMetadata['imports'];
+  readonly providers?: Provider[];
+  readonly inject: { readonly [Key in keyof Dependencies]: InjectionToken<Dependencies[Key]>; };
+  readonly useFactory: (...dependencies: Dependencies) => Awaitable<ServerExecutableFor<ContractType, Context, 'nestjs', NestAdapterContext<Request, Response>>>;
+  readonly scope?: Scope;
+};
+type NestAdapter<Request extends NestRequest = NestRequest, Response = unknown> = ServerAdapter<'nestjs', NestAdapterContext<Request, Response>> & {
+  /** Returns a native controller for the application's @Module({ controllers: [...] }). Supports fragments. */
+  readonly mount: <const ContractType extends Contract, const Context extends object>(implementation: ServerExecutableFor<ContractType, Context, 'nestjs', NestAdapterContext<Request, Response>>, options?: NestServerOptions<Request, Response>) => Type<object>;
+  /** Creates an injectable implementation provider and native controller, including request-scoped dependencies. */
+  readonly register: <const ContractType extends Contract, const Context extends object, Dependencies extends unknown[]>(contract: ContractType, options: NestFactoryOptions<ContractType, Context, Dependencies, Request, Response>) => DynamicModule;
+};
+declare function nestAdapter<Request extends NestRequest = NestRequest, Response = unknown>(defaults?: NestServerOptions<Request, Response>): NestAdapter<Request, Response>;
+//#endregion
+export { NestAdapter, NestAdapterContext, NestContextInput, NestFactoryOptions, NestRequest, NestServerErrorInput, NestServerOptions, nestAdapter };

package/dist/index.js

@@ -0,0 +1,184 @@
+import "reflect-metadata";
+import { Readable } from "node:stream";
+import { compileContract } from "@hulla/api";
+import { nodeRequestLifetime } from "@hulla/api-node";
+import { createAdapterRuntime, errorResponse, toFetchResponse } from "@hulla/api/adapters";
+import { assertAdapterContext, createServerAdapter } from "@hulla/api/server";
+import { Controller, Inject, Module, Req, RequestMapping, RequestMethod, Res, StreamableFile } from "@nestjs/common";
+import { HttpAdapterHost } from "@nestjs/core";
+
+//#region src/index.ts
+const routeKey = (route) => JSON.stringify(route.key);
+function runtime(implementation, options) {
+	assertAdapterContext(implementation.context, "nestjs");
+	return createAdapterRuntime(implementation, options.onError === void 0 ? {} : { onError: ({ hostContext, ...input }) => options.onError({
+		...input,
+		...hostContext
+	}) });
+}
+function nodeResponse(response) {
+	return response.raw ?? response;
+}
+function readable(source, response, onError) {
+	const stream = Readable.from(source, { objectMode: false });
+	const disconnected = () => stream.destroy();
+	response.once("close", disconnected);
+	stream.once("close", () => response.off("close", disconnected));
+	stream.once("error", (error) => {
+		onError(error);
+		response.destroy();
+	});
+	return stream;
+}
+async function output(result, host, request, response, observe) {
+	const native = host.httpAdapter;
+	let body = result.body;
+	let headers = result.headers;
+	if (body.kind === "raw" || body.kind === "form-data") {
+		const web = toFetchResponse(result);
+		const values = Object.fromEntries(web.headers);
+		const cookies = web.headers.getSetCookie();
+		if (cookies.length > 0) values["set-cookie"] = cookies;
+		headers = values;
+		body = web.body === null ? {
+			kind: "empty",
+			value: void 0
+		} : {
+			kind: "stream",
+			value: (async function* () {
+				const reader = web.body.getReader();
+				try {
+					while (true) {
+						const item = await reader.read();
+						if (item.done) return;
+						yield item.value;
+					}
+				} finally {
+					await reader.cancel().catch(() => {});
+					reader.releaseLock();
+				}
+			})()
+		};
+		if (request.method === "HEAD") await web.body?.cancel();
+	}
+	native.status(response, result.status);
+	for (const [name, value] of Object.entries(headers)) if (typeof value === "string") native.setHeader(response, name, value);
+	else for (const field of value) native.appendHeader(response, name, field);
+	if (request.method === "HEAD") {
+		if (body.kind === "stream") await body.value[Symbol.asyncIterator]().return?.();
+		return;
+	}
+	if (body.kind === "empty") return void 0;
+	if (body.kind === "stream") {
+		const type = headers["content-type"];
+		return new StreamableFile(readable(body.value, nodeResponse(response), observe), typeof type === "string" ? { type } : {});
+	}
+	if (body.kind === "bytes") return new StreamableFile(body.value);
+	return body.value;
+}
+function controller(routes, options, configured, token) {
+	for (const route of routes) if (route.method === "QUERY") throw new TypeError("NestJS integration does not support QUERY routes across its supported host versions");
+	class ContractController {
+		host;
+		routes;
+		constructor(host, injected) {
+			this.host = host;
+			if (!["express", "fastify"].includes(host.httpAdapter.getType())) throw new TypeError("NestJS integration requires the Express or Fastify platform adapter");
+			const runtime = injected ?? configured;
+			this.routes = new Map(runtime.routes.map((route) => [routeKey(route), route]));
+			if (this.routes.size !== routes.length || routes.some((route) => !this.routes.has(routeKey(route)))) throw new TypeError("NestJS factory must implement every registered contract route");
+		}
+	}
+	Controller()(ContractController);
+	Inject(HttpAdapterHost)(ContractController, void 0, 0);
+	if (token) Inject(token)(ContractController, void 0, 1);
+	for (const [index, route] of routes.entries()) {
+		const name = `operation${index}`;
+		Object.defineProperty(ContractController.prototype, name, {
+			configurable: true,
+			value: async function(request, response) {
+				const raw = request.raw ?? request;
+				const lifetime = nodeRequestLifetime(raw, nodeResponse(response));
+				const nativeContext = {
+					request,
+					response
+				};
+				const headers = {};
+				for (const [name, value] of Object.entries(request.headers)) if (value !== void 0) headers[name] = typeof value === "string" ? value : value.join(", ");
+				const query = request.url.indexOf("?");
+				return output(await this.routes.get(routeKey(route)).execute({
+					request,
+					signal: lifetime.signal,
+					contextInput: nativeContext,
+					hostContext: nativeContext,
+					params: request.params ?? {},
+					headers,
+					...query < 0 ? {} : { query: new URLSearchParams(request.url.slice(query + 1)) },
+					...request.body === void 0 ? {} : { body: { value: request.body } },
+					readBody: async () => {
+						throw new TypeError("NestJS body is unavailable; configure the matching host parser before mounting");
+					}
+				}), this.host, request, response, (error) => {
+					Promise.resolve().then(() => options.onError?.({
+						...nativeContext,
+						error,
+						phase: "transport",
+						route,
+						defaultResponse: errorResponse(error, "transport")
+					})).catch(() => {});
+				});
+			}
+		});
+		const descriptor = Object.getOwnPropertyDescriptor(ContractController.prototype, name);
+		RequestMapping({
+			path: route.path,
+			method: RequestMethod[route.method]
+		})(ContractController.prototype, name, descriptor);
+		Req()(ContractController.prototype, name, 0);
+		Res({ passthrough: true })(ContractController.prototype, name, 1);
+		for (const decorate of options.routeDecorators?.(route) ?? []) decorate(ContractController.prototype, name, descriptor);
+	}
+	for (const decorate of options.controllerDecorators ?? []) decorate(ContractController);
+	return ContractController;
+}
+function nestAdapter(defaults = {}) {
+	const configured = { ...defaults };
+	return createServerAdapter("nestjs", {
+		mount: (implementation, options) => {
+			const merged = {
+				...configured,
+				...options
+			};
+			const compiled = runtime(implementation, merged);
+			return controller(compiled.routes, merged, compiled);
+		},
+		register: (contract, options) => {
+			const merged = {
+				...configured,
+				...options
+			};
+			const token = Symbol("contract runtime");
+			const generated = controller(compileContract(contract).routes, merged, void 0, token);
+			class ContractModule {}
+			Module({})(ContractModule);
+			return {
+				module: ContractModule,
+				controllers: [generated],
+				imports: options.imports ?? [],
+				providers: [...options.providers ?? [], {
+					provide: token,
+					inject: [...options.inject],
+					...options.scope === void 0 ? {} : { scope: options.scope },
+					useFactory: async (...dependencies) => {
+						const implementation = await options.useFactory(...dependencies);
+						if (implementation.contract !== contract) throw new TypeError("NestJS implementation factory returned a different contract");
+						return runtime(implementation, merged);
+					}
+				}]
+			};
+		}
+	});
+}
+
+//#endregion
+export { nestAdapter };

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@hulla/api-nestjs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.1",
+  "description": "Native NestJS controller and dependency-injection integration for @hulla/api",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hulladev/api.git",
+    "directory": "packages/nestjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rm -rf dist coverage",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hulla/api-node": "^2.0.1"
+  },
+  "devDependencies": {
+    "@hulla/api": "2.0.1",
+    "@nestjs/common": "^12.0.1",
+    "@nestjs/core": "^12.0.1",
+    "@nestjs/platform-express": "^12.0.1",
+    "@nestjs/platform-fastify": "^12.0.1",
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.2.0",
+    "express": "^5.2.1",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2"
+  },
+  "peerDependencies": {
+    "@hulla/api": "^2.0.1",
+    "@nestjs/common": "^11.1.0 || ^12.0.1",
+    "@nestjs/core": "^11.1.0 || ^12.0.1",
+    "@types/node": ">=22.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.