@queryweave/node 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QueryWeave contributors
+
+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,14 @@
+# `@queryweave/node`
+
+Node.js request adapters that bridge into `@queryweave/server`.
+
+```ts
+import { readNodeQuery, resolveNodeRequestUrl } from "@queryweave/node";
+
+readNodeQuery(request, productFilters);
+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.

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { IncomingMessage } from "node:http";
+import { DecodeResult, QueryModel, QueryModelValues, QueryParamDefinitions, QuerySource } from "@queryweave/core";
+//#region src/index.d.ts
+/**
+ * Node.js request adapters.
+ *
+ * This package only bridges Node primitives into `@queryweave/server`; decoding stays in one
+ * place, and no HTTP framework is required.
+ */
+/** Options accepted by {@link resolveNodeRequestUrl}. */
+interface ResolveNodeRequestUrlOptions {
+  /** Explicit authority, overriding request headers. */
+  readonly host?: string | undefined;
+  /** Explicit scheme without `:`, overriding request headers. */
+  readonly protocol?: string | undefined;
+  /** Read `x-forwarded-host` and `x-forwarded-proto` when present. Off by default. */
+  readonly trustForwardedHeaders?: boolean | undefined;
+}
+/** A read-only source backed by a Node request. */
+interface NodeRequestQuerySource extends QuerySource {
+  readonly request: IncomingMessage;
+}
+/** Resolve the absolute URL a Node request was made against. */
+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>>;
+/** Decode the query of a Node request, awaiting asynchronous validation. */
+declare function readNodeQueryAsync<TDefs extends QueryParamDefinitions>(request: IncomingMessage, model: QueryModel<TDefs>, options?: ResolveNodeRequestUrlOptions): Promise<DecodeResult<QueryModelValues<TDefs>>>;
+/** Create a request-scoped read-only source for a Node request. */
+declare function createNodeQuerySource(request: IncomingMessage, options?: ResolveNodeRequestUrlOptions): NodeRequestQuerySource;
+//#endregion
+export { NodeRequestQuerySource, ResolveNodeRequestUrlOptions, createNodeQuerySource, readNodeQuery, readNodeQueryAsync, resolveNodeRequestUrl };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,38 @@
+import { readUrlQuery, readUrlQueryAsync } from "@queryweave/server";
+
+//#region src/index.ts
+const fallbackHost = "queryweave.invalid";
+function firstHeaderValue(value) {
+	if (value === void 0) return;
+	const raw = typeof value === "string" ? value : value[0];
+	if (raw === void 0) return;
+	const first = raw.split(",")[0]?.trim();
+	return first === void 0 || first === "" ? void 0 : first;
+}
+/** Resolve the absolute URL a Node request was made against. */
+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}`);
+}
+/** Decode the query of a Node request with a model. */
+function readNodeQuery(request, model, options = {}) {
+	return readUrlQuery(resolveNodeRequestUrl(request, options), model);
+}
+/** Decode the query of a Node request, awaiting asynchronous validation. */
+async function readNodeQueryAsync(request, model, options = {}) {
+	return readUrlQueryAsync(resolveNodeRequestUrl(request, options), model);
+}
+/** Create a request-scoped read-only source for a Node request. */
+function createNodeQuerySource(request, options = {}) {
+	return {
+		request,
+		read: () => resolveNodeRequestUrl(request, options).search
+	};
+}
+
+//#endregion
+export { createNodeQuerySource, readNodeQuery, readNodeQueryAsync, resolveNodeRequestUrl };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@queryweave/node",
+  "version": "0.1.0-alpha.1",
+  "description": "Node.js request contracts for QueryWeave.",
+  "keywords": [
+    "node",
+    "query",
+    "server",
+    "state",
+    "url"
+  ],
+  "homepage": "https://github.com/boussadjra/queryweave#readme",
+  "bugs": {
+    "url": "https://github.com/boussadjra/queryweave/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boussadjra/queryweave.git",
+    "directory": "packages/node"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@queryweave/core": "0.1.0-alpha.1",
+    "@queryweave/server": "0.1.0-alpha.1"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.1",
+    "@queryweave/typescript-config": "0.0.0"
+  },
+  "engines": {
+    "node": ">=24.18.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc -p tsconfig.json",
+    "test:types": "tsc -p tsconfig.json",
+    "package:check": "publint --strict && attw --pack . --profile esm-only",
+    "clean": "node ../../scripts/clean-package.mjs"
+  }
+}