@zeno-lib/query 0.0.0

package/README.md

@@ -0,0 +1,3 @@
+# @zeno-lib/query
+
+See [Queries](https://www.zeno-lib.com/docs/core-framework/data-management/queries).

package/dist/prefetched-queries.d.mts

@@ -0,0 +1,17 @@
+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 = {
+  children: ReactNode;
+  state: DehydratedState;
+};
+/**
+ * TanStack's `HydrationBoundary` plus the flag above. It hydrates `state` into the cache **during
+ * 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 };

package/dist/prefetched-queries.mjs

@@ -0,0 +1,37 @@
+"use client";
+import { HydrationBoundary } from "@tanstack/react-query";
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/prefetched-queries.tsx
+/**
+* True inside a subtree that was handed a filled dehydrated cache.
+*
+* `QuerySuspense` reads it to skip the gate that otherwise keeps a suspense query off the server
+* render. It is **derived from the payload**, not passed as a flag, so nothing can opt in without
+* having prefetched: the only way to make it true is to arrive here with cache entries.
+*
+* What it does *not* promise is that every query below was prefetched. One that was not still runs
+* its `queryFn` during the server render, so a route that opts in has to prefetch every suspense
+* query its **server pass** reaches.
+*/
+const PrefetchedQueriesContext = createContext(false);
+/** Whether the nearest `PrefetchedQueries` above was handed at least one dehydrated query. */
+function useHasPrefetchedQueries() {
+	return useContext(PrefetchedQueriesContext);
+}
+/**
+* TanStack's `HydrationBoundary` plus the flag above. It hydrates `state` into the cache **during
+* 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.
+*/
+function PrefetchedQueries({ children, state }) {
+	return /* @__PURE__ */ jsx(HydrationBoundary, {
+		state,
+		children: /* @__PURE__ */ jsx(PrefetchedQueriesContext.Provider, {
+			value: state.queries.length > 0,
+			children
+		})
+	});
+}
+//#endregion
+export { PrefetchedQueries, useHasPrefetchedQueries };

package/dist/query-defaults.d.mts

@@ -0,0 +1,41 @@
+//#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`.
+ *
+ * ```ts
+ * queryOptions({ ...cachedQueryDefaults, queryKey: ["countries"], queryFn: fetchCountries })
+ * ```
+ *
+ * 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: {
+  readonly refetchInterval: number;
+  readonly refetchIntervalInBackground: true;
+  readonly staleTime: number;
+};
+/** Fast-moving data refreshed while it is on screen: 30 s. */
+declare const liveQueryDefaults: {
+  readonly refetchInterval: number;
+  readonly staleTime: number;
+};
+/** Data that can be slightly stale: 1 min. */
+declare const shortLivedQueryDefaults: {
+  readonly staleTime: number;
+};
+/** Slower-changing detail data: 2 min. */
+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: {
+  readonly gcTime: number;
+  readonly staleTime: number;
+};
+/** Effectively immutable data: never stale. */
+declare const staticQueryDefaults: {
+  readonly staleTime: number;
+};
+//#endregion
+export { cachedQueryDefaults, liveBackgroundQueryDefaults, liveQueryDefaults, longLivedQueryDefaults, shortLivedQueryDefaults, staticQueryDefaults };

package/dist/query-defaults.mjs

@@ -0,0 +1,37 @@
+//#region 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`.
+*
+* ```ts
+* queryOptions({ ...cachedQueryDefaults, queryKey: ["countries"], queryFn: fetchCountries })
+* ```
+*
+* Every duration is in milliseconds.
+*/
+const SECOND = 1e3;
+const MINUTE = 60 * SECOND;
+/** Fast-moving data that keeps updating even while the tab is hidden: 15 s, refetched in the background. */
+const liveBackgroundQueryDefaults = {
+	refetchInterval: 15 * SECOND,
+	refetchIntervalInBackground: true,
+	staleTime: 15 * SECOND
+};
+/** Fast-moving data refreshed while it is on screen: 30 s. */
+const liveQueryDefaults = {
+	refetchInterval: 30 * SECOND,
+	staleTime: 30 * SECOND
+};
+/** Data that can be slightly stale: 1 min. */
+const shortLivedQueryDefaults = { staleTime: MINUTE };
+/** Slower-changing detail data: 2 min. */
+const longLivedQueryDefaults = { staleTime: 2 * MINUTE };
+/** Reference data worth keeping longer: 5 min stale, 30 min in the cache (the one preset that raises `gcTime`). */
+const cachedQueryDefaults = {
+	gcTime: 30 * MINUTE,
+	staleTime: 5 * MINUTE
+};
+/** 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

@@ -0,0 +1,37 @@
+import { DehydrateOptions, QueryClient } from "@tanstack/react-query";
+import { ReactNode } from "react";
+//#region src/query-hydration-boundary.d.ts
+type QueryHydrationBoundaryProps = {
+  children: ReactNode;
+  /**
+   * Fills the server-side cache. Call each query through the same `queryOptions` factory the
+   * browser uses, unchanged, so the entry has the key *and* the value the client would build.
+   * Use `fetchQuery` for a read the route cannot render without (`prefetchQuery` swallows
+   * failures); everything else can be `prefetchQuery`.
+   */
+  prefetch: (queryClient: QueryClient) => Promise<unknown>;
+  /**
+   * Builds the per-request `QueryClient` handed to `prefetch`. Defaults to `new QueryClient()`.
+   * Pass one when your queries depend on client-level defaults (e.g. `defaultOptions.queries`).
+   */
+  createQueryClient?: () => QueryClient;
+  /** Forwarded to TanStack's `dehydrate` (e.g. to also dehydrate pending queries). */
+  dehydrateOptions?: DehydrateOptions;
+};
+/**
+ * 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
+ * server render *and* in the browser. That is what lets a `QuerySuspense` subtree render real
+ * HTML instead of holding its fallback until hydration.
+ *
+ * ```tsx
+ * <QueryHydrationBoundary
+ *   prefetch={(queryClient) => queryClient.fetchQuery(dealsQueryOptions(filters))}
+ * >
+ *   <Deals />
+ * </QueryHydrationBoundary>
+ * ```
+ */
+declare function QueryHydrationBoundary({ children, createQueryClient, dehydrateOptions, prefetch }: QueryHydrationBoundaryProps): Promise<import("react/jsx-runtime").JSX.Element>;
+//#endregion
+export { QueryHydrationBoundary, QueryHydrationBoundaryProps };

