@hulla/api-node 0.0.0-stage → 2.0.0

package/dist/http.d.ts

@@ -0,0 +1,26 @@
+import { AdapterErrorInput, AdapterResponse, AdapterRuntimeOptions } from "@hulla/api/adapters";
+import { Awaitable, ServerAdapter, ServerContextInput, ServerExecutableFor } from "@hulla/api/server";
+import { IncomingMessage, ServerResponse } from "node:http";
+import { Contract } from "@hulla/api";
+//#region src/http.d.ts
+type NodeHttpRequest = IncomingMessage;
+type NodeHttpResponse = ServerResponse<NodeHttpRequest>;
+type NodeHttpHandler = (request: NodeHttpRequest, response: NodeHttpResponse) => void;
+type NodeHttpAdapterContext = {
+  readonly request: NodeHttpRequest;
+  readonly response: NodeHttpResponse;
+};
+type NodeHttpContextInput<ContractType extends Contract = Contract> = ServerContextInput<ContractType> & NodeHttpAdapterContext;
+type NodeHttpServerErrorInput = Omit<AdapterErrorInput, 'hostContext' | 'request'> & NodeHttpAdapterContext;
+type NodeHttpServerOptions = Omit<AdapterRuntimeOptions, 'onError'> & {
+  /** Optional byte limit for adapter-owned body reads. Defaults to Infinity; host limits still apply. */
+  readonly maxBodyBytes?: number;
+  readonly onError?: ((input: NodeHttpServerErrorInput) => Awaitable<AdapterResponse | undefined | void>) | undefined;
+};
+type NodeHttpAdapter = ServerAdapter<'node-http', NodeHttpAdapterContext> & {
+  readonly mount: <const ContractType extends Contract, const Context extends object>(implementation: ServerExecutableFor<ContractType, Context, 'node-http', NodeHttpAdapterContext>, options?: NodeHttpServerOptions) => NodeHttpHandler;
+};
+/** Creates a dependency-free Node.js HTTP adapter for one server implementation or fragment. */
+declare function nodeHttpAdapter(options?: NodeHttpServerOptions): NodeHttpAdapter;
+//#endregion
+export { NodeHttpAdapter, NodeHttpAdapterContext, NodeHttpContextInput, NodeHttpHandler, NodeHttpRequest, NodeHttpResponse, NodeHttpServerErrorInput, NodeHttpServerOptions, nodeHttpAdapter };

package/dist/http.js

