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

package/dist/agGrid/handleRowsScrollEnd.js

@@ -0,0 +1,47 @@
+//#region src/agGrid/handleRowsScrollEnd.ts
+/**
+* handleRowsScrollEnd
+*
+* Requests the next page when an AG Grid is scrolled near its last row, or shows none — the
+* grid paging on demand. The handler for what MUI X DataGrid calls `onRowsScrollEnd`; wire it
+* to AG Grid's `onBodyScrollEnd` and `onModelUpdated`, the second so that a grid whose rows a
+* client-side filter hid entirely keeps loading.
+*
+* A function, not part of any hook: the data hook does not know a grid exists, and the grid
+* does not know where its rows come from. It lives in this subpath because it needs `GridApi`,
+* and AG Grid is an optional peer.
+*
+* Events fire in bursts, before `isFetchingNextPage` has flipped, so the request is made with
+* `cancelRefetch: false`: TanStack then ignores a repeat while the first one is in flight,
+* instead of cancelling it and asking for the same page again.
+*
+* @param {GridApi} gridApi - The grid, from the event (`event.api`).
+* @param {InfiniteQueryPaging} query - The infinite query feeding the grid.
+* @param {HandleRowsScrollEndOptions} [options] - `scrollEndThreshold`, in pixels (default 80).
+*
+* Example:
+* ```tsx
+* const { query } = useFetchDatastores({ filters, select: toRows });
+*
+* <AgGridReact
+*   rowData={query.data}
+*   onBodyScrollEnd={(event) => handleRowsScrollEnd(event.api, query)}
+*   onModelUpdated={(event) => handleRowsScrollEnd(event.api, query)}
+* />
+* ```
+*/
+var handleRowsScrollEnd = (gridApi, query, { scrollEndThreshold = 80 } = {}) => {
+	if (!query.hasNextPage || query.isFetchingNextPage) return;
+	const rowCount = gridApi.getDisplayedRowCount();
+	const lastRow = rowCount > 0 ? gridApi.getDisplayedRowAtIndex(rowCount - 1) : void 0;
+	if (lastRow) {
+		const rowsEnd = (lastRow.rowTop ?? 0) + (lastRow.rowHeight ?? 0);
+		const { bottom } = gridApi.getVerticalPixelRange();
+		if (rowsEnd - bottom > scrollEndThreshold) return;
+	}
+	query.fetchNextPage({ cancelRefetch: false });
+};
+//#endregion
+export { handleRowsScrollEnd };
+
+//# sourceMappingURL=handleRowsScrollEnd.js.map

package/dist/agGrid/handleRowsScrollEnd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handleRowsScrollEnd.js","names":[],"sources":["../../src/agGrid/handleRowsScrollEnd.ts"],"sourcesContent":["import type { GridApi } from \"ag-grid-community\";\n\n/**\n * The part of an infinite query this needs. Structural, so it takes any list hook's `query`,\n * or a `useInfiniteQuery` an app writes itself.\n */\nexport type InfiniteQueryPaging = {\n    hasNextPage: boolean;\n    isFetchingNextPage: boolean;\n    fetchNextPage: (options?: { cancelRefetch?: boolean }) => Promise<unknown>;\n};\n\nexport type HandleRowsScrollEndOptions = {\n    /**\n     * Distance in pixels from the end of the rows at which the next page is requested. Named and\n     * measured as MUI X DataGrid's `scrollEndThreshold`, whose default it shares. Pixels rather\n     * than rows, so it holds with rows of different heights.\n     */\n    scrollEndThreshold?: number;\n};\n\n/**\n * handleRowsScrollEnd\n *\n * Requests the next page when an AG Grid is scrolled near its last row, or shows none — the\n * grid paging on demand. The handler for what MUI X DataGrid calls `onRowsScrollEnd`; wire it\n * to AG Grid's `onBodyScrollEnd` and `onModelUpdated`, the second so that a grid whose rows a\n * client-side filter hid entirely keeps loading.\n *\n * A function, not part of any hook: the data hook does not know a grid exists, and the grid\n * does not know where its rows come from. It lives in this subpath because it needs `GridApi`,\n * and AG Grid is an optional peer.\n *\n * Events fire in bursts, before `isFetchingNextPage` has flipped, so the request is made with\n * `cancelRefetch: false`: TanStack then ignores a repeat while the first one is in flight,\n * instead of cancelling it and asking for the same page again.\n *\n * @param {GridApi} gridApi - The grid, from the event (`event.api`).\n * @param {InfiniteQueryPaging} query - The infinite query feeding the grid.\n * @param {HandleRowsScrollEndOptions} [options] - `scrollEndThreshold`, in pixels (default 80).\n *\n * Example:\n * ```tsx\n * const { query } = useFetchDatastores({ filters, select: toRows });\n *\n * <AgGridReact\n *   rowData={query.data}\n *   onBodyScrollEnd={(event) => handleRowsScrollEnd(event.api, query)}\n *   onModelUpdated={(event) => handleRowsScrollEnd(event.api, query)}\n * />\n * ```\n */\nexport const handleRowsScrollEnd = (\n    gridApi: GridApi,\n    query: InfiniteQueryPaging,\n    { scrollEndThreshold = 80 }: HandleRowsScrollEndOptions = {},\n): void => {\n    if (!query.hasNextPage || query.isFetchingNextPage) return;\n\n    const rowCount = gridApi.getDisplayedRowCount();\n    const lastRow = rowCount > 0 ? gridApi.getDisplayedRowAtIndex(rowCount - 1) : undefined;\n\n    if (lastRow) {\n        const rowsEnd = (lastRow.rowTop ?? 0) + (lastRow.rowHeight ?? 0);\n        const { bottom } = gridApi.getVerticalPixelRange();\n\n        if (rowsEnd - bottom > scrollEndThreshold) return;\n    }\n\n    void query.fetchNextPage({ cancelRefetch: false });\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,IAAa,uBACT,SACA,OACA,EAAE,qBAAqB,OAAmC,CAAC,MACpD;CACP,IAAI,CAAC,MAAM,eAAe,MAAM,oBAAoB;CAEpD,MAAM,WAAW,QAAQ,qBAAqB;CAC9C,MAAM,UAAU,WAAW,IAAI,QAAQ,uBAAuB,WAAW,CAAC,IAAI,KAAA;CAE9E,IAAI,SAAS;EACT,MAAM,WAAW,QAAQ,UAAU,MAAM,QAAQ,aAAa;EAC9D,MAAM,EAAE,WAAW,QAAQ,sBAAsB;EAEjD,IAAI,UAAU,SAAS,oBAAoB;CAC/C;CAEA,MAAW,cAAc,EAAE,eAAe,MAAM,CAAC;AACrD"}

package/dist/agGrid/index.d.ts

@@ -1,4 +1,6 @@
 export { setAgGridLicense, AgGridLicenseProvider } from "../contexts/agGridLicenseContext/provider.js";
 export type { AgGridLicenseProviderProps } from "../contexts/agGridLicenseContext/provider.js";
 export { getAgGridTheme, useAgGridTheme, agGridThemeParams } from "./agGridTheme";
+export { handleRowsScrollEnd } from "./handleRowsScrollEnd";
+export type { HandleRowsScrollEndOptions, InfiniteQueryPaging } from "./handleRowsScrollEnd";
 //# sourceMappingURL=index.d.ts.map

package/dist/agGrid/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agGrid/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACnG,YAAY,EAAE,0BAA0B,EAAE,MAAM,0CAA0C,CAAC;AAE3F,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agGrid/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACnG,YAAY,EAAE,0BAA0B,EAAE,MAAM,0CAA0C,CAAC;AAE3F,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElF,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,YAAY,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/agGrid/index.js

@@ -1,3 +1,4 @@
 import { AgGridLicenseProvider, setAgGridLicense } from "../contexts/agGridLicenseContext/provider.js";
 import { agGridThemeParams, getAgGridTheme, useAgGridTheme } from "./agGridTheme.js";
