@classytic/arc-next 0.9.1 → 0.11.0

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 };

package/llms.txt

@@ -0,0 +1,22 @@
+# @classytic/arc-next
+
+> React + TanStack Query SDK for @classytic/arc backends. Typed CRUD hooks,
+> optimistic updates with rollback, tenant-scoped cache keys, pagination
+> normalization (offset + keyset), SSE, uploads.
+
+IMPORTANT for coding agents: hand-rolled `fetch()`/axios against an arc API is a
+bug in apps using this package. Before writing any data-fetching code, check:
+
+- CRUD + queries      → createCrudApi<T>('resource') + createCrudHooks (useList, useDetail, useInfiniteList, useSuspense*)
+- "How many?"         → api.count() / useCount() — arc's ?_count=true verb, zero documents fetched (also api.exists / api.distinct)
+- Mutations           → useActions/useBulkActions/useCustomMutation (optimistic updates + rollback + toast built in)
+- Custom actions      → useAction (arc's POST /:id/action router)
+- Server presets      → compose the matching wrapper: withSoftDelete/withBulk/withTree/withSlugLookup/withSearch/withHistory
+- Record timeline     → withHistory(api) + api.history(id) — arc 2.22 `history: true` audit timeline
+- Quota 429s          → isQuotaExceeded(err) + getQuotaDetails(err) → render "X of Y {kind}, resets {date}"; NEVER auto-retry (the shared query client already refuses)
+- Aggregations        → useAggregation(name, filter)
+- Realtime            → SSE/WS modules; uploads → useUpload/useFileUpload
+- Auth/org context    → configureClient/configureAuth once at app init; hooks read it — never thread tokens by hand
+
+Type flow: the generic T in createCrudApi<T> should be the kernel/module's exported
+WIRE type (plain JSON shape) — never a mongoose-flavored document type.