@tanstack/angular-table 9.0.0-alpha.49 → 9.0.0-alpha.51

package/skills/angular/compose-with-tanstack-store/SKILL.md

@@ -2,8 +2,8 @@
 name: angular/compose-with-tanstack-store
 description: >
   Compose TanStack Table v9 with `@tanstack/angular-store`. TanStack Table v9 is itself built on
-  TanStack Store — each state slice is an atom. Three read surfaces: `table.atoms.<slice>` (per-slice
-  readonly, signal-backed), `table.store` (flat readonly view), and `table.baseAtoms.<slice>`
+  TanStack Store — each state slice is an atom. Read surfaces include `table.atoms.<slice>`
+  (per-slice readonly, signal-backed), `table.state` / `table.store` (flat readonly views), and `table.baseAtoms.<slice>`
   (writable). The `atoms` table option lets you replace an internal slice with an external
   TanStack Store atom for cross-app sharing (URL sync, persistence, multi-table coordination).
   In Angular, native signals + `state` + `on[State]Change` is the default; reach for external
@@ -42,11 +42,12 @@ sources:
 
 Every TanStack Table instance exposes its state at three layers:
 
-| Surface                   | Shape                             | Angular reactivity              | Use when                                            |
-| ------------------------- | --------------------------------- | ------------------------------- | --------------------------------------------------- |
-| `table.baseAtoms.<slice>` | Writable `Atom<T>`                | Backed by an Angular `signal`   | Direct internal writes; rare                        |
-| `table.atoms.<slice>`     | Readonly `Atom<T>` (derived)      | Backed by an Angular `computed` | Reading or driving Angular reactivity per-slice     |
-| `table.store`             | Readonly flat `Store<TableState>` | Backed by an Angular `computed` | Reading multiple slices in one go (devtools, debug) |
+| Surface                   | Shape                             | Angular reactivity              | Use when                                        |
+| ------------------------- | --------------------------------- | ------------------------------- | ----------------------------------------------- |
+| `table.baseAtoms.<slice>` | Writable `Atom<T>`                | Backed by an Angular `signal`   | Direct internal writes; rare                    |
+| `table.atoms.<slice>`     | Readonly `Atom<T>` (derived)      | Backed by an Angular `computed` | Reading or driving Angular reactivity per-slice |
+| `table.state`             | Readonly flat proxy               | Reads from slice atoms          | Full-state JSON/debug output                    |
+| `table.store`             | Readonly flat `Store<TableState>` | Backed by an Angular `computed` | Low-level flat store access; rare               |
 
 All three are populated only for **registered features** (`_features`). All
 three are signal-backed via `angularReactivity(injector)`:
@@ -60,7 +61,7 @@ tracks the dependency.
 ```ts
 this.table.atoms.pagination.get()            // current value (reactive)
 this.table.atoms.pagination.subscribe(obs)   // RxJS observer form
-this.table.store.state.pagination            // flat snapshot read
+this.table.state.pagination                  // flat proxy read; prefer atoms for narrow reads
 this.table.baseAtoms.pagination.set(...)     // direct internal write (avoid)
 ```
 

package/skills/angular/migrate-v8-to-v9/SKILL.md

@@ -3,8 +3,8 @@ name: angular/migrate-v8-to-v9
 description: >
   Mechanical v8 → v9 migration for `@tanstack/angular-table`: `createAngularTable` →
   `injectTable`, `get*RowModel()` options → `_rowModels` factories with explicit `*Fns`,
-  required `_features` via `tableFeatures()`, `state` access via `table.store.state` instead
-  of `table.getState()`, `createColumnHelper<TFeatures, TData>()` generic-order flip, every
+  required `_features` via `tableFeatures()`, state access via `table.atoms.<slice>.get()`
+  or `table.state` instead of `table.getState()`, `createColumnHelper<TFeatures, TData>()` generic-order flip, every
   type now requires `TFeatures`, `enablePinning` split into `enableColumnPinning` /
   `enableRowPinning`, `sortingFn` → `sortFn` rename pile, `ColumnSizingInfo` → `ColumnResizing`
   split, removal of `_`-prefixed internals, signal-backed atoms replacing v8 memoized accessors,
@@ -124,24 +124,26 @@ Row-model and feature lookup tables → [`references/v8-to-v9-mapping.md`](refer
 
 ---
 
-## 3. State access: `getState()` → `table.store.state` (and atoms)
+## 3. State access: `getState()` → atoms or `table.state`
 
 ```ts
 // v8
 const { sorting, pagination } = table.getState()
 
-// v9 — flat snapshot
-const { sorting, pagination } = table.store.state
+// v9 — full-state flat proxy
+const { sorting, pagination } = table.state
 
-// v9 — per slice (signal-backed in Angular)
+// v9 — per slice (preferred for Angular render code)
 const sorting = table.atoms.sorting.get()
 const pagination = table.atoms.pagination.get()
 ```
 
-In Angular, all three (`table.atoms.<slice>`, `table.store.state`,
+In Angular, all three (`table.atoms.<slice>`, `table.state`,
 `table.baseAtoms.<slice>`) are signal-backed — reading them inside a template,
 `computed(...)`, or `effect(...)` registers an Angular dependency
-automatically. No `toSignal(...)` wrappers needed.
+automatically. No `toSignal(...)` wrappers needed. Prefer direct atom reads for
+specific slices; keep `table.state` for full-state JSON/debug output or code
+that genuinely wants the flat state shape.
 
 See `tanstack-table/angular/table-state` for the full state surface mental
 model.
@@ -275,7 +277,8 @@ v8 backed reactivity with manual memoized getters. v9's adapter
 `computed` and every writable atom with an Angular `signal`. Consequences:
 
 - **No `toSignal(...)` adapters around table state.** Read `table.atoms.x.get()`
-  / `table.store.state.x` directly inside templates, `computed`, `effect`.
+  directly inside templates, `computed`, `effect` for specific slices. Use
+  `table.state` when you need the full-state flat shape.
 - **`computed(...)` is for derivation / equality, not for "make it reactive".**
   Use `{ equal: shallow }` from `@tanstack/angular-table` on object/array
   slices to skip downstream work on no-op updates.
@@ -306,8 +309,8 @@ v8 backed reactivity with manual memoized getters. v9's adapter
 - [ ] Update `createColumnHelper<Person>()` → `createColumnHelper<typeof _features, Person>()`.
 - [ ] Update every `ColumnDef<Person>` / `Cell<Person, X>` etc. to include
       `TFeatures`.
-- [ ] Replace `table.getState()` reads with `table.store.state` (or
-      `table.atoms.<slice>.get()` for per-slice reactivity).
+- [ ] Replace `table.getState().slice` reads with `table.atoms.<slice>.get()`
+      where possible; use `table.state` for full-state/debug reads.
 - [ ] Remove any usage of the v8 single `onStateChange` — split into per-slice
       `on[State]Change`.
 - [ ] In `on[State]Change` callbacks, handle both value and updater-fn shapes.
@@ -366,12 +369,13 @@ _rowModels: {
 Same for sorting, pagination, expanding, grouping, faceting. Selection,
 visibility, ordering, pinning, sizing, resizing do **not** need a row model.
 
-### 4. (HIGH) `getState()` → `table.store.state` text replacement loses reactivity
+### 4. (HIGH) `getState()` → `table.state` text replacement can be too broad
 
-Bulk-replacing `table.getState().x` with `table.store.state.x` works for _current
-value_ reads, but if you used a `computed`/`memo` around `getState()` for
-reactivity, switch to `table.atoms.x.get()` — it's already signal-backed and
-needs no wrapper.
+Bulk-replacing `table.getState().x` with `table.state.x` works for _current
+value_ reads, but it hides which slice the component depends on. For Angular
+render code and reactive derivations, switch to `table.atoms.x.get()` — it's
+already signal-backed and needs no wrapper. Keep `table.state` for full-state
+debug output.
 
 ### 5. (HIGH) Stale `sortingFn` / `sortingFns` references in column defs
 

package/skills/angular/production-readiness/SKILL.md

@@ -6,7 +6,7 @@ description: >
   stable references OUTSIDE the `injectTable` initializer; pass only the `*Fns` your data needs
   to `createSortedRowModel` / `createFilteredRowModel` / `createGroupedRowModel`; use
   `ChangeDetectionStrategy.OnPush`; lean on signal-backed atoms (`table.atoms.<slice>.get()`)
-  instead of broad `table.store.state` reads where granularity matters; use `{ equal: shallow }`
+  instead of broad `table.state` reads where granularity matters; use `{ equal: shallow }`
   on object/array `computed` selectors; set `getRowId` for stable identity; track by `id` in
   every `@for`; defer cell components with `flexRenderComponent` only when you need its options;
   scope DI tokens via `[tanStackTable*]` directives to kill prop drilling.
@@ -148,20 +148,21 @@ All `examples/angular/*` use `OnPush`. Match that.
 
 ---
 
-## 4. Read narrowly — `table.atoms.<slice>.get()` over `table.store.state`
+## 4. Read narrowly — `table.atoms.<slice>.get()` over `table.state`
 
 Both surfaces are signal-backed. The difference is _which signal_ gets read.
 
 ```ts
-// Wider — depends on the flat snapshot signal (recomputes when ANY registered slice changes)
-const pageIndex = computed(() => this.table.store.state.pagination.pageIndex)
+// Wider — reads through the flat state proxy
+const pageIndex = computed(() => this.table.state.pagination.pageIndex)
 
 // Narrower — depends only on the pagination atom
 const pageIndex = computed(() => this.table.atoms.pagination.get().pageIndex)
 ```
 
-For most apps the difference is negligible. For high-frequency atoms or
-deeply-derived components, prefer per-atom reads.
+For most apps the difference is negligible. For render code, high-frequency
+atoms, or deeply-derived components, prefer per-atom reads. Keep `table.state`
+for places that genuinely want the full-state shape, such as debug JSON.
 
 ---
 
@@ -347,7 +348,7 @@ the wiring cost. Pick exactly one source of truth per slice (see
 - [ ] Cell render fns return primitives or component classes when possible;
       `flexRenderComponent(...)` reserved for explicit-option cases.
 - [ ] Reading state inside `effect`s / heavy `computed`s uses
-      `table.atoms.<slice>.get()` (not the flat snapshot).
+      `table.atoms.<slice>.get()` (not the flat state proxy).
 - [ ] Object/array `computed` selectors that feed expensive downstream use
       `{ equal: shallow }`.
 - [ ] No `cell` / `header` / `table` inputs drilled through multiple

package/skills/angular/table-state/SKILL.md

@@ -30,6 +30,7 @@ sources:
 > on top of TanStack Store (`alien-signals`). In Angular, the adapter bridges those
 > atoms to native Angular signals, so reading `table.atoms.<slice>.get()` from a
 > template, `computed(...)`, or `effect(...)` participates in Angular reactivity.
+> Prefer that direct atom read when you need a specific state slice.
 >
 > This is the prerequisite for every other Angular Table skill. Don't skip it.
 
@@ -145,17 +146,20 @@ A table instance has three ways to look at its state:
 | ------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------- |
 | `table.baseAtoms.<slice>` | writable TanStack Store atom (always exists for registered slices)             | low-level direct write; rare                |
 | `table.atoms.<slice>`     | **readonly** derived atom per registered feature; backed by Angular `computed` | reading current value or driving reactivity |
-| `table.store.state`       | flat snapshot object of every registered slice; backed by Angular `computed`   | reading multiple slices at once, devtools   |
+| `table.state`             | flat proxy object over every registered slice                                  | full-state JSON/debug output                |
 
 All three are signal-backed in Angular. Reading any of them inside a template,
-`computed(...)`, or `effect(...)` registers an Angular dependency.
+`computed(...)`, or `effect(...)` registers an Angular dependency. For normal
+render code, prefer `table.atoms.<slice>.get()` so the read is explicit and
+limited to the slice the component needs. Use `table.state` when you actually
+need the flat full-state shape, such as `JSON.stringify(table.state, null, 2)`.
 
 ```ts
 // Read current value (anywhere)
 const pagination = this.table.atoms.pagination.get()
 
-// Same value, flat shape
-const pagination2 = this.table.store.state.pagination
+// Same value through the flat proxy; use mainly for full-state debug output
+const pagination2 = this.table.state.pagination
 
 // Reactive derivation with custom equality
 import { computed } from '@angular/core'

package/src/injectTable.ts

@@ -20,6 +20,7 @@ import type {
   Table,
   TableFeatures,
   TableOptions,
+  TableState,
 } from '@tanstack/table-core'
 
 export type SubscribeSource<TValue> =
@@ -31,7 +32,70 @@ export type SubscribeSource<TValue> =
 export type AngularTable<
   TFeatures extends TableFeatures,
   TData extends RowData,
-> = Table<TFeatures, TData>
+> = Table<TFeatures, TData> & {
+  /**
+   * @deprecated Prefer `table.atoms.<slice>.get()` for template/render reads
+   * of a specific state slice, `table.state` for full-state debug snapshots, or
+   * Angular computed values around explicit selectors. `table.store.state` is a
+   * current-value snapshot and is easy to misuse in render code.
+   */
+  readonly store: Table<TFeatures, TData>['store']
+  /**
+   * The current table state exposed as a flat proxy. Prefer
+   * `table.atoms.<slice>.get()` when reading a specific slice.
+   */
+  readonly state: Readonly<TableState<TFeatures>>
+}
+
+function createStateProxy<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table<TFeatures, TData>): Readonly<TableState<TFeatures>> {
+  const getSnapshot = () => {
+    const snapshot = {} as TableState<TFeatures>
+    const stateKeys = Object.keys(table.initialState) as Array<
+      keyof TableState<TFeatures>
+    >
+
+    for (const key of stateKeys) {
+      snapshot[key] = table.atoms[key].get()
+    }
+
+    return snapshot
+  }
+
+  const target = {} as TableState<TFeatures>
+
+  return new Proxy(target, {
+    get(target, prop, receiver) {
+      if (prop === 'toJSON') {
+        return getSnapshot
+      }
+
+      if (typeof prop === 'string' && prop in table.initialState) {
+        return table.atoms[prop as keyof TableState<TFeatures>]?.get()
+      }
+
+      return Reflect.get(target, prop, receiver)
+    },
+    has(_, prop) {
+      return typeof prop === 'string' && prop in table.initialState
+    },
+    ownKeys() {
+      return Reflect.ownKeys(table.initialState)
+    },
+    getOwnPropertyDescriptor(_, prop) {
+      if (typeof prop !== 'string' || !(prop in table.initialState)) {
+        return undefined
+      }
+
+      return {
+        enumerable: true,
+        configurable: true,
+      }
+    },
+  })
+}
 
 /**
  * Creates and returns an Angular-reactive table instance.
@@ -107,6 +171,15 @@ export function injectTable<
           coreReativityFeature: angularReactivity(injector),
           ...options()._features,
         },
+      }) as AngularTable<TFeatures, TData>
+      const stateProxy = createStateProxy(table)
+
+      Object.defineProperty(table, 'state', {
+        get() {
+          return stateProxy
+        },
+        configurable: true,
+        enumerable: true,
       })
 
       let isMount = true

package/src/reactivity.ts

@@ -1,5 +1,12 @@
-import { NgZone, computed, signal, untracked } from '@angular/core'
-import { toObservable } from '@angular/core/rxjs-interop'
+import {
+  DestroyRef,
+  NgZone,
+  computed,
+  effect,
+  signal,
+  untracked,
+} from '@angular/core'
+import { batch, createAtom } from '@tanstack/angular-store'
 import type { Atom, Observer, ReadonlyAtom } from '@tanstack/angular-store'
 import type {
   TableAtomOptions,
@@ -7,70 +14,134 @@ import type {
 } from '@tanstack/table-core/reactivity'
 import type { Injector, Signal, WritableSignal } from '@angular/core'
 
+const optionsStoreDebugName = 'table/optionsStore'
+
+function observerToCallback<T>(
+  observerOrNext: Observer<T> | ((value: T) => void),
+): (value: T) => void {
+  return typeof observerOrNext === 'function'
+    ? observerOrNext
+    : (value) => observerOrNext.next?.(value)
+}
+
 function signalToReadonlyAtom<T>(
-  signal: Signal<T>,
-  injector: Injector,
+  source: Signal<T>,
+  getSource: () => T,
+  subscribeSource: (observerOrNext: Observer<T> | ((value: T) => void)) => {
+    unsubscribe: () => void
+  },
 ): ReadonlyAtom<T> {
-  return Object.assign(signal, {
-    get: () => signal(),
-    subscribe: (observer: Observer<T>) => {
-      return toObservable(computed(signal), { injector: injector }).subscribe(
-        observer,
-      )
+  return Object.assign(source, {
+    get: () => {
+      const value = getSource()
+      source()
+      return value
     },
+    subscribe: subscribeSource as ReadonlyAtom<T>['subscribe'],
   })
 }
 
 function signalToWritableAtom<T>(
-  signal: WritableSignal<T>,
+  source: WritableSignal<T>,
   injector: Injector,
 ): Atom<T> {
-  return Object.assign(signal.asReadonly(), {
+  const observers = new Set<(value: T) => void>()
+  let observed = false
+  effect(
+    () => {
+      const value = source()
+      if (!observed) {
+        observed = true
+        return
+      }
+      observers.forEach((observer) => observer(value))
+    },
+    { injector },
+  )
+
+  return Object.assign(source.asReadonly(), {
     set: (updater: T | ((prevVal: T) => T)) => {
       typeof updater === 'function'
-        ? signal.update(updater as (val: T) => T)
-        : signal.set(updater)
-    },
-    get: () => signal(),
-    subscribe: (observer: Observer<T>) => {
-      return toObservable(computed(signal), { injector: injector }).subscribe(
-        observer,
-      )
+        ? source.update(updater as (val: T) => T)
+        : source.set(updater)
     },
+    get: () => source(),
+    subscribe: ((observerOrNext: Observer<T> | ((value: T) => void)) => {
+      const observer = observerToCallback(observerOrNext)
+      observers.add(observer)
+
+      return {
+        unsubscribe: () => observers.delete(observer),
+      }
+    }) as Atom<T>['subscribe'],
   })
 }
 
 /**
  * Creates the table-core reactivity bindings used by the Angular adapter.
  *
- * Readonly table atoms are backed by Angular `computed` signals and writable
- * atoms by Angular `signal`. Subscriptions bridge through `toObservable` with
- * the caller's injector so table APIs can be consumed from Angular `computed`
- * and `effect` calls.
+ * Table state atoms are backed by TanStack Store atoms. The options store stays
+ * framework-native because row-model APIs read `table.options` directly during
+ * render. Readonly table atoms bridge Store dependency tracking into Angular
+ * computed signals.
  */
 export function angularReactivity(injector: Injector): TableReactivityBindings {
   const ngZone = injector.get(NgZone)
+  const destroyRef = injector.get(DestroyRef)
+
   return {
     createOptionsStore: true,
     schedule: (fn) => ngZone.runOutsideAngular(() => queueMicrotask(fn)),
     createReadonlyAtom: <T>(fn: () => T, options?: TableAtomOptions<T>) => {
-      const signal = computed(() => fn(), {
-        equal: options?.compare,
-        debugName: options?.debugName,
+      const storeAtom = createAtom(() => fn(), {
+        compare: options?.compare,
+      })
+      const version = signal(0, {
+        equal: () => false,
+      })
+      const subscription = storeAtom.subscribe(() => {
+        version.update((value) => value + 1)
       })
-      return signalToReadonlyAtom(signal, injector)
+      destroyRef.onDestroy(() => subscription.unsubscribe())
+
+      const value = computed(
+        () => {
+          version()
+          return storeAtom.get()
+        },
+        {
+          equal: options?.compare,
+          debugName: options?.debugName,
+        },
+      )
+      return signalToReadonlyAtom(
+        value,
+        () => storeAtom.get(),
+        (observerOrNext) => {
+          const observer = observerToCallback(observerOrNext)
+          return storeAtom.subscribe(() => {
+            observer(storeAtom.get())
+          })
+        },
+      )
     },
     createWritableAtom: <T>(
       value: T,
       options?: TableAtomOptions<T>,
     ): Atom<T> => {
-      const writableSignal = signal(value, {
-        equal: options?.compare,
-        debugName: options?.debugName,
+      if (options?.debugName === optionsStoreDebugName) {
+        const writableSignal = signal(value, {
+          equal: options.compare,
+          debugName: options.debugName,
+        })
+        return signalToWritableAtom(writableSignal, injector)
+      }
+
+      return createAtom(value, {
+        compare: options?.compare,
       })
-      return signalToWritableAtom(writableSignal, injector)
     },
     untrack: untracked,
-    batch: (fn) => fn(),
+    batch,
   }
 }