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

package/src/types/type-utils.ts

@@ -0,0 +1,84 @@
+export type Updater<T> = T | ((old: T) => T)
+
+export type OnChangeFn<T> = (updaterOrValue: Updater<T>) => void
+
+export type RowData = Record<string, any> | Array<any>
+
+export type CellData = unknown
+
+export type PartialKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
+
+export type RequiredKeys<T, K extends keyof T> = Omit<T, K> &
+  Required<Pick<T, K>>
+
+export type UnionToIntersection<T> = (
+  T extends any ? (x: T) => any : never
+) extends (x: infer R) => any
+  ? R
+  : never
+
+type ComputeRange<
+  N extends number,
+  Result extends Array<unknown> = [],
+> = Result['length'] extends N
+  ? Result
+  : ComputeRange<N, [...Result, Result['length']]>
+
+type Index40 = ComputeRange<40>[number]
+
+// Is this type a tuple?
+type IsTuple<T> = T extends ReadonlyArray<any> & { length: infer Length }
+  ? Length extends Index40
+    ? T
+    : never
+  : never
+
+// If this type is a tuple, what indices are allowed?
+type AllowedIndexes<
+  Tuple extends ReadonlyArray<any>,
+  Keys extends number = never,
+> = Tuple extends readonly []
+  ? Keys
+  : Tuple extends readonly [infer _, ...infer Tail]
+    ? AllowedIndexes<Tail, Keys | Tail['length']>
+    : Keys
+
+export type DeepKeys<
+  T,
+  TDepth extends Array<any> = [],
+> = TDepth['length'] extends 5
+  ? never
+  : unknown extends T
+    ? string
+    : T extends ReadonlyArray<any> & IsTuple<T>
+      ? AllowedIndexes<T> | DeepKeysPrefix<T, AllowedIndexes<T>, TDepth>
+      : T extends Array<any>
+        ? DeepKeys<T[number], [...TDepth, any]>
+        : T extends Date
+          ? never
+          : T extends object
+            ? (keyof T & string) | DeepKeysPrefix<T, keyof T, TDepth>
+            : never
+
+type DeepKeysPrefix<
+  T,
+  TPrefix,
+  TDepth extends Array<any>,
+> = TPrefix extends keyof T & (number | string)
+  ? `${TPrefix}.${DeepKeys<T[TPrefix], [...TDepth, any]> & string}`
+  : never
+
+export type DeepValue<T, TProp> =
+  T extends Record<string | number, any>
+    ? TProp extends `${infer TBranch}.${infer TDeepProp}`
+      ? DeepValue<T[TBranch], TDeepProp>
+      : T[TProp & string]
+    : never
+
+export type NoInfer<T> = [T][T extends any ? 0 : never]
+
+export type Getter<TValue> = <TTValue = TValue>() => NoInfer<TTValue>
+
+export type Prettify<T> = {
+  [K in keyof T]: T[K]
+} & unknown

package/src/utils.ts

