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

package/dist/hooks/datastore/useFetchDatastores.d.ts

@@ -1,70 +1,65 @@
-import { type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
-import type { DatastoreWithRows } from "../../types/datastore.d.ts";
-import type { FetchEntitiesParams, EntityDefaultResponse } from "../../types/entityQuery.d.ts";
-type PageToken = string | null;
-type InfiniteOptions<TData> = Omit<UseInfiniteQueryOptions<DatastoreQueryPage, Error, TData, QueryKey, PageToken>, "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam">;
-export type DatastoreQueryPage = EntityDefaultResponse & {
-    datastores: DatastoreWithRows[];
+import type { ParsedDatastore } from "../../types/datastore.d.ts";
+import type { DatastoreDataFormat } from "../../types/datastoreDataFormat.d.ts";
+import type { PagedResponse, FetchEntitiesProps, ListQueryProps, ListCache } from "../../types/entityQuery.d.ts";
+export type DatastoreQueryPage<F extends DatastoreDataFormat = "object"> = PagedResponse & {
+    datastores: ParsedDatastore<F>[];
 };
-export type FetchInfiniteDatastoreProps = FetchEntitiesParams<DatastoreWithRows[], InfiniteOptions<DatastoreWithRows[]>> & {
-    pageSize?: number;
+/** The query cache of `useFetchDatastores`, for typing `setQueryData`. */
+export type DatastoresCache<F extends DatastoreDataFormat = "object"> = ListCache<DatastoreQueryPage<F>>;
+export type FetchDatastoresProps<F extends DatastoreDataFormat = "object", TData = ParsedDatastore<F>[]> = ListQueryProps & FetchEntitiesProps<ParsedDatastore<F>, TData, DatastoreQueryPage<F>> & {
+    /**
+     * Tabular datastores only: `"object"` (default) turns the matrix into one object per row;
+     * `"matrix"` leaves the matrix, header row included. A JSON datastore's `data` is unchanged either way.
+     */
+    dataFormat?: F;
 };
 /**
  * useFetchDatastores
  *
- * Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve
- * datastores with cursor-based pagination.
+ * Lists datastores with cursor pagination. `query.data` is every loaded page merged into one
+ * `ParsedDatastore[]`, each datastore's matrix converted to row objects — or whatever
+ * `select` makes of that list.
  *
- * It also:
- * - flattens all pages into a single `DatastoreWithRows[]` via `select`
- * - exposes `actions` for cache management
- * - exposes `events` for ag-Grid integration
+ * Built to be used directly rather than wrapped: `select` shapes the result, `queryKey` and
+ * `DatastoresCache` let an app write to the cache, and `fetchAllPages` reads a whole set.
+ * Paging on grid scroll is `handleRowsScrollEnd` from `@everysk/apps-sdk/ag-grid`, kept out of
+ * this hook so it works for any list.
  *
- * Important notes:
- * - `query.data` returns a flat `DatastoreWithRows[]` (all pages merged).
- * - Each item retains the full `Datastore` shape, with `data` replaced by `AnyRecord[]` (rows transformed via `tableToObjects`).
+ * Without a `workspace` filter, or with an empty one, the read fails at once with an error
+ * naming this hook, logged to the console, and no request is sent. The app config is in place
+ * before the app renders, so a missing workspace is a misconfigured app, never a wait.
  *
- * Parameters (FetchInfiniteDatastoreProps):
- * @param {FilterClause[]} [filters=[]]
- *   Filters applied to every page request. Must include a `workspace` filter.
+ * Rows are converted in the request (`parseDatastore`), so the cache holds objects and an
+ * app patches a row as `{ ...row, ...patch }`. `dataFormat: "matrix"` skips the conversion and
+ * leaves a tabular datastore's matrix unconverted, for a grid that takes arrays, an export, or a
+ * datastore too large to convert. It is a value, not a conversion function, so that it can be
+ * part of the cache key: two callers converting differently would otherwise share one entry.
  *
- * @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 datastores to fetch per page.
- *
- * @param {InfiniteOptions<DatastoreWithRows[]>} [queryOptions]
- *   TanStack Query options passed through to `useInfiniteQuery`
- *   (e.g., enabled, staleTime, gcTime, etc.).
- *
- * Returns:
- * @returns {object}
- *   - `query`: the full `useInfiniteQuery` result (data, isLoading, hasNextPage, fetchNextPage, etc.)
- *   - `queryKey`: the cache key used by React Query
- *   - `events.handleFetchIfGridEmptyOrNearEnd(gridApi)`: triggers next page fetch when the ag-Grid is empty or near the end of the list
+ * @param {FilterClause[]} [filters=[]] - Filters of every page request; one must be `workspace`.
+ * @param {string[]} [order=[]] - Sorting of every page request.
+ * @param {Projection} [projection=""] - The fields to return, one or a list: `"field"` returns
+ *   only that field (others come back null), `"-field"` every field but that one. Several go as a
+ *   list, never comma-joined — `"a,b"` is a 500.
+ * @param {number} [pageSize=10] - Datastores per request.
+ * @param {"object" | "matrix"} [dataFormat="object"] - How a table's rows are handed over.
+ * @param {(datastores: ParsedDatastore[]) => TData} [select] - Shapes the merged list.
+ * @param {boolean} [fetchAllPages=false] - Reads to the last page before reporting success.
+ * @param {EntityInfiniteQueryOptions} [queryOptions] - Passed through to `useInfiniteQuery`.
+ * @returns {object} `query` (the `useInfiniteQuery` result) and `queryKey`.
  *
  * Example:
  * ```ts
- * const { query, events } = useFetchDatastores({
- *   filters: [{ field: "workspace", value: "ws-1" }],
- *   pageSize: 20,
- * });
- *
- * // Flat list of all fetched datastores with transformed rows
- * const datastores = query.data ?? [];
+ * // A list can mix tabular and JSON datastores; only a table's `data` is rows.
+ * const toRows = (datastores: ParsedDatastore[]) => datastores.filter(isTableDatastore).flatMap((d) => d.data);
  *
- * // Load next page when grid is near end
- * <AgGridReact onBodyScroll={() => events.handleFetchIfGridEmptyOrNearEnd(gridApi)} />
+ * const { query } = useFetchDatastores({
+ *   filters: [{ field: "workspace", value: workspace }],
+ *   select: toRows, // query.data: AnyRecord[]
+ * });
  * ```
  */
-export declare function useFetchDatastores({ filters, order, projection, pageSize, queryOptions }: FetchInfiniteDatastoreProps): {
-    query: import("@tanstack/react-query").UseInfiniteQueryResult<DatastoreWithRows[], Error>;
+export declare function useFetchDatastores<F extends DatastoreDataFormat = "object", TData = ParsedDatastore<F>[]>({ filters, order, projection, pageSize, dataFormat, select, fetchAllPages, queryOptions, }: FetchDatastoresProps<F, TData>): {
+    query: import("@tanstack/react-query").UseInfiniteQueryResult<TData, Error>;
     queryKey: unknown[];
 };
-export {};
 //# sourceMappingURL=useFetchDatastores.d.ts.map

package/dist/hooks/datastore/useFetchDatastores.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFetchDatastores.d.ts","sourceRoot":"","sources":["../../../src/hooks/datastore/useFetchDatastores.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,KAAK,uBAAuB,EAAE,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAQtG,OAAO,KAAK,EAAoC,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC7F,OAAO,KAAK,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAGtF,KAAK,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC;AAE/B,KAAK,eAAe,CAAC,KAAK,IAAI,IAAI,CAC9B,uBAAuB,CAAC,kBAAkB,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,EAC9E,UAAU,GAAG,SAAS,GAAG,kBAAkB,GAAG,kBAAkB,CACnE,CAAC;AAGF,MAAM,MAAM,kBAAkB,GAAG,qBAAqB,GAAG;IACrD,UAAU,EAAE,iBAAiB,EAAE,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG,mBAAmB,CAAC,iBAAiB,EAAE,EAAE,eAAe,CAAC,iBAAiB,EAAE,CAAC,CAAC,GAAG;IACvH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAQF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,OAAY,EAAE,KAAU,EAAE,UAAe,EAAE,QAAa,EAAE,YAAY,EAAE,EAAE,2BAA2B;;;EAwEzI"}
+{"version":3,"file":"useFetchDatastores.d.ts","sourceRoot":"","sources":["../../../src/hooks/datastore/useFetchDatastores.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAyB,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EACR,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,SAAS,EACZ,MAAM,qBAAqB,CAAC;AAQ7B,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,mBAAmB,GAAG,QAAQ,IAAI,aAAa,GAAG;IACvF,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;CACpC,CAAC;AAEF,0EAA0E;AAC1E,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,mBAAmB,GAAG,QAAQ,IAAI,SAAS,CAC7E,kBAAkB,CAAC,CAAC,CAAC,CACxB,CAAC;AAEF,MAAM,MAAM,oBAAoB,CAC5B,CAAC,SAAS,mBAAmB,GAAG,QAAQ,EACxC,KAAK,GAAG,eAAe,CAAC,CAAC,CAAC,EAAE,IAC5B,cAAc,GACd,kBAAkB,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,GAAG;IACnE;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,CAAC;CAClB,CAAC;AAEN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,kBAAkB,CAC9B,CAAC,SAAS,mBAAmB,GAAG,QAAQ,EACxC,KAAK,GAAG,eAAe,CAAC,CAAC,CAAC,EAAE,EAC9B,EACE,OAAY,EACZ,KAAU,EACV,UAAe,EACf,QAAa,EACb,UAAU,EACV,MAAM,EACN,aAAqB,EACrB,YAAY,GACf,EAAE,oBAAoB,CAAC,CAAC,EAAE,KAAK,CAAC;;;EAsChC"}

package/dist/hooks/datastore/useFetchDatastores.js

@@ -1,100 +1,85 @@
 import { useAxios } from "../useAxios.js";
-import { buildQueryKey, buildQueryObject } from "../../api/entityQuery.js";
+import { useEntityInfiniteQuery } from "../useEntityInfiniteQuery.js";
+import { buildQueryKey, buildQueryObject, hasWorkspaceFilter, missingWorkspaceError } from "../../api/entityQuery.js";
 import { listDatastores } from "../../api/datastore.js";
-import { tableToObjects } from "../../lib/datastoreTable.js";
-import { useMemo } from "react";
-import { useInfiniteQuery } from "@tanstack/react-query";
+import { parseDatastore } from "../../lib/datastoreTable.js";
 //#region src/hooks/datastore/useFetchDatastores.ts
-var defaultQueryOptions = {
-	refetchOnMount: "always",
-	staleTime: 0,
-	gcTime: 0
-};
 /**
 * useFetchDatastores
 *
-* Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve
-* datastores with cursor-based pagination.
+* Lists datastores with cursor pagination. `query.data` is every loaded page merged into one
+* `ParsedDatastore[]`, each datastore's matrix converted to row objects — or whatever
+* `select` makes of that list.
 *
-* It also:
-* - flattens all pages into a single `DatastoreWithRows[]` via `select`
-* - exposes `actions` for cache management
-* - exposes `events` for ag-Grid integration
+* Built to be used directly rather than wrapped: `select` shapes the result, `queryKey` and
+* `DatastoresCache` let an app write to the cache, and `fetchAllPages` reads a whole set.
+* Paging on grid scroll is `handleRowsScrollEnd` from `@everysk/apps-sdk/ag-grid`, kept out of
+* this hook so it works for any list.
 *
-* Important notes:
-* - `query.data` returns a flat `DatastoreWithRows[]` (all pages merged).
-* - Each item retains the full `Datastore` shape, with `data` replaced by `AnyRecord[]` (rows transformed via `tableToObjects`).
+* Without a `workspace` filter, or with an empty one, the read fails at once with an error
+* naming this hook, logged to the console, and no request is sent. The app config is in place
+* before the app renders, so a missing workspace is a misconfigured app, never a wait.
 *
-* Parameters (FetchInfiniteDatastoreProps):
-* @param {FilterClause[]} [filters=[]]
-*   Filters applied to every page request. Must include a `workspace` filter.
+* Rows are converted in the request (`parseDatastore`), so the cache holds objects and an
+* app patches a row as `{ ...row, ...patch }`. `dataFormat: "matrix"` skips the conversion and
+* leaves a tabular datastore's matrix unconverted, for a grid that takes arrays, an export, or a
+* datastore too large to convert. It is a value, not a conversion function, so that it can be
+* part of the cache key: two callers converting differently would otherwise share one entry.
 *
-* @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 datastores to fetch per page.
-*
-* @param {InfiniteOptions<DatastoreWithRows[]>} [queryOptions]
-*   TanStack Query options passed through to `useInfiniteQuery`
-*   (e.g., enabled, staleTime, gcTime, etc.).
-*
-* Returns:
-* @returns {object}
-*   - `query`: the full `useInfiniteQuery` result (data, isLoading, hasNextPage, fetchNextPage, etc.)
-*   - `queryKey`: the cache key used by React Query
-*   - `events.handleFetchIfGridEmptyOrNearEnd(gridApi)`: triggers next page fetch when the ag-Grid is empty or near the end of the list
+* @param {FilterClause[]} [filters=[]] - Filters of every page request; one must be `workspace`.
+* @param {string[]} [order=[]] - Sorting of every page request.
+* @param {Projection} [projection=""] - The fields to return, one or a list: `"field"` returns
+*   only that field (others come back null), `"-field"` every field but that one. Several go as a
+*   list, never comma-joined — `"a,b"` is a 500.
+* @param {number} [pageSize=10] - Datastores per request.
+* @param {"object" | "matrix"} [dataFormat="object"] - How a table's rows are handed over.
+* @param {(datastores: ParsedDatastore[]) => TData} [select] - Shapes the merged list.
+* @param {boolean} [fetchAllPages=false] - Reads to the last page before reporting success.
+* @param {EntityInfiniteQueryOptions} [queryOptions] - Passed through to `useInfiniteQuery`.
+* @returns {object} `query` (the `useInfiniteQuery` result) and `queryKey`.
 *
 * Example:
 * ```ts
-* const { query, events } = useFetchDatastores({
-*   filters: [{ field: "workspace", value: "ws-1" }],
-*   pageSize: 20,
-* });
-*
-* // Flat list of all fetched datastores with transformed rows
-* const datastores = query.data ?? [];
+* // A list can mix tabular and JSON datastores; only a table's `data` is rows.
+* const toRows = (datastores: ParsedDatastore[]) => datastores.filter(isTableDatastore).flatMap((d) => d.data);
 *
-* // Load next page when grid is near end
-* <AgGridReact onBodyScroll={() => events.handleFetchIfGridEmptyOrNearEnd(gridApi)} />
+* const { query } = useFetchDatastores({
+*   filters: [{ field: "workspace", value: workspace }],
+*   select: toRows, // query.data: AnyRecord[]
+* });
 * ```
 */
-function useFetchDatastores({ filters = [], order = [], projection = "", pageSize = 10, queryOptions }) {
+function useFetchDatastores({ filters = [], order = [], projection = "", pageSize = 10, dataFormat, select, fetchAllPages = false, queryOptions }) {
 	const { api } = useAxios();
-	const queryKey = buildQueryKey(["datastores"], filters);
-	const mergedQueryOptions = useMemo(() => ({
-		...defaultQueryOptions,
-		...queryOptions ?? {}
-	}), [queryOptions]);
+	const format = dataFormat ?? "object";
+	const queryKey = buildQueryKey(["datastores"], filters, {
+		order,
+		projection,
+		pageSize,
+		fetchAllPages,
+		dataFormat: format
+	});
 	return {
-		query: useInfiniteQuery({
+		query: useEntityInfiniteQuery({
 			queryKey,
-			initialPageParam: null,
-			getNextPageParam: (lastPage) => lastPage.next_page_token ?? void 0,
-			queryFn: async ({ pageParam }) => {
-				const queryFilter = buildQueryObject({
+			itemsKey: "datastores",
+			fetchPage: async (pageToken, signal) => {
+				const response = await listDatastores(api, buildQueryObject({
 					filters,
 					order,
 					projection,
 					pageSize,
-					pageToken: pageParam ?? void 0
-				});
-				const response = await listDatastores(api, queryFilter);
-				const nested = response.datastores.map((datastore) => ({
-					...datastore,
-					data: tableToObjects(datastore.id, datastore.data?.[0], datastore.data)
-				}));
+					pageToken
+				}), signal);
 				return {
 					next_page_token: response.next_page_token,
-					datastores: nested
+					datastores: response.datastores.map((datastore) => parseDatastore(datastore, format))
 				};
 			},
-			select: (data) => data.pages.flatMap((p) => p.datastores),
-			...mergedQueryOptions
+			select,
+			fetchAllPages,
+			configError: hasWorkspaceFilter(filters) ? void 0 : missingWorkspaceError("useFetchDatastores"),
+			queryOptions
 		}),
 		queryKey
 	};

package/dist/hooks/datastore/useFetchDatastores.js.map

@@ -1 +1 @@
-{"version":3,"file":"useFetchDatastores.js","names":[],"sources":["../../../src/hooks/datastore/useFetchDatastores.ts"],"sourcesContent":["//import { useCallback, useMemo, useRef } from \"react\";\nimport { useMemo } from \"react\";\nimport { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from \"@tanstack/react-query\";\n\n//import type { GridApi } from \"ag-grid-community\";\n\nimport { useAxios } from \"@/hooks/useAxios\";\nimport { tableToObjects } from \"@/lib/datastoreTable\";\nimport { listDatastores } from \"@/api/datastore\";\n\nimport type { Datastore, DatastoreListResponse, DatastoreWithRows } from \"@/types/datastore\";\nimport type { FetchEntitiesParams, EntityDefaultResponse } from \"@/types/entityQuery\";\nimport { buildQueryKey, buildQueryObject } from \"@/api/entityQuery\";\n\ntype PageToken = string | null;\n\ntype InfiniteOptions<TData> = Omit<\n    UseInfiniteQueryOptions<DatastoreQueryPage, Error, TData, QueryKey, PageToken>,\n    \"queryKey\" | \"queryFn\" | \"initialPageParam\" | \"getNextPageParam\"\n>;\n\n\nexport type DatastoreQueryPage = EntityDefaultResponse & {\n    datastores: DatastoreWithRows[];\n};\n\nexport type FetchInfiniteDatastoreProps = FetchEntitiesParams<DatastoreWithRows[], InfiniteOptions<DatastoreWithRows[]>> & {\n    pageSize?: number;\n};\n\nconst defaultQueryOptions: InfiniteOptions<DatastoreWithRows[]> = {\n    refetchOnMount: \"always\",\n    staleTime: 0,\n    gcTime: 0,\n};\n\n/**\n * useFetchDatastores\n *\n * Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve\n * datastores with cursor-based pagination.\n *\n * It also:\n * - flattens all pages into a single `DatastoreWithRows[]` via `select`\n * - exposes `actions` for cache management\n * - exposes `events` for ag-Grid integration\n *\n * Important notes:\n * - `query.data` returns a flat `DatastoreWithRows[]` (all pages merged).\n * - Each item retains the full `Datastore` shape, with `data` replaced by `AnyRecord[]` (rows transformed via `tableToObjects`).\n *\n * Parameters (FetchInfiniteDatastoreProps):\n * @param {FilterClause[]} [filters=[]]\n *   Filters applied to every page request. Must include a `workspace` filter.\n *\n * @param {string[]} [order=[]]\n *   Sorting applied to every page request.\n *\n * @param {string} [projection=\"\"]\n *   Single field to project: `\"field\"` returns only that field (others come back null),\n *   `\"-field\"` returns every field except that one. One field only — lists 500. Omitted when empty.\n *\n * @param {number} [pageSize=10]\n *   Number of datastores to fetch per page.\n *\n * @param {InfiniteOptions<DatastoreWithRows[]>} [queryOptions]\n *   TanStack Query options passed through to `useInfiniteQuery`\n *   (e.g., enabled, staleTime, gcTime, etc.).\n *\n * Returns:\n * @returns {object}\n *   - `query`: the full `useInfiniteQuery` result (data, isLoading, hasNextPage, fetchNextPage, etc.)\n *   - `queryKey`: the cache key used by React Query\n *   - `events.handleFetchIfGridEmptyOrNearEnd(gridApi)`: triggers next page fetch when the ag-Grid is empty or near the end of the list\n *\n * Example:\n * ```ts\n * const { query, events } = useFetchDatastores({\n *   filters: [{ field: \"workspace\", value: \"ws-1\" }],\n *   pageSize: 20,\n * });\n *\n * // Flat list of all fetched datastores with transformed rows\n * const datastores = query.data ?? [];\n *\n * // Load next page when grid is near end\n * <AgGridReact onBodyScroll={() => events.handleFetchIfGridEmptyOrNearEnd(gridApi)} />\n * ```\n */\nexport function useFetchDatastores({ filters = [], order = [], projection = \"\", pageSize = 10, queryOptions }: FetchInfiniteDatastoreProps) {\n    const { api } = useAxios();\n\n    //const fetchingGuardRef = useRef(false);\n    const queryKey = buildQueryKey([\"datastores\"], filters);\n\n    const mergedQueryOptions = useMemo<InfiniteOptions<DatastoreWithRows[]>>(() => ({\n        ...defaultQueryOptions,\n        ...(queryOptions ?? {}),\n    }), [queryOptions]);\n\n    const query = useInfiniteQuery<DatastoreQueryPage, Error, DatastoreWithRows[], QueryKey, PageToken>({\n        queryKey,\n        initialPageParam: null,\n        getNextPageParam: (lastPage) => lastPage.next_page_token ?? undefined,\n\n        queryFn: async ({ pageParam }) => {\n            const queryFilter = buildQueryObject({\n                filters,\n                order,\n                projection,\n                pageSize,\n                pageToken: pageParam ?? undefined,\n            });\n\n            const response: DatastoreListResponse = await listDatastores(api, queryFilter);\n\n            const nested: DatastoreWithRows[] = response.datastores.map((datastore: Datastore) => ({\n                ...datastore,\n                data: tableToObjects(\n                    datastore.id,\n                    datastore.data?.[0] as string[],\n                    datastore.data\n                ),\n            }));\n\n            return {\n                next_page_token: response.next_page_token,\n                datastores: nested,\n            };\n        },\n\n        select: (data) => data.pages.flatMap((p) => p.datastores),\n\n        ...mergedQueryOptions,\n    });\n\n    /*\n    const { hasNextPage, isFetchingNextPage, fetchNextPage } = query;\n    const handleFetchIfGridEmptyOrNearEnd = useCallback((gridApi: GridApi) => {\n        if (!hasNextPage || isFetchingNextPage || fetchingGuardRef.current) return;\n\n        const total = gridApi.getDisplayedRowCount();\n        const last = gridApi.getLastDisplayedRowIndex();\n\n        const isEmpty = total === 0 || last < 0;\n        const isNearEnd = !isEmpty && (total - 1 - last) <= 30;\n\n        if (!isEmpty && !isNearEnd) return;\n\n        fetchingGuardRef.current = true;\n        fetchNextPage().finally(() => {\n            fetchingGuardRef.current = false;\n        });\n    }, [hasNextPage, isFetchingNextPage, fetchNextPage]);\n    */\n\n    return {\n        query,\n        queryKey,\n        //events: { handleFetchIfGridEmptyOrNearEnd },\n    };\n}"],"mappings":";;;;;;;AA8BA,IAAM,sBAA4D;CAC9D,gBAAgB;CAChB,WAAW;CACX,QAAQ;AACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDA,SAAgB,mBAAmB,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,GAAG,aAAa,IAAI,WAAW,IAAI,gBAA6C;CACxI,MAAM,EAAE,QAAQ,SAAS;CAGzB,MAAM,WAAW,cAAc,CAAC,YAAY,GAAG,OAAO;CAEtD,MAAM,qBAAqB,eAAqD;EAC5E,GAAG;EACH,GAAI,gBAAgB,CAAC;CACzB,IAAI,CAAC,YAAY,CAAC;CA0DlB,OAAO;EACH,OAzDU,iBAAsF;GAChG;GACA,kBAAkB;GAClB,mBAAmB,aAAa,SAAS,mBAAmB,KAAA;GAE5D,SAAS,OAAO,EAAE,gBAAgB;IAC9B,MAAM,cAAc,iBAAiB;KACjC;KACA;KACA;KACA;KACA,WAAW,aAAa,KAAA;IAC5B,CAAC;IAED,MAAM,WAAkC,MAAM,eAAe,KAAK,WAAW;IAE7E,MAAM,SAA8B,SAAS,WAAW,KAAK,eAA0B;KACnF,GAAG;KACH,MAAM,eACF,UAAU,IACV,UAAU,OAAO,IACjB,UAAU,IACd;IACJ,EAAE;IAEF,OAAO;KACH,iBAAiB,SAAS;KAC1B,YAAY;IAChB;GACJ;GAEA,SAAS,SAAS,KAAK,MAAM,SAAS,MAAM,EAAE,UAAU;GAExD,GAAG;EACP,CAuBI;EACA;CAEJ;AACJ"}
+{"version":3,"file":"useFetchDatastores.js","names":[],"sources":["../../../src/hooks/datastore/useFetchDatastores.ts"],"sourcesContent":["import { useAxios } from \"@/hooks/useAxios\";\nimport { useEntityInfiniteQuery } from \"@/hooks/useEntityInfiniteQuery\";\nimport { parseDatastore } from \"@/lib/datastoreTable\";\nimport { listDatastores } from \"@/api/datastore\";\n\nimport type { DatastoreListResponse, ParsedDatastore } from \"@/types/datastore\";\nimport type { DatastoreDataFormat } from \"@/types/datastoreDataFormat\";\nimport type {\n    PagedResponse,\n    FetchEntitiesProps,\n    ListQueryProps,\n    ListCache,\n} from \"@/types/entityQuery\";\nimport {\n    buildQueryKey,\n    buildQueryObject,\n    hasWorkspaceFilter,\n    missingWorkspaceError,\n} from \"@/api/entityQuery\";\n\nexport type DatastoreQueryPage<F extends DatastoreDataFormat = \"object\"> = PagedResponse & {\n    datastores: ParsedDatastore<F>[];\n};\n\n/** The query cache of `useFetchDatastores`, for typing `setQueryData`. */\nexport type DatastoresCache<F extends DatastoreDataFormat = \"object\"> = ListCache<\n    DatastoreQueryPage<F>\n>;\n\nexport type FetchDatastoresProps<\n    F extends DatastoreDataFormat = \"object\",\n    TData = ParsedDatastore<F>[],\n> = ListQueryProps &\n    FetchEntitiesProps<ParsedDatastore<F>, TData, DatastoreQueryPage<F>> & {\n        /**\n         * Tabular datastores only: `\"object\"` (default) turns the matrix into one object per row;\n         * `\"matrix\"` leaves the matrix, header row included. A JSON datastore's `data` is unchanged either way.\n         */\n        dataFormat?: F;\n    };\n\n/**\n * useFetchDatastores\n *\n * Lists datastores with cursor pagination. `query.data` is every loaded page merged into one\n * `ParsedDatastore[]`, each datastore's matrix converted to row objects — or whatever\n * `select` makes of that list.\n *\n * Built to be used directly rather than wrapped: `select` shapes the result, `queryKey` and\n * `DatastoresCache` let an app write to the cache, and `fetchAllPages` reads a whole set.\n * Paging on grid scroll is `handleRowsScrollEnd` from `@everysk/apps-sdk/ag-grid`, kept out of\n * this hook so it works for any list.\n *\n * Without a `workspace` filter, or with an empty one, the read fails at once with an error\n * naming this hook, logged to the console, and no request is sent. The app config is in place\n * before the app renders, so a missing workspace is a misconfigured app, never a wait.\n *\n * Rows are converted in the request (`parseDatastore`), so the cache holds objects and an\n * app patches a row as `{ ...row, ...patch }`. `dataFormat: \"matrix\"` skips the conversion and\n * leaves a tabular datastore's matrix unconverted, for a grid that takes arrays, an export, or a\n * datastore too large to convert. It is a value, not a conversion function, so that it can be\n * part of the cache key: two callers converting differently would otherwise share one entry.\n *\n * @param {FilterClause[]} [filters=[]] - Filters of every page request; one must be `workspace`.\n * @param {string[]} [order=[]] - Sorting of every page request.\n * @param {Projection} [projection=\"\"] - The fields to return, one or a list: `\"field\"` returns\n *   only that field (others come back null), `\"-field\"` every field but that one. Several go as a\n *   list, never comma-joined — `\"a,b\"` is a 500.\n * @param {number} [pageSize=10] - Datastores per request.\n * @param {\"object\" | \"matrix\"} [dataFormat=\"object\"] - How a table's rows are handed over.\n * @param {(datastores: ParsedDatastore[]) => TData} [select] - Shapes the merged list.\n * @param {boolean} [fetchAllPages=false] - Reads to the last page before reporting success.\n * @param {EntityInfiniteQueryOptions} [queryOptions] - Passed through to `useInfiniteQuery`.\n * @returns {object} `query` (the `useInfiniteQuery` result) and `queryKey`.\n *\n * Example:\n * ```ts\n * // A list can mix tabular and JSON datastores; only a table's `data` is rows.\n * const toRows = (datastores: ParsedDatastore[]) => datastores.filter(isTableDatastore).flatMap((d) => d.data);\n *\n * const { query } = useFetchDatastores({\n *   filters: [{ field: \"workspace\", value: workspace }],\n *   select: toRows, // query.data: AnyRecord[]\n * });\n * ```\n */\nexport function useFetchDatastores<\n    F extends DatastoreDataFormat = \"object\",\n    TData = ParsedDatastore<F>[],\n>({\n    filters = [],\n    order = [],\n    projection = \"\",\n    pageSize = 10,\n    dataFormat,\n    select,\n    fetchAllPages = false,\n    queryOptions,\n}: FetchDatastoresProps<F, TData>) {\n    const { api } = useAxios();\n\n    const format = (dataFormat ?? \"object\") as F;\n    const queryKey = buildQueryKey([\"datastores\"], filters, {\n        order,\n        projection,\n        pageSize,\n        fetchAllPages,\n        dataFormat: format,\n    });\n\n    const query = useEntityInfiniteQuery<DatastoreQueryPage<F>, \"datastores\", TData>({\n        queryKey,\n        itemsKey: \"datastores\",\n        fetchPage: async (pageToken, signal) => {\n            const response: DatastoreListResponse = await listDatastores(\n                api,\n                buildQueryObject({ filters, order, projection, pageSize, pageToken }),\n                signal,\n            );\n\n            return {\n                next_page_token: response.next_page_token,\n                datastores: response.datastores.map((datastore) =>\n                    parseDatastore(datastore, format),\n                ),\n            };\n        },\n        select,\n        fetchAllPages,\n        configError: hasWorkspaceFilter(filters)\n            ? undefined\n            : missingWorkspaceError(\"useFetchDatastores\"),\n        queryOptions,\n    });\n\n    return { query, queryKey };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsFA,SAAgB,mBAGd,EACE,UAAU,CAAC,GACX,QAAQ,CAAC,GACT,aAAa,IACb,WAAW,IACX,YACA,QACA,gBAAgB,OAChB,gBAC+B;CAC/B,MAAM,EAAE,QAAQ,SAAS;CAEzB,MAAM,SAAU,cAAc;CAC9B,MAAM,WAAW,cAAc,CAAC,YAAY,GAAG,SAAS;EACpD;EACA;EACA;EACA;EACA,YAAY;CAChB,CAAC;CA2BD,OAAO;EAAE,OAzBK,uBAAmE;GAC7E;GACA,UAAU;GACV,WAAW,OAAO,WAAW,WAAW;IACpC,MAAM,WAAkC,MAAM,eAC1C,KACA,iBAAiB;KAAE;KAAS;KAAO;KAAY;KAAU;IAAU,CAAC,GACpE,MACJ;IAEA,OAAO;KACH,iBAAiB,SAAS;KAC1B,YAAY,SAAS,WAAW,KAAK,cACjC,eAAe,WAAW,MAAM,CACpC;IACJ;GACJ;GACA;GACA;GACA,aAAa,mBAAmB,OAAO,IACjC,KAAA,IACA,sBAAsB,oBAAoB;GAChD;EACJ,CAES;EAAO;CAAS;AAC7B"}

package/dist/hooks/file/fileData.d.ts

@@ -0,0 +1,17 @@
+import type { EveryskFile } from "../../types/file.d.ts";
+/** What the file hooks take about a file's content. */
+export type FileDataProps = {
+    /**
+     * `true` returns the content (`data`, base64). Left out by default: it is a third larger than
+     * the file, and showing or downloading a file needs only its `url` (`/file/<hash>`), which
+     * the platform serves inline with the user's session and the devkit's dev server serves too.
+     * With a list `projection` of the app's own that includes fields, `data` comes only if the
+     * projection names it.
+     */
+    withData?: boolean;
+};
+/** The file without its content, as the hooks return it unless `withData` asks for it. */
+export declare const withoutData: <F extends {
+    data: EveryskFile["data"];
+}>(file: F) => F;
+//# sourceMappingURL=fileData.d.ts.map

package/dist/hooks/file/fileData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileData.d.ts","sourceRoot":"","sources":["../../../src/hooks/file/fileData.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,uDAAuD;AACvD,MAAM,MAAM,aAAa,GAAG;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,0FAA0F;AAC1F,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS;IAAE,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAAE,EAAE,MAAM,CAAC,KAAG,CAG7E,CAAC"}

package/dist/hooks/file/fileData.js

@@ -0,0 +1,10 @@
+//#region src/hooks/file/fileData.ts
+/** The file without its content, as the hooks return it unless `withData` asks for it. */
+var withoutData = (file) => ({
+	...file,
+	data: null
+});
+//#endregion
+export { withoutData };
+
+//# sourceMappingURL=fileData.js.map

package/dist/hooks/file/fileData.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileData.js","names":[],"sources":["../../../src/hooks/file/fileData.ts"],"sourcesContent":["import type { EveryskFile } from \"@/types/file\";\n\n/** What the file hooks take about a file's content. */\nexport type FileDataProps = {\n    /**\n     * `true` returns the content (`data`, base64). Left out by default: it is a third larger than\n     * the file, and showing or downloading a file needs only its `url` (`/file/<hash>`), which\n     * the platform serves inline with the user's session and the devkit's dev server serves too.\n     * With a list `projection` of the app's own that includes fields, `data` comes only if the\n     * projection names it.\n     */\n    withData?: boolean;\n};\n\n/** The file without its content, as the hooks return it unless `withData` asks for it. */\nexport const withoutData = <F extends { data: EveryskFile[\"data\"] }>(file: F): F => ({\n    ...file,\n    data: null,\n});\n"],"mappings":";;AAeA,IAAa,eAAwD,UAAgB;CACjF,GAAG;CACH,MAAM;AACV"}

package/dist/hooks/file/useFetchFile.d.ts

@@ -1,54 +1,24 @@
 import type { EveryskFile } from "../../types/file.d.ts";
-import type { FetchEntityParams } from "../../types/entityQuery.d.ts";
-export type FetchFileProps<TData = EveryskFile, TSelected = TData> = FetchEntityParams<TData, TSelected>;
+import type { FetchEntityByIdProps } from "../../types/entityQuery.d.ts";
+import { type FileDataProps } from "./fileData";
+export type FetchFileProps<TData = EveryskFile, TSelected = TData> = FetchEntityByIdProps<TData, TSelected> & FileDataProps;
 /**
  * useFetchFile
  *
- * Data-fetching hook built on TanStack Query to retrieve a single file by ID.
+ * Fetches one file; `data` is the file, or whatever `select` makes of it. Idle while `id` is
+ * empty; fails loudly, without a request, while `workspace` is. A failure is shown as an error
+ * alert. The file comes without its content unless `withData` asks for it: show or download it
+ * through its `url`.
  *
- * It also:
- * - builds a stable React Query `queryKey` that can be reused by mutation hooks for cache invalidation
- * - triggers an error alert via `useAppAlert` whenever `query.error` is present
- *
- * Important notes:
- * - Always returns a single `EveryskFile` object.
- * - `EveryskFile.data` represents the file content and is expected to be a Base64-encoded string
- *   when provided by the API (or when sending content through mutations).
- *
- * Parameters (FetchFileProps):
- * @param {string} id
- *   EveryskFile identifier (required).
- *
- * @param {string} workspace
- *   Workspace the file belongs to (required by `getFile`).
- *
- * @param {EntityQueryOptions<any>} [queryOptions=defaultQueryOptions]
- *   TanStack Query options passed through to `useQuery` (e.g., enabled, staleTime, gcTime, etc.).
- *
- * Returns:
- * @returns {object}
- *   TanStack Query's `query` object extended with:
- *   - `queryKey`: the cache key used by React Query
- *
- * Tip:
- * - The returned `queryKey` can be reused by mutation hooks for cache invalidation:
- *   ```ts
- *   const fetch = useFetchFile({ id: "file-123", workspace: "ws-1" });
- *   useFileMutations({ queryKey: fetch.queryKey });
- *   ```
- *
- * Example:
- * ```ts
- * const { data, isLoading } = useFetchFile({
- *   id: "file-123",
- *   workspace: "ws-1",
- * });
- * // data -> EveryskFile
- * ```
+ * @param {FetchFileProps} props - `id`, `workspace`, `withData`, `select` and TanStack
+ *   `queryOptions`.
+ * @returns {object} The `useQuery` result, plus `queryKey`.
  */
-export declare const useFetchFile: ({ id, workspace, queryOptions }: FetchFileProps) => {
-    queryKey: string[];
-    data: EveryskFile;
+export declare const useFetchFile: <TSelected = EveryskFile>({ id, workspace, select, queryOptions, withData, }: FetchFileProps<EveryskFile, TSelected>) => {
+    queryKey: (string | {
+        withData: boolean;
+    })[];
+    data: TSelected;
     error: Error;
     isError: true;
     isPending: false;
@@ -71,11 +41,13 @@ export declare const useFetchFile: ({ id, workspace, queryOptions }: FetchFilePr
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<EveryskFile, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 } | {
-    queryKey: string[];
-    data: EveryskFile;
+    queryKey: (string | {
+        withData: boolean;
+    })[];
+    data: TSelected;
     error: null;
     isError: false;
     isPending: false;
@@ -98,10 +70,12 @@ export declare const useFetchFile: ({ id, workspace, queryOptions }: FetchFilePr
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<EveryskFile, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 } | {
-    queryKey: string[];
+    queryKey: (string | {
+        withData: boolean;
+    })[];
     data: undefined;
     error: Error;
     isError: true;
@@ -125,10 +99,12 @@ export declare const useFetchFile: ({ id, workspace, queryOptions }: FetchFilePr
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<EveryskFile, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 } | {
-    queryKey: string[];
+    queryKey: (string | {
+        withData: boolean;
+    })[];
     data: undefined;
     error: null;
     isError: false;
@@ -152,10 +128,12 @@ export declare const useFetchFile: ({ id, workspace, queryOptions }: FetchFilePr
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<EveryskFile, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 } | {
-    queryKey: string[];
+    queryKey: (string | {
+        withData: boolean;
+    })[];
     data: undefined;
     error: null;
     isError: false;
@@ -179,11 +157,13 @@ export declare const useFetchFile: ({ id, workspace, queryOptions }: FetchFilePr
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<EveryskFile, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 } | {
-    queryKey: string[];
-    data: EveryskFile;
+    queryKey: (string | {
+        withData: boolean;
+    })[];
+    data: TSelected;
     isError: false;
     error: null;
     isPending: false;
@@ -206,7 +186,7 @@ export declare const useFetchFile: ({ id, workspace, queryOptions }: FetchFilePr
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<EveryskFile, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 };
 //# sourceMappingURL=useFetchFile.d.ts.map

package/dist/hooks/file/useFetchFile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFetchFile.d.ts","sourceRoot":"","sources":["../../../src/hooks/file/useFetchFile.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,KAAK,EAAsB,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAEjF,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,WAAW,EAAE,SAAS,GAAG,KAAK,IAAI,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;AAQzG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,YAAY,GAAI,iCAAuD,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BjG,CAAC"}
+{"version":3,"file":"useFetchFile.d.ts","sourceRoot":"","sources":["../../../src/hooks/file/useFetchFile.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAE7D,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,WAAW,EAAE,SAAS,GAAG,KAAK,IAAI,oBAAoB,CACrF,KAAK,EACL,SAAS,CACZ,GACG,aAAa,CAAC;AAElB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,GAAG,WAAW,EAAE,oDAMnD,cAAc,CAAC,WAAW,EAAE,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuBxC,CAAC"}