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

package/src/fns/aggregationFns.ts

@@ -0,0 +1,245 @@
+import type { RowData } from '../types/type-utils'
+import type { TableFeatures } from '../types/TableFeatures'
+import type { Row } from '../types/Row'
+
+/**
+ * Sums numeric child-row values for a grouped column.
+ *
+ * Non-number values contribute `0`. Child rows are used so nested group totals
+ * can reuse already aggregated values.
+ */
+export function aggregationFn_sum<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  columnId: string,
+  _leafRows: Array<Row<TFeatures, TData>>,
+  childRows: Array<Row<TFeatures, TData>>,
+) {
+  // It's faster to just add the aggregations together instead of
+  // process leaf nodes individually
+  return childRows.reduce((sumValue, next) => {
+    const nextValue = next.getValue(columnId)
+    return sumValue + (typeof nextValue === 'number' ? nextValue : 0)
+  }, 0)
+}
+
+/**
+ * Finds the minimum numeric child-row value for a grouped column.
+ *
+ * Nullish and non-number values are ignored. Returns `undefined` when no
+ * numeric value is found.
+ */
+export function aggregationFn_min<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  columnId: string,
+  _leafRows: Array<Row<TFeatures, TData>>,
+  childRows: Array<Row<TFeatures, TData>>,
+) {
+  let minValue: number | undefined
+
+  childRows.forEach((row) => {
+    const value = row.getValue(columnId)
+
+    if (
+      value != null &&
+      typeof value === 'number' &&
+      (minValue === undefined || value < minValue)
+    ) {
+      minValue = value
+    }
+  })
+
+  return minValue
+}
+
+/**
+ * Finds the maximum numeric child-row value for a grouped column.
+ *
+ * Nullish and non-number values are ignored. Returns `undefined` when no
+ * numeric value is found.
+ */
+export function aggregationFn_max<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  columnId: string,
+  _leafRows: Array<Row<TFeatures, TData>>,
+  childRows: Array<Row<TFeatures, TData>>,
+) {
+  let maxValue: number | undefined
+
+  childRows.forEach((row) => {
+    const value = row.getValue(columnId)
+    if (
+      value != null &&
+      typeof value === 'number' &&
+      (maxValue === undefined || value > maxValue)
+    ) {
+      maxValue = value
+    }
+  })
+
+  return maxValue
+}
+
+/**
+ * Finds the numeric extent for a grouped column.
+ *
+ * Returns `[min, max]`, where each entry is `undefined` when no numeric value is
+ * present.
+ */
+export function aggregationFn_extent<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  columnId: string,
+  _leafRows: Array<Row<TFeatures, TData>>,
+  childRows: Array<Row<TFeatures, TData>>,
+) {
+  let minValue: number | undefined
+  let maxValue: number | undefined
+
+  childRows.forEach((row) => {
+    const value = row.getValue(columnId)
+    if (value != null && typeof value === 'number') {
+      if (minValue === undefined) {
+        minValue = maxValue = value
+      } else {
+        if (minValue > value) minValue = value
+        if (maxValue! < value) maxValue = value
+      }
+    }
+  })
+
+  return [minValue, maxValue]
+}
+
+/**
+ * Averages numeric leaf-row values for a grouped column.
+ *
+ * Number-like values are coerced with unary `+`; nullish and non-numeric values
+ * are ignored.
+ */
+export function aggregationFn_mean<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(columnId: string, leafRows: Array<Row<TFeatures, TData>>) {
+  let count = 0
+  let sumValue = 0
+
+  leafRows.forEach((row) => {
+    const value = row.getValue(columnId)
+    if (value != null && typeof value === 'number') {
+      ++count
+      sumValue += value
+    } else if (value != null) {
+      const numValue = +value
+      if (!Number.isNaN(numValue)) {
+        ++count
+        sumValue += numValue
+      }
+    }
+  })
+
+  if (count) return sumValue / count
+
+  return
+}
+
+/**
+ * Computes the median of numeric leaf-row values for a grouped column.
+ *
+ * All values must be numbers. If any value is non-numeric, or no leaf rows are
+ * present, the result is `undefined`.
+ */
+export function aggregationFn_median<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(columnId: string, leafRows: Array<Row<TFeatures, TData>>) {
+  if (!leafRows.length) {
+    return
+  }
+
+  const values: Array<number> = new Array(leafRows.length)
+  for (let i = 0; i < leafRows.length; i++) {
+    const v = leafRows[i]!.getValue(columnId)
+    if (typeof v !== 'number') return
+    values[i] = v
+  }
+
+  if (values.length === 1) {
+    return values[0]
+  }
+
+  const mid = Math.floor(values.length / 2)
+  values.sort((a, b) => a - b)
+  return values.length % 2 !== 0
+    ? values[mid]
+    : (values[mid - 1]! + values[mid]!) / 2
+}
+
+/**
+ * Collects unique leaf-row values for a grouped column.
+ *
+ * Values are compared with JavaScript `Set` semantics.
+ */
+export function aggregationFn_unique<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(columnId: string, leafRows: Array<Row<TFeatures, TData>>) {
+  const set = new Set<unknown>()
+  for (let i = 0; i < leafRows.length; i++) {
+    set.add(leafRows[i]!.getValue(columnId))
+  }
+  return Array.from(set.values())
+}
+
+/**
+ * Counts unique leaf-row values for a grouped column.
+ *
+ * Values are compared with JavaScript `Set` semantics.
+ */
+export function aggregationFn_uniqueCount<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(columnId: string, leafRows: Array<Row<TFeatures, TData>>) {
+  const set = new Set<unknown>()
+  for (let i = 0; i < leafRows.length; i++) {
+    set.add(leafRows[i]!.getValue(columnId))
+  }
+  return set.size
+}
+
+/**
+ * Counts the number of leaf rows in the group.
+ *
+ * The column id is ignored because the result is based only on group size.
+ */
+export function aggregationFn_count<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(_columnId: string, leafRows: Array<Row<TFeatures, TData>>) {
+  return leafRows.length
+}
+
+/**
+ * The built-in aggregation function registry.
+ *
+ * Pass this object to grouped row model creation or extend it with custom aggregation functions for grouped columns.
+ */
+export const aggregationFns = {
+  sum: aggregationFn_sum,
+  min: aggregationFn_min,
+  max: aggregationFn_max,
+  extent: aggregationFn_extent,
+  mean: aggregationFn_mean,
+  median: aggregationFn_median,
+  unique: aggregationFn_unique,
+  uniqueCount: aggregationFn_uniqueCount,
+  count: aggregationFn_count,
+}
+
+export type BuiltInAggregationFn = keyof typeof aggregationFns

