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

package/src/EveryskApp.tsx

@@ -12,6 +12,55 @@ import type { Theme } from "@mui/material/styles";
 /** A provider is any component that renders its children. */
 export type ProviderComponent = ComponentType<PropsWithChildren>;
 
+/** A provider with the props it is mounted with, as `withProps` describes it. */
+export type ConfiguredProvider = {
+    readonly component: ComponentType<PropsWithChildren<AnyRecord>>;
+    readonly props: AnyRecord;
+};
+
+/** What `providers` takes: a provider, or one with its props. */
+export type ProviderEntry = ProviderComponent | ConfiguredProvider;
+
+/**
+ * withProps
+ *
+ * A provider for `EveryskApp`'s `providers`, mounted with these props. `providers` mounts a bare
+ * component as `<Provider>{children}</Provider>`, so a provider configured by a prop — AG Grid's
+ * license key — needs its props said here:
+ *
+ * ```tsx
+ * <EveryskApp
+ *     providers={[
+ *         withProps(AgGridLicenseProvider, { licenseKey: import.meta.env.VITE_AG_GRID_LICENSE_KEY }),
+ *         WebSocketProvider,
+ *     ]}
+ * >
+ * ```
+ *
+ * It describes the provider rather than returning a wrapper component: a wrapper made in `App`'s
+ * render is a new component type each time, and React would remount the whole app under it on
+ * every render. The props are checked against the component's own.
+ */
+export const withProps = <P extends { children?: ReactNode }>(
+    component: ComponentType<P>,
+    props: NoInfer<Omit<P, "children">>,
+): ConfiguredProvider => ({
+    component: component as ComponentType<PropsWithChildren<AnyRecord>>,
+    props: props as AnyRecord,
+});
+
+const isConfigured = (entry: ProviderEntry): entry is ConfiguredProvider =>
+    typeof entry === "object" && entry !== null && "component" in entry && "props" in entry;
+
+const mount = (entry: ProviderEntry, children: ReactNode): ReactNode => {
+    if (!isConfigured(entry)) {
+        const Provider = entry;
+        return <Provider>{children}</Provider>;
+    }
+    const { component: Provider, props } = entry;
+    return <Provider {...props}>{children}</Provider>;
+};
+
 export type EveryskAppProps = PropsWithChildren<{
     /**
      * The client every `useQuery` in the tree talks to. Defaults to a fresh
@@ -36,8 +85,10 @@ export type EveryskAppProps = PropsWithChildren<{
      * `modules.json` kept an explicit `providerOrder` only because the app owned the tree and
      * each module had to be hand-wired into the right slot; owning the tree here is what
      * retires that contract.
+     *
+     * A provider configured by props goes in through `withProps`.
      */
-    providers?: ProviderComponent[];
+    providers?: ProviderEntry[];
 }>;
 
 /**
@@ -92,7 +143,7 @@ export const EveryskApp = ({
     const client = queryClient ?? fallbackQueryClient;
 
     const wrapped = (providers ?? []).reduceRight<ReactNode>(
-        (inner, Provider) => <Provider>{inner}</Provider>,
+        (inner, entry) => mount(entry, inner),
         children,
     );
 

package/src/agGrid/handleRowsScrollEnd.ts

@@ -0,0 +1,71 @@
+import type { GridApi } from "ag-grid-community";
+
+/**
+ * The part of an infinite query this needs. Structural, so it takes any list hook's `query`,
+ * or a `useInfiniteQuery` an app writes itself.
+ */
+export type InfiniteQueryPaging = {
+    hasNextPage: boolean;
+    isFetchingNextPage: boolean;
+    fetchNextPage: (options?: { cancelRefetch?: boolean }) => Promise<unknown>;
+};
+
+export type HandleRowsScrollEndOptions = {
+    /**
+     * Distance in pixels from the end of the rows at which the next page is requested. Named and
+     * measured as MUI X DataGrid's `scrollEndThreshold`, whose default it shares. Pixels rather
+     * than rows, so it holds with rows of different heights.
+     */
+    scrollEndThreshold?: number;
+};
+
+/**
+ * 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)}
+ * />
+ * ```
+ */
+export const handleRowsScrollEnd = (
+    gridApi: GridApi,
+    query: InfiniteQueryPaging,
+    { scrollEndThreshold = 80 }: HandleRowsScrollEndOptions = {},
+): void => {
+    if (!query.hasNextPage || query.isFetchingNextPage) return;
+
+    const rowCount = gridApi.getDisplayedRowCount();
+    const lastRow = rowCount > 0 ? gridApi.getDisplayedRowAtIndex(rowCount - 1) : undefined;
+
+    if (lastRow) {
+        const rowsEnd = (lastRow.rowTop ?? 0) + (lastRow.rowHeight ?? 0);
+        const { bottom } = gridApi.getVerticalPixelRange();
+
+        if (rowsEnd - bottom > scrollEndThreshold) return;
+    }
+
+    void query.fetchNextPage({ cancelRefetch: false });
+};

package/src/agGrid/index.ts

