@sdxc/http 0.0.0-pre.1

package/dist/content-type.js

@@ -0,0 +1,312 @@
+/**
+ * MIME type constants for HTTP `Content-Type` header values.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Used for simple text responses without any formatting.
+ * @example
+ * headers.set("Content-Type", Text);
+ * @example
+ * return new Response("Hello", { headers: { "Content-Type": Text } });
+ */
+export const Text = "text/plain";
+/**
+ * Used for web pages and HTML document responses.
+ * @example
+ * headers.set("Content-Type", HTML);
+ * @example
+ * return new Response("<h1>Hello</h1>", { headers: { "Content-Type": HTML } });
+ */
+export const HTML = "text/html";
+/**
+ * Used for stylesheet responses.
+ * @example
+ * headers.set("Content-Type", CSS);
+ * @example
+ * return new Response("body { color: red; }", { headers: { "Content-Type": CSS } });
+ */
+export const CSS = "text/css";
+/**
+ * Used for JavaScript file responses.
+ * @example
+ * headers.set("Content-Type", JavaScript);
+ * @example
+ * return new Response("console.log('hi')", { headers: { "Content-Type": JavaScript } });
+ */
+export const JavaScript = "text/javascript";
+/**
+ * Used for comma-separated values data exports.
+ * @example
+ * headers.set("Content-Type", CSV);
+ * @example
+ * return new Response("name,age\nJohn,30", { headers: { "Content-Type": CSV } });
+ */
+export const CSV = "text/csv";
+/**
+ * Used for XML documents intended for human readability.
+ * @example
+ * headers.set("Content-Type", XML);
+ * @example
+ * return new Response("<root><item/></root>", { headers: { "Content-Type": XML } });
+ */
+export const XML = "text/xml";
+/**
+ * Used for Markdown-formatted text responses.
+ * @example
+ * headers.set("Content-Type", Markdown);
+ * @example
+ * return new Response("# Hello", { headers: { "Content-Type": Markdown } });
+ */
+export const Markdown = "text/markdown";
+/**
+ * Used for API responses and requests with structured data.
+ * Named `Json` (not `JSON`) to avoid shadowing the global `JSON` object.
+ * @example
+ * headers.set("Content-Type", Json);
+ * @example
+ * if (contentType === Json) { parseJson(body); }
+ */
+export const Json = "application/json";
+/**
+ * Used for newline-delimited JSON streaming responses.
+ * @example
+ * headers.set("Content-Type", JSONLines);
+ * @example
+ * return new Response('{"a":1}\n{"b":2}', { headers: { "Content-Type": JSONLines } });
+ */
+export const JSONLines = "application/jsonl";
+/**
+ * PDF content type.
+ * Used for PDF document responses.
+ * @example
+ * headers.set("Content-Type", PDF);
+ * @example
+ * return new Response(pdfBuffer, { headers: { "Content-Type": PDF } });
+ */
+export const PDF = "application/pdf";
+/**
+ * ZIP archive content type.
+ * Used for compressed archive file responses.
+ * @example
+ * headers.set("Content-Type", ZIP);
+ * @example
+ * return new Response(zipBuffer, { headers: { "Content-Type": ZIP } });
+ */
+export const ZIP = "application/zip";
+/**
+ * GZip compressed content type.
+ * Used for gzip-compressed file responses.
+ * @example
+ * headers.set("Content-Type", GZip);
+ * @example
+ * return new Response(gzipBuffer, { headers: { "Content-Type": GZip } });
+ */
+export const GZip = "application/gzip";
+/**
+ * Multipart form data content type.
+ * Used for form submissions with file uploads.
+ * @example
+ * if (contentType.startsWith(FormData)) { parseFormData(body); }
+ * @example
+ * headers.set("Content-Type", FormData);
+ */
+export const FormData = "multipart/form-data";
+/**
+ * URL-encoded form content type.
+ * Used for simple form submissions without files.
+ * @example
+ * headers.set("Content-Type", FormURLEncoded);
+ * @example
+ * if (contentType === FormURLEncoded) { parseURLEncoded(body); }
+ */
+export const FormURLEncoded = "application/x-www-form-urlencoded";
+/**
+ * Binary octet stream content type.
+ * Used for arbitrary binary data when type is unknown.
+ * @example
+ * headers.set("Content-Type", OctetStream);
+ * @example
+ * return new Response(binaryData, { headers: { "Content-Type": OctetStream } });
+ */
+export const OctetStream = "application/octet-stream";
+/**
+ * Used for XML data in API responses and machine processing.
+ * @example
+ * headers.set("Content-Type", ApplicationXML);
+ * @example
+ * return new Response(xmlData, { headers: { "Content-Type": ApplicationXML } });
+ */
+export const ApplicationXML = "application/xml";
+/**
+ * PNG image content type.
+ * Used for lossless raster image responses.
+ * @example
+ * headers.set("Content-Type", PNG);
+ * @example
+ * return new Response(pngBuffer, { headers: { "Content-Type": PNG } });
+ */
+export const PNG = "image/png";
+/**
+ * JPEG image content type.
+ * Used for lossy compressed photo responses.
+ * @example
+ * headers.set("Content-Type", JPEG);
+ * @example
+ * return new Response(jpegBuffer, { headers: { "Content-Type": JPEG } });
+ */
+export const JPEG = "image/jpeg";
+/**
+ * GIF image content type.
+ * Used for animated or simple graphics responses.
+ * @example
+ * headers.set("Content-Type", GIF);
+ * @example
+ * return new Response(gifBuffer, { headers: { "Content-Type": GIF } });
+ */
+export const GIF = "image/gif";
+/**
+ * WebP image content type.
+ * Used for modern lossy/lossless image responses.
+ * @example
+ * headers.set("Content-Type", WebP);
+ * @example
+ * return new Response(webpBuffer, { headers: { "Content-Type": WebP } });
+ */
+export const WebP = "image/webp";
+/**
+ * SVG image content type.
+ * Used for vector graphics responses.
+ * @example
+ * headers.set("Content-Type", SVG);
+ * @example
+ * return new Response(svgString, { headers: { "Content-Type": SVG } });
+ */
+export const SVG = "image/svg+xml";
+/**
+ * ICO image content type.
+ * Used for favicon and icon file responses.
+ * @example
+ * headers.set("Content-Type", ICO);
+ * @example
+ * return new Response(icoBuffer, { headers: { "Content-Type": ICO } });
+ */
+export const ICO = "image/x-icon";
+/**
+ * AVIF image content type.
+ * Used for highly compressed modern image responses.
+ * @example
+ * headers.set("Content-Type", AVIF);
+ * @example
+ * return new Response(avifBuffer, { headers: { "Content-Type": AVIF } });
+ */
+export const AVIF = "image/avif";
+/**
+ * MP3 audio content type.
+ * Used for MPEG audio file responses.
+ * @example
+ * headers.set("Content-Type", MP3);
+ * @example
+ * return new Response(mp3Buffer, { headers: { "Content-Type": MP3 } });
+ */
+export const MP3 = "audio/mpeg";
+/**
+ * WAV audio content type.
+ * Used for uncompressed audio file responses.
+ * @example
+ * headers.set("Content-Type", WAV);
+ * @example
+ * return new Response(wavBuffer, { headers: { "Content-Type": WAV } });
+ */
+export const WAV = "audio/wav";
+/**
+ * OGG audio content type.
+ * Used for Ogg Vorbis audio file responses.
+ * @example
+ * headers.set("Content-Type", OGG);
+ * @example
+ * return new Response(oggBuffer, { headers: { "Content-Type": OGG } });
+ */
+export const OGG = "audio/ogg";
+/**
+ * WebM audio content type.
+ * Used for WebM audio-only file responses.
+ * @example
+ * headers.set("Content-Type", WebMAudio);
+ * @example
+ * return new Response(webmAudioBuffer, { headers: { "Content-Type": WebMAudio } });
+ */
+export const WebMAudio = "audio/webm";
+/**
+ * MP4 video content type.
+ * Used for MPEG-4 video file responses.
+ * @example
+ * headers.set("Content-Type", MP4);
+ * @example
+ * return new Response(mp4Buffer, { headers: { "Content-Type": MP4 } });
+ */
+export const MP4 = "video/mp4";
+/**
+ * WebM video content type.
+ * Used for WebM video file responses.
+ * @example
+ * headers.set("Content-Type", WebMVideo);
+ * @example
+ * return new Response(webmVideoBuffer, { headers: { "Content-Type": WebMVideo } });
+ */
+export const WebMVideo = "video/webm";
+/**
+ * WOFF font content type.
+ * Used for Web Open Font Format file responses.
+ * @example
+ * headers.set("Content-Type", WOFF);
+ * @example
+ * return new Response(woffBuffer, { headers: { "Content-Type": WOFF } });
+ */
+export const WOFF = "font/woff";
+/**
+ * WOFF2 font content type.
+ * Used for Web Open Font Format 2.0 file responses.
+ * @example
+ * headers.set("Content-Type", WOFF2);
+ * @example
+ * return new Response(woff2Buffer, { headers: { "Content-Type": WOFF2 } });
+ */
+export const WOFF2 = "font/woff2";
+/**
+ * TrueType font content type.
+ * Used for TTF font file responses.
+ * @example
+ * headers.set("Content-Type", TTF);
+ * @example
+ * return new Response(ttfBuffer, { headers: { "Content-Type": TTF } });
+ */
+export const TTF = "font/ttf";
+/**
+ * OpenType font content type.
+ * Used for OTF font file responses.
+ * @example
+ * headers.set("Content-Type", OTF);
+ * @example
+ * return new Response(otfBuffer, { headers: { "Content-Type": OTF } });
+ */
+export const OTF = "font/otf";
+/**
+ * Server-Sent Events content type.
+ * Used for streaming event responses to clients.
+ * @example
+ * headers.set("Content-Type", EventStream);
+ * @example
+ * return new Response(stream, { headers: { "Content-Type": EventStream } });
+ */
+export const EventStream = "text/event-stream";
+/**
+ * Newline-delimited JSON content type.
+ * Used for streaming JSON objects one per line.
+ * @example
+ * headers.set("Content-Type", NDJson);
+ * @example
+ * return new Response(ndjsonStream, { headers: { "Content-Type": NDJson } });
+ */
+export const NDJson = "application/x-ndjson";

