@danmat/query-server 0.1.1 → 0.2.0

package/README.md

@@ -70,6 +70,25 @@ Builds an `Accept-Query` header value from the media types you accept (strings a
 
 Returns a copy of `response` with the `Accept-Query` header set — handy on both success and `415` responses.
 
+### `conditional(request, response): Promise<Response>`
+
+HTTP revalidation for QUERY results: attaches a strong `ETag`, and returns `304 Not Modified` when the request's `If-None-Match` already matches (echoing `Content-Location`/`Cache-Control`/`Vary`). Only applied to 2xx responses. QUERY is safe and cacheable, so this is exactly the method conditional requests are meant for.
+
+```ts
+return conditional(
+  request,
+  withContentLocation(withAcceptQuery(Response.json(results), ACCEPTED), request.url),
+);
+```
+
+### `withContentLocation(response, location): Response`
+
+Returns a copy of `response` with a `Content-Location` header (the URL identifying the returned representation).
+
+### `etagFor(body): Promise<string>`
+
+Computes a strong `ETag` (quoted SHA-256/base64url) for a body — equal bytes yield equal tags. Used by `conditional`, exposed for custom flows.
+
 ### `QueryRequestError`
 
 `Error` subclass with `status: number`, `headers: Record<string,string>`, and `toResponse(): Response`.

package/dist/index.cjs

@@ -93,14 +93,71 @@ function withAcceptQuery(response, mediaTypes) {
     headers
   });
 }
