Library Utilities

The lib/ directory contains utility functions, constants, and helper functions used throughout the data table components.

Constants

Centralized constants for join operators, filter operators, filter variants, and UI configuration.

Source Code ↗

JOIN_OPERATORS

Join operators for combining multiple filters.

Constant	Value	Description
AND	"and"	Logical AND (all filters must match)
OR	"or"	Logical OR (any filter can match)
MIXED	"mixed"	Mixed logic (combination of AND/OR)

FILTER_OPERATORS

Filter operator constants defining the comparison logic. Naming follows SQL/PostgREST standards.

Constant	Value	Description
ILIKE	"ilike"	SQL ILIKE (Case-insensitive search)
NOT_ILIKE	"not.ilike"	SQL NOT ILIKE
EQ	"eq"	SQL EQUAL (=)
NEQ	"neq"	SQL NOT EQUAL (!=)
IN	"in"	SQL IN (one of)
NOT_IN	"not.in"	SQL NOT IN (none of)
EMPTY	"empty"	Value is null or empty string
NOT_EMPTY	"not.empty"	Value is not null and not empty string
LT	"lt"	SQL LESS THAN (<)
LTE	"lte"	SQL LESS THAN OR EQUAL (<=)
GT	"gt"	SQL GREATER THAN (>)
GTE	"gte"	SQL GREATER THAN OR EQUAL (>=)
BETWEEN	"between"	SQL BETWEEN (range)
RELATIVE	"relative"	Relative date calculation (e.g., “today”)

FILTER_VARIANTS

Filter variant constants defining the UI control type.

Constant	Value	Description
TEXT	"text"	Standard text input
NUMBER	"number"	Numeric input
RANGE	"range"	Two-value range input
DATE	"date"	Single date picker
DATE_RANGE	"date_range"	Date range picker
SELECT	"select"	Single select dropdown
MULTI_SELECT	"multi_select"	Multi-select dropdown
BOOLEAN	"boolean"	Checkbox or toggle

DEFAULT_VALUES

Global default values.

Property	Value	Description
JOIN_OPERATOR	JOIN_OPERATORS.AND	Default join operator
PAGE_SIZE	10	Default page size
PAGE_INDEX	0	Default page index

UI_CONSTANTS

UI-related constraints and settings.

Property	Value	Description
FILTER_ID_MAX_LENGTH	100	Max characters allowed for a filter ID
MAX_FILTER_DISPLAY_HEIGHT	300	Default max height for scrollable filter popovers
DEBOUNCE_DELAY	300	Default debounce delay in milliseconds for search inputs

KEYBOARD_SHORTCUTS

Default keyboard shortcut key mappings.

Property	Value	Description
FILTER_TOGGLE	"f"	Open/Toggle filter menu
FILTER_REMOVE	"f"	Remove active filter (with Shift)
ESCAPE	"escape"	Close active UI elements
ENTER	"enter"	Confirm or submit active action
BACKSPACE	"backspace"	Remove character or navigate back
DELETE	"delete"	Item deletion

Data Table Utilities

Helper functions for filter operations and validation.

Source Code ↗

getFilterOperators

Get available filter operators for a given filter variant.

import { getFilterOperators } from "@/components/niko-table/lib"
import { FILTER_VARIANTS } from "@/components/niko-table/lib"

const textOperators = getFilterOperators(FILTER_VARIANTS.TEXT)
// Returns: [{ label: "Contains", value: "ilike" }, ...]

Parameters

Name	Type	Description
filterVariant	FilterVariant	The filter variant type

Returns

Array of operator objects with label and value properties.

Type: Array<{ label: string; value: FilterOperator }>

getDefaultFilterOperator

Get the default filter operator for a given filter variant.

import { getDefaultFilterOperator } from "@/components/niko-table/lib"
import { FILTER_VARIANTS } from "@/components/niko-table/lib"

const defaultOp = getDefaultFilterOperator(FILTER_VARIANTS.TEXT)
// Returns: "ilike"

Parameters

Name	Type	Description
filterVariant	FilterVariant	The filter variant type

Returns

FilterOperator - The default operator for the variant.

getValidFilters

Filter out invalid filters from an array.

import { getValidFilters } from "@/components/niko-table/lib"

const validFilters = getValidFilters(filters)
// Returns: ExtendedColumnFilter<TData>[] with only valid filters

Parameters

Name	Type	Description
filters	ExtendedColumnFilter<TData>[]	Array of filters to validate

Returns

ExtendedColumnFilter<TData>[] - Array containing only valid filters.

Format Utilities

Formatting functions for dates, labels, and query strings.

Source Code ↗

formatDate

Format a date value into a human-readable string.

import { formatDate } from "@/components/niko-table/lib"

formatDate(new Date())
// Returns: "January 1, 2024"

formatDate(new Date(), { month: "short", day: "numeric" })
// Returns: "Jan 1"

Parameters

Name	Type	Default	Description
date	Date | string | number | undefined	-	Date value to format
opts	Intl.DateTimeFormatOptions	{}	Formatting options

Returns

string - Formatted date string, or empty string if date is invalid.

formatLabel

Format a value into a human-readable label. Capitalizes first letter of each word and replaces hyphens/underscores with spaces.

import { formatLabel } from "@/components/niko-table/lib"

formatLabel("firstName") // "FirstName"
formatLabel("first-name") // "First Name"
formatLabel("first_name") // "First Name"
formatLabel("true") // "Yes"
formatLabel("false") // "No"

Parameters

Name	Type	Description
value	string	Value to format

Returns

string - Formatted label string.

daysAgo

Create a date relative to the current date by subtracting days.