@@ -0,0 +1,107 @@
+import { createNodeBodyReader, nodeRequestHeader, nodeRequestHeaders, nodeRequestLifetime, writeNodeResponse } from "./index.js";
+import { bodyLimit, createAdapterHandler, errorResponse } from "@hulla/api/adapters";
+import { assertAdapterContext, createServerAdapter, serverContextAdapterId } from "@hulla/api/server";
+
+//#region src/http.ts
+function readHeader(name) {
+	return nodeRequestHeader(this.request.headers, name);
+}
+function pathname(url) {
+	const authority = url.indexOf("://");
+	const start = authority === -1 ? 0 : url.indexOf("/", authority + 3);
+	if (start === -1) return "/";
+	const query = url.indexOf("?", start);
+	const hash = url.indexOf("#", start);
+	const end = query === -1 ? hash === -1 ? url.length : hash : hash === -1 ? query : Math.min(query, hash);
+	return url.slice(start, end) || "/";
+}
+function requestQuery(url) {
+	const query = url.indexOf("?");
+	if (query === -1) return void 0;
+	const hash = url.indexOf("#", query + 1);
+	return new URLSearchParams(url.slice(query + 1, hash === -1 ? void 0 : hash));
+}
+function transportFailure(_error, response) {
+	if (response.destroyed || response.writableEnded) return;
+	if (response.headersSent) {
+		response.destroy();
+		return;
+	}
+	response.statusCode = 500;
+	response.setHeader("content-type", "text/plain; charset=utf-8");
+	response.end("Internal Server Error");
+}
+function createNodeHttpHandler(implementation, options = {}) {
+	assertAdapterContext(implementation.context, "node-http");
+	const limit = bodyLimit(options.maxBodyBytes);
+	const usesNativeContext = serverContextAdapterId(implementation.context) !== void 0;
+	const dispatch = createAdapterHandler(implementation, options.onError === void 0 ? {} : { onError: ({ hostContext, ...input }) => options.onError?.({
+		...input,
+		...hostContext
+	}) });
+	return (request, response) => {
+		const lifetime = nodeRequestLifetime(request, response);
+		const method = request.method?.toUpperCase() ?? "";
+		const dispatchMethod = method === "HEAD" ? "GET" : method;
+		const url = request.url ?? "/";
+		const query = requestQuery(url);
+		const nativeContext = {
+			request,
+			response
+		};
+		const execute = async () => {
+			const result = await dispatch({
+				request,
+				signal: lifetime.signal,
+				method: dispatchMethod,
+				pathname: pathname(url),
+				...query === void 0 ? {} : { query },
+				readHeaders: () => nodeRequestHeaders(request.headers),
+				readHeader,
+				readBody: createNodeBodyReader(request, limit),
+				...usesNativeContext ? { contextInput: nativeContext } : {},
+				...options.onError === void 0 ? {} : { hostContext: nativeContext }
+			});
+			await writeNodeResponse(result, response, method);
+		};
+		execute().catch(async (error) => {
+			const fallback = errorResponse(error, "transport");
+			let replacement;
+			try {
+				replacement = await options.onError?.({
+					error,
+					phase: "transport",
+					request,
+					response,
+					defaultResponse: fallback
+				});
+			} catch {}
+			if (response.headersSent) {
+				response.destroy();
+				return;
+			}
+			for (const name of response.getHeaderNames()) response.removeHeader(name);
+			try {
+				await writeNodeResponse(replacement ?? fallback, response, method);
+			} catch (failure) {
+				transportFailure(failure, response);
+			}
+		}).finally(lifetime.dispose);
+	};
+}
+let nodeHttpAdapterValue;
+function createNodeHttpAdapter(defaults) {
+	return createServerAdapter("node-http", { mount: (implementation, options) => createNodeHttpHandler(implementation, options === void 0 ? defaults : {
+		...defaults,
+		...options
+	}) });
+}
+/** Creates a dependency-free Node.js HTTP adapter for one server implementation or fragment. */
+function nodeHttpAdapter(options) {
+	if (options !== void 0) return createNodeHttpAdapter({ ...options });
+	nodeHttpAdapterValue ??= createNodeHttpAdapter({});
+	return nodeHttpAdapterValue;
+}
+
+//#endregion
+export { nodeHttpAdapter };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { AdapterResponse } from "@hulla/api/adapters";
+import { IncomingHttpHeaders, IncomingMessage, ServerResponse } from "node:http";
+//#region src/index.d.ts
+/** Reads one normalized Node header without copying unrelated fields. */
+declare function nodeRequestHeader(source: IncomingHttpHeaders, name: string): string | undefined;
+declare function nodeRequestHeaders(source: IncomingHttpHeaders): Readonly<Record<string, string>>;
+declare function createNodeBodyReader(request: IncomingMessage, limit: number, host?: string): (representation: string) => Promise<unknown>;
+/** Request lifetime shared by Node HTTP and Express; never retained after response completion. */
+declare function nodeRequestLifetime(request: IncomingMessage, response: ServerResponse): {
+  signal: AbortSignal;
+  dispose: () => void;
+};
+/** Native response writing; callers retain their host registration and error policy. */
+declare function writeNodeResponse(source: AdapterResponse, target: ServerResponse, method: string): Promise<void>;
+//#endregion
+export { createNodeBodyReader, nodeRequestHeader, nodeRequestHeaders, nodeRequestLifetime, writeNodeResponse };

package/dist/index.js

