@everysk/apps-sdk 0.2.0 → 0.3.0-beta-20261016180126

package/src/hooks/portfolio/useFetchPortfolios.ts

@@ -1,109 +1,66 @@
-import { useMemo } from "react";
-import { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
-
 import { useAxios } from "@/hooks/useAxios";
+import { useEntityInfiniteQuery } from "@/hooks/useEntityInfiniteQuery";
 import { listPortfolios } from "@/api/portfolio";
-import type { FetchEntitiesParams } from "@/types/entityQuery";
 import type { Portfolio, PortfolioListResponse } from "@/types/portfolio";
-import { buildQueryKey, buildQueryObject } from "@/api/entityQuery";
-
-type PageToken = string | null;
-
-type InfiniteOptions<TData> = Omit<
-    UseInfiniteQueryOptions<PortfolioListResponse, Error, TData, QueryKey, PageToken>,
-    "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam"
->;
+import type { FetchEntitiesProps, ListQueryProps, ListCache } from "@/types/entityQuery";
+import {
+    buildQueryKey,
+    buildQueryObject,
+    hasWorkspaceFilter,
+    missingWorkspaceError,
+} from "@/api/entityQuery";
 
-export type FetchInfinitePortfolioProps = FetchEntitiesParams<Portfolio[], InfiniteOptions<Portfolio[]>> & {
-    pageSize?: number;
-};
+/** The query cache of `useFetchPortfolios`, for typing `setQueryData`. */
+export type PortfoliosCache = ListCache<PortfolioListResponse>;
 
-const defaultQueryOptions: InfiniteOptions<Portfolio[]> = {
-    refetchOnMount: "always",
-    staleTime: 0,
-    gcTime: 0,
-};
+export type FetchPortfoliosProps<TData = Portfolio[]> = ListQueryProps &
+    FetchEntitiesProps<Portfolio, TData, PortfolioListResponse>;
 
 /**
- * useFetchInfinitePortfolios
- *
- * Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve
- * portfolios with cursor-based pagination.
- *
- * It also:
- * - flattens all pages into a single `Portfolio[]` via `select`
- *
- * Important notes:
- * - `query.data` returns a flat `Portfolio[]` (all pages merged).
- *
- * Parameters (FetchInfinitePortfolioProps):
- * @param {FilterClause[]} [filters=[]]
- *   Filters applied to every page request. Must include a `workspace` filter.
- *
- * @param {string[]} [order=[]]
- *   Sorting applied to every page request.
- *
- * @param {string} [projection=""]
- *   Single field to project: `"field"` returns only that field (others come back null),
- *   `"-field"` returns every field except that one. One field only — lists 500. Omitted when empty.
- *
- * @param {number} [pageSize=10]
- *   Number of portfolios to fetch per page.
+ * useFetchPortfolios
  *
- * @param {InfiniteOptions<Portfolio[]>} [queryOptions]
- *   TanStack Query options passed through to `useInfiniteQuery`
- *   (e.g., enabled, staleTime, gcTime, etc.).
+ * Lists portfolios with cursor pagination; `query.data` is every loaded page merged, or
+ * whatever `select` makes of it. Paging, `select`, `fetchAllPages` and the
+ * missing-workspace error behave as in `useFetchDatastores`.
  *
- * Returns:
- * @returns {object}
- *   - `query`: the full `useInfiniteQuery` result (data, isLoading, hasNextPage, fetchNextPage, etc.)
- *   - `queryKey`: the cache key used by React Query
- *
- * Example:
- * ```ts
- * const { query } = useFetchInfinitePortfolios({
- *   filters: [{ field: "workspace", value: "ws-1" }],
- *   pageSize: 20,
- * });
- *
- * // Flat list of all fetched portfolios
- * const portfolios = query.data ?? [];
- * ```
+ * @param {FetchPortfoliosProps} props - Filters (one must be `workspace`), order,
+ *   projection, page size, `select`, `fetchAllPages` and TanStack `queryOptions`.
+ * @returns {object} `query` (the `useInfiniteQuery` result) and `queryKey`.
  */
-export function useFetchPortfolios({ filters = [], order = [], projection = "", pageSize = 10, queryOptions }: FetchInfinitePortfolioProps) {
+export function useFetchPortfolios<TData = Portfolio[]>({
+    filters = [],
+    order = [],
+    projection = "",
+    pageSize = 10,
+    select,
+    fetchAllPages = false,
+    queryOptions,
+}: FetchPortfoliosProps<TData>) {
     const { api } = useAxios();
 
-    const queryKey = buildQueryKey(["portfolios"], filters);
-
-    const mergedQueryOptions = useMemo<InfiniteOptions<Portfolio[]>>(() => ({
-        ...defaultQueryOptions,
-        ...(queryOptions ?? {}),
-    }), [queryOptions]);
+    const queryKey = buildQueryKey(["portfolios"], filters, {
+        order,
+        projection,
+        pageSize,
+        fetchAllPages,
+    });
 
-    const query = useInfiniteQuery<PortfolioListResponse, Error, Portfolio[], QueryKey, PageToken>({
+    const query = useEntityInfiniteQuery<PortfolioListResponse, "portfolios", TData>({
         queryKey,
-        initialPageParam: null,
-        getNextPageParam: (lastPage) => lastPage.next_page_token ?? undefined,
-
-        queryFn: async ({ pageParam }) => {
-            const queryFilter = buildQueryObject({
-                filters,
-                order,
-                projection,
-                pageSize,
-                pageToken: pageParam ?? undefined,
-            });
-
-            return await listPortfolios(api, queryFilter);
-        },
-
-        select: (data) => data.pages.flatMap((p) => p.portfolios),
-
-        ...mergedQueryOptions,
+        itemsKey: "portfolios",
+        fetchPage: (pageToken, signal) =>
+            listPortfolios(
+                api,
+                buildQueryObject({ filters, order, projection, pageSize, pageToken }),
+                signal,
+            ),
+        select,
+        fetchAllPages,
+        configError: hasWorkspaceFilter(filters)
+            ? undefined
+            : missingWorkspaceError("useFetchPortfolios"),
+        queryOptions,
     });
 
-    return {
-        query,
-        queryKey,
-    };
-}
+    return { query, queryKey };
+}

package/src/hooks/portfolio/usePortfolioMutations.ts

@@ -1,7 +1,5 @@
-import { useMutation, useQueryClient } from "@tanstack/react-query";
-
 import { useAxios } from "@/hooks/useAxios";
-import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import { useEntityMutation } from "@/hooks/useEntityMutation";
 import type { Portfolio } from "@/types/portfolio";
 import { deletePortfolio, createPortfolio, updatePortfolio } from "@/api/portfolio";
 
@@ -23,9 +21,6 @@ type UsePortfolioMutationsProps = {
     queryKey?: unknown[];
 };
 
-const getErrorMessage = (err: unknown, fallback: string) =>
-    err instanceof Error && err.message ? err.message : fallback;
-
 /**
  * usePortfolioMutations
  *
@@ -60,26 +55,26 @@ const getErrorMessage = (err: unknown, fallback: string) =>
  *   - mutationFn: `createPortfolio(api, data)`
  *   - variables: `{ data: Partial<Portfolio> }`
  *   - success message: "Portfolio created successfully."
- *   - error message: "We couldn't create the portfolio. Please review your inputs and try again." (fallback)
+ *   - error message: "Unable to create the portfolio. Please try again." (fallback)
  *
  * - `update`:
  *   - mutationFn: `updatePortfolio(api, id, data)`
  *   - variables: `{ id: string; data: Partial<Portfolio> }`
  *   - success message: "Portfolio updated successfully."
- *   - error message: "We couldn't update the portfolio. Please try again." (fallback)
+ *   - error message: "Unable to update the portfolio. Please try again." (fallback)
  *
  * - `remove`:
  *   - mutationFn: `deletePortfolio(api, id, workspace)`
  *   - variables: `{ id: string; workspace: string }`
  *   - success message: "Portfolio deleted successfully."
- *   - error message: "We couldn't delete the portfolio. Please try again." (fallback)
+ *   - error message: "Unable to delete the portfolio. Please try again." (fallback)
  *
  * Return value:
  * @returns {object}
  *  Returns an object with the three TanStack Query mutation results:
  *  - `create`: UseMutationResult<Portfolio, Error, CreatePortfolioProps, unknown>
  *  - `update`: UseMutationResult<Portfolio, Error, UpdatePortfolioProps, unknown>
- *  - `remove`: UseMutationResult<Portfolio, Error, DeletePortfolioProps, unknown>
+ *  - `remove`: UseMutationResult<DeletedEntity, Error, DeletePortfolioProps, unknown>
  *
  * Each mutation includes standard TanStack Query helpers:
  * - `mutate(variables, options?)`
@@ -92,7 +87,7 @@ const getErrorMessage = (err: unknown, fallback: string) =>
  * ```ts
  * const { create, update, remove } = usePortfolioMutations({ queryKey: ["portfolio"] });
  *
-  * // Create (minimal example - other Security fields omitted for brevity)
+ * // Create (minimal example - other Security fields omitted for brevity)
  * create.mutate({
  *   data: {
  *     name: "My Portfolio",
@@ -178,72 +173,27 @@ const getErrorMessage = (err: unknown, fallback: string) =>
 
 export const usePortfolioMutations = ({ queryKey }: UsePortfolioMutationsProps) => {
     const { api } = useAxios();
-    const { showAlert } = useAppAlert();
-    const queryClient = useQueryClient();
-
-    const invalidate = async () => {
-        if (!queryKey?.length) return;
-        await queryClient.invalidateQueries({ queryKey });
-    };
 
-    const create = useMutation({
-        mutationFn: async ({ data }: CreatePortfolioProps) => createPortfolio(api, data),
-        onSuccess: async () => {
-            await invalidate();
-            showAlert({
-                severity: "success",
-                message: "Portfolio created successfully.",
-            });
-        },
-        onError: (err: unknown) => {
-            showAlert({
-                severity: "error",
-                message: getErrorMessage(
-                    err,
-                    "We couldn't create the portfolio. Please review your inputs and try again."
-                ),
-            });
-        },
+    const create = useEntityMutation({
+        mutationFn: ({ data }: CreatePortfolioProps) => createPortfolio(api, data),
+        queryKey,
+        successMessage: "Portfolio created successfully.",
+        errorMessage: "Unable to create the portfolio. Please try again.",
     });
 
-    const update = useMutation({
-        mutationFn: async ({ id, data }: UpdatePortfolioProps) => updatePortfolio(api, id, data),
-        onSuccess: async () => {
-            await invalidate();
-            showAlert({
-                severity: "success",
-                message: "Portfolio updated successfully.",
-            });
-        },
-        onError: (err: unknown) => {
-            showAlert({
-                severity: "error",
-                message: getErrorMessage(
-                    err,
-                    "We couldn't update the portfolio. Please try again."
-                ),
-            });
-        },
+    const update = useEntityMutation({
+        mutationFn: ({ id, data }: UpdatePortfolioProps) => updatePortfolio(api, id, data),
+        queryKey,
+        successMessage: "Portfolio updated successfully.",
+        errorMessage: "Unable to update the portfolio. Please try again.",
     });
 
-    const remove = useMutation({
-        mutationFn: async ({ id, workspace }: DeletePortfolioProps) => deletePortfolio(api, id, workspace),
-        onSuccess: async () => {
-            await invalidate();
-            showAlert({
-                severity: "success",
-                message: "Portfolio deleted successfully.",
-            });
-        },
-        onError: (err: unknown) => {
-            showAlert({
-                severity: "error",
-                message: getErrorMessage(
-                    err,
-                    "We couldn't delete the portfolio. Please try again."
-                ),
-            });
-        },
+    const remove = useEntityMutation({
+        mutationFn: ({ id, workspace }: DeletePortfolioProps) =>
+            deletePortfolio(api, id, workspace),
+        queryKey,
+        successMessage: "Portfolio deleted successfully.",
+        errorMessage: "Unable to delete the portfolio. Please try again.",
     });
 
     return { create, update, remove };

package/src/hooks/profile/useFetchProfile.ts

@@ -1,26 +1,20 @@
-import { useEffect } from "react";
-
-import { useQuery } from "@tanstack/react-query";
-
 import { useAxios } from "@/hooks/useAxios";
-import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
-import type { Profile } from "@/types/profile";
+import { useEntityQuery } from "@/hooks/useEntityQuery";
 import { getProfile } from "@/api/profile";
-import type { EntityQueryOptions } from "@/types/entityQuery";
+import type { Profile } from "@/types/profile";
+import type { FetchEntityProps, EntityQueryOptions } from "@/types/entityQuery";
 
-export type FetchProfileProps<TData = Profile, TSelected = TData> = {
-    queryOptions?: EntityQueryOptions<TData, TSelected>;
-    /**
-     * Served instead of calling the API. Pass `DEV_PROFILE` while running the dev server,
-     * where `/api/profile` has no session to resolve.
-     */
+export type FetchProfileProps<TData = Profile, TSelected = TData> = FetchEntityProps<
+    TData,
+    TSelected
+> & {
     fallback?: Profile;
 };
 
 // The logged user's profile does not change during a session, so it is fetched once and kept —
 // unlike the entity hooks (staleTime/gcTime 0, refetch on every mount), which read data the
 // platform keeps changing.
-const defaultQueryOptions: EntityQueryOptions<Profile> = {
+const profileQueryOptions: EntityQueryOptions<Profile> = {
     staleTime: Infinity,
     refetchOnMount: false,
     refetchOnWindowFocus: false,
@@ -29,65 +23,30 @@ const defaultQueryOptions: EntityQueryOptions<Profile> = {
 /**
  * useFetchProfile
  *
- * Data-fetching hook built on TanStack Query to retrieve the profile of the logged user. It takes
- * no identifier: the API resolves the user from the session.
- *
- * It also:
- * - builds a stable React Query `queryKey`, shared by every consumer, so the profile is fetched
- *   once per session and read from cache afterwards
- * - triggers an error alert via `useAppAlert` whenever `query.error` is present
- *
- * Parameters (FetchProfileProps):
- * @param queryOptions
- *   TanStack Query options passed through to `useQuery` (e.g., enabled, staleTime, gcTime, etc.).
- *   Defaults keep the profile cached for the whole session.
- * @param fallback
- *   Served instead of calling the API. `/api/profile` only resolves in production, so an app
- *   running the dev server passes `DEV_PROFILE` here:
- *   `useFetchProfile({ fallback: import.meta.env.DEV ? DEV_PROFILE : undefined })`.
- *   The SDK cannot make that choice itself — see `getProfile`.
+ * Fetches the logged user's profile, once per session; `data` is the profile, or whatever
+ * `select` makes of it. `fallback` is what `getProfile` returns when the platform has none to
+ * give — see `getProfile` for why it is a parameter. A failure is shown as an error alert.
  *
- * Returns:
- * @returns {object}
- *   TanStack Query's `query` object extended with:
- *   - `queryKey`: the cache key used by React Query
- *
- * Example:
- * ```ts
- * const { data, isPending } = useFetchProfile();
- * // data -> Profile
- * ```
+ * @param {FetchProfileProps} [props] - `fallback`, `select` and TanStack `queryOptions`, merged
+ *   over the fetched-once defaults.
+ * @returns {object} The `useQuery` result, plus `queryKey`.
  */
-export const useFetchProfile = ({
-    queryOptions = defaultQueryOptions,
+export const useFetchProfile = <TSelected = Profile>({
     fallback,
-}: FetchProfileProps = {}) => {
-
+    select,
+    queryOptions,
+}: FetchProfileProps<Profile, TSelected> = {}) => {
     const { api } = useAxios();
-    const { showAlert } = useAppAlert();
 
     const queryKey = ["profile"];
 
-    const query = useQuery<Profile>({
+    const query = useEntityQuery<Profile, TSelected>({
         queryKey,
-        queryFn: async () => {
-            const profile = await getProfile(api, fallback);
-            return profile;
-        },
-        ...queryOptions ?? {}
+        fetchEntity: (signal) => getProfile(api, fallback, signal),
+        select,
+        defaultQueryOptions: profileQueryOptions as EntityQueryOptions<Profile, TSelected>,
+        queryOptions,
     });
 
-    useEffect(() => {
-        if (!query.error) return;
-
-        showAlert({
-            severity: "error",
-            message: query.error.message,
-        });
-    }, [query.error, showAlert]);
-
-    return {
-        ...query,
-        queryKey,
-    };
+    return { ...query, queryKey };
 };

package/src/hooks/useAxios.ts

@@ -43,7 +43,6 @@ import { useAppConfig } from "@/contexts/appConfigContext/useAppConfig";
  */
 
 export const useAxios = (url: string | null = null) => {
-
     const reqInterceptorId = useRef<number | null>(null);
     const { appId } = useAppConfig();
 
@@ -68,11 +67,12 @@ export const useAxios = (url: string | null = null) => {
                         const queryObj = typeof rawQuery === "string" ? JSON.parse(rawQuery) : null;
 
                         const workspaceFilter = queryObj?.filters?.find(
-                            (filter: FilterExpression) => filter?.[0] === "workspace"
+                            (filter: FilterExpression) => filter?.[0] === "workspace",
                         );
 
-                        const workspace =
-                            Array.isArray(workspaceFilter) ? workspaceFilter[workspaceFilter.length - 1] : null;
+                        const workspace = Array.isArray(workspaceFilter)
+                            ? workspaceFilter[workspaceFilter.length - 1]
+                            : null;
 
                         if (workspace) {
                             config.params = { ...params, workspace };
@@ -83,7 +83,7 @@ export const useAxios = (url: string | null = null) => {
                 }
 
                 return config;
-            }
+            },
         );
 
         return () => {

package/src/hooks/useEntityInfiniteQuery.ts

@@ -0,0 +1,193 @@
+import { useCallback } from "react";
+import { useInfiniteQuery, type QueryKey } from "@tanstack/react-query";
+
+import type {
+    PagedResponse,
+    EntityInfiniteQueryOptions,
+    ListCache,
+    PageToken,
+} from "@/types/entityQuery";
+
+/**
+ * Ceiling on `fetchAllPages`. Reaching it fails the read instead of returning what was read so
+ * far: a cursor that never ends is a bug, and a consolidated view shown from a partial read is
+ * a wrong answer that looks right. A set legitimately this long wants a larger `pageSize`.
+ */
+export const FETCH_ALL_PAGES_LIMIT = 100;
+
+/** The element type of a page's item array. */
+export type ItemOf<TPage, K extends keyof TPage> = TPage[K] extends (infer TItem)[] ? TItem : never;
+
+export type EntityInfiniteQueryProps<TPage extends PagedResponse, K extends keyof TPage, TData> = {
+    /**
+     * Must describe everything that changes the response, `fetchAllPages` included, or two reads
+     * share one cache entry. Build it with `buildQueryKey(keys, filters, { order, projection,
+     * pageSize, fetchAllPages })`, and return it from your hook so callers can write to the cache.
+     */
+    queryKey: QueryKey;
+    /** Where a page keeps its items (`"datastores"`, `"files"`, …). */
+    itemsKey: K;
+    /**
+     * Requests one page; `undefined` asks for the first. `signal` aborts when no screen wants the
+     * read any more — pass it to the request (`api.get(url, { signal })`) to cancel it in flight.
+     */
+    fetchPage: (pageToken: string | undefined, signal?: AbortSignal) => Promise<TPage>;
+    select?: (items: ItemOf<TPage, K>[]) => TData;
+    fetchAllPages?: boolean;
+    /**
+     * Your hook's own precondition for something legitimately not there yet (a selection the
+     * user has not made), ANDed with the caller's `queryOptions.enabled`. Unmet, the query stays
+     * idle. For something that should always be there, use `configError`: idle hides it.
+     */
+    enabled?: boolean;
+    /**
+     * Why the request cannot be right, when it cannot — `missingWorkspaceError(hookName)` in the
+     * SDK's hooks. Set, the query fails at once with it as the error, without a request or a
+     * retry, and logs it with `console.error` once per message, in every environment: a
+     * misconfigured app shows up in the browser console and in test output, not as an empty
+     * screen.
+     * It is reported even while `enabled` is unmet, so an empty id cannot hide a misconfigured
+     * workspace; only the caller's `queryOptions.enabled: false` holds it back.
+     */
+    configError?: string;
+    queryOptions?: EntityInfiniteQueryOptions<TPage, TData>;
+};
+
+/** The `configError` messages already logged, so a render loop does not flood the console. */
+const loggedConfigErrors = new Set<string>();
+
+/**
+ * Fails a query with its `configError`, logging it the first time. Shared by the SDK's query
+ * hooks.
+ */
+export const failWithConfigError = (configError: string): never => {
+    if (!loggedConfigErrors.has(configError)) {
+        loggedConfigErrors.add(configError);
+        console.error(configError);
+    }
+
+    throw new Error(configError);
+};
+
+const defaultQueryOptions = {
+    refetchOnMount: "always",
+    staleTime: 0,
+    gcTime: 0,
+} as const;
+
+/**
+ * Reads every page into one page, so the cache holds a single entry for the whole set and a
+ * refetch rereads all of it.
+ *
+ * Stops as soon as `signal` aborts. TanStack aborts it when the last screen reading the query
+ * unmounts — only because the query function takes it — and without this check the loop would
+ * go on requesting every remaining page for nobody.
+ */
+const fetchEveryPage = async <TPage extends PagedResponse, K extends keyof TPage>(
+    fetchPage: (pageToken: string | undefined, signal?: AbortSignal) => Promise<TPage>,
+    itemsKey: K,
+    signal: AbortSignal,
+): Promise<TPage> => {
+    let page = await fetchPage(undefined, signal);
+    const items = [...(page[itemsKey] as unknown[])];
+
+    for (let count = 1; page.next_page_token; count++) {
+        signal.throwIfAborted();
+
+        if (count >= FETCH_ALL_PAGES_LIMIT) {
+            throw new Error(
+                `fetchAllPages stopped after ${FETCH_ALL_PAGES_LIMIT} pages without reaching the end. ` +
+                    "Raise pageSize, or page on demand instead.",
+            );
+        }
+
+        page = await fetchPage(page.next_page_token, signal);
+        items.push(...(page[itemsKey] as unknown[]));
+    }
+
+    return { ...page, [itemsKey]: items, next_page_token: null };
+};
+
+/**
+ * useEntityInfiniteQuery
+ *
+ * The list hook every SDK list hook is built on, and the one to build on for an endpoint the
+ * SDK does not cover. A hook says how to request a page and where its items are; this merges
+ * the pages, applies the caller's `select`, and owns the paging modes (`fetchAllPages`, and
+ * `fetchNextPage` for `handleRowsScrollEnd`). It replaced seven copies of the same
+ * `useInfiniteQuery` call, which is how one `select` defect had reached all seven — an app
+ * copying a list hook instead of composing this would copy the next one too.
+ *
+ * `select` is composed with the merging after the caller's options are spread, so nothing in
+ * `queryOptions` can replace it. The composed function is memoised on the caller's `select`:
+ * TanStack skips a select whose data and reference are both unchanged.
+ *
+ * @returns {UseInfiniteQueryResult} The `useInfiniteQuery` result; `data` is the merged items,
+ *   or what `select` makes of them.
+ *
+ * Example:
+ * ```ts
+ * export const useFetchReports = <TData = Report[]>({ workspace, select, fetchAllPages = false }: Props<TData>) => {
+ *   const { api } = useAxios();
+ *   const filters = [{ field: "workspace", value: workspace }];
+ *   const queryKey = buildQueryKey(["reports"], filters, { fetchAllPages });
+ *
+ *   const query = useEntityInfiniteQuery<ReportListResponse, "reports", TData>({
+ *     queryKey,
+ *     itemsKey: "reports",
+ *     fetchPage: (pageToken) => listReports(api, workspace, pageToken),
+ *     select,
+ *     fetchAllPages,
+ *     configError: hasWorkspaceFilter(filters) ? undefined : missingWorkspaceError("useFetchReports"),
+ *   });
+ *
+ *   return { query, queryKey };
+ * };
+ * ```
+ */
+export function useEntityInfiniteQuery<
+    TPage extends PagedResponse,
+    K extends keyof TPage,
+    TData = ItemOf<TPage, K>[],
+>({
+    queryKey,
+    itemsKey,
+    fetchPage,
+    select,
+    fetchAllPages = false,
+    enabled = true,
+    configError,
+    queryOptions,
+}: EntityInfiniteQueryProps<TPage, K, TData>) {
+    const selectMerged = useCallback(
+        (data: ListCache<TPage>): TData => {
+            const items = data.pages.flatMap((page) => page[itemsKey] as ItemOf<TPage, K>[]);
+            return select ? select(items) : (items as unknown as TData);
+        },
+        [itemsKey, select],
+    );
+
+    return useInfiniteQuery<TPage, Error, TData, QueryKey, PageToken>({
+        ...defaultQueryOptions,
+        ...queryOptions,
+
+        queryKey,
+        initialPageParam: null,
+        getNextPageParam: (lastPage) => lastPage.next_page_token ?? undefined,
+        queryFn: async ({ pageParam, signal }) => {
+            if (configError) return failWithConfigError(configError);
+
+            return fetchAllPages
+                ? fetchEveryPage(fetchPage, itemsKey, signal)
+                : fetchPage(pageParam ?? undefined, signal);
+        },
+        // A retry would rerun the same check and delay an error that cannot resolve itself.
+        ...(configError ? { retry: false } : {}),
+
+        select: selectMerged,
+        // A config error runs past the hook's own precondition, so that an empty id cannot hide a
+        // misconfigured workspace; the caller's `enabled` still wins. Kept as the caller wrote it,
+        // so a function still works.
+        enabled: configError || enabled ? (queryOptions?.enabled ?? true) : false,
+    });
+}