@everysk/apps-sdk 0.1.0-beta.0

package/src/contexts/webSocketContext/provider.tsx

@@ -0,0 +1,125 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import { getWebsocketsConfig } from "@/api/websocketsConfig";
+import { useAxios } from "@/hooks/useAxios";
+import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import { WebSocketContext } from ".";
+import { WebSocketHandler } from "./handler";
+import type { WebSocketContextType, WebSocketNotification, WebSocketProviderProps, WebSocketStatus } from "./types";
+
+/**
+ * WebSocketProvider
+ *
+ * React context provider that exposes a receive-only pub/sub API backed by Socket.IO.
+ *
+ * What this provider does:
+ * - Fetches `/api/websockets_config` once on mount to get the connection URL, channel id,
+ *   and session uid. Socket.IO handles reconnection internally — the config is not re-fetched.
+ * - Opens a `WebSocketHandler` instance that connects and joins the per-user channel.
+ * - Exposes `subscribe`, `lastMessage`, and `status` via `WebSocketContext`.
+ *
+ * Why the pending buffer exists (`pendingRef`):
+ * - The handler is created asynchronously (after the config fetch resolves).
+ * - Consumers that call `subscribe` before the handler is ready have their callbacks buffered
+ *   and registered once the handler initializes, ensuring no early subscriptions are lost.
+ *
+ * Subscribe buffering behavior:
+ * - If `subscribe(fn)` is called before the handler exists, `fn` is stored with a `null` placeholder.
+ * - Once the handler is ready, all pending callbacks are registered and their unsubscribe functions
+ *   stored back into the map.
+ * - The returned cleanup always works: it calls the real unsubscribe if available, or removes
+ *   the entry from the pending map.
+ *
+ * Usage:
+ * ```tsx
+ * <WebSocketProvider>
+ *   <YourPage />
+ * </WebSocketProvider>
+ * ```
+ *
+ * Context value (WebSocketContextType):
+ * @returns {object}
+ *  - `subscribe(fn)`: register a listener; returns an unsubscribe function.
+ *  - `lastMessage`: the most recently received notification (or null).
+ *  - `status`: current connection status ("connecting" | "connected" | "error").
+ */
+export const WebSocketProvider = ({ children }: WebSocketProviderProps) => {
+    const { api } = useAxios();
+    const { showAlert } = useAppAlert();
+
+    // Refs keep the latest values accessible inside the mount-only effect without
+    // making it re-run when api or showAlert change.
+    const apiRef = useRef(api);
+    const showAlertRef = useRef(showAlert);
+    useEffect(() => { apiRef.current = api; });
+    useEffect(() => { showAlertRef.current = showAlert; });
+
+    const handlerRef = useRef<WebSocketHandler | null>(null);
+    const unsubscribeProviderRef = useRef<(() => void) | null>(null);
+    const [lastMessage, setLastMessage] = useState<WebSocketNotification | null>(null);
+    const [status, setStatus] = useState<WebSocketStatus>("idle");
+
+    const pendingRef = useRef(new Map<(m: WebSocketNotification) => void, (() => void) | null>());
+
+    useEffect(() => {
+        let cancelled = false;
+        const pending = pendingRef.current;
+
+        getWebsocketsConfig(apiRef.current)
+            .then((config) => {
+                if (cancelled) return;
+
+                setStatus("connecting");
+                const handler = new WebSocketHandler({
+                    ...config,
+                    onStatusChange: (s) => setStatus(s),
+                });
+                handlerRef.current = handler;
+
+                unsubscribeProviderRef.current = handler.listen((message) => setLastMessage(message));
+
+                for (const [fn, unsub] of pending.entries()) {
+                    if (!unsub) {
+                        const realUnsub = handler.listen(fn);
+                        pending.set(fn, realUnsub);
+                    }
+                }
+            })
+            .catch((error) => {
+                if (cancelled) return;
+                console.error("Failed to initialize WebSocket connection:", error);
+                setStatus("error");
+                showAlertRef.current({ message: "Real-time notifications are unavailable. Please refresh the page.", severity: "error" });
+            });
+
+        return () => {
+            cancelled = true;
+            unsubscribeProviderRef.current?.();
+            unsubscribeProviderRef.current = null;
+            handlerRef.current?.close();
+            handlerRef.current = null;
+            pending.clear();
+        };
+    }, []); // mount-only — Socket.IO handles reconnection; no re-init needed when api changes
+
+    const subscribe = useCallback((fn: (m: WebSocketNotification) => void) => {
+        if (handlerRef.current) {
+            return handlerRef.current.listen(fn);
+        }
+
+        pendingRef.current.set(fn, null);
+
+        return () => {
+            const maybeUnsub = pendingRef.current.get(fn);
+            if (maybeUnsub) maybeUnsub();
+            pendingRef.current.delete(fn);
+        };
+    }, []);
+
+    const value: WebSocketContextType = useMemo(
+        () => ({ subscribe, lastMessage, status }),
+        [subscribe, lastMessage, status]
+    );
+
+    return <WebSocketContext.Provider value={value}>{children}</WebSocketContext.Provider>;
+};

