@zeno-lib/query 0.0.3 → 0.1.0

package/dist/query-caller.d.mts

@@ -0,0 +1,48 @@
+import { t as QueryMap } from "./query-map-Dbbk7vtk.mjs";
+import { QueryClient } from "@tanstack/react-query";
+//#region src/query-caller.d.ts
+/** The part of TanStack's `QueryFunctionContext` a call reads. */
+export type QueryCallContext = {
+  /** Finds the queries a `QueryHydrationBoundary` bound for its server pass. */
+  client?: QueryClient;
+  /** Abandons the request when TanStack cancels the query. */
+  signal?: AbortSignal;
+};
+/** What `name` takes: its one argument, or nothing. */
+export type QueryInput<TQueries extends QueryMap, TName extends keyof TQueries> = Parameters<TQueries[TName]>[0];
+/** What `name` resolves to. */
+export type QueryData<TQueries extends QueryMap, TName extends keyof TQueries> = Awaited<ReturnType<TQueries[TName]>>;
+/** A query the route answered with an error status. */
+export declare class QueryRequestError extends Error {
+  readonly query: string;
+  readonly status: number;
+  constructor(query: string, status: number);
+}
+export type QueryCaller<TQueries extends QueryMap> = <TName extends keyof TQueries & string>(name: TName, input: QueryInput<TQueries, TName>, context?: QueryCallContext) => Promise<QueryData<TQueries, TName>>;
+/**
+ * Builds the browser side of `createQueryRoute`: `callQuery(name, input,
+ * context)` posts to `${path}/${name}` and resolves to the query's data. Type
+ * it with the map the route serves, imported as a type only, so no server code
+ * reaches the bundle:
+ *
+ * ```ts
+ * import type { queries } from "./queries"
+ *
+ * export const callQuery = createQueryCaller<typeof queries>({
+ *   path: "/api/queries",
+ * })
+ *
+ * queryFn: (context) => callQuery("selectPosts", { authorId }, context)
+ * ```
+ *
+ * Unlike a Server Function, each call is its own request, so a screen's
+ * queries run in parallel, and TanStack's `signal` cancels them. During a
+ * `QueryHydrationBoundary` prefetch, the call runs the bound server function
+ * in-process instead.
+ */
+export declare function createQueryCaller<TQueries extends QueryMap>({ path }: {
+  /** Where the route is mounted, without the trailing name segment. */
+  path: string;
+}): QueryCaller<TQueries>;
+//#endregion
+export type { QueryMap };

package/dist/query-caller.mjs

@@ -0,0 +1,71 @@
+import { i as getBoundQueries, r as findQuery, t as QUERY_CONTENT_TYPE } from "./query-map-XxynJ3jl.mjs";
+import { parse, stringify } from "devalue";
+//#region src/query-caller.ts
+/** A query the route answered with an error status. */
+var QueryRequestError = class extends Error {
+	constructor(query, status) {
+		super(`Query ${query} failed with status ${status}`);
+		this.name = "QueryRequestError";
+		this.query = query;
+		this.status = status;
+	}
+};
+/**
+* Builds the browser side of `createQueryRoute`: `callQuery(name, input,
+* context)` posts to `${path}/${name}` and resolves to the query's data. Type
+* it with the map the route serves, imported as a type only, so no server code
+* reaches the bundle:
+*
+* ```ts
+* import type { queries } from "./queries"
+*
+* export const callQuery = createQueryCaller<typeof queries>({
+*   path: "/api/queries",
+* })
+*
+* queryFn: (context) => callQuery("selectPosts", { authorId }, context)
+* ```
+*
+* Unlike a Server Function, each call is its own request, so a screen's
+* queries run in parallel, and TanStack's `signal` cancels them. During a
+* `QueryHydrationBoundary` prefetch, the call runs the bound server function
+* in-process instead.
+*/
+function createQueryCaller({ path }) {
+	return async (name, input, context = {}) => {
+		const bound = context.client && getBoundQueries(context.client);
+		if (bound) {
+			const query = findQuery(bound, name);
+			if (!query) throw new Error(`callQuery: "${name}" is not in the queries bound to this QueryHydrationBoundary`);
+			return await query(input);
+		}
+		if (typeof window === "undefined") throw new Error(`callQuery: "${name}" ran on the server outside a QueryHydrationBoundary that binds its queries`);
+		const response = await fetch(`${path}/${encodeURIComponent(name)}`, {
+			body: stringify(input),
+			headers: { "content-type": QUERY_CONTENT_TYPE },
+			method: "POST",
+			redirect: "manual",
+			signal: context.signal
+		});
+		if (response.type === "opaqueredirect") {
+			reloadOnce();
+			throw new QueryRequestError(name, 401);
+		}
+		if (!(response.ok && response.headers.get("content-type")?.startsWith("application/json"))) throw new QueryRequestError(name, response.status);
+		return parse(await response.text());
+	};
+}
+const RELOADED_AT_KEY = "zeno-query:reloaded-at";
+/**
+* Reloads the page, unless a redirect already did within the last minute: a
+* redirect the reload does not clear (a trailing-slash rule, a middleware that
+* redirects only API paths) would otherwise reload forever.
+*/
+function reloadOnce() {
+	const reloadedAt = Number(sessionStorage.getItem(RELOADED_AT_KEY));
+	if (Date.now() - reloadedAt < 6e4) return;
+	sessionStorage.setItem(RELOADED_AT_KEY, String(Date.now()));
+	window.location.reload();
+}
+//#endregion
+export { QueryRequestError, createQueryCaller };