package/src/fns/filterFns.ts

@@ -0,0 +1,382 @@
+import type { RowData } from '../types/type-utils'
+import type { TableFeatures } from '../types/TableFeatures'
+import type { Row } from '../types/Row'
+
+// Basic filters
+
+/**
+ * Keeps rows whose column value is strictly equal to the filter value.
+ *
+ * Uses JavaScript `===` comparison and auto-removes empty filter values.
+ */
+export const filterFn_equals = Object.assign(
+  <TFeatures extends TableFeatures, TData extends RowData>(
+    row: Row<TFeatures, TData>,
+    columnId: string,
+    filterValue: unknown,
+  ) => {
+    return row.getValue(columnId) === filterValue
+  },
+  { autoRemove: (val: any) => testFalsy(val) },
+)
+
+/**
+ * Keeps rows whose column value is loosely equal to the filter value.
+ *
+ * Uses JavaScript `==` comparison and auto-removes empty filter values. This is
+ * useful for matching string input against numeric row values.
+ */
+export const filterFn_weakEquals = Object.assign(
+  <TFeatures extends TableFeatures, TData extends RowData>(
+    row: Row<TFeatures, TData>,
+    columnId: string,
+    filterValue: unknown,
+  ) => {
+    return row.getValue(columnId) == filterValue
+  },
+  { autoRemove: (val: any) => testFalsy(val) },
+)
+
+// String filters
+
+/**
+ * Keeps rows whose stringified column value includes the filter text.
+ *
+ * Matching is case-sensitive and empty filter values are auto-removed.
+ */
+export const filterFn_includesStringSensitive = Object.assign(
+  <TFeatures extends TableFeatures, TData extends RowData>(
+    row: Row<TFeatures, TData>,
+    columnId: string,
+    filterValue: unknown,
+  ) => {
+    return Boolean(
+      row.getValue(columnId)?.toString().includes(String(filterValue)),
+    )
+  },
+  { autoRemove: (val: any) => testFalsy(val) },
+)
+
+/**
+ * Keeps rows whose stringified column value includes the filter text.
+ *
+ * Both values are lowercased before comparison, and empty filter values are
+ * auto-removed.
+ */
+export const filterFn_includesString = Object.assign(
+  <TFeatures extends TableFeatures, TData extends RowData>(
+    row: Row<TFeatures, TData>,
+    columnId: string,
+    filterValue: unknown,
+  ) => {
+    return Boolean(
+      row
+        .getValue(columnId)
+        ?.toString()
+        .toLowerCase()
+        .includes(String(filterValue).toLowerCase()),
+    )
+  },
+  { autoRemove: (val: any) => testFalsy(val) },
+)
+
+/**
+ * Keeps rows whose stringified column value equals the filter text.
+ *
+ * Both values are lowercased before comparison, and empty filter values are
+ * auto-removed.
+ */
+export const filterFn_equalsString = Object.assign(
+  <TFeatures extends TableFeatures, TData extends RowData>(
+    row: Row<TFeatures, TData>,
+    columnId: string,
+    filterValue: unknown,
+  ) => {
+    return (
+      row.getValue(columnId)?.toString().toLowerCase() ===
+      String(filterValue).toLowerCase()
+    )
+  },
+  { autoRemove: (val: any) => testFalsy(val) },
+)
+
+/**
+ * Keeps rows whose stringified column value exactly equals the filter text.
+ *
+ * Matching is case-sensitive and empty filter values are auto-removed.
+ */
+export const filterFn_equalsStringSensitive = Object.assign(
+  <TFeatures extends TableFeatures, TData extends RowData>(
+    row: Row<TFeatures, TData>,
+    columnId: string,
+    filterValue: unknown,
+  ) => {
+    return row.getValue(columnId)?.toString() === String(filterValue)
+  },
+  { autoRemove: (val: any) => testFalsy(val) },
+)
+
+// Number filters
+
+/**
+ * Keeps rows whose value is greater than the filter value.
+ *
+ * Numeric values are compared numerically when both sides can be coerced to
+ * numbers; otherwise normalized strings are compared.
+ */
+export const filterFn_greaterThan = Object.assign(
+  <TFeatures extends TableFeatures, TData extends RowData>(
+    row: Row<TFeatures, TData>,
+    columnId: string,
+    filterValue: unknown,
+  ) => {
+    const rowValue = row.getValue(columnId)
+    const numericRowValue =
+      rowValue === null || rowValue === undefined ? 0 : +rowValue
+    const numericFilterValue = Number(filterValue)
+
+    if (!isNaN(numericFilterValue) && !isNaN(numericRowValue)) {
+      return numericRowValue > numericFilterValue
+    }
+
+    const stringValue = (rowValue ?? '').toString().toLowerCase().trim()
+    const stringFilterValue = String(filterValue).toLowerCase().trim()
+    return stringValue > stringFilterValue
+  },
+  { resolveFilterValue: (val: any) => testFalsy(val) },
+)
+
+/**
+ * Keeps rows whose value is greater than or equal to the filter value.
+ *
+ * Delegates to the built-in greater-than and equality comparisons.
+ */
+export const filterFn_greaterThanOrEqualTo = Object.assign(
+  <TFeatures extends TableFeatures, TData extends RowData>(
+    row: Row<TFeatures, TData>,
+    columnId: string,
+    filterValue: unknown,
+  ) => {
+    return (
+      filterFn_greaterThan(row, columnId, filterValue) ||
+      filterFn_equals(row, columnId, filterValue)
+    )
+  },
+  { resolveFilterValue: (val: any) => testFalsy(val) },
+)
+
+/**
+ * Keeps rows whose value is less than the filter value.
+ *
+ * This is implemented as the inverse of greater-than-or-equal comparison.
+ */
+export const filterFn_lessThan = Object.assign(
+  <TFeatures extends TableFeatures, TData extends RowData>(
+    row: Row<TFeatures, TData>,
+    columnId: string,
+    filterValue: unknown,
+  ) => {
+    return !filterFn_greaterThanOrEqualTo(row, columnId, filterValue)
+  },
+  { resolveFilterValue: (val: any) => testFalsy(val) },
+)
+
+/**
+ * Keeps rows whose value is less than or equal to the filter value.
+ *
+ * This is implemented as the inverse of greater-than comparison.
+ */
+export const filterFn_lessThanOrEqualTo = Object.assign(
+  <TFeatures extends TableFeatures, TData extends RowData>(
+    row: Row<TFeatures, TData>,
+    columnId: string,
+    filterValue: unknown,
+  ) => {
+    return !filterFn_greaterThan(row, columnId, filterValue)
+  },
+  { resolveFilterValue: (val: any) => testFalsy(val) },
+)
+
+// Range filters
+
+/**
+ * Keeps rows whose value falls between an exclusive min/max pair.
+ *
+ * Blank range endpoints are treated as open-ended.
+ */
+const filterFn_between = Object.assign(
+  <TFeatures extends TableFeatures, TData extends RowData>(
+    row: Row<TFeatures, TData>,
+    columnId: string,
+    filterValues: [unknown, unknown],
+  ): boolean =>
+    ((['', undefined] as Array<any>).includes(filterValues[0]) ||
+      filterFn_greaterThan(row, columnId, filterValues[0])) &&
+    ((!isNaN(Number(filterValues[0])) &&
+      !isNaN(Number(filterValues[1])) &&
+      Number(filterValues[0]) > Number(filterValues[1])) ||
+      (['', undefined] as Array<any>).includes(filterValues[1]) ||
+      filterFn_lessThan(row, columnId, filterValues[1])),
+  { autoRemove: (val: any) => !val },
+)
+
+/**
+ * Keeps rows whose value falls between an inclusive min/max pair.
+ *
+ * Blank range endpoints are treated as open-ended.
+ */
+const filterFn_betweenInclusive = Object.assign(
+  <TFeatures extends TableFeatures, TData extends RowData>(
+    row: Row<TFeatures, TData>,
+    columnId: string,
+    filterValues: [unknown, unknown],
+  ): boolean =>
+    ((['', undefined] as Array<any>).includes(filterValues[0]) ||
+      filterFn_greaterThanOrEqualTo(row, columnId, filterValues[0])) &&
+    ((!isNaN(Number(filterValues[0])) &&
+      !isNaN(Number(filterValues[1])) &&
+      Number(filterValues[0]) > Number(filterValues[1])) ||
+      (['', undefined] as Array<any>).includes(filterValues[1]) ||
+      filterFn_lessThanOrEqualTo(row, columnId, filterValues[1])),
+  { autoRemove: (val: any) => !val },
+)
+
+/**
+ * Keeps rows whose numeric value is inside an inclusive `[min, max]` range.
+ *
+ * Filter values are normalized so blank endpoints become open-ended and
+ * reversed endpoints are swapped.
+ */
+export const filterFn_inNumberRange = Object.assign(
+  <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
+  },
+  {
+    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
+    },
+    autoRemove: (val: any) =>
+      testFalsy(val) || (testFalsy(val[0]) && testFalsy(val[1])),
+  },
+)
+
+// Array filters
+
+/**
+ * Keeps rows whose scalar column value equals at least one filter value.
+ */
+export const filterFn_arrHas = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: Array<unknown>,
+) => {
+  return filterValue.some((val) => row.getValue<unknown>(columnId) === val)
+}
+
+/**
+ * Keeps rows whose array or string column value includes at least one filter value.
+ */
+export const filterFn_arrIncludes = Object.assign(
+  <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,
+      ),
+    )
+  },
+  { autoRemove: (val: any) => testFalsy(val) || !val?.length },
+)
+
+/**
+ * Keeps rows whose array column value includes every filter value.
+ */
+export const filterFn_arrIncludesAll = Object.assign(
+  <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))
+  },
+  { autoRemove: (val: any) => testFalsy(val) || !val?.length },
+)
+
+/**
+ * Keeps rows whose array column value includes at least one filter value.
+ */
+export const filterFn_arrIncludesSome = Object.assign(
+  <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))
+  },
+  { autoRemove: (val: any) => testFalsy(val) || !val?.length },
+)
+
+// Export
+
+/**
+ * The built-in filter function registry.
+ *
+ * Pass this object to filtered row model creation or extend it with custom filter functions.
+ */
+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 === ''
+}