import { daysAgo } from "@/components/niko-table/lib"

daysAgo(7) // 7 days ago
daysAgo(30) // 30 days ago (1 month)
daysAgo(365) // 365 days ago (1 year)

Parameters

Name	Type	Description
days	number	Number of days to subtract

Returns

Date - Date object representing the date N days ago.

formatQueryString

Format URL query parameters into a human-readable query string for display.

import { formatQueryString } from "@/components/niko-table/lib"

const urlParams = { search: "i", globalFilter: { filters: [...], joinOperator: "mixed" } }
const urlKeys = { search: "search", globalFilter: "global" }
formatQueryString(urlParams, urlKeys)
// Returns: "?search=i&global={"filters":[...], "joinOperator":"mixed"}"

Parameters

Name	Type	Description
urlParams	Record<string, unknown>	The parsed URL parameters object
urlKeys	Record<string, string>	Mapping of parameter keys to URL query keys

Returns

string - Formatted query string (e.g., ?search=i&global={"filters":[...]}).

Filter Functions

Custom filter functions for TanStack Table with performance optimizations.

Source Code ↗

The filter functions module provides optimized filter implementations for TanStack Table. It includes:

• Regex caching - Caches compiled regex patterns for 70-90% faster filter execution
• Operator support - Implements all filter operators (ilike, eq, neq, in, between, etc.)
• Performance optimizations - LRU-style cache eviction to prevent memory leaks

Performance Notes

The filter functions use regex caching to improve performance:

• Without caching: 1,000 rows × 10 columns = 10,000 regex creations per search keystroke (~100-500ms)
• With caching: First search creates regex once, subsequent searches reuse cached regex (~5-20ms)

The cache has a maximum size of 100 entries and uses LRU-like eviction to prevent memory leaks.

extendedFilter

Custom filter function for TanStack Table that supports all filter operators (ilike, eq, neq, in, not_in, between, lt, gt, lte, gte, empty, not_empty). Used as the default filterFn for columns with advanced filtering.

import { extendedFilter } from "@/components/niko-table/lib"

const columns = [
  {
    accessorKey: "name",
    filterFn: extendedFilter,
  },
]

globalFilter

Custom global filter function that searches across all visible columns. Supports debounced search input.

import { globalFilter } from "@/components/niko-table/lib"

const table = useReactTable({
  globalFilterFn: globalFilter,
})

numberRangeFilter

Filter function for numeric range columns. Filters rows where the value is between a [min, max] range.

import { numberRangeFilter } from "@/components/niko-table/lib"

const columns = [
  {
    accessorKey: "price",
    filterFn: numberRangeFilter,
  },
]

dateRangeFilter

Filter function for date range columns. Filters rows where the date falls between a start and end date.

import { dateRangeFilter } from "@/components/niko-table/lib"

const columns = [
  {
    accessorKey: "createdAt",
    filterFn: dateRangeFilter,
  },
]

createFilterValue

Utility to create a properly typed filter value object from an ExtendedColumnFilter. Used internally by the filter menu and inline filter components.

import { createFilterValue } from "@/components/niko-table/lib"

const filterValue = createFilterValue(filter)

processFiltersForLogic

Processes an array of ExtendedColumnFilter objects and groups them by join operator (AND/OR) for TanStack Table’s column filter state. Returns processed filters and the join operator map.

import { processFiltersForLogic } from "@/components/niko-table/lib"

const { processedFilters, joinOperators } = processFiltersForLogic(filters)

Style Utilities

Helper functions for styling table components, particularly for column pinning.

Source Code ↗

getCommonPinningStyles

Returns CSS styles for pinned columns (sticky positioning, z-index, shadows). Used internally by DataTable components, but available for custom implementations.

import { getCommonPinningStyles } from "@/components/niko-table/lib"

// In a custom header cell
const pinningStyles = getCommonPinningStyles(column, true)

// In a custom body cell
const pinningStyles = getCommonPinningStyles(column, false)

Parameters

Name	Type	Default	Description
column	Column<TData>	-	TanStack Table column instance
isHeader	boolean	false	Whether this is a header cell (affects z-index layer)

Returns

React.CSSProperties - CSS styles object with sticky positioning, z-index, background, and shadow.

Style Properties Applied:

• position: sticky - Keeps column fixed during horizontal scroll
• left or right - Calculated position based on pinning side
• zIndex - 20 for headers, 10 for body cells
• backgroundColor - Uses --background CSS variable for opacity
• boxShadow - Visual separator using --border CSS variable

Additional Constants

SYSTEM_COLUMN_IDS

System column IDs used for smart pinning and feature detection. These are the IDs for special columns like row selection and row expansion.

import { SYSTEM_COLUMN_IDS } from "@/components/niko-table/lib"

// Available IDs:
SYSTEM_COLUMN_IDS.SELECT // "select" - Row selection checkbox column
SYSTEM_COLUMN_IDS.EXPAND // "expand" - Row expansion toggle column

SYSTEM_COLUMN_ID_LIST

Array version of SYSTEM_COLUMN_IDS values. Useful for filtering or checking if a column ID is a system column.

import { SYSTEM_COLUMN_ID_LIST } from "@/components/niko-table/lib"

// ["select", "expand"]
const isSystemColumn = SYSTEM_COLUMN_ID_LIST.includes(columnId)

ERROR_MESSAGES

Standard error messages used throughout the library for consistent error reporting.

import { ERROR_MESSAGES } from "@/components/niko-table/lib"

// Available messages:
ERROR_MESSAGES.DEPRECATED_GLOBAL_JOIN_OPERATOR