Filters and Sort

Imports

import {
  FiltersAndSortService,
  createFiltersAndSortService,
  SORT_DIRECTIONS,
} from '@codella-software/utils'
import { useFiltersAndSort, useFilters } from '@codella-software/react'

Core service

type UserFilters = {
  role: string
  search: string
}

const service = new FiltersAndSortService<UserFilters>({
  storageKey: 'users',
  defaultFilters: { role: '', search: '' },
  // optional: stored as "MYAPP-users" in localStorage
  storageKeyPrefix: 'MYAPP',
})

service.setFilters({ role: 'admin' })
service.setSort('name')
service.setPagination(0, 25)
service.setQuery('anna')

Public methods:

• getStorageKey()
• getFullStorageKey()
• getState()
• getStateSubject()
• getDebouncedState(ms?)
• getCurrentState()
• getDefaultState()
• setFilters(filters): merges into the current filters
• setAllFilters(filters): replaces all filters
• removeFilter(filterName)
• clearFilters()
• clearStorage()
• setSort(fieldName)
• setPagination(page, limit?)
• setQuery(query)
• reset()
• getActions()
• destroy()

setSort(fieldName) toggles the same field through asc -> desc -> undefined. setFilters, setAllFilters and setQuery reset to the first page.

Persistence is on by default (persistToStorage: true, debounced by storageDebounceMs, 300 ms). Pass a storageAdapter to persist somewhere other than localStorage. If a write fails (quota exceeded, for example), the service logs a warning and keeps working in memory.

State shape

type FilterAndSortState<T> = {
  filters: T
  sort?: {
    fieldName: string
    direction: 'asc' | 'desc'
  }
  pagination: {
    page: number
    limit: number
  }
  query: string
}

page is zero-based in the current implementation.

React hook

const filters = useFiltersAndSort<UserFilters>({
  config: {
    storageKey: 'users',
    defaultFilters: { role: '', search: '' },
  },
})

filters.setFilter('role', 'admin')
filters.setSort('name')
filters.setPageSize(50)

useFiltersAndSort() returns:

• filters
• sortBy
• sortDirection
• page
• pageSize
• query
• state
• setFilter
• setFilters
• clearFilter
• clearAllFilters
• hasFilter
• hasAnyFilters
• activeFilterCount
• setSort
• toggleSort
• clearSort
• isSortedBy
• setPage
• setPageSize
• setPagination
• nextPage
• prevPage
• firstPage
• isFirstPage
• offset
• setQuery
• clearQuery
• reset
• clearStorageAndReset
• storageKey
• getService

Shortcut:

const filters = useFilters<UserFilters>('users', {
  defaultFilters: { role: '', search: '' },
})