Skip to content

LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows

7.5 KB
Raw Blame
import { useCallback, useRef, useState } from "react";

/**
 * Build the query params for a paginated list request, omitting empty
 * search/sort so non-paginated callers stay unaffected. Callers add any
 * resource-specific params (e.g. `adapter_type`) to the returned object.
 *
 * @param {Object} args
 * @param {number} args.page - Requested page.
 * @param {number} args.pageSize - Requested page size.
 * @param {string} [args.search] - Search term.
 * @param {string} [args.sortBy] - Sort column key.
 * @param {string} [args.order] - Sort direction.
 * @return {Object} Query params.
 */
function buildPagedParams({ page, pageSize, search, sortBy, order }) {
  const params = { page, page_size: pageSize };
  if (search) {
    params.search = search;
  }
  if (sortBy) {
    // DRF OrderingFilter: `?ordering=field`, a leading `-` sorts descending.
    params.ordering = (order === "desc" ? "-" : "") + sortBy;
  }
  return params;
}

/**
 * Commit a paginated list response, shared by every resource list page.
 *
 * Unwraps the opt-in envelope (`{results, count}` or a bare array), drops stale
 * responses that a newer request already superseded, and steps back a page when
 * a delete empties the last one — returning that refetch promise so the caller's
 * `finally` waits for replacement data instead of clearing loading early.
 *
 * @param {Object} args
 * @param {*} args.data - `res.data`: envelope or bare array.
 * @param {number} args.page - Requested page.
 * @param {number} args.pageSize - Requested page size.
 * @param {number} args.seq - This request's sequence token.
 * @param {{current: number}} args.latestSeqRef - Ref holding the newest token.
 * @param {Function} args.setList - List state setter.
 * @param {Function} args.setPagination - Pagination state setter.
 * @param {Function} args.refetchPrevPage - Refetches `page - 1`; its promise is
 *   returned so the caller's `finally` waits for it.
 * @return {Promise|undefined}
 */
function applyPagedResponse({
  data,
  page,
  pageSize,
  seq,
  latestSeqRef,
  setList,
  setPagination,
  refetchPrevPage,
}) {
  // A newer request already fired — ignore this superseded response.
  if (seq !== latestSeqRef.current) {
    return undefined;
  }
  // A 204 body or an unexpected object must not reach antd Table as dataSource.
  const raw = data?.results ?? data;
  const results = Array.isArray(raw) ? raw : [];
  const total = data?.count ?? results.length;
  // Deleting the last row on a page leaves it empty; step back a page.
  if (results.length === 0 && page > 1 && total > 0) {
    return refetchPrevPage();
  }
  setList(results);
  setPagination((prev) => ({ ...prev, current: page, pageSize, total }));
  return undefined;
}

/**
 * Shared hook for paginated list state and handlers.
 *
 * Owns `fetchRef` — the page assigns its fetch fn to `fetchRef.current`, and the
 * hook's handlers (search/sort/paginate) plus `handleListRefresh` invoke the
 * latest one, so pages don't re-derive that wiring. `handleListRefresh` refetches
 * the current page preserving active search/sort — pass it to mutation callbacks.
 *
 * @param {Object} [options]
 * @param {number} [options.defaultPageSize=10]
 * @param {string} [options.defaultSortBy=""] - initial sort column key
 * @param {string} [options.defaultOrder="asc"] - initial sort direction
 * @return {Object} Pagination/sort state, `fetchRef`, and handlers.
 */
