htmx-router 2.2.6 → 2.2.8

package/dist/etag.d.ts

@@ -0,0 +1,218 @@
+type ResourceOptions = {
+    etag?: string;
+    lastModified?: Date;
+    revalidate?: number;
+    public?: boolean;
+};
+/**
+ * @deprecated use {@link AssertResourceFresh} instead
+ */
+export declare function AssertETagStale(request: Request, headers: Headers, etag: string, options?: {
+    revalidate?: number;
+    public?: boolean;
+}): void;
+/**
+ * Asserts the freshness of a resource using ETag or Last-Modified headers to manage conditional HTTP requests.
+ * This function acts as a guard: it evaluates the request against the provided resource state and
+ * throws a Response to intercept the execution flow if the cache state requires it.
+ *
+ * @param {Request}  request               - The incoming HTTP request object
+ * @param {Headers}  headers               - The response headers object to modify
+ * @param {Object}   options               - Configuration for freshness validation
+ * @param {string}  [options.etag]         - The current ETag value for the resource (do not quote)
+ * @param {Date}    [options.lastModified] - The last modified timestamp of the resource
+ * @param {number}  [options.revalidate]   - Client must revalidate their cache at this interval in seconds
+ * @param {boolean} [options.public]       - Cache visibility scope:
+ *   - true: Can be cached by any cache (e.g., Cloudflare)
+ *   - false: Can only be cached by private caches (e.g., browser)
+ *
+ * @throws {Response} `304 Not Modified`
+ *   For `GET` or `HEAD` requests when the client's cache is still valid (stale state).
+ *
+ * @throws {Response} `412 Precondition Failed`
+ *   - When the client's conditional headers do not match the current resource state.
+ *   - For non-idempotent methods (`POST`, `PUT`, `PATCH`, `DELETE`) when the resource state is stale.
+ *
+ * @returns {void} If the resource is fresh or the request is valid, allows execution to continue.
+ *
+ * @example
+ * Basic usage with ETag
+ * ```ts
+ * AssertResourceFresh(request, headers, { etag: "v1.2.3" });
+ * ```
+ *
+ * @example
+ * Usage with Last-Modified and caching options
+ * ```ts
+ * AssertResourceFresh(request, headers, {
+ *   lastModified: new Date("2026-01-01T00:00:00Z"),
+ *   revalidate: 3600,
+ *   public: true
+ * });
+ * ```
+ *
+ * @example
+ * Usage in a handler function
+ * ```ts
+ * async function handleRequest(request, headers) {
+ *   const data = await fetchData();
+ *   const etag = GenerateEtag(data);
+ *
+ *   // Will throw 304 if the client's cache is still valid
+ *   // Or throw 412 if preconditions fail
+ *   AssertResourceFresh(request, headers, { etag });
+ *
+ *   // This code only runs if the client needs updated content
+ *   return new Response(JSON.stringify(data), { headers });
+ * }
+ * ```
+ *
+ * @see {@link GetResourceState} For the detailed breakdown of the underlying state logic
+ */
+export declare function AssertResourceFresh(request: Request, headers: Headers, options: {
+    etag?: string;
+    lastModified?: Date;
+    revalidate?: number;
+    public?: boolean;
+}): void;
+/**
+ * A predicate function that checks if the resource is "fresh" (i.e., it has been
+ * updated or changed since the client's last cached version).
+ *
+ * Use this to determine if you need to proceed with generating a full response
+ * or if the client can continue using their current cached version.
+ *
+ * @param {Request}         request - The incoming HTTP request object
+ * @param {Headers}         headers - The response headers object
+ * @param {ResourceOptions} options - The current metadata of the resource (ETag, Last-Modified, etc.)
+ *
+ * @returns {boolean} `true` if the resource is fresh (has changed and needs to be sent),
+ *   `false` if the resource is stale (client's cache is still valid) or a precondition has failed.
+ *
+ * @example
+ * Check if we need to send new data
+ * ```ts
+ * if (IsResourceFresh(request, headers, { etag: currentEtag })) {
+ *   return new Response(JSON.stringify(data), { headers });
+ * } else {
+ *   // The resource is stale (client has it) or preconditions failed
+ *   // Handle accordingly (e.g., return 304 or 412)
+ * }
+ * ```
+ *
+ * @example
+ * Using it with more complex options
+ * ```ts
+ * const options = {
+ *   etag: "v2",
+ *   revalidate: 300,
+ *   public: true
+ * };
+ *
+ * if (IsResourceFresh(request, headers, options)) {
+ *   // Generate full response...
+ * }
+ * ```
+ *
+ * @see {@link GetResourceState} For the detailed breakdown of the underlying state logic.
+ */
+export declare function IsResourceFresh(request: Request, headers: Headers, options: ResourceOptions): boolean;
+/**
+ * Evaluates the freshness and precondition status of a resource by comparing
+ * the incoming request's conditional headers against the current resource metadata.
+ *
+ * This function performs the core logic to determine if a client's cached version
+ * is still valid, needs updating, or if a conditional request (like `If-Match`)
+ * has failed.
+ *
+ * @param {Request}  request               - The incoming HTTP request object containing conditional headers
+ * @param {Headers}  headers               - The response headers object to be used during evaluation
+ * @param {Object}   options               - The current metadata of the resource being requested
+ * @param {string}  [options.etag]         - The current ETag value of the resource
+ * @param {Date}    [options.lastModified] - The last modified timestamp of the resource
+ * @param {number}  [options.revalidate]   - The revalidation interval in seconds
+ * @param {boolean} [options.public]       - Cache visibility scope:
+ *   - true: Can be cached by any cache (e.g., Cloudflare)
+ *   - false: Can only be cached by private caches (e.g., browser)
+ *
+ * @returns {'FRESH' | 'STALE' | 'PRECONDITION FAILED'} The calculated state:
+ *   - `'FRESH'`: The client's cache is outdated; new content should be sent.
+ *   - `'STALE'`: The client's cache is valid; no update is required.
+ *   - `'PRECONDITION FAILED'`: The client's conditional headers (e.g., `If-Match`) did not match the current resource state.
+ *
+ * @example
+ * Manual state checking
+ * ```ts
+ * const state = GetResourceState(request, responseHeaders, { etag: "v1.2.3" });
+ *
+ * if (state === 'FRESH') {
+ *   console.log("Client needs new data");
+ * } else if (state === 'PRECONDITION FAILED') {
+ *   console.log("Client's precondition check failed");
+ * }
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag      | ETag - MDN Web Docs}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match       | If-None-Match - MDN Web Docs}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match            | If-Match - MDN Web Docs}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Modified-Since   | If-Modified-Since - MDN Web Docs}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Unmodified-Since | If-Unmodified-Since - MDN Web Docs}
+ */
+export declare function GetResourceState(request: Request, headers: Headers, options: {
+    etag?: string;
+    lastModified?: Date;
+    revalidate?: number;
+    public?: boolean;
+}): 'FRESH' | 'STALE' | 'PRECONDITION FAILED';
+/**
+ * Generates a deterministic ETag (Entity Tag) for various data types.
+ *
+ * The generation strategy varies based on the input type to balance performance and collision resistance:
+ * - **Dates & Numbers**: Uses a lightweight base-36 encoding for speed.
+ * - **Arrays**: Joins elements with `:` and returns the string if shorter than the hash would; otherwise, hashes the result.
+ * - **Strings, Uint8Arrays, & ArrayBuffers**: Produces a SHA-256 hex digest.
+ *
+ * @param {string | Uint8Array | ArrayBuffer | Date | number | number[]} data - The content to represent.
+ *
+ * @returns {Promise<string>} A unique string identifier:
+ *   - A base-36 string (for `Date` and `number`).
+ *   - A colon-separated string (for short `number[]`).
+ *   - A hex-encoded SHA-256 hash (for strings, buffers, or long arrays).
+ *
+ * @example
+ * Generating an ETag for a Date (Base-36)
+ * ```ts
+ * const dateEtag = await GenerateETag(new Date());
+ * ```
+ *
+ * @example
+ * Generating an ETag for a number (Base-36)
+ * ```ts
+ * const numEtag = await GenerateETag(12345);
+ * ```
+ *
+ * @example
+ * Generating an ETag for a large string (SHA-256 Hash)
+ * ```ts
+ * const content = "Large payload...";
+ * const stringEtag = await GenerateETag(content);
+ * ```
+ *
+ * @throws {Error} If the cryptographic operation fails.
+ */
+export declare function GenerateETag(data: string | Uint8Array | ArrayBuffer | Date | Number | Number[]): Promise<string>;
+/**
+ * Sets the `ETag` header on the provided `Headers` object.
+ *
+ * This utility ensures the ETag is compliant with HTTP standards and safe for transport by:
+ * 1. Trimming leading/trailing whitespace.
+ * 2. Applying URI encoding to safely handle special characters.
+ * 3. Wrapping the resulting value in double quotes as required by RFC standards.
+ *
+ * @param {Headers} headers - The response headers object to modify.
+ * @param {string} etag - The raw ETag value (e.g., a hash or a version string).
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag      | ETag - MDN Web Docs}
+ */
+export declare function SetETag(headers: Headers, etag: string): void;
+export {};

