@tanstack/angular-table 9.0.0-alpha.10 → 9.0.0-alpha.12

package/src/helpers/table.ts

@@ -0,0 +1,87 @@
+import { Directive, InjectionToken, inject, input } from '@angular/core'
+import { RowData, TableFeatures, TableState } from '@tanstack/table-core'
+import { AngularTable } from '../injectTable'
+import type { Signal } from '@angular/core'
+
+/**
+ * Injection token that provides access to the current {@link AngularTable} instance.
+ *
+ * This token is provided by the {@link TanStackTable} directive.
+ */
+export const TanStackTableToken = new InjectionToken<
+  Signal<AngularTable<any, any>>
+>('[TanStack Table] Table Context')
+
+/**
+ * Provides a TanStack Table instance (`AngularTable`) in Angular DI.
+ *
+ * The table can be injected by:
+ * - any descendant of an element using `[tanStackTable]="..."`
+ * - any component instantiated by `*flexRender` when the render props contains `table`
+ *
+ * @example
+ * ```html
+ * <div [tanStackTable]="table">
+ *   <app-pagination />
+ * </div>
+ * ```
+ *
+ * ```ts
+ * @Component({
+ *   selector: 'app-pagination',
+ *   template: `
+ *     <button (click)="prev()" [disabled]="!table().getCanPreviousPage()">Prev</button>
+ *     <button (click)="next()" [disabled]="!table().getCanNextPage()">Next</button>
+ *   `,
+ * })
+ * export class PaginationComponent {
+ *   readonly table = injectTableContext()
+ *
+ *   prev() {
+ *     this.table().previousPage()
+ *   }
+ *   next() {
+ *     this.table().nextPage()
+ *   }
+ * }
+ * ```
+ */
+@Directive({
+  selector: '[tanStackTable]',
+  exportAs: 'table',
+  providers: [
+    {
+      provide: TanStackTableToken,
+      useFactory: () => inject(TanStackTable).table,
+    },
+  ],
+})
+export class TanStackTable<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSelected extends {} = TableState<TFeatures>,
+> {
+  /**
+   * The current TanStack Table instance.
+   *
+   * Provided as a required signal input so DI consumers always read the latest value.
+   */
+  readonly table = input.required<AngularTable<TFeatures, TData, TSelected>>({
+    alias: 'tanStackTable',
+  })
+}
+
+/**
+ * Injects the current TanStack Table instance signal.
+ *
+ * Available when:
+ * - there is a nearest `[tanStackTable]` directive in the DI tree, or
+ * - the caller is rendered via `*flexRender` with render props containing `table`
+ */
+export function injectTableContext<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSelected extends {} = TableState<TFeatures>,
+>(): Signal<AngularTable<TFeatures, TData, TSelected>> {
+  return inject(TanStackTableToken)
+}

package/src/index.ts

@@ -1,73 +1,25 @@
-import { computed, type Signal, signal } from '@angular/core'
-import {
-  RowData,
-  TableOptions,
-  TableOptionsResolved,
-  TableState,
-  _createTable,
-  type Table,
-} from '@tanstack/table-core'
-import { lazyInit } from './lazy-signal-initializer'
-import { proxifyTable } from './proxy'
+import { FlexRenderCell } from './helpers/flexRenderCell'
+import { FlexRenderDirective } from './flexRender'
 
 export * from '@tanstack/table-core'
 
