@classytic/arc-next 0.9.0 → 0.10.0

package/dist/prefetch.js

@@ -1,11 +1,25 @@
-import { createQueryKeys } from "./cache.js";
+import { createEntityQueries } from "./query-options.js";
 import { HydrationBoundary, dehydrate } from "@tanstack/react-query";
 
 //#region src/prefetch.ts
+/** Extract the queryFn context (auth + fetch caching) from prefetch options. */
+function toCtx(options) {
+	const { staleTime: _staleTime, ...ctx } = options;
+	return ctx;
+}
 /**
 * Create server-safe prefetch helpers for CRUD queries.
 * Use in Next.js server components to pre-populate the query cache before rendering.
 *
+* Since 0.10 this is a thin layer over `createEntityQueries`
+* (@classytic/arc-next/query-options) — the queryOptions factories are the
+* single source of key + queryFn, shared with the client CRUD hooks, so
+* prefetch keys can never drift from hook keys. Prefer the factories directly
+* for new code that also needs `ensureQueryData` / router-loader integration:
+*
+*   const products = createEntityQueries(productApi, 'products');
+*   await queryClient.prefetchQuery({ ...products.list({ limit: 20 }, { token }), staleTime: 60_000 });
+*
 * @example
 * // products-prefetch.ts
 * import { productsApi } from '@/api/products-api';
@@ -28,146 +42,54 @@ import { HydrationBoundary, dehydrate } from "@tanstack/react-query";
 * }
 */
 function createCrudPrefetcher(api, entityKey) {
-	const KEYS = createQueryKeys(entityKey);
-	const apiOptions = (o) => {
-		const opt = {};
-		if (o.headers) opt.headerOptions = o.headers;
-		if (o.cache !== void 0) opt.cache = o.cache;
-		if (o.revalidate !== void 0) opt.revalidate = o.revalidate;
-		if (o.tags !== void 0) opt.tags = o.tags;
-		return Object.keys(opt).length ? { options: opt } : {};
-	};
+	const queries = createEntityQueries(api, entityKey);
 	return {
 		async prefetchList(queryClient, params = {}, options = {}) {
-			const { organizationId: paramOrgId, ...restParams } = params;
-			const orgId = paramOrgId ?? options.organizationId ?? null;
-			const scope = orgId ? "tenant" : "super-admin";
-			const queryKey = KEYS.scopedList(scope, {
-				...orgId ? { organizationId: orgId } : {},
-				...restParams
-			});
 			await queryClient.prefetchQuery({
-				queryKey,
-				queryFn: () => api.getAll({
-					params: restParams,
-					token: options.token ?? null,
-					organizationId: orgId,
-					...apiOptions(options)
-				}),
+				...queries.list(params, toCtx(options)),
 				staleTime: options.staleTime
 			});
 		},
 		async prefetchDetail(queryClient, id, options = {}) {
-			const { params, staleTime, token, organizationId } = options;
-			const baseKey = KEYS.detail(id);
-			const queryKey = params ? [...baseKey, params] : baseKey;
+			const { staleTime, ...detailOpts } = options;
 			await queryClient.prefetchQuery({
-				queryKey,
-				queryFn: () => api.getById({
-					id,
-					token: token ?? null,
-					organizationId: organizationId ?? null,
-					...params ? { params } : {},
-					...apiOptions(options)
-				}),
+				...queries.detail(id, detailOpts),
 				staleTime
 			});
 		},
 		async prefetchBySlug(queryClient, slug, options = {}) {
 			if (!api.getBySlug) throw new Error(`[arc-next] prefetchBySlug requires an api with getBySlug (slugLookup preset)`);
-			const { params, staleTime, token, organizationId } = options;
-			const queryKey = params ? KEYS.custom("slug", slug, params) : KEYS.custom("slug", slug);
+			const { staleTime, ...detailOpts } = options;
 			await queryClient.prefetchQuery({
-				queryKey,
-				queryFn: () => api.getBySlug({
-					slug,
-					token: token ?? null,
-					organizationId: organizationId ?? null,
-					...params ? { params } : {},
-					...apiOptions(options)
-				}),
+				...queries.bySlug(slug, detailOpts),
 				staleTime
 			});
 		},
 		async prefetchDeleted(queryClient, params = {}, options = {}) {
 			if (!api.getDeleted) throw new Error(`[arc-next] prefetchDeleted requires an api with getDeleted (softDelete preset)`);
-			const { organizationId: paramOrgId, ...restParams } = params;
-			const orgId = paramOrgId ?? options.organizationId ?? null;
-			const queryKey = KEYS.custom("deleted", {
-				...orgId ? { organizationId: orgId } : {},
-				...restParams
-			});
 			await queryClient.prefetchQuery({
-				queryKey,
-				queryFn: () => api.getDeleted({
-					params: restParams,
-					token: options.token ?? null,
-					organizationId: orgId,
-					...apiOptions(options)
-				}),
+				...queries.deleted(params, toCtx(options)),
 				staleTime: options.staleTime
 			});
 		},
 		async prefetchAggregation(queryClient, name, filter, options = {}) {
 			if (!api.aggregate) throw new Error(`[arc-next] prefetchAggregation requires an api with aggregate (arc 2.13+)`);
 			if (!name) throw new Error("[arc-next] prefetchAggregation: aggregation name is required");
-			const orgId = options.organizationId ?? null;
-			const filterKey = orgId ? {
-				_org: orgId,
-				...filter ?? {}
-			} : filter ?? {};
 			await queryClient.prefetchQuery({
-				queryKey: KEYS.aggregation(name, filterKey),
-				queryFn: () => api.aggregate({
-					name,
-					filter,
-					token: options.token ?? null,
-					organizationId: orgId,
-					...apiOptions(options)
-				}),
+				...queries.aggregation(name, filter, toCtx(options)),
 				staleTime: options.staleTime
 			});
 		},
 		async prefetchTree(queryClient, params = {}, options = {}) {
 			if (!api.getTree) throw new Error(`[arc-next] prefetchTree requires an api with getTree (tree preset)`);
-			const { organizationId: paramOrgId, ...restParams } = params;
-			const orgId = paramOrgId ?? options.organizationId ?? null;
-			const queryKey = KEYS.custom("tree", {
-				...orgId ? { organizationId: orgId } : {},
-				...restParams
-			});
 			await queryClient.prefetchQuery({
-				queryKey,
-				queryFn: () => api.getTree({
-					params: restParams,
-					token: options.token ?? null,
-					organizationId: orgId,
-					...apiOptions(options)
-				}),
+				...queries.tree(params, toCtx(options)),
 				staleTime: options.staleTime
 			});
 		},
 		async prefetchInfiniteList(queryClient, params = {}, options = {}) {
-			const { organizationId: paramOrgId, ...restParams } = params;
-			const orgId = paramOrgId ?? options.organizationId ?? null;
-			const scope = orgId ? "tenant" : "super-admin";
-			const queryKey = [...KEYS.scopedList(scope, {
-				...orgId ? { organizationId: orgId } : {},
-				...restParams
-			}), "infinite"];
 			await queryClient.prefetchInfiniteQuery({
-				queryKey,
-				queryFn: ({ pageParam }) => api.getAll({
-					params: {
-						...restParams,
-						...pageParam ? { page: pageParam } : {}
-					},
-					token: options.token ?? null,
-					organizationId: orgId,
-					...apiOptions(options)
-				}),
-				initialPageParam: 1,
-				getNextPageParam: () => void 0,
+				...queries.infiniteList(params, toCtx(options)),
 				staleTime: options.staleTime
 			});
 		}

package/dist/presets/tree.js

@@ -16,14 +16,10 @@
 function withTree(api) {
 	return Object.assign(api, {
 		async getTree({ token = null, organizationId = null, params = {}, options = {} } = {}) {
-			const merged = {
-				...api.config.defaultParams,
-				...params
-			};
 			return api.request("GET", `${api.baseUrl}/tree`, {
 				token,
 				organizationId,
-				params: merged,
+				params,
 				options
 			});
 		},

package/dist/query-options.d.ts

@@ -0,0 +1,165 @@
+import { QueryKeys } from "./cache.js";
+import * as _$_tanstack_react_query0 from "@tanstack/react-query";
+
+//#region src/query-options.d.ts
+/** Per-call request context: auth + Next.js fetch caching passthrough. */
+interface QueryFnContext {
+  /** Bearer token for protected endpoints (required server-side for non-public reads). */
+  token?: string | null;
+  /** Organization ID for multi-tenant reads. Also becomes part of the cache key. */
+  organizationId?: string | null;
+  /** Extra headers (e.g. x-api-key). */
+  headers?: Record<string, string>;
+  /** Next.js fetch caching forwarded to the API call (ISR-friendly prefetch). */
+  cache?: RequestCache;
+  revalidate?: number | false;
+  tags?: string[];
+}
+type ForwardedApiOptions = {
+  headerOptions?: Record<string, string>;
+  cache?: RequestCache;
+  revalidate?: number | false;
+  tags?: string[];
+  signal?: AbortSignal;
+};
+/** Structural read-API contract (BaseApi satisfies this; presets add the optionals). */
+interface EntityReadApi {
+  getAll: (opts: {
+    params?: Record<string, unknown>;
+    token?: string | null;
+    organizationId?: string | null;
+    options?: ForwardedApiOptions;
+  }) => Promise<unknown>;
+  getById: (opts: {
+    id: string;
+    token?: string | null;
+    organizationId?: string | null;
+    params?: Record<string, unknown>;
+    options?: ForwardedApiOptions;
+  }) => Promise<unknown>;
+  getBySlug?: (opts: {
+    slug: string;
+    token?: string | null;
+    organizationId?: string | null;
+    params?: Record<string, unknown>;
+    options?: ForwardedApiOptions;
+  }) => Promise<unknown>;
+  getDeleted?: (opts: {
+    params?: Record<string, unknown>;
+    token?: string | null;
+    organizationId?: string | null;
+    options?: ForwardedApiOptions;
+  }) => Promise<unknown>;
+  getTree?: (opts: {
+    params?: Record<string, unknown>;
+    token?: string | null;
+    organizationId?: string | null;
+    options?: ForwardedApiOptions;
+  }) => Promise<unknown>;
+  getChildren?: (opts: {
+    parentId: string;
+    params?: Record<string, unknown>;
+    token?: string | null;
+    organizationId?: string | null;
+    options?: ForwardedApiOptions;
+  }) => Promise<unknown>;
+  aggregate?: (opts: {
+    name: string;
+    filter?: Record<string, unknown>;
+    token?: string | null;
+    organizationId?: string | null;
+    options?: ForwardedApiOptions;
+  }) => Promise<unknown>;
+}
+interface DetailQueryOpts extends QueryFnContext {
+  /** Query params (select, populate) — becomes part of the key, matching useDetail. */
+  params?: {
+    select?: string;
+    populate?: string | string[];
+  };
+}
+type EntityQueries = ReturnType<typeof createEntityQueries>;
+/**
+ * Build queryOptions factories for one entity. Server-safe; keys are
+ * hash-identical to the corresponding `createCrudHooks` hooks.
+ *
+ * @example
+ * // queries/products.ts — colocate next to the api definition
+ * export const productQueries = createEntityQueries(productApi, 'products');
+ *
+ * // RSC / route loader
+ * await queryClient.ensureQueryData(productQueries.detail(id, { token }));
+ */
+declare function createEntityQueries(api: EntityReadApi, entityKey: string): {
+  /** The entity's key factory — for invalidation / setQueryData at call sites. */keys: QueryKeys; /** GET /:resource — mirrors `useList`'s key (scoped, org-normalized). */
+  list(params?: Record<string, unknown>, ctx?: QueryFnContext): _$_tanstack_react_query0.OmitKeyof<_$_tanstack_react_query0.UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
+    queryFn?: _$_tanstack_react_query0.QueryFunction<unknown, readonly unknown[], never> | undefined;
+  } & {
+    queryKey: readonly unknown[] & {
+      [dataTagSymbol]: unknown;
+      [dataTagErrorSymbol]: Error;
+    };
+  }; /** GET /:resource/:id — mirrors `useDetail`'s scoped key (+ params variant). */
+  detail(id: string, opts?: DetailQueryOpts): _$_tanstack_react_query0.OmitKeyof<_$_tanstack_react_query0.UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
+    queryFn?: _$_tanstack_react_query0.QueryFunction<unknown, readonly unknown[], never> | undefined;
+  } & {
+    queryKey: readonly unknown[] & {
+      [dataTagSymbol]: unknown;
+      [dataTagErrorSymbol]: Error;
+    };
+  }; /** GET /:resource/slug/:slug — mirrors `useDetailBySlug`'s key. */
+  bySlug(slug: string, opts?: DetailQueryOpts): _$_tanstack_react_query0.OmitKeyof<_$_tanstack_react_query0.UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
+    queryFn?: _$_tanstack_react_query0.QueryFunction<unknown, readonly unknown[], never> | undefined;
+  } & {
+    queryKey: readonly unknown[] & {
+      [dataTagSymbol]: unknown;
+      [dataTagErrorSymbol]: Error;
+    };
+  }; /** GET /:resource/deleted — mirrors `useDeleted`'s key. */
+  deleted(params?: Record<string, unknown>, ctx?: QueryFnContext): _$_tanstack_react_query0.OmitKeyof<_$_tanstack_react_query0.UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
+    queryFn?: _$_tanstack_react_query0.QueryFunction<unknown, readonly unknown[], never> | undefined;
+  } & {
+    queryKey: readonly unknown[] & {
+      [dataTagSymbol]: unknown;
+      [dataTagErrorSymbol]: Error;
+    };
+  }; /** GET /:resource/tree — mirrors `useTree`'s key. */
+  tree(params?: Record<string, unknown>, ctx?: QueryFnContext): _$_tanstack_react_query0.OmitKeyof<_$_tanstack_react_query0.UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
+    queryFn?: _$_tanstack_react_query0.QueryFunction<unknown, readonly unknown[], never> | undefined;
+  } & {
+    queryKey: readonly unknown[] & {
+      [dataTagSymbol]: unknown;
+      [dataTagErrorSymbol]: Error;
+    };
+  }; /** GET /:resource/:parentId/children — mirrors `useChildren`'s key. */
+  children(parentId: string, params?: Record<string, unknown>, ctx?: QueryFnContext): _$_tanstack_react_query0.OmitKeyof<_$_tanstack_react_query0.UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
+    queryFn?: _$_tanstack_react_query0.QueryFunction<unknown, readonly unknown[], never> | undefined;
+  } & {
+    queryKey: readonly unknown[] & {
+      [dataTagSymbol]: unknown;
+      [dataTagErrorSymbol]: Error;
+    };
+  }; /** GET /:resource/aggregations/:name — mirrors `useAggregation`'s tenant-scoped key. */
+  aggregation(name: string, filter?: Record<string, unknown>, ctx?: QueryFnContext): _$_tanstack_react_query0.OmitKeyof<_$_tanstack_react_query0.UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
+    queryFn?: _$_tanstack_react_query0.QueryFunction<unknown, readonly unknown[], never> | undefined;
+  } & {
+    queryKey: readonly unknown[] & {
+      [dataTagSymbol]: unknown;
+      [dataTagErrorSymbol]: Error;
+    };
+  };
+  /**
+   * Infinite list — mirrors `useInfiniteList`'s key (`scopedList + 'infinite'`)
+   * and its page-param semantics (keyset cursor or offset page + 1).
+   */
+  infiniteList(params?: Record<string, unknown>, ctx?: QueryFnContext): _$_tanstack_react_query0.OmitKeyof<_$_tanstack_react_query0.UseInfiniteQueryOptions<unknown, Error, _$_tanstack_react_query0.InfiniteData<unknown, unknown>, unknown[], unknown>, "queryFn"> & {
+    queryFn?: _$_tanstack_react_query0.QueryFunction<unknown, unknown[], unknown> | undefined;
+  } & {
+    queryKey: unknown[] & {
+      [dataTagSymbol]: _$_tanstack_react_query0.InfiniteData<unknown, unknown>;
+      [dataTagErrorSymbol]: Error;
+    };
+  };
+};
+//#endregion
+export { DetailQueryOpts, EntityQueries, EntityReadApi, QueryFnContext, createEntityQueries };