package/dist/etag.js

@@ -0,0 +1,339 @@
+import crypto from 'node:crypto';
+/**
+ * @deprecated use {@link AssertResourceFresh} instead
+ */
+export function AssertETagStale(request, headers, etag, options) {
+    return AssertResourceFresh(request, headers, { etag, ...options });
+}
+/**
+ * Asserts the freshness of a resource using ETag or Last-Modified headers to manage conditional HTTP requests.
+ * This function acts as a guard: it evaluates the request against the provided resource state and
+ * throws a Response to intercept the execution flow if the cache state requires it.
+ *
+ * @param {Request}  request               - The incoming HTTP request object
+ * @param {Headers}  headers               - The response headers object to modify
+ * @param {Object}   options               - Configuration for freshness validation
+ * @param {string}  [options.etag]         - The current ETag value for the resource (do not quote)
+ * @param {Date}    [options.lastModified] - The last modified timestamp of the resource
+ * @param {number}  [options.revalidate]   - Client must revalidate their cache at this interval in seconds
+ * @param {boolean} [options.public]       - Cache visibility scope:
+ *   - true: Can be cached by any cache (e.g., Cloudflare)
+ *   - false: Can only be cached by private caches (e.g., browser)
+ *
+ * @throws {Response} `304 Not Modified`
+ *   For `GET` or `HEAD` requests when the client's cache is still valid (stale state).
+ *
+ * @throws {Response} `412 Precondition Failed`
+ *   - When the client's conditional headers do not match the current resource state.
+ *   - For non-idempotent methods (`POST`, `PUT`, `PATCH`, `DELETE`) when the resource state is stale.
+ *
+ * @returns {void} If the resource is fresh or the request is valid, allows execution to continue.
+ *
+ * @example
+ * Basic usage with ETag
+ * ```ts
+ * AssertResourceFresh(request, headers, { etag: "v1.2.3" });
+ * ```
+ *
+ * @example
+ * Usage with Last-Modified and caching options
+ * ```ts
+ * AssertResourceFresh(request, headers, {
+ *   lastModified: new Date("2026-01-01T00:00:00Z"),
+ *   revalidate: 3600,
+ *   public: true
+ * });
+ * ```
+ *
+ * @example
+ * Usage in a handler function
+ * ```ts
+ * async function handleRequest(request, headers) {
+ *   const data = await fetchData();
+ *   const etag = GenerateEtag(data);
+ *
+ *   // Will throw 304 if the client's cache is still valid
+ *   // Or throw 412 if preconditions fail
+ *   AssertResourceFresh(request, headers, { etag });
+ *
+ *   // This code only runs if the client needs updated content
+ *   return new Response(JSON.stringify(data), { headers });
+ * }
+ * ```
+ *
+ * @see {@link GetResourceState} For the detailed breakdown of the underlying state logic
+ */
+export function AssertResourceFresh(request, headers, options) {
+    const state = GetResourceState(request, headers, options);
+    function PreconditionFailed() {
+        headers.set("X-Caught", "true");
+        throw new Response(null, { headers, status: 412, statusText: 'Precondition Failed' });
+    }
+    function Stale() {
+        headers.set("X-Caught", "true");
+        throw new Response(null, { headers, status: 304, statusText: 'Not Modified' });
+    }
+    if (request.method === 'GET' || request.method === 'HEAD') {
+        switch (state) {
+            case 'PRECONDITION FAILED': return PreconditionFailed();
+            case 'STALE': return Stale();
+            case 'FRESH': return; // continue with response generation
+        }
+    }
+    else {
+        switch (state) {
+            case 'PRECONDITION FAILED': return PreconditionFailed();
+            case 'STALE': return PreconditionFailed(); // always treat as pre-condition on post/patch/put/delete
+            case 'FRESH': return; // continue with response generation
+        }
+    }
+}
+/**
+ * A predicate function that checks if the resource is "fresh" (i.e., it has been
+ * updated or changed since the client's last cached version).
+ *
+ * Use this to determine if you need to proceed with generating a full response
+ * or if the client can continue using their current cached version.
+ *
+ * @param {Request}         request - The incoming HTTP request object
+ * @param {Headers}         headers - The response headers object
+ * @param {ResourceOptions} options - The current metadata of the resource (ETag, Last-Modified, etc.)
+ *
+ * @returns {boolean} `true` if the resource is fresh (has changed and needs to be sent),
+ *   `false` if the resource is stale (client's cache is still valid) or a precondition has failed.
+ *
+ * @example
+ * Check if we need to send new data
+ * ```ts
+ * if (IsResourceFresh(request, headers, { etag: currentEtag })) {
+ *   return new Response(JSON.stringify(data), { headers });
+ * } else {
+ *   // The resource is stale (client has it) or preconditions failed
+ *   // Handle accordingly (e.g., return 304 or 412)
+ * }
+ * ```
+ *
+ * @example
+ * Using it with more complex options
+ * ```ts
+ * const options = {
+ *   etag: "v2",
+ *   revalidate: 300,
+ *   public: true
+ * };
+ *
+ * if (IsResourceFresh(request, headers, options)) {
+ *   // Generate full response...
+ * }
+ * ```
+ *
+ * @see {@link GetResourceState} For the detailed breakdown of the underlying state logic.
+ */
+export function IsResourceFresh(request, headers, options) {
+    const state = GetResourceState(request, headers, options);
+    return state === 'FRESH';
+}
+/**
+ * Evaluates the freshness and precondition status of a resource by comparing
+ * the incoming request's conditional headers against the current resource metadata.
+ *
+ * This function performs the core logic to determine if a client's cached version
+ * is still valid, needs updating, or if a conditional request (like `If-Match`)
+ * has failed.
+ *
+ * @param {Request}  request               - The incoming HTTP request object containing conditional headers
+ * @param {Headers}  headers               - The response headers object to be used during evaluation
+ * @param {Object}   options               - The current metadata of the resource being requested
+ * @param {string}  [options.etag]         - The current ETag value of the resource
+ * @param {Date}    [options.lastModified] - The last modified timestamp of the resource
+ * @param {number}  [options.revalidate]   - The revalidation interval in seconds
+ * @param {boolean} [options.public]       - Cache visibility scope:
+ *   - true: Can be cached by any cache (e.g., Cloudflare)
+ *   - false: Can only be cached by private caches (e.g., browser)
+ *
+ * @returns {'FRESH' | 'STALE' | 'PRECONDITION FAILED'} The calculated state:
+ *   - `'FRESH'`: The client's cache is outdated; new content should be sent.
+ *   - `'STALE'`: The client's cache is valid; no update is required.
+ *   - `'PRECONDITION FAILED'`: The client's conditional headers (e.g., `If-Match`) did not match the current resource state.
+ *
+ * @example
+ * Manual state checking
+ * ```ts
+ * const state = GetResourceState(request, responseHeaders, { etag: "v1.2.3" });
+ *
+ * if (state === 'FRESH') {
+ *   console.log("Client needs new data");
+ * } else if (state === 'PRECONDITION FAILED') {
+ *   console.log("Client's precondition check failed");
+ * }
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag      | ETag - MDN Web Docs}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match       | If-None-Match - MDN Web Docs}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match            | If-Match - MDN Web Docs}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Modified-Since   | If-Modified-Since - MDN Web Docs}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Unmodified-Since | If-Unmodified-Since - MDN Web Docs}
+ */
+export function GetResourceState(request, headers, options) {
+    headers.delete("Cache-Control"); // clear any defaults
+    // only apply cache control if something was actually provided in the options
+    if (options.etag || options.lastModified || options.public !== undefined || options.revalidate !== undefined) {
+        // default to private, because it's the slightly less worse of the two potential foot guns
+        if (options.public)
+            headers.append("Cache-Control", "public");
+        else
+            headers.append("Cache-Control", "private");
+        if (options.revalidate !== undefined)
+            headers.append("Cache-Control", `max-age=${options.revalidate}`);
+    }
+    if (options.etag)
+        headers.append("Cache-Control", "must-revalidate");
+    if (options?.lastModified)
+        headers.append("Last-Modified", options.lastModified.toUTCString());
+    if (options.etag) {
+        SetETag(headers, options.etag);
+        const match = CheckETag(request, options.etag);
+        if (match) {
+            if (match.some === false)
+                return 'PRECONDITION FAILED';
+            //  match.some === true,  no-op still check dates
+            if (match.none === false)
+                return 'STALE';
+            //  match.none === true,  no-op still check dates
+        }
+    }
+    if (options?.lastModified) {
+        // HTTP dates only have second precision
+        function StripMs(time) {
+            return Math.floor(time / 1000) * 1000;
+        }
+        const actual = StripMs(options.lastModified.getTime());
+        if (isNaN(actual))
+            return 'FRESH';
+        const modified = request.headers.get('If-Modified-Since');
+        if (modified) {
+            const expected = StripMs(new Date(modified).getTime());
+            if (!isNaN(expected) && actual <= expected)
+                return 'STALE';
+        }
+        const unmodified = request.headers.get('If-Unmodified-Since');
+        if (unmodified) {
+            const expected = StripMs(new Date(unmodified).getTime());
+            if (!isNaN(expected) && actual > expected)
+                return 'PRECONDITION FAILED';
+        }
+    }
+    return 'FRESH';
+}
+/**
+ * Generates a deterministic ETag (Entity Tag) for various data types.
+ *
+ * The generation strategy varies based on the input type to balance performance and collision resistance:
+ * - **Dates & Numbers**: Uses a lightweight base-36 encoding for speed.
+ * - **Arrays**: Joins elements with `:` and returns the string if shorter than the hash would; otherwise, hashes the result.
+ * - **Strings, Uint8Arrays, & ArrayBuffers**: Produces a SHA-256 hex digest.
+ *
+ * @param {string | Uint8Array | ArrayBuffer | Date | number | number[]} data - The content to represent.
+ *
+ * @returns {Promise<string>} A unique string identifier:
+ *   - A base-36 string (for `Date` and `number`).
+ *   - A colon-separated string (for short `number[]`).
+ *   - A hex-encoded SHA-256 hash (for strings, buffers, or long arrays).
+ *
+ * @example
+ * Generating an ETag for a Date (Base-36)
+ * ```ts
+ * const dateEtag = await GenerateETag(new Date());
+ * ```
+ *
+ * @example
+ * Generating an ETag for a number (Base-36)
+ * ```ts
+ * const numEtag = await GenerateETag(12345);
+ * ```
+ *
+ * @example
+ * Generating an ETag for a large string (SHA-256 Hash)
+ * ```ts
+ * const content = "Large payload...";
+ * const stringEtag = await GenerateETag(content);
+ * ```
+ *
+ * @throws {Error} If the cryptographic operation fails.
+ */
+export async function GenerateETag(data) {
+    if (data instanceof Date)
+        return data.getTime().toString(36);
+    if (typeof data === 'number')
+        return data.toString(36);
+    if (Array.isArray(data)) {
+        data = data.join(':');
+        if (data.length < 64)
+            return data;
+    }
+    let view;
+    if (typeof data === 'string') {
+        view = new TextEncoder().encode(data).buffer;
+    }
+    else if (data instanceof Uint8Array) {
+        view = data.buffer;
+    }
+    else {
+        view = data;
+    }
+    const hash = await crypto.subtle.digest('SHA-256', view);
+    const chars = [];
+    for (const byte of new Uint8Array(hash))
+        chars.push(byte.toString(16).padStart(2, '0'));
+    return chars.join('');
+}
+/**
+ * Sets the `ETag` header on the provided `Headers` object.
+ *
+ * This utility ensures the ETag is compliant with HTTP standards and safe for transport by:
+ * 1. Trimming leading/trailing whitespace.
+ * 2. Applying URI encoding to safely handle special characters.
+ * 3. Wrapping the resulting value in double quotes as required by RFC standards.
+ *
+ * @param {Headers} headers - The response headers object to modify.
+ * @param {string} etag - The raw ETag value (e.g., a hash or a version string).
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag      | ETag - MDN Web Docs}
+ */
+export function SetETag(headers, etag) {
+    etag = encodeURIComponent(etag.trim()); // safely handle any special characters
+    headers.set("ETag", `"${etag}"`);
+}
+function GetETagRules(input) {
+    const target = input instanceof Request ? input.headers : input;
+    const some = target.get("if-match")?.trim();
+    const none = target.get("if-none-match")?.trim();
+    return { some, none };
+}
+function CheckETag(input, etag) {
+    const headers = input instanceof Request ? input.headers : input;
+    return CheckRules(GetETagRules(headers), etag);
+}
+function CheckRules(rules, etag) {
+    if (!rules)
+        return { some: undefined, none: undefined, valid: true };
+    const some = rules.some ? MatchRules(rules.some, etag) : undefined;
+    const none = rules.none ? !MatchRules(rules.none, etag) : undefined;
+    const vSome = some || some === undefined;
+    const vNone = none || none === undefined;
+    return { some, none, valid: vSome && vNone };
+}
+function MatchRules(header, etag) {
+    if (header === "*")
+        return true;
+    for (const term of header.split(/,\s*/)) {
+        let s = term.startsWith('W/') ? 'W/'.length : 0;
+        if (term.startsWith('"', s))
+            s++;
+        const e = term.endsWith('"') ? term.length - 1 : term.length;
+        const tag = term.slice(s, e);
+        if (etag === tag)
+            return true;
+    }
+    return false;
+}

