Global helpers

The functions that let you read, write, inspect, and tear down pgTables from outside React. tableApi's methods are the React-bound flavour; these are the same store, addressed by pgTableId, callable from anywhere — analytics flushes, event bridges, sign-out hooks, tests, listener bodies in a <name>-table-listeners.ts.

Full surface

Two clusters. The first is the in-memory store (hasTable, getTable, removeTable, plus four direct read/write helpers). The second is the webstorage layer (getPersistedTableProps, clearStoredTables, dropTableEverywhere).

TSsurface.ts

// In-memory store
hasTable(pgTableId):                          boolean
getTable<C, S>(pgTableId):                    PgTableApi<C, S> | null
removeTable(pgTableId):                       boolean

// Direct read/write — same store, no React lifecycle
getTableData<C>(pgTableId):                   PgTableData<C>             | null
getTableState<T>(pgTableId):                  PgTableStateValues<T>      | null
setTableData<C, T>(pgTableId, next):          void
setTableState<C, T>(pgTableId, next):         void

// Webstorage persistence
getPersistedTableProps(opts?):                PgTablePersistedProps[]
clearStoredTables(opts?):                     void
dropTableEverywhere(pgTableId):               void

Accessing a table by id

getTable(pgTableId) returns the same PgTableApi shape you get from usePgTable, or null when no entry exists. hasTable is the cheap existence check when you want to branch without paying for the API object.

TSXcharacters-table-listeners.ts

// Named-table-state-listener body. Reaches the table by id rather than
// importing tableApi from the composition-component — the listener stays
// caller-agnostic.
import { getTable, hasTable } from '@westopp/pgtable'
import type { charactersColumns, charactersState } from './characters-table-config'
import { CHARACTERS_TABLE_ID } from './characters-table-config'

export const onSortChange = async () => {
if (!hasTable(CHARACTERS_TABLE_ID)) return
const api = getTable<typeof charactersColumns, typeof charactersState>(CHARACTERS_TABLE_ID)
if (!api) return
api.setState((prev) => { prev.pagination.page = 1; prev.selectedIds = [] })
}

Direct read/write

getTableData, getTableState, setTableData, and setTableState skip the API construction and hit the store directly. Same writes, same notifications — just a lighter call site. Reads stay read-only to the caller; writes go through the set* helpers.

TSXcharacters-table-listeners.ts

// Light-touch reads/writes without going through tableApi. Useful when
// you do not need dirty checks, columnsArray, or the rest of the surface.
import { getTableData, getTableState, setTableData, setTableState } from '@westopp/pgtable'

const rows = getTableData('characters')                    // PgTableData | null
const sort = getTableState('characters')?.sort             // T['sort'] | undefined

setTableData('characters', (rows) => rows.filter((r) => r.power > 0))
setTableState('characters', { page: 1 })

Aggregating across tables

Forms and tables survive unmount so you can pull state from several of them into a single payload without an external store framework. Iterate the ids your feature knows about (caller-supplied — there is no global "every table"), pull the dirty subsets, ship.

TSXsave-dirty-tables.ts

// Multiple tables, one save flow. The caller knows which ids are in play;
// pgTable does not enumerate them for you.
import { getTable } from '@westopp/pgtable'

export const saveDirtyTables = async (ids: string[]) => {
const payload = ids
  .map((id) => {
    const t = getTable(id)
    if (!t) return null
    if (!t.isDirtyData() && !t.isDirtyState()) return null
    return { id, rows: t.getData(), changes: t.dirtyStateProperties() }
  })
  .filter((x) => x !== null)

await api.saveAll(payload)
}

Persisted-entry inspection and cleanup

Persisted entries are addressable independently of the in-memory store. getPersistedTableProps lists them; clearStoredTables wipes them by id, mode, or wholesale; dropTableEverywhere is the all-in-one for a single id.

TSXpersistence-admin.ts

import { clearStoredTables, dropTableEverywhere, getPersistedTableProps } from '@westopp/pgtable'

// What is on webstorage right now?
getPersistedTableProps()                                 // [{ pgTableId, mode, schemaVersion, lastUpdatedAt, expiresAt }, ...]
getPersistedTableProps({ mode: 'local' })                // only localStorage entries

// Wipe persisted entries — accepts ids, mode, or neither (everything).
clearStoredTables({ ids: ['characters'] })
clearStoredTables({ mode: 'session' })                   // every pgtable: entry in sessionStorage
clearStoredTables()                                      // every pgtable: entry, both storages

// Drop both in-memory and persisted entries for one table.
dropTableEverywhere('characters')

A sign-out hook

The clean-up most apps need. Walk every persisted entry, drop its in-memory twin, then clear webstorage. After this, a fresh mount with autoRestore still on will start from declared initials.

TSXon-sign-out.ts

// Canonical sign-out flow — clear everything from both storages and any
// in-memory entries the persisted list reports. Add this to your auth
// provider's onSignOut hook.
import { clearStoredTables, getPersistedTableProps, removeTable } from '@westopp/pgtable'

export const onSignOut = () => {
for (const t of getPersistedTableProps()) removeTable(t.pgTableId)
clearStoredTables()
}

Previous← Persistence config