@@ -1,128 +1,91 @@
-import { TableOptionsResolved, TableState, Updater } from './types'
-
-export type PartialKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
-export type RequiredKeys<T, K extends keyof T> = Omit<T, K> &
-  Required<Pick<T, K>>
-export type Overwrite<T, U extends { [TKey in keyof T]?: any }> = Omit<
-  T,
-  keyof U
-> &
-  U
-
-export type UnionToIntersection<T> = (
-  T extends any ? (x: T) => any : never
-) extends (x: infer R) => any
-  ? R
-  : never
-
-export type IsAny<T, Y, N> = 1 extends 0 & T ? Y : N
-export type IsKnown<T, Y, N> = unknown extends T ? N : Y
-
-type ComputeRange<
-  N extends number,
-  Result extends Array<unknown> = [],
-> = Result['length'] extends N
-  ? Result
-  : ComputeRange<N, [...Result, Result['length']]>
-type Index40 = ComputeRange<40>[number]
-
-// Is this type a tuple?
-type IsTuple<T> = T extends readonly any[] & { length: infer Length }
-  ? Length extends Index40
-    ? T
-    : never
-  : never
-
-// If this type is a tuple, what indices are allowed?
-type AllowedIndexes<
-  Tuple extends ReadonlyArray<any>,
-  Keys extends number = never,
-> = Tuple extends readonly []
-  ? Keys
-  : Tuple extends readonly [infer _, ...infer Tail]
-    ? AllowedIndexes<Tail, Keys | Tail['length']>
-    : Keys
-
-export type DeepKeys<T, TDepth extends any[] = []> = TDepth['length'] extends 5
-  ? never
-  : unknown extends T
-    ? string
-    : T extends readonly any[] & IsTuple<T>
-      ? AllowedIndexes<T> | DeepKeysPrefix<T, AllowedIndexes<T>, TDepth>
-      : T extends any[]
-        ? DeepKeys<T[number], [...TDepth, any]>
-        : T extends Date
-          ? never
-          : T extends object
-            ? (keyof T & string) | DeepKeysPrefix<T, keyof T, TDepth>
-            : never
-
-type DeepKeysPrefix<
-  T,
-  TPrefix,
-  TDepth extends any[],
-> = TPrefix extends keyof T & (number | string)
-  ? `${TPrefix}.${DeepKeys<T[TPrefix], [...TDepth, any]> & string}`
-  : never
-
-export type DeepValue<T, TProp> =
-  T extends Record<string | number, any>
-    ? TProp extends `${infer TBranch}.${infer TDeepProp}`
-      ? DeepValue<T[TBranch], TDeepProp>
-      : T[TProp & string]
-    : never
-
-export type NoInfer<T> = [T][T extends any ? 0 : never]
-
-export type Getter<TValue> = <TTValue = TValue>() => NoInfer<TTValue>
-
-///
-
+import type { Table, Table_Internal } from './types/Table'
+import type { NoInfer, RowData, Updater } from './types/type-utils'
+import type { TableFeatures } from './types/TableFeatures'
+import type { TableState, TableState_All } from './types/TableState'
+
+/**
+ * Applies a TanStack updater to a value.
+ *
+ * If the updater is a function it is called with the previous value; otherwise the updater value is returned directly.
+ */
 export function functionalUpdate<T>(updater: Updater<T>, input: T): T {
   return typeof updater === 'function'
-    ? (updater as (input: T) => T)(input)
+    ? (updater as (i: T) => T)(input)
     : updater
 }
 