-export {
-  type FlexRenderContent,
-  FlexRenderComponent,
-  FlexRenderDirective,
-  injectFlexRenderContext,
-} from './flex-render'
-
-export function injectTable<TData extends RowData>(
-  options: () => TableOptions<TData>
-): Table<TData> & Signal<Table<TData>> {
-  return lazyInit(() => {
-    const resolvedOptions = {
-      state: {},
-      onStateChange: () => {},
-      renderFallbackValue: null,
-      ...options(),
-    }
-
-    const table = _createTable(resolvedOptions)
-
-    // By default, manage table state here using the table's initial state
-    const state = signal<TableState>(table.initialState)
-
-    // Compose table options using computed.
-    // This is to allow `tableSignal` to listen and set table option
-    const updatedOptions = computed<TableOptionsResolved<TData>>(() => {
-      // listen to table state changed
-      const tableState = state()
-      // listen to input options changed
-      const tableOptions = options()
-      return {
-        ...table.options,
-        ...resolvedOptions,
-        ...tableOptions,
-        state: { ...tableState, ...tableOptions.state },
-        onStateChange: updater => {
-          const value =
-            updater instanceof Function ? updater(tableState) : updater
-          state.set(value)
-          resolvedOptions.onStateChange?.(updater)
-        },
-      }
-    })
-
-    // convert table instance to signal for proxify to listen to any table state and options changes
-    const tableSignal = computed(
-      () => {
-        table.setOptions(updatedOptions())
-        return table
-      },
-      {
-        equal: () => false,
-      }
-    )
-
-    // proxify Table instance to provide ability for consumer to listen to any table state changes
-    return proxifyTable(tableSignal)
-  })
-}
+export * from './angularReactivityFeature'
+export * from './flexRender'
+export * from './injectTable'
+export * from './flex-render/flexRenderComponent'
+
+export * from './helpers/cell'
+export * from './helpers/header'
+export * from './helpers/table'
+export * from './helpers/createTableHook'
+export * from './helpers/flexRenderCell'
+
+/**
+ * Constant helper to import FlexRender directives.
+ *
+ * You should prefer to use this constant over importing the directives separately,
+ * as it ensures you always have the correct set of directives over library updates.
+ *
+ * @see {@link FlexRenderDirective} and {@link FlexRenderCell} for more details on the directives included in this export.
+ */
+export const FlexRender = [FlexRenderDirective, FlexRenderCell] as const

package/src/injectTable.ts

