@tanstack/table-core 9.0.0-alpha.8 → 9.0.0-beta.10

package/src/fns/sortFns.ts

@@ -0,0 +1,240 @@
+import type { RowData } from '../types/type-utils'
+import type { TableFeatures } from '../types/TableFeatures'
+import type { Row } from '../types/Row'
+
+/**
+ * Regular expression used to split mixed text and numeric chunks.
+ *
+ * The alphanumeric sort functions use these chunks for natural sorting of
+ * strings like `item2` before `item10`.
+ */
+export const reSplitAlphaNumeric = /([0-9]+)/gm
+
+/**
+ * Sorts rows with the built-in alphanumeric strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_alphanumeric = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<TFeatures, TData>,
+  rowB: Row<TFeatures, TData>,
+  columnId: string,
+) => {
+  return compareAlphanumeric(
+    toString(rowA.getValue(columnId)).toLowerCase(),
+    toString(rowB.getValue(columnId)).toLowerCase(),
+  )
+}
+
+/**
+ * Sorts rows with the built-in alphanumeric case sensitive strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_alphanumericCaseSensitive = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<TFeatures, TData>,
+  rowB: Row<TFeatures, TData>,
+  columnId: string,
+) => {
+  return compareAlphanumeric(
+    toString(rowA.getValue(columnId)),
+    toString(rowB.getValue(columnId)),
+  )
+}
+
+// The text filter is more basic (less numeric support)
+// but is much faster
+/**
+ * Sorts rows with the built-in text strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_text = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<TFeatures, TData>,
+  rowB: Row<TFeatures, TData>,
+  columnId: string,
+) => {
+  return compareBasic(
+    toString(rowA.getValue(columnId)).toLowerCase(),
+    toString(rowB.getValue(columnId)).toLowerCase(),
+  )
+}
+
+// The text filter is more basic (less numeric support)
+// but is much faster
+/**
+ * Sorts rows with the built-in text case sensitive strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_textCaseSensitive = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<TFeatures, TData>,
+  rowB: Row<TFeatures, TData>,
+  columnId: string,
+) => {
+  return compareBasic(
+    toString(rowA.getValue(columnId)),
+    toString(rowB.getValue(columnId)),
+  )
+}
+
+/**
+ * Sorts rows with the built-in datetime strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_datetime = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<TFeatures, TData>,
+  rowB: Row<TFeatures, TData>,
+  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
+  // Date objects (would require calling getTime()).
+  return a > b ? 1 : a < b ? -1 : 0
+}
+
+/**
+ * Sorts rows with the built-in basic strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_basic = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<TFeatures, TData>,
+  rowB: Row<TFeatures, TData>,
+  columnId: string,
+) => {
+  return compareBasic(rowA.getValue(columnId), rowB.getValue(columnId))
+}
+
+// Utils
+
+function compareBasic(a: any, b: any) {
+  return a === b ? 0 : a > b ? 1 : -1
+}
+
+function toString(a: any) {
+  if (typeof a === 'number') {
+    if (isNaN(a) || a === Infinity || a === -Infinity) {
+      return ''
+    }
+    return String(a)
+  }
+  if (typeof a === 'string') {
+    return a
+  }
+  return ''
+}
+
+// Mixed sorting is slow, but very inclusive of many edge cases.
+// It handles numbers, mixed alphanumeric combinations, and even
+// null, undefined, and Infinity
+function compareAlphanumeric(aStr: string, bStr: string) {
+  const a = aStr.split(reSplitAlphaNumeric)
+  const b = bStr.split(reSplitAlphaNumeric)
+
+  let ai = 0
+  let bi = 0
+  const aLen = a.length
+  const bLen = b.length
+
+  while (ai < aLen && bi < bLen) {
+    // Skip the empty boundary chunks that .filter(Boolean) used to remove
+    if (!a[ai]) {
+      ai++
+      continue
+    }
+    if (!b[bi]) {
+      bi++
+      continue
+    }
+
+    const aa = a[ai++]!
+    const bb = b[bi++]!
+
+    // Chunks are either all-digit (parseInt always succeeds) or digit-free
+    // (parseInt is always NaN), so NaN-ness fully classifies each chunk
+    const an = parseInt(aa, 10)
+    const bn = parseInt(bb, 10)
+
+    const aIsNaN = isNaN(an)
+    const bIsNaN = isNaN(bn)
+
+    // Both are string
+    if (aIsNaN && bIsNaN) {
+      if (aa > bb) {
+        return 1
+      }
+      if (bb > aa) {
+        return -1
+      }
+      continue
+    }
+
+    // One is a string, one is a number — the string chunk sorts first
+    if (aIsNaN || bIsNaN) {
+      return aIsNaN ? -1 : 1
+    }
+
+    // Both are numbers
+    if (an > bn) {
+      return 1
+    }
+    if (bn > an) {
+      return -1
+    }
+  }
+
+  // One side is exhausted — compare the counts of remaining non-empty chunks
+  let remaining = 0
+  for (; ai < aLen; ai++) {
+    if (a[ai]) {
+      remaining++
+    }
+  }
+  for (; bi < bLen; bi++) {
+    if (b[bi]) {
+      remaining--
+    }
+  }
+  return remaining
+}
+
+// Exports
+
+/**
+ * The built-in sorting function registry.
+ *
+ * Pass this object to sorted row model creation or extend it with custom sorting functions.
+ */
+export const sortFns = {
+  alphanumeric: sortFn_alphanumeric,
+  alphanumericCaseSensitive: sortFn_alphanumericCaseSensitive,
+  basic: sortFn_basic,
+  datetime: sortFn_datetime,
+  text: sortFn_text,
+  textCaseSensitive: sortFn_textCaseSensitive,
+}
+
+export type BuiltInSortFn = keyof typeof sortFns