function usePaginatedList({
  defaultPageSize = 10,
  defaultSortBy = "",
  defaultOrder = "asc",
} = {}) {
  const [pagination, setPagination] = useState({
    current: 1,
    pageSize: defaultPageSize,
    total: 0,
  });
  const [searchTerm, setSearchTerm] = useState("");
  const [sort, setSort] = useState({
    sortBy: defaultSortBy,
    order: defaultOrder,
  });
  // The default sort still drives the server; this only gates the header's
  // "active" styling so the default column isn't highlighted until the user
  // explicitly picks a sort.
  const [userSorted, setUserSorted] = useState(false);

  // Page assigns its fetch fn here; handlers call the latest one via the ref.
  const fetchRef = useRef(null);

  // page/pageSize mirror the applied view; search/sort are last-REQUESTED
  // (handlers commit before firing). syncRequested snapshots this for refresh.
  const appliedRef = useRef(null);
  appliedRef.current = {
    page: pagination.current,
    pageSize: pagination.pageSize,
    search: searchTerm,
    sortBy: sort.sortBy,
    order: sort.order,
  };

  // Params of the last request, recorded at fetch time (state lags applies).
  // handleListRefresh replays these so a refresh targets the asked-for view.
  const requestedRef = useRef({
    page: 1,
    pageSize: defaultPageSize,
    search: "",
    sortBy: defaultSortBy,
    order: defaultOrder,
  });

  // Single fetch entry: records the requested view before firing so every path
  // (navigation, stepback, reset) keeps requestedRef in sync. Returns the fetch
  // promise so a stepback propagates up through applyPagedResponse.
  const requestList = (page, pageSize, search, sortBy, order) => {
    requestedRef.current = { page, pageSize, search, sortBy, order };
    return fetchRef.current?.(page, pageSize, search, sortBy, order);
  };

  const handlePaginationChange = (page, pageSize) => {
    const newPage = pageSize === pagination.pageSize ? page : 1;
    requestList(newPage, pageSize, searchTerm, sort.sortBy, sort.order);
  };

  const handleSearch = (searchText) => {
    const term = searchText?.trim() || "";
    setSearchTerm(term);
    requestList(1, pagination.pageSize, term, sort.sortBy, sort.order);
  };

  // Table header sort click: reset to page 1 (the page a row sits on changes)
  // and refetch with the new ordering.
  const handleSortChange = (sortBy, order) => {
    // "Clear Sort" (empty sortBy) restores the default view, not an empty
    // ordering: the viewset always applies one, so header and rows stay in sync.
    const nextSort = sortBy
      ? { sortBy, order: order || "asc" }
      : { sortBy: defaultSortBy, order: defaultOrder };
    setSort(nextSort);
    setUserSorted(Boolean(sortBy));
    requestList(
      1,
      pagination.pageSize,
      searchTerm,
      nextSort.sortBy,
      nextSort.order,
    );
  };

  // Reset to a fresh default view (state + requestedRef) and fetch — used when
  // a persistent instance changes what it lists (e.g. ToolSettings adapter type)
  // so search box, sort header, and requestedRef all start clean.
  const resetList = () => {
    setSearchTerm("");
    setSort({ sortBy: defaultSortBy, order: defaultOrder });
    setUserSorted(false);
    requestList(1, defaultPageSize, "", defaultSortBy, defaultOrder);
  };

  // Realign requestedRef with the displayed view — call from a page's catch when
  // its newest request failed (setList was skipped, so the screen still shows the
  // previous view). Stops the next handleListRefresh from replaying the failed
  // target (e.g. jumping to a page whose fetch errored).
  const syncRequested = () => {
    requestedRef.current = { ...appliedRef.current };
  };

  // Stable identity; replays the last requested params.
  const handleListRefresh = useCallback(() => {
    const { page, pageSize, search, sortBy, order } = requestedRef.current;
    fetchRef.current?.(page, pageSize, search, sortBy, order);
  }, []);

  return {
    pagination,
    setPagination,
    searchTerm,
    setSearchTerm,
    sort,
    userSorted,
    fetchRef,
    requestList,
    resetList,
    syncRequested,
    handlePaginationChange,
    handleSearch,
    handleSortChange,
    handleListRefresh,
  };
}

export { applyPagedResponse, buildPagedParams, usePaginatedList };