Node.js

Adapter

Node request primitives bridged into the server helpers.

Package: @queryweave/node
Runtime: Node.js
Depends on: @queryweave/core, @queryweave/server
Framework required: No

What it owns

One thing: turning a Node IncomingMessage into an absolute URL. Everything after that is delegated to @queryweave/server, so decoding lives in exactly one place.

What it does not own

Decoding, validation, defaults, navigation, and any HTTP framework. Express, Fastify, NestJS, and Hono are not dependencies and never will be — they all expose a request object this package can read.

Request-scoped source — reads once, never navigates

/* Scripting is off, so the canvas will never arrive: the space held for it is given back, and the text alternative is promoted from screen-reader-only to the figure's content. */ .diagram .qw-diagram-canvas { display: none; } .diagram .alternative { position: static; width: auto; height: auto; padding: 0; margin: 0; overflow: visible; clip-path: none; white-space: normal; }

Resolve an absolute URL, then hand the query to the same decoder the browser uses.

Install

pnpm add @queryweave/core @queryweave/server @queryweave/node

Example

import { createServer } from "node:http";

import { readNodeQuery } from "@queryweave/node";

createServer((request, response) => {
  const result = readNodeQuery(request, products);
  const values = result.ok ? result.value : { ...products.defaults(), ...result.partial };

  response.writeHead(200, { "content-type": "application/json" });
  response.end(JSON.stringify({ values, issues: result.issues }));
}).listen(3000);

Resolving the URL

A Node request carries a path, not an absolute URL, so the authority has to come from somewhere:

import { resolveNodeRequestUrl } from "@queryweave/node";

resolveNodeRequestUrl(request);
// http://<host header>/products?page=2

resolveNodeRequestUrl(request, { host: "example.com", protocol: "https" });
// https://example.com/products?page=2

The order of precedence is: explicit options, then forwarded headers if you opted in, then the host header, then the fallback host queryweave.invalid.

x-forwarded-host and x-forwarded-proto are attacker-controlled unless a trusted proxy sets them. They are ignored unless you pass trustForwardedHeaders: true, which you should do only when a proxy you control is guaranteed to overwrite them.

const result = readNodeQuery(request, products, { trustForwardedHeaders: true });

result.ok; // true for ?search=vue&page=2
if (result.ok) result.value.page; // 2

Only the query is decoded, so the authority does not affect the values — but it does affect any URL you build from the result.

A request-scoped source

import { createNodeQuerySource } from "@queryweave/node";

const source = createNodeQuerySource(request);
source.read(); // "?page=2"
source.request; // the original IncomingMessage

Asynchronous validation

const result = await readNodeQueryAsync(request, products);

const values = result.ok ? result.value : { ...products.defaults(), ...result.partial };
const rows = await searchProducts(values);
result.issues; // keep normalized validation issues for logging

Same rule as everywhere else: use the asynchronous form when a parameter or the model uses an asynchronous refinement.

Edge cases

A request with no URL resolves to /.
A comma-separated forwarded header uses the first entry, trimmed.
An empty header value is ignored rather than producing an empty host.
The fallback host is queryweave.invalid, chosen because .invalid can never resolve.

How it is tested

tests/node/node.test.ts covers URL resolution, header precedence, the forwarded-header opt-in, and decoding. The node consumer fixture runs the packed archive against a real node:http server.