package/dist/middleware/head-requests.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Router middleware that answers `HEAD` requests with the `GET` representation's
+ * status and headers and no body, as RFC 9110 §9.3.2 requires. The fetch router
+ * matches a route's method by strict equality, so without this a `HEAD` probe
+ * falls through to the default handler and a monitor reads a healthy page as a
+ * 404.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Middleware } from "remix/router";
+/**
+ * Creates a middleware that dispatches `HEAD` requests as `GET`, strips the
+ * response body, and keeps `HEAD` on the same chain as `GET` so auth, rate
+ * limiting, and other guards behave identically; install it first in the chain.
+ *
+ * @returns The middleware to place at the head of the router's global chain.
+ */
+export declare function headRequests(): Middleware;

package/dist/middleware/head-requests.js

@@ -0,0 +1,30 @@
+/**
+ * Router middleware that answers `HEAD` requests with the `GET` representation's
+ * status and headers and no body, as RFC 9110 §9.3.2 requires. The fetch router
+ * matches a route's method by strict equality, so without this a `HEAD` probe
+ * falls through to the default handler and a monitor reads a healthy page as a
+ * 404.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Creates a middleware that dispatches `HEAD` requests as `GET`, strips the
+ * response body, and keeps `HEAD` on the same chain as `GET` so auth, rate
+ * limiting, and other guards behave identically; install it first in the chain.
+ *
+ * @returns The middleware to place at the head of the router's global chain.
+ */
+export function headRequests() {
+    return async function headRequestsMiddleware(context, next) {
+        if (context.method !== "HEAD")
+            return next();
+        context.method = "GET";
+        let response = await next();
+        return new Response(null, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        });
+    };
+}

