@tanstack/table-core 9.0.0-alpha.4 → 9.0.0-alpha.41

package/src/fns/filterFns.ts

@@ -0,0 +1,379 @@
+import type { RowData } from '../types/type-utils'
+import type { TableFeatures } from '../types/TableFeatures'
+import type { Row } from '../types/Row'
+import type { FilterFn } from '../features/column-filtering/columnFilteringFeature.types'
+
+// Basic filters
+
+/**
+ * Filter function for checking if a value is exactly equal to a given value. (JS === comparison)
+ */
+export const filterFn_equals: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: unknown,
+) => {
+  return row.getValue(columnId) === filterValue
+}
+
+filterFn_equals.autoRemove = (val: any) => testFalsy(val)
+
+/**
+ * Filter function for checking if a value is weakly equal to a given value. (JS == comparison)
+ */
+export const filterFn_weakEquals: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: unknown,
+) => {
+  return row.getValue(columnId) == filterValue
+}
+
+filterFn_weakEquals.autoRemove = (val: any) => testFalsy(val)
+
+// String filters
+
+/**
+ * Filter function for checking if a string includes a given substring. (Case-sensitive)
+ */
+export const filterFn_includesStringSensitive: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: string,
+) => {
+  return Boolean(
+    row.getValue(columnId)?.toString().includes(filterValue.toString()),
+  )
+}
+
+filterFn_includesStringSensitive.autoRemove = (val: any) => testFalsy(val)
+
+/**
+ * Filter function for checking if a string includes a given substring. (Non-case-sensitive)
+ */
+export const filterFn_includesString: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: string,
+) => {
+  return Boolean(
+    row
+      .getValue(columnId)
+      ?.toString()
+      .toLowerCase()
+      .includes(filterValue.toString().toLowerCase()),
+  )
+}
+
+filterFn_includesString.autoRemove = (val: any) => testFalsy(val)
+
+/**
+ * Filter function for checking if a string is exactly equal to a given string. (Non-case-sensitive)
+ */
+export const filterFn_equalsString: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: string,
+) => {
+  return (
+    row.getValue(columnId)?.toString().toLowerCase() ===
+    filterValue.toLowerCase()
+  )
+}
+
+filterFn_equalsString.autoRemove = (val: any) => testFalsy(val)
+
+/**
+ * Filter function for checking if a string is exactly equal to a given string. (Case-sensitive)
+ */
+export const filterFn_equalsStringSensitive: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: string,
+) => {
+  return row.getValue(columnId)?.toString() === filterValue
+}
+
+filterFn_equalsStringSensitive.autoRemove = (val: any) => testFalsy(val)
+
+// Number filters
+
+/**
+ * Filter function for checking if a number is greater than a given number.
+ */
+export const filterFn_greaterThan: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: Date | number | string,
+) => {
+  const rowValue = row.getValue(columnId)
+  const numericRowValue =
+    rowValue === null || rowValue === undefined ? 0 : +rowValue
+  const numericFilterValue = +filterValue
+
+  if (!isNaN(numericFilterValue) && !isNaN(numericRowValue)) {
+    return numericRowValue > numericFilterValue
+  }
+
+  const stringValue = (rowValue ?? '').toString().toLowerCase().trim()
+  const stringFilterValue = filterValue.toString().toLowerCase().trim()
+  return stringValue > stringFilterValue
+}
+
+filterFn_greaterThan.resolveFilterValue = (val: any) => testFalsy(val)
+
+/**
+ * Filter function for checking if a number is greater than or equal to a given number.
+ */
+export const filterFn_greaterThanOrEqualTo: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: Date | number | string,
+) => {
+  return (
+    filterFn_greaterThan(row as any, columnId, filterValue) ||
+    filterFn_equals(row as any, columnId, filterValue)
+  )
+}
+
+filterFn_greaterThanOrEqualTo.resolveFilterValue = (val: any) => testFalsy(val)
+
+/**
+ * Filter function for checking if a number is less than a given number.
+ */
+export const filterFn_lessThan: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: Date | number | string,
+) => {
+  return !filterFn_greaterThanOrEqualTo(row as any, columnId, filterValue)
+}
+
+filterFn_lessThan.resolveFilterValue = (val: any) => testFalsy(val)
+
+/**
+ * Filter function for checking if a number is less than or equal to a given number.
+ */
+export const filterFn_lessThanOrEqualTo: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: Date | number | string,
+) => {
+  return !filterFn_greaterThan(row as any, columnId, filterValue)
+}
+
+filterFn_lessThanOrEqualTo.resolveFilterValue = (val: any) => testFalsy(val)
+
+// Range filters
+
+/**
+ * Filter function for checking if a number or a string is between two given values.
+ */
+const filterFn_between: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValues: [number | string, number | string],
+): boolean =>
+  ((['', undefined] as Array<any>).includes(filterValues[0]) ||
+    filterFn_greaterThan(row as any, columnId, filterValues[0])) &&
+  ((!isNaN(+filterValues[0]) &&
+    !isNaN(+filterValues[1]) &&
+    +filterValues[0] > +filterValues[1]) ||
+    (['', undefined] as Array<any>).includes(filterValues[1]) ||
+    filterFn_lessThan(row as any, columnId, filterValues[1]))
+
+filterFn_between.autoRemove = (val: any) => !val
+
+/**
+ * Filter function for checking if a number or a string is between two given values or equal to them.
+ */
+const filterFn_betweenInclusive: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValues: [number | string, number | string],
+): boolean =>
+  ((['', undefined] as Array<any>).includes(filterValues[0]) ||
+    filterFn_greaterThanOrEqualTo(row as any, columnId, filterValues[0])) &&
+  ((!isNaN(+filterValues[0]) &&
+    !isNaN(+filterValues[1]) &&
+    +filterValues[0] > +filterValues[1]) ||
+    (['', undefined] as Array<any>).includes(filterValues[1]) ||
+    filterFn_lessThanOrEqualTo(row as any, columnId, filterValues[1]))
+
+filterFn_betweenInclusive.autoRemove = (val: any) => !val
+
+/**
+ * Filter function for checking if a number is within a given range.
+ */
+export const filterFn_inNumberRange: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: [number, number],
+) => {
+  const [min, max] = filterValue
+
+  const rowValue: number = row.getValue(columnId)
+  return rowValue >= min && rowValue <= max
+}
+
+filterFn_inNumberRange.resolveFilterValue = (val: [any, any]) => {
+  const [unsafeMin, unsafeMax] = val
+
+  const parsedMin =
+    typeof unsafeMin !== 'number' ? parseFloat(unsafeMin) : unsafeMin
+  const parsedMax =
+    typeof unsafeMax !== 'number' ? parseFloat(unsafeMax) : unsafeMax
+
+  let min =
+    unsafeMin === null || Number.isNaN(parsedMin) ? -Infinity : parsedMin
+  let max = unsafeMax === null || Number.isNaN(parsedMax) ? Infinity : parsedMax
+
+  if (min > max) {
+    const temp = min
+    min = max
+    max = temp
+  }
+
+  return [min, max] as const
+}
+
+filterFn_inNumberRange.autoRemove = (val: any) =>
+  testFalsy(val) || (testFalsy(val[0]) && testFalsy(val[1]))
+
+// Array filters
+
+/**
+ * Filter function for checking if an array has a given value.
+ */
+export const filterFn_arrHas: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: Array<unknown>,
+) => {
+  return filterValue.some((val) => row.getValue<unknown>(columnId) === val)
+}
+
+/**
+ * Filter function for checking if an array includes a given value.
+ */
+export const filterFn_arrIncludes: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: Array<unknown>,
+) => {
+  return filterValue.some((val) =>
+    (row.getValue<unknown>(columnId) as Array<unknown> | string).includes(
+      val as any,
+    ),
+  )
+}
+
+filterFn_arrIncludes.autoRemove = (val: any) => testFalsy(val) || !val?.length
+
+/**
+ * Filter function for checking if an array includes all of the given values.
+ */
+export const filterFn_arrIncludesAll: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: Array<unknown>,
+) => {
+  const value = row.getValue<Array<unknown>>(columnId)
+  if (!Array.isArray(value)) return false
+  return !filterValue.some((val) => !value.includes(val))
+}
+
+filterFn_arrIncludesAll.autoRemove = (val: any) =>
+  testFalsy(val) || !val?.length
+
+/**
+ * Filter function for checking if an array includes any of the given values.
+ */
+export const filterFn_arrIncludesSome: FilterFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: Array<unknown>,
+) => {
+  const value = row.getValue<Array<unknown>>(columnId)
+  if (!Array.isArray(value)) return false
+  return filterValue.some((val) => value.includes(val))
+}
+
+filterFn_arrIncludesSome.autoRemove = (val: any) =>
+  testFalsy(val) || !val?.length
+
+// Export
+
+export const filterFns = {
+  arrIncludes: filterFn_arrIncludes,
+  arrIncludesAll: filterFn_arrIncludesAll,
+  arrHas: filterFn_arrHas,
+  arrIncludesSome: filterFn_arrIncludesSome,
+  between: filterFn_between,
+  betweenInclusive: filterFn_betweenInclusive,
+  equals: filterFn_equals,
+  equalsString: filterFn_equalsString,
+  inNumberRange: filterFn_inNumberRange,
+  includesString: filterFn_includesString,
+  includesStringSensitive: filterFn_includesStringSensitive,
+  weakEquals: filterFn_weakEquals,
+}
+
+export type BuiltInFilterFn = keyof typeof filterFns
+
+// Utils
+
+function testFalsy(val: any) {
+  return val === undefined || val === null || val === ''
+}