package/dist/event-source.d.ts

@@ -34,7 +34,7 @@ export declare class EventSourceSet<JsxEnabled extends boolean = false> extends
      * Send update to all EventSources, auto closing failed dispatches
      * @returns number of successful sends
      */
-    dispatch(type: string, data: string): number;
+    dispatch(type: string, data: JsxEnabled extends true ? (JSX.Element | string) : string): number;
     /**
      * Cull all closed connections
      * @returns number of connections closed
@@ -60,7 +60,7 @@ export declare class EventSourceMap<T, JsxEnabled extends boolean = false> exten
      * Send update to all EventSources, auto closing failed dispatches
      * @returns number of successful sends
      */
-    dispatch(type: string, data: string): number;
+    dispatch(type: string, data: JsxEnabled extends true ? (JSX.Element | string) : string): number;
     /**
      * Cull all closed connections
      * @returns number of connections closed

package/dist/response.d.ts

@@ -1,3 +1,4 @@
+import * as etag from "./etag";
 import { ResponseInit } from "./util/types";
 export declare function text(text: BodyInit, init?: ResponseInit): Response;
 export declare function html(text: BodyInit, init?: ResponseInit): Response;
@@ -15,49 +16,6 @@ export declare function refresh(init?: ResponseInit & {
     clientOnly?: boolean;
 }): Response;
 /**
- * Handles Entity-Tag based conditional requests by setting cache headers and controlling execution flow.
- * Acts like an assertion that stops execution when the client's ETag matches the current ETag.
- *
- * @param {Request} request - The incoming HTTP request object
- * @param {Headers} headers - The output response headers object to modify
- * @param {string} etag - The current ETag value for the resource (do not quote)
- * @param {Object} [options] - Optional caching configuration
- * @param {number} [options.revalidate] - client must revalidate their etag at this interval in seconds
- * @param {boolean} [options.public] - cache visibility scope:
- *   - "public": Can be cached by any cache (i.e. Cloudflare)
- *   - "private": Can only be cached by private caches (i.e. browser)
- *
- * @throws {Response} `304 Not Modified` Response with the configured headers
- *   when the client's If-None-Match header matches the provided ETag
- *
- * @returns {void} if client's etag is stale, allows execution to continue to generate new result
- *
- * @example
- * // Basic usage - will return early if client has current version
- * GuardEntityTag(request, headers, "v1.2.3");
- *
- * @example
- * // With caching options
- * GuardEntityTag(request, headers, "v1.2.3", {
- *   revalidate: 3600,
- *   scope: "public"
- * });
- *
- * @example
- * // Usage in a handler function
- * function handleRequest(request, headers) {
- *   const currentEtag = generateEtag(data);
- *
- *   // Will throw 304 if client ETag is fresh
- *   GuardEntityTag(request, headers, currentEtag);
- *
- *   // This code only runs if client needs updated content
- *   return new Response(generateContent(), { headers });
- * }
- *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag | ETag - MDN Web Docs }
+ * @deprecated import from `htmx-router/etag` instead
  */