package/dist/query-options.js

@@ -0,0 +1,188 @@
+import { isKeysetPagination, isOffsetPagination } from "./api.js";
+import { createQueryKeys, withOrgParams } from "./cache.js";
+import { infiniteQueryOptions, queryOptions } from "@tanstack/react-query";
+
+//#region src/query-options.ts
+/**
+* Build queryOptions factories for one entity. Server-safe; keys are
+* hash-identical to the corresponding `createCrudHooks` hooks.
+*
+* @example
+* // queries/products.ts — colocate next to the api definition
+* export const productQueries = createEntityQueries(productApi, 'products');
+*
+* // RSC / route loader
+* await queryClient.ensureQueryData(productQueries.detail(id, { token }));
+*/
+function createEntityQueries(api, entityKey) {
+	const KEYS = createQueryKeys(entityKey);
+	const fwd = (ctx, signal) => {
+		const opt = {};
+		if (ctx.headers) opt.headerOptions = ctx.headers;
+		if (ctx.cache !== void 0) opt.cache = ctx.cache;
+		if (ctx.revalidate !== void 0) opt.revalidate = ctx.revalidate;
+		if (ctx.tags !== void 0) opt.tags = ctx.tags;
+		if (signal) opt.signal = signal;
+		return Object.keys(opt).length ? { options: opt } : {};
+	};
+	const resolveOrg = (params, ctx) => {
+		const { organizationId: paramOrg, ...rest } = params;
+		return {
+			org: paramOrg ?? ctx.organizationId ?? null,
+			rest
+		};
+	};
+	return {
+		/** The entity's key factory — for invalidation / setQueryData at call sites. */
+		keys: KEYS,
+		/** GET /:resource — mirrors `useList`'s key (scoped, org-normalized). */
+		list(params = {}, ctx = {}) {
+			const { org, rest } = resolveOrg(params, ctx);
+			const scope = org ? "tenant" : "super-admin";
+			return queryOptions({
+				queryKey: KEYS.scopedList(scope, withOrgParams(org, rest)),
+				queryFn: ({ signal }) => api.getAll({
+					params: rest,
+					token: ctx.token ?? null,
+					organizationId: org,
+					...fwd(ctx, signal)
+				})
+			});
+		},
+		/** GET /:resource/:id — mirrors `useDetail`'s scoped key (+ params variant). */
+		detail(id, opts = {}) {
+			const { params, ...ctx } = opts;
+			const baseKey = KEYS.scopedDetail(id, ctx.organizationId ?? null);
+			return queryOptions({
+				queryKey: params ? [...baseKey, params] : baseKey,
+				queryFn: ({ signal }) => api.getById({
+					id,
+					token: ctx.token ?? null,
+					organizationId: ctx.organizationId ?? null,
+					...params ? { params } : {},
+					...fwd(ctx, signal)
+				})
+			});
+		},
+		/** GET /:resource/slug/:slug — mirrors `useDetailBySlug`'s key. */
+		bySlug(slug, opts = {}) {
+			const { params, ...ctx } = opts;
+			return queryOptions({
+				queryKey: params ? KEYS.custom("slug", slug, params) : KEYS.custom("slug", slug),
+				queryFn: ({ signal }) => {
+					if (!api.getBySlug) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define getBySlug (slugLookup preset)`));
+					return api.getBySlug({
+						slug,
+						token: ctx.token ?? null,
+						organizationId: ctx.organizationId ?? null,
+						...params ? { params } : {},
+						...fwd(ctx, signal)
+					});
+				}
+			});
+		},
+		/** GET /:resource/deleted — mirrors `useDeleted`'s key. */
+		deleted(params = {}, ctx = {}) {
+			const { org, rest } = resolveOrg(params, ctx);
+			return queryOptions({
+				queryKey: KEYS.custom("deleted", withOrgParams(org, rest)),
+				queryFn: ({ signal }) => {
+					if (!api.getDeleted) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define getDeleted (softDelete preset)`));
+					return api.getDeleted({
+						params: rest,
+						token: ctx.token ?? null,
+						organizationId: org,
+						...fwd(ctx, signal)
+					});
+				}
+			});
+		},
+		/** GET /:resource/tree — mirrors `useTree`'s key. */
+		tree(params = {}, ctx = {}) {
+			const { org, rest } = resolveOrg(params, ctx);
+			return queryOptions({
+				queryKey: KEYS.custom("tree", withOrgParams(org, rest)),
+				queryFn: ({ signal }) => {
+					if (!api.getTree) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define getTree (tree preset)`));
+					return api.getTree({
+						params: rest,
+						token: ctx.token ?? null,
+						organizationId: org,
+						...fwd(ctx, signal)
+					});
+				}
+			});
+		},
+		/** GET /:resource/:parentId/children — mirrors `useChildren`'s key. */
+		children(parentId, params = {}, ctx = {}) {
+			const { org, rest } = resolveOrg(params, ctx);
+			return queryOptions({
+				queryKey: KEYS.custom("children", parentId, withOrgParams(org, rest)),
+				queryFn: ({ signal }) => {
+					if (!api.getChildren) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define getChildren (tree preset)`));
+					return api.getChildren({
+						parentId,
+						params: rest,
+						token: ctx.token ?? null,
+						organizationId: org,
+						...fwd(ctx, signal)
+					});
+				}
+			});
+		},
+		/** GET /:resource/aggregations/:name — mirrors `useAggregation`'s tenant-scoped key. */
+		aggregation(name, filter, ctx = {}) {
+			const org = ctx.organizationId ?? null;
+			const filterKey = org ? {
+				_org: org,
+				...filter ?? {}
+			} : filter ?? {};
+			return queryOptions({
+				queryKey: KEYS.aggregation(name, filterKey),
+				queryFn: ({ signal }) => {
+					if (!api.aggregate) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define aggregate (arc 2.13+)`));
+					return api.aggregate({
+						name,
+						filter,
+						token: ctx.token ?? null,
+						organizationId: org,
+						...fwd(ctx, signal)
+					});
+				}
+			});
+		},
+		/**
+		* Infinite list — mirrors `useInfiniteList`'s key (`scopedList + 'infinite'`)
+		* and its page-param semantics (keyset cursor or offset page + 1).
+		*/
+		infiniteList(params = {}, ctx = {}) {
+			const { org, rest } = resolveOrg(params, ctx);
+			const scope = org ? "tenant" : "super-admin";
+			return infiniteQueryOptions({
+				queryKey: [...KEYS.scopedList(scope, withOrgParams(org, rest)), "infinite"],
+				queryFn: ({ pageParam, signal }) => api.getAll({
+					params: {
+						...rest,
+						...pageParam ? { page: pageParam } : {}
+					},
+					token: ctx.token ?? null,
+					organizationId: org,
+					...fwd(ctx, signal)
+				}),
+				initialPageParam: 1,
+				getNextPageParam: (lastPage) => {
+					if (isKeysetPagination(lastPage)) return lastPage.hasMore ? lastPage.next : void 0;
+					if (isOffsetPagination(lastPage)) {
+						const p = lastPage;
+						return p.hasNext ? p.page + 1 : void 0;
+					}
+					const p = lastPage;
+					if (p && typeof p.hasNext === "boolean" && typeof p.page === "number") return p.hasNext ? p.page + 1 : void 0;
+				}
+			});
+		}
+	};
+}
+
+//#endregion
+export { createEntityQueries };