package/dist/query-hydration-boundary.mjs

@@ -0,0 +1,28 @@
+import { PrefetchedQueries } from "./prefetched-queries.mjs";
+import { QueryClient, dehydrate } from "@tanstack/react-query";
+import { jsx } from "react/jsx-runtime";
+//#region 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
+* server render *and* in the browser. That is what lets a `QuerySuspense` subtree render real
+* HTML instead of holding its fallback until hydration.
+*
+* ```tsx
+* <QueryHydrationBoundary
+*   prefetch={(queryClient) => queryClient.fetchQuery(dealsQueryOptions(filters))}
+* >
+*   <Deals />
+* </QueryHydrationBoundary>
+* ```
+*/
+async function QueryHydrationBoundary({ children, createQueryClient = () => new QueryClient(), dehydrateOptions, prefetch }) {
+	const queryClient = createQueryClient();
+	await prefetch(queryClient);
+	return /* @__PURE__ */ jsx(PrefetchedQueries, {
+		state: dehydrate(queryClient, dehydrateOptions),
+		children
+	});
+}
+//#endregion
+export { QueryHydrationBoundary };

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

@@ -0,0 +1,11 @@
+import { ComponentPropsWithoutRef } from "react";
+//#region src/query-suspense-loading.d.ts
+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 };

package/dist/query-suspense-loading.mjs

@@ -0,0 +1,17 @@
+import { jsx } from "react/jsx-runtime";
+//#region 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
+* all `div` props; the `aria-busy` and `aria-live` defaults can be overridden.
+*/
+function QuerySuspenseLoading({ "aria-busy": ariaBusy = true, "aria-live": ariaLive = "polite", children, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"aria-busy": ariaBusy,
+		"aria-live": ariaLive,
+		...props,
+		children
+	});
+}
+//#endregion
+export { QuerySuspenseLoading };

package/dist/query-suspense.d.mts

