@zeno-lib/query 0.0.3 → 0.1.1

package/dist/prefetched-queries.d.mts

@@ -1,6 +1,5 @@
 import { DehydratedState } from "@tanstack/react-query";
 import { ReactNode } from "react";
-//#region src/prefetched-queries.d.ts
 /** Whether the nearest `PrefetchedQueries` above was handed at least one dehydrated query. */
 export declare function useHasPrefetchedQueries(): boolean;
 export type PrefetchedQueriesProps = {
@@ -12,5 +11,4 @@ export type PrefetchedQueriesProps = {
  * render** (on the server pass as well as in the browser), so a `useSuspenseQuery` below it
  * resolves synchronously in both and the two passes produce the same markup.
  */
-export declare function PrefetchedQueries({ children, state }: PrefetchedQueriesProps): import("react").JSX.Element;
-//#endregion
+export declare function PrefetchedQueries({ children, state }: PrefetchedQueriesProps): import("react").JSX.Element;

package/dist/prefetched-queries.mjs

@@ -2,7 +2,7 @@
 import { HydrationBoundary } from "@tanstack/react-query";
 import { createContext, useContext } from "react";
 import { jsx } from "react/jsx-runtime";
-//#region src/prefetched-queries.tsx
+// src/prefetched-queries.tsx
 /**
 * True inside a subtree that was handed a filled dehydrated cache.
 *
@@ -33,5 +33,4 @@ function PrefetchedQueries({ children, state }) {
 		})
 	});
 }
-//#endregion
 export { PrefetchedQueries, useHasPrefetchedQueries };

package/dist/query-caller.d.mts

@@ -0,0 +1,46 @@
+import { t as QueryMap } from "./query-map-Catubr0X.mjs";
+import { QueryClient } from "@tanstack/react-query";
+/** 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>;
+export type { QueryMap };

package/dist/query-caller.mjs

@@ -0,0 +1,70 @@
+import { i as getBoundQueries, r as findQuery, t as QUERY_CONTENT_TYPE } from "./query-map-DD9UrwSx.mjs";
+import { parse, stringify } from "devalue";
+// 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();
+}
+export { QueryRequestError, createQueryCaller };

package/dist/query-defaults.d.mts

@@ -1,4 +1,3 @@
-//#region src/query-defaults.d.ts
 /**
  * Timing presets to spread as the first property of a `queryOptions(…)` call, so freshness stays
  * consistent across a codebase instead of every query inventing its own `staleTime`.
@@ -36,5 +35,4 @@ export declare const cachedQueryDefaults: {
 /** Effectively immutable data: never stale. */
 export declare const staticQueryDefaults: {
   readonly staleTime: number;
-};
-//#endregion
+};

package/dist/query-defaults.mjs

@@ -1,4 +1,4 @@
-//#region src/query-defaults.ts
+// src/query-defaults.ts
 /**
 * Timing presets to spread as the first property of a `queryOptions(…)` call, so freshness stays
 * consistent across a codebase instead of every query inventing its own `staleTime`.
@@ -33,5 +33,4 @@ const cachedQueryDefaults = {
 };
 /** Effectively immutable data: never stale. */
 const staticQueryDefaults = { staleTime: Number.POSITIVE_INFINITY };
-//#endregion
 export { cachedQueryDefaults, liveBackgroundQueryDefaults, liveQueryDefaults, longLivedQueryDefaults, shortLivedQueryDefaults, staticQueryDefaults };

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

@@ -1,6 +1,6 @@
+import { t as QueryMap } from "./query-map-Catubr0X.mjs";
 import { DehydrateOptions, QueryClient } from "@tanstack/react-query";
 import { ReactNode } from "react";
-//#region src/query-hydration-boundary.d.ts
 export type QueryHydrationBoundaryProps = {
   children: ReactNode;
   /**
@@ -17,6 +17,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 +37,4 @@ export type QueryHydrationBoundaryProps = {
  * </QueryHydrationBoundary>
  * ```
  */
-export declare function QueryHydrationBoundary({ children, createQueryClient, dehydrateOptions, prefetch }: QueryHydrationBoundaryProps): Promise<import("react").JSX.Element>;
-//#endregion
+export declare function QueryHydrationBoundary({ children, createQueryClient, dehydrateOptions, prefetch, queries }: QueryHydrationBoundaryProps): Promise<import("react").JSX.Element>;

package/dist/query-hydration-boundary.mjs

@@ -1,7 +1,8 @@
 import { PrefetchedQueries } from "./prefetched-queries.mjs";
+import { n as bindQueries } from "./query-map-DD9UrwSx.mjs";
 import { QueryClient, dehydrate } from "@tanstack/react-query";
 import { jsx } from "react/jsx-runtime";
-//#region src/query-hydration-boundary.tsx
+// src/query-hydration-boundary.tsx
 /**
 * Async **server component**: runs `prefetch` against a fresh `QueryClient` and dehydrates the
 * result into `PrefetchedQueries`, so the suspense queries below resolve from the cache in the
@@ -16,13 +17,13 @@ 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),
 		children
 	});
 }
-//#endregion
 export { QueryHydrationBoundary };

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

@@ -0,0 +1,7 @@
+import { QueryClient } from "@tanstack/react-query";
+/**
+ * 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>>;
+export { QueryMap as t };

package/dist/query-map-DD9UrwSx.mjs

@@ -0,0 +1,25 @@
+// 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);
+}
+export { getBoundQueries as i, bindQueries as n, findQuery as r, QUERY_CONTENT_TYPE as t };

package/dist/query-route.d.mts

@@ -0,0 +1,21 @@
+import { t as QueryMap } from "./query-map-Catubr0X.mjs";
+/**
+ * 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>;
+};
+export type { QueryMap };

package/dist/query-route.mjs

@@ -0,0 +1,53 @@
+import { r as findQuery, t as QUERY_CONTENT_TYPE } from "./query-map-DD9UrwSx.mjs";
+import { parse, stringify } from "devalue";
+// src/query-route.ts
+/** The largest body the route parses, the default Server Functions accept. */
+const MAX_BODY_BYTES = 1048576;
+const TRAILING_SLASH = /\/$/u;
+/**
+* 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 "";
+	}
+}
+export { createQueryRoute };

package/dist/query-suspense-loading.d.mts

@@ -1,10 +1,8 @@
 import { ComponentPropsWithoutRef } from "react";
-//#region src/query-suspense-loading.d.ts
 export type QuerySuspenseLoadingProps = ComponentPropsWithoutRef<"div">;
 /**
  * Single layout root for Suspense loading UI: set `className` and children here so `aria-busy` /
  * `aria-live` apply to the same element as your skeleton stack (no inner wrapper div). Accepts
  * all `div` props; the `aria-busy` and `aria-live` defaults can be overridden.
  */
-export declare function QuerySuspenseLoading({ "aria-busy": ariaBusy, "aria-live": ariaLive, children, ...props }: QuerySuspenseLoadingProps): import("react").JSX.Element;
-//#endregion
+export declare function QuerySuspenseLoading({ "aria-busy": ariaBusy, "aria-live": ariaLive, children, ...props }: QuerySuspenseLoadingProps): import("react").JSX.Element;

package/dist/query-suspense-loading.mjs

@@ -1,5 +1,5 @@
 import { jsx } from "react/jsx-runtime";
-//#region src/query-suspense-loading.tsx
+// src/query-suspense-loading.tsx
 /**
 * Single layout root for Suspense loading UI: set `className` and children here so `aria-busy` /
 * `aria-live` apply to the same element as your skeleton stack (no inner wrapper div). Accepts
@@ -13,5 +13,4 @@ function QuerySuspenseLoading({ "aria-busy": ariaBusy = true, "aria-live": ariaL
 		children
 	});
 }
-//#endregion
 export { QuerySuspenseLoading };

package/dist/query-suspense.d.mts

@@ -1,5 +1,4 @@
 import { ReactNode } from "react";
-//#region src/query-suspense.d.ts
 export type QuerySuspenseErrorFallbackProps = {
   error: Error;
   onRetry: () => void;
@@ -25,5 +24,4 @@ export type QuerySuspenseProps = {
  * hydration gate: `fallback` is all it renders on the server and through hydration, unless a
  * `PrefetchedQueries` (e.g. from `QueryHydrationBoundary`) above it was handed dehydrated queries.
  */
-export declare function QuerySuspense({ children, errorFallback, fallback, debugState }: QuerySuspenseProps): import("react").JSX.Element;
-//#endregion
+export declare function QuerySuspense({ children, errorFallback, fallback, debugState }: QuerySuspenseProps): import("react").JSX.Element;

package/dist/query-suspense.mjs

@@ -3,7 +3,7 @@ import { useHasPrefetchedQueries } from "./prefetched-queries.mjs";
 import { QueryErrorResetBoundary } from "@tanstack/react-query";
 import { Component, Suspense, useSyncExternalStore } from "react";
 import { Fragment, jsx } from "react/jsx-runtime";
-//#region src/query-suspense.tsx
+// src/query-suspense.tsx
 const debugStateEnabled = process.env.NODE_ENV !== "production";
 const subscribeToNothing = () => () => {};
 const useIsHydrated = () => useSyncExternalStore(subscribeToNothing, () => true, () => false);
@@ -59,5 +59,4 @@ function QuerySuspense({ children, errorFallback, fallback, debugState }) {
 		})
 	}) });
 }
-//#endregion
 export { QuerySuspense };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeno-lib/query",
-  "version": "0.0.3",
+  "version": "0.1.1",
   "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,23 +46,26 @@
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "devalue": "^6.0.3"
+  },
   "devDependencies": {
-    "@tanstack/react-query": "^5.104.1",
-    "@types/node": "26.6.4",
+    "@tanstack/react-query": "^5.105.0",
+    "@types/node": "26.6.5",
     "@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/test": "^0.1.2",
+    "@zeno-lib/typescript": "^1.2.0",
     "@zeno-lib/ui": "^0.0.1",
-    "react": "^19.3.0",
-    "react-dom": "^19.3.0",
-    "tsdown": "^0.23.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "tsdown": "^0.23.1",
     "typescript": "7.0.2",
-    "vite": "8.3.3",
-    "vitest": "5.0.3"
+    "vite": "8.3.5",
+    "vitest": "5.0.5"
   },
   "peerDependencies": {
-    "@tanstack/react-query": ">=5",
+    "@tanstack/react-query": ">=5.66.0",
     "react": ">=19"
   },
   "publishConfig": {