@@ -0,0 +1,170 @@
+import {
+  Injector,
+  assertInInjectionContext,
+  computed,
+  inject,
+  untracked,
+} from '@angular/core'
+import { constructTable } from '@tanstack/table-core'
+import { injectStore } from '@tanstack/angular-store'
+import { lazyInit } from './lazySignalInitializer'
+import { angularReactivityFeature } from './angularReactivityFeature'
+import type {
+  RowData,
+  Table,
+  TableFeatures,
+  TableOptions,
+  TableState,
+} from '@tanstack/table-core'
+import type { Signal, ValueEqualityFn } from '@angular/core'
+
+export type AngularTable<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSelected = TableState<TFeatures>,
+> = Table<TFeatures, TData> & {
+  /**
+   * The selected state from the table store, based on the selector provided.
+   */
+  readonly state: Signal<Readonly<TSelected>>
+  /**
+   * Subscribe to changes in the table store with a custom selector.
+   */
+  Subscribe: <TSubSelected = {}>(props: {
+    selector: (state: TableState<TFeatures>) => TSubSelected
+    equal?: ValueEqualityFn<TSubSelected>
+  }) => Signal<Readonly<TSubSelected>>
+}
+
+/**
+ * Creates and returns an Angular-reactive table instance.
+ *
+ * The initializer is intentionally re-evaluated whenever any signal read inside it changes.
+ * This is how the adapter keeps the table in sync with Angular's reactivity model.
+ *
+ * Because of that behavior, keep expensive/static values (for example `columns`, feature setup, row models)
+ * as stable references outside the initializer, and only read reactive state (`data()`, pagination/filter/sorting signals, etc.)
+ * inside it.
+ *
+ * The returned table is also signal-reactive: table state and table APIs are wired for Angular signals, so you can safely consume table methods inside `computed(...)` and `effect(...)`.
+ *
+ * @example
+ * 1. Register the table features you need
+ * ```ts
+ * // Register only the features you need
+ * import {tableFeatures, rowPaginationFeature} from '@tanstack/angular-table';
+ * const _features = tableFeatures({
+ *  rowPaginationFeature,
+ *  // ...all other features you need
+ * })
+ *
+ * // Use all table core features
+ * import {stockFeatures} from '@tanstack/angular-table';
+ * const _features = tableFeatures(stockFeatures);
+ * ```
+ * 2. Prepare the table columns
+ * ```ts
+ * import {ColumnDef} from '@tanstack/angular-table';
+ *
+ * type MyData = {}
+ *
+ * const columns: ColumnDef<typeof _features, MyData>[] = [
+ *   // ...column definitions
+ * ]
+ *
+ * // or using createColumnHelper
+ * import {createColumnHelper} from '@tanstack/angular-table';
+ * const columnHelper = createColumnHelper<typeof _features, MyData>();
+ * const columns = columnHelper.columns([
+ *  columnHelper.accessor(...),
+ *  // ...other columns
+ * ])
+ * ```
+ * 3. Create the table instance with `injectTable`
+ * ```ts
+ * const table = injectTable(() => {
+ *   // ...table options,
+ *   _features,
+ *   columns: columns,
+ *   data: myDataSignal(),
+ * })
+ * ```
+ *
+ * @returns An Angular-reactive TanStack Table instance.
+ */
+export function injectTable<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSelected = TableState<TFeatures>,
+>(
+  options: () => TableOptions<TFeatures, TData>,
+  selector: (state: TableState<TFeatures>) => TSelected = (state) =>
+    state as TSelected,
+): AngularTable<TFeatures, TData, TSelected> {
+  assertInInjectionContext(injectTable)
+  const injector = inject(Injector)
+
+  return lazyInit(() => {
+    const resolvedOptions: TableOptions<TFeatures, TData> = {
+      ...options(),
+      _features: {
+        ...options()._features,
+        angularReactivityFeature,
+      },
+    } as TableOptions<TFeatures, TData>
+
+    const table: AngularTable<TFeatures, TData, TSelected> = constructTable(
+      resolvedOptions,
+    ) as AngularTable<TFeatures, TData, TSelected>
+
+    const updatedOptions = computed<TableOptions<TFeatures, TData>>(() => {
+      const tableOptionsValue = options()
+      const result: TableOptions<TFeatures, TData> = {
+        ...table.options,
+        ...tableOptionsValue,
+        _features: {
+          ...tableOptionsValue._features,
+          angularReactivityFeature,
+        },
+      }
+      if (tableOptionsValue.state) {
+        result.state = tableOptionsValue.state
+      }
+      return result
+    })
+
+    const tableState = injectStore(
+      table.store,
+      (state: TableState<TFeatures>) => state,
+      { injector },
+    )
+
+    const tableSignalNotifier = computed(
+      () => {
+        tableState()
+        table.setOptions(updatedOptions())
+        untracked(() => table.baseStore.setState((prev) => ({ ...prev })))
+        return table
+      },
+      { equal: () => false },
+    )
+
+    table.setTableNotifier(tableSignalNotifier)
+
+    table.Subscribe = function Subscribe<TSubSelected = {}>(props: {
+      selector: (state: TableState<TFeatures>) => TSubSelected
+      equal?: ValueEqualityFn<TSubSelected>
+    }) {
+      return injectStore(table.store, props.selector, {
+        injector,
+        equal: props.equal,
+      })
+    }
+
+    Object.defineProperty(table, 'state', {
+      value: injectStore(table.store, selector, { injector }),
+    })
+
+    return table
+  })
+}

package/src/{lazy-signal-initializer.ts → lazySignalInitializer.ts}

@@ -2,7 +2,7 @@ import { untracked } from '@angular/core'
 
 /**
  * Implementation from @tanstack/angular-query
- * {@link https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/util/lazy-init/lazy-init.ts}
+ * {https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/util/lazy-init/lazy-init.ts}
  */
 export function lazyInit<T extends object>(initializer: () => T): T {
   let object: T | null = null
@@ -18,7 +18,7 @@ export function lazyInit<T extends object>(initializer: () => T): T {
   const table = () => {}
 
   return new Proxy<T>(table as T, {
-    apply(target: T, thisArg: any, argArray: any[]): any {
+    apply(target: T, thisArg: any, argArray: Array<any>): any {
       initializeObject()
       if (typeof object === 'function') {
         return Reflect.apply(object, thisArg, argArray)

package/src/reactivityUtils.ts

@@ -0,0 +1,232 @@
+import { computed, isSignal } from '@angular/core'
+import { $internalMemoFnMeta, getMemoFnMeta } from '@tanstack/table-core'
+import type { MemoFnMeta } from '@tanstack/table-core'
+import type { Signal } from '@angular/core'
+
+const $TABLE_REACTIVE = Symbol('reactive')
+
+function markReactive<T extends object>(obj: T): void {
+  Object.defineProperty(obj, $TABLE_REACTIVE, { value: true })
+}
+
+function isReactive<T>(obj: T): boolean {
+  return Reflect.get(obj as {}, $TABLE_REACTIVE) === true
+}
+
+/**
+ * Defines a lazy computed property on an object. The property is initialized
+ * with a getter that computes its value only when accessed for the first time.
+ * After the first access, the computed value is cached, and the getter is
+ * replaced with a direct property assignment for efficiency.
+ *
+ * @internal should be used only internally
+ */
+export function defineLazyComputedProperty<T extends object>(
+  notifier: Signal<T>,
+  setObjectOptions: {
+    originalObject: T
+    property: keyof T & string
+    valueFn: (...args: any) => any
+    overridePrototype?: boolean
+  },
+) {
+  const { originalObject, property, overridePrototype, valueFn } =
+    setObjectOptions
+
+  if (overridePrototype) {
+    assignReactivePrototypeAPI(notifier, originalObject, property)
+  } else {
+    Object.defineProperty(originalObject, property, {
+      enumerable: true,
+      configurable: true,
+      get() {
+        const computedValue = toComputed(notifier, valueFn, property)
+        markReactive(computedValue)
+        // Once the property is set the first time, we don't need a getter anymore
+        // since we have a computed / cached fn value
+        Object.defineProperty(originalObject, property, {
+          value: computedValue,
+          configurable: true,
+          enumerable: true,
+        })
+        return computedValue
+      },
+    })
+  }
+}
+
+/**
+ * @internal should be used only internally
+ */
+type ComputedFunction<T> = T extends () => infer TReturn
+  ? Signal<TReturn>
+  : // 1+ args
+    T extends (arg0?: any, ...args: Array<any>) => any
+    ? T
+    : never
+
+/**
+ * @description Transform a function into a computed that react to given notifier re-computations
+ *
+ * Here we'll handle all type of accessors:
+ * - 0 argument -> e.g. table.getCanNextPage())
+ * - 0~1 arguments -> e.g. table.getIsSomeRowsPinned(position?)
+ * - 1 required argument -> e.g. table.getColumn(columnId)
+ * - 1+ argument -> e.g. table.getRow(id, searchAll?)
+ *
+ * Since we are not able to detect automatically the accessors parameters,
+ * we'll wrap all accessors into a cached function wrapping a computed
+ * that return it's value based on the given parameters
+ *
+ * @internal should be used only internally
+ */
+export function toComputed<
+  T,
+  TReturn,
+  TFunction extends (...args: any) => TReturn,
+>(
+  notifier: Signal<T>,
+  fn: TFunction,
+  debugName: string,
+): ComputedFunction<TFunction> {
+  const hasArgs = getFnArgsLength(fn) > 0
+  if (!hasArgs) {
+    const computedFn = computed(
+      () => {
+        void notifier()
+        return fn()
+      },
+      { debugName },
+    )
+    Object.defineProperty(computedFn, 'name', { value: debugName })
+    markReactive(computedFn)
+    return computedFn as ComputedFunction<TFunction>
+  }
+
+  const computedFn: ((this: unknown, ...argsArray: Array<any>) => unknown) & {
+    _reactiveCache?: Record<string, Signal<unknown>>
+  } = function (this: unknown, ...argsArray: Array<any>) {
+    const cacheable =
+      argsArray.length === 0 ||
+      argsArray.every((arg) => {
+        return (
+          arg === null ||
+          arg === undefined ||
+          typeof arg === 'string' ||
+          typeof arg === 'number' ||
+          typeof arg === 'boolean' ||
+          typeof arg === 'symbol'
+        )
+      })
+    if (!cacheable) {
+      return fn.apply(this, argsArray)
+    }
+    const serializedArgs = serializeArgs(...argsArray)
+    if ((computedFn._reactiveCache ??= {})[serializedArgs]) {
+      return computedFn._reactiveCache[serializedArgs]()
+    }
+    const computedSignal = computed(
+      () => {
+        void notifier()
+        return fn.apply(this, argsArray)
+      },
+      { debugName },
+    )
+
+    computedFn._reactiveCache[serializedArgs] = computedSignal
+
+    return computedSignal()
+  }
+
+  Object.defineProperty(computedFn, 'name', { value: debugName })
+  markReactive(computedFn)
+
+  return computedFn as ComputedFunction<TFunction>
+}
+
+function serializeArgs(...args: Array<any>) {
+  return JSON.stringify(args)
+}
+
+function getFnArgsLength(
+  fn: ((...args: any) => any) & { originalArgsLength?: number },
+): number {
+  return Math.max(0, getMemoFnMeta(fn)?.originalArgsLength ?? fn.length)
+}
+
+function assignReactivePrototypeAPI(
+  notifier: Signal<unknown>,
+  prototype: Record<string, any>,
+  fnName: string,
+) {
+  if (isReactive(prototype[fnName])) return
+
+  const fn = prototype[fnName]
+  const originalArgsLength = getFnArgsLength(fn)
+
+  if (originalArgsLength <= 1) {
+    Object.defineProperty(prototype, fnName, {
+      enumerable: true,
+      configurable: true,
+      get(this) {
+        const self = this
+        // Create a cache in the current prototype to allow the signals
+        // to be garbage collected. Shorthand for a WeakMap implementation
+        self._reactiveCache ??= {}
+        const cached = (self._reactiveCache[`${self.id}${fnName}`] ??= computed(
+          () => {
+            notifier()
+            return fn.apply(self)
+          },
+          {},
+        ))
+        markReactive(cached)
+        cached[$internalMemoFnMeta] = {
+          originalArgsLength,
+        } satisfies MemoFnMeta
+        return cached
+      },
+    })
+  } else {
+    prototype[fnName] = function (this: unknown, ...args: Array<any>) {
+      notifier()
+      return fn.apply(this, args)
+    }
+    markReactive(prototype[fnName])
+    prototype[fnName][$internalMemoFnMeta] = {
+      originalArgsLength,
+    } satisfies MemoFnMeta
+  }
+}
+
+export function setReactivePropertiesOnObject<T extends object>(
+  notifier: Signal<T>,
+  obj: { [key: string]: any },
+  options: {
+    overridePrototype?: boolean
+    skipProperty: (property: string) => boolean
+  },
+) {
+  const { skipProperty } = options
+  if (isReactive(obj)) {
+    return
+  }
+  markReactive(obj)
+
+  for (const property in obj) {
+    const value = obj[property]
+    if (
+      isSignal(value) ||
+      typeof value !== 'function' ||
+      skipProperty(property)
+    ) {
+      continue
+    }
+    defineLazyComputedProperty(notifier, {
+      valueFn: value,
+      property,
+      originalObject: obj,
+      overridePrototype: options.overridePrototype,
+    })
+  }
+}