+function withContentLocation(response, location) {
+  const headers = new Headers(response.headers);
+  headers.set("content-location", location.toString());
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+async function getSubtle() {
+  const globalCrypto = globalThis.crypto;
+  if (globalCrypto?.subtle) return globalCrypto.subtle;
+  const specifier = "node:crypto";
+  const nodeCrypto = await import(specifier);
+  return nodeCrypto.webcrypto.subtle;
+}
+function base64url(buffer) {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+async function etagFor(body) {
+  const bytes = body == null ? new ArrayBuffer(0) : await new Response(body).arrayBuffer();
+  const digest = await (await getSubtle()).digest("SHA-256", bytes);
+  return `"${base64url(digest)}"`;
+}
+function ifNoneMatchSatisfied(ifNoneMatch, etag) {
+  if (!ifNoneMatch) return false;
+  if (ifNoneMatch.trim() === "*") return true;
+  const strip = (tag) => tag.trim().replace(/^W\//, "");
+  const target = strip(etag);
+  return ifNoneMatch.split(",").some((tag) => strip(tag) === target);
+}
+async function conditional(request, response) {
+  if (!response.ok) return response;
+  const buffer = await response.clone().arrayBuffer();
+  const etag = response.headers.get("etag") ?? await etagFor(buffer);
+  if (ifNoneMatchSatisfied(request.headers.get("if-none-match"), etag)) {
+    const headers2 = new Headers({ etag });
+    for (const name of ["content-location", "cache-control", "vary"]) {
+      const value = response.headers.get(name);
+      if (value) headers2.set(name, value);
+    }
+    return new Response(null, { status: 304, headers: headers2 });
+  }
+  const headers = new Headers(response.headers);
+  headers.set("etag", etag);
+  return new Response(buffer, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
 
 exports.QUERY_METHOD = QUERY_METHOD;
 exports.QueryRequestError = QueryRequestError;
 exports.acceptQueryHeader = acceptQueryHeader;
 exports.assertQueryRequest = assertQueryRequest;
 exports.checkQueryRequest = checkQueryRequest;
+exports.conditional = conditional;
+exports.etagFor = etagFor;
 exports.isQueryRequest = isQueryRequest;
 exports.readQueryJson = readQueryJson;
 exports.withAcceptQuery = withAcceptQuery;
+exports.withContentLocation = withContentLocation;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":["formatAcceptQuery","negotiateQuery"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @danmat/query-server\n *\n * Framework-agnostic server helpers for the HTTP QUERY method (RFC 10008),\n * built on Web-standard `Request`/`Response` — so they work in Hono, Deno,\n * Bun, Cloudflare Workers, and Node (via a web adapter).\n *\n * Validate incoming QUERY requests, enforce the RFC's `Content-Type`\n * requirement, negotiate the accepted query formats, and advertise them with\n * the `Accept-Query` response header.\n *\n * @see https://www.rfc-editor.org/rfc/rfc10008\n */\n\nimport {\n  formatAcceptQuery,\n  negotiateQuery,\n  type MediaRangeInput,\n} from \"@danmat/accept-query\";\n\n/** The QUERY method name. */\nexport const QUERY_METHOD = \"QUERY\";\n\nexport interface QueryRequestOptions {\n  /**\n   * Also accept `POST` requests carrying `X-HTTP-Method-Override: QUERY` as\n   * QUERY requests — the fallback that clients like `@danmat/query-fetch` use\n   * for servers that don't route QUERY natively. Default `true`.\n   */\n  allowMethodOverride?: boolean;\n}\n\nexport interface QueryValidationOptions extends QueryRequestOptions {\n  /**\n   * Media types this server accepts as query bodies. When provided, requests\n   * with an unsupported `Content-Type` are rejected with `415` and an\n   * `Accept-Query` header advertising these types.\n   */\n  accept?: MediaRangeInput[];\n}\n\n/**\n * An error describing why a request is not a valid QUERY, carrying the HTTP\n * status and headers that should be sent in response.\n */\nexport class QueryRequestError extends Error {\n  override name = \"QueryRequestError\";\n  readonly status: number;\n  readonly headers: Record<string, string>;\n\n  constructor(message: string, status: number, headers: Record<string, string> = {}) {\n    super(message);\n    this.status = status;\n    this.headers = headers;\n    Object.setPrototypeOf(this, QueryRequestError.prototype);\n  }\n\n  /** Render this error as a JSON `Response` with the appropriate status/headers. */\n  toResponse(): Response {\n    return new Response(JSON.stringify({ error: this.message }), {\n      status: this.status,\n      headers: { \"content-type\": \"application/json\", ...this.headers },\n    });\n  }\n}\n\n/** Whether a request should be handled as a QUERY (honoring method override). */\nexport function isQueryRequest(\n  request: Request,\n  options: QueryRequestOptions = {},\n): boolean {\n  const { allowMethodOverride = true } = options;\n  const method = request.method.toUpperCase();\n  if (method === QUERY_METHOD) return true;\n  if (allowMethodOverride && method === \"POST\") {\n    return (\n      (request.headers.get(\"x-http-method-override\") ?? \"\").toUpperCase() ===\n      QUERY_METHOD\n    );\n  }\n  return false;\n}\n\n/** Build an `Accept-Query` header value from the media types a server accepts. */\nexport function acceptQueryHeader(mediaTypes: MediaRangeInput[]): string {\n  return formatAcceptQuery(mediaTypes);\n}\n\nfunction isAccepted(contentType: string, accept: MediaRangeInput[]): boolean {\n  return negotiateQuery(formatAcceptQuery(accept), [contentType]) !== null;\n}\n\n/**\n * Validate that `request` is a well-formed QUERY per RFC 10008. Throws a\n * {@link QueryRequestError} (with the right HTTP status) when it isn't:\n *\n * - not a QUERY request → `405 Method Not Allowed` (`Allow: QUERY`)\n * - missing `Content-Type` → `400 Bad Request`\n * - unsupported `Content-Type` (when `accept` is given) → `415` + `Accept-Query`\n */\nexport function assertQueryRequest(\n  request: Request,\n  options: QueryValidationOptions = {},\n): void {\n  const { accept, allowMethodOverride = true } = options;\n\n  if (!isQueryRequest(request, { allowMethodOverride })) {\n    throw new QueryRequestError(\n      `Expected a ${QUERY_METHOD} request but received ${request.method}.`,\n      405,\n      { allow: QUERY_METHOD },\n    );\n  }\n\n  const contentType = request.headers.get(\"content-type\");\n  if (!contentType) {\n    throw new QueryRequestError(\n      \"A QUERY request must include a Content-Type (RFC 10008).\",\n      400,\n    );\n  }\n\n  if (accept && accept.length > 0 && !isAccepted(contentType, accept)) {\n    throw new QueryRequestError(\n      `Unsupported query media type \"${contentType}\".`,\n      415,\n      { \"accept-query\": acceptQueryHeader(accept) },\n    );\n  }\n}\n\n/**\n * Non-throwing companion to {@link assertQueryRequest}. Returns an error\n * `Response` to send back, or `null` if the request is valid.\n *\n * @example\n * ```ts\n * const bad = checkQueryRequest(request, { accept: [\"application/json\"] });\n * if (bad) return bad;\n * const query = await readQueryJson(request);\n * ```\n */\nexport function checkQueryRequest(\n  request: Request,\n  options: QueryValidationOptions = {},\n): Response | null {\n  try {\n    assertQueryRequest(request, options);\n    return null;\n  } catch (error) {\n    if (error instanceof QueryRequestError) return error.toResponse();\n    throw error;\n  }\n}\n\n/**\n * Read a QUERY request body as JSON, guarding the content type. Throws a\n * {@link QueryRequestError} (`415` for a non-JSON type, `400` for invalid JSON).\n */\nexport async function readQueryJson<T = unknown>(\n  request: Request,\n): Promise<T> {\n  const contentType = request.headers.get(\"content-type\") ?? \"\";\n  if (!/\\bjson\\b/i.test(contentType)) {\n    throw new QueryRequestError(\n      `Expected a JSON query body but Content-Type was \"${contentType || \"absent\"}\".`,\n      415,\n    );\n  }\n  try {\n    return (await request.json()) as T;\n  } catch {\n    throw new QueryRequestError(\"Query body is not valid JSON.\", 400);\n  }\n}\n\n/** Return a copy of `response` with an `Accept-Query` header advertising `mediaTypes`. */\nexport function withAcceptQuery(\n  response: Response,\n  mediaTypes: MediaRangeInput[],\n): Response {\n  const headers = new Headers(response.headers);\n  headers.set(\"accept-query\", acceptQueryHeader(mediaTypes));\n  return new Response(response.body, {\n    status: response.status,\n    statusText: response.statusText,\n    headers,\n  });\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":["formatAcceptQuery","negotiateQuery","headers"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @danmat/query-server\n *\n * Framework-agnostic server helpers for the HTTP QUERY method (RFC 10008),\n * built on Web-standard `Request`/`Response` — so they work in Hono, Deno,\n * Bun, Cloudflare Workers, and Node (via a web adapter).\n *\n * Validate incoming QUERY requests, enforce the RFC's `Content-Type`\n * requirement, negotiate the accepted query formats, and advertise them with\n * the `Accept-Query` response header.\n *\n * @see https://www.rfc-editor.org/rfc/rfc10008\n */\n\nimport {\n  formatAcceptQuery,\n  type MediaRangeInput,\n  negotiateQuery,\n} from \"@danmat/accept-query\";\n\n/** The QUERY method name. */\nexport const QUERY_METHOD = \"QUERY\";\n\nexport interface QueryRequestOptions {\n  /**\n   * Also accept `POST` requests carrying `X-HTTP-Method-Override: QUERY` as\n   * QUERY requests — the fallback that clients like `@danmat/query-fetch` use\n   * for servers that don't route QUERY natively. Default `true`.\n   */\n  allowMethodOverride?: boolean;\n}\n\nexport interface QueryValidationOptions extends QueryRequestOptions {\n  /**\n   * Media types this server accepts as query bodies. When provided, requests\n   * with an unsupported `Content-Type` are rejected with `415` and an\n   * `Accept-Query` header advertising these types.\n   */\n  accept?: MediaRangeInput[];\n}\n\n/**\n * An error describing why a request is not a valid QUERY, carrying the HTTP\n * status and headers that should be sent in response.\n */\nexport class QueryRequestError extends Error {\n  override name = \"QueryRequestError\";\n  readonly status: number;\n  readonly headers: Record<string, string>;\n\n  constructor(\n    message: string,\n    status: number,\n    headers: Record<string, string> = {},\n  ) {\n    super(message);\n    this.status = status;\n    this.headers = headers;\n    Object.setPrototypeOf(this, QueryRequestError.prototype);\n  }\n\n  /** Render this error as a JSON `Response` with the appropriate status/headers. */\n  toResponse(): Response {\n    return new Response(JSON.stringify({ error: this.message }), {\n      status: this.status,\n      headers: { \"content-type\": \"application/json\", ...this.headers },\n    });\n  }\n}\n\n/** Whether a request should be handled as a QUERY (honoring method override). */\nexport function isQueryRequest(\n  request: Request,\n  options: QueryRequestOptions = {},\n): boolean {\n  const { allowMethodOverride = true } = options;\n  const method = request.method.toUpperCase();\n  if (method === QUERY_METHOD) return true;\n  if (allowMethodOverride && method === \"POST\") {\n    return (\n      (request.headers.get(\"x-http-method-override\") ?? \"\").toUpperCase() ===\n      QUERY_METHOD\n    );\n  }\n  return false;\n}\n\n/** Build an `Accept-Query` header value from the media types a server accepts. */\nexport function acceptQueryHeader(mediaTypes: MediaRangeInput[]): string {\n  return formatAcceptQuery(mediaTypes);\n}\n\nfunction isAccepted(contentType: string, accept: MediaRangeInput[]): boolean {\n  return negotiateQuery(formatAcceptQuery(accept), [contentType]) !== null;\n}\n\n/**\n * Validate that `request` is a well-formed QUERY per RFC 10008. Throws a\n * {@link QueryRequestError} (with the right HTTP status) when it isn't:\n *\n * - not a QUERY request → `405 Method Not Allowed` (`Allow: QUERY`)\n * - missing `Content-Type` → `400 Bad Request`\n * - unsupported `Content-Type` (when `accept` is given) → `415` + `Accept-Query`\n */\nexport function assertQueryRequest(\n  request: Request,\n  options: QueryValidationOptions = {},\n): void {\n  const { accept, allowMethodOverride = true } = options;\n\n  if (!isQueryRequest(request, { allowMethodOverride })) {\n    throw new QueryRequestError(\n      `Expected a ${QUERY_METHOD} request but received ${request.method}.`,\n      405,\n      { allow: QUERY_METHOD },\n    );\n  }\n\n  const contentType = request.headers.get(\"content-type\");\n  if (!contentType) {\n    throw new QueryRequestError(\n      \"A QUERY request must include a Content-Type (RFC 10008).\",\n      400,\n    );\n  }\n\n  if (accept && accept.length > 0 && !isAccepted(contentType, accept)) {\n    throw new QueryRequestError(\n      `Unsupported query media type \"${contentType}\".`,\n      415,\n      { \"accept-query\": acceptQueryHeader(accept) },\n    );\n  }\n}\n\n/**\n * Non-throwing companion to {@link assertQueryRequest}. Returns an error\n * `Response` to send back, or `null` if the request is valid.\n *\n * @example\n * ```ts\n * const bad = checkQueryRequest(request, { accept: [\"application/json\"] });\n * if (bad) return bad;\n * const query = await readQueryJson(request);\n * ```\n */\nexport function checkQueryRequest(\n  request: Request,\n  options: QueryValidationOptions = {},\n): Response | null {\n  try {\n    assertQueryRequest(request, options);\n    return null;\n  } catch (error) {\n    if (error instanceof QueryRequestError) return error.toResponse();\n    throw error;\n  }\n}\n\n/**\n * Read a QUERY request body as JSON, guarding the content type. Throws a\n * {@link QueryRequestError} (`415` for a non-JSON type, `400` for invalid JSON).\n */\nexport async function readQueryJson<T = unknown>(request: Request): Promise<T> {\n  const contentType = request.headers.get(\"content-type\") ?? \"\";\n  if (!/\\bjson\\b/i.test(contentType)) {\n    throw new QueryRequestError(\n      `Expected a JSON query body but Content-Type was \"${contentType || \"absent\"}\".`,\n      415,\n    );\n  }\n  try {\n    return (await request.json()) as T;\n  } catch {\n    throw new QueryRequestError(\"Query body is not valid JSON.\", 400);\n  }\n}\n\n/** Return a copy of `response` with an `Accept-Query` header advertising `mediaTypes`. */\nexport function withAcceptQuery(\n  response: Response,\n  mediaTypes: MediaRangeInput[],\n): Response {\n  const headers = new Headers(response.headers);\n  headers.set(\"accept-query\", acceptQueryHeader(mediaTypes));\n  return new Response(response.body, {\n    status: response.status,\n    statusText: response.statusText,\n    headers,\n  });\n}\n\n/** Return a copy of `response` with a `Content-Location` header. */\nexport function withContentLocation(\n  response: Response,\n  location: string | URL,\n): Response {\n  const headers = new Headers(response.headers);\n  headers.set(\"content-location\", location.toString());\n  return new Response(response.body, {\n    status: response.status,\n    statusText: response.statusText,\n    headers,\n  });\n}\n\nasync function getSubtle(): Promise<SubtleCrypto> {\n  const globalCrypto = (globalThis as { crypto?: Crypto }).crypto;\n  if (globalCrypto?.subtle) return globalCrypto.subtle;\n  // Older Node without a global `crypto`; never reached in browsers/workers.\n  const specifier = \"node:crypto\";\n  const nodeCrypto = (await import(specifier)) as {\n    webcrypto: { subtle: SubtleCrypto };\n  };\n  return nodeCrypto.webcrypto.subtle;\n}\n\nfunction base64url(buffer: ArrayBuffer): string {\n  const bytes = new Uint8Array(buffer);\n  let binary = \"\";\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary)\n    .replace(/\\+/g, \"-\")\n    .replace(/\\//g, \"_\")\n    .replace(/=+$/, \"\");\n}\n\n/**\n * Compute a strong `ETag` (a quoted SHA-256/base64url digest) for a body. A\n * QUERY response's representation is identified by its bytes, so equal bodies\n * yield equal tags.\n */\nexport async function etagFor(\n  body: BodyInit | null | undefined,\n): Promise<string> {\n  const bytes =\n    body == null ? new ArrayBuffer(0) : await new Response(body).arrayBuffer();\n  const digest = await (await getSubtle()).digest(\"SHA-256\", bytes);\n  return `\"${base64url(digest)}\"`;\n}\n\n/** RFC 9110 weak comparison: does `ifNoneMatch` match `etag`? */\nfunction ifNoneMatchSatisfied(\n  ifNoneMatch: string | null,\n  etag: string,\n): boolean {\n  if (!ifNoneMatch) return false;\n  if (ifNoneMatch.trim() === \"*\") return true;\n  const strip = (tag: string) => tag.trim().replace(/^W\\//, \"\");\n  const target = strip(etag);\n  return ifNoneMatch.split(\",\").some((tag) => strip(tag) === target);\n}\n\n/**\n * Add HTTP revalidation to a response: attach a strong `ETag`, and when the\n * request's `If-None-Match` already matches, short-circuit to `304 Not\n * Modified`. Safe for QUERY, which is idempotent and cacheable.\n *\n * Only applied to successful (2xx) responses; others pass through unchanged.\n *\n * @example\n * ```ts\n * return conditional(request, withAcceptQuery(Response.json(results), ACCEPTED));\n * ```\n */\nexport async function conditional(\n  request: Request,\n  response: Response,\n): Promise<Response> {\n  if (!response.ok) return response;\n\n  const buffer = await response.clone().arrayBuffer();\n  const etag = response.headers.get(\"etag\") ?? (await etagFor(buffer));\n\n  if (ifNoneMatchSatisfied(request.headers.get(\"if-none-match\"), etag)) {\n    const headers = new Headers({ etag });\n    // A 304 carries no body but should echo the caching-relevant headers.\n    for (const name of [\"content-location\", \"cache-control\", \"vary\"]) {\n      const value = response.headers.get(name);\n      if (value) headers.set(name, value);\n    }\n    return new Response(null, { status: 304, headers });\n  }\n\n  const headers = new Headers(response.headers);\n  headers.set(\"etag\", etag);\n  return new Response(buffer, {\n    status: response.status,\n    statusText: response.statusText,\n    headers,\n  });\n}\n"]}

package/dist/index.d.cts

@@ -76,5 +76,26 @@ declare function checkQueryRequest(request: Request, options?: QueryValidationOp
 declare function readQueryJson<T = unknown>(request: Request): Promise<T>;
 /** Return a copy of `response` with an `Accept-Query` header advertising `mediaTypes`. */
 declare function withAcceptQuery(response: Response, mediaTypes: MediaRangeInput[]): Response;
+/** Return a copy of `response` with a `Content-Location` header. */
+declare function withContentLocation(response: Response, location: string | URL): Response;
+/**
+ * Compute a strong `ETag` (a quoted SHA-256/base64url digest) for a body. A
+ * QUERY response's representation is identified by its bytes, so equal bodies
+ * yield equal tags.
+ */
+declare function etagFor(body: BodyInit | null | undefined): Promise<string>;
+/**
+ * Add HTTP revalidation to a response: attach a strong `ETag`, and when the
+ * request's `If-None-Match` already matches, short-circuit to `304 Not
+ * Modified`. Safe for QUERY, which is idempotent and cacheable.
+ *
+ * Only applied to successful (2xx) responses; others pass through unchanged.
+ *
+ * @example
+ * ```ts
+ * return conditional(request, withAcceptQuery(Response.json(results), ACCEPTED));
+ * ```
+ */
+declare function conditional(request: Request, response: Response): Promise<Response>;
 
-export { QUERY_METHOD, QueryRequestError, type QueryRequestOptions, type QueryValidationOptions, acceptQueryHeader, assertQueryRequest, checkQueryRequest, isQueryRequest, readQueryJson, withAcceptQuery };
+export { QUERY_METHOD, QueryRequestError, type QueryRequestOptions, type QueryValidationOptions, acceptQueryHeader, assertQueryRequest, checkQueryRequest, conditional, etagFor, isQueryRequest, readQueryJson, withAcceptQuery, withContentLocation };

package/dist/index.d.ts

@@ -76,5 +76,26 @@ declare function checkQueryRequest(request: Request, options?: QueryValidationOp
 declare function readQueryJson<T = unknown>(request: Request): Promise<T>;
 /** Return a copy of `response` with an `Accept-Query` header advertising `mediaTypes`. */
 declare function withAcceptQuery(response: Response, mediaTypes: MediaRangeInput[]): Response;
+/** Return a copy of `response` with a `Content-Location` header. */
+declare function withContentLocation(response: Response, location: string | URL): Response;
+/**
+ * Compute a strong `ETag` (a quoted SHA-256/base64url digest) for a body. A
+ * QUERY response's representation is identified by its bytes, so equal bodies
+ * yield equal tags.
+ */
+declare function etagFor(body: BodyInit | null | undefined): Promise<string>;
+/**
+ * Add HTTP revalidation to a response: attach a strong `ETag`, and when the
+ * request's `If-None-Match` already matches, short-circuit to `304 Not
+ * Modified`. Safe for QUERY, which is idempotent and cacheable.
+ *
+ * Only applied to successful (2xx) responses; others pass through unchanged.
+ *
+ * @example
+ * ```ts
+ * return conditional(request, withAcceptQuery(Response.json(results), ACCEPTED));
+ * ```
+ */
+declare function conditional(request: Request, response: Response): Promise<Response>;
 
-export { QUERY_METHOD, QueryRequestError, type QueryRequestOptions, type QueryValidationOptions, acceptQueryHeader, assertQueryRequest, checkQueryRequest, isQueryRequest, readQueryJson, withAcceptQuery };
+export { QUERY_METHOD, QueryRequestError, type QueryRequestOptions, type QueryValidationOptions, acceptQueryHeader, assertQueryRequest, checkQueryRequest, conditional, etagFor, isQueryRequest, readQueryJson, withAcceptQuery, withContentLocation };

package/dist/index.js

@@ -91,7 +91,61 @@ function withAcceptQuery(response, mediaTypes) {
     headers
   });
 }
+function withContentLocation(response, location) {
+  const headers = new Headers(response.headers);
+  headers.set("content-location", location.toString());
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+async function getSubtle() {
+  const globalCrypto = globalThis.crypto;
+  if (globalCrypto?.subtle) return globalCrypto.subtle;
+  const specifier = "node:crypto";
+  const nodeCrypto = await import(specifier);
+  return nodeCrypto.webcrypto.subtle;
+}
+function base64url(buffer) {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+async function etagFor(body) {
+  const bytes = body == null ? new ArrayBuffer(0) : await new Response(body).arrayBuffer();
+  const digest = await (await getSubtle()).digest("SHA-256", bytes);
+  return `"${base64url(digest)}"`;
+}
+function ifNoneMatchSatisfied(ifNoneMatch, etag) {
+  if (!ifNoneMatch) return false;
+  if (ifNoneMatch.trim() === "*") return true;
+  const strip = (tag) => tag.trim().replace(/^W\//, "");
+  const target = strip(etag);
+  return ifNoneMatch.split(",").some((tag) => strip(tag) === target);
+}
+async function conditional(request, response) {
+  if (!response.ok) return response;
+  const buffer = await response.clone().arrayBuffer();
+  const etag = response.headers.get("etag") ?? await etagFor(buffer);
+  if (ifNoneMatchSatisfied(request.headers.get("if-none-match"), etag)) {
+    const headers2 = new Headers({ etag });
+    for (const name of ["content-location", "cache-control", "vary"]) {
+      const value = response.headers.get(name);
+      if (value) headers2.set(name, value);
+    }
+    return new Response(null, { status: 304, headers: headers2 });
+  }
+  const headers = new Headers(response.headers);
+  headers.set("etag", etag);
+  return new Response(buffer, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
 
-export { QUERY_METHOD, QueryRequestError, acceptQueryHeader, assertQueryRequest, checkQueryRequest, isQueryRequest, readQueryJson, withAcceptQuery };
+export { QUERY_METHOD, QueryRequestError, acceptQueryHeader, assertQueryRequest, checkQueryRequest, conditional, etagFor, isQueryRequest, readQueryJson, withAcceptQuery, withContentLocation };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AAqBO,IAAM,YAAA,GAAe;AAwBrB,IAAM,iBAAA,GAAN,MAAM,kBAAA,SAA0B,KAAA,CAAM;AAAA,EAClC,IAAA,GAAO,mBAAA;AAAA,EACP,MAAA;AAAA,EACA,OAAA;AAAA,EAET,WAAA,CAAY,OAAA,EAAiB,MAAA,EAAgB,OAAA,GAAkC,EAAC,EAAG;AACjF,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,OAAA,GAAU,OAAA;AACf,IAAA,MAAA,CAAO,cAAA,CAAe,IAAA,EAAM,kBAAA,CAAkB,SAAS,CAAA;AAAA,EACzD;AAAA;AAAA,EAGA,UAAA,GAAuB;AACrB,IAAA,OAAO,IAAI,SAAS,IAAA,CAAK,SAAA,CAAU,EAAE,KAAA,EAAO,IAAA,CAAK,OAAA,EAAS,CAAA,EAAG;AAAA,MAC3D,QAAQ,IAAA,CAAK,MAAA;AAAA,MACb,SAAS,EAAE,cAAA,EAAgB,kBAAA,EAAoB,GAAG,KAAK,OAAA;AAAQ,KAChE,CAAA;AAAA,EACH;AACF;AAGO,SAAS,cAAA,CACd,OAAA,EACA,OAAA,GAA+B,EAAC,EACvB;AACT,EAAA,MAAM,EAAE,mBAAA,GAAsB,IAAA,EAAK,GAAI,OAAA;AACvC,EAAA,MAAM,MAAA,GAAS,OAAA,CAAQ,MAAA,CAAO,WAAA,EAAY;AAC1C,EAAA,IAAI,MAAA,KAAW,cAAc,OAAO,IAAA;AACpC,EAAA,IAAI,mBAAA,IAAuB,WAAW,MAAA,EAAQ;AAC5C,IAAA,OAAA,CACG,QAAQ,OAAA,CAAQ,GAAA,CAAI,wBAAwB,CAAA,IAAK,EAAA,EAAI,aAAY,KAClE,YAAA;AAAA,EAEJ;AACA,EAAA,OAAO,KAAA;AACT;AAGO,SAAS,kBAAkB,UAAA,EAAuC;AACvE,EAAA,OAAO,kBAAkB,UAAU,CAAA;AACrC;AAEA,SAAS,UAAA,CAAW,aAAqB,MAAA,EAAoC;AAC3E,EAAA,OAAO,eAAe,iBAAA,CAAkB,MAAM,GAAG,CAAC,WAAW,CAAC,CAAA,KAAM,IAAA;AACtE;AAUO,SAAS,kBAAA,CACd,OAAA,EACA,OAAA,GAAkC,EAAC,EAC7B;AACN,EAAA,MAAM,EAAE,MAAA,EAAQ,mBAAA,GAAsB,IAAA,EAAK,GAAI,OAAA;AAE/C,EAAA,IAAI,CAAC,cAAA,CAAe,OAAA,EAAS,EAAE,mBAAA,EAAqB,CAAA,EAAG;AACrD,IAAA,MAAM,IAAI,iBAAA;AAAA,MACR,CAAA,WAAA,EAAc,YAAY,CAAA,sBAAA,EAAyB,OAAA,CAAQ,MAAM,CAAA,CAAA,CAAA;AAAA,MACjE,GAAA;AAAA,MACA,EAAE,OAAO,YAAA;AAAa,KACxB;AAAA,EACF;AAEA,EAAA,MAAM,WAAA,GAAc,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,cAAc,CAAA;AACtD,EAAA,IAAI,CAAC,WAAA,EAAa;AAChB,IAAA,MAAM,IAAI,iBAAA;AAAA,MACR,0DAAA;AAAA,MACA;AAAA,KACF;AAAA,EACF;AAEA,EAAA,IAAI,MAAA,IAAU,OAAO,MAAA,GAAS,CAAA,IAAK,CAAC,UAAA,CAAW,WAAA,EAAa,MAAM,CAAA,EAAG;AACnE,IAAA,MAAM,IAAI,iBAAA;AAAA,MACR,iCAAiC,WAAW,CAAA,EAAA,CAAA;AAAA,MAC5C,GAAA;AAAA,MACA,EAAE,cAAA,EAAgB,iBAAA,CAAkB,MAAM,CAAA;AAAE,KAC9C;AAAA,EACF;AACF;AAaO,SAAS,iBAAA,CACd,OAAA,EACA,OAAA,GAAkC,EAAC,EAClB;AACjB,EAAA,IAAI;AACF,IAAA,kBAAA,CAAmB,SAAS,OAAO,CAAA;AACnC,IAAA,OAAO,IAAA;AAAA,EACT,SAAS,KAAA,EAAO;AACd,IAAA,IAAI,KAAA,YAAiB,iBAAA,EAAmB,OAAO,KAAA,CAAM,UAAA,EAAW;AAChE,IAAA,MAAM,KAAA;AAAA,EACR;AACF;AAMA,eAAsB,cACpB,OAAA,EACY;AACZ,EAAA,MAAM,WAAA,GAAc,OAAA,CAAQ,OAAA,CAAQ,GAAA,CAAI,cAAc,CAAA,IAAK,EAAA;AAC3D,EAAA,IAAI,CAAC,WAAA,CAAY,IAAA,CAAK,WAAW,CAAA,EAAG;AAClC,IAAA,MAAM,IAAI,iBAAA;AAAA,MACR,CAAA,iDAAA,EAAoD,eAAe,QAAQ,CAAA,EAAA,CAAA;AAAA,MAC3E;AAAA,KACF;AAAA,EACF;AACA,EAAA,IAAI;AACF,IAAA,OAAQ,MAAM,QAAQ,IAAA,EAAK;AAAA,EAC7B,CAAA,CAAA,MAAQ;AACN,IAAA,MAAM,IAAI,iBAAA,CAAkB,+BAAA,EAAiC,GAAG,CAAA;AAAA,EAClE;AACF;AAGO,SAAS,eAAA,CACd,UACA,UAAA,EACU;AACV,EAAA,MAAM,OAAA,GAAU,IAAI,OAAA,CAAQ,QAAA,CAAS,OAAO,CAAA;AAC5C,EAAA,OAAA,CAAQ,GAAA,CAAI,cAAA,EAAgB,iBAAA,CAAkB,UAAU,CAAC,CAAA;AACzD,EAAA,OAAO,IAAI,QAAA,CAAS,QAAA,CAAS,IAAA,EAAM;AAAA,IACjC,QAAQ,QAAA,CAAS,MAAA;AAAA,IACjB,YAAY,QAAA,CAAS,UAAA;AAAA,IACrB;AAAA,GACD,CAAA;AACH","file":"index.js","sourcesContent":["/**\n * @danmat/query-server\n *\n * Framework-agnostic server helpers for the HTTP QUERY method (RFC 10008),\n * built on Web-standard `Request`/`Response` — so they work in Hono, Deno,\n * Bun, Cloudflare Workers, and Node (via a web adapter).\n *\n * Validate incoming QUERY requests, enforce the RFC's `Content-Type`\n * requirement, negotiate the accepted query formats, and advertise them with\n * the `Accept-Query` response header.\n *\n * @see https://www.rfc-editor.org/rfc/rfc10008\n */\n\nimport {\n  formatAcceptQuery,\n  negotiateQuery,\n  type MediaRangeInput,\n} from \"@danmat/accept-query\";\n\n/** The QUERY method name. */\nexport const QUERY_METHOD = \"QUERY\";\n\nexport interface QueryRequestOptions {\n  /**\n   * Also accept `POST` requests carrying `X-HTTP-Method-Override: QUERY` as\n   * QUERY requests — the fallback that clients like `@danmat/query-fetch` use\n   * for servers that don't route QUERY natively. Default `true`.\n   */\n  allowMethodOverride?: boolean;\n}\n\nexport interface QueryValidationOptions extends QueryRequestOptions {\n  /**\n   * Media types this server accepts as query bodies. When provided, requests\n   * with an unsupported `Content-Type` are rejected with `415` and an\n   * `Accept-Query` header advertising these types.\n   */\n  accept?: MediaRangeInput[];\n}\n\n/**\n * An error describing why a request is not a valid QUERY, carrying the HTTP\n * status and headers that should be sent in response.\n */\nexport class QueryRequestError extends Error {\n  override name = \"QueryRequestError\";\n  readonly status: number;\n  readonly headers: Record<string, string>;\n\n  constructor(message: string, status: number, headers: Record<string, string> = {}) {\n    super(message);\n    this.status = status;\n    this.headers = headers;\n    Object.setPrototypeOf(this, QueryRequestError.prototype);\n  }\n\n  /** Render this error as a JSON `Response` with the appropriate status/headers. */\n  toResponse(): Response {\n    return new Response(JSON.stringify({ error: this.message }), {\n      status: this.status,\n      headers: { \"content-type\": \"application/json\", ...this.headers },\n    });\n  }\n}\n\n/** Whether a request should be handled as a QUERY (honoring method override). */\nexport function isQueryRequest(\n  request: Request,\n  options: QueryRequestOptions = {},\n): boolean {\n  const { allowMethodOverride = true } = options;\n  const method = request.method.toUpperCase();\n  if (method === QUERY_METHOD) return true;\n  if (allowMethodOverride && method === \"POST\") {\n    return (\n      (request.headers.get(\"x-http-method-override\") ?? \"\").toUpperCase() ===\n      QUERY_METHOD\n    );\n  }\n  return false;\n}\n\n/** Build an `Accept-Query` header value from the media types a server accepts. */\nexport function acceptQueryHeader(mediaTypes: MediaRangeInput[]): string {\n  return formatAcceptQuery(mediaTypes);\n}\n\nfunction isAccepted(contentType: string, accept: MediaRangeInput[]): boolean {\n  return negotiateQuery(formatAcceptQuery(accept), [contentType]) !== null;\n}\n\n/**\n * Validate that `request` is a well-formed QUERY per RFC 10008. Throws a\n * {@link QueryRequestError} (with the right HTTP status) when it isn't:\n *\n * - not a QUERY request → `405 Method Not Allowed` (`Allow: QUERY`)\n * - missing `Content-Type` → `400 Bad Request`\n * - unsupported `Content-Type` (when `accept` is given) → `415` + `Accept-Query`\n */\nexport function assertQueryRequest(\n  request: Request,\n  options: QueryValidationOptions = {},\n): void {\n  const { accept, allowMethodOverride = true } = options;\n\n  if (!isQueryRequest(request, { allowMethodOverride })) {\n    throw new QueryRequestError(\n      `Expected a ${QUERY_METHOD} request but received ${request.method}.`,\n      405,\n      { allow: QUERY_METHOD },\n    );\n  }\n\n  const contentType = request.headers.get(\"content-type\");\n  if (!contentType) {\n    throw new QueryRequestError(\n      \"A QUERY request must include a Content-Type (RFC 10008).\",\n      400,\n    );\n  }\n\n  if (accept && accept.length > 0 && !isAccepted(contentType, accept)) {\n    throw new QueryRequestError(\n      `Unsupported query media type \"${contentType}\".`,\n      415,\n      { \"accept-query\": acceptQueryHeader(accept) },\n    );\n  }\n}\n\n/**\n * Non-throwing companion to {@link assertQueryRequest}. Returns an error\n * `Response` to send back, or `null` if the request is valid.\n *\n * @example\n * ```ts\n * const bad = checkQueryRequest(request, { accept: [\"application/json\"] });\n * if (bad) return bad;\n * const query = await readQueryJson(request);\n * ```\n */\nexport function checkQueryRequest(\n  request: Request,\n  options: QueryValidationOptions = {},\n): Response | null {\n  try {\n    assertQueryRequest(request, options);\n    return null;\n  } catch (error) {\n    if (error instanceof QueryRequestError) return error.toResponse();\n    throw error;\n  }\n}\n\n/**\n * Read a QUERY request body as JSON, guarding the content type. Throws a\n * {@link QueryRequestError} (`415` for a non-JSON type, `400` for invalid JSON).\n */\nexport async function readQueryJson<T = unknown>(\n  request: Request,\n): Promise<T> {\n  const contentType = request.headers.get(\"content-type\") ?? \"\";\n  if (!/\\bjson\\b/i.test(contentType)) {\n    throw new QueryRequestError(\n      `Expected a JSON query body but Content-Type was \"${contentType || \"absent\"}\".`,\n      415,\n    );\n  }\n  try {\n    return (await request.json()) as T;\n  } catch {\n    throw new QueryRequestError(\"Query body is not valid JSON.\", 400);\n  }\n}\n\n/** Return a copy of `response` with an `Accept-Query` header advertising `mediaTypes`. */\nexport function withAcceptQuery(\n  response: Response,\n  mediaTypes: MediaRangeInput[],\n): Response {\n  const headers = new Headers(response.headers);\n  headers.set(\"accept-query\", acceptQueryHeader(mediaTypes));\n  return new Response(response.body, {\n    status: response.status,\n    statusText: response.statusText,\n    headers,\n  });\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":["headers"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @danmat/query-server\n *\n * Framework-agnostic server helpers for the HTTP QUERY method (RFC 10008),\n * built on Web-standard `Request`/`Response` — so they work in Hono, Deno,\n * Bun, Cloudflare Workers, and Node (via a web adapter).\n *\n * Validate incoming QUERY requests, enforce the RFC's `Content-Type`\n * requirement, negotiate the accepted query formats, and advertise them with\n * the `Accept-Query` response header.\n *\n * @see https://www.rfc-editor.org/rfc/rfc10008\n */\n\nimport {\n  formatAcceptQuery,\n  type MediaRangeInput,\n  negotiateQuery,\n} from \"@danmat/accept-query\";\n\n/** The QUERY method name. */\nexport const QUERY_METHOD = \"QUERY\";\n\nexport interface QueryRequestOptions {\n  /**\n   * Also accept `POST` requests carrying `X-HTTP-Method-Override: QUERY` as\n   * QUERY requests — the fallback that clients like `@danmat/query-fetch` use\n   * for servers that don't route QUERY natively. Default `true`.\n   */\n  allowMethodOverride?: boolean;\n}\n\nexport interface QueryValidationOptions extends QueryRequestOptions {\n  /**\n   * Media types this server accepts as query bodies. When provided, requests\n   * with an unsupported `Content-Type` are rejected with `415` and an\n   * `Accept-Query` header advertising these types.\n   */\n  accept?: MediaRangeInput[];\n}\n\n/**\n * An error describing why a request is not a valid QUERY, carrying the HTTP\n * status and headers that should be sent in response.\n */\nexport class QueryRequestError extends Error {\n  override name = \"QueryRequestError\";\n  readonly status: number;\n  readonly headers: Record<string, string>;\n\n  constructor(\n    message: string,\n    status: number,\n    headers: Record<string, string> = {},\n  ) {\n    super(message);\n    this.status = status;\n    this.headers = headers;\n    Object.setPrototypeOf(this, QueryRequestError.prototype);\n  }\n\n  /** Render this error as a JSON `Response` with the appropriate status/headers. */\n  toResponse(): Response {\n    return new Response(JSON.stringify({ error: this.message }), {\n      status: this.status,\n      headers: { \"content-type\": \"application/json\", ...this.headers },\n    });\n  }\n}\n\n/** Whether a request should be handled as a QUERY (honoring method override). */\nexport function isQueryRequest(\n  request: Request,\n  options: QueryRequestOptions = {},\n): boolean {\n  const { allowMethodOverride = true } = options;\n  const method = request.method.toUpperCase();\n  if (method === QUERY_METHOD) return true;\n  if (allowMethodOverride && method === \"POST\") {\n    return (\n      (request.headers.get(\"x-http-method-override\") ?? \"\").toUpperCase() ===\n      QUERY_METHOD\n    );\n  }\n  return false;\n}\n\n/** Build an `Accept-Query` header value from the media types a server accepts. */\nexport function acceptQueryHeader(mediaTypes: MediaRangeInput[]): string {\n  return formatAcceptQuery(mediaTypes);\n}\n\nfunction isAccepted(contentType: string, accept: MediaRangeInput[]): boolean {\n  return negotiateQuery(formatAcceptQuery(accept), [contentType]) !== null;\n}\n\n/**\n * Validate that `request` is a well-formed QUERY per RFC 10008. Throws a\n * {@link QueryRequestError} (with the right HTTP status) when it isn't:\n *\n * - not a QUERY request → `405 Method Not Allowed` (`Allow: QUERY`)\n * - missing `Content-Type` → `400 Bad Request`\n * - unsupported `Content-Type` (when `accept` is given) → `415` + `Accept-Query`\n */\nexport function assertQueryRequest(\n  request: Request,\n  options: QueryValidationOptions = {},\n): void {\n  const { accept, allowMethodOverride = true } = options;\n\n  if (!isQueryRequest(request, { allowMethodOverride })) {\n    throw new QueryRequestError(\n      `Expected a ${QUERY_METHOD} request but received ${request.method}.`,\n      405,\n      { allow: QUERY_METHOD },\n    );\n  }\n\n  const contentType = request.headers.get(\"content-type\");\n  if (!contentType) {\n    throw new QueryRequestError(\n      \"A QUERY request must include a Content-Type (RFC 10008).\",\n      400,\n    );\n  }\n\n  if (accept && accept.length > 0 && !isAccepted(contentType, accept)) {\n    throw new QueryRequestError(\n      `Unsupported query media type \"${contentType}\".`,\n      415,\n      { \"accept-query\": acceptQueryHeader(accept) },\n    );\n  }\n}\n\n/**\n * Non-throwing companion to {@link assertQueryRequest}. Returns an error\n * `Response` to send back, or `null` if the request is valid.\n *\n * @example\n * ```ts\n * const bad = checkQueryRequest(request, { accept: [\"application/json\"] });\n * if (bad) return bad;\n * const query = await readQueryJson(request);\n * ```\n */\nexport function checkQueryRequest(\n  request: Request,\n  options: QueryValidationOptions = {},\n): Response | null {\n  try {\n    assertQueryRequest(request, options);\n    return null;\n  } catch (error) {\n    if (error instanceof QueryRequestError) return error.toResponse();\n    throw error;\n  }\n}\n\n/**\n * Read a QUERY request body as JSON, guarding the content type. Throws a\n * {@link QueryRequestError} (`415` for a non-JSON type, `400` for invalid JSON).\n */\nexport async function readQueryJson<T = unknown>(request: Request): Promise<T> {\n  const contentType = request.headers.get(\"content-type\") ?? \"\";\n  if (!/\\bjson\\b/i.test(contentType)) {\n    throw new QueryRequestError(\n      `Expected a JSON query body but Content-Type was \"${contentType || \"absent\"}\".`,\n      415,\n    );\n  }\n  try {\n    return (await request.json()) as T;\n  } catch {\n    throw new QueryRequestError(\"Query body is not valid JSON.\", 400);\n  }\n}\n\n/** Return a copy of `response` with an `Accept-Query` header advertising `mediaTypes`. */\nexport function withAcceptQuery(\n  response: Response,\n  mediaTypes: MediaRangeInput[],\n): Response {\n  const headers = new Headers(response.headers);\n  headers.set(\"accept-query\", acceptQueryHeader(mediaTypes));\n  return new Response(response.body, {\n    status: response.status,\n    statusText: response.statusText,\n    headers,\n  });\n}\n\n/** Return a copy of `response` with a `Content-Location` header. */\nexport function withContentLocation(\n  response: Response,\n  location: string | URL,\n): Response {\n  const headers = new Headers(response.headers);\n  headers.set(\"content-location\", location.toString());\n  return new Response(response.body, {\n    status: response.status,\n    statusText: response.statusText,\n    headers,\n  });\n}\n\nasync function getSubtle(): Promise<SubtleCrypto> {\n  const globalCrypto = (globalThis as { crypto?: Crypto }).crypto;\n  if (globalCrypto?.subtle) return globalCrypto.subtle;\n  // Older Node without a global `crypto`; never reached in browsers/workers.\n  const specifier = \"node:crypto\";\n  const nodeCrypto = (await import(specifier)) as {\n    webcrypto: { subtle: SubtleCrypto };\n  };\n  return nodeCrypto.webcrypto.subtle;\n}\n\nfunction base64url(buffer: ArrayBuffer): string {\n  const bytes = new Uint8Array(buffer);\n  let binary = \"\";\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary)\n    .replace(/\\+/g, \"-\")\n    .replace(/\\//g, \"_\")\n    .replace(/=+$/, \"\");\n}\n\n/**\n * Compute a strong `ETag` (a quoted SHA-256/base64url digest) for a body. A\n * QUERY response's representation is identified by its bytes, so equal bodies\n * yield equal tags.\n */\nexport async function etagFor(\n  body: BodyInit | null | undefined,\n): Promise<string> {\n  const bytes =\n    body == null ? new ArrayBuffer(0) : await new Response(body).arrayBuffer();\n  const digest = await (await getSubtle()).digest(\"SHA-256\", bytes);\n  return `\"${base64url(digest)}\"`;\n}\n\n/** RFC 9110 weak comparison: does `ifNoneMatch` match `etag`? */\nfunction ifNoneMatchSatisfied(\n  ifNoneMatch: string | null,\n  etag: string,\n): boolean {\n  if (!ifNoneMatch) return false;\n  if (ifNoneMatch.trim() === \"*\") return true;\n  const strip = (tag: string) => tag.trim().replace(/^W\\//, \"\");\n  const target = strip(etag);\n  return ifNoneMatch.split(\",\").some((tag) => strip(tag) === target);\n}\n\n/**\n * Add HTTP revalidation to a response: attach a strong `ETag`, and when the\n * request's `If-None-Match` already matches, short-circuit to `304 Not\n * Modified`. Safe for QUERY, which is idempotent and cacheable.\n *\n * Only applied to successful (2xx) responses; others pass through unchanged.\n *\n * @example\n * ```ts\n * return conditional(request, withAcceptQuery(Response.json(results), ACCEPTED));\n * ```\n */\nexport async function conditional(\n  request: Request,\n  response: Response,\n): Promise<Response> {\n  if (!response.ok) return response;\n\n  const buffer = await response.clone().arrayBuffer();\n  const etag = response.headers.get(\"etag\") ?? (await etagFor(buffer));\n\n  if (ifNoneMatchSatisfied(request.headers.get(\"if-none-match\"), etag)) {\n    const headers = new Headers({ etag });\n    // A 304 carries no body but should echo the caching-relevant headers.\n    for (const name of [\"content-location\", \"cache-control\", \"vary\"]) {\n      const value = response.headers.get(name);\n      if (value) headers.set(name, value);\n    }\n    return new Response(null, { status: 304, headers });\n  }\n\n  const headers = new Headers(response.headers);\n  headers.set(\"etag\", etag);\n  return new Response(buffer, {\n    status: response.status,\n    statusText: response.statusText,\n    headers,\n  });\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danmat/query-server",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Framework-agnostic server helpers for the HTTP QUERY method (RFC 10008): validate requests, negotiate content types, and advertise Accept-Query. Built on Web-standard Request/Response.",
   "keywords": [
     "http",
@@ -12,7 +12,11 @@
     "middleware",
     "accept-query",
     "hono",
-    "content-negotiation"
+    "content-negotiation",
+    "etag",
+    "caching",
+    "conditional-requests",
+    "revalidation"
   ],
   "type": "module",
   "main": "./dist/index.cjs",
@@ -39,7 +43,10 @@
     "test:watch": "vitest",
     "coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "prepare": "husky"
   },
   "author": "Dan Matthew <dannymatthew@gmail.com>",
   "license": "MIT",
@@ -58,9 +65,15 @@
     "@danmat/accept-query": "^0.1.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.2",
     "@vitest/coverage-v8": "^2.1.8",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.5.2",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"
+  },
+  "lint-staged": {
+    "*.{ts,js,json,jsonc,md}": "biome check --write --no-errors-on-unmatched"
   }
 }