@zudojs/http 1.2.0 → 1.3.0

package/dist/httpProxy/http.proxy.js

@@ -10,7 +10,7 @@
 import { appendHeader, deleteHeader, getHeader, setHeader, } from "../httpProtocol/http.protocol.js";
 import { isValidHTTPURL, isValidHeaderValue } from "../httpValidation/index.js";
 import { isLinkLocalAddress, isLoopbackAddress, isUniqueLocalAddress, parseIpAddress, } from "../httpTrustProxy/httpTrustProxy.ip.js";
-import { assertSafeHeaderValue } from "../httpHeaders/security/index.js";
+import { assertSafeHeaderValue, escapeHeaderQuotedString, } from "../httpHeaders/security/index.js";
 import { assertProxyPathContained } from "./httpProxy.pathGuard.js";
 /* -------------------------------------------------------------------------- */
 /* Target                                                                     */
@@ -72,6 +72,16 @@ function isBlockedLiteralAddress(hostname) {
             (address.bytes[1] ?? 0) <= 127) {
             return true;
         }
+        /* 192.0.0.0/24 IETF protocol assignments (192.0.0.8, 192.0.0.170, …). */
+        if (first === 192 &&
+            (address.bytes[1] ?? 0) === 0 &&
+            (address.bytes[2] ?? 0) === 0) {
+            return true;
+        }
+        /* 198.18.0.0/15 benchmarking. */
+        if (first === 198 && ((address.bytes[1] ?? 0) & 0xfe) === 18) {
+            return true;
+        }
         return false;
     }
     const first = address.bytes[0] ?? 0;
