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

package/src/hooks/datastore/useDatastoreMutations.ts

@@ -1,7 +1,5 @@
-import { useMutation, useQueryClient } from "@tanstack/react-query";
-
-import { useAxios } from "./../useAxios";
-import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import { useAxios } from "@/hooks/useAxios";
+import { useEntityMutation } from "@/hooks/useEntityMutation";
 import type { Datastore } from "@/types/datastore";
 import { deleteDatastore, createDatastore, updateDatastore } from "@/api/datastore";
 
@@ -23,9 +21,6 @@ type UseDatastoreMutationsProps = {
     queryKey?: unknown[];
 };
 
-const getErrorMessage = (err: unknown, fallback: string) =>
-    err instanceof Error && err.message ? err.message : fallback;
-
 /**
  * useDatastoreMutations
  *
@@ -79,7 +74,7 @@ const getErrorMessage = (err: unknown, fallback: string) =>
  *  Returns an object with the three TanStack Query mutation results:
  *  - `create`: UseMutationResult<Datastore, Error, CreateDatastoreProps, unknown>
  *  - `update`: UseMutationResult<Datastore, Error, UpdateDatastoreProps, unknown>
- *  - `remove`: UseMutationResult<Datastore, Error, DeleteDatastoreProps, unknown>
+ *  - `remove`: UseMutationResult<DeletedEntity, Error, DeleteDatastoreProps, unknown>
  *
  * Each mutation includes standard TanStack Query helpers:
  * - `mutate(variables, options?)`
@@ -158,63 +153,27 @@ const getErrorMessage = (err: unknown, fallback: string) =>
 
 export const useDatastoreMutations = ({ queryKey }: UseDatastoreMutationsProps) => {
     const { api } = useAxios();
-    const { showAlert } = useAppAlert();
-    const queryClient = useQueryClient();
-
-    const invalidate = async () => {
-        if (!queryKey?.length) return;
-        await queryClient.invalidateQueries({ queryKey });
-    };
 
-    const create = useMutation({
-        mutationFn: async ({ data }: CreateDatastoreProps) => createDatastore(api, data),
-        onSuccess: async () => {
-            await invalidate();
-            showAlert({
-                severity: "success",
-                message: "Datastore created successfully.",
-            });
-        },
-        onError: (err: unknown) => {
-            showAlert({
-                severity: "error",
-                message: getErrorMessage(err, "Unable to create the datastore. Please try again."),
-            });
-        },
+    const create = useEntityMutation({
+        mutationFn: ({ data }: CreateDatastoreProps) => createDatastore(api, data),
+        queryKey,
+        successMessage: "Datastore created successfully.",
+        errorMessage: "Unable to create the datastore. Please try again.",
     });
 
-    const update = useMutation({
-        mutationFn: async ({ id, data }: UpdateDatastoreProps) => updateDatastore(api, id, data),
-        onSuccess: async () => {
-            await invalidate();
-            showAlert({
-                severity: "success",
-                message: "Datastore updated successfully.",
-            });
-        },
-        onError: (err: unknown) => {
-            showAlert({
-                severity: "error",
-                message: getErrorMessage(err, "Unable to update the datastore. Please try again."),
-            });
-        },
+    const update = useEntityMutation({
+        mutationFn: ({ id, data }: UpdateDatastoreProps) => updateDatastore(api, id, data),
+        queryKey,
+        successMessage: "Datastore updated successfully.",
+        errorMessage: "Unable to update the datastore. Please try again.",
     });
 
-    const remove = useMutation({
-        mutationFn: async ({ id, workspace }: DeleteDatastoreProps) => deleteDatastore(api, id, workspace),
-        onSuccess: async () => {
-            await invalidate();
-            showAlert({
-                severity: "success",
-                message: "Datastore deleted successfully.",
-            });
-        },
-        onError: (err: unknown) => {
-            showAlert({
-                severity: "error",
-                message: getErrorMessage(err, "Unable to delete the datastore. Please try again."),
-            });
-        },
+    const remove = useEntityMutation({
+        mutationFn: ({ id, workspace }: DeleteDatastoreProps) =>
+            deleteDatastore(api, id, workspace),
+        queryKey,
+        successMessage: "Datastore deleted successfully.",
+        errorMessage: "Unable to delete the datastore. Please try again.",
     });
 
     return { create, update, remove };

package/src/hooks/datastore/useFetchDatastore.ts

@@ -1,95 +1,67 @@
-import { useEffect } from "react";
-
-import { useQuery } from "@tanstack/react-query";
-
 import { useAxios } from "@/hooks/useAxios";
-import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import { useEntityQuery } from "@/hooks/useEntityQuery";
+import { missingWorkspaceError } from "@/api/entityQuery";
 import { getDatastore } from "@/api/datastore";
-import { tableToObjects } from "@/lib/datastoreTable";
-import type { DatastoreWithRows } from "@/types/datastore";
-import type { EntityQueryOptions, FetchEntityParams } from "@/types/entityQuery";
-
-export type FetchDatastoreProps = FetchEntityParams<DatastoreWithRows>;
+import { parseDatastore } from "@/lib/datastoreTable";
+import type { ParsedDatastore } from "@/types/datastore";
+import type { DatastoreDataFormat } from "@/types/datastoreDataFormat";
+import type { FetchEntityByIdProps } from "@/types/entityQuery";
 
-const defaultQueryOptions: EntityQueryOptions<DatastoreWithRows> = {
-    refetchOnMount: "always",
-    staleTime: 0,
-    gcTime: 0,
+export type FetchDatastoreProps<
+    F extends DatastoreDataFormat = "object",
+    TSelected = ParsedDatastore<F>,
+> = FetchEntityByIdProps<ParsedDatastore<F>, TSelected> & {
+    /**
+     * 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;
 };
 
 /**
  * useFetchDatastore
  *
- * Data-fetching hook built on TanStack Query to retrieve a single datastore by ID.
- *
- * It also:
- * - triggers an error alert via `useAppAlert` whenever `query.error` is present
- *
- * Important notes:
- * - Returns a `DatastoreWithRows` object: the full `Datastore` shape with `data`
- *   replaced by `AnyRecord[]` (rows transformed via `tableToObjects`).
- *
- * Parameters (FetchDatastoreProps):
- * @param {string} id
- *   Datastore identifier (required).
+ * Fetches one datastore. `data` is a `ParsedDatastore` — a table's matrix converted to row
+ * objects with `fields`, or a JSON datastore's content untouched, told apart by `format`, the
+ * same shape `useFetchDatastores` returns — or whatever `select` makes of it. With
+ * `dataFormat: "matrix"` a tabular datastore keeps its matrix unconverted, as in `useFetchDatastores`.
  *
- * @param {string} workspace
- *   Workspace the datastore belongs to (required by `getDatastore`).
+ * Idle while `id` is empty; fails loudly, without a request, while `workspace` is. A failure is
+ * shown as an error alert.
  *
- * @param {EntityQueryOptions<DatastoreWithRows>} [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
+ * @param {FetchDatastoreProps} props - `id`, `workspace`, `dataFormat`, `select` and TanStack
+ *   `queryOptions`.
+ * @returns {object} The `useQuery` result, plus `queryKey`.
  *
  * Example:
  * ```ts
- * const { data, isLoading } = useFetchDatastore({
- *   id: "abc123",
- *   workspace: "my-workspace",
- * });
- * // data -> DatastoreWithRows (datastore metadata + rows as AnyRecord[])
- * // data.name -> "my-datastore"
- * // data.data -> [{ datastoreId: "abc123", col1: "value", ... }]
+ * const { data, isLoading, queryKey } = useFetchDatastore({ id: "abc123", workspace: "ws-1" });
  * ```
  */
