@queryweave/node 0.1.0-alpha.1 → 0.1.0-beta.2

package/README.md

@@ -2,6 +2,10 @@
 
 Node.js request adapters that bridge into `@queryweave/server`.
 
+```sh
+pnpm add @queryweave/node
+```
+
 ```ts
 import { readNodeQuery, resolveNodeRequestUrl } from "@queryweave/node";
 
@@ -12,3 +16,5 @@ resolveNodeRequestUrl(request, { trustForwardedHeaders: true });
 Decoding lives in one place: this package only translates Node primitives. Forwarded headers are
 ignored unless you opt in. No Express, Fastify, NestJS, Hono, or frontend framework dependency is
 included.
+
+Documentation: https://queryweave-docs.vercel.app/adapters/node/

package/dist/index.d.ts

@@ -11,7 +11,7 @@ import { DecodeResult, QueryModel, QueryModelValues, QueryParamDefinitions, Quer
 interface ResolveNodeRequestUrlOptions {
   /** Explicit authority, overriding request headers. */
   readonly host?: string | undefined;
-  /** Explicit scheme without `:`, overriding request headers. */
+  /** Explicit scheme without `:`, overriding request headers and the socket. */
   readonly protocol?: string | undefined;
   /** Read `x-forwarded-host` and `x-forwarded-proto` when present. Off by default. */
   readonly trustForwardedHeaders?: boolean | undefined;
@@ -20,7 +20,14 @@ interface ResolveNodeRequestUrlOptions {
 interface NodeRequestQuerySource extends QuerySource {
   readonly request: IncomingMessage;
 }
-/** Resolve the absolute URL a Node request was made against. */
+/**
+ * Resolve the absolute URL a Node request was made against.
+ *
+ * The authority comes from the `host` header, or from `:authority` on an HTTP/2 request; the
+ * scheme from `:scheme` or the socket's TLS state. Forwarded headers are read only when
+ * `trustForwardedHeaders` is set. Never throws: a request whose headers cannot form a URL still
+ * resolves, against the placeholder host.
+ */
 declare function resolveNodeRequestUrl(request: IncomingMessage, options?: ResolveNodeRequestUrlOptions): URL;
 /** Decode the query of a Node request with a model. */
 declare function readNodeQuery<TDefs extends QueryParamDefinitions>(request: IncomingMessage, model: QueryModel<TDefs>, options?: ResolveNodeRequestUrlOptions): DecodeResult<QueryModelValues<TDefs>>;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;;;UAmBiB;;WAEN;;WAEA;;WAEA;;;UAIM,+BAA+B;WACrC,SAAS;;;iBAkBJ,sBACd,SAAS,iBACT,UAAS,+BACR;;iBAmBa,cAAc,cAAc,uBAC1C,SAAS,iBACT,OAAO,WAAW,QAClB,UAAS,+BACR,aAAa,iBAAiB;;iBAKX,mBAAmB,cAAc,uBACrD,SAAS,iBACT,OAAO,WAAW,QAClB,UAAS,+BACR,QAAQ,aAAa,iBAAiB;;iBAKzB,sBACd,SAAS,iBACT,UAAS,+BACR"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;;;UAmBiB;;WAEN;;WAEA;;WAEA;;;UAIM,+BAA+B;WACrC,SAAS;;;;;;;;;;iBAoEJ,sBACd,SAAS,iBACT,UAAS,+BACR;;iBAoCa,cAAc,cAAc,uBAC1C,SAAS,iBACT,OAAO,WAAW,QAClB,UAAS,+BACR,aAAa,iBAAiB;;iBAKX,mBAAmB,cAAc,uBACrD,SAAS,iBACT,OAAO,WAAW,QAClB,UAAS,+BACR,QAAQ,aAAa,iBAAiB;;iBAKzB,sBACd,SAAS,iBACT,UAAS,+BACR"}

package/dist/index.js

@@ -2,6 +2,7 @@ import { readUrlQuery, readUrlQueryAsync } from "@queryweave/server";
 
 //#region src/index.ts
 const fallbackHost = "queryweave.invalid";
+const absoluteForm = /^[a-z][a-z0-9+.-]*:\/\//iu;
 function firstHeaderValue(value) {
 	if (value === void 0) return;
 	const raw = typeof value === "string" ? value : value[0];
@@ -9,13 +10,63 @@ function firstHeaderValue(value) {
 	const first = raw.split(",")[0]?.trim();
 	return first === void 0 || first === "" ? void 0 : first;
 }
-/** Resolve the absolute URL a Node request was made against. */
+/**
+* The request target as the client sent it.
+*
+* Frameworks that mount routers rewrite `url` to strip the mount prefix and keep the original in
+* `originalUrl`; the original is the one a canonical URL should be built from.
+*/
+function requestTarget(request) {
+	const original = request.originalUrl;
+	if (typeof original === "string" && original !== "") return original;
+	return request.url ?? "/";
+}
+function isEncrypted(request) {
+	return request.socket?.encrypted === true;
+}
+/**
+* Compose an origin-form target onto an authority without letting the target reach the host.
+*
+* `new URL("//evil.example/p", base)` would treat the path as protocol-relative; setting the
+* path and query separately keeps a `//` path on the request's own host. A malformed authority
+* falls back to the placeholder host rather than throwing.
+*/
+function composeUrl(protocol, host, target) {
+	let url;
+	try {
+		url = new URL(`${protocol}://${host}/`);
+	} catch {
+		url = new URL(`http://${fallbackHost}/`);
+	}
+	const hash = target.indexOf("#");
+	const withoutHash = hash === -1 ? target : target.slice(0, hash);
+	const query = withoutHash.indexOf("?");
+	const path = query === -1 ? withoutHash : withoutHash.slice(0, query);
+	url.pathname = path.startsWith("/") ? path : `/${path}`;
+	url.search = query === -1 ? "" : withoutHash.slice(query + 1);
+	return url;
+}
+/**
+* Resolve the absolute URL a Node request was made against.
+*
+* The authority comes from the `host` header, or from `:authority` on an HTTP/2 request; the
+* scheme from `:scheme` or the socket's TLS state. Forwarded headers are read only when
+* `trustForwardedHeaders` is set. Never throws: a request whose headers cannot form a URL still
+* resolves, against the placeholder host.
+*/
 function resolveNodeRequestUrl(request, options = {}) {
 	const headers = request.headers;
 	const trusted = options.trustForwardedHeaders === true;
-	const host = options.host ?? (trusted ? firstHeaderValue(headers["x-forwarded-host"]) : void 0) ?? firstHeaderValue(headers.host) ?? fallbackHost;
-	const protocol = options.protocol ?? (trusted ? firstHeaderValue(headers["x-forwarded-proto"]) : void 0) ?? "http";
-	return new URL(request.url ?? "/", `${protocol}://${host}`);
+	const host = options.host ?? (trusted ? firstHeaderValue(headers["x-forwarded-host"]) : void 0) ?? firstHeaderValue(headers.host) ?? firstHeaderValue(headers[":authority"]) ?? fallbackHost;
+	const protocol = options.protocol ?? (trusted ? firstHeaderValue(headers["x-forwarded-proto"]) : void 0) ?? firstHeaderValue(headers[":scheme"]) ?? (isEncrypted(request) ? "https" : "http");
+	const target = requestTarget(request);
+	if (absoluteForm.test(target)) try {
+		const url = new URL(target);
+		if (options.host !== void 0) url.host = options.host;
+		if (options.protocol !== void 0) url.protocol = options.protocol;
+		return url;
+	} catch {}
+	return composeUrl(protocol, host, target);
 }
 /** Decode the query of a Node request with a model. */
 function readNodeQuery(request, model, options = {}) {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { IncomingMessage } from \"node:http\";\n\nimport type {\n  DecodeResult,\n  QueryModel,\n  QueryModelValues,\n  QueryParamDefinitions,\n  QuerySource,\n} from \"@queryweave/core\";\nimport { readUrlQuery, readUrlQueryAsync } from \"@queryweave/server\";\n\n/**\n * Node.js request adapters.\n *\n * This package only bridges Node primitives into `@queryweave/server`; decoding stays in one\n * place, and no HTTP framework is required.\n */\n\n/** Options accepted by {@link resolveNodeRequestUrl}. */\nexport interface ResolveNodeRequestUrlOptions {\n  /** Explicit authority, overriding request headers. */\n  readonly host?: string | undefined;\n  /** Explicit scheme without `:`, overriding request headers. */\n  readonly protocol?: string | undefined;\n  /** Read `x-forwarded-host` and `x-forwarded-proto` when present. Off by default. */\n  readonly trustForwardedHeaders?: boolean | undefined;\n}\n\n/** A read-only source backed by a Node request. */\nexport interface NodeRequestQuerySource extends QuerySource {\n  readonly request: IncomingMessage;\n}\n\nconst fallbackHost = \"queryweave.invalid\";\n\nfunction firstHeaderValue(value: string | readonly string[] | undefined): string | undefined {\n  if (value === undefined) {\n    return undefined;\n  }\n  const raw = typeof value === \"string\" ? value : value[0];\n  if (raw === undefined) {\n    return undefined;\n  }\n  const first = raw.split(\",\")[0]?.trim();\n  return first === undefined || first === \"\" ? undefined : first;\n}\n\n/** Resolve the absolute URL a Node request was made against. */\nexport function resolveNodeRequestUrl(\n  request: IncomingMessage,\n  options: ResolveNodeRequestUrlOptions = {},\n): URL {\n  const headers = request.headers;\n  const trusted = options.trustForwardedHeaders === true;\n\n  const host =\n    options.host ??\n    (trusted ? firstHeaderValue(headers[\"x-forwarded-host\"]) : undefined) ??\n    firstHeaderValue(headers.host) ??\n    fallbackHost;\n\n  const protocol =\n    options.protocol ??\n    (trusted ? firstHeaderValue(headers[\"x-forwarded-proto\"]) : undefined) ??\n    \"http\";\n\n  return new URL(request.url ?? \"/\", `${protocol}://${host}`);\n}\n\n/** Decode the query of a Node request with a model. */\nexport function readNodeQuery<TDefs extends QueryParamDefinitions>(\n  request: IncomingMessage,\n  model: QueryModel<TDefs>,\n  options: ResolveNodeRequestUrlOptions = {},\n): DecodeResult<QueryModelValues<TDefs>> {\n  return readUrlQuery(resolveNodeRequestUrl(request, options), model);\n}\n\n/** Decode the query of a Node request, awaiting asynchronous validation. */\nexport async function readNodeQueryAsync<TDefs extends QueryParamDefinitions>(\n  request: IncomingMessage,\n  model: QueryModel<TDefs>,\n  options: ResolveNodeRequestUrlOptions = {},\n): Promise<DecodeResult<QueryModelValues<TDefs>>> {\n  return readUrlQueryAsync(resolveNodeRequestUrl(request, options), model);\n}\n\n/** Create a request-scoped read-only source for a Node request. */\nexport function createNodeQuerySource(\n  request: IncomingMessage,\n  options: ResolveNodeRequestUrlOptions = {},\n): NodeRequestQuerySource {\n  return {\n    request,\n    read: () => resolveNodeRequestUrl(request, options).search,\n  };\n}\n"],"mappings":";;;AAiCA,MAAM,eAAe;AAErB,SAAS,iBAAiB,OAAmE;CAC3F,IAAI,UAAU,QACZ;CAEF,MAAM,MAAM,OAAO,UAAU,WAAW,QAAQ,MAAM;CACtD,IAAI,QAAQ,QACV;CAEF,MAAM,QAAQ,IAAI,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK;CACtC,OAAO,UAAU,UAAa,UAAU,KAAK,SAAY;AAC3D;;AAGA,SAAgB,sBACd,SACA,UAAwC,CAAC,GACpC;CACL,MAAM,UAAU,QAAQ;CACxB,MAAM,UAAU,QAAQ,0BAA0B;CAElD,MAAM,OACJ,QAAQ,SACP,UAAU,iBAAiB,QAAQ,mBAAmB,IAAI,WAC3D,iBAAiB,QAAQ,IAAI,KAC7B;CAEF,MAAM,WACJ,QAAQ,aACP,UAAU,iBAAiB,QAAQ,oBAAoB,IAAI,WAC5D;CAEF,OAAO,IAAI,IAAI,QAAQ,OAAO,KAAK,GAAG,SAAS,KAAK,MAAM;AAC5D;;AAGA,SAAgB,cACd,SACA,OACA,UAAwC,CAAC,GACF;CACvC,OAAO,aAAa,sBAAsB,SAAS,OAAO,GAAG,KAAK;AACpE;;AAGA,eAAsB,mBACpB,SACA,OACA,UAAwC,CAAC,GACO;CAChD,OAAO,kBAAkB,sBAAsB,SAAS,OAAO,GAAG,KAAK;AACzE;;AAGA,SAAgB,sBACd,SACA,UAAwC,CAAC,GACjB;CACxB,OAAO;EACL;EACA,YAAY,sBAAsB,SAAS,OAAO,CAAC,CAAC;CACtD;AACF"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { IncomingMessage } from \"node:http\";\n\nimport type {\n  DecodeResult,\n  QueryModel,\n  QueryModelValues,\n  QueryParamDefinitions,\n  QuerySource,\n} from \"@queryweave/core\";\nimport { readUrlQuery, readUrlQueryAsync } from \"@queryweave/server\";\n\n/**\n * Node.js request adapters.\n *\n * This package only bridges Node primitives into `@queryweave/server`; decoding stays in one\n * place, and no HTTP framework is required.\n */\n\n/** Options accepted by {@link resolveNodeRequestUrl}. */\nexport interface ResolveNodeRequestUrlOptions {\n  /** Explicit authority, overriding request headers. */\n  readonly host?: string | undefined;\n  /** Explicit scheme without `:`, overriding request headers and the socket. */\n  readonly protocol?: string | undefined;\n  /** Read `x-forwarded-host` and `x-forwarded-proto` when present. Off by default. */\n  readonly trustForwardedHeaders?: boolean | undefined;\n}\n\n/** A read-only source backed by a Node request. */\nexport interface NodeRequestQuerySource extends QuerySource {\n  readonly request: IncomingMessage;\n}\n\nconst fallbackHost = \"queryweave.invalid\";\nconst absoluteForm = /^[a-z][a-z0-9+.-]*:\\/\\//iu;\n\nfunction firstHeaderValue(value: string | readonly string[] | undefined): string | undefined {\n  if (value === undefined) {\n    return undefined;\n  }\n  const raw = typeof value === \"string\" ? value : value[0];\n  if (raw === undefined) {\n    return undefined;\n  }\n  const first = raw.split(\",\")[0]?.trim();\n  return first === undefined || first === \"\" ? undefined : first;\n}\n\n/**\n * The request target as the client sent it.\n *\n * Frameworks that mount routers rewrite `url` to strip the mount prefix and keep the original in\n * `originalUrl`; the original is the one a canonical URL should be built from.\n */\nfunction requestTarget(request: IncomingMessage): string {\n  const original = (request as { originalUrl?: unknown }).originalUrl;\n  if (typeof original === \"string\" && original !== \"\") {\n    return original;\n  }\n  return request.url ?? \"/\";\n}\n\nfunction isEncrypted(request: IncomingMessage): boolean {\n  const socket = (request as { socket?: { encrypted?: unknown } }).socket;\n  return socket?.encrypted === true;\n}\n\n/**\n * Compose an origin-form target onto an authority without letting the target reach the host.\n *\n * `new URL(\"//evil.example/p\", base)` would treat the path as protocol-relative; setting the\n * path and query separately keeps a `//` path on the request's own host. A malformed authority\n * falls back to the placeholder host rather than throwing.\n */\nfunction composeUrl(protocol: string, host: string, target: string): URL {\n  let url: URL;\n  try {\n    url = new URL(`${protocol}://${host}/`);\n  } catch {\n    url = new URL(`http://${fallbackHost}/`);\n  }\n  const hash = target.indexOf(\"#\");\n  const withoutHash = hash === -1 ? target : target.slice(0, hash);\n  const query = withoutHash.indexOf(\"?\");\n  const path = query === -1 ? withoutHash : withoutHash.slice(0, query);\n  url.pathname = path.startsWith(\"/\") ? path : `/${path}`;\n  url.search = query === -1 ? \"\" : withoutHash.slice(query + 1);\n  return url;\n}\n\n/**\n * Resolve the absolute URL a Node request was made against.\n *\n * The authority comes from the `host` header, or from `:authority` on an HTTP/2 request; the\n * scheme from `:scheme` or the socket's TLS state. Forwarded headers are read only when\n * `trustForwardedHeaders` is set. Never throws: a request whose headers cannot form a URL still\n * resolves, against the placeholder host.\n */\nexport function resolveNodeRequestUrl(\n  request: IncomingMessage,\n  options: ResolveNodeRequestUrlOptions = {},\n): URL {\n  const headers = request.headers;\n  const trusted = options.trustForwardedHeaders === true;\n\n  const host =\n    options.host ??\n    (trusted ? firstHeaderValue(headers[\"x-forwarded-host\"]) : undefined) ??\n    firstHeaderValue(headers.host) ??\n    firstHeaderValue(headers[\":authority\"]) ??\n    fallbackHost;\n\n  const protocol =\n    options.protocol ??\n    (trusted ? firstHeaderValue(headers[\"x-forwarded-proto\"]) : undefined) ??\n    firstHeaderValue(headers[\":scheme\"]) ??\n    (isEncrypted(request) ? \"https\" : \"http\");\n\n  const target = requestTarget(request);\n  if (absoluteForm.test(target)) {\n    try {\n      const url = new URL(target);\n      if (options.host !== undefined) {\n        url.host = options.host;\n      }\n      if (options.protocol !== undefined) {\n        url.protocol = options.protocol;\n      }\n      return url;\n    } catch {\n      // Fall through and treat the target as a path.\n    }\n  }\n  return composeUrl(protocol, host, target);\n}\n\n/** Decode the query of a Node request with a model. */\nexport function readNodeQuery<TDefs extends QueryParamDefinitions>(\n  request: IncomingMessage,\n  model: QueryModel<TDefs>,\n  options: ResolveNodeRequestUrlOptions = {},\n): DecodeResult<QueryModelValues<TDefs>> {\n  return readUrlQuery(resolveNodeRequestUrl(request, options), model);\n}\n\n/** Decode the query of a Node request, awaiting asynchronous validation. */\nexport async function readNodeQueryAsync<TDefs extends QueryParamDefinitions>(\n  request: IncomingMessage,\n  model: QueryModel<TDefs>,\n  options: ResolveNodeRequestUrlOptions = {},\n): Promise<DecodeResult<QueryModelValues<TDefs>>> {\n  return readUrlQueryAsync(resolveNodeRequestUrl(request, options), model);\n}\n\n/** Create a request-scoped read-only source for a Node request. */\nexport function createNodeQuerySource(\n  request: IncomingMessage,\n  options: ResolveNodeRequestUrlOptions = {},\n): NodeRequestQuerySource {\n  return {\n    request,\n    read: () => resolveNodeRequestUrl(request, options).search,\n  };\n}\n"],"mappings":";;;AAiCA,MAAM,eAAe;AACrB,MAAM,eAAe;AAErB,SAAS,iBAAiB,OAAmE;CAC3F,IAAI,UAAU,QACZ;CAEF,MAAM,MAAM,OAAO,UAAU,WAAW,QAAQ,MAAM;CACtD,IAAI,QAAQ,QACV;CAEF,MAAM,QAAQ,IAAI,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK;CACtC,OAAO,UAAU,UAAa,UAAU,KAAK,SAAY;AAC3D;;;;;;;AAQA,SAAS,cAAc,SAAkC;CACvD,MAAM,WAAY,QAAsC;CACxD,IAAI,OAAO,aAAa,YAAY,aAAa,IAC/C,OAAO;CAET,OAAO,QAAQ,OAAO;AACxB;AAEA,SAAS,YAAY,SAAmC;CAEtD,OADgB,QAAiD,QAClD,cAAc;AAC/B;;;;;;;;AASA,SAAS,WAAW,UAAkB,MAAc,QAAqB;CACvE,IAAI;CACJ,IAAI;EACF,MAAM,IAAI,IAAI,GAAG,SAAS,KAAK,KAAK,EAAE;CACxC,QAAQ;EACN,MAAM,IAAI,IAAI,UAAU,aAAa,EAAE;CACzC;CACA,MAAM,OAAO,OAAO,QAAQ,GAAG;CAC/B,MAAM,cAAc,SAAS,KAAK,SAAS,OAAO,MAAM,GAAG,IAAI;CAC/D,MAAM,QAAQ,YAAY,QAAQ,GAAG;CACrC,MAAM,OAAO,UAAU,KAAK,cAAc,YAAY,MAAM,GAAG,KAAK;CACpE,IAAI,WAAW,KAAK,WAAW,GAAG,IAAI,OAAO,IAAI;CACjD,IAAI,SAAS,UAAU,KAAK,KAAK,YAAY,MAAM,QAAQ,CAAC;CAC5D,OAAO;AACT;;;;;;;;;AAUA,SAAgB,sBACd,SACA,UAAwC,CAAC,GACpC;CACL,MAAM,UAAU,QAAQ;CACxB,MAAM,UAAU,QAAQ,0BAA0B;CAElD,MAAM,OACJ,QAAQ,SACP,UAAU,iBAAiB,QAAQ,mBAAmB,IAAI,WAC3D,iBAAiB,QAAQ,IAAI,KAC7B,iBAAiB,QAAQ,aAAa,KACtC;CAEF,MAAM,WACJ,QAAQ,aACP,UAAU,iBAAiB,QAAQ,oBAAoB,IAAI,WAC5D,iBAAiB,QAAQ,UAAU,MAClC,YAAY,OAAO,IAAI,UAAU;CAEpC,MAAM,SAAS,cAAc,OAAO;CACpC,IAAI,aAAa,KAAK,MAAM,GAC1B,IAAI;EACF,MAAM,MAAM,IAAI,IAAI,MAAM;EAC1B,IAAI,QAAQ,SAAS,QACnB,IAAI,OAAO,QAAQ;EAErB,IAAI,QAAQ,aAAa,QACvB,IAAI,WAAW,QAAQ;EAEzB,OAAO;CACT,QAAQ,CAER;CAEF,OAAO,WAAW,UAAU,MAAM,MAAM;AAC1C;;AAGA,SAAgB,cACd,SACA,OACA,UAAwC,CAAC,GACF;CACvC,OAAO,aAAa,sBAAsB,SAAS,OAAO,GAAG,KAAK;AACpE;;AAGA,eAAsB,mBACpB,SACA,OACA,UAAwC,CAAC,GACO;CAChD,OAAO,kBAAkB,sBAAsB,SAAS,OAAO,GAAG,KAAK;AACzE;;AAGA,SAAgB,sBACd,SACA,UAAwC,CAAC,GACjB;CACxB,OAAO;EACL;EACA,YAAY,sBAAsB,SAAS,OAAO,CAAC,CAAC;CACtD;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@queryweave/node",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-beta.2",
   "description": "Node.js request contracts for QueryWeave.",
   "keywords": [
     "node",
@@ -38,15 +38,15 @@
     "provenance": true
   },
   "dependencies": {
-    "@queryweave/core": "0.1.0-alpha.1",
-    "@queryweave/server": "0.1.0-alpha.1"
+    "@queryweave/core": "0.1.0-beta.2",
+    "@queryweave/server": "0.1.0-beta.2"
   },
   "devDependencies": {
     "@types/node": "26.1.1",
     "@queryweave/typescript-config": "0.0.0"
   },
   "engines": {
-    "node": ">=24.18.0"
+    "node": ">=22.12.0"
   },
   "scripts": {
     "build": "tsdown",