@danmat/query-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan Matthew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @danmat/query-server
+
+[![CI](https://github.com/DanMat/query-server/actions/workflows/ci.yml/badge.svg)](https://github.com/DanMat/query-server/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@danmat/query-server.svg)](https://www.npmjs.com/package/@danmat/query-server)
+[![minified + gzip size](https://img.shields.io/bundlejs/size/@danmat/query-server)](https://bundlejs.com/?q=@danmat/query-server)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+Framework-agnostic **server** helpers for the HTTP QUERY method ([RFC 10008](https://www.rfc-editor.org/rfc/rfc10008)). Validate incoming QUERY requests, enforce the RFC's `Content-Type` rule, negotiate accepted query formats, and advertise them with `Accept-Query`.
+
+Built on **Web-standard `Request`/`Response`**, so it runs anywhere they do — Hono, Deno, Bun, Cloudflare Workers, and Node (via a web adapter). Its only dependency is [`@danmat/accept-query`](https://github.com/DanMat/accept-query).
+
+```ts
+import { checkQueryRequest, readQueryJson, withAcceptQuery } from "@danmat/query-server";
+
+const ACCEPTED = ["application/json", "application/sql"];
+
+async function handler(request: Request): Promise<Response> {
+  // Reject non-QUERY, missing/unsupported Content-Type — with correct status codes.
+  const rejection = checkQueryRequest(request, { accept: ACCEPTED });
+  if (rejection) return withAcceptQuery(rejection, ACCEPTED);
+
+  const query = await readQueryJson<{ filter: unknown }>(request);
+  const results = await runQuery(query);
+
+  return withAcceptQuery(Response.json(results), ACCEPTED);
+}
+```
+
+## Why?
+
+RFC 10008 puts real obligations on the *server*: it MUST reject a QUERY whose `Content-Type` is missing, it should tell clients which query formats it accepts (via `Accept-Query`), and it needs to answer the method-override fallback that clients use when they're unsure the server speaks QUERY. This library packages those rules so your handler stays about *your* query logic.
+
+## Install
+
+```sh
+npm install @danmat/query-server
+```
+
+## API
+
+### `isQueryRequest(request, options?): boolean`
+
+Whether a request should be handled as a QUERY. Recognizes the `QUERY` method and, by default, `POST` + `X-HTTP-Method-Override: QUERY` (the fallback used by clients like [`@danmat/query-fetch`](https://github.com/DanMat/query-fetch)). Disable with `{ allowMethodOverride: false }`.
+
+### `assertQueryRequest(request, options?): void`
+
+Throws a `QueryRequestError` (carrying the correct HTTP `status` and `headers`) when the request isn't a valid QUERY:
+
+| Condition | Status | Extra |
+| --- | --- | --- |
+| Not a QUERY request | `405` | `Allow: QUERY` |
+| Missing `Content-Type` | `400` | — |
+| `Content-Type` not in `accept` | `415` | `Accept-Query: …` |
+
+Pass `{ accept: ["application/json", …] }` to enable media-type negotiation (wildcards and parameters supported).
+
+### `checkQueryRequest(request, options?): Response | null`
+
+Non-throwing companion — returns a ready-to-send error `Response`, or `null` when the request is valid.
+
+### `readQueryJson<T>(request): Promise<T>`
+
+Reads the body as JSON, guarding the content type (`415` for a non-JSON type, `400` for malformed JSON).
+
+### `acceptQueryHeader(mediaTypes): string`
+
+Builds an `Accept-Query` header value from the media types you accept (strings and/or structured ranges with `q` weights).
+
+### `withAcceptQuery(response, mediaTypes): Response`
+
+Returns a copy of `response` with the `Accept-Query` header set — handy on both success and `415` responses.
+
+### `QueryRequestError`
+
+`Error` subclass with `status: number`, `headers: Record<string,string>`, and `toResponse(): Response`.
+
+## The `@danmat` QUERY suite
+
+- [`@danmat/query-fetch`](https://github.com/DanMat/query-fetch) — client for the QUERY method.
+- [`@danmat/accept-query`](https://github.com/DanMat/accept-query) — parse/build/negotiate `Accept-Query`.
+- [`@danmat/query-cache`](https://github.com/DanMat/query-cache) — body-aware response caching.
+- **`@danmat/query-server`** — server-side request validation & negotiation *(you are here)*.
+
+## License
+
+[MIT](./LICENSE) © Dan Matthew

package/dist/index.cjs

@@ -0,0 +1,106 @@
+'use strict';
+
+var acceptQuery = require('@danmat/accept-query');
+
+// src/index.ts
+var QUERY_METHOD = "QUERY";
+var QueryRequestError = class _QueryRequestError extends Error {
+  name = "QueryRequestError";
+  status;
+  headers;
+  constructor(message, status, headers = {}) {
+    super(message);
+    this.status = status;
+    this.headers = headers;
+    Object.setPrototypeOf(this, _QueryRequestError.prototype);
+  }
+  /** Render this error as a JSON `Response` with the appropriate status/headers. */
+  toResponse() {
+    return new Response(JSON.stringify({ error: this.message }), {
+      status: this.status,
+      headers: { "content-type": "application/json", ...this.headers }
+    });
+  }
+};
+function isQueryRequest(request, options = {}) {
+  const { allowMethodOverride = true } = options;
+  const method = request.method.toUpperCase();
+  if (method === QUERY_METHOD) return true;
+  if (allowMethodOverride && method === "POST") {
+    return (request.headers.get("x-http-method-override") ?? "").toUpperCase() === QUERY_METHOD;
+  }
+  return false;
+}
+function acceptQueryHeader(mediaTypes) {
+  return acceptQuery.formatAcceptQuery(mediaTypes);
+}
+function isAccepted(contentType, accept) {
+  return acceptQuery.negotiateQuery(acceptQuery.formatAcceptQuery(accept), [contentType]) !== null;
+}
+function assertQueryRequest(request, options = {}) {
+  const { accept, allowMethodOverride = true } = options;
+  if (!isQueryRequest(request, { allowMethodOverride })) {
+    throw new QueryRequestError(
+      `Expected a ${QUERY_METHOD} request but received ${request.method}.`,
+      405,
+      { allow: QUERY_METHOD }
+    );
+  }
+  const contentType = request.headers.get("content-type");
+  if (!contentType) {
+    throw new QueryRequestError(
+      "A QUERY request must include a Content-Type (RFC 10008).",
+      400
+    );
+  }
+  if (accept && accept.length > 0 && !isAccepted(contentType, accept)) {
+    throw new QueryRequestError(
+      `Unsupported query media type "${contentType}".`,
+      415,
+      { "accept-query": acceptQueryHeader(accept) }
+    );
+  }
+}
+function checkQueryRequest(request, options = {}) {
+  try {
+    assertQueryRequest(request, options);
+    return null;
+  } catch (error) {
+    if (error instanceof QueryRequestError) return error.toResponse();
+    throw error;
+  }
+}
+async function readQueryJson(request) {
+  const contentType = request.headers.get("content-type") ?? "";
+  if (!/\bjson\b/i.test(contentType)) {
+    throw new QueryRequestError(
+      `Expected a JSON query body but Content-Type was "${contentType || "absent"}".`,
+      415
+    );
+  }
+  try {
+    return await request.json();
+  } catch {
+    throw new QueryRequestError("Query body is not valid JSON.", 400);
+  }
+}
+function withAcceptQuery(response, mediaTypes) {
+  const headers = new Headers(response.headers);
+  headers.set("accept-query", acceptQueryHeader(mediaTypes));
+  return new Response(response.body, {
+    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.isQueryRequest = isQueryRequest;
+exports.readQueryJson = readQueryJson;
+exports.withAcceptQuery = withAcceptQuery;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["formatAcceptQuery","negotiateQuery"],"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,OAAOA,8BAAkB,UAAU,CAAA;AACrC;AAEA,SAAS,UAAA,CAAW,aAAqB,MAAA,EAAoC;AAC3E,EAAA,OAAOC,2BAAeD,6BAAA,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.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"]}

package/dist/index.d.cts

@@ -0,0 +1,80 @@
+import { MediaRangeInput } from '@danmat/accept-query';
+
+/**
+ * @danmat/query-server
+ *
+ * Framework-agnostic server helpers for the HTTP QUERY method (RFC 10008),
+ * built on Web-standard `Request`/`Response` — so they work in Hono, Deno,
+ * Bun, Cloudflare Workers, and Node (via a web adapter).
+ *
+ * Validate incoming QUERY requests, enforce the RFC's `Content-Type`
+ * requirement, negotiate the accepted query formats, and advertise them with
+ * the `Accept-Query` response header.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc10008
+ */
+
+/** The QUERY method name. */
+declare const QUERY_METHOD = "QUERY";
+interface QueryRequestOptions {
+    /**
+     * Also accept `POST` requests carrying `X-HTTP-Method-Override: QUERY` as
+     * QUERY requests — the fallback that clients like `@danmat/query-fetch` use
+     * for servers that don't route QUERY natively. Default `true`.
+     */
+    allowMethodOverride?: boolean;
+}
+interface QueryValidationOptions extends QueryRequestOptions {
+    /**
+     * Media types this server accepts as query bodies. When provided, requests
+     * with an unsupported `Content-Type` are rejected with `415` and an
+     * `Accept-Query` header advertising these types.
+     */
+    accept?: MediaRangeInput[];
+}
+/**
+ * An error describing why a request is not a valid QUERY, carrying the HTTP
+ * status and headers that should be sent in response.
+ */
+declare class QueryRequestError extends Error {
+    name: string;
+    readonly status: number;
+    readonly headers: Record<string, string>;
+    constructor(message: string, status: number, headers?: Record<string, string>);
+    /** Render this error as a JSON `Response` with the appropriate status/headers. */
+    toResponse(): Response;
+}
+/** Whether a request should be handled as a QUERY (honoring method override). */
+declare function isQueryRequest(request: Request, options?: QueryRequestOptions): boolean;
+/** Build an `Accept-Query` header value from the media types a server accepts. */
+declare function acceptQueryHeader(mediaTypes: MediaRangeInput[]): string;
+/**
+ * Validate that `request` is a well-formed QUERY per RFC 10008. Throws a
+ * {@link QueryRequestError} (with the right HTTP status) when it isn't:
+ *
+ * - not a QUERY request → `405 Method Not Allowed` (`Allow: QUERY`)
+ * - missing `Content-Type` → `400 Bad Request`
+ * - unsupported `Content-Type` (when `accept` is given) → `415` + `Accept-Query`
+ */
+declare function assertQueryRequest(request: Request, options?: QueryValidationOptions): void;
+/**
+ * Non-throwing companion to {@link assertQueryRequest}. Returns an error
+ * `Response` to send back, or `null` if the request is valid.
+ *
+ * @example
+ * ```ts
+ * const bad = checkQueryRequest(request, { accept: ["application/json"] });
+ * if (bad) return bad;
+ * const query = await readQueryJson(request);
+ * ```
+ */
+declare function checkQueryRequest(request: Request, options?: QueryValidationOptions): Response | null;
+/**
+ * Read a QUERY request body as JSON, guarding the content type. Throws a
+ * {@link QueryRequestError} (`415` for a non-JSON type, `400` for invalid JSON).
+ */
+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;
+
+export { QUERY_METHOD, QueryRequestError, type QueryRequestOptions, type QueryValidationOptions, acceptQueryHeader, assertQueryRequest, checkQueryRequest, isQueryRequest, readQueryJson, withAcceptQuery };

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+import { MediaRangeInput } from '@danmat/accept-query';
+
+/**
+ * @danmat/query-server
+ *
+ * Framework-agnostic server helpers for the HTTP QUERY method (RFC 10008),
+ * built on Web-standard `Request`/`Response` — so they work in Hono, Deno,
+ * Bun, Cloudflare Workers, and Node (via a web adapter).
+ *
+ * Validate incoming QUERY requests, enforce the RFC's `Content-Type`
+ * requirement, negotiate the accepted query formats, and advertise them with
+ * the `Accept-Query` response header.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc10008
+ */
+
+/** The QUERY method name. */
+declare const QUERY_METHOD = "QUERY";
+interface QueryRequestOptions {
+    /**
+     * Also accept `POST` requests carrying `X-HTTP-Method-Override: QUERY` as
+     * QUERY requests — the fallback that clients like `@danmat/query-fetch` use
+     * for servers that don't route QUERY natively. Default `true`.
+     */
+    allowMethodOverride?: boolean;
+}
+interface QueryValidationOptions extends QueryRequestOptions {
+    /**
+     * Media types this server accepts as query bodies. When provided, requests
+     * with an unsupported `Content-Type` are rejected with `415` and an
+     * `Accept-Query` header advertising these types.
+     */
+    accept?: MediaRangeInput[];
+}
+/**
+ * An error describing why a request is not a valid QUERY, carrying the HTTP
+ * status and headers that should be sent in response.
+ */
+declare class QueryRequestError extends Error {
+    name: string;
+    readonly status: number;
+    readonly headers: Record<string, string>;
+    constructor(message: string, status: number, headers?: Record<string, string>);
+    /** Render this error as a JSON `Response` with the appropriate status/headers. */
+    toResponse(): Response;
+}
+/** Whether a request should be handled as a QUERY (honoring method override). */
+declare function isQueryRequest(request: Request, options?: QueryRequestOptions): boolean;
+/** Build an `Accept-Query` header value from the media types a server accepts. */
+declare function acceptQueryHeader(mediaTypes: MediaRangeInput[]): string;
+/**
+ * Validate that `request` is a well-formed QUERY per RFC 10008. Throws a
+ * {@link QueryRequestError} (with the right HTTP status) when it isn't:
+ *
+ * - not a QUERY request → `405 Method Not Allowed` (`Allow: QUERY`)
+ * - missing `Content-Type` → `400 Bad Request`
+ * - unsupported `Content-Type` (when `accept` is given) → `415` + `Accept-Query`
+ */
+declare function assertQueryRequest(request: Request, options?: QueryValidationOptions): void;
+/**
+ * Non-throwing companion to {@link assertQueryRequest}. Returns an error
+ * `Response` to send back, or `null` if the request is valid.
+ *
+ * @example
+ * ```ts
+ * const bad = checkQueryRequest(request, { accept: ["application/json"] });
+ * if (bad) return bad;
+ * const query = await readQueryJson(request);
+ * ```
+ */
+declare function checkQueryRequest(request: Request, options?: QueryValidationOptions): Response | null;
+/**
+ * Read a QUERY request body as JSON, guarding the content type. Throws a
+ * {@link QueryRequestError} (`415` for a non-JSON type, `400` for invalid JSON).
+ */
+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;
+
+export { QUERY_METHOD, QueryRequestError, type QueryRequestOptions, type QueryValidationOptions, acceptQueryHeader, assertQueryRequest, checkQueryRequest, isQueryRequest, readQueryJson, withAcceptQuery };

package/dist/index.js

@@ -0,0 +1,97 @@
+import { formatAcceptQuery, negotiateQuery } from '@danmat/accept-query';
+
+// src/index.ts
+var QUERY_METHOD = "QUERY";
+var QueryRequestError = class _QueryRequestError extends Error {
+  name = "QueryRequestError";
+  status;
+  headers;
+  constructor(message, status, headers = {}) {
+    super(message);
+    this.status = status;
+    this.headers = headers;
+    Object.setPrototypeOf(this, _QueryRequestError.prototype);
+  }
+  /** Render this error as a JSON `Response` with the appropriate status/headers. */
+  toResponse() {
+    return new Response(JSON.stringify({ error: this.message }), {
+      status: this.status,
+      headers: { "content-type": "application/json", ...this.headers }
+    });
+  }
+};
+function isQueryRequest(request, options = {}) {
+  const { allowMethodOverride = true } = options;
+  const method = request.method.toUpperCase();
+  if (method === QUERY_METHOD) return true;
+  if (allowMethodOverride && method === "POST") {
+    return (request.headers.get("x-http-method-override") ?? "").toUpperCase() === QUERY_METHOD;
+  }
+  return false;
+}
+function acceptQueryHeader(mediaTypes) {
+  return formatAcceptQuery(mediaTypes);
+}
+function isAccepted(contentType, accept) {
+  return negotiateQuery(formatAcceptQuery(accept), [contentType]) !== null;
+}
+function assertQueryRequest(request, options = {}) {
+  const { accept, allowMethodOverride = true } = options;
+  if (!isQueryRequest(request, { allowMethodOverride })) {
+    throw new QueryRequestError(
+      `Expected a ${QUERY_METHOD} request but received ${request.method}.`,
+      405,
+      { allow: QUERY_METHOD }
+    );
+  }
+  const contentType = request.headers.get("content-type");
+  if (!contentType) {
+    throw new QueryRequestError(
+      "A QUERY request must include a Content-Type (RFC 10008).",
+      400
+    );
+  }
+  if (accept && accept.length > 0 && !isAccepted(contentType, accept)) {
+    throw new QueryRequestError(
+      `Unsupported query media type "${contentType}".`,
+      415,
+      { "accept-query": acceptQueryHeader(accept) }
+    );
+  }
+}
+function checkQueryRequest(request, options = {}) {
+  try {
+    assertQueryRequest(request, options);
+    return null;
+  } catch (error) {
+    if (error instanceof QueryRequestError) return error.toResponse();
+    throw error;
+  }
+}
+async function readQueryJson(request) {
+  const contentType = request.headers.get("content-type") ?? "";
+  if (!/\bjson\b/i.test(contentType)) {
+    throw new QueryRequestError(
+      `Expected a JSON query body but Content-Type was "${contentType || "absent"}".`,
+      415
+    );
+  }
+  try {
+    return await request.json();
+  } catch {
+    throw new QueryRequestError("Query body is not valid JSON.", 400);
+  }
+}
+function withAcceptQuery(response, mediaTypes) {
+  const headers = new Headers(response.headers);
+  headers.set("accept-query", acceptQueryHeader(mediaTypes));
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+
+export { QUERY_METHOD, QueryRequestError, acceptQueryHeader, assertQueryRequest, checkQueryRequest, isQueryRequest, readQueryJson, withAcceptQuery };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"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  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"]}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@danmat/query-server",
+  "version": "0.1.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",
+    "query",
+    "query-method",
+    "rfc10008",
+    "rfc-10008",
+    "server",
+    "middleware",
+    "accept-query",
+    "hono",
+    "content-negotiation"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "Dan Matthew <dannymatthew@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DanMat/query-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DanMat/query-server/issues"
+  },
+  "homepage": "https://github.com/DanMat/query-server#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@danmat/accept-query": "^0.1.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.8",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}