@@ -361,6 +371,15 @@ function appendForwardedValue(headers, name, value) {
 /* -------------------------------------------------------------------------- */
 /* Standard Forwarded Header                                                  */
 /* -------------------------------------------------------------------------- */
+/**
+ * Builds an RFC 7239 `Forwarded` field value.
+ *
+ * Every parameter is escaped as a `quoted-string` when it is not a bare
+ * token, and the finished value is checked the same way `setForwardedHeaders`
+ * checks the values it writes.
+ *
+ * @throws {TypeError} If any parameter contains a control character.
+ */
 export function createForwardedHeader(address) {
     const parts = [];
     if (address.for) {
@@ -375,7 +394,9 @@ export function createForwardedHeader(address) {
     if (address.protocol) {
         parts.push(`proto=${formatForwardedValue(address.protocol)}`);
     }
-    return parts.join("; ");
+    const value = parts.join("; ");
+    assertSafeHeaderValue(value);
+    return value;
 }
 export function parseForwardedHeader(value) {
     if (!value || value.trim().length === 0) {
@@ -534,11 +555,22 @@ function formatForwardedIdentifier(value) {
     }
     return formatForwardedValue(value);
 }
+/**
+ * Emits an RFC 7239 parameter value.
+ *
+ * Wrapping a value in quotes does not neutralise a CR or LF — the control
+ * character survives into the field value and an attacker-chosen header
+ * follows it on the wire. `escapeHeaderQuotedString` rejects those characters
+ * rather than escaping them, which is what every other quoted-parameter
+ * emitter in this package already uses.
+ *
+ * @throws {TypeError} If the value contains a forbidden control character.
+ */
 function formatForwardedValue(value) {
     if (/^[A-Za-z0-9._:-]+$/.test(value)) {
         return value;
     }
-    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    return `"${escapeHeaderQuotedString(value)}"`;
 }
 function unquoteForwardedValue(value) {
     if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {

package/dist/httpQuery/index.d.ts

@@ -1,7 +1,16 @@
 /**
  * @zudojs/http/httpQuery
  *
- * HTTP query string parsing and utilities.
+ * HTTP query string parsing, request accessors, and serialization.
+ *
+ * Every parser in this module enforces the same four limits
+ * ({@link QueryLimitOptions}) and drops `__proto__`, `constructor` and
+ * `prototype`, on both the string and the `URLSearchParams` entry points.
+ * Exceeding a limit throws {@link HTTPQueryLimitError}, which carries a 414
+ * status code.
  */
-export * from "./http.query.js";
+export * from "./queryTypes/index.js";
+export * from "./queryParse/index.js";
+export * from "./queryRequest/index.js";
+export * from "./querySerialize/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/httpQuery/index.js

@@ -1,7 +1,16 @@
 /**
  * @zudojs/http/httpQuery
  *
- * HTTP query string parsing and utilities.
+ * HTTP query string parsing, request accessors, and serialization.
+ *
+ * Every parser in this module enforces the same four limits
+ * ({@link QueryLimitOptions}) and drops `__proto__`, `constructor` and
+ * `prototype`, on both the string and the `URLSearchParams` entry points.
+ * Exceeding a limit throws {@link HTTPQueryLimitError}, which carries a 414
+ * status code.
  */
-export * from "./http.query.js";
+export * from "./queryTypes/index.js";
+export * from "./queryParse/index.js";
+export * from "./queryRequest/index.js";
+export * from "./querySerialize/index.js";
 //# sourceMappingURL=index.js.map

package/dist/httpQuery/queryParse/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @zudojs/http/httpQuery/queryParse
+ *
+ * The query-string tokenizer and the two parsers built on it: a nested,
+ * bracket-path parser and a flat one. Both enforce the same limits.
+ */
+export { decodeQueryComponent, stripQueryPrefix, tokenizeQuery, tokenizeSearchParams, } from "./queryParse.tokenizer.js";
+export { normalizeQueryValue, parseQuery, parseQueryKey, } from "./queryParse.nested.js";
+export { parseQueryString } from "./queryParse.flat.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpQuery/queryParse/index.js

@@ -0,0 +1,10 @@
+/**
+ * @zudojs/http/httpQuery/queryParse
+ *
+ * The query-string tokenizer and the two parsers built on it: a nested,
+ * bracket-path parser and a flat one. Both enforce the same limits.
+ */
+export { decodeQueryComponent, stripQueryPrefix, tokenizeQuery, tokenizeSearchParams, } from "./queryParse.tokenizer.js";
+export { normalizeQueryValue, parseQuery, parseQueryKey, } from "./queryParse.nested.js";
+export { parseQueryString } from "./queryParse.flat.js";
+//# sourceMappingURL=index.js.map

package/dist/httpQuery/queryParse/queryParse.flat.d.ts

@@ -0,0 +1,13 @@
+import type { QueryStringParseOptions } from "../queryTypes/index.js";
+/**
+ * Parses a query string into a flat record of decoded values.
+ *
+ * Unlike {@link parseQuery} this applies no bracket-path nesting and no value
+ * coercion: every value is the decoded string, and a repeated name yields an
+ * array. Both functions share one tokenizer and one set of limits.
+ *
+ * The record has a `null` prototype and `__proto__` / `constructor` /
+ * `prototype` are dropped, so no parameter name can reach a prototype chain.
+ */
+export declare function parseQueryString(input: string | undefined | null, options?: QueryStringParseOptions): Record<string, string | string[]>;
+//# sourceMappingURL=queryParse.flat.d.ts.map

package/dist/httpQuery/queryParse/queryParse.flat.js

@@ -0,0 +1,44 @@
+import { createQueryContainer, isForbiddenQueryKey, ownValue, resolveLimits, } from "../queryTypes/index.js";
+import { stripQueryPrefix, tokenizeQuery } from "./queryParse.tokenizer.js";
+/**
+ * Parses a query string into a flat record of decoded values.
+ *
+ * Unlike {@link parseQuery} this applies no bracket-path nesting and no value
+ * coercion: every value is the decoded string, and a repeated name yields an
+ * array. Both functions share one tokenizer and one set of limits.
+ *
+ * The record has a `null` prototype and `__proto__` / `constructor` /
+ * `prototype` are dropped, so no parameter name can reach a prototype chain.
+ */
+export function parseQueryString(input, options = {}) {
+    const result = createQueryContainer();
+    if (input === undefined || input === null || input === "") {
+        return result;
+    }
+    const value = stripQueryPrefix(input);
+    if (value.length === 0) {
+        return result;
+    }
+    const allowEmptyKeys = options.allowEmptyKeys ?? true;
+    const entries = tokenizeQuery(value, resolveLimits(options), true, options.decodePlusAsSpace !== false, false);
+    for (const [key, item] of entries) {
+        if (!allowEmptyKeys && key.length === 0) {
+            continue;
+        }
+        if (isForbiddenQueryKey(key)) {
+            continue;
+        }
+        const existing = ownValue(result, key);
+        if (existing === undefined) {
+            result[key] = item;
+            continue;
+        }
+        if (Array.isArray(existing)) {
+            existing.push(item);
+            continue;
+        }
+        result[key] = [existing, item];
+    }
+    return result;
+}
+//# sourceMappingURL=queryParse.flat.js.map

package/dist/httpQuery/queryParse/queryParse.nested.d.ts

@@ -0,0 +1,25 @@
+import type { QueryObject, QueryParseOptions, QueryPrimitive } from "../queryTypes/index.js";
+/**
+ * Parses a query string into a nested object.
+ *
+ * The returned objects have a `null` prototype: a parameter named
+ * `__proto__` can never reach `Object.prototype`, and a lookup of an
+ * unrelated key can never return an inherited member.
+ */
+export declare function parseQuery(query: string | URLSearchParams | undefined, options?: QueryParseOptions): QueryObject;
+/**
+ * Splits a bracket/dot path such as `a[b][c]` into its segments.
+ *
+ * A path containing `__proto__`, `constructor` or `prototype` yields an empty
+ * array, which callers treat as "drop this parameter entirely".
+ */
+export declare function parseQueryKey(key: string): string[];
+/**
+ * Coerces the well-known literals and numbers that round-trip exactly.
+ *
+ * A numeric literal is only converted when `String(Number(value)) === value`,
+ * so a 20-digit identifier stays the string it arrived as instead of being
+ * silently rewritten to a different number.
+ */
+export declare function normalizeQueryValue(value: string): QueryPrimitive;
+//# sourceMappingURL=queryParse.nested.d.ts.map

package/dist/httpQuery/queryParse/queryParse.nested.js

@@ -0,0 +1,112 @@
+import { createQueryContainer, DEFAULT_QUERY_MAX_DEPTH, HTTPQueryLimitError, isForbiddenQueryKey, isQueryObject, ownValue, resolveLimits, } from "../queryTypes/index.js";
+import { stripQueryPrefix, tokenizeQuery, tokenizeSearchParams, } from "./queryParse.tokenizer.js";
+/**
+ * Parses a query string into a nested object.
+ *
+ * The returned objects have a `null` prototype: a parameter named
+ * `__proto__` can never reach `Object.prototype`, and a lookup of an
+ * unrelated key can never return an inherited member.
+ */
+export function parseQuery(query, options = {}) {
+    if (query === undefined) {
+        return createQueryContainer();
+    }
+    const limits = resolveLimits(options);
+    const maxDepth = options.maxDepth ?? DEFAULT_QUERY_MAX_DEPTH;
+    const commaSeparated = options.commaSeparated === true;
+    const entries = query instanceof URLSearchParams
+        ? tokenizeSearchParams(query, limits, commaSeparated)
+        : tokenizeQuery(stripQueryPrefix(query), limits, options.decode !== false, options.plusAsSpace !== false, commaSeparated);
+    const result = createQueryContainer();
+    for (const [key, value] of entries) {
+        appendQueryValue(result, parseQueryKey(key), value, maxDepth);
+    }
+    return result;
+}
+/**
+ * Splits a bracket/dot path such as `a[b][c]` into its segments.
+ *
+ * A path containing `__proto__`, `constructor` or `prototype` yields an empty
+ * array, which callers treat as "drop this parameter entirely".
+ */
+export function parseQueryKey(key) {
+    if (!key) {
+        return [""];
+    }
+    const normalized = key.replace(/\]/g, "");
+    const segments = normalized.split(/[.[\]]+/).filter((part) => part.length > 0);
+    if (segments.some(isForbiddenQueryKey)) {
+        return [];
+    }
+    return segments;
+}
+/**
+ * Writes one value into the nested result object.
+ *
+ * Iterative rather than recursive so a deeply nested key cannot overflow the
+ * stack, depth-capped so it cannot allocate without bound, and every level is
+ * a null-prototype container read through `hasOwnProperty`.
+ */
+function appendQueryValue(target, path, value, maxDepth) {
+    if (path.length === 0) {
+        return;
+    }
+    if (path.length > maxDepth) {
+        throw new HTTPQueryLimitError("Query parameter nesting exceeds the maximum allowed depth.");
+    }
+    let current = target;
+    for (let index = 0; index < path.length - 1; index += 1) {
+        const segment = path[index];
+        if (segment === undefined) {
+            continue;
+        }
+        const existing = ownValue(current, segment);
+        if (isQueryObject(existing)) {
+            current = existing;
+            continue;
+        }
+        const next = createQueryContainer();
+        current[segment] = next;
+        current = next;
+    }
+    const leaf = path[path.length - 1];
+    if (leaf === undefined) {
+        return;
+    }
+    const existing = ownValue(current, leaf);
+    if (existing === undefined) {
+        current[leaf] = normalizeQueryValue(value);
+        return;
+    }
+    if (Array.isArray(existing)) {
+        existing.push(normalizeQueryValue(value));
+        return;
+    }
+    current[leaf] = [existing, normalizeQueryValue(value)];
+}
+/**
+ * Coerces the well-known literals and numbers that round-trip exactly.
+ *
+ * A numeric literal is only converted when `String(Number(value)) === value`,
+ * so a 20-digit identifier stays the string it arrived as instead of being
+ * silently rewritten to a different number.
+ */
+export function normalizeQueryValue(value) {
+    if (value === "null") {
+        return null;
+    }
+    if (value === "true") {
+        return true;
+    }
+    if (value === "false") {
+        return false;
+    }
+    if (/^-?(?:0|[1-9]\d*)(?:\.\d+)?$/.test(value)) {
+        const number = Number(value);
+        if (Number.isFinite(number) && String(number) === value) {
+            return number;
+        }
+    }
+    return value;
+}
+//# sourceMappingURL=queryParse.nested.js.map

package/dist/httpQuery/queryParse/queryParse.tokenizer.d.ts

@@ -0,0 +1,37 @@
+import type { QueryLimits } from "../queryTypes/index.js";
+/**
+ * Percent-decodes a query component.
+ *
+ * A malformed sequence such as `%ZZ` makes `decodeURIComponent` throw a
+ * `URIError`. Any client can send one, so the raw component is returned
+ * instead of propagating an unhandled error onto the request path. The raw
+ * bytes are never interpolated into an error message.
+ */
+export declare function decodeQueryComponent(value: string, decode?: boolean, plusAsSpace?: boolean): string;
+export declare function stripQueryPrefix(input: string): string;
+/**
+ * Splits a raw query string into decoded `[name, value]` pairs, enforcing
+ * every configured limit as it goes.
+ *
+ * This is the single tokenizer for the module: {@link parseQuery} and
+ * {@link parseQueryString} are both built on it — including their
+ * `URLSearchParams` entry points — so the limits and the decoding rules
+ * cannot drift apart.
+ *
+ * `maxKeys` counts *emitted* pairs, not `&`-separated segments. Counting
+ * segments let `?a=1,2,3,...` expand past the cap under `commaSeparated`,
+ * because the split happened after the check: a single parameter could yield
+ * thousands of entries with `maxKeys` set to 1.
+ */
+export declare function tokenizeQuery(query: string, limits: QueryLimits, decode: boolean, plusAsSpace: boolean, commaSeparated: boolean): Array<readonly [string, string]>;
+/**
+ * Tokenizes a `URLSearchParams` through the same path as a raw string.
+ *
+ * `toString()` re-encodes, and the tokenizer decodes again, so the round-trip
+ * is lossless. Routing it through the tokenizer is what makes `maxTotalLength`
+ * and `commaSeparated` apply here at all: the previous bespoke loop checked
+ * only the per-key and per-value caps, so `parseQuery(new URLSearchParams(…))`
+ * silently ignored two of the four documented limits and the comma option.
+ */
+export declare function tokenizeSearchParams(params: URLSearchParams, limits: QueryLimits, commaSeparated: boolean): Array<readonly [string, string]>;
+//# sourceMappingURL=queryParse.tokenizer.d.ts.map

package/dist/httpQuery/queryParse/queryParse.tokenizer.js

@@ -0,0 +1,95 @@
+import { HTTPQueryLimitError } from "../queryTypes/index.js";
+/**
+ * Percent-decodes a query component.
+ *
+ * A malformed sequence such as `%ZZ` makes `decodeURIComponent` throw a
+ * `URIError`. Any client can send one, so the raw component is returned
+ * instead of propagating an unhandled error onto the request path. The raw
+ * bytes are never interpolated into an error message.
+ */
+export function decodeQueryComponent(value, decode = true, plusAsSpace = true) {
+    const input = plusAsSpace ? value.replace(/\+/g, " ") : value;
+    if (!decode) {
+        return input;
+    }
+    try {
+        return decodeURIComponent(input);
+    }
+    catch {
+        return input;
+    }
+}
+export function stripQueryPrefix(input) {
+    let value = input;
+    if (value.startsWith("?")) {
+        value = value.slice(1);
+    }
+    const hashIndex = value.indexOf("#");
+    if (hashIndex !== -1) {
+        value = value.slice(0, hashIndex);
+    }
+    return value;
+}
+/**
+ * Splits a raw query string into decoded `[name, value]` pairs, enforcing
+ * every configured limit as it goes.
+ *
+ * This is the single tokenizer for the module: {@link parseQuery} and
+ * {@link parseQueryString} are both built on it — including their
+ * `URLSearchParams` entry points — so the limits and the decoding rules
+ * cannot drift apart.
+ *
+ * `maxKeys` counts *emitted* pairs, not `&`-separated segments. Counting
+ * segments let `?a=1,2,3,...` expand past the cap under `commaSeparated`,
+ * because the split happened after the check: a single parameter could yield
+ * thousands of entries with `maxKeys` set to 1.
+ */
+export function tokenizeQuery(query, limits, decode, plusAsSpace, commaSeparated) {
+    if (query.length > limits.maxTotalLength) {
+        throw new HTTPQueryLimitError("Query string exceeds the maximum allowed length.");
+    }
+    const entries = [];
+    const push = (key, value) => {
+        if (entries.length >= limits.maxKeys) {
+            throw new HTTPQueryLimitError("Query string contains too many parameters.");
+        }
+        entries.push([key, value]);
+    };
+    for (const part of query.split("&")) {
+        if (part === "") {
+            continue;
+        }
+        const separator = part.indexOf("=");
+        const rawKey = separator === -1 ? part : part.slice(0, separator);
+        const rawValue = separator === -1 ? "" : part.slice(separator + 1);
+        const key = decodeQueryComponent(rawKey, decode, plusAsSpace);
+        if (key.length > limits.maxKeyLength) {
+            throw new HTTPQueryLimitError("Query parameter name exceeds the maximum allowed length.");
+        }
+        const value = decodeQueryComponent(rawValue, decode, plusAsSpace);
+        if (value.length > limits.maxValueLength) {
+            throw new HTTPQueryLimitError("Query parameter value exceeds the maximum allowed length.");
+        }
+        if (commaSeparated && value.includes(",")) {
+            for (const item of value.split(",")) {
+                push(key, item);
+            }
+            continue;
+        }
+        push(key, value);
+    }
+    return entries;
+}
+/**
+ * Tokenizes a `URLSearchParams` through the same path as a raw string.
+ *
+ * `toString()` re-encodes, and the tokenizer decodes again, so the round-trip
+ * is lossless. Routing it through the tokenizer is what makes `maxTotalLength`
+ * and `commaSeparated` apply here at all: the previous bespoke loop checked
+ * only the per-key and per-value caps, so `parseQuery(new URLSearchParams(…))`
+ * silently ignored two of the four documented limits and the comma option.
+ */
+export function tokenizeSearchParams(params, limits, commaSeparated) {
+    return tokenizeQuery(params.toString(), limits, true, true, commaSeparated);
+}
+//# sourceMappingURL=queryParse.tokenizer.js.map

package/dist/httpQuery/queryRequest/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @zudojs/http/httpQuery/queryRequest
+ *
+ * Accessors that read the query component of an {@link HTTPRequest}. Every
+ * accessor here answers about the same parsed object, so middleware and a
+ * handler asking the same question get the same answer.
+ */
+export { getQuery, getQueryString, getQueryStrings, getQueryValue, getSearchParams, hasQuery, querySize, } from "./query.request.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpQuery/queryRequest/index.js

@@ -0,0 +1,9 @@
+/**
+ * @zudojs/http/httpQuery/queryRequest
+ *
+ * Accessors that read the query component of an {@link HTTPRequest}. Every
+ * accessor here answers about the same parsed object, so middleware and a
+ * handler asking the same question get the same answer.
+ */
+export { getQuery, getQueryString, getQueryStrings, getQueryValue, getSearchParams, hasQuery, querySize, } from "./query.request.js";
+//# sourceMappingURL=index.js.map

package/dist/httpQuery/queryRequest/query.request.d.ts

@@ -0,0 +1,43 @@
+import type { HTTPRequest } from "../../httpTypes/http.types.js";
+import type { QueryObject, QueryParseOptions, QueryValue } from "../queryTypes/index.js";
+export declare function getQuery(request: HTTPRequest, options?: QueryParseOptions): QueryObject;
+export declare function getQueryValue(request: HTTPRequest, key: string): QueryValue | undefined;
+/**
+ * Returns a single parameter as a string.
+ *
+ * A parameter that appeared more than once, or as a bracket path, has no
+ * single string form and yields `undefined`; use {@link getQueryStrings} for
+ * those. A literal `?a=null` yields `"null"` — the text the client sent.
+ * This used to return `null` while declaring `string | undefined`, so a
+ * caller doing `value.length` on a non-`undefined` result crashed.
+ */
+export declare function getQueryString(request: HTTPRequest, key: string): string | undefined;
+/**
+ * Returns every value a parameter carries, as strings.
+ *
+ * The parsed shape is attacker-chosen: `?a[b]=1&a=2` puts a null-prototype
+ * object inside the array for `a`, and `String()` on such an object throws
+ * `TypeError: Cannot convert object to primitive value`. Stringifying through
+ * {@link queryValueToString} keeps this total for every reachable input.
+ */
+export declare function getQueryStrings(request: HTTPRequest, key: string): string[];
+/**
+ * Returns the raw search parameters of a request-target.
+ *
+ * This is the undecoded, unnested view. It applies none of the parser's
+ * limits and drops no key, so prefer {@link getQuery} for anything that
+ * reaches application code.
+ */
+export declare function getSearchParams(request: HTTPRequest): URLSearchParams;
+/**
+ * Reports whether a parameter is present in the parsed query.
+ *
+ * Answers about the same object {@link getQuery} returns, not about the raw
+ * search params. The two used to disagree: `hasQuery(req, "a")` was `false`
+ * for `?a[b]=1` (which `getQuery` exposes as `a`), and
+ * `hasQuery(req, "__proto__")` was `true` for a key the parser drops.
+ */
+export declare function hasQuery(request: HTTPRequest, key: string): boolean;
+/** Number of distinct parameter names in the parsed query. */
+export declare function querySize(request: HTTPRequest): number;
+//# sourceMappingURL=query.request.d.ts.map

package/dist/httpQuery/queryRequest/query.request.js

@@ -0,0 +1,96 @@
+import { createQueryContainer, ownValue, queryValueToString, } from "../queryTypes/index.js";
+import { parseQuery } from "../queryParse/index.js";
+/**
+ * Extracts the query component of a request-target.
+ *
+ * The fragment is stripped: a proxy or a client that leaves `#…` on the
+ * request line must not turn it into a parameter.
+ */
+function queryComponent(url) {
+    if (!url) {
+        return undefined;
+    }
+    const queryIndex = url.indexOf("?");
+    if (queryIndex === -1) {
+        return undefined;
+    }
+    const hashIndex = url.indexOf("#", queryIndex + 1);
+    return url.slice(queryIndex + 1, hashIndex === -1 ? undefined : hashIndex);
+}
+export function getQuery(request, options = {}) {
+    const query = queryComponent(request.url);
+    if (query === undefined) {
+        return createQueryContainer();
+    }
+    return parseQuery(query, options);
+}
+export function getQueryValue(request, key) {
+    return ownValue(getQuery(request), key);
+}
+/**
+ * Returns a single parameter as a string.
+ *
+ * A parameter that appeared more than once, or as a bracket path, has no
+ * single string form and yields `undefined`; use {@link getQueryStrings} for
+ * those. A literal `?a=null` yields `"null"` — the text the client sent.
+ * This used to return `null` while declaring `string | undefined`, so a
+ * caller doing `value.length` on a non-`undefined` result crashed.
+ */
+export function getQueryString(request, key) {
+    const value = getQueryValue(request, key);
+    if (value === undefined || Array.isArray(value)) {
+        return undefined;
+    }
+    if (typeof value === "object" && value !== null) {
+        return undefined;
+    }
+    return queryValueToString(value);
+}
+/**
+ * Returns every value a parameter carries, as strings.
+ *
+ * The parsed shape is attacker-chosen: `?a[b]=1&a=2` puts a null-prototype
+ * object inside the array for `a`, and `String()` on such an object throws
+ * `TypeError: Cannot convert object to primitive value`. Stringifying through
+ * {@link queryValueToString} keeps this total for every reachable input.
+ */
+export function getQueryStrings(request, key) {
+    const value = getQueryValue(request, key);
+    if (value === undefined) {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        return value.map(queryValueToString);
+    }
+    return [queryValueToString(value)];
+}
+/**
+ * Returns the raw search parameters of a request-target.
+ *
+ * This is the undecoded, unnested view. It applies none of the parser's
+ * limits and drops no key, so prefer {@link getQuery} for anything that
+ * reaches application code.
+ */
+export function getSearchParams(request) {
+    const query = queryComponent(request.url ?? "");
+    if (query === undefined) {
+        return new URLSearchParams();
+    }
+    return new URLSearchParams(query);
+}
+/**
+ * Reports whether a parameter is present in the parsed query.
+ *
+ * Answers about the same object {@link getQuery} returns, not about the raw
+ * search params. The two used to disagree: `hasQuery(req, "a")` was `false`
+ * for `?a[b]=1` (which `getQuery` exposes as `a`), and
+ * `hasQuery(req, "__proto__")` was `true` for a key the parser drops.
+ */
+export function hasQuery(request, key) {
+    return getQueryValue(request, key) !== undefined;
+}
+/** Number of distinct parameter names in the parsed query. */
+export function querySize(request) {
+    return Object.keys(getQuery(request)).length;
+}
+//# sourceMappingURL=query.request.js.map

package/dist/httpQuery/querySerialize/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @zudojs/http/httpQuery/querySerialize
+ *
+ * Serializing an object back into a query string, and the clone/merge
+ * helpers that operate on an already-parsed query. All three are bounded the
+ * same way the parser is.
+ */
+export { buildQueryString, stringifyQuery, } from "./querySerialize.core.js";
+export { cloneQuery, mergeQuery } from "./query.util.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpQuery/querySerialize/index.js

@@ -0,0 +1,10 @@
+/**
+ * @zudojs/http/httpQuery/querySerialize
+ *
+ * Serializing an object back into a query string, and the clone/merge
+ * helpers that operate on an already-parsed query. All three are bounded the
+ * same way the parser is.
+ */
+export { buildQueryString, stringifyQuery, } from "./querySerialize.core.js";
+export { cloneQuery, mergeQuery } from "./query.util.js";
+//# sourceMappingURL=index.js.map