-export function noop() {
-  //
+/**
+ * Clones table state values while preserving non-plain objects.
+ *
+ * Plain objects and arrays are copied recursively so state updates can avoid mutating existing references.
+ */
+export function cloneState<T>(value: T): T {
+  if (Array.isArray(value)) {
+    return value.map(cloneState) as T
+  }
+
+  if (value && typeof value === 'object') {
+    const proto = Object.getPrototypeOf(value)
+
+    if (proto !== Object.prototype && proto !== null) {
+      return value
+    }
+
+    const copy: Record<string, unknown> = {}
+    const keys = Object.keys(value)
+
+    for (let i = 0; i < keys.length; i++) {
+      const key = keys[i]!
+      copy[key] = cloneState((value as Record<string, unknown>)[key])
+    }
+
+    return copy as T
+  }
+
+  return value
 }
 
-export function makeStateUpdater<K extends keyof TableState>(
-  key: K,
-  instance: unknown
-) {
-  return (updater: Updater<TableState[K]>) => {
-    ;(instance as any).setState(<TTableState>(old: TTableState) => {
-      return {
-        ...old,
-        [key]: functionalUpdate(updater, (old as any)[key]),
-      }
-    })
+/**
+ * Creates a table state updater for a single state slice.
+ *
+ * The updater writes through the table base atom for the slice and supports both value and functional updater forms.
+ */
+export function makeStateUpdater<
+  TFeatures extends TableFeatures,
+  K extends (string & {}) | keyof TableState_All | keyof TableState<TFeatures>,
+>(key: K, instance: Table<TFeatures, any>) {
+  return (updater: Updater<TableState<any>[K & keyof TableState<any>]>) => {
+    const externalAtom = (instance.options as any).atoms?.[key]
+    const targetAtom = externalAtom ?? (instance.baseAtoms as any)[key]
+    targetAtom.set((old: any) => functionalUpdate(updater, old))
   }
 }
 
 type AnyFunction = (...args: any) => any
 
+/**
+ * Returns whether a value is a function.
+ */
 export function isFunction<T extends AnyFunction>(d: any): d is T {
   return d instanceof Function
 }
 
-export function isNumberArray(d: any): d is number[] {
-  return Array.isArray(d) && d.every(val => typeof val === 'number')
-}
-
+/**
+ * Flattens a tree of nodes by recursively reading child nodes.
+ *
+ * The original nodes are preserved in depth-first order.
+ */
 export function flattenBy<TNode>(
-  arr: TNode[],
-  getChildren: (item: TNode) => TNode[]
+  arr: Array<TNode>,
+  getChildren: (item: TNode) => Array<TNode>,
 ) {
-  const flat: TNode[] = []
+  const flat: Array<TNode> = []
 
-  const recurse = (subArr: TNode[]) => {
-    subArr.forEach(item => {
+  const recurse = (subArr: Array<TNode>) => {
+    subArr.forEach((item) => {
       flat.push(item)
       const children = getChildren(item)
-      if (children?.length) {
+      if (children.length) {
         recurse(children)
       }
     })
@@ -133,27 +96,46 @@ export function flattenBy<TNode>(
   return flat
 }
 
-export function memo<TDeps extends readonly any[], TDepArgs, TResult>(
-  getDeps: (depArgs?: TDepArgs) => [...TDeps],
-  fn: (...args: NoInfer<[...TDeps]>) => TResult,
-  opts: {
-    key: any
-    debug?: () => any
-    onChange?: (result: TResult) => void
-  }
-): (depArgs?: TDepArgs) => TResult {
-  let deps: any[] = []
-  let result: TResult | undefined
-
-  return depArgs => {
-    let depTime: number
-    if (opts.key && opts.debug) depTime = Date.now()
+interface MemoOptions<TDeps extends ReadonlyArray<any>, TDepArgs, TResult> {
+  fn: (...args: NoInfer<TDeps>) => TResult
+  memoDeps?: (depArgs?: TDepArgs) => [...TDeps] | undefined
+  onAfterCompare?: (depsChanged: boolean) => void
+  onAfterUpdate?: (result: TResult) => void
+  onBeforeCompare?: () => void
+  onBeforeUpdate?: () => void
+}
 
-    const newDeps = getDeps(depArgs)
+/**
+ * Creates a dependency-tracked memoized function for table internals.
+ *
+ * The memo recomputes only when its dependency tuple changes and can emit debug timing information.
+ */
+export const memo = <TDeps extends ReadonlyArray<any>, TDepArgs, TResult>({
+  fn,
+  memoDeps,
+  onAfterCompare,
+  onAfterUpdate,
+  onBeforeCompare,
+  onBeforeUpdate,
+}: MemoOptions<TDeps, TDepArgs, TResult>): ((
+  depArgs?: TDepArgs,
+) => TResult) => {
+  let deps: Array<any> | undefined = []
+  let result: TResult | undefined
 
-    const depsChanged =
-      newDeps.length !== deps.length ||
-      newDeps.some((dep: any, index: number) => deps[index] !== dep)
+  const memoizedFn = (depArgs?: TDepArgs): TResult => {
+    onBeforeCompare?.()
+    const newDeps = memoDeps?.(depArgs)
+    let depsChanged = !newDeps || newDeps.length !== deps?.length
+    if (!depsChanged && newDeps) {
+      for (let i = 0; i < newDeps.length; i++) {
+        if (newDeps[i] !== deps![i]) {
+          depsChanged = true
+          break
+        }
+      }
+    }
+    onAfterCompare?.(depsChanged)
 
     if (!depsChanged) {
       return result!
@@ -161,59 +143,299 @@ export function memo<TDeps extends readonly any[], TDepArgs, TResult>(
 
     deps = newDeps
 
-    let resultTime: number
-    if (opts.key && opts.debug) resultTime = Date.now()
+    onBeforeUpdate?.()
+    result = fn(...(newDeps ?? ([] as any)))
+    onAfterUpdate?.(result)
 
-    result = fn(...newDeps)
-    opts?.onChange?.(result)
+    return result
+  }
 
-    if (opts.key && opts.debug) {
-      if (opts?.debug()) {
-        const depEndTime = Math.round((Date.now() - depTime!) * 100) / 100
-        const resultEndTime = Math.round((Date.now() - resultTime!) * 100) / 100
-        const resultFpsPercentage = resultEndTime / 16
+  return memoizedFn
+}
 
-        const pad = (str: number | string, num: number) => {
-          str = String(str)
-          while (str.length < num) {
-            str = ' ' + str
-          }
-          return str
-        }
+interface TableMemoOptions<
+  TFeatures extends TableFeatures,
+  TDeps extends ReadonlyArray<any>,
+  TDepArgs,
+  TResult,
+> extends MemoOptions<TDeps, TDepArgs, TResult> {
+  feature?: keyof TFeatures & string
+  fnName: string
+  objectId?: string
+  onAfterUpdate?: () => void
+  table: Table_Internal<TFeatures, any>
+}
 
-        console.info(
-          `%c⏱ ${pad(resultEndTime, 5)} /${pad(depEndTime, 5)} ms`,
-          `
-            font-size: .6rem;
-            font-weight: bold;
-            color: hsl(${Math.max(
-              0,
-              Math.min(120 - 120 * resultFpsPercentage, 120)
-            )}deg 100% 31%);`,
-          opts?.key
-        )
-      }
+const pad = (str: number | string, num: number) => {
+  str = String(str)
+  while (str.length < num) {
+    str = ' ' + str
+  }
+  return str
+}
+
+/**
+ * Creates a table-aware memoized function.
+ *
+ * This wraps `memo` with table debug options and feature metadata so row models and derived APIs can share consistent diagnostics.
+ */
+export function tableMemo<
+  TFeatures extends TableFeatures,
+  TDeps extends ReadonlyArray<any>,
+  TDepArgs,
+  TResult,
+>({
+  feature,
+  fnName,
+  objectId,
+  onAfterUpdate,
+  table,
+  ...memoOptions
+}: TableMemoOptions<TFeatures, TDeps, TDepArgs, TResult>) {
+  let beforeCompareTime: number
+  let afterCompareTime: number
+  let startCalcTime: number
+  let endCalcTime: number
+  let runCount = 0
+  let debug: boolean | undefined
+  let debugCache: boolean | undefined
+
+  if (process.env.NODE_ENV === 'development') {
+    const { debugCache: _debugCache, debugAll } = table.options
+    debugCache = _debugCache
+    const { parentName } = getFunctionNameInfo(fnName, '.')
+
+    const debugByParent =
+      // @ts-expect-error
+      table.options[
+        `debug${(parentName != 'table' ? parentName + 's' : parentName).replace(
+          parentName,
+          parentName.charAt(0).toUpperCase() + parentName.slice(1),
+        )}`
+      ]
+    const debugByFeature = feature
+      ? // @ts-expect-error
+        table.options[
+          `debug${feature.charAt(0).toUpperCase() + feature.slice(1)}`
+        ]
+      : false
+
+    debug = debugAll || debugByParent || debugByFeature
+  }
+
+  function logTime(time: number, depsChanged: boolean) {
+    const runType =
+      runCount === 0
+        ? '(1st run)'
+        : depsChanged
+          ? '(rerun #' + runCount + ')'
+          : '(cache)'
+    runCount++
+
+    console.groupCollapsed(
+      `%c⏱ ${pad(`${time.toFixed(1)} ms`, 12)} %c${runType}%c ${fnName}%c ${objectId ? `(${fnName.split('.')[0]}Id: ${objectId})` : ''}`,
+      `font-size: .6rem; font-weight: bold; ${
+        depsChanged
+          ? `color: hsl(
+        ${Math.max(0, Math.min(120 - Math.log10(time) * 60, 120))}deg 100% 31%);`
+          : ''
+      } `,
+      `color: ${runCount < 2 ? '#FF00FF' : '#FF1493'}`,
+      'color: #666',
+      'color: #87CEEB',
+    )
+    console.info({
+      feature,
+      state: table.store.state,
+      deps: memoOptions.memoDeps?.toString(),
+    })
+    console.trace()
+    console.groupEnd()
+  }
+
+  const onAfterUpdateHandler = () => {
+    if (!onAfterUpdate) {
+      return
     }
 
-    return result!
+    const { schedule, untrack } = table._reactivity
+    schedule(() => untrack(() => onAfterUpdate()))
   }
+
+  const debugOptions =
+    process.env.NODE_ENV === 'development'
+      ? {
+          onBeforeCompare: () => {
+            if (debugCache) {
+              beforeCompareTime = performance.now()
+            }
+          },
+          onAfterCompare: (depsChanged: boolean) => {
+            if (debugCache) {
+              afterCompareTime = performance.now()
+              const compareTime =
+                Math.round((afterCompareTime - beforeCompareTime) * 100) / 100
+              if (!depsChanged) {
+                logTime(compareTime, depsChanged)
+              }
+            }
+          },
+          onBeforeUpdate: () => {
+            if (debug) {
+              startCalcTime = performance.now()
+            }
+          },
+          onAfterUpdate: () => {
+            if (debug) {
+              endCalcTime = performance.now()
+              const executionTime =
+                Math.round((endCalcTime - startCalcTime) * 100) / 100
+              logTime(executionTime, true)
+            }
+            onAfterUpdateHandler()
+          },
+        }
+      : {
+          onAfterUpdate: () => {
+            onAfterUpdateHandler()
+          },
+        }
+
+  return memo({
+    ...memoOptions,
+    ...debugOptions,
+  })
+}
+
+export interface API<TDeps extends ReadonlyArray<any>, TDepArgs> {
+  fn: (...args: any) => any
+  memoDeps?: (depArgs?: any) => [...any] | undefined
 }
 
-export function getMemoOptions(
-  tableOptions: Partial<TableOptionsResolved<any>>,
-  debugLevel:
-    | 'debugAll'
-    | 'debugCells'
-    | 'debugTable'
-    | 'debugColumns'
-    | 'debugRows'
-    | 'debugHeaders',
-  key: string,
-  onChange?: (result: any) => void
+export type APIObject<TDeps extends ReadonlyArray<any>, TDepArgs> = Record<
+  string,
+  API<TDeps, TDepArgs>
+>
+
+/**
+ * Assumes that a function name is in the format of `parentName_fnKey` and returns the `fnKey` and `fnName` in the format of `parentName.fnKey`.
+ */
+export function getFunctionNameInfo(
+  staticFnName: string,
+  splitBy: '_' | '.' = '_',
 ) {
-  return {
-    debug: () => tableOptions?.debugAll ?? tableOptions[debugLevel],
-    key: process.env.NODE_ENV === 'development' && key,
-    onChange,
+  const [parentName, fnKey] = staticFnName.split(splitBy)
+  const fnName = `${parentName}.${fnKey}`
+  return { fnKey, fnName, parentName } as {
+    fnKey: string
+    fnName: string
+    parentName: string
   }
 }
+
+/**
+ * Assigns Table API methods directly to the table instance.
+ * Unlike row/cell/column/header, the table is a singleton so methods are assigned directly.
+ */
+export function assignTableAPIs<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TDeps extends ReadonlyArray<any>,
+  TDepArgs,
+>(
+  feature: keyof TFeatures & string,
+  table: Table_Internal<TFeatures, TData>,
+  apis: APIObject<TDeps, NoInfer<TDepArgs>>,
+): void {
+  for (const [staticFnName, { fn, memoDeps }] of Object.entries(apis)) {
+    const { fnKey, fnName } = getFunctionNameInfo(staticFnName)
+
+    ;(table as Record<string, any>)[fnKey] = memoDeps
+      ? tableMemo({
+          memoDeps,
+          fn,
+          fnName,
+          table,
+          feature,
+        })
+      : fn
+  }
+}
+
+export interface PrototypeAPI<TDeps extends ReadonlyArray<any>, TDepArgs> {
+  fn: (self: any, ...args: any) => any
+  memoDeps?: (self: any, depArgs?: any) => [...any] | undefined
+}
+
+export type PrototypeAPIObject<
+  TDeps extends ReadonlyArray<any>,
+  TDepArgs,
+> = Record<string, PrototypeAPI<TDeps, TDepArgs>>
+
+/**
+ * Assigns API methods to a prototype object for memory-efficient method sharing.
+ * All instances created with this prototype will share the same method references.
+ *
+ * For memoized methods, the memo state is lazily created and stored on each instance.
+ * This provides the best of both worlds: shared method code + per-instance caching.
+ */
+export function assignPrototypeAPIs<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TDeps extends ReadonlyArray<any>,
+  TDepArgs,
+>(
+  feature: keyof TFeatures & string,
+  prototype: Record<string, any>,
+  table: Table_Internal<TFeatures, TData>,
+  apis: PrototypeAPIObject<TDeps, NoInfer<TDepArgs>>,
+): void {
+  for (const [staticFnName, { fn, memoDeps }] of Object.entries(apis)) {
+    const { fnKey, fnName } = getFunctionNameInfo(staticFnName)
+
+    if (memoDeps) {
+      // For memoized methods, create a function that lazily initializes
+      // the memo on first access and stores it on the instance
+      const memoKey = `_memo_${fnKey}`
+
+      prototype[fnKey] = function (this: any, ...args: Array<any>) {
+        // Lazily create memo on first access for this instance
+        if (!this[memoKey]) {
+          const self = this
+          this[memoKey] = tableMemo({
+            memoDeps: (depArgs) => memoDeps(self, depArgs),
+            fn: (...deps) => fn(self, ...deps),
+            fnName,
+            objectId: self.id,
+            table,
+            feature,
+          })
+        }
+        return this[memoKey](...args)
+      }
+    } else {
+      // Non-memoized methods just call the static function with `this`
+      prototype[fnKey] = function (this: any, ...args: Array<any>) {
+        return fn(this, ...args)
+      }
+    }
+  }
+}
+
+/**
+ * Looks to run the memoized function with the builder pattern on the object if it exists, otherwise fallback to the static method passed in.
+ */
+export function callMemoOrStaticFn<
+  TObject extends Record<string, any>,
+  TArgs extends Array<any>,
+  TReturn,
+>(
+  obj: TObject,
+  fnKey: string,
+  staticFn: (obj: TObject, ...args: TArgs) => TReturn,
+  ...args: TArgs
+): TReturn {
+  return (
+    (obj[fnKey] as Function | undefined)?.(...args) ?? staticFn(obj, ...args)
+  )
+}