@@ -0,0 +1,30 @@
+import { ReactNode } from "react";
+//#region src/query-suspense.d.ts
+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";
+/** Exported so callers can type wrapper components that forward `fallback` / `errorFallback`. */
+type QuerySuspenseProps = {
+  children: ReactNode;
+  /** Suspense fallback: usually a skeleton of the same layout. */
+  fallback: ReactNode;
+  /** Rendered when a query below throws; `onRetry` resets the failed queries and re-renders. */
+  errorFallback: (props: QuerySuspenseErrorFallbackProps) => ReactNode;
+  /**
+   * Development / test only: render `fallback` or `errorFallback` without running queries.
+   * No effect when `NODE_ENV` is `"production"`.
+   */
+  debugState?: QuerySuspenseDebugState;
+};
+/**
+ * TanStack's recommended suspense stack (`QueryErrorResetBoundary` → error boundary →
+ * `Suspense`, see https://tanstack.com/query/v5/docs/framework/react/guides/suspense), plus a
+ * 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 };

package/dist/query-suspense.mjs

@@ -0,0 +1,63 @@
+"use client";
+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
+const debugStateEnabled = typeof process !== "undefined" && process.env.NODE_ENV !== "production";
+const subscribeToNothing = () => () => {};
+const useIsHydrated = () => useSyncExternalStore(subscribeToNothing, () => true, () => false);
+const debugError = Object.freeze(/* @__PURE__ */ new Error("QuerySuspense: debugState=\"error\" (development / test only; for screenshots)"));
+const noop = () => {};
+/** Next.js control-flow errors (`notFound()`, `redirect()`, …) carry a `NEXT_`-prefixed digest. */
+const isNextControlFlowError = (error) => typeof error === "object" && error !== null && "digest" in error && typeof error.digest === "string" && error.digest.startsWith("NEXT_");
+var QueryErrorBoundary = class extends Component {
+	constructor(props) {
+		super(props);
+		this.handleRetry = () => {
+			this.props.onQueryReset();
+			this.setState({ error: null });
+		};
+		this.state = { error: null };
+	}
+	static getDerivedStateFromError(error) {
+		if (isNextControlFlowError(error)) throw error;
+		return { error };
+	}
+	componentDidCatch(error) {
+		console.error("QueryErrorBoundary:", error);
+	}
+	render() {
+		if (this.state.error) return this.props.errorFallback({
+			error: this.state.error,
+			onRetry: this.handleRetry
+		});
+		return this.props.children;
+	}
+};
+/**
+* TanStack's recommended suspense stack (`QueryErrorResetBoundary` → error boundary →
+* `Suspense`, see https://tanstack.com/query/v5/docs/framework/react/guides/suspense), plus a
+* 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.
+*/
+function QuerySuspense({ children, errorFallback, fallback, debugState }) {
+	const isHydrated = useIsHydrated();
+	const hasPrefetchedQueries = useHasPrefetchedQueries();
+	if (debugStateEnabled && debugState === "loading") return /* @__PURE__ */ jsx(Fragment, { children: fallback });
+	if (debugStateEnabled && debugState === "error") return /* @__PURE__ */ jsx(Fragment, { children: errorFallback({
+		error: debugError,
+		onRetry: noop
+	}) });
+	if (!(isHydrated || hasPrefetchedQueries)) return /* @__PURE__ */ jsx(Fragment, { children: fallback });
+	return /* @__PURE__ */ jsx(QueryErrorResetBoundary, { children: ({ reset }) => /* @__PURE__ */ jsx(QueryErrorBoundary, {
+		errorFallback,
+		onQueryReset: reset,
+		children: /* @__PURE__ */ jsx(Suspense, {
+			fallback,
+			children
+		})
+	}) });
+}
+//#endregion
+export { QuerySuspense };

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@zeno-lib/query",
+  "version": "0.0.0",
+  "type": "module",
+  "exports": {
+    "./prefetched-queries": {
+      "types": "./dist/prefetched-queries.d.mts",
+      "import": "./dist/prefetched-queries.mjs",
+      "default": "./dist/prefetched-queries.mjs"
+    },
+    "./query-defaults": {
+      "types": "./dist/query-defaults.d.mts",
+      "import": "./dist/query-defaults.mjs",
+      "default": "./dist/query-defaults.mjs"
+    },
+    "./query-hydration-boundary": {
+      "types": "./dist/query-hydration-boundary.d.mts",
+      "import": "./dist/query-hydration-boundary.mjs",
+      "default": "./dist/query-hydration-boundary.mjs"
+    },
+    "./query-suspense": {
+      "types": "./dist/query-suspense.d.mts",
+      "import": "./dist/query-suspense.mjs",
+      "default": "./dist/query-suspense.mjs"
+    },
+    "./query-suspense-loading": {
+      "types": "./dist/query-suspense-loading.d.mts",
+      "import": "./dist/query-suspense-loading.mjs",
+      "default": "./dist/query-suspense-loading.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "url": "https://github.com/zeno-lib/zeno.git",
+    "directory": "packages/query"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": ">=5",
+    "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.0.3",
+    "@zeno-lib/typescript": "^1.1.0",
+    "@zeno-lib/ui": "^0.0.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest --run",
+    "test:watch": "vitest watch",
+    "types:check": "tsc --noEmit"
+  }
+}