package/src/helpers/columnHelper.ts

@@ -0,0 +1,122 @@
+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>
+}
+
+/**
+ * Creates helper functions for authoring column definitions with stronger value
+ * inference.
+ *
+ * `accessor` infers `TValue` from an accessor key or accessor function,
+ * `display` creates non-data columns, `group` creates parent columns, and
+ * `columns` preserves tuple-level value types for arrays. At runtime these
+ * helpers only return column definition objects.
+ *
+ * @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, { id: '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/metaHelper.ts

@@ -0,0 +1,24 @@
+/**
+ * A helper for declaring the `tableMeta`/`columnMeta` type-only slots in the
+ * `features` option without a type assertion.
+ *
+ * Equivalent to `{} as TMeta`, but reads as type-only at the call site and
+ * avoids `@typescript-eslint/no-unnecessary-type-assertion` false positives
+ * when the meta type has only optional properties (where an auto-fix removing
+ * the assertion would silently degrade the inferred meta type to `{}`).
+ *
+ * The returned value is a phantom — it is ignored and stripped from the
+ * table's registered features at runtime; only its type is used.
+ * @example
+ * ```
+ * import { metaHelper, tableFeatures, rowSortingFeature } from '@tanstack/react-table'
+ * const features = tableFeatures({
+ *   rowSortingFeature,
+ *   tableMeta: metaHelper<MyTableMeta>(),
+ *   columnMeta: metaHelper<MyColumnMeta>(),
+ * });
+ * ```
+ */
+export function metaHelper<TMeta extends object>(): TMeta {
+  return {} as TMeta
+}

package/src/helpers/tableFeatures.ts