package/dist/negotiate.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Accept-header content negotiation: parse quality-ordered client
+ * preferences and pick the response representation that matches.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Holds an Accept header's types ordered by quality so callers can query
+ * preference without re-parsing on every check.
+ */
+export declare class AcceptList {
+    private types;
+    constructor(header: string);
+    /**
+     * Matches shorthand types ("json", "html", "xml", "text", "markdown") as
+     * well as full MIME types, and treats a wildcard Accept header as
+     * matching any type.
+     * @param type - The content type or shorthand to check
+     * @returns True if the type is accepted
+     * @example
+     * if (accepts(request).includes("json")) { ... }
+     * @example
+     * if (accepts(request).includes("text/html")) { ... }
+     */
+    includes(type: string): boolean;
+    /**
+     * Accepted types sorted by preference, highest quality first.
+     * @returns Array of MIME types sorted by preference
+     * @example
+     * let types = accepts(request).all(); // ["text/html", "application/json", ...]
+     */
+    all(): string[];
+    /**
+     * Walks the client's accepted types in preference order and returns the
+     * first one present in `types`; a wildcard Accept header matches the
+     * first of `types` rather than every candidate.
+     * @param types - Available content types to choose from
+     * @returns The preferred type or null
+     * @example
+     * let preferred = accepts(request).preferred("application/json", "text/html");
+     */
+    preferred(...types: string[]): string | null;
+    /**
+     * Converts a MIME type to its shorthand form.
+     * @param mimeType - The full MIME type
+     * @returns The shorthand type or null if not recognized
+     */
+    toShortType(mimeType: string): string | null;
+    private parseAcceptHeader;
+    private resolveType;
+}
+/**
+ * Reads the Accept header, defaulting to accepting every type when the
+ * client sends none.
+ * @param request - The incoming request
+ * @returns An AcceptList instance for querying accepted types
+ * @example
+ * if (accepts(request).includes("json")) return json(data);
+ * @example
+ * let types = accepts(request).all();
+ */
+export declare function accepts(request: Request): AcceptList;
+/**
+ * Calls the handler for the client's preferred type, trying candidates in
+ * quality order; answers 406 Not Acceptable when nothing matches and no
+ * `default` handler is given.
+ * @param request - The incoming request
+ * @param handlers - Object mapping content types to response handlers
+ * @returns The response from the matching handler
+ * @example
+ * return respond(request, {
+ *   json: () => json({ data }),
+ *   html: () => html(renderPage(data)),
+ * });
+ * @example
+ * return respond(request, {
+ *   json: () => json({ data }),
+ *   default: () => json({ data }), // fallback
+ * });
+ */
+export declare function respond(request: Request, handlers: respond.Handlers): Response;
+export declare namespace respond {
+    type Handlers = {
+        json?: () => Response;
+        html?: () => Response;
+        xml?: () => Response;
+        text?: () => Response;
+        markdown?: () => Response;
+        css?: () => Response;
+        javascript?: () => Response;
+        csv?: () => Response;
+        pdf?: () => Response;
+        default?: () => Response;
+        [key: string]: (() => Response) | undefined;
+    };
+}