@@ -0,0 +1,197 @@
+import { readBodyBytes, toFetchHeaders } from "@hulla/api/adapters";
+
+//#region src/index.ts
+/** Reads one normalized Node header without copying unrelated fields. */
+function nodeRequestHeader(source, name) {
+	if (name.startsWith(":") || !Object.hasOwn(source, name)) return void 0;
+	const value = source[name];
+	return typeof value === "string" ? value : value?.join(", ");
+}
+function nodeRequestHeaders(source) {
+	const entries = Object.entries(source);
+	let length = 0;
+	for (const entry of entries) {
+		const [name, value] = entry;
+		if (value === void 0 || name.startsWith(":")) continue;
+		entry[1] = typeof value === "string" ? value : value.join(", ");
+		entries[length++] = entry;
+	}
+	entries.length = length;
+	return Object.fromEntries(entries);
+}
+function createNodeBodyReader(request, limit, host = "Node HTTP") {
+	let body;
+	return async (representation) => {
+		const bytes = await (body ??= readBodyBytes(request.iterator({ destroyOnReturn: false }), limit).catch((error) => {
+			request.resume();
+			throw error;
+		}));
+		switch (representation) {
+			case "json": return JSON.parse(new TextDecoder().decode(bytes));
+			case "text": return new TextDecoder().decode(bytes);
+			case "bytes": return bytes;
+			case "form-data": {
+				const contentType = request.headers["content-type"];
+				return new Response(bytes, { ...contentType === void 0 ? {} : { headers: { "content-type": contentType } } }).formData();
+			}
+			default: throw new TypeError(`Unsupported ${host} request body representation ${representation}`);
+		}
+	};
+}
+/** Request lifetime shared by Node HTTP and Express; never retained after response completion. */
+function nodeRequestLifetime(request, response) {
+	const controller = new AbortController();
+	const abort = () => controller.abort(/* @__PURE__ */ new Error("HTTP connection closed"));
+	const close = () => {
+		if (!response.writableEnded) abort();
+		dispose();
+	};
+	const dispose = () => {
+		request.off("aborted", abort);
+		response.off("close", close);
+		response.off("finish", dispose);
+	};
+	request.once("aborted", abort);
+	response.once("close", close);
+	response.once("finish", dispose);
+	if (request.destroyed && !request.complete) abort();
+	return {
+		signal: controller.signal,
+		dispose
+	};
+}
+function drain(response) {
+	if (response.destroyed) return Promise.reject(/* @__PURE__ */ new Error("HTTP response closed"));
+	return new Promise((resolve, reject) => {
+		const cleanup = () => {
+			response.off("drain", ready);
+			response.off("close", closed);
+			response.off("error", failed);
+		};
+		const ready = () => {
+			cleanup();
+			resolve();
+		};
+		const closed = () => failed(/* @__PURE__ */ new Error("HTTP response closed before drain"));
+		const failed = (error) => {
+			cleanup();
+			reject(error);
+		};
+		response.once("drain", ready);
+		response.once("close", closed);
+		response.once("error", failed);
+	});
+}
+async function writeStream(source, target) {
+	const iterator = Symbol.asyncIterator in source ? source[Symbol.asyncIterator]() : source[Symbol.iterator]();
+	let finished = false;
+	let returning;
+	const closeSource = async () => {
+		if (finished) return;
+		returning ??= Promise.resolve().then(() => iterator.return?.());
+		await returning;
+	};
+	const disconnected = () => {
+		closeSource().catch(() => {});
+	};
+	target.once("close", disconnected);
+	try {
+		while (!target.destroyed && !target.writableEnded) {
+			const item = await iterator.next();
+			if (item.done) {
+				finished = true;
+				break;
+			}
+			if (target.destroyed || target.writableEnded) break;
+			if (!(item.value instanceof Uint8Array)) throw new TypeError("Stream chunk must be Uint8Array");
+			if (!target.write(item.value)) await drain(target);
+		}
+		if (!target.destroyed && !target.writableEnded) target.end();
+	} finally {
+		target.off("close", disconnected);
+		await closeSource();
+	}
+}
+async function writeFetch(source, target, method) {
+	target.statusCode = source.status;
+	source.headers.forEach((value, name) => {
+		if (name !== "set-cookie") target.setHeader(name, value);
+	});
+	const cookies = source.headers.getSetCookie();
+	if (cookies.length > 0) target.setHeader("set-cookie", cookies);
+	if (source.body === null) {
+		target.end();
+		return;
+	}
+	if (method === "HEAD") {
+		await source.body.cancel();
+		target.end();
+		return;
+	}
+	const reader = source.body.getReader();
+	const close = () => {
+		reader.cancel().catch(() => {});
+	};
+	target.once("close", close);
+	try {
+		async function* chunks() {
+			try {
+				while (true) {
+					const item = await reader.read();
+					if (item.done) return;
+					yield item.value;
+				}
+			} finally {
+				await reader.cancel();
+			}
+		}
+		await writeStream(chunks(), target);
+	} finally {
+		target.off("close", close);
+		reader.releaseLock();
+	}
+}
+/** Native response writing; callers retain their host registration and error policy. */
+async function writeNodeResponse(source, target, method) {
+	const body = source.body;
+	if (body.kind === "raw") {
+		if (!(body.value instanceof Response) || body.value.status !== source.status) throw new TypeError("Raw Fetch response status must match its declared contract status");
+		return writeFetch(body.value, target, method);
+	}
+	if (body.kind === "form-data") {
+		if (!(body.value instanceof FormData)) throw new TypeError("Form data response body must be FormData");
+		return writeFetch(new Response(body.value, {
+			status: source.status,
+			headers: toFetchHeaders(source.headers)
+		}), target, method);
+	}
+	const encoded = body.kind === "json" ? JSON.stringify(body.value) : void 0;
+	if (body.kind === "json" && encoded === void 0) throw new TypeError("JSON response body cannot encode to undefined");
+	target.statusCode = source.status;
+	for (const [name, value] of Object.entries(source.headers)) target.setHeader(name, value);
+	if (method === "HEAD" || body.kind === "empty") {
+		if (body.kind === "stream") {
+			const stream = body.value;
+			await (stream[Symbol.asyncIterator]?.() ?? stream[Symbol.iterator]()).return?.();
+		}
+		target.end();
+		return;
+	}
+	switch (body.kind) {
+		case "json":
+			target.end(encoded);
+			return;
+		case "text":
+			if (typeof body.value !== "string") throw new TypeError("Text response body must be a string");
+			target.end(body.value);
+			return;
+		case "bytes":
+			if (!(body.value instanceof Uint8Array)) throw new TypeError("Byte response body must be Uint8Array");
+			target.end(body.value);
+			return;
+		case "stream": return writeStream(body.value, target);
+	}
+}
+
+//#endregion
+export { createNodeBodyReader, nodeRequestHeader, nodeRequestHeaders, nodeRequestLifetime, writeNodeResponse };

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@hulla/api-node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0",
+  "description": "Node.js HTTP adapter and shared native HTTP helpers for @hulla/api",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "import": "./dist/http.js"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rm -rf dist coverage",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@hulla/api": "2.0.0",
+    "@types/node": "^26.2.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@hulla/api": "^2.0.0",
+    "@types/node": ">=22.0.0"
+  }
+}

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.