@@ -1,4 +1,5 @@
-// `@everysk/apps-sdk/ag-grid` — the grid layer: license registration and the grid theme.
+// `@everysk/apps-sdk/ag-grid` — the grid layer: license registration, the grid theme and
+// paging on scroll.
 //
 // `ag-grid-community` and `ag-grid-enterprise` are OPTIONAL peers: an app that never imports
 // this subpath does not install them, which keeps the grid out of the lockfile, out of CI
@@ -13,3 +14,6 @@ export { setAgGridLicense, AgGridLicenseProvider } from "@/contexts/agGridLicens
 export type { AgGridLicenseProviderProps } from "@/contexts/agGridLicenseContext/provider";
 
 export { getAgGridTheme, useAgGridTheme, agGridThemeParams } from "./agGridTheme";
+
+export { handleRowsScrollEnd } from "./handleRowsScrollEnd";
+export type { HandleRowsScrollEndOptions, InfiniteQueryPaging } from "./handleRowsScrollEnd";

package/src/api/datastore.ts

@@ -1,11 +1,20 @@
-import { isAxiosError, type AxiosInstance, type AxiosResponse } from "axios";
+import type { AxiosInstance } from "axios";
 
-import type { AnyRecord } from "@/types/anyRecord";
-import type { DeleteEntityDefaultResponse, FilterExpression, QueryObject } from "@/types/entityQuery";
-import type { Datastore, DatastoreSingleResponse, DatastoreListResponse, DeleteDatastoreResponse } from "@/types/datastore";
+import type {
+    DeletedEntity,
+    DeleteEntityResponse,
+    EntitySingleResponse,
+    QueryObject,
+} from "@/types/entityQuery";
+import type { Datastore, DatastoreListResponse } from "@/types/datastore";
+import { listParams, request, requireWorkspace } from "./request";
 
 const baseUrl = "datastores";
 
+/** The endpoint's envelopes, private: every function here returns the entity itself. */
+type DatastoreSingleResponse = EntitySingleResponse<"datastore", Datastore>;
+type DeleteDatastoreResponse = DeleteEntityResponse<"datastore">;
+
 /**
  * getDatastore
  *
@@ -14,29 +23,25 @@ const 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.
  */
