@queryweave/server 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QueryWeave contributors
+
+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,15 @@
+# `@queryweave/server`
+
+Web-standard helpers for request-scoped query state.
+
+```ts
+import { createQueryUrl, encodeQuery, readRequestQuery, readUrlQuery } from "@queryweave/server";
+
+readUrlQuery("https://example.test/products?page=3", productFilters);
+readRequestQuery(request, productFilters);
+encodeQuery(productFilters, values);
+createQueryUrl("https://example.test/products", productFilters, values);
+```
+
+Every helper is a pure function over `URL` and `Request`. There is no stored state, so request data
+cannot leak between calls, and no Node.js built-in, browser history, or frontend framework is used.

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { DecodeResult, QueryModel, QueryModelValues, QueryParamDefinitions, QuerySource } from "@queryweave/core";
+//#region src/index.d.ts
+/**
+ * Web-standard helpers for request-scoped query state.
+ *
+ * Everything here is a pure function over `URL` and `Request`. There is no runtime state, no
+ * navigation, and no framework coupling, so the same helpers work in Node.js, edge, and worker
+ * runtimes.
+ */
+/** Base used when a relative URL string is supplied. */
+declare const relativeUrlBase = "http://queryweave.invalid";
+/** A read-only source backed by a web-standard `Request`. */
+interface WebRequestQuerySource extends QuerySource {
+  readonly request: Request;
+}
+/** Decode the query of a URL or URL-like string with a model. */
+declare function readUrlQuery<TDefs extends QueryParamDefinitions>(url: string | URL, model: QueryModel<TDefs>): DecodeResult<QueryModelValues<TDefs>>;
+/** Decode the query of a URL or URL-like string, awaiting asynchronous validation. */
+declare function readUrlQueryAsync<TDefs extends QueryParamDefinitions>(url: string | URL, model: QueryModel<TDefs>): Promise<DecodeResult<QueryModelValues<TDefs>>>;
+/** Decode the query of a web-standard request with a model. */
+declare function readRequestQuery<TDefs extends QueryParamDefinitions>(request: Request, model: QueryModel<TDefs>): DecodeResult<QueryModelValues<TDefs>>;
+/** Decode the query of a web-standard request, awaiting asynchronous validation. */
+declare function readRequestQueryAsync<TDefs extends QueryParamDefinitions>(request: Request, model: QueryModel<TDefs>): Promise<DecodeResult<QueryModelValues<TDefs>>>;
+/** Create a request-scoped read-only source for a web-standard request. */
+declare function createRequestQuerySource(request: Request): WebRequestQuerySource;
+/** Encode typed state into a canonical query string without a leading `?`. */
+declare function encodeQuery<TDefs extends QueryParamDefinitions>(model: QueryModel<TDefs>, value: QueryModelValues<TDefs>): string;
+/**
+ * Build a URL that carries the model's canonical query.
+ *
+ * Query keys the model does not manage are preserved from `base`, in their original order, after
+ * the managed keys.
+ */
+declare function createQueryUrl<TDefs extends QueryParamDefinitions>(base: string | URL, model: QueryModel<TDefs>, value: QueryModelValues<TDefs>): URL;
+//#endregion
+export { WebRequestQuerySource, createQueryUrl, createRequestQuerySource, encodeQuery, readRequestQuery, readRequestQueryAsync, readUrlQuery, readUrlQueryAsync, relativeUrlBase };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;;;cAqBa;;UAGI,8BAA8B;WACpC,SAAS;;;iBAeJ,aAAa,cAAc,uBACzC,cAAc,KACd,OAAO,WAAW,SACjB,aAAa,iBAAiB;;iBAKX,kBAAkB,cAAc,uBACpD,cAAc,KACd,OAAO,WAAW,SACjB,QAAQ,aAAa,iBAAiB;;iBAKzB,iBAAiB,cAAc,uBAC7C,SAAS,SACT,OAAO,WAAW,SACjB,aAAa,iBAAiB;;iBAKX,sBAAsB,cAAc,uBACxD,SAAS,SACT,OAAO,WAAW,SACjB,QAAQ,aAAa,iBAAiB;;iBAKzB,yBAAyB,SAAS,UAAU;;iBAQ5C,YAAY,cAAc,uBACxC,OAAO,WAAW,QAClB,OAAO,iBAAiB;;;;;;;iBAWV,eAAe,cAAc,uBAC3C,eAAe,KACf,OAAO,WAAW,QAClB,OAAO,iBAAiB,SACvB"}

package/dist/index.js