-export const useFetchDatastore = ({ id, workspace, queryOptions = defaultQueryOptions }: FetchDatastoreProps) => {
-
+export const useFetchDatastore = <
+    F extends DatastoreDataFormat = "object",
+    TSelected = ParsedDatastore<F>,
+>({
+    id,
+    workspace,
+    dataFormat,
+    select,
+    queryOptions,
+}: FetchDatastoreProps<F, TSelected>) => {
     const { api } = useAxios();
-    const { showAlert } = useAppAlert();
 
-    const queryKey = ["datastore", id, workspace];
+    const format = (dataFormat ?? "object") as F;
+    const queryKey = ["datastore", id, workspace, format];
 
-    const query = useQuery<DatastoreWithRows>({
+    const query = useEntityQuery<ParsedDatastore<F>, TSelected>({
         queryKey,
-        queryFn: async () => {
-            const datastore = await getDatastore(api, id, workspace);
-
-            return {
-                ...datastore,
-                data: tableToObjects(
-                    datastore.id,
-                    datastore.data?.[0] as string[],
-                    datastore.data
-                ),
-            };
-        },
-        ...queryOptions ?? {}
+        fetchEntity: async (signal) =>
+            parseDatastore(await getDatastore(api, id, workspace, signal), format),
+        select,
+        enabled: Boolean(id),
+        configError: workspace ? undefined : missingWorkspaceError("useFetchDatastore"),
+        queryOptions,
     });
 
-    useEffect(() => {
-        if (!query.error) return;
-
-        showAlert({
-            severity: "error",
-            message: query.error.message,
-        });
-    }, [query.error, showAlert]);
-
-    return {
-        ...query,
-        queryKey,
-    };
+    return { ...query, queryKey };
 };

package/src/hooks/datastore/useFetchDatastores.ts

@@ -1,162 +1,137 @@
-//import { useCallback, useMemo, useRef } from "react";
-import { useMemo } from "react";
-import { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
-
-//import type { GridApi } from "ag-grid-community";
-
 import { useAxios } from "@/hooks/useAxios";
-import { tableToObjects } from "@/lib/datastoreTable";
+import { useEntityInfiniteQuery } from "@/hooks/useEntityInfiniteQuery";
+import { parseDatastore } from "@/lib/datastoreTable";
 import { listDatastores } from "@/api/datastore";
 
-import type { Datastore, DatastoreListResponse, DatastoreWithRows } from "@/types/datastore";
-import type { FetchEntitiesParams, EntityDefaultResponse } from "@/types/entityQuery";
-import { buildQueryKey, buildQueryObject } from "@/api/entityQuery";
-
-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 { DatastoreListResponse, ParsedDatastore } from "@/types/datastore";
+import type { DatastoreDataFormat } from "@/types/datastoreDataFormat";
+import type {
+    PagedResponse,
+    FetchEntitiesProps,
+    ListQueryProps,
+    ListCache,
+} from "@/types/entityQuery";
+import {
+    buildQueryKey,
+    buildQueryObject,
+    hasWorkspaceFilter,
+    missingWorkspaceError,
+} from "@/api/entityQuery";
+
+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>
+>;
 
-const defaultQueryOptions: InfiniteOptions<DatastoreWithRows[]> = {
-    refetchOnMount: "always",
-    staleTime: 0,
-    gcTime: 0,
-};
+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.
- *
- * It also:
- * - flattens all pages into a single `DatastoreWithRows[]` via `select`
- * - exposes `actions` for cache management
- * - exposes `events` for ag-Grid integration
- *
- * 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`).
+ * 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.
  *
- * Parameters (FetchInfiniteDatastoreProps):
- * @param {FilterClause[]} [filters=[]]
- *   Filters applied to every page request. Must include a `workspace` filter.
+ * 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.
  *
- * @param {string[]} [order=[]]
- *   Sorting applied to every page request.
+ * 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.
  *
- * @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.
+ * 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 {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 function useFetchDatastores({ filters = [], order = [], projection = "", pageSize = 10, queryOptions }: FetchInfiniteDatastoreProps) {
+export function useFetchDatastores<
+    F extends DatastoreDataFormat = "object",
+    TData = ParsedDatastore<F>[],
+>({
+    filters = [],
+    order = [],
+    projection = "",
+    pageSize = 10,
+    dataFormat,
+    select,
+    fetchAllPages = false,
+    queryOptions,
+}: FetchDatastoresProps<F, TData>) {
     const { api } = useAxios();
 
-    //const fetchingGuardRef = useRef(false);
-    const queryKey = buildQueryKey(["datastores"], filters);
-
-    const mergedQueryOptions = useMemo<InfiniteOptions<DatastoreWithRows[]>>(() => ({
-        ...defaultQueryOptions,
-        ...(queryOptions ?? {}),
-    }), [queryOptions]);
+    const format = (dataFormat ?? "object") as F;
+    const queryKey = buildQueryKey(["datastores"], filters, {
+        order,
+        projection,
+        pageSize,
+        fetchAllPages,
+        dataFormat: format,
+    });
 
-    const query = useInfiniteQuery<DatastoreQueryPage, Error, DatastoreWithRows[], QueryKey, PageToken>({
+    const query = useEntityInfiniteQuery<DatastoreQueryPage<F>, "datastores", TData>({
         queryKey,
-        initialPageParam: null,
-        getNextPageParam: (lastPage) => lastPage.next_page_token ?? undefined,
-
-        queryFn: async ({ pageParam }) => {
-            const queryFilter = buildQueryObject({
-                filters,
-                order,
-                projection,
-                pageSize,
-                pageToken: pageParam ?? undefined,
-            });
-
-            const response: DatastoreListResponse = await listDatastores(api, queryFilter);
-
-            const nested: DatastoreWithRows[] = response.datastores.map((datastore: Datastore) => ({
-                ...datastore,
-                data: tableToObjects(
-                    datastore.id,
-                    datastore.data?.[0] as string[],
-                    datastore.data
-                ),
-            }));
+        itemsKey: "datastores",
+        fetchPage: async (pageToken, signal) => {
+            const response: DatastoreListResponse = await listDatastores(
+                api,
+                buildQueryObject({ filters, order, projection, pageSize, 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)
+            ? undefined
+            : missingWorkspaceError("useFetchDatastores"),
+        queryOptions,
     });
 
-    /*
-    const { hasNextPage, isFetchingNextPage, fetchNextPage } = query;
-    const handleFetchIfGridEmptyOrNearEnd = useCallback((gridApi: GridApi) => {
-        if (!hasNextPage || isFetchingNextPage || fetchingGuardRef.current) return;
-
-        const total = gridApi.getDisplayedRowCount();
-        const last = gridApi.getLastDisplayedRowIndex();
-
-        const isEmpty = total === 0 || last < 0;
-        const isNearEnd = !isEmpty && (total - 1 - last) <= 30;
-
-        if (!isEmpty && !isNearEnd) return;
-
-        fetchingGuardRef.current = true;
-        fetchNextPage().finally(() => {
-            fetchingGuardRef.current = false;
-        });
-    }, [hasNextPage, isFetchingNextPage, fetchNextPage]);
-    */
-
-    return {
-        query,
-        queryKey,
-        //events: { handleFetchIfGridEmptyOrNearEnd },
-    };
-}
+    return { query, queryKey };
+}

package/src/hooks/file/fileData.ts

@@ -0,0 +1,19 @@
+import type { EveryskFile } from "@/types/file";
+
+/** 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 const withoutData = <F extends { data: EveryskFile["data"] }>(file: F): F => ({
+    ...file,
+    data: null,
+});