-export declare function AssertETagStale(request: Request, headers: Headers, etag: string, options?: {
-    revalidate?: number;
-    public?: boolean;
-}): void;
+export declare const AssertETagStale: typeof etag.AssertETagStale;

package/dist/response.js

@@ -1,3 +1,4 @@
+import * as etag from "./etag";
 export function text(text, init) {
     init = FillResponseInit(200, "Ok", init);
     const res = new Response(text, init);
@@ -55,83 +56,9 @@ export function refresh(init) {
     return res;
 }
 /**
- * Handles Entity-Tag based conditional requests by setting cache headers and controlling execution flow.
- * Acts like an assertion that stops execution when the client's ETag matches the current ETag.
- *
- * @param {Request} request - The incoming HTTP request object
- * @param {Headers} headers - The output response headers object to modify
- * @param {string} etag - The current ETag value for the resource (do not quote)
- * @param {Object} [options] - Optional caching configuration
- * @param {number} [options.revalidate] - client must revalidate their etag at this interval in seconds
- * @param {boolean} [options.public] - cache visibility scope:
- *   - "public": Can be cached by any cache (i.e. Cloudflare)
- *   - "private": Can only be cached by private caches (i.e. browser)
- *
- * @throws {Response} `304 Not Modified` Response with the configured headers
- *   when the client's If-None-Match header matches the provided ETag
- *
- * @returns {void} if client's etag is stale, allows execution to continue to generate new result
- *
- * @example
- * // Basic usage - will return early if client has current version
- * GuardEntityTag(request, headers, "v1.2.3");
- *
- * @example
- * // With caching options
- * GuardEntityTag(request, headers, "v1.2.3", {
- *   revalidate: 3600,
- *   scope: "public"
- * });
- *
- * @example
- * // Usage in a handler function
- * function handleRequest(request, headers) {
- *   const currentEtag = generateEtag(data);
- *
- *   // Will throw 304 if client ETag is fresh
- *   GuardEntityTag(request, headers, currentEtag);
- *
- *   // This code only runs if client needs updated content
- *   return new Response(generateContent(), { headers });
- * }
- *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag | ETag - MDN Web Docs }
+ * @deprecated import from `htmx-router/etag` instead
  */
-export function AssertETagStale(request, headers, etag, options) {
-    headers.delete("Cache-Control"); // clear any defaults
-    if (options) {
-        // default to private, because it's the slightly less worse of the two potential foot guns
-        if (options.public)
-            headers.append("Cache-Control", "public");
-        else
-            headers.append("Cache-Control", "private");
-        if (options.revalidate !== undefined)
-            headers.append("Cache-Control", `max-age=${options.revalidate}`);
-    }
-    headers.append("Cache-Control", "must-revalidate");
-    etag = encodeURIComponent(etag.trim()); // safely handle any special characters
-    headers.set("ETag", `"${etag}"`);
-    const rules = request.headers.get("if-none-match");
-    if (!rules || !MatchEtags(rules.trim(), etag))
-        return;
-    const res = new Response(null, { headers, status: 304, statusText: "Not Modified" });
-    res.headers.set("X-Caught", "true");
-    throw res;
-}
-function MatchEtags(header, etag) {
-    if (header === "*")
-        return true;
-    for (const term of header.split(/,\s*/)) {
-        let s = term.startsWith('W/') ? 'W/'.length : 0;
-        let e = term.endsWith('"') ? term.length - 1 : term.length;
-        if (term.startsWith('"', s))
-            s++;
-        const tag = term.slice(s, e);
-        if (etag === tag)
-            return true;
-    }
-    return false;
-}
+export const AssertETagStale = etag.AssertETagStale;
 /**
  * This is to fix issues with deno
  * When you try and change the statusText on a Response object

package/dist/router.d.ts

@@ -27,6 +27,11 @@ export declare class RouteResolver {
     resolve(): Promise<Response | null>;
     unwind(e: unknown, offset: number): Promise<Response>;
 }
+type IngestContext = {
+    path: string[];
+    route: string;
+    params: string[];
+};
 export declare class RouteTree {
     private nested;
     private index;
@@ -34,12 +39,13 @@ export declare class RouteTree {
     private wild;
     private wildCard;
     constructor();
-    ingest(node: RouteLeaf, path?: string[]): void;
+    ingest(node: RouteLeaf, ctx?: IngestContext): void;
     _applyChain(out: RouteResolver, fragments: string[], offset?: number): void;
 }
 declare class RouteLeaf {
     readonly module: RouteModule<any>;
     readonly path: string;
     constructor(module: RouteModule<any>, path: string);
+    checkParameters(ctx: IngestContext): void;
 }
 export {};

package/dist/router.js

@@ -148,19 +148,28 @@ export class RouteTree {
         this.wild = null;
         this.slug = null;
     }
-    ingest(node, path) {
-        if (!path)
-            path = node.path.length === 0 ? [] : node.path.slice(1).split("/");
-        if (path.length === 0) {
+    ingest(node, ctx) {
+        if (!ctx)
+            ctx = {
+                path: node.path.slice(1).split("/").reverse(),
+                route: node.path,
+                params: [],
+            };
+        const segment = ctx.path.pop();
+        if (!segment) {
+            node.checkParameters(ctx);
             this.index = node;
             return;
         }
-        if (path[0] === "$") {
+        if (segment === "$") {
+            ctx.params.push('$');
+            node.checkParameters(ctx);
             this.slug = node;
             return;
         }
-        if (path[0][0] === "$") {
-            const wildCard = path[0].slice(1);
+        if (segment[0] === "$") {
+            const wildCard = segment.slice(1);
+            ctx.params.push(wildCard);
             // Check wildcard isn't being changed
             if (!this.wild) {
                 this.wildCard = wildCard;
@@ -169,15 +178,15 @@ export class RouteTree {
             else if (wildCard !== this.wildCard) {
                 throw new Error(`Redefinition of wild card ${this.wildCard} to ${wildCard}`);
             }
-            this.wild.ingest(node, path.slice(1));
+            this.wild.ingest(node, ctx);
             return;
         }
-        let next = this.nested.get(path[0]);
+        let next = this.nested.get(segment);
         if (!next) {
             next = new RouteTree();
-            this.nested.set(path[0], next);
+            this.nested.set(segment, next);
         }
-        next.ingest(node, path.slice(1));
+        next.ingest(node, ctx);
     }
     _applyChain(out, fragments, offset = 0) {
         if (this.slug) {
@@ -205,4 +214,13 @@ class RouteLeaf {
         this.module = module;
         this.path = path;
     }
+    checkParameters(ctx) {
+        if (!this.module.parameters)
+            return;
+        for (const key in this.module.parameters) {
+            if (ctx.params.includes(key))
+                continue;
+            console.warn(`\x1b[33mWarn:\x1b[0m \x1b[36m${ctx.route}\x1b[0m has no parameter \x1b[36m${key}\x1b[0m`);
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "htmx-router",
-	"version": "2.2.6",
+	"version": "2.2.8",
 	"description": "A lightweight SSR framework with server+client islands",
 	"keywords": [ "htmx", "router", "client islands", "ssr", "vite" ],
 	"type": "module",
@@ -15,6 +15,7 @@
 		"./defer":        "./dist/defer.js",
 		"./endpoint":     "./dist/endpoint.js",
 		"./event":        "./dist/event.js",
+		"./etag":         "./dist/etag.js",
 		"./event-source": "./dist/event-source.js",
 		"./navigate":     "./dist/navigate.js",
 		"./response":     "./dist/response.js",