@promoboxx/use-filter 1.11.1 → 2.0.0

package/src/useFilter.ts

@@ -0,0 +1,524 @@
+import { useEffect, useRef, useCallback, useState } from 'react'
+
+import buildDefaultFilterInfo from './lib/buildDefaultFilterInfo'
+import getOffsetFromPage from './lib/getOffsetFromPage'
+import getPageFromOffset from './lib/getPageFromOffset'
+import shallowEqual from './lib/shallowEqual'
+import { getFilterStore } from './store'
+import type { FilterStore } from './store'
+
+type MaybePromise<T> = T | Promise<T>
+
+interface UseFilterOptions<TFilter extends Record<string, unknown>, TResult> {
+  /**
+   * Default values for your filter. When calling `.reset` your filter will be
+   * set to this.
+   * Changing these values does not cause a call to happen.
+   */
+  defaultFilterInfo?: Partial<FilterInfo<TFilter>>
+  /**
+   * Enable this if you are not using the data caching of this hook.
+   */
+  shouldForceRunOnMount?: boolean
+  /**
+   * Called whenever the filter changes.
+   */
+  onChange: (
+    filterInfo: FilterInfo<TFilter>,
+    reason: UseFilterUpdateReason,
+  ) => MaybePromise<UseFilterOnChangeResult<TFilter, TResult>>
+  /**
+   * In case you want to change the default debounce duration.
+   */
+  debounceDuration?: number
+  onBeforeSaveFilter?: (filterInfo: FilterInfo<TFilter>) => FilterInfo<TFilter>
+
+  store?: FilterStore
+}
+
+export interface FilterApi<TFilter extends Record<string, unknown>, TResult> {
+  /**
+   * Whether the system is debouncing or waiting for your `onChange` to finish.
+   */
+  isLoading: boolean
+  /**
+   * Any cached data for this filter.
+   */
+  data: TResult | null | undefined
+  /**
+   * Access to the filter and its metadata.
+   */
+  filterInfo: FilterInfo<TFilter>
+
+  /**
+   * Whether the filter existed in the system when the component mounted.
+   * @deprecated
+   */
+  doesFilterExist: boolean
+  /**
+   * Why the last update happened.
+   */
+  updateReason: UseFilterUpdateReason
+
+  /**
+   * Update one or more values in your filter.
+   */
+  updateFilter: (
+    filter: Partial<TFilter>,
+    shouldRunImmediately?: boolean,
+  ) => void
+
+  /**
+   * Resets the filter back to `defaultFilterInfo`.
+   */
+  resetFilter: (shouldRunImmediately?: boolean) => void
+
+  /**
+   * Changes the offset. Will update `page`.
+   */
+  setOffset: (offset: number | string, shouldRunImmediately?: boolean) => void
+
+  /**
+   * Changes the page. Will update `offset`.
+   */
+  setPage: (page: number | string, shouldRunImmediately?: boolean) => void
+
+  /**
+   * Changes the page size.
+   */
+  setPageSize: (
+    pageSize: number | string,
+    shouldRunImmediately?: boolean,
+  ) => void
+
+  /**
+   * Change the sort method.
+   */
+  setSort: (sort: string | undefined, shouldRunImmediately?: boolean) => void
+
+  /**
+   * Changes the cursor.
+   */
+  setCursor: (
+    cursor: string | null | undefined,
+    shouldRunImmediately?: boolean,
+  ) => void
+
+  /**
+   * Forces a refresh of the filter.
+   */
+  forceRefresh: (shouldRunImmediately?: boolean) => void
+}
+
+export type UseFilterUpdateReason = 'initial' | 'filter' | 'pagination'
+
+function useFilter<TFilter extends Record<string, unknown>, TResult>(
+  namespace: string,
+  options: UseFilterOptions<TFilter, TResult>,
+) {
+  // Having these types of refs helps get around rules of hooks, and they need
+  // to be updated each render.
+  const ctxRefValue = {
+    namespace,
+    onChange: options.onChange,
+    debounceDuration: options.debounceDuration,
+    defaultFilterInfo: options.defaultFilterInfo,
+    onBeforeSaveFilter: options.onBeforeSaveFilter,
+    store: options.store,
+  }
+  const ctxRef = useRef(ctxRefValue)
+  useEffect(() => {
+    ctxRef.current = ctxRefValue
+  })
+
+  const [filterInfo, setFilterInfoState] = useState(() => {
+    const fromStore = getFilterStore(ctxRef.current.store).getFilter<TFilter>(
+      namespace,
+    )
+
+    // If the filter is already in the store, we have to make sure it ...
+    // - has both the filter and filterInfo
+    // - has all the fields the user passed to the hook
+    if (fromStore) {
+      const filterInfo = buildDefaultFilterInfo({
+        ...fromStore,
+        shouldRunImmediately: true,
+        filter: {
+          ...options.defaultFilterInfo?.filter,
+          ...fromStore.filter,
+        },
+      })
+
+      return filterInfo
+    }
+  })
+  const [data, setData] = useState(() =>
+    getFilterStore(ctxRef.current.store).getData<TResult>(namespace),
+  )
+
+  const [isLoading, setIsLoading] = useState(!filterInfo)
+  const doesFilterExist = useRef(!!filterInfo)
+  const lastRefreshAtRef = useRef(
+    // if shouldForceRunOnMount is set, always use -1
+    // otherwise, try grabbing lastRefreshAt
+    // then, just use -1 cause there's no other option
+    options.shouldForceRunOnMount
+      ? -1
+      : filterInfo
+        ? filterInfo.lastRefreshAt
+        : -1,
+  )
+
+  const updateReasonRef = useRef<UseFilterUpdateReason>('initial')
+
+  // Call onChange when data changes.
+  useEffect(() => {
+    setIsLoading(true)
+
+    // If there is no existing filter info, set it to the defaults and return.
+    // This same effect will trigger next go.
+    if (!filterInfo) {
+      setFilterInfoState({
+        ...buildDefaultFilterInfo(ctxRef.current.defaultFilterInfo),
+        shouldRunImmediately: true,
+      })
+      return
+    }
+
+    // If the lastRefreshAt hasn't changed, don't make a request.
+    if (lastRefreshAtRef.current === filterInfo.lastRefreshAt) {
+      setIsLoading(false)
+      return
+    }
+
+    const makeRequest = () => {
+      lastRefreshAtRef.current = filterInfo.lastRefreshAt
+      const response = ctxRef.current.onChange(
+        filterInfo,
+        updateReasonRef.current,
+      )
+      getFilterStore(ctxRef.current.store).saveFilter(
+        namespace,
+        ctxRef.current.onBeforeSaveFilter
+          ? ctxRef.current.onBeforeSaveFilter(filterInfo)
+          : filterInfo,
+      )
+
+      if (!response) {
+        setIsLoading(false)
+        return
+      }
+
+      function handleResponse(
+        response?: UseFilterOnChangeResult<TFilter, TResult>,
+      ) {
+        if (!response) {
+          return
+        }
+
+        if (response.filterInfo) {
+          setFilterInfoState((previous) => {
+            // Even though we've already checked for response.filterInfo, since
+            // we're in a callback TypeScript still considers accessing it
+            // unsafe, so do another check.
+            invariant(!!response.filterInfo, '')
+
+            invariant(
+              previous != null,
+              'handleResponse called without filterInfo',
+            )
+
+            const extra: Partial<FilterInfo<TFilter>> = {}
+            const {
+              page,
+              offset,
+              totalResults,
+              pageSize,
+              nextCursor,
+              ...filterInfoFromResponse
+            } = response.filterInfo
+
+            const pageSizeNumber = Number(pageSize || previous.pageSize)
+
+            if (page != null && offset == null) {
+              extra.offset = getOffsetFromPage(page, pageSizeNumber)
+              extra.page = page
+              // If there's an offset but no page, set the page.
+            } else if (page == null && offset != null) {
+              const offsetNumber = Number(offset)
+              extra.offset = offsetNumber
+              extra.page = getPageFromOffset(offsetNumber, pageSizeNumber)
+            }
+
+            // `null` / `undefined` are valid here, it means there is zero
+            // results, so we can't just check if it's truthy, we need to check
+            // for presence.
+            if ('totalResults' in response.filterInfo) {
+              extra.totalResults = Number(totalResults || 0)
+              extra.totalPages = Math.ceil(extra.totalResults / pageSizeNumber)
+            }
+
+            // `null` / `undefined` are valid here, it means there is no next
+            // cursor, so we can't just check if it's truthy, we need to check
+            // for presence.
+            if ('nextCursor' in response.filterInfo) {
+              extra.nextCursor = nextCursor
+            }
+
+            return {
+              ...previous,
+              ...filterInfoFromResponse,
+              ...extra,
+            }
+          })
+        }
+
+        if (response.data) {
+          setData(response.data)
+          getFilterStore(ctxRef.current.store).saveData(
+            namespace,
+            response.data,
+          )
+        }
+      }
+
+      if (isPromise(response)) {
+        response.then(handleResponse).finally(() => setIsLoading(false))
+      } else {
+        handleResponse(response)
+        setIsLoading(false)
+      }
+    }
+
+    let timeout: ReturnType<typeof setTimeout> | undefined = undefined
+
+    if (filterInfo.shouldRunImmediately) {
+      makeRequest()
+    } else {
+      timeout = setTimeout(
+        makeRequest,
+        ctxRef.current.debounceDuration != null
+          ? ctxRef.current.debounceDuration
+          : 500,
+      )
+    }
+
+    return () => {
+      if (timeout) {
+        clearTimeout(timeout)
+      }
+    }
+  }, [filterInfo, namespace])
+
+  const api: FilterApi<TFilter, TResult> = {
+    isLoading,
+    data,
+    doesFilterExist: doesFilterExist.current,
+    filterInfo: filterInfo || buildDefaultFilterInfo(options.defaultFilterInfo),
+    updateReason: updateReasonRef.current,
+
+    updateFilter: useCallback(
+      (filter: Partial<TFilter>, shouldRunImmediately: boolean = false) => {
+        updateReasonRef.current = 'filter'
+
+        setFilterInfoState((previous) => {
+          invariant(previous != null, 'updateFilter called without filterInfo')
+
+          const nextFilter = {
+            ...previous.filter,
+            ...filter,
+          }
+
+          if (shallowEqual(previous.filter, nextFilter)) {
+            return previous
+          }
+
+          return {
+            ...previous,
+            offset: 0,
+            page: 1,
+            totalResults: 1,
+            totalPages: 1,
+            filter: nextFilter,
+            lastRefreshAt: new Date().getTime(),
+            cursor: undefined,
+            nextCursor: undefined,
+            shouldRunImmediately,
+          }
+        })
+      },
+      [],
+    ),
+
+    resetFilter: useCallback((shouldRunImmediately: boolean = false) => {
+      updateReasonRef.current = 'filter'
+
+      setFilterInfoState({
+        ...buildDefaultFilterInfo(ctxRef.current.defaultFilterInfo),
+        lastRefreshAt: new Date().getTime(),
+        shouldRunImmediately,
+      })
+    }, []),
+
+    setOffset: useCallback(
+      (offset: number | string, shouldRunImmediately: boolean = false) => {
+        updateReasonRef.current = 'pagination'
+
+        setFilterInfoState((previous) => {
+          invariant(previous != null, 'setOffset called without filterInfo')
+
+          const offsetNumber = Number(offset)
+
+          return {
+            ...previous,
+            offset: offsetNumber,
+            page: getPageFromOffset(offsetNumber, previous.pageSize),
+            lastRefreshAt: new Date().getTime(),
+            shouldRunImmediately,
+          }
+        })
+      },
+      [],
+    ),
+
+    setPage: useCallback(
+      (page: number | string, shouldRunImmediately: boolean = false) => {
+        updateReasonRef.current = 'pagination'
+
+        setFilterInfoState((previous) => {
+          invariant(previous != null, 'setPage called without filterInfo')
+
+          const pageNumber = Number(page)
+
+          return {
+            ...previous,
+            offset: getOffsetFromPage(pageNumber, previous.pageSize),
+            page: pageNumber,
+            lastRefreshAt: new Date().getTime(),
+            shouldRunImmediately,
+          }
+        })
+      },
+      [],
+    ),
+
+    setPageSize: useCallback(
+      (pageSize: number | string, shouldRunImmediately: boolean = false) => {
+        updateReasonRef.current = 'pagination'
+
+        setFilterInfoState((previous) => {
+          invariant(previous != null, 'setPageSize called without filterInfo')
+
+          const pageSizeNumber = Number(pageSize)
+          const page = getPageFromOffset(previous.offset, pageSizeNumber)
+          const offset = getOffsetFromPage(page, pageSizeNumber)
+
+          return {
+            ...previous,
+            pageSize: pageSizeNumber,
+            offset,
+            page,
+            lastRefreshAt: new Date().getTime(),
+            shouldRunImmediately,
+          }
+        })
+      },
+      [],
+    ),
+
+    setSort: useCallback(
+      (sort: string | undefined, shouldRunImmediately: boolean = false) => {
+        updateReasonRef.current = 'filter'
+
+        setFilterInfoState((previous) => {
+          invariant(previous != null, 'setSort called without filterInfo')
+
+          return {
+            ...previous,
+            sort,
+            lastRefreshAt: new Date().getTime(),
+            shouldRunImmediately,
+          }
+        })
+      },
+      [],
+    ),
+
+    setCursor: useCallback(
+      (
+        cursor: string | null | undefined,
+        shouldRunImmediately: boolean = false,
+      ) => {
+        setFilterInfoState((previous) => {
+          updateReasonRef.current = 'pagination'
+
+          invariant(previous != null, 'setCursor called without filterInfo')
+
+          return {
+            ...previous,
+            cursor,
+            lastRefreshAt: new Date().getTime(),
+            shouldRunImmediately,
+          }
+        })
+      },
+      [],
+    ),
+
+    forceRefresh: useCallback((shouldRunImmediately: boolean = false) => {
+      updateReasonRef.current = 'filter'
+
+      setFilterInfoState((previous) => {
+        invariant(previous != null, 'forceRefresh called without filterInfo')
+
+        return {
+          ...previous,
+          lastRefreshAt: new Date().getTime(),
+          shouldRunImmediately,
+        }
+      })
+    }, []),
+  }
+
+  return api
+}
+
+export default useFilter
+
+export interface FilterInfo<TFilter extends Record<string, unknown>> {
+  filter: TFilter
+  offset: number
+  page: number
+  sort?: string
+  pageSize: number
+  lastRefreshAt: number
+  totalResults: number
+  totalPages: number
+  shouldRunImmediately: boolean
+  cursor?: string | null
+  nextCursor?: string | null
+}
+
+type UseFilterOnChangeResult<
+  TFilter extends Record<string, unknown>,
+  TResult,
+> = void | {
+  filterInfo?: Partial<
+    Omit<FilterInfo<TFilter>, 'totalResults' | 'offset' | 'pageSize'> & {
+      totalResults: string | number
+      offset: string | number
+      pageSize: string | number
+    }
+  >
+  data?: TResult
+}
+
+function invariant(input: boolean, message: string): asserts input {
+  if (!input) {
+    throw new Error(`Invariant error: ${message}`)
+  }
+}
+
+function isPromise(t?: any): t is Promise<any> {
+  return !!t?.then
+}