package/dist/query-hydration-boundary.d.mts

@@ -1,3 +1,4 @@
+import { t as QueryMap } from "./query-map-Dbbk7vtk.mjs";
 import { DehydrateOptions, QueryClient } from "@tanstack/react-query";
 import { ReactNode } from "react";
 //#region src/query-hydration-boundary.d.ts
@@ -17,6 +18,11 @@ export type QueryHydrationBoundaryProps = {
   createQueryClient?: () => QueryClient;
   /** Forwarded to TanStack's `dehydrate` (e.g. to also dehydrate pending queries). */
   dehydrateOptions?: DehydrateOptions;
+  /**
+   * The map your query route serves. A `queryFn` built on `createQueryCaller` then calls these
+   * functions in-process during `prefetch`, since the server has no URL to fetch them from.
+   */
+  queries?: QueryMap;
 };
 /**
  * Async **server component**: runs `prefetch` against a fresh `QueryClient` and dehydrates the
@@ -32,5 +38,5 @@ export type QueryHydrationBoundaryProps = {
  * </QueryHydrationBoundary>
  * ```
  */
-export declare function QueryHydrationBoundary({ children, createQueryClient, dehydrateOptions, prefetch }: QueryHydrationBoundaryProps): Promise<import("react").JSX.Element>;
+export declare function QueryHydrationBoundary({ children, createQueryClient, dehydrateOptions, prefetch, queries }: QueryHydrationBoundaryProps): Promise<import("react").JSX.Element>;
 //#endregion

package/dist/query-hydration-boundary.mjs

@@ -1,4 +1,5 @@
 import { PrefetchedQueries } from "./prefetched-queries.mjs";
+import { n as bindQueries } from "./query-map-XxynJ3jl.mjs";
 import { QueryClient, dehydrate } from "@tanstack/react-query";
 import { jsx } from "react/jsx-runtime";
 //#region src/query-hydration-boundary.tsx
