@sdxc/http 0.0.0-pre.1

package/dist/cache/precondition.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `If-Match` preconditions for writes: the check that a client is updating the
+ * version of a resource it actually read. The outcome is a `Result`, so turning a
+ * failed precondition into a `412` stays the caller's decision.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+/**
+ * The current validator a write is checked against.
+ */
+export interface PreconditionOptions {
+    /**
+     * The resource's current entity tag, as `etag()` produces it. A weak tag never
+     * satisfies an `If-Match`, because equivalent content is not the same version.
+     */
+    etag: string;
+}
+/**
+ * The client's `If-Match` did not name the version the resource is currently at,
+ * which means the write would overwrite a change the client never saw.
+ *
+ * Delivered inside a `Failure` for the caller to inspect and answer with a `412`.
+ *
+ * @example
+ * if (isFailure(result)) return preconditionFailed({ error: result.error.message });
+ */
+export declare class PreconditionFailedError extends Error {
+    /** The validator the resource is actually at, for logs and diagnostics. */
+    readonly etag: string;
+    /**
+     * @param etag - The resource's current entity tag.
+     */
+    constructor(etag: string);
+}
+/**
+ * Checks a write request's `If-Match` against the resource's current validator.
+ *
+ * An absent `If-Match` or a `*` always matches; every other value is compared
+ * strongly, so a weak tag never satisfies it, binding writes to a version read.
+ *
+ * @param request - The incoming write request.
+ * @param options - The resource's current entity tag.
+ * @returns The satisfied validator, or a `PreconditionFailedError` to answer with a `412`.
+ *
+ * @example
+ * let checked = precondition(request, { etag: current });
+ * if (isFailure(checked)) return preconditionFailed("<h1>Precondition Failed</h1>");
+ * @example
+ * precondition(request, { etag: '"abc"' }); // success('"abc"') when If-Match is absent
+ */
+export declare function precondition(request: Request, options: PreconditionOptions): Result<string, PreconditionFailedError>;

package/dist/cache/precondition.js

@@ -0,0 +1,53 @@
+/**
+ * `If-Match` preconditions for writes: the check that a client is updating the
+ * version of a resource it actually read. The outcome is a `Result`, so turning a
+ * failed precondition into a `412` stays the caller's decision.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, success } from "@sdxc/result";
+import { IfMatch } from "remix/headers";
+/**
+ * The client's `If-Match` did not name the version the resource is currently at,
+ * which means the write would overwrite a change the client never saw.
+ *
+ * Delivered inside a `Failure` for the caller to inspect and answer with a `412`.
+ *
+ * @example
+ * if (isFailure(result)) return preconditionFailed({ error: result.error.message });
+ */
+export class PreconditionFailedError extends Error {
+    /** The validator the resource is actually at, for logs and diagnostics. */
+    etag;
+    /**
+     * @param etag - The resource's current entity tag.
+     */
+    constructor(etag) {
+        super(`Precondition failed: resource is at ${etag}`);
+        this.name = "PreconditionFailedError";
+        this.etag = etag;
+    }
+}
+/**
+ * Checks a write request's `If-Match` against the resource's current validator.
+ *
+ * An absent `If-Match` or a `*` always matches; every other value is compared
+ * strongly, so a weak tag never satisfies it, binding writes to a version read.
+ *
+ * @param request - The incoming write request.
+ * @param options - The resource's current entity tag.
+ * @returns The satisfied validator, or a `PreconditionFailedError` to answer with a `412`.
+ *
+ * @example
+ * let checked = precondition(request, { etag: current });
+ * if (isFailure(checked)) return preconditionFailed("<h1>Precondition Failed</h1>");
+ * @example
+ * precondition(request, { etag: '"abc"' }); // success('"abc"') when If-Match is absent
+ */
+export function precondition(request, options) {
+    let ifMatch = IfMatch.from(request.headers.get("If-Match"));
+    if (!ifMatch.matches(options.etag))
+        return failure(new PreconditionFailedError(options.etag));
+    return success(options.etag);
+}

package/dist/cache/vary.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Merging of `Vary` header names, so a response that negotiates on one dimension
+ * can add a second without discarding the first. Header names are the cache key,
+ * which is why this merges instead of replacing.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Adds request header names to a response's `Vary`, keeping whatever is
+ * there. Each header multiplies the cache variants stored for the URL, so
+ * varying on `Cookie` disables shared caching; prefer `Policies.private()`.
+ *
+ * @param headers - Response headers to merge into; mutated in place.
+ * @param names - Request header names the response depends on.
+ * @returns The same `Headers` object, for chaining.
+ *
+ * @example
+ * vary(headers, ["Accept-Language", "Cookie"]);
+ * @example
+ * let headers = new Headers({ Vary: "Accept-Encoding" });
+ * vary(headers, "Accept-Language").get("Vary"); // "accept-encoding, accept-language"
+ */
+export declare function vary(headers: Headers, names: string | string[]): Headers;

package/dist/cache/vary.js

@@ -0,0 +1,33 @@
+/**
+ * Merging of `Vary` header names, so a response that negotiates on one dimension
+ * can add a second without discarding the first. Header names are the cache key,
+ * which is why this merges instead of replacing.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { Vary } from "remix/headers";
+/**
+ * Adds request header names to a response's `Vary`, keeping whatever is
+ * there. Each header multiplies the cache variants stored for the URL, so
+ * varying on `Cookie` disables shared caching; prefer `Policies.private()`.
+ *
+ * @param headers - Response headers to merge into; mutated in place.
+ * @param names - Request header names the response depends on.
+ * @returns The same `Headers` object, for chaining.
+ *
+ * @example
+ * vary(headers, ["Accept-Language", "Cookie"]);
+ * @example
+ * let headers = new Headers({ Vary: "Accept-Encoding" });
+ * vary(headers, "Accept-Language").get("Vary"); // "accept-encoding, accept-language"
+ */
+export function vary(headers, names) {
+    let value = Vary.from(headers.get("Vary"));
+    for (let name of typeof names === "string" ? [names] : names)
+        value.add(name);
+    if (value.size === 0)
+        return headers;
+    headers.set("Vary", value.toString());
+    return headers;
+}

package/dist/content-type.d.ts

@@ -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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare const NDJson: "application/x-ndjson";