package/src/{sortingFns.ts → fns/sortFns.ts}

@@ -1,42 +1,80 @@
-import { SortingFn } from './features/RowSorting'
+import type { RowData } from '../types/type-utils'
+import type { TableFeatures } from '../types/TableFeatures'
+import type { Row } from '../types/Row'
+import type { SortFn } from '../features/row-sorting/rowSortingFeature.types'
 
 export const reSplitAlphaNumeric = /([0-9]+)/gm
 
-const alphanumeric: SortingFn<any> = (rowA, rowB, columnId) => {
+export const sortFn_alphanumeric: SortFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<any, any>,
+  rowB: Row<any, any>,
+  columnId: string,
+) => {
   return compareAlphanumeric(
     toString(rowA.getValue(columnId)).toLowerCase(),
-    toString(rowB.getValue(columnId)).toLowerCase()
+    toString(rowB.getValue(columnId)).toLowerCase(),
   )
 }
 
-const alphanumericCaseSensitive: SortingFn<any> = (rowA, rowB, columnId) => {
+export const sortFn_alphanumericCaseSensitive: SortFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<any, any>,
+  rowB: Row<any, any>,
+  columnId: string,
+) => {
   return compareAlphanumeric(
     toString(rowA.getValue(columnId)),
-    toString(rowB.getValue(columnId))
+    toString(rowB.getValue(columnId)),
   )
 }
 
 // The text filter is more basic (less numeric support)
 // but is much faster