@@ -0,0 +1,64 @@
+import { formatQueryString, normalizeQueryEntries } from "@queryweave/core";
+
+//#region src/index.ts
+/**
+* Web-standard helpers for request-scoped query state.
+*
+* Everything here is a pure function over `URL` and `Request`. There is no runtime state, no
+* navigation, and no framework coupling, so the same helpers work in Node.js, edge, and worker
+* runtimes.
+*/
+/** Base used when a relative URL string is supplied. */
+const relativeUrlBase = "http://queryweave.invalid";
+function toUrl(url) {
+	if (typeof url !== "string") return url;
+	try {
+		return new URL(url);
+	} catch {
+		return new URL(url, relativeUrlBase);
+	}
+}
+/** Decode the query of a URL or URL-like string with a model. */
+function readUrlQuery(url, model) {
+	return model.decode(toUrl(url).search);
+}
+/** Decode the query of a URL or URL-like string, awaiting asynchronous validation. */
+async function readUrlQueryAsync(url, model) {
+	return model.decodeAsync(toUrl(url).search);
+}
+/** Decode the query of a web-standard request with a model. */
+function readRequestQuery(request, model) {
+	return readUrlQuery(request.url, model);
+}
+/** Decode the query of a web-standard request, awaiting asynchronous validation. */
+async function readRequestQueryAsync(request, model) {
+	return readUrlQueryAsync(request.url, model);
+}
+/** Create a request-scoped read-only source for a web-standard request. */
+function createRequestQuerySource(request) {
+	return {
+		request,
+		read: () => toUrl(request.url).search
+	};
+}
+/** Encode typed state into a canonical query string without a leading `?`. */
+function encodeQuery(model, value) {
+	return formatQueryString(model.encode(value));
+}
+/**
+* Build a URL that carries the model's canonical query.
+*
+* Query keys the model does not manage are preserved from `base`, in their original order, after
+* the managed keys.
+*/
+function createQueryUrl(base, model, value) {
+	const target = new URL(toUrl(base).href);
+	const managedKeys = new Set(model.keys());
+	const unmanaged = normalizeQueryEntries(target.search).filter(([key]) => !managedKeys.has(key));
+	target.search = formatQueryString([...model.encode(value), ...unmanaged]);
+	return target;
+}
+
+//#endregion
+export { createQueryUrl, createRequestQuerySource, encodeQuery, readRequestQuery, readRequestQueryAsync, readUrlQuery, readUrlQueryAsync, relativeUrlBase };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import {\n  formatQueryString,\n  normalizeQueryEntries,\n  type DecodeResult,\n  type QueryEntry,\n  type QueryModel,\n  type QueryModelValues,\n  type QueryOutput,\n  type QueryParamDefinitions,\n  type QuerySource,\n} from \"@queryweave/core\";\n\n/**\n * Web-standard helpers for request-scoped query state.\n *\n * Everything here is a pure function over `URL` and `Request`. There is no runtime state, no\n * navigation, and no framework coupling, so the same helpers work in Node.js, edge, and worker\n * runtimes.\n */\n\n/** Base used when a relative URL string is supplied. */\nexport const relativeUrlBase = \"http://queryweave.invalid\";\n\n/** A read-only source backed by a web-standard `Request`. */\nexport interface WebRequestQuerySource extends QuerySource {\n  readonly request: Request;\n}\n\nfunction toUrl(url: string | URL): URL {\n  if (typeof url !== \"string\") {\n    return url;\n  }\n  try {\n    return new URL(url);\n  } catch {\n    return new URL(url, relativeUrlBase);\n  }\n}\n\n/** Decode the query of a URL or URL-like string with a model. */\nexport function readUrlQuery<TDefs extends QueryParamDefinitions>(\n  url: string | URL,\n  model: QueryModel<TDefs>,\n): DecodeResult<QueryModelValues<TDefs>> {\n  return model.decode(toUrl(url).search);\n}\n\n/** Decode the query of a URL or URL-like string, awaiting asynchronous validation. */\nexport async function readUrlQueryAsync<TDefs extends QueryParamDefinitions>(\n  url: string | URL,\n  model: QueryModel<TDefs>,\n): Promise<DecodeResult<QueryModelValues<TDefs>>> {\n  return model.decodeAsync(toUrl(url).search);\n}\n\n/** Decode the query of a web-standard request with a model. */\nexport function readRequestQuery<TDefs extends QueryParamDefinitions>(\n  request: Request,\n  model: QueryModel<TDefs>,\n): DecodeResult<QueryModelValues<TDefs>> {\n  return readUrlQuery(request.url, model);\n}\n\n/** Decode the query of a web-standard request, awaiting asynchronous validation. */\nexport async function readRequestQueryAsync<TDefs extends QueryParamDefinitions>(\n  request: Request,\n  model: QueryModel<TDefs>,\n): Promise<DecodeResult<QueryModelValues<TDefs>>> {\n  return readUrlQueryAsync(request.url, model);\n}\n\n/** Create a request-scoped read-only source for a web-standard request. */\nexport function createRequestQuerySource(request: Request): WebRequestQuerySource {\n  return {\n    request,\n    read: () => toUrl(request.url).search,\n  };\n}\n\n/** Encode typed state into a canonical query string without a leading `?`. */\nexport function encodeQuery<TDefs extends QueryParamDefinitions>(\n  model: QueryModel<TDefs>,\n  value: QueryModelValues<TDefs>,\n): string {\n  return formatQueryString(model.encode(value));\n}\n\n/**\n * Build a URL that carries the model's canonical query.\n *\n * Query keys the model does not manage are preserved from `base`, in their original order, after\n * the managed keys.\n */\nexport function createQueryUrl<TDefs extends QueryParamDefinitions>(\n  base: string | URL,\n  model: QueryModel<TDefs>,\n  value: QueryModelValues<TDefs>,\n): URL {\n  const target = new URL(toUrl(base).href);\n  const managedKeys = new Set<string>(model.keys());\n  const unmanaged: QueryEntry[] = normalizeQueryEntries(target.search).filter(\n    ([key]) => !managedKeys.has(key),\n  );\n  const output: QueryOutput = [...model.encode(value), ...unmanaged];\n  target.search = formatQueryString(output);\n  return target;\n}\n"],"mappings":";;;;;;;;;;;AAqBA,MAAa,kBAAkB;AAO/B,SAAS,MAAM,KAAwB;CACrC,IAAI,OAAO,QAAQ,UACjB,OAAO;CAET,IAAI;EACF,OAAO,IAAI,IAAI,GAAG;CACpB,QAAQ;EACN,OAAO,IAAI,IAAI,KAAK,eAAe;CACrC;AACF;;AAGA,SAAgB,aACd,KACA,OACuC;CACvC,OAAO,MAAM,OAAO,MAAM,GAAG,CAAC,CAAC,MAAM;AACvC;;AAGA,eAAsB,kBACpB,KACA,OACgD;CAChD,OAAO,MAAM,YAAY,MAAM,GAAG,CAAC,CAAC,MAAM;AAC5C;;AAGA,SAAgB,iBACd,SACA,OACuC;CACvC,OAAO,aAAa,QAAQ,KAAK,KAAK;AACxC;;AAGA,eAAsB,sBACpB,SACA,OACgD;CAChD,OAAO,kBAAkB,QAAQ,KAAK,KAAK;AAC7C;;AAGA,SAAgB,yBAAyB,SAAyC;CAChF,OAAO;EACL;EACA,YAAY,MAAM,QAAQ,GAAG,CAAC,CAAC;CACjC;AACF;;AAGA,SAAgB,YACd,OACA,OACQ;CACR,OAAO,kBAAkB,MAAM,OAAO,KAAK,CAAC;AAC9C;;;;;;;AAQA,SAAgB,eACd,MACA,OACA,OACK;CACL,MAAM,SAAS,IAAI,IAAI,MAAM,IAAI,CAAC,CAAC,IAAI;CACvC,MAAM,cAAc,IAAI,IAAY,MAAM,KAAK,CAAC;CAChD,MAAM,YAA0B,sBAAsB,OAAO,MAAM,CAAC,CAAC,QAClE,CAAC,SAAS,CAAC,YAAY,IAAI,GAAG,CACjC;CAEA,OAAO,SAAS,kBAAkB,CADL,GAAG,MAAM,OAAO,KAAK,GAAG,GAAG,SACjB,CAAC;CACxC,OAAO;AACT"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@queryweave/server",
+  "version": "0.1.0-alpha.1",
+  "description": "Web-standard server contracts for QueryWeave.",
+  "keywords": [
+    "query",
+    "server",
+    "state",
+    "url",
+    "web-standard"
+  ],
+  "homepage": "https://github.com/boussadjra/queryweave#readme",
+  "bugs": {
+    "url": "https://github.com/boussadjra/queryweave/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boussadjra/queryweave.git",
+    "directory": "packages/server"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@queryweave/core": "0.1.0-alpha.1"
+  },
+  "devDependencies": {
+    "@queryweave/typescript-config": "0.0.0"
+  },
+  "engines": {
+    "node": ">=24.18.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc -p tsconfig.json",
+    "test:types": "tsc -p tsconfig.json",
+    "package:check": "publint --strict && attw --pack . --profile esm-only",
+    "clean": "node ../../scripts/clean-package.mjs"
+  }
+}