-export const getDatastore = async (api: AxiosInstance, id: string, workspace: string): Promise<Datastore> => {
-  const params: AnyRecord = { workspace };
-
-  if (!workspace) throw new Error("Workspace filter is required to fetch a datastore");
-
-  try {
-    const response: AxiosResponse<DatastoreSingleResponse> = await api.get(`${baseUrl}/${id}`, { params });
-    return response.data.datastore;
-  } catch (error: unknown) {
-    if (isAxiosError<AnyRecord>(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 });
-  }
+export const getDatastore = async (
+    api: AxiosInstance,
+    id: string,
+    workspace: string,
+    signal?: AbortSignal,
+): Promise<Datastore> => {
+    requireWorkspace(workspace, "fetch a datastore");
+
+    const body = await request(
+        () =>
+            api.get<DatastoreSingleResponse>(`${baseUrl}/${id}`, { params: { workspace }, signal }),
+        "Error fetching datastore",
+    );
+    return body.datastore;
 };
 
 /**
@@ -45,37 +50,24 @@ export const getDatastore = async (api: AxiosInstance, id: string, workspace: st
  * 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 const listDatastores = async (api: AxiosInstance, query: QueryObject): Promise<DatastoreListResponse> => {
-  const workspaceFilter = query.filters.find((filter: FilterExpression) => filter[0] === "workspace");
-  const workspace = workspaceFilter?.[workspaceFilter.length - 1];
-
-  if (!workspace) throw new Error("Workspace filter is required to list datastores");
-
-  const params: AnyRecord = {
-    workspace,
-    ...(query ? { query: JSON.stringify(query) } : {}),
-  };
-
-  try {
-    const response: AxiosResponse<DatastoreListResponse> = await api.get(baseUrl, { params });
-    return response.data;
-  } catch (error: unknown) {
-    if (isAxiosError<AnyRecord>(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 });
-  }
+export const listDatastores = async (
+    api: AxiosInstance,
+    query: QueryObject,
+    signal?: AbortSignal,
+): Promise<DatastoreListResponse> => {
+    const params = listParams(query, "list datastores");
+
+    return request(
+        () => api.get<DatastoreListResponse>(baseUrl, { params, signal }),
+        "Error listing datastores",
+    );
 };
 
 /**
@@ -89,25 +81,17 @@ export const listDatastores = async (api: AxiosInstance, query: QueryObject): Pr
  *
  * @throws {Error} If the request fails.
  */
-export const createDatastore = async (api: AxiosInstance, data: Partial<Datastore>): Promise<Datastore> => {
-
-  const { workspace } = data;
-  if (!workspace) throw new Error("Workspace filter is required to create a datastore");
-
-  try {
-    const response: AxiosResponse<DatastoreSingleResponse> = await api.post(baseUrl, data);
-    return response.data.datastore;
-  } catch (error: unknown) {
-    if (isAxiosError<AnyRecord>(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 });
-  }
+export const createDatastore = async (
+    api: AxiosInstance,
+    data: Partial<Datastore>,
+): Promise<Datastore> => {
+    requireWorkspace(data.workspace, "create a datastore");
+
+    const body = await request(
+        () => api.post<DatastoreSingleResponse>(baseUrl, data),
+        "Error creating datastore",
+    );
+    return body.datastore;
 };
 
 /**
@@ -122,25 +106,18 @@ export const createDatastore = async (api: AxiosInstance, data: Partial<Datastor
  *
  * @throws {Error} If the request fails.
  */
-export const updateDatastore = async (api: AxiosInstance, id: string, data: Partial<Datastore>): Promise<Datastore> => {
-
-  const { workspace } = data;
-  if (!workspace) throw new Error("Workspace filter is required to update a datastore");
-
-  try {
-    const response: AxiosResponse<DatastoreSingleResponse> = await api.put(`${baseUrl}/${id}`, data);
-    return response.data.datastore;
-  } catch (error: unknown) {
-    if (isAxiosError<AnyRecord>(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 });
-  }
+export const updateDatastore = async (
+    api: AxiosInstance,
+    id: string,
+    data: Partial<Datastore>,
+): Promise<Datastore> => {
+    requireWorkspace(data.workspace, "update a datastore");
+
+    const body = await request(
+        () => api.put<DatastoreSingleResponse>(`${baseUrl}/${id}`, data),
+        "Error updating datastore",
+    );
+    return body.datastore;
 };
 
 /**
@@ -151,25 +128,20 @@ export const updateDatastore = async (api: AxiosInstance, id: string, data: Part
  * @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 const deleteDatastore = async (api: AxiosInstance, id: string, workspace: string): Promise<DeleteEntityDefaultResponse[]> => {
-  const params: AnyRecord = { workspace };
-
-  try {
-    const response: AxiosResponse<DeleteDatastoreResponse> = await api.delete(`${baseUrl}/${id}`, { params });
-    return response.data.datastores;
-  } catch (error: unknown) {
-    if (isAxiosError<AnyRecord>(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 });
-  }
-};
+export const deleteDatastore = async (
+    api: AxiosInstance,
+    id: string,
+    workspace: string,
+): Promise<DeletedEntity> => {
+    requireWorkspace(workspace, "delete a datastore");
+
+    const body = await request(
+        () => api.delete<DeleteDatastoreResponse>(`${baseUrl}/${id}`, { params: { workspace } }),
+        "Error deleting datastore",
+    );
+    return body.datastore;
+};

package/src/api/entityQuery.ts

@@ -1,4 +1,11 @@
-import type { FilterClause, FilterExpression, EntityQueryParams, QueryObject } from "@/types/entityQuery";
+import type {
+    FilterClause,
+    FilterExpression,
+    EntityQueryParams,
+    Projection,
+    QueryObject,
+} from "@/types/entityQuery";
+import { workspaceOf } from "./request";
 
 /**
  * toFilterTuple
@@ -23,7 +30,7 @@ import type { FilterClause, FilterExpression, EntityQueryParams, QueryObject } f
  */
 export const toFilterTuple = (filter: FilterClause): FilterExpression => {
     const { field, op, value } = filter;
-    if (!op || op === '=') {
+    if (!op || op === "=") {
         return [field, value];
     }
     return [field, op, value];
@@ -40,9 +47,10 @@ export const toFilterTuple = (filter: FilterClause): FilterExpression => {
  * @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,39 +71,100 @@ export const toFilterTuple = (filter: FilterClause): FilterExpression => {
  * // }
  * ```
  */
+/** An empty string or list asks for every field, as no projection does. */
+const hasProjection = (projection: Projection | undefined): projection is Projection =>
+    projection !== undefined && projection.length > 0;
+
 export const buildQueryObject = (params: EntityQueryParams): QueryObject => {
     const { filters, pageSize, pageToken, order, projection } = params;
 
     return {
         filters: filters.map(toFilterTuple),
         order,
-        ...(!!projection && { projection }),
+        ...(hasProjection(projection) && { projection }),
         page_size: pageSize,
         page_token: pageToken,
     };
-}
+};
+
+/** 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";
+};
 
 /**
  * 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 }]
  * ```
  */
-export const buildQueryKey = (keys: (string | number)[], filters: FilterClause[]): unknown[] => {
+export const buildQueryKey = (
+    keys: (string | number | null)[],
+    filters: FilterClause[],
+    { order, projection, pageSize, fetchAllPages, dataFormat }: QueryKeyParams = {},
+): unknown[] => {
     return [
         ...keys,
-        ...filters.flatMap((filter) => filter.value)
+        {
+            filters: filters.map(toFilterTuple),
+            ...(order?.length ? { order } : {}),
+            // The request omits an empty projection, so the key must not tell it apart.
+            ...(hasProjection(projection) ? { projection } : {}),
+            ...(pageSize !== undefined ? { 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.
+ */
+export const hasWorkspaceFilter = (filters: FilterClause[]): boolean =>
+    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.
+ */
+export const missingWorkspaceError = (hookName: string): string =>
+    `[apps-sdk] ${hookName}: the "workspace" filter is missing or empty, so the request was not ` +
+    "sent. Check the workspace the app config provides.";