-const text: SortingFn<any> = (rowA, rowB, columnId) => {
+export const sortFn_text: SortFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<any, any>,
+  rowB: Row<any, any>,
+  columnId: string,
+) => {
   return compareBasic(
     toString(rowA.getValue(columnId)).toLowerCase(),
-    toString(rowB.getValue(columnId)).toLowerCase()
+    toString(rowB.getValue(columnId)).toLowerCase(),
   )
 }
 
 // The text filter is more basic (less numeric support)
 // but is much faster
-const textCaseSensitive: SortingFn<any> = (rowA, rowB, columnId) => {
+export const sortFn_textCaseSensitive: SortFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<any, any>,
+  rowB: Row<any, any>,
+  columnId: string,
+) => {
   return compareBasic(
     toString(rowA.getValue(columnId)),
-    toString(rowB.getValue(columnId))
+    toString(rowB.getValue(columnId)),
   )
 }
 
-const datetime: SortingFn<any> = (rowA, rowB, columnId) => {
-  const a = rowA.getValue<Date>(columnId)
-  const b = rowB.getValue<Date>(columnId)
+export const sortFn_datetime: SortFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<any, any>,
+  rowB: Row<any, any>,
+  columnId: string,
+) => {
+  const a: number | string = rowA.getValue(columnId)
+  const b: number | string = rowB.getValue(columnId)
 
   // Can handle nullish values
   // Use > and < because == (and ===) doesn't work with
@@ -44,7 +82,14 @@ const datetime: SortingFn<any> = (rowA, rowB, columnId) => {
   return a > b ? 1 : a < b ? -1 : 0
 }
 
-const basic: SortingFn<any> = (rowA, rowB, columnId) => {
+export const sortFn_basic: SortFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<any, any>,
+  rowB: Row<any, any>,
+  columnId: string,
+) => {
   return compareBasic(rowA.getValue(columnId), rowB.getValue(columnId))
 }
 
@@ -116,13 +161,13 @@ function compareAlphanumeric(aStr: string, bStr: string) {
 
 // Exports
 
-export const sortingFns = {
-  alphanumeric,
-  alphanumericCaseSensitive,
-  text,
-  textCaseSensitive,
-  datetime,
-  basic,
+export const sortFns = {
+  alphanumeric: sortFn_alphanumeric,
+  alphanumericCaseSensitive: sortFn_alphanumericCaseSensitive,
+  basic: sortFn_basic,
+  datetime: sortFn_datetime,
+  text: sortFn_text,
+  textCaseSensitive: sortFn_textCaseSensitive,
 }
 
-export type BuiltInSortingFn = keyof typeof sortingFns
+export type BuiltInSortFn = keyof typeof sortFns

package/src/helpers/columnHelper.ts

@@ -0,0 +1,117 @@
+import type { DeepKeys, DeepValue, RowData } from '../types/type-utils'
+import type { TableFeatures } from '../types/TableFeatures'
+import type {
+  AccessorFn,
+  AccessorFnColumnDef,
+  AccessorKeyColumnDef,
+  ColumnDef,
+  DisplayColumnDef,
+  GroupColumnDef,
+  IdentifiedColumnDef,
+} from '../types/ColumnDef'
+
+export type ColumnHelper<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = {
+  /**
+   * Creates a data column definition with an accessor key or function to extract the cell value.
+   * @example
+   * ```ts
+   * helper.accessor('firstName', { cell: (info) => info.getValue() })
+   * helper.accessor((row) => row.lastName, { id: 'lastName' })
+   * ```
+   */
+  accessor: <
+    TAccessor extends AccessorFn<TData> | DeepKeys<TData>,
+    TValue extends TAccessor extends AccessorFn<TData, infer TReturn>
+      ? TReturn
+      : TAccessor extends DeepKeys<TData>
+        ? DeepValue<TData, TAccessor>
+        : never,
+  >(
+    accessor: TAccessor,
+    column: TAccessor extends AccessorFn<TData>
+      ? DisplayColumnDef<TFeatures, TData, TValue>
+      : IdentifiedColumnDef<TFeatures, TData, TValue>,
+  ) => TAccessor extends AccessorFn<TData>
+    ? AccessorFnColumnDef<TFeatures, TData, TValue>
+    : AccessorKeyColumnDef<TFeatures, TData, TValue>
+  /**
+   * Wraps an array of column definitions to preserve each column's individual TValue type.
+   * Uses variadic tuple types to infer element types before checking constraints, preventing type widening.
+   * @example
+   * ```ts
+   * helper.columns([helper.accessor('firstName', {}), helper.accessor('age', {})])
+   * ```
+   */
+  columns: <TColumns extends ReadonlyArray<ColumnDef<TFeatures, TData, any>>>(
+    columns: [...TColumns],
+  ) => Array<ColumnDef<TFeatures, TData, any>> & [...TColumns]
+  /**
+   * Creates a display column definition for non-data columns like actions or row selection.
+   * @example
+   * ```ts
+   * helper.display({ id: 'actions', header: 'Actions', cell: () => <button>Edit</button> })
+   * ```
+   */
+  display: (
+    column: DisplayColumnDef<TFeatures, TData>,
+  ) => DisplayColumnDef<TFeatures, TData, unknown>
+  /**
+   * Creates a group column definition that contains nested child columns.
+   * @example
+   * ```ts
+   * helper.group({
+   *   id: 'name',
+   *   header: 'Name',
+   *   columns: helper.columns([
+   *     helper.accessor('firstName', {}),
+   *     helper.accessor('lastName', { id: 'lastName' }),
+   *   ]),
+   * })
+   * ```
+   */
+  group: (
+    column: GroupColumnDef<TFeatures, TData, unknown>,
+  ) => GroupColumnDef<TFeatures, TData, unknown>
+}
+
+/**
+ * A helper utility for creating column definitions with slightly better type inference for each individual column.
+ * The `TValue` generic is inferred based on the accessor key or function provided.
+ * **Note:** From a JavaScript perspective, the functions in these helpers do not do anything. They are only used to help TypeScript infer the correct types for the column definitions.
+ * @example
+ * ```tsx
+ * const helper = createColumnHelper<typeof _features, Person>() // _features is the result of `tableFeatures({})` helper
+ * const columns = [
+ *  helper.display({ id: 'actions', header: 'Actions' }),
+ *  helper.accessor('firstName', {}),
+ *  helper.accessor((row) => row.lastName, {}
+ * ]
+ * ```
+ */
+export function createColumnHelper<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): ColumnHelper<TFeatures, TData> {
+  return {
+    accessor: (accessor, column) => {
+      return typeof accessor === 'function'
+        ? ({
+            ...column,
+            accessorFn: accessor,
+          } as any)
+        : {
+            ...column,
+            accessorKey: accessor,
+          }
+    },
+    columns: <TColumns extends ReadonlyArray<ColumnDef<TFeatures, TData, any>>>(
+      columns: [...TColumns],
+    ): Array<ColumnDef<TFeatures, TData, any>> & [...TColumns] =>
+      columns as Array<ColumnDef<TFeatures, TData, any>> & [...TColumns],
+    display: (column) => column,
+    group: (column) => column,
+  }
+}

package/src/helpers/tableFeatures.ts

@@ -0,0 +1,24 @@
+import type { TableFeatures } from '../types/TableFeatures'
+
+/**
+ * A helper function to help define the features that are to be imported and applied to a table instance.
+ * Use this utility to make it easier to have the correct type inference for the features that are being imported.
+ * **Note:** It is recommended to use this utility statically outside of a component.
+ * @example
+ * ```
+ * import { tableFeatures, columnVisibilityFeature, rowPinningFeature } from '@tanstack/react-table'
+ * const _features = tableFeatures({ columnVisibilityFeature, rowPinningFeature });
+ * const table = useTable({ _features, rowModels: {}, columns, data });
+ * ```
+ */
+export function tableFeatures<TFeatures extends TableFeatures>(
+  features: TFeatures,
+): TFeatures {
+  return features
+}
+
+// test
+
+// const features = tableFeatures({
+//   rowPinningFeature: {},
+// });