@zudojs/http 0.1.0 → 1.1.0

package/dist/httpQuery/http.query.js

@@ -0,0 +1,484 @@
+import { HttpError } from "@zudojs/errors";
+/* -------------------------------------------------------------------------- */
+/* Limits                                                                     */
+/* -------------------------------------------------------------------------- */
+export const DEFAULT_QUERY_MAX_KEYS = 1000;
+export const DEFAULT_QUERY_MAX_KEY_LENGTH = 4096;
+export const DEFAULT_QUERY_MAX_VALUE_LENGTH = 16384;
+export const DEFAULT_QUERY_MAX_TOTAL_LENGTH = 1024 * 1024;
+export const DEFAULT_QUERY_MAX_DEPTH = 10;
+/**
+ * Thrown when a query string exceeds one of the parser's limits.
+ *
+ * Carries `statusCode: 414` so an error handler can answer with
+ * `414 URI Too Long` rather than treating the rejection as an internal fault.
+ */
+export class HTTPQueryLimitError extends HttpError {
+    constructor(message) {
+        super(message, {
+            statusCode: 414,
+            code: "HTTP_QUERY_LIMIT",
+            expose: true,
+            isOperational: true,
+        });
+        this.name = "HTTPQueryLimitError";
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Prototype Safety                                                           */
+/* -------------------------------------------------------------------------- */
+/**
+ * Key names that would mutate a prototype chain if assigned to an object.
+ *
+ * `__proto__` is the direct pollution vector. `constructor` and `prototype`
+ * are blocked as defence in depth so no future container type re-opens the
+ * hole.
+ */
+const FORBIDDEN_QUERY_KEYS = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+export function isForbiddenQueryKey(key) {
+    return FORBIDDEN_QUERY_KEYS.has(key);
+}
+function createQueryContainer() {
+    return Object.create(null);
+}
+function ownValue(target, key) {
+    return Object.prototype.hasOwnProperty.call(target, key)
+        ? target[key]
+        : undefined;
+}
+function resolveLimits(options) {
+    return {
+        maxKeys: options.maxKeys ?? DEFAULT_QUERY_MAX_KEYS,
+        maxKeyLength: options.maxKeyLength ?? DEFAULT_QUERY_MAX_KEY_LENGTH,
+        maxValueLength: options.maxValueLength ?? DEFAULT_QUERY_MAX_VALUE_LENGTH,
+        maxTotalLength: options.maxTotalLength ?? DEFAULT_QUERY_MAX_TOTAL_LENGTH,
+    };
+}
+/**
+ * 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;
+    }
+}
+/**
+ * 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: both {@link parseQuery} and
+ * {@link parseQueryString} are built on it, so the limits and the decoding
+ * rules cannot drift apart.
+ */
+function tokenizeQuery(query, limits, decode, plusAsSpace, commaSeparated) {
+    if (query.length > limits.maxTotalLength) {
+        throw new HTTPQueryLimitError("Query string exceeds the maximum allowed length.");
+    }
+    const entries = [];
+    let count = 0;
+    for (const part of query.split("&")) {
+        if (part === "") {
+            continue;
+        }
+        count += 1;
+        if (count > limits.maxKeys) {
+            throw new HTTPQueryLimitError("Query string contains too many parameters.");
+        }
+        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(",")) {
+                entries.push([key, item]);
+            }
+            continue;
+        }
+        entries.push([key, value]);
+    }
+    return entries;
+}
+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;
+}
+/* -------------------------------------------------------------------------- */
+/* Query Parser                                                               */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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 entries = query instanceof URLSearchParams
+        ? limitSearchParams(query, limits)
+        : tokenizeQuery(stripQueryPrefix(query), limits, options.decode !== false, options.plusAsSpace !== false, options.commaSeparated === true);
+    const result = createQueryContainer();
+    for (const [key, value] of entries) {
+        appendQueryValue(result, parseQueryKey(key), value, maxDepth);
+    }
+    return result;
+}
+function limitSearchParams(params, limits) {
+    const entries = [];
+    let count = 0;
+    for (const [key, value] of params.entries()) {
+        count += 1;
+        if (count > limits.maxKeys) {
+            throw new HTTPQueryLimitError("Query string contains too many parameters.");
+        }
+        if (key.length > limits.maxKeyLength) {
+            throw new HTTPQueryLimitError("Query parameter name exceeds the maximum allowed length.");
+        }
+        if (value.length > limits.maxValueLength) {
+            throw new HTTPQueryLimitError("Query parameter value exceeds the maximum allowed length.");
+        }
+        entries.push([key, value]);
+    }
+    return entries;
+}
+/**
+ * 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.
+ */
+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;
+}
+/* -------------------------------------------------------------------------- */
+/* Request Query Helpers                                                      */
+/* -------------------------------------------------------------------------- */
+export function getQuery(request, options = {}) {
+    const url = request.url;
+    if (!url) {
+        return createQueryContainer();
+    }
+    const queryIndex = url.indexOf("?");
+    if (queryIndex === -1) {
+        return createQueryContainer();
+    }
+    const hashIndex = url.indexOf("#", queryIndex + 1);
+    const query = url.slice(queryIndex + 1, hashIndex === -1 ? undefined : hashIndex);
+    return parseQuery(query, options);
+}
+export function getQueryValue(request, key) {
+    return ownValue(getQuery(request), key);
+}
+export function getQueryString(request, key) {
+    const value = getQueryValue(request, key);
+    if (value === undefined || Array.isArray(value)) {
+        return undefined;
+    }
+    if (value === null) {
+        return null;
+    }
+    return String(value);
+}
+export function getQueryStrings(request, key) {
+    const value = getQueryValue(request, key);
+    if (value === undefined) {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        return value.map(String);
+    }
+    return [String(value)];
+}
+/* -------------------------------------------------------------------------- */
+/* Search Params                                                               */
+/* -------------------------------------------------------------------------- */
+export function getSearchParams(request) {
+    const url = request.url ?? "";
+    const queryIndex = url.indexOf("?");
+    if (queryIndex === -1) {
+        return new URLSearchParams();
+    }
+    const hashIndex = url.indexOf("#", queryIndex + 1);
+    const query = url.slice(queryIndex + 1, hashIndex === -1 ? undefined : hashIndex);
+    return new URLSearchParams(query);
+}
+/* -------------------------------------------------------------------------- */
+/* Query String Serialization                                                 */
+/* -------------------------------------------------------------------------- */
+export function stringifyQuery(query) {
+    const params = new URLSearchParams();
+    appendObjectToSearchParams(params, query);
+    return params.toString();
+}
+export function buildQueryString(query) {
+    const value = stringifyQuery(query);
+    return value ? `?${value}` : "";
+}
+/* -------------------------------------------------------------------------- */
+/* Query Value Access                                                         */
+/* -------------------------------------------------------------------------- */
+export function hasQuery(request, key) {
+    return getSearchParams(request).has(key);
+}
+export function querySize(request) {
+    let size = 0;
+    for (const _ of getSearchParams(request)) {
+        size += 1;
+    }
+    return size;
+}
+/* -------------------------------------------------------------------------- */
+/* Query Key Parsing                                                          */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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;
+}
+/* -------------------------------------------------------------------------- */
+/* Nested Query Values                                                        */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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)];
+}
+/* -------------------------------------------------------------------------- */
+/* Query Value Normalization                                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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;
+}
+function isQueryObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/* -------------------------------------------------------------------------- */
+/* Serialization                                                              */
+/* -------------------------------------------------------------------------- */
+function appendObjectToSearchParams(params, object, prefix) {
+    for (const [key, value] of Object.entries(object)) {
+        const path = prefix ? `${prefix}[${key}]` : key;
+        if (value === undefined) {
+            continue;
+        }
+        if (value === null) {
+            params.append(path, "null");
+            continue;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item === undefined) {
+                    continue;
+                }
+                if (isPlainObject(item)) {
+                    appendObjectToSearchParams(params, item, path);
+                }
+                else {
+                    params.append(path, serializeQueryPrimitive(item));
+                }
+            }
+            continue;
+        }
+        if (isPlainObject(value)) {
+            appendObjectToSearchParams(params, value, path);
+            continue;
+        }
+        params.append(path, serializeQueryPrimitive(value));
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Primitive Serialization                                                    */
+/* -------------------------------------------------------------------------- */
+function serializeQueryPrimitive(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (value === undefined) {
+        return "";
+    }
+    if (typeof value === "boolean") {
+        return value ? "true" : "false";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "bigint") {
+        return String(value);
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    return String(value);
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/* -------------------------------------------------------------------------- */
+/* Query Utilities                                                            */
+/* -------------------------------------------------------------------------- */
+export function cloneQuery(query) {
+    return JSON.parse(JSON.stringify(query));
+}
+export function mergeQuery(...queries) {
+    const result = createQueryContainer();
+    for (const query of queries) {
+        mergeQueryObject(result, query);
+    }
+    return result;
+}
+function mergeQueryObject(target, source) {
+    for (const [key, value] of Object.entries(source)) {
+        if (isForbiddenQueryKey(key)) {
+            continue;
+        }
+        const existing = ownValue(target, key);
+        if (isQueryObject(existing) && isQueryObject(value)) {
+            mergeQueryObject(existing, value);
+            continue;
+        }
+        target[key] = value;
+    }
+}
+//# sourceMappingURL=http.query.js.map

package/dist/httpQuery/index.d.ts

@@ -4,5 +4,4 @@
  * HTTP query string parsing and utilities.
  */
 export * from "./http.query.js";
-export { type QueryStringPrimitive, type QueryStringValue, type QueryStringParseOptions, parseQueryString, } from "./httpQuery.string.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/httpQuery/index.js

@@ -4,5 +4,4 @@
  * HTTP query string parsing and utilities.
  */
 export * from "./http.query.js";
-export { parseQueryString, } from "./httpQuery.string.js";
 //# sourceMappingURL=index.js.map

package/dist/httpRange/http.range.d.ts

@@ -0,0 +1,53 @@
+/**
+ * HTTP byte-range utilities.
+ *
+ * Implements parsing and resolution of HTTP Range headers, primarily for
+ * byte-range responses such as files and static assets.
+ */
+export interface ByteRange {
+    readonly start: number | undefined;
+    readonly end: number | undefined;
+}
+export interface ResolvedByteRange {
+    readonly start: number;
+    readonly end: number;
+    readonly length: number;
+}
+export interface RangeResult {
+    readonly unit: string;
+    readonly ranges: readonly ResolvedByteRange[];
+}
+export interface UnsatisfiableRange {
+    readonly unit: string;
+    readonly ranges: readonly ByteRange[];
+}
+export declare const DEFAULT_RANGE_UNIT = "bytes";
+export declare const MAX_RANGE_COUNT = 128;
+export declare function parseRangeHeader(value: string | undefined | null): {
+    readonly unit: string;
+    readonly ranges: readonly ByteRange[];
+} | undefined;
+export declare function parseByteRange(value: string): ByteRange | undefined;
+export declare function resolveByteRange(range: ByteRange, size: number): ResolvedByteRange | undefined;
+export declare function resolveRanges(ranges: readonly ByteRange[], size: number): readonly ResolvedByteRange[];
+export declare function resolveRangeHeader(header: string | undefined | null, size: number): RangeResult | undefined;
+export declare function isByteRangeUnit(unit: string): boolean;
+export declare function isRangeSatisfiable(range: ByteRange, size: number): boolean;
+export declare function hasSatisfiableRanges(ranges: readonly ByteRange[], size: number): boolean;
+export declare function isUnsatisfiableRangeHeader(header: string | undefined | null, size: number): boolean;
+export declare function normalizeRanges(ranges: readonly ResolvedByteRange[]): readonly ResolvedByteRange[];
+export declare function mergeRanges(ranges: readonly ResolvedByteRange[]): readonly ResolvedByteRange[];
+export declare function formatRangeHeader(ranges: readonly ByteRange[], unit?: string): string;
+export declare function formatByteRange(range: ByteRange): string;
+export declare function formatContentRange(range: ResolvedByteRange, size: number, unit?: string): string;
+export declare function formatUnsatisfiedContentRange(size: number, unit?: string): string;
+export declare function createRangeResponse(header: string | undefined | null, size: number): {
+    readonly status: 200 | 206 | 416;
+    readonly ranges: readonly ResolvedByteRange[];
+    readonly contentRange?: string;
+};
+export declare function isFullResourceRange(range: ResolvedByteRange, size: number): boolean;
+export declare function getRangeLength(range: ResolvedByteRange): number;
+export declare function sliceRange<T>(value: ArrayLike<T>, range: ResolvedByteRange): T[];
+export declare function coalesceRanges(ranges: readonly ResolvedByteRange[], maxRanges?: number): readonly ResolvedByteRange[];
+//# sourceMappingURL=http.range.d.ts.map