@@ -0,0 +1,55 @@
+import type {
+  TableFeatures,
+  ValidateFeatureSlots,
+} 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.
+ *
+ * Alongside feature modules, this object carries everything else that is
+ * statically stitched into the table:
+ *
+ * - Row model factories (`sortedRowModel`, `filteredRowModel`, etc.)
+ * - Row model function registries (`sortFns`, `filterFns`, `aggregationFns`),
+ *   whose keys become the valid string values for `sortFn`, `filterFn`,
+ *   `globalFilterFn`, and `aggregationFn` with full inference
+ * - Type-only `tableMeta`/`columnMeta` slots for declaring per-table meta types
+ *   instead of using global declaration merging. The values are phantom
+ *   (ignored and stripped at runtime); only their types are used.
+ * @example
+ * ```
+ * import {
+ *   columnFilteringFeature,
+ *   createFilteredRowModel,
+ *   createSortedRowModel,
+ *   filterFns,
+ *   rowSortingFeature,
+ *   sortFns,
+ *   tableFeatures,
+ * } from '@tanstack/react-table'
+ * const features = tableFeatures({
+ *   columnFilteringFeature,
+ *   rowSortingFeature,
+ *   filteredRowModel: createFilteredRowModel(),
+ *   sortedRowModel: createSortedRowModel(),
+ *   filterFns: { ...filterFns, myCustomFilterFn },
+ *   sortFns,
+ *   tableMeta: {} as { updateData: (rowIndex: number, columnId: string, value: unknown) => void },
+ *   columnMeta: {} as { align?: 'left' | 'right' },
+ * });
+ * const table = useTable({ features, columns, data });
+ * ```
+ */
+export function tableFeatures<TFeatures extends TableFeatures>(
+  features: TFeatures & ValidateFeatureSlots<TFeatures>,
+): TFeatures {
+  return features
+}
+
+// test
+
+// const features = tableFeatures({
+//   rowPinningFeature: {},
+// });

package/src/helpers/tableOptions.ts

@@ -0,0 +1,117 @@
+import type { RowData } from '../types/type-utils'
+import type { TableFeatures } from '../types/TableFeatures'
+import type { TableOptions } from '../types/TableOptions'
+
+/**
+ * Preserves table option inference when reusable options omit `columns`.
+ *
+ * This is useful for composing shared options that will receive columns later
+ * from a framework adapter or table factory.
+ */
+export function tableOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  options: Omit<TableOptions<TFeatures, TData>, 'columns'> & {
+    features: TFeatures
+  },
+): Omit<TableOptions<TFeatures, TData>, 'columns' | 'features'> & {
+  features: TFeatures
+}
+
+/**
+ * Preserves table option inference when reusable options omit `data`.
+ */
+export function tableOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  options: Omit<TableOptions<TFeatures, TData>, 'data'> & {
+    features: TFeatures
+  },
+): Omit<TableOptions<TFeatures, TData>, 'data' | 'features'> & {
+  features: TFeatures
+}
+
+/**
+ * Preserves table option inference when reusable options omit both `data` and
+ * `columns`.
+ */
+export function tableOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  options: Omit<TableOptions<TFeatures, TData>, 'data' | 'columns'> & {
+    features: TFeatures
+  },
+): Omit<TableOptions<TFeatures, TData>, 'data' | 'columns' | 'features'> & {
+  features: TFeatures
+}
+
+/**
+ * Preserves inference for a fully specified table options object.
+ */
+export function tableOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(options: TableOptions<TFeatures, TData>): TableOptions<TFeatures, TData>
+
+/**
+ * Preserves inference when a wrapper supplies `features`.
+ */
+export function tableOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  options: Omit<TableOptions<TFeatures, TData>, 'features'>,
+): Omit<TableOptions<TFeatures, TData>, 'features'>
+
+/**
+ * Preserves inference when a wrapper supplies both `data` and `features`.
+ */
+export function tableOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  options: Omit<TableOptions<TFeatures, TData>, 'data' | 'features'>,
+): Omit<TableOptions<TFeatures, TData>, 'data' | 'features'>
+
+/**
+ * Preserves inference when a wrapper supplies both `columns` and `features`.
+ */
+export function tableOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  options: Omit<TableOptions<TFeatures, TData>, 'columns' | 'features'>,
+): Omit<TableOptions<TFeatures, TData>, 'columns' | 'features'>
+
+/**
+ * Preserves inference when a wrapper supplies `data`, `columns`, and
+ * `features`.
+ */
+export function tableOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  options: Omit<
+    TableOptions<TFeatures, TData>,
+    'data' | 'columns' | 'features'
+  >,
+): Omit<TableOptions<TFeatures, TData>, 'data' | 'columns' | 'features'>
+
+/**
+ * Runtime implementation for `tableOptions`.
+ *
+ * The helper returns the same object it receives; all value comes from the
+ * overloads preserving table option inference at compile time.
+ */
+export function tableOptions(options: unknown) {
+  return options
+}
+
+// test
+
+// const options = tableOptions({
+//   features: {},
+// })