-export { AgGridLicenseProvider, agGridThemeParams, getAgGridTheme, setAgGridLicense, useAgGridTheme };
+import { handleRowsScrollEnd } from "./handleRowsScrollEnd.js";
+export { AgGridLicenseProvider, agGridThemeParams, getAgGridTheme, handleRowsScrollEnd, setAgGridLicense, useAgGridTheme };

package/dist/api/datastore.d.ts

@@ -1,5 +1,5 @@
-import { type AxiosInstance } from "axios";
-import type { DeleteEntityDefaultResponse, QueryObject } from "../types/entityQuery.d.ts";
+import type { AxiosInstance } from "axios";
+import type { DeletedEntity, QueryObject } from "../types/entityQuery.d.ts";
 import type { Datastore, DatastoreListResponse } from "../types/datastore.d.ts";
 /**
  * getDatastore
@@ -9,24 +9,26 @@ import type { Datastore, DatastoreListResponse } from "../types/datastore.d.ts";
  * @param {AxiosInstance} api - Axios instance.
  * @param {string} id - Datastore identifier.
  * @param {string} workspace - Workspace the datastore belongs to.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.
  * @returns {Promise<Datastore>} The fetched datastore.
  *
  * @throws {Error} If the request fails.
  */
-export declare const getDatastore: (api: AxiosInstance, id: string, workspace: string) => Promise<Datastore>;
+export declare const getDatastore: (api: AxiosInstance, id: string, workspace: string, signal?: AbortSignal) => Promise<Datastore>;
 /**
  * listDatastores
  *
  * Fetches a list of datastores using a query object (filters, order, pagination, etc.).
  *
  * @param {AxiosInstance} api - Axios instance.
- * @param {AnyRecord} query - Query object built via `buildQueryObject`.
+ * @param {QueryObject} query - Query object built via `buildQueryObject`.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the list hooks pass the query's own.
  * @returns {Promise<DatastoreListResponse>} Paginated list of datastores.
  *
- * @throws {Error} If workspace filter is missing.
+ * @throws {Error} If the query has no workspace filter.
  * @throws {Error} If the request fails.
  */
-export declare const listDatastores: (api: AxiosInstance, query: QueryObject) => Promise<DatastoreListResponse>;
+export declare const listDatastores: (api: AxiosInstance, query: QueryObject, signal?: AbortSignal) => Promise<DatastoreListResponse>;
 /**
  * createDatastore
  *
@@ -60,9 +62,9 @@ export declare const updateDatastore: (api: AxiosInstance, id: string, data: Par
  * @param {AxiosInstance} api - Axios instance.
  * @param {string} id - Datastore identifier.
  * @param {string} workspace - Workspace the datastore belongs to.
- * @returns {Promise<DeleteEntityDefaultResponse[]>} List of deleted entity records.
+ * @returns {Promise<DeletedEntity>} The deletion record: id, name and `deleted`.
  *
  * @throws {Error} If the request fails.
  */
-export declare const deleteDatastore: (api: AxiosInstance, id: string, workspace: string) => Promise<DeleteEntityDefaultResponse[]>;
+export declare const deleteDatastore: (api: AxiosInstance, id: string, workspace: string) => Promise<DeletedEntity>;
 //# sourceMappingURL=datastore.d.ts.map