@@ -16,8 +17,9 @@ import { jsx } from "react/jsx-runtime";
 * </QueryHydrationBoundary>
 * ```
 */
-async function QueryHydrationBoundary({ children, createQueryClient = () => new QueryClient(), dehydrateOptions, prefetch }) {
+async function QueryHydrationBoundary({ children, createQueryClient = () => new QueryClient(), dehydrateOptions, prefetch, queries }) {
 	const queryClient = createQueryClient();
+	if (queries) bindQueries(queryClient, queries);
 	await prefetch(queryClient);
 	return /* @__PURE__ */ jsx(PrefetchedQueries, {
 		state: dehydrate(queryClient, dehydrateOptions),

package/dist/query-map-Dbbk7vtk.d.mts

@@ -0,0 +1,9 @@
+import { QueryClient } from "@tanstack/react-query";
+//#region src/query-map.d.ts
+/**
+ * The server functions a query route serves, keyed by the name the browser
+ * calls them by. Each takes one argument and resolves to the query's data.
+ */
+type QueryMap = Record<string, (input: any) => Promise<unknown>>;
+//#endregion
+export { QueryMap as t };

package/dist/query-map-XxynJ3jl.mjs

@@ -0,0 +1,26 @@
+//#region src/query-map.ts
+/**
+* The function `queries` serves as `name`. `Object.hasOwn`, so `constructor` or
+* `__proto__` is not a query, and the type check, so a module namespace's
+* `__esModule` flag is not one either.
+*/
+function findQuery(queries, name) {
+	const query = Object.hasOwn(queries, name) ? queries[name] : void 0;
+	return typeof query === "function" ? query : void 0;
+}
+/** The body type both ways; the route refuses any other. */
+const QUERY_CONTENT_TYPE = "application/json";
+/**
+* The queries bound to a server `QueryClient`. A query function that runs
+* against that client calls the server function in-process instead of going
+* through the route, which a server render has no URL for.
+*/
+const boundQueries = /* @__PURE__ */ new WeakMap();
+function bindQueries(client, queries) {
+	boundQueries.set(client, queries);
+}
+function getBoundQueries(client) {
+	return boundQueries.get(client);
+}
+//#endregion
+export { getBoundQueries as i, bindQueries as n, findQuery as r, QUERY_CONTENT_TYPE as t };

package/dist/query-route.d.mts

@@ -0,0 +1,23 @@
+import { t as QueryMap } from "./query-map-Dbbk7vtk.mjs";
+//#region src/query-route.d.ts
+/**
+ * Builds the `POST` handler of a route that serves `queries` to the browser,
+ * one request per call, so the reads of a screen run in parallel. Mount it on a
+ * dynamic segment whose last part is the query's name:
+ *
+ * ```ts
+ * // app/api/queries/[query]/route.ts
+ * export const { POST } = createQueryRoute(queries)
+ * ```
+ *
+ * The body and the result travel through `devalue`, so a `Date`, a `Map`, a
+ * `bigint` or an `undefined` arrives as it was sent. An error the query throws
+ * is left to the framework, which answers 500 and reports it. Every entry of
+ * `queries` is a public endpoint: authorize inside it, as you would in a
+ * server action.
+ */
+export declare function createQueryRoute(queries: QueryMap): {
+  POST: (request: Request) => Promise<Response>;
+};
+//#endregion
+export type { QueryMap };

package/dist/query-route.mjs

@@ -0,0 +1,54 @@
+import { r as findQuery, t as QUERY_CONTENT_TYPE } from "./query-map-XxynJ3jl.mjs";
+import { parse, stringify } from "devalue";
+//#region src/query-route.ts
+/** The largest body the route parses, the default Server Functions accept. */
+const MAX_BODY_BYTES = 1048576;
+const TRAILING_SLASH = /\/$/;
+/**
+* Builds the `POST` handler of a route that serves `queries` to the browser,
+* one request per call, so the reads of a screen run in parallel. Mount it on a
+* dynamic segment whose last part is the query's name:
+*
+* ```ts
+* // app/api/queries/[query]/route.ts
+* export const { POST } = createQueryRoute(queries)
+* ```
+*
+* The body and the result travel through `devalue`, so a `Date`, a `Map`, a
+* `bigint` or an `undefined` arrives as it was sent. An error the query throws
+* is left to the framework, which answers 500 and reports it. Every entry of
+* `queries` is a public endpoint: authorize inside it, as you would in a
+* server action.
+*/
+function createQueryRoute(queries) {
+	return { POST: async (request) => {
+		const query = findQuery(queries, queryName(request));
+		if (!query) return new Response(null, { status: 404 });
+		if (!request.headers.get("content-type")?.startsWith("application/json")) return new Response(null, { status: 415 });
+		if (Number(request.headers.get("content-length")) > MAX_BODY_BYTES) return new Response(null, { status: 413 });
+		const body = await request.text();
+		if (body.length > MAX_BODY_BYTES) return new Response(null, { status: 413 });
+		let input;
+		try {
+			input = parse(body);
+		} catch {
+			return new Response(null, { status: 400 });
+		}
+		const data = await query(input);
+		return new Response(stringify(data), { headers: {
+			"cache-control": "private, no-store",
+			"content-type": QUERY_CONTENT_TYPE
+		} });
+	} };
+}
+/** The path's last segment, or `""` when it is not a valid escape. */
+function queryName(request) {
+	const segment = new URL(request.url).pathname.replace(TRAILING_SLASH, "").split("/").at(-1);
+	try {
+		return decodeURIComponent(segment ?? "");
+	} catch {
+		return "";
+	}
+}
+//#endregion
+export { createQueryRoute };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeno-lib/query",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "repository": {
     "url": "https://github.com/zeno-lib/zeno.git",
     "directory": "packages/query"
@@ -17,11 +17,21 @@
       "import": "./dist/query-defaults.mjs",
       "default": "./dist/query-defaults.mjs"
     },
+    "./query-caller": {
+      "types": "./dist/query-caller.d.mts",
+      "import": "./dist/query-caller.mjs",
+      "default": "./dist/query-caller.mjs"
+    },
     "./query-hydration-boundary": {
       "types": "./dist/query-hydration-boundary.d.mts",
       "import": "./dist/query-hydration-boundary.mjs",
       "default": "./dist/query-hydration-boundary.mjs"
     },
+    "./query-route": {
+      "types": "./dist/query-route.d.mts",
+      "import": "./dist/query-route.mjs",
+      "default": "./dist/query-route.mjs"
+    },
     "./query-suspense": {
       "types": "./dist/query-suspense.d.mts",
       "import": "./dist/query-suspense.mjs",
@@ -36,13 +46,16 @@
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "devalue": "^6.0.3"
+  },
   "devDependencies": {
     "@tanstack/react-query": "^5.104.1",
     "@types/node": "26.6.4",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
     "@zeno-lib/test": "^0.1.1",
-    "@zeno-lib/typescript": "^1.1.0",
+    "@zeno-lib/typescript": "^1.2.0",
     "@zeno-lib/ui": "^0.0.1",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
@@ -52,7 +65,7 @@
     "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "@tanstack/react-query": ">=5",
+    "@tanstack/react-query": ">=5.66.0",
     "react": ">=19"
   },
   "publishConfig": {