package/src/contexts/webSocketContext/types.ts

@@ -0,0 +1,50 @@
+import type { ReactNode } from "react";
+
+export type WebsocketsConfig = {
+    appConnectionURL: string;
+    appChannelID: string;
+    everyskUID: string;
+};
+
+export type WebSocketStatus = "idle" | "connecting" | "connected" | "error";
+
+export type AppNotificationPayload = {
+    [key: string]: unknown;
+};
+
+/**
+ * WebSocketNotification
+ *
+ * Base type for all Socket.IO notifications.
+ * `event_type` discriminates between notification kinds (e.g. "USER_APP_NOTIFICATION",
+ * "WORKFLOW_EXECUTION_COMPLETED"). Other fields vary per event_type.
+ */
+export type WebSocketNotification = {
+    event_type: string;
+    [key: string]: unknown;
+};
+
+/**
+ * AppNotification
+ *
+ * Narrowed type for event_type === "USER_APP_NOTIFICATION".
+ * Has a nested `payload` with app-level metadata.
+ */
+export type AppNotification = WebSocketNotification & {
+    event_type: "USER_APP_NOTIFICATION";
+    user_app_id: string;
+    payload: AppNotificationPayload;
+};
+
+export type WebSocketContextType = {
+    subscribe: (listener: (msg: WebSocketNotification) => void) => () => void;
+    lastMessage: WebSocketNotification | null;
+    status: WebSocketStatus;
+};
+
+export type WebSocketProviderProps = {
+    // Optional, so this provider satisfies `ProviderComponent` and can be handed to
+    // `EveryskApp`'s `providers` array. A provider that only renders `{children}` behaves
+    // correctly when there are none.
+    children?: ReactNode;
+};

package/src/datastore/index.ts

@@ -0,0 +1,14 @@
+// The datastore entity slice: API calls, entity hooks and types.
+//
+// Re-exported from the package root rather than its own subpath: nothing here carries an
+// optional peer, so there is nothing for a subpath to isolate.
+//
+// `export *` rather than a hand-written list: a slice is exactly "everything these modules
+// expose", and an enumerated list silently drops an export when the slice grows.
+
+export * from "@/api/datastore";
+export * from "@/types/datastore";
+export * from "@/hooks/datastore/useDatastoreMutations";
+export * from "@/hooks/datastore/useFetchDatastore";
+export * from "@/hooks/datastore/useFetchDatastores";
+export * from "@/lib/datastoreTable";

package/src/file/index.ts

@@ -0,0 +1,13 @@
+// The file entity slice: API calls, entity hooks and types.
+//
+// Re-exported from the package root rather than its own subpath: nothing here carries an
+// optional peer, so there is nothing for a subpath to isolate.
+//
+// `export *` rather than a hand-written list: a slice is exactly "everything these modules
+// expose", and an enumerated list silently drops an export when the slice grows.
+
+export * from "@/api/file";
+export * from "@/types/file";
+export * from "@/hooks/file/useFetchFile";
+export * from "@/hooks/file/useFetchFiles";
+export * from "@/hooks/file/useFileMutations";

package/src/hooks/datastore/useDatastoreMutations.ts