package/dist/api/datastore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"datastore.d.ts","sourceRoot":"","sources":["../../src/api/datastore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,aAAa,EAAsB,MAAM,OAAO,CAAC;AAG7E,OAAO,KAAK,EAAE,2BAA2B,EAAoB,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACtG,OAAO,KAAK,EAAE,SAAS,EAA2B,qBAAqB,EAA2B,MAAM,mBAAmB,CAAC;AAI5H;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,GAAU,KAAK,aAAa,EAAE,IAAI,MAAM,EAAE,WAAW,MAAM,KAAG,OAAO,CAAC,SAAS,CAmBvG,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GAAU,KAAK,aAAa,EAAE,OAAO,WAAW,KAAG,OAAO,CAAC,qBAAqB,CAyB1G,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAAU,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,KAAG,OAAO,CAAC,SAAS,CAmBrG,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GAAU,KAAK,aAAa,EAAE,IAAI,MAAM,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,KAAG,OAAO,CAAC,SAAS,CAmBjH,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GAAU,KAAK,aAAa,EAAE,IAAI,MAAM,EAAE,WAAW,MAAM,KAAG,OAAO,CAAC,2BAA2B,EAAE,CAiB9H,CAAC"}
+{"version":3,"file":"datastore.d.ts","sourceRoot":"","sources":["../../src/api/datastore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C,OAAO,KAAK,EACR,aAAa,EAGb,WAAW,EACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAS1E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,GACrB,KAAK,aAAa,EAClB,IAAI,MAAM,EACV,WAAW,MAAM,EACjB,SAAS,WAAW,KACrB,OAAO,CAAC,SAAS,CASnB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,GACvB,KAAK,aAAa,EAClB,OAAO,WAAW,EAClB,SAAS,WAAW,KACrB,OAAO,CAAC,qBAAqB,CAO/B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GACxB,KAAK,aAAa,EAClB,MAAM,OAAO,CAAC,SAAS,CAAC,KACzB,OAAO,CAAC,SAAS,CAQnB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GACxB,KAAK,aAAa,EAClB,IAAI,MAAM,EACV,MAAM,OAAO,CAAC,SAAS,CAAC,KACzB,OAAO,CAAC,SAAS,CAQnB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GACxB,KAAK,aAAa,EAClB,IAAI,MAAM,EACV,WAAW,MAAM,KAClB,OAAO,CAAC,aAAa,CAQvB,CAAC"}

package/dist/api/datastore.js

@@ -1,4 +1,4 @@
-import { isAxiosError } from "axios";
+import { listParams, request, requireWorkspace } from "./request.js";
 //#region src/api/datastore.ts
 var baseUrl = "datastores";
 /**
@@ -9,20 +9,17 @@ var baseUrl = "datastores";
 * @param {AxiosInstance} api - Axios instance.
 * @param {string} id - Datastore identifier.
 * @param {string} workspace - Workspace the datastore belongs to.
+* @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.
 * @returns {Promise<Datastore>} The fetched datastore.
 *
 * @throws {Error} If the request fails.
 */
-var getDatastore = async (api, id, workspace) => {
-	const params = { workspace };
-	if (!workspace) throw new Error("Workspace filter is required to fetch a datastore");
-	try {
-		return (await api.get(`${baseUrl}/${id}`, { params })).data.datastore;
-	} catch (error) {
-		if (isAxiosError(error)) throw new Error(error.message || "Error fetching datastore", { cause: error });
-		if (error instanceof Error) throw error;
-		throw new Error("Error fetching datastore", { cause: error });
-	}
+var getDatastore = async (api, id, workspace, signal) => {
+	requireWorkspace(workspace, "fetch a datastore");
+	return (await request(() => api.get(`${baseUrl}/${id}`, {
+		params: { workspace },
+		signal
+	}), "Error fetching datastore")).datastore;
 };
 /**
 * listDatastores
@@ -30,27 +27,19 @@ var getDatastore = async (api, id, workspace) => {
 * Fetches a list of datastores using a query object (filters, order, pagination, etc.).
 *
 * @param {AxiosInstance} api - Axios instance.
-* @param {AnyRecord} query - Query object built via `buildQueryObject`.
+* @param {QueryObject} query - Query object built via `buildQueryObject`.
+* @param {AbortSignal} [signal] - Aborts the request itself; the list hooks pass the query's own.
 * @returns {Promise<DatastoreListResponse>} Paginated list of datastores.
 *
-* @throws {Error} If workspace filter is missing.
+* @throws {Error} If the query has no workspace filter.
 * @throws {Error} If the request fails.
 */
-var listDatastores = async (api, query) => {
-	const workspaceFilter = query.filters.find((filter) => filter[0] === "workspace");
-	const workspace = workspaceFilter?.[workspaceFilter.length - 1];
-	if (!workspace) throw new Error("Workspace filter is required to list datastores");
-	const params = {
-		workspace,
-		...query ? { query: JSON.stringify(query) } : {}
-	};
-	try {
-		return (await api.get(baseUrl, { params })).data;
-	} catch (error) {
-		if (isAxiosError(error)) throw new Error(error.message || "Error listing datastores", { cause: error });
-		if (error instanceof Error) throw error;
-		throw new Error("Error listing datastores", { cause: error });
-	}
+var listDatastores = async (api, query, signal) => {
+	const params = listParams(query, "list datastores");
+	return request(() => api.get(baseUrl, {
+		params,
+		signal
+	}), "Error listing datastores");
 };
 /**
 * createDatastore
@@ -64,15 +53,8 @@ var listDatastores = async (api, query) => {
 * @throws {Error} If the request fails.
 */
 var createDatastore = async (api, data) => {
-	const { workspace } = data;
-	if (!workspace) throw new Error("Workspace filter is required to create a datastore");
-	try {
-		return (await api.post(baseUrl, data)).data.datastore;
-	} catch (error) {
-		if (isAxiosError(error)) throw new Error(error.message || "Error creating datastore", { cause: error });
-		if (error instanceof Error) throw error;
-		throw new Error("Error creating datastore", { cause: error });
-	}
+	requireWorkspace(data.workspace, "create a datastore");
+	return (await request(() => api.post(baseUrl, data), "Error creating datastore")).datastore;
 };
 /**
 * updateDatastore
@@ -87,15 +69,8 @@ var createDatastore = async (api, data) => {
 * @throws {Error} If the request fails.
 */
 var updateDatastore = async (api, id, data) => {
-	const { workspace } = data;
-	if (!workspace) throw new Error("Workspace filter is required to update a datastore");
-	try {
-		return (await api.put(`${baseUrl}/${id}`, data)).data.datastore;
-	} catch (error) {
-		if (isAxiosError(error)) throw new Error(error.message || "Error updating datastore", { cause: error });
-		if (error instanceof Error) throw error;
-		throw new Error("Error updating datastore", { cause: error });
-	}
+	requireWorkspace(data.workspace, "update a datastore");
+	return (await request(() => api.put(`${baseUrl}/${id}`, data), "Error updating datastore")).datastore;
 };
 /**
 * deleteDatastore
@@ -105,19 +80,13 @@ var updateDatastore = async (api, id, data) => {
 * @param {AxiosInstance} api - Axios instance.
 * @param {string} id - Datastore identifier.
 * @param {string} workspace - Workspace the datastore belongs to.
-* @returns {Promise<DeleteEntityDefaultResponse[]>} List of deleted entity records.
+* @returns {Promise<DeletedEntity>} The deletion record: id, name and `deleted`.
 *
 * @throws {Error} If the request fails.
 */
 var deleteDatastore = async (api, id, workspace) => {
-	const params = { workspace };
-	try {
-		return (await api.delete(`${baseUrl}/${id}`, { params })).data.datastores;
-	} catch (error) {
-		if (isAxiosError(error)) throw new Error(error.message || "Error removing datastore", { cause: error });
-		if (error instanceof Error) throw error;
-		throw new Error("Error removing datastore", { cause: error });
-	}
+	requireWorkspace(workspace, "delete a datastore");
+	return (await request(() => api.delete(`${baseUrl}/${id}`, { params: { workspace } }), "Error deleting datastore")).datastore;
 };
 //#endregion
 export { createDatastore, deleteDatastore, getDatastore, listDatastores, updateDatastore };

package/dist/api/datastore.js.map

@@ -1 +1 @@
-{"version":3,"file":"datastore.js","names":[],"sources":["../../src/api/datastore.ts"],"sourcesContent":["import { isAxiosError, type AxiosInstance, type AxiosResponse } from \"axios\";\n\nimport type { AnyRecord } from \"@/types/anyRecord\";\nimport type { DeleteEntityDefaultResponse, FilterExpression, QueryObject } from \"@/types/entityQuery\";\nimport type { Datastore, DatastoreSingleResponse, DatastoreListResponse, DeleteDatastoreResponse } from \"@/types/datastore\";\n\nconst baseUrl = \"datastores\";\n\n/**\n * getDatastore\n *\n * Fetches a single datastore by ID.\n *\n * @param {AxiosInstance} api - Axios instance.\n * @param {string} id - Datastore identifier.\n * @param {string} workspace - Workspace the datastore belongs to.\n * @returns {Promise<Datastore>} The fetched datastore.\n *\n * @throws {Error} If the request fails.\n */\nexport const getDatastore = async (api: AxiosInstance, id: string, workspace: string): Promise<Datastore> => {\n  const params: AnyRecord = { workspace };\n\n  if (!workspace) throw new Error(\"Workspace filter is required to fetch a datastore\");\n\n  try {\n    const response: AxiosResponse<DatastoreSingleResponse> = await api.get(`${baseUrl}/${id}`, { params });\n    return response.data.datastore;\n  } catch (error: unknown) {\n    if (isAxiosError<AnyRecord>(error)) {\n      throw new Error(error.message || \"Error fetching datastore\", { cause: error });\n    }\n\n    if (error instanceof Error) {\n      throw error;\n    }\n\n    throw new Error(\"Error fetching datastore\", { cause: error });\n  }\n};\n\n/**\n * listDatastores\n *\n * Fetches a list of datastores using a query object (filters, order, pagination, etc.).\n *\n * @param {AxiosInstance} api - Axios instance.\n * @param {AnyRecord} query - Query object built via `buildQueryObject`.\n * @returns {Promise<DatastoreListResponse>} Paginated list of datastores.\n *\n * @throws {Error} If workspace filter is missing.\n * @throws {Error} If the request fails.\n */\nexport const listDatastores = async (api: AxiosInstance, query: QueryObject): Promise<DatastoreListResponse> => {\n  const workspaceFilter = query.filters.find((filter: FilterExpression) => filter[0] === \"workspace\");\n  const workspace = workspaceFilter?.[workspaceFilter.length - 1];\n\n  if (!workspace) throw new Error(\"Workspace filter is required to list datastores\");\n\n  const params: AnyRecord = {\n    workspace,\n    ...(query ? { query: JSON.stringify(query) } : {}),\n  };\n\n  try {\n    const response: AxiosResponse<DatastoreListResponse> = await api.get(baseUrl, { params });\n    return response.data;\n  } catch (error: unknown) {\n    if (isAxiosError<AnyRecord>(error)) {\n      throw new Error(error.message || \"Error listing datastores\", { cause: error });\n    }\n\n    if (error instanceof Error) {\n      throw error;\n    }\n\n    throw new Error(\"Error listing datastores\", { cause: error });\n  }\n};\n\n/**\n * createDatastore\n *\n * Creates a new datastore.\n *\n * @param {AxiosInstance} api - Axios instance.\n * @param {Partial<Datastore>} data - Datastore payload.\n * @returns {Promise<Datastore>} The created datastore.\n *\n * @throws {Error} If the request fails.\n */\nexport const createDatastore = async (api: AxiosInstance, data: Partial<Datastore>): Promise<Datastore> => {\n\n  const { workspace } = data;\n  if (!workspace) throw new Error(\"Workspace filter is required to create a datastore\");\n\n  try {\n    const response: AxiosResponse<DatastoreSingleResponse> = await api.post(baseUrl, data);\n    return response.data.datastore;\n  } catch (error: unknown) {\n    if (isAxiosError<AnyRecord>(error)) {\n      throw new Error(error.message || \"Error creating datastore\", { cause: error });\n    }\n\n    if (error instanceof Error) {\n      throw error;\n    }\n\n    throw new Error(\"Error creating datastore\", { cause: error });\n  }\n};\n\n/**\n * updateDatastore\n *\n * Updates an existing datastore by ID.\n *\n * @param {AxiosInstance} api - Axios instance.\n * @param {string} id - Datastore identifier.\n * @param {Partial<Datastore>} data - Fields to update.\n * @returns {Promise<Datastore>} The updated datastore.\n *\n * @throws {Error} If the request fails.\n */\nexport const updateDatastore = async (api: AxiosInstance, id: string, data: Partial<Datastore>): Promise<Datastore> => {\n\n  const { workspace } = data;\n  if (!workspace) throw new Error(\"Workspace filter is required to update a datastore\");\n\n  try {\n    const response: AxiosResponse<DatastoreSingleResponse> = await api.put(`${baseUrl}/${id}`, data);\n    return response.data.datastore;\n  } catch (error: unknown) {\n    if (isAxiosError<AnyRecord>(error)) {\n      throw new Error(error.message || \"Error updating datastore\", { cause: error });\n    }\n\n    if (error instanceof Error) {\n      throw error;\n    }\n\n    throw new Error(\"Error updating datastore\", { cause: error });\n  }\n};\n\n/**\n * deleteDatastore\n *\n * Deletes a datastore by ID.\n *\n * @param {AxiosInstance} api - Axios instance.\n * @param {string} id - Datastore identifier.\n * @param {string} workspace - Workspace the datastore belongs to.\n * @returns {Promise<DeleteEntityDefaultResponse[]>} List of deleted entity records.\n *\n * @throws {Error} If the request fails.\n */\nexport const deleteDatastore = async (api: AxiosInstance, id: string, workspace: string): Promise<DeleteEntityDefaultResponse[]> => {\n  const params: AnyRecord = { workspace };\n\n  try {\n    const response: AxiosResponse<DeleteDatastoreResponse> = await api.delete(`${baseUrl}/${id}`, { params });\n    return response.data.datastores;\n  } catch (error: unknown) {\n    if (isAxiosError<AnyRecord>(error)) {\n      throw new Error(error.message || \"Error removing datastore\", { cause: error });\n    }\n\n    if (error instanceof Error) {\n      throw error;\n    }\n\n    throw new Error(\"Error removing datastore\", { cause: error });\n  }\n};"],"mappings":";;AAMA,IAAM,UAAU;;;;;;;;;;;;;AAchB,IAAa,eAAe,OAAO,KAAoB,IAAY,cAA0C;CAC3G,MAAM,SAAoB,EAAE,UAAU;CAEtC,IAAI,CAAC,WAAW,MAAM,IAAI,MAAM,mDAAmD;CAEnF,IAAI;EAEF,QAAO,MADwD,IAAI,IAAI,GAAG,QAAQ,GAAG,MAAM,EAAE,OAAO,CAAC,EAAA,CACrF,KAAK;CACvB,SAAS,OAAgB;EACvB,IAAI,aAAwB,KAAK,GAC/B,MAAM,IAAI,MAAM,MAAM,WAAW,4BAA4B,EAAE,OAAO,MAAM,CAAC;EAG/E,IAAI,iBAAiB,OACnB,MAAM;EAGR,MAAM,IAAI,MAAM,4BAA4B,EAAE,OAAO,MAAM,CAAC;CAC9D;AACF;;;;;;;;;;;;;AAcA,IAAa,iBAAiB,OAAO,KAAoB,UAAuD;CAC9G,MAAM,kBAAkB,MAAM,QAAQ,MAAM,WAA6B,OAAO,OAAO,WAAW;CAClG,MAAM,YAAY,kBAAkB,gBAAgB,SAAS;CAE7D,IAAI,CAAC,WAAW,MAAM,IAAI,MAAM,iDAAiD;CAEjF,MAAM,SAAoB;EACxB;EACA,GAAI,QAAQ,EAAE,OAAO,KAAK,UAAU,KAAK,EAAE,IAAI,CAAC;CAClD;CAEA,IAAI;EAEF,QAAO,MADsD,IAAI,IAAI,SAAS,EAAE,OAAO,CAAC,EAAA,CACxE;CAClB,SAAS,OAAgB;EACvB,IAAI,aAAwB,KAAK,GAC/B,MAAM,IAAI,MAAM,MAAM,WAAW,4BAA4B,EAAE,OAAO,MAAM,CAAC;EAG/E,IAAI,iBAAiB,OACnB,MAAM;EAGR,MAAM,IAAI,MAAM,4BAA4B,EAAE,OAAO,MAAM,CAAC;CAC9D;AACF;;;;;;;;;;;;AAaA,IAAa,kBAAkB,OAAO,KAAoB,SAAiD;CAEzG,MAAM,EAAE,cAAc;CACtB,IAAI,CAAC,WAAW,MAAM,IAAI,MAAM,oDAAoD;CAEpF,IAAI;EAEF,QAAO,MADwD,IAAI,KAAK,SAAS,IAAI,EAAA,CACrE,KAAK;CACvB,SAAS,OAAgB;EACvB,IAAI,aAAwB,KAAK,GAC/B,MAAM,IAAI,MAAM,MAAM,WAAW,4BAA4B,EAAE,OAAO,MAAM,CAAC;EAG/E,IAAI,iBAAiB,OACnB,MAAM;EAGR,MAAM,IAAI,MAAM,4BAA4B,EAAE,OAAO,MAAM,CAAC;CAC9D;AACF;;;;;;;;;;;;;AAcA,IAAa,kBAAkB,OAAO,KAAoB,IAAY,SAAiD;CAErH,MAAM,EAAE,cAAc;CACtB,IAAI,CAAC,WAAW,MAAM,IAAI,MAAM,oDAAoD;CAEpF,IAAI;EAEF,QAAO,MADwD,IAAI,IAAI,GAAG,QAAQ,GAAG,MAAM,IAAI,EAAA,CAC/E,KAAK;CACvB,SAAS,OAAgB;EACvB,IAAI,aAAwB,KAAK,GAC/B,MAAM,IAAI,MAAM,MAAM,WAAW,4BAA4B,EAAE,OAAO,MAAM,CAAC;EAG/E,IAAI,iBAAiB,OACnB,MAAM;EAGR,MAAM,IAAI,MAAM,4BAA4B,EAAE,OAAO,MAAM,CAAC;CAC9D;AACF;;;;;;;;;;;;;AAcA,IAAa,kBAAkB,OAAO,KAAoB,IAAY,cAA8D;CAClI,MAAM,SAAoB,EAAE,UAAU;CAEtC,IAAI;EAEF,QAAO,MADwD,IAAI,OAAO,GAAG,QAAQ,GAAG,MAAM,EAAE,OAAO,CAAC,EAAA,CACxF,KAAK;CACvB,SAAS,OAAgB;EACvB,IAAI,aAAwB,KAAK,GAC/B,MAAM,IAAI,MAAM,MAAM,WAAW,4BAA4B,EAAE,OAAO,MAAM,CAAC;EAG/E,IAAI,iBAAiB,OACnB,MAAM;EAGR,MAAM,IAAI,MAAM,4BAA4B,EAAE,OAAO,MAAM,CAAC;CAC9D;AACF"}
+{"version":3,"file":"datastore.js","names":[],"sources":["../../src/api/datastore.ts"],"sourcesContent":["import type { AxiosInstance } from \"axios\";\n\nimport type {\n    DeletedEntity,\n    DeleteEntityResponse,\n    EntitySingleResponse,\n    QueryObject,\n} from \"@/types/entityQuery\";\nimport type { Datastore, DatastoreListResponse } from \"@/types/datastore\";\nimport { listParams, request, requireWorkspace } from \"./request\";\n\nconst baseUrl = \"datastores\";\n\n/** The endpoint's envelopes, private: every function here returns the entity itself. */\ntype DatastoreSingleResponse = EntitySingleResponse<\"datastore\", Datastore>;\ntype DeleteDatastoreResponse = DeleteEntityResponse<\"datastore\">;\n\n/**\n * getDatastore\n *\n * Fetches a single datastore by ID.\n *\n * @param {AxiosInstance} api - Axios instance.\n * @param {string} id - Datastore identifier.\n * @param {string} workspace - Workspace the datastore belongs to.\n * @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.\n * @returns {Promise<Datastore>} The fetched datastore.\n *\n * @throws {Error} If the request fails.\n */\nexport const getDatastore = async (\n    api: AxiosInstance,\n    id: string,\n    workspace: string,\n    signal?: AbortSignal,\n): Promise<Datastore> => {\n    requireWorkspace(workspace, \"fetch a datastore\");\n\n    const body = await request(\n        () =>\n            api.get<DatastoreSingleResponse>(`${baseUrl}/${id}`, { params: { workspace }, signal }),\n        \"Error fetching datastore\",\n    );\n    return body.datastore;\n};\n\n/**\n * listDatastores\n *\n * Fetches a list of datastores using a query object (filters, order, pagination, etc.).\n *\n * @param {AxiosInstance} api - Axios instance.\n * @param {QueryObject} query - Query object built via `buildQueryObject`.\n * @param {AbortSignal} [signal] - Aborts the request itself; the list hooks pass the query's own.\n * @returns {Promise<DatastoreListResponse>} Paginated list of datastores.\n *\n * @throws {Error} If the query has no workspace filter.\n * @throws {Error} If the request fails.\n */\nexport const listDatastores = async (\n    api: AxiosInstance,\n    query: QueryObject,\n    signal?: AbortSignal,\n): Promise<DatastoreListResponse> => {\n    const params = listParams(query, \"list datastores\");\n\n    return request(\n        () => api.get<DatastoreListResponse>(baseUrl, { params, signal }),\n        \"Error listing datastores\",\n    );\n};\n\n/**\n * createDatastore\n *\n * Creates a new datastore.\n *\n * @param {AxiosInstance} api - Axios instance.\n * @param {Partial<Datastore>} data - Datastore payload.\n * @returns {Promise<Datastore>} The created datastore.\n *\n * @throws {Error} If the request fails.\n */\nexport const createDatastore = async (\n    api: AxiosInstance,\n    data: Partial<Datastore>,\n): Promise<Datastore> => {\n    requireWorkspace(data.workspace, \"create a datastore\");\n\n    const body = await request(\n        () => api.post<DatastoreSingleResponse>(baseUrl, data),\n        \"Error creating datastore\",\n    );\n    return body.datastore;\n};\n\n/**\n * updateDatastore\n *\n * Updates an existing datastore by ID.\n *\n * @param {AxiosInstance} api - Axios instance.\n * @param {string} id - Datastore identifier.\n * @param {Partial<Datastore>} data - Fields to update.\n * @returns {Promise<Datastore>} The updated datastore.\n *\n * @throws {Error} If the request fails.\n */\nexport const updateDatastore = async (\n    api: AxiosInstance,\n    id: string,\n    data: Partial<Datastore>,\n): Promise<Datastore> => {\n    requireWorkspace(data.workspace, \"update a datastore\");\n\n    const body = await request(\n        () => api.put<DatastoreSingleResponse>(`${baseUrl}/${id}`, data),\n        \"Error updating datastore\",\n    );\n    return body.datastore;\n};\n\n/**\n * deleteDatastore\n *\n * Deletes a datastore by ID.\n *\n * @param {AxiosInstance} api - Axios instance.\n * @param {string} id - Datastore identifier.\n * @param {string} workspace - Workspace the datastore belongs to.\n * @returns {Promise<DeletedEntity>} The deletion record: id, name and `deleted`.\n *\n * @throws {Error} If the request fails.\n */\nexport const deleteDatastore = async (\n    api: AxiosInstance,\n    id: string,\n    workspace: string,\n): Promise<DeletedEntity> => {\n    requireWorkspace(workspace, \"delete a datastore\");\n\n    const body = await request(\n        () => api.delete<DeleteDatastoreResponse>(`${baseUrl}/${id}`, { params: { workspace } }),\n        \"Error deleting datastore\",\n    );\n    return body.datastore;\n};\n"],"mappings":";;AAWA,IAAM,UAAU;;;;;;;;;;;;;;AAmBhB,IAAa,eAAe,OACxB,KACA,IACA,WACA,WACqB;CACrB,iBAAiB,WAAW,mBAAmB;CAO/C,QAAO,MALY,cAEX,IAAI,IAA6B,GAAG,QAAQ,GAAG,MAAM;EAAE,QAAQ,EAAE,UAAU;EAAG;CAAO,CAAC,GAC1F,0BACJ,EAAA,CACY;AAChB;;;;;;;;;;;;;;AAeA,IAAa,iBAAiB,OAC1B,KACA,OACA,WACiC;CACjC,MAAM,SAAS,WAAW,OAAO,iBAAiB;CAElD,OAAO,cACG,IAAI,IAA2B,SAAS;EAAE;EAAQ;CAAO,CAAC,GAChE,0BACJ;AACJ;;;;;;;;;;;;AAaA,IAAa,kBAAkB,OAC3B,KACA,SACqB;CACrB,iBAAiB,KAAK,WAAW,oBAAoB;CAMrD,QAAO,MAJY,cACT,IAAI,KAA8B,SAAS,IAAI,GACrD,0BACJ,EAAA,CACY;AAChB;;;;;;;;;;;;;AAcA,IAAa,kBAAkB,OAC3B,KACA,IACA,SACqB;CACrB,iBAAiB,KAAK,WAAW,oBAAoB;CAMrD,QAAO,MAJY,cACT,IAAI,IAA6B,GAAG,QAAQ,GAAG,MAAM,IAAI,GAC/D,0BACJ,EAAA,CACY;AAChB;;;;;;;;;;;;;AAcA,IAAa,kBAAkB,OAC3B,KACA,IACA,cACyB;CACzB,iBAAiB,WAAW,oBAAoB;CAMhD,QAAO,MAJY,cACT,IAAI,OAAgC,GAAG,QAAQ,GAAG,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,GACvF,0BACJ,EAAA,CACY;AAChB"}

package/dist/api/entityQuery.d.ts

@@ -1,4 +1,4 @@
-import type { FilterClause, FilterExpression, EntityQueryParams, QueryObject } from "../types/entityQuery.d.ts";
+import type { FilterClause, FilterExpression, EntityQueryParams, Projection, QueryObject } from "../types/entityQuery.d.ts";
 /**
  * toFilterTuple
  *
@@ -21,58 +21,63 @@ import type { FilterClause, FilterExpression, EntityQueryParams, QueryObject } f
  * ```
  */
 export declare const toFilterTuple: (filter: FilterClause) => FilterExpression;
+export declare const buildQueryObject: (params: EntityQueryParams) => QueryObject;
+/** What, besides the filters, changes the response a list read gets back. */
+export type QueryKeyParams = {
+    order?: string[];
+    projection?: Projection;
+    pageSize?: number;
+    fetchAllPages?: boolean;
+    /** The datastore hooks' `dataFormat`. In the key whenever a hook passes it; only those hooks do. */
+    dataFormat?: "object" | "matrix";
+};
 /**
- * buildQueryObject
+ * buildQueryKey
  *
- * Builds the query payload object to be sent to the API,
- * converting filters, ordering, pagination, and projection into the expected format.
+ * Builds the React Query cache key of a list read: the base keys, then one object holding
+ * everything that changes the response.
  *
- * @param {EntityQueryParams} params - Query parameters.
- * @param {FilterClause[]} params.filters - Filters to apply (converted via `toFilterTuple`).
- * @param {string[]} params.order - Sorting fields.
- * @param {number} [params.pageSize] - Number of items per page.
- * @param {string} [params.pageToken] - Cursor token for the next page.
- * @param {string} [params.projection] - Single field to project. `"field"` returns only that
- *   field (every other field comes back null); `"-field"` returns all fields except that one.
- *   One field only — comma/space lists return a 500. Omitted from payload if empty.
- * @returns {QueryObject} Query payload ready to be passed to the API.
+ * Every part of the request is in the key, not only the filter values. The key used to be
+ * `[...keys, ...values]`, so a `-data` metadata read and a full read of the same workspace,
+ * or `date = X` and `date >= X`, shared one cache entry and one of them rendered the other's
+ * data. Filters go in as the tuples the API receives, so field and operator are included.
+ *
+ * The base keys stay in front, so prefix invalidation keeps working:
+ * `invalidateQueries({ queryKey: ["workflow_executions", workflowId] })`.
+ *
+ * @param {(string | number | null)[]} keys - Base keys (entity name, then any ids).
+ * @param {FilterClause[]} filters - The filters of the read.
+ * @param {QueryKeyParams} [params] - Order, projection, page size and paging mode.
+ * @returns {unknown[]} Cache key array for use in `queryKey`.
  *
  * Example:
  * ```ts
- * buildQueryObject({
- *   filters: [{ field: "workspace", value: "ws-1" }],
- *   order: ["name"], // plain field name(s) only — no "asc"/"desc" suffix
- *   pageSize: 10,
- *   pageToken: "token-abc",
- *   projection: "name",
- * });
- * // -> {
- * //   filters: [["workspace", "ws-1"]],
- * //   order: ["name"],
- * //   projection: "name",
- * //   page_size: 10,
- * //   page_token: "token-abc",
- * // }
+ * buildQueryKey(["datastores"], [{ field: "workspace", value: "ws-1" }], { pageSize: 10 });
+ * // -> ["datastores", { filters: [["workspace", "ws-1"]], pageSize: 10 }]
  * ```
  */
-export declare const buildQueryObject: (params: EntityQueryParams) => QueryObject;
+export declare const buildQueryKey: (keys: (string | number | null)[], filters: FilterClause[], { order, projection, pageSize, fetchAllPages, dataFormat }?: QueryKeyParams) => unknown[];
 /**
- * buildQueryKey
+ * hasWorkspaceFilter
  *
- * Builds a stable React Query cache key by combining a base key array
- * with the values of the provided filters.
+ * Whether a read can be sent: every endpoint that takes filters rejects a request with no
+ * workspace. It reads the workspace through `workspaceOf`, as the list functions in `api/` do:
+ * while each read it its own way, it passed on a filter the request then ignored.
  *
- * This ensures the query is re-executed whenever filter values change.
+ * @param {FilterClause[]} filters - The filters of the read.
+ * @returns {boolean} True when the first `workspace` filter carries a value.
+ */
+export declare const hasWorkspaceFilter: (filters: FilterClause[]) => boolean;
+/**
+ * missingWorkspaceError
  *
- * @param {(string | number)[]} keys - Base keys (e.g. entity name, id).
- * @param {FilterClause[]} filters - Filters whose values are appended to the key.
- * @returns {unknown[]} Cache key array for use in `queryKey`.
+ * The reason a hook gives, as `configError`, when it has no workspace to read. A missing
+ * workspace is a misconfigured app, never a state to wait out: the app config is merged into
+ * `window.APP_CONFIG` before the app renders, so an empty value there is a wrong or misspelled
+ * key. The message names the hook, so it points at the call to fix.
  *
- * Example:
- * ```ts
- * buildQueryKey(["datastores"], [{ field: "workspace", value: "ws-1" }]);
- * // -> ["datastores", "ws-1"]
- * ```
+ * @param {string} hookName - The hook that could not send its request.
+ * @returns {string} The error message.
  */
-export declare const buildQueryKey: (keys: (string | number)[], filters: FilterClause[]) => unknown[];
+export declare const missingWorkspaceError: (hookName: string) => string;
 //# sourceMappingURL=entityQuery.d.ts.map

package/dist/api/entityQuery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entityQuery.d.ts","sourceRoot":"","sources":["../../src/api/entityQuery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE1G;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,YAAY,KAAG,gBAMpD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,iBAAiB,KAAG,WAU5D,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EAAE,SAAS,YAAY,EAAE,KAAG,OAAO,EAKzF,CAAA"}
+{"version":3,"file":"entityQuery.d.ts","sourceRoot":"","sources":["../../src/api/entityQuery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,WAAW,EACd,MAAM,qBAAqB,CAAC;AAG7B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,YAAY,KAAG,gBAMpD,CAAC;AAyCF,eAAO,MAAM,gBAAgB,GAAI,QAAQ,iBAAiB,KAAG,WAU5D,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,cAAc,GAAG;IACzB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,oGAAoG;IACpG,UAAU,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;CACpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,aAAa,GACtB,MAAM,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,EAChC,SAAS,YAAY,EAAE,EACvB,6DAA4D,cAAmB,KAChF,OAAO,EAaT,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,YAAY,EAAE,KAAG,OACT,CAAC;AAErD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,GAAI,UAAU,MAAM,KAAG,MAED,CAAC"}

package/dist/api/entityQuery.js

@@ -1,3 +1,4 @@
+import { workspaceOf } from "./request.js";
 //#region src/api/entityQuery.ts
 /**
 * toFilterTuple
@@ -40,9 +41,10 @@ var toFilterTuple = (filter) => {
 * @param {string[]} params.order - Sorting fields.
 * @param {number} [params.pageSize] - Number of items per page.
 * @param {string} [params.pageToken] - Cursor token for the next page.
-* @param {string} [params.projection] - Single field to project. `"field"` returns only that
-*   field (every other field comes back null); `"-field"` returns all fields except that one.
-*   One field only — comma/space lists return a 500. Omitted from payload if empty.
+* @param {Projection} [params.projection] - The fields to return: one, or a list. `"field"`
+*   returns only that field (every other field comes back null); `"-field"` returns all fields
+*   except that one. Pass several as a list, never comma-joined: `"a,b"` is a 500. Omitted from
+*   the payload when empty.
 * @returns {QueryObject} Query payload ready to be passed to the API.
 *
 * Example:
@@ -63,12 +65,14 @@ var toFilterTuple = (filter) => {
 * // }
 * ```
 */
+/** An empty string or list asks for every field, as no projection does. */
+var hasProjection = (projection) => projection !== void 0 && projection.length > 0;
 var buildQueryObject = (params) => {
 	const { filters, pageSize, pageToken, order, projection } = params;
 	return {
 		filters: filters.map(toFilterTuple),
 		order,
-		...!!projection && { projection },
+		...hasProjection(projection) && { projection },
 		page_size: pageSize,
 		page_token: pageToken
 	};
@@ -76,25 +80,62 @@ var buildQueryObject = (params) => {
 /**
 * buildQueryKey
 *
-* Builds a stable React Query cache key by combining a base key array
-* with the values of the provided filters.
+* Builds the React Query cache key of a list read: the base keys, then one object holding
+* everything that changes the response.
 *
-* This ensures the query is re-executed whenever filter values change.
+* Every part of the request is in the key, not only the filter values. The key used to be
+* `[...keys, ...values]`, so a `-data` metadata read and a full read of the same workspace,
+* or `date = X` and `date >= X`, shared one cache entry and one of them rendered the other's
+* data. Filters go in as the tuples the API receives, so field and operator are included.
 *
-* @param {(string | number)[]} keys - Base keys (e.g. entity name, id).
-* @param {FilterClause[]} filters - Filters whose values are appended to the key.
+* The base keys stay in front, so prefix invalidation keeps working:
+* `invalidateQueries({ queryKey: ["workflow_executions", workflowId] })`.
+*
+* @param {(string | number | null)[]} keys - Base keys (entity name, then any ids).
+* @param {FilterClause[]} filters - The filters of the read.
+* @param {QueryKeyParams} [params] - Order, projection, page size and paging mode.
 * @returns {unknown[]} Cache key array for use in `queryKey`.
 *
 * Example:
 * ```ts
-* buildQueryKey(["datastores"], [{ field: "workspace", value: "ws-1" }]);
-* // -> ["datastores", "ws-1"]
+* buildQueryKey(["datastores"], [{ field: "workspace", value: "ws-1" }], { pageSize: 10 });
+* // -> ["datastores", { filters: [["workspace", "ws-1"]], pageSize: 10 }]
 * ```
 */
-var buildQueryKey = (keys, filters) => {
-	return [...keys, ...filters.flatMap((filter) => filter.value)];
+var buildQueryKey = (keys, filters, { order, projection, pageSize, fetchAllPages, dataFormat } = {}) => {
+	return [...keys, {
+		filters: filters.map(toFilterTuple),
+		...order?.length ? { order } : {},
+		...hasProjection(projection) ? { projection } : {},
+		...pageSize !== void 0 ? { pageSize } : {},
+		...fetchAllPages ? { fetchAllPages } : {},
+		...dataFormat ? { dataFormat } : {}
+	}];
 };
+/**
+* hasWorkspaceFilter
+*
+* Whether a read can be sent: every endpoint that takes filters rejects a request with no
+* workspace. It reads the workspace through `workspaceOf`, as the list functions in `api/` do:
+* while each read it its own way, it passed on a filter the request then ignored.
+*
+* @param {FilterClause[]} filters - The filters of the read.
+* @returns {boolean} True when the first `workspace` filter carries a value.
+*/
+var hasWorkspaceFilter = (filters) => Boolean(workspaceOf(filters.map(toFilterTuple)));
+/**
+* missingWorkspaceError
+*
+* The reason a hook gives, as `configError`, when it has no workspace to read. A missing
+* workspace is a misconfigured app, never a state to wait out: the app config is merged into
+* `window.APP_CONFIG` before the app renders, so an empty value there is a wrong or misspelled
+* key. The message names the hook, so it points at the call to fix.
+*
+* @param {string} hookName - The hook that could not send its request.
+* @returns {string} The error message.
+*/
+var missingWorkspaceError = (hookName) => `[apps-sdk] ${hookName}: the "workspace" filter is missing or empty, so the request was not sent. Check the workspace the app config provides.`;
 //#endregion
-export { buildQueryKey, buildQueryObject, toFilterTuple };
+export { buildQueryKey, buildQueryObject, hasWorkspaceFilter, missingWorkspaceError, toFilterTuple };
 
 //# sourceMappingURL=entityQuery.js.map

package/dist/api/entityQuery.js.map

@@ -1 +1 @@
-{"version":3,"file":"entityQuery.js","names":[],"sources":["../../src/api/entityQuery.ts"],"sourcesContent":["import type { FilterClause, FilterExpression, EntityQueryParams, QueryObject } from \"@/types/entityQuery\";\n\n/**\n * toFilterTuple\n *\n * Converts a `FilterClause` object into a `FilterExpression` tuple\n * compatible with the API query format.\n *\n * - If no operator is provided or operator is `\"=\"`, returns a 2-tuple `[field, value]`.\n * - Otherwise, returns a 3-tuple `[field, op, value]`.\n *\n * @param {FilterClause} filter - Filter clause to convert.\n * @returns {FilterExpression} Tuple representation of the filter.\n *\n * Examples:\n * ```ts\n * toFilterTuple({ field: \"workspace\", value: \"ws-1\" })\n * // -> [\"workspace\", \"ws-1\"]\n *\n * toFilterTuple({ field: \"age\", op: \">=\", value: 18 })\n * // -> [\"age\", \">=\", 18]\n * ```\n */\nexport const toFilterTuple = (filter: FilterClause): FilterExpression => {\n    const { field, op, value } = filter;\n    if (!op || op === '=') {\n        return [field, value];\n    }\n    return [field, op, value];\n};\n\n/**\n * buildQueryObject\n *\n * Builds the query payload object to be sent to the API,\n * converting filters, ordering, pagination, and projection into the expected format.\n *\n * @param {EntityQueryParams} params - Query parameters.\n * @param {FilterClause[]} params.filters - Filters to apply (converted via `toFilterTuple`).\n * @param {string[]} params.order - Sorting fields.\n * @param {number} [params.pageSize] - Number of items per page.\n * @param {string} [params.pageToken] - Cursor token for the next page.\n * @param {string} [params.projection] - Single field to project. `\"field\"` returns only that\n *   field (every other field comes back null); `\"-field\"` returns all fields except that one.\n *   One field only — comma/space lists return a 500. Omitted from payload if empty.\n * @returns {QueryObject} Query payload ready to be passed to the API.\n *\n * Example:\n * ```ts\n * buildQueryObject({\n *   filters: [{ field: \"workspace\", value: \"ws-1\" }],\n *   order: [\"name\"], // plain field name(s) only — no \"asc\"/\"desc\" suffix\n *   pageSize: 10,\n *   pageToken: \"token-abc\",\n *   projection: \"name\",\n * });\n * // -> {\n * //   filters: [[\"workspace\", \"ws-1\"]],\n * //   order: [\"name\"],\n * //   projection: \"name\",\n * //   page_size: 10,\n * //   page_token: \"token-abc\",\n * // }\n * ```\n */\nexport const buildQueryObject = (params: EntityQueryParams): QueryObject => {\n    const { filters, pageSize, pageToken, order, projection } = params;\n\n    return {\n        filters: filters.map(toFilterTuple),\n        order,\n        ...(!!projection && { projection }),\n        page_size: pageSize,\n        page_token: pageToken,\n    };\n}\n\n/**\n * buildQueryKey\n *\n * Builds a stable React Query cache key by combining a base key array\n * with the values of the provided filters.\n *\n * This ensures the query is re-executed whenever filter values change.\n *\n * @param {(string | number)[]} keys - Base keys (e.g. entity name, id).\n * @param {FilterClause[]} filters - Filters whose values are appended to the key.\n * @returns {unknown[]} Cache key array for use in `queryKey`.\n *\n * Example:\n * ```ts\n * buildQueryKey([\"datastores\"], [{ field: \"workspace\", value: \"ws-1\" }]);\n * // -> [\"datastores\", \"ws-1\"]\n * ```\n */\nexport const buildQueryKey = (keys: (string | number)[], filters: FilterClause[]): unknown[] => {\n    return [\n        ...keys,\n        ...filters.flatMap((filter) => filter.value)\n    ];\n}"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAuBA,IAAa,iBAAiB,WAA2C;CACrE,MAAM,EAAE,OAAO,IAAI,UAAU;CAC7B,IAAI,CAAC,MAAM,OAAO,KACd,OAAO,CAAC,OAAO,KAAK;CAExB,OAAO;EAAC;EAAO;EAAI;CAAK;AAC5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,IAAa,oBAAoB,WAA2C;CACxE,MAAM,EAAE,SAAS,UAAU,WAAW,OAAO,eAAe;CAE5D,OAAO;EACH,SAAS,QAAQ,IAAI,aAAa;EAClC;EACA,GAAI,CAAC,CAAC,cAAc,EAAE,WAAW;EACjC,WAAW;EACX,YAAY;CAChB;AACJ;;;;;;;;;;;;;;;;;;;AAoBA,IAAa,iBAAiB,MAA2B,YAAuC;CAC5F,OAAO,CACH,GAAG,MACH,GAAG,QAAQ,SAAS,WAAW,OAAO,KAAK,CAC/C;AACJ"}
+{"version":3,"file":"entityQuery.js","names":[],"sources":["../../src/api/entityQuery.ts"],"sourcesContent":["import type {\n    FilterClause,\n    FilterExpression,\n    EntityQueryParams,\n    Projection,\n    QueryObject,\n} from \"@/types/entityQuery\";\nimport { workspaceOf } from \"./request\";\n\n/**\n * toFilterTuple\n *\n * Converts a `FilterClause` object into a `FilterExpression` tuple\n * compatible with the API query format.\n *\n * - If no operator is provided or operator is `\"=\"`, returns a 2-tuple `[field, value]`.\n * - Otherwise, returns a 3-tuple `[field, op, value]`.\n *\n * @param {FilterClause} filter - Filter clause to convert.\n * @returns {FilterExpression} Tuple representation of the filter.\n *\n * Examples:\n * ```ts\n * toFilterTuple({ field: \"workspace\", value: \"ws-1\" })\n * // -> [\"workspace\", \"ws-1\"]\n *\n * toFilterTuple({ field: \"age\", op: \">=\", value: 18 })\n * // -> [\"age\", \">=\", 18]\n * ```\n */\nexport const toFilterTuple = (filter: FilterClause): FilterExpression => {\n    const { field, op, value } = filter;\n    if (!op || op === \"=\") {\n        return [field, value];\n    }\n    return [field, op, value];\n};\n\n/**\n * buildQueryObject\n *\n * Builds the query payload object to be sent to the API,\n * converting filters, ordering, pagination, and projection into the expected format.\n *\n * @param {EntityQueryParams} params - Query parameters.\n * @param {FilterClause[]} params.filters - Filters to apply (converted via `toFilterTuple`).\n * @param {string[]} params.order - Sorting fields.\n * @param {number} [params.pageSize] - Number of items per page.\n * @param {string} [params.pageToken] - Cursor token for the next page.\n * @param {Projection} [params.projection] - The fields to return: one, or a list. `\"field\"`\n *   returns only that field (every other field comes back null); `\"-field\"` returns all fields\n *   except that one. Pass several as a list, never comma-joined: `\"a,b\"` is a 500. Omitted from\n *   the payload when empty.\n * @returns {QueryObject} Query payload ready to be passed to the API.\n *\n * Example:\n * ```ts\n * buildQueryObject({\n *   filters: [{ field: \"workspace\", value: \"ws-1\" }],\n *   order: [\"name\"], // plain field name(s) only — no \"asc\"/\"desc\" suffix\n *   pageSize: 10,\n *   pageToken: \"token-abc\",\n *   projection: \"name\",\n * });\n * // -> {\n * //   filters: [[\"workspace\", \"ws-1\"]],\n * //   order: [\"name\"],\n * //   projection: \"name\",\n * //   page_size: 10,\n * //   page_token: \"token-abc\",\n * // }\n * ```\n */\n/** An empty string or list asks for every field, as no projection does. */\nconst hasProjection = (projection: Projection | undefined): projection is Projection =>\n    projection !== undefined && projection.length > 0;\n\nexport const buildQueryObject = (params: EntityQueryParams): QueryObject => {\n    const { filters, pageSize, pageToken, order, projection } = params;\n\n    return {\n        filters: filters.map(toFilterTuple),\n        order,\n        ...(hasProjection(projection) && { projection }),\n        page_size: pageSize,\n        page_token: pageToken,\n    };\n};\n\n/** What, besides the filters, changes the response a list read gets back. */\nexport type QueryKeyParams = {\n    order?: string[];\n    projection?: Projection;\n    pageSize?: number;\n    fetchAllPages?: boolean;\n    /** The datastore hooks' `dataFormat`. In the key whenever a hook passes it; only those hooks do. */\n    dataFormat?: \"object\" | \"matrix\";\n};\n\n/**\n * buildQueryKey\n *\n * Builds the React Query cache key of a list read: the base keys, then one object holding\n * everything that changes the response.\n *\n * Every part of the request is in the key, not only the filter values. The key used to be\n * `[...keys, ...values]`, so a `-data` metadata read and a full read of the same workspace,\n * or `date = X` and `date >= X`, shared one cache entry and one of them rendered the other's\n * data. Filters go in as the tuples the API receives, so field and operator are included.\n *\n * The base keys stay in front, so prefix invalidation keeps working:\n * `invalidateQueries({ queryKey: [\"workflow_executions\", workflowId] })`.\n *\n * @param {(string | number | null)[]} keys - Base keys (entity name, then any ids).\n * @param {FilterClause[]} filters - The filters of the read.\n * @param {QueryKeyParams} [params] - Order, projection, page size and paging mode.\n * @returns {unknown[]} Cache key array for use in `queryKey`.\n *\n * Example:\n * ```ts\n * buildQueryKey([\"datastores\"], [{ field: \"workspace\", value: \"ws-1\" }], { pageSize: 10 });\n * // -> [\"datastores\", { filters: [[\"workspace\", \"ws-1\"]], pageSize: 10 }]\n * ```\n */\nexport const buildQueryKey = (\n    keys: (string | number | null)[],\n    filters: FilterClause[],\n    { order, projection, pageSize, fetchAllPages, dataFormat }: QueryKeyParams = {},\n): unknown[] => {\n    return [\n        ...keys,\n        {\n            filters: filters.map(toFilterTuple),\n            ...(order?.length ? { order } : {}),\n            // The request omits an empty projection, so the key must not tell it apart.\n            ...(hasProjection(projection) ? { projection } : {}),\n            ...(pageSize !== undefined ? { pageSize } : {}),\n            ...(fetchAllPages ? { fetchAllPages } : {}),\n            ...(dataFormat ? { dataFormat } : {}),\n        },\n    ];\n};\n\n/**\n * hasWorkspaceFilter\n *\n * Whether a read can be sent: every endpoint that takes filters rejects a request with no\n * workspace. It reads the workspace through `workspaceOf`, as the list functions in `api/` do:\n * while each read it its own way, it passed on a filter the request then ignored.\n *\n * @param {FilterClause[]} filters - The filters of the read.\n * @returns {boolean} True when the first `workspace` filter carries a value.\n */\nexport const hasWorkspaceFilter = (filters: FilterClause[]): boolean =>\n    Boolean(workspaceOf(filters.map(toFilterTuple)));\n\n/**\n * missingWorkspaceError\n *\n * The reason a hook gives, as `configError`, when it has no workspace to read. A missing\n * workspace is a misconfigured app, never a state to wait out: the app config is merged into\n * `window.APP_CONFIG` before the app renders, so an empty value there is a wrong or misspelled\n * key. The message names the hook, so it points at the call to fix.\n *\n * @param {string} hookName - The hook that could not send its request.\n * @returns {string} The error message.\n */\nexport const missingWorkspaceError = (hookName: string): string =>\n    `[apps-sdk] ${hookName}: the \"workspace\" filter is missing or empty, so the request was not ` +\n    \"sent. Check the workspace the app config provides.\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AA8BA,IAAa,iBAAiB,WAA2C;CACrE,MAAM,EAAE,OAAO,IAAI,UAAU;CAC7B,IAAI,CAAC,MAAM,OAAO,KACd,OAAO,CAAC,OAAO,KAAK;CAExB,OAAO;EAAC;EAAO;EAAI;CAAK;AAC5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,IAAM,iBAAiB,eACnB,eAAe,KAAA,KAAa,WAAW,SAAS;AAEpD,IAAa,oBAAoB,WAA2C;CACxE,MAAM,EAAE,SAAS,UAAU,WAAW,OAAO,eAAe;CAE5D,OAAO;EACH,SAAS,QAAQ,IAAI,aAAa;EAClC;EACA,GAAI,cAAc,UAAU,KAAK,EAAE,WAAW;EAC9C,WAAW;EACX,YAAY;CAChB;AACJ;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,IAAa,iBACT,MACA,SACA,EAAE,OAAO,YAAY,UAAU,eAAe,eAA+B,CAAC,MAClE;CACZ,OAAO,CACH,GAAG,MACH;EACI,SAAS,QAAQ,IAAI,aAAa;EAClC,GAAI,OAAO,SAAS,EAAE,MAAM,IAAI,CAAC;EAEjC,GAAI,cAAc,UAAU,IAAI,EAAE,WAAW,IAAI,CAAC;EAClD,GAAI,aAAa,KAAA,IAAY,EAAE,SAAS,IAAI,CAAC;EAC7C,GAAI,gBAAgB,EAAE,cAAc,IAAI,CAAC;EACzC,GAAI,aAAa,EAAE,WAAW,IAAI,CAAC;CACvC,CACJ;AACJ;;;;;;;;;;;AAYA,IAAa,sBAAsB,YAC/B,QAAQ,YAAY,QAAQ,IAAI,aAAa,CAAC,CAAC;;;;;;;;;;;;AAanD,IAAa,yBAAyB,aAClC,cAAc,SAAS"}