@zeno-lib/query 0.0.2 → 0.1.0

package/dist/prefetched-queries.d.mts

@@ -2,8 +2,8 @@ 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. */
-declare function useHasPrefetchedQueries(): boolean;
-type PrefetchedQueriesProps = {
+export declare function useHasPrefetchedQueries(): boolean;
+export type PrefetchedQueriesProps = {
   children: ReactNode;
   state: DehydratedState;
 };
@@ -12,6 +12,5 @@ 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.
  */
-declare function PrefetchedQueries({ children, state }: PrefetchedQueriesProps): import("react/jsx-runtime").JSX.Element;
-//#endregion
-export { PrefetchedQueries, PrefetchedQueriesProps, useHasPrefetchedQueries };
+export declare function PrefetchedQueries({ children, state }: PrefetchedQueriesProps): import("react").JSX.Element;
+//#endregion

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-defaults.d.mts

@@ -10,32 +10,31 @@
  * Every duration is in milliseconds.
  */
 /** Fast-moving data that keeps updating even while the tab is hidden: 15 s, refetched in the background. */
-declare const liveBackgroundQueryDefaults: {
+export declare const liveBackgroundQueryDefaults: {
   readonly refetchInterval: number;
   readonly refetchIntervalInBackground: true;
   readonly staleTime: number;
 };
 /** Fast-moving data refreshed while it is on screen: 30 s. */
-declare const liveQueryDefaults: {
+export declare const liveQueryDefaults: {
   readonly refetchInterval: number;
   readonly staleTime: number;
 };
 /** Data that can be slightly stale: 1 min. */
-declare const shortLivedQueryDefaults: {
+export declare const shortLivedQueryDefaults: {
   readonly staleTime: number;
 };
 /** Slower-changing detail data: 2 min. */
-declare const longLivedQueryDefaults: {
+export declare const longLivedQueryDefaults: {
   readonly staleTime: number;
 };
 /** Reference data worth keeping longer: 5 min stale, 30 min in the cache (the one preset that raises `gcTime`). */
-declare const cachedQueryDefaults: {
+export declare const cachedQueryDefaults: {
   readonly gcTime: number;
   readonly staleTime: number;
 };
 /** Effectively immutable data: never stale. */
-declare const staticQueryDefaults: {
+export declare const staticQueryDefaults: {
   readonly staleTime: number;
 };
-//#endregion
-export { cachedQueryDefaults, liveBackgroundQueryDefaults, liveQueryDefaults, longLivedQueryDefaults, shortLivedQueryDefaults, staticQueryDefaults };
+//#endregion

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

@@ -1,7 +1,8 @@
+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
-type QueryHydrationBoundaryProps = {
+export type QueryHydrationBoundaryProps = {
   children: ReactNode;
   /**
    * Fills the server-side cache. Call each query through the same `queryOptions` factory the
@@ -17,6 +18,11 @@ 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,6 +38,5 @@ type QueryHydrationBoundaryProps = {
  * </QueryHydrationBoundary>
  * ```
  */
-declare function QueryHydrationBoundary({ children, createQueryClient, dehydrateOptions, prefetch }: QueryHydrationBoundaryProps): Promise<import("react/jsx-runtime").JSX.Element>;
-//#endregion
-export { QueryHydrationBoundary, QueryHydrationBoundaryProps };
+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/dist/query-suspense-loading.d.mts

@@ -1,11 +1,10 @@
 import { ComponentPropsWithoutRef } from "react";
 //#region src/query-suspense-loading.d.ts
-type QuerySuspenseLoadingProps = ComponentPropsWithoutRef<"div">;
+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.
  */
-declare function QuerySuspenseLoading({ "aria-busy": ariaBusy, "aria-live": ariaLive, children, ...props }: QuerySuspenseLoadingProps): import("react/jsx-runtime").JSX.Element;
-//#endregion
-export { QuerySuspenseLoading, QuerySuspenseLoadingProps };
+export declare function QuerySuspenseLoading({ "aria-busy": ariaBusy, "aria-live": ariaLive, children, ...props }: QuerySuspenseLoadingProps): import("react").JSX.Element;
+//#endregion

package/dist/query-suspense.d.mts

@@ -1,13 +1,13 @@
 import { ReactNode } from "react";
 //#region src/query-suspense.d.ts
-type QuerySuspenseErrorFallbackProps = {
+export type QuerySuspenseErrorFallbackProps = {
   error: Error;
   onRetry: () => void;
 };
 /** Dev/test only: force a boundary's loading or error UI (e.g. for screenshots). Ignored in production. */
-type QuerySuspenseDebugState = "loading" | "error";
+export type QuerySuspenseDebugState = "loading" | "error";
 /** Exported so callers can type wrapper components that forward `fallback` / `errorFallback`. */
-type QuerySuspenseProps = {
+export type QuerySuspenseProps = {
   children: ReactNode;
   /** Suspense fallback: usually a skeleton of the same layout. */
   fallback: ReactNode;
@@ -25,6 +25,5 @@ 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.
  */
-declare function QuerySuspense({ children, errorFallback, fallback, debugState }: QuerySuspenseProps): import("react/jsx-runtime").JSX.Element;
-//#endregion
-export { QuerySuspense, QuerySuspenseDebugState, QuerySuspenseErrorFallbackProps, QuerySuspenseProps };
+export declare function QuerySuspense({ children, errorFallback, fallback, debugState }: QuerySuspenseProps): import("react").JSX.Element;
+//#endregion

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@zeno-lib/query",
-  "version": "0.0.2",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/zeno-lib/zeno.git",
+    "directory": "packages/query"
+  },
   "type": "module",
   "exports": {
     "./prefetched-queries": {
@@ -13,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",
@@ -32,34 +46,34 @@
   "files": [
     "dist"
   ],
-  "publishConfig": {
-    "access": "public"
+  "dependencies": {
+    "devalue": "^6.0.3"
   },
-  "repository": {
-    "url": "https://github.com/zeno-lib/zeno.git",
-    "directory": "packages/query"
+  "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.2.0",
+    "@zeno-lib/ui": "^0.0.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "tsdown": "^0.23.0",
+    "typescript": "7.0.2",
+    "vite": "8.3.3",
+    "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "@tanstack/react-query": ">=5",
+    "@tanstack/react-query": ">=5.66.0",
     "react": ">=19"
   },
-  "devDependencies": {
-    "@tanstack/react-query": "^5.103.2",
-    "@types/node": "25.6.0",
-    "@types/react": "19.2.14",
-    "@types/react-dom": "19.2.3",
-    "react": "^19.2.5",
-    "react-dom": "^19.2.5",
-    "tsdown": "^0.22.14",
-    "typescript": "7.0.2",
-    "vite": "8.0.16",
-    "vitest": "4.1.11",
-    "@zeno-lib/test": "^0.1.0",
-    "@zeno-lib/typescript": "^1.1.0",
-    "@zeno-lib/ui": "^0.0.1"
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
     "build": "tsdown",
+    "dev": "tsdown --watch --no-clean",
     "test": "vitest --run",
     "test:watch": "vitest watch",
     "types:check": "tsc --noEmit"