@@ -0,0 +1,221 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+import { useAxios } from "./../useAxios";
+import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import type { Datastore } from "@/types/datastore";
+import { deleteDatastore, createDatastore, updateDatastore } from "@/api/datastore";
+
+type CreateDatastoreProps = {
+    data: Partial<Datastore>;
+};
+
+type UpdateDatastoreProps = {
+    id: string;
+    data: Partial<Datastore>;
+};
+
+type DeleteDatastoreProps = {
+    id: string;
+    workspace: string;
+};
+
+type UseDatastoreMutationsProps = {
+    queryKey?: unknown[];
+};
+
+const getErrorMessage = (err: unknown, fallback: string) =>
+    err instanceof Error && err.message ? err.message : fallback;
+
+/**
+ * useDatastoreMutations
+ *
+ * Mutation hook built on TanStack Query to perform Datastore write operations:
+ * - create a datastore (POST)
+ * - update a datastore (PUT)
+ * - delete a datastore (DELETE)
+ *
+ * It also:
+ * - optionally invalidates a target query cache key after successful mutations
+ * - displays success/error alerts via `useAppAlert`
+ *
+ * Important notes:
+ * - This hook is intended for side-effect operations only. Reading/retrieving data should be done via `useQuery` or `useFetchDatastore`.
+ * - Cache invalidation is controlled by `queryKey`. If `queryKey` is not provided, the hook will still run
+ *   mutations and show alerts, but it will NOT invalidate any cached queries.
+ * - `remove` requires a `workspace` parameter because the underlying API helper `deleteDatastore(api, id, workspace)`
+ *   expects it as a query param.
+ *
+ * Parameters (UseDatastoreMutationsProps):
+ * @param {unknown[]} [queryKey]
+ *  Query key to invalidate after successful mutations. Use the same `queryKey` you pass to the relevant `useQuery`
+ *  (e.g., datastore list/detail) so UI data is refreshed automatically after a write.
+ *
+ *  Tip:
+ *  - If you're using `useFetchDatastore`, you can pass its returned `queryKey` directly:
+ *    `const fetch = useFetchDatastore(...);`
+ *    `useDatastoreMutations({ queryKey: fetch.queryKey });`
+ *
+ * Mutations:
+ * - `create`:
+ *   - mutationFn: `createDatastore(api, data)`
+ *   - variables: `{ data: Partial<Datastore> }`
+ *   - success message: "Datastore created successfully."
+ *   - error message: "Unable to create the datastore. Please try again." (fallback)
+ *
+ * - `update`:
+ *   - mutationFn: `updateDatastore(api, id, data)`
+ *   - variables: `{ id: string; data: Partial<Datastore> }`
+ *   - success message: "Datastore updated successfully."
+ *   - error message: "Unable to update the datastore. Please try again." (fallback)
+ *
+ * - `remove`:
+ *   - mutationFn: `deleteDatastore(api, id, workspace)`
+ *   - variables: `{ id: string; workspace: string }`
+ *   - success message: "Datastore deleted successfully."
+ *   - error message: "Unable to delete the datastore. Please try again." (fallback)
+ *
+ * Return value:
+ * @returns {object}
+ *  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>
+ *
+ * Each mutation includes standard TanStack Query helpers:
+ * - `mutate(variables, options?)`
+ * - `mutateAsync(variables, options?)`
+ * - `isPending`, `isSuccess`, `isError`, `error`, `data`, etc.
+ *
+ * Examples:
+ *
+ * 1) Invalidate a datastore list query after mutations:
+ * ```ts
+ * const { create, update, remove } = useDatastoreMutations({ queryKey: ["datastore"] });
+ *
+ * // Create
+ * create.mutate({
+ *   data: {
+ *     name: "My datastore",
+ *     workspace: "ws-1",
+ *     data: [["id", "name"], ["ABEOX135", "Jorge"]],
+ *   }
+ * });
+ *
+ * // Update
+ * update.mutate({
+ *   id: "ds-123",
+ *   data: {
+ *     name: "Renamed datastore",
+ *     data: [["id", "name"], ["ABEOX135", "Jorge"]],
+ *   }
+ * });
+ *
+ * // Delete
+ * remove.mutate({
+ *   id: "ds-123",
+ *   workspace: "ws-1"
+ * });
+ * ```
+ *
+ * 2) Using async/await with `mutateAsync`:
+ * ```ts
+ * const { create } = useDatastoreMutations({ queryKey: ["datastore"] });
+ *
+ * await create.mutateAsync({
+ *   data: {
+ *     name: "My datastore",
+ *     workspace: "ws-1",
+ *     data: [["id", "name"], ["ABEOX135", "Jorge"]],
+ *   }
+ * });
+ * ```
+ *
+ * 3) Without cache invalidation (no queryKey):
+ * ```ts
+ * const { update } = useDatastoreMutations({});
+ *
+ * update.mutate({
+ *   id: "ds-123",
+ *   data: { name: "Renamed datastore" }
+ * });
+ * // Mutation still runs and alerts are shown, but cached queries are not invalidated.
+ * ```
+ *
+ * 4) Using `useFetchDatastore` queryKey for automatic invalidation:
+ * ```ts
+ * const fetch = useFetchDatastore({
+ *   id: null,
+ *   filters: [{ field: "workspace", value: "ws-1" }],
+ * });
+ *
+ * const { create } = useDatastoreMutations({ queryKey: fetch.queryKey });
+ *
+ * await create.mutateAsync({
+ *   data: { name: "My datastore", workspace: "ws-1" }
+ * });
+ * ```
+ */
+
+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 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 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."),
+            });
+        },
+    });
+
+    return { create, update, remove };
+};

package/src/hooks/datastore/useFetchDatastore.ts

@@ -0,0 +1,95 @@
+import { useEffect } from "react";
+
+import { useQuery } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+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>;
+
+const defaultQueryOptions: EntityQueryOptions<DatastoreWithRows> = {
+    refetchOnMount: "always",
+    staleTime: 0,
+    gcTime: 0,
+};
+
+/**
+ * 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).
+ *
+ * @param {string} workspace
+ *   Workspace the datastore belongs to (required by `getDatastore`).
+ *
+ * @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
+ *
+ * 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", ... }]
+ * ```
+ */
+export const useFetchDatastore = ({ id, workspace, queryOptions = defaultQueryOptions }: FetchDatastoreProps) => {
+
+    const { api } = useAxios();
+    const { showAlert } = useAppAlert();
+
+    const queryKey = ["datastore", id, workspace];
+
+    const query = useQuery<DatastoreWithRows>({
+        queryKey,
+        queryFn: async () => {
+            const datastore = await getDatastore(api, id, workspace);
+
+            return {
+                ...datastore,
+                data: tableToObjects(
+                    datastore.id,
+                    datastore.data?.[0] as string[],
+                    datastore.data
+                ),
+            };
+        },
+        ...queryOptions ?? {}
+    });
+
+    useEffect(() => {
+        if (!query.error) return;
+
+        showAlert({
+            severity: "error",
+            message: query.error.message,
+        });
+    }, [query.error, showAlert]);
+
+    return {
+        ...query,
+        queryKey,
+    };
+};

package/src/hooks/datastore/useFetchDatastores.ts

@@ -0,0 +1,162 @@
+//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 { 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[];
+};
+
+export type FetchInfiniteDatastoreProps = FetchEntitiesParams<DatastoreWithRows[], InfiniteOptions<DatastoreWithRows[]>> & {
+    pageSize?: number;
+};
+
+const defaultQueryOptions: InfiniteOptions<DatastoreWithRows[]> = {
+    refetchOnMount: "always",
+    staleTime: 0,
+    gcTime: 0,
+};
+
+/**
+ * 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`).
+ *
+ * Parameters (FetchInfiniteDatastoreProps):
+ * @param {FilterClause[]} [filters=[]]
+ *   Filters applied to every page request. Must include a `workspace` filter.
+ *
+ * @param {string[]} [order=[]]
+ *   Sorting applied to every page request.
+ *
+ * @param {string} [projection=""]
+ *   Single field to project: `"field"` returns only that field (others come back null),
+ *   `"-field"` returns every field except that one. One field only — lists 500. Omitted when empty.
+ *
+ * @param {number} [pageSize=10]
+ *   Number of 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
+ *
+ * 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 ?? [];
+ *
+ * // Load next page when grid is near end
+ * <AgGridReact onBodyScroll={() => events.handleFetchIfGridEmptyOrNearEnd(gridApi)} />
+ * ```
+ */
+export function useFetchDatastores({ filters = [], order = [], projection = "", pageSize = 10, queryOptions }: FetchInfiniteDatastoreProps) {
+    const { api } = useAxios();
+
+    //const fetchingGuardRef = useRef(false);
+    const queryKey = buildQueryKey(["datastores"], filters);
+
+    const mergedQueryOptions = useMemo<InfiniteOptions<DatastoreWithRows[]>>(() => ({
+        ...defaultQueryOptions,
+        ...(queryOptions ?? {}),
+    }), [queryOptions]);
+
+    const query = useInfiniteQuery<DatastoreQueryPage, Error, DatastoreWithRows[], QueryKey, PageToken>({
+        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
+                ),
+            }));
+
+            return {
+                next_page_token: response.next_page_token,
+                datastores: nested,
+            };
+        },
+
+        select: (data) => data.pages.flatMap((p) => p.datastores),
+
+        ...mergedQueryOptions,
+    });
+
+    /*
+    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 },
+    };
+}