package/dist/negotiate.js

@@ -0,0 +1,156 @@
+/**
+ * Accept-header content negotiation: parse quality-ordered client
+ * preferences and pick the response representation that matches.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+const shortToMime = new Map([
+    ["json", ["application/json"]],
+    ["html", ["text/html"]],
+    ["xml", ["application/xml", "text/xml"]],
+    ["text", ["text/plain"]],
+    ["markdown", ["text/markdown"]],
+    ["css", ["text/css"]],
+    ["javascript", ["text/javascript", "application/javascript"]],
+    ["csv", ["text/csv"]],
+    ["pdf", ["application/pdf"]],
+]);
+const mimeToShort = new Map([
+    ["application/json", "json"],
+    ["text/html", "html"],
+    ["application/xml", "xml"],
+    ["text/xml", "xml"],
+    ["text/plain", "text"],
+    ["text/markdown", "markdown"],
+    ["text/css", "css"],
+    ["text/javascript", "javascript"],
+    ["application/javascript", "javascript"],
+    ["text/csv", "csv"],
+    ["application/pdf", "pdf"],
+]);
+/**
+ * Holds an Accept header's types ordered by quality so callers can query
+ * preference without re-parsing on every check.
+ */
+export class AcceptList {
+    types;
+    constructor(header) {
+        this.types = this.parseAcceptHeader(header);
+    }
+    /**
+     * Matches shorthand types ("json", "html", "xml", "text", "markdown") as
+     * well as full MIME types, and treats a wildcard Accept header as
+     * matching any type.
+     * @param type - The content type or shorthand to check
+     * @returns True if the type is accepted
+     * @example
+     * if (accepts(request).includes("json")) { ... }
+     * @example
+     * if (accepts(request).includes("text/html")) { ... }
+     */
+    includes(type) {
+        let mimeTypes = this.resolveType(type);
+        return this.types.some((t) => mimeTypes.includes(t) || t === "*/*");
+    }
+    /**
+     * Accepted types sorted by preference, highest quality first.
+     * @returns Array of MIME types sorted by preference
+     * @example
+     * let types = accepts(request).all(); // ["text/html", "application/json", ...]
+     */
+    all() {
+        return this.types;
+    }
+    /**
+     * Walks the client's accepted types in preference order and returns the
+     * first one present in `types`; a wildcard Accept header matches the
+     * first of `types` rather than every candidate.
+     * @param types - Available content types to choose from
+     * @returns The preferred type or null
+     * @example
+     * let preferred = accepts(request).preferred("application/json", "text/html");
+     */
+    preferred(...types) {
+        for (let accepted of this.types) {
+            if (types.includes(accepted))
+                return accepted;
+            if (accepted === "*/*")
+                return types[0] ?? null;
+        }
+        return null;
+    }
+    /**
+     * Converts a MIME type to its shorthand form.
+     * @param mimeType - The full MIME type
+     * @returns The shorthand type or null if not recognized
+     */
+    toShortType(mimeType) {
+        return mimeToShort.get(mimeType) ?? null;
+    }
+    parseAcceptHeader(header) {
+        return header
+            .split(",")
+            .map((part) => {
+            let [type = "", ...params] = part.trim().split(";");
+            let q = 1;
+            for (let param of params) {
+                let [key, value = ""] = param.trim().split("=");
+                if (key === "q")
+                    q = Number.parseFloat(value) || 0;
+            }
+            return { type: type.trim(), q };
+        })
+            .sort((a, b) => b.q - a.q)
+            .map(({ type }) => type);
+    }
+    resolveType(type) {
+        return shortToMime.get(type) ?? [type];
+    }
+}
+/**
+ * Reads the Accept header, defaulting to accepting every type when the
+ * client sends none.
+ * @param request - The incoming request
+ * @returns An AcceptList instance for querying accepted types
+ * @example
+ * if (accepts(request).includes("json")) return json(data);
+ * @example
+ * let types = accepts(request).all();
+ */
+export function accepts(request) {
+    let header = request.headers.get("Accept") ?? "*/*";
+    return new AcceptList(header);
+}
+/**
+ * Calls the handler for the client's preferred type, trying candidates in
+ * quality order; answers 406 Not Acceptable when nothing matches and no
+ * `default` handler is given.
+ * @param request - The incoming request
+ * @param handlers - Object mapping content types to response handlers
+ * @returns The response from the matching handler
+ * @example
+ * return respond(request, {
+ *   json: () => json({ data }),
+ *   html: () => html(renderPage(data)),
+ * });
+ * @example
+ * return respond(request, {
+ *   json: () => json({ data }),
+ *   default: () => json({ data }), // fallback
+ * });
+ */
+export function respond(request, handlers) {
+    let accept = accepts(request);
+    for (let type of accept.all()) {
+        let shortType = accept.toShortType(type);
+        if (shortType && handlers[shortType])
+            return handlers[shortType]();
+    }
+    if (handlers.default)
+        return handlers.default();
+    return new Response("Not Acceptable", {
+        status: 406,
+        statusText: "Not Acceptable",
+    });
+}