p-table stateStorage stateKey rotation after schema change

What is persisted by stateStorage?

PrimeNG’s stateStorage serialises a TableState object into the browser’s localStorage or sessionStorage under the exact string supplied by stateKey. The object typically contains:

• Pagination: first, rows
• Sorting: sortField & sortOrder (or multiSortMeta)
• Filters: a map of column field names to filter metadata (value, matchMode, etc.)
• Column state: selection, order, widths when column resizing or reordering is enabled

Stability across PrimeNG versions

The shape of TableState is not part of the public API and has changed between major releases. A blob written by PrimeNG 13 may contain fields that the 14 runtime does not recognise, and vice‑versa. Consequently, a persisted state from an older version can become stale or even corrupt the table if applied unchanged.

Does rotating or namespacing stateKey invalidate old entries?

Yes. The storage lookup is a strict string match. If you change the key—e.g. orders-grid-v3 instead of orders-grid—the new table will ignore the old entry. The old entry simply remains in storage as orphaned data; it is not automatically cleaned up. Re‑using the same key across schema changes will cause the table to restore an incompatible state and can lead to hidden rows or UI glitches.

Reconciling restored filters after a schema change

Because the table initialises before data is fetched, a restored filter that references a removed or renamed column can silently hide all rows. To avoid this, validate the deserialised state before binding it:

1. Deserialize the stored JSON.
2. Iterate over filters and multiSortMeta entries.
3. Keep only those whose field property matches a column definition in the current cols array.
4. Optionally map renamed fields (e.g. oldName → newName) if you maintain a migration map.
5. Apply the cleaned state to the table via tableState or by setting first, rows, etc. manually.

Implementing this step in a small helper function keeps the UI predictable after upgrades.

Practical steps for a release cycle

1. Version the key: Append the app or schema version to the key (e.g. orders-grid-v3).
2. Persist a migration map: If column names change, keep a simple object that maps old names to new ones.
3. Validate on load: When the component mounts, read the stored state, filter out unknown fields, remap using the migration map, then apply.
4. Clean up: On upgrade, delete the old key from storage (e.g. localStorage.removeItem('orders-grid-v2')) to prevent storage bloat.
5. Test: Save a state with the old key, deploy the new version, and confirm the table starts with defaults and the old key is ignored.

Ask for missing diagnostic detail

To tailor the migration logic precisely, could you confirm which PrimeNG major version you are upgrading from and to? Knowing the exact versions helps identify the exact fields that changed in TableState.