@atscript/ui-table
Framework-agnostic table model. Filter conditions, filter→Uniquery conversion, sorter/filter merging, URL state bridging, preset wire types, window-mode pagination math, column widths, selection helpers, and the abstract TableStateMethods / TableStateData contracts that @atscript/vue-table fulfills. Zero Vue dependency — React or Svelte adapters reuse everything here.
Contents
- Filter model
- Filter input format
- Filters and Uniquery
- Date and time filters
- Date shortcuts
- Presets — wire types
- Presets — application types
- Presets — id helpers
- Presets — system presets
- Presets — dirty detection
- Hidden-field pruning
- Presets — local draft
- Presets — HTTP clients
- Query builder
- URL query bridge
- Selection
- State contracts
- Window mode helpers
- Column widths
- Display columns
- Export
- Utilities
Filter model
FilterConditionType
Canonical operator names used in filter conditions. bw ("between") is the range operator — there is no separate between alias.
type FilterConditionType =
| "eq"
| "ne"
| "gt"
| "gte"
| "lt"
| "lte"
| "contains"
| "starts"
| "ends"
| "bw"
| "null"
| "notNull"
| "regex";FilterCondition
A single per-field condition. Operands live in a positional array — most operators read value[0]; bw reads value[0] (low) + value[1] (high); null / notNull ignore value.
interface FilterCondition {
type: FilterConditionType;
value: (string | number | boolean)[];
}FieldFilters
Per-field map of applied conditions. The framework treats absence and empty array as equivalent.
type FieldFilters = Record<string, FilterCondition[]>;Condition helpers
function isFilled(cond: FilterCondition): boolean;
function hasSecondValue(type: FilterConditionType): boolean; // `true` only for `"bw"`
function isSimpleEq(cond: FilterCondition): boolean;
/** `kind` (since 0.1.148): on `"date"` / `"datetime"` the comparisons read on / not on / before / on or before / after / on or after / between. */
function conditionLabel(type: FilterConditionType, kind?: ColumnFilterType, t?: UiT): string;
function filledFilterCount(filters: FieldFilters): number;
function compactFieldFilters(filters: FieldFilters): FieldFilters; // since 0.1.142
function filterTokenLabel(
path: string,
conditions: FilterCondition[],
columnLabel?: string,
t?: UiT,
): string;
const NULL_OPS: ReadonlySet<FilterConditionType>; // { "null", "notNull" }isFilled returns true when the condition has at least one operand bound (or uses a NULL_OPS operator). filledFilterCount is used by toolbar badges. compactFieldFilters drops the fields with no filled condition — the shape table state holds (state.setFieldFilter and preset apply both write it) — returning the input itself when nothing goes. filterTokenLabel summarises a field's filled conditions into a chip-friendly token.
Every function here that words something for people (conditionLabel, filterTokenLabel, formatFilterExpr, formatColumnCondition / formatColumnValue via opts.t, temporalShortcuts, resolveSystemPresets) reads UI texts (UI_FILTER_*, UI_DATE_* in AS_UI_MESSAGES) through an optional t (UiT from @atscript/ui) — the active UI locale's when omitted. The Vue components pass the app's own (useAsLocale().t). See Language & Translations.
Conditions per type
/** `"datetime"` since 0.1.148 — a date filter on a column that stores instants. Same conditions as `"date"`. */
type ColumnFilterType = "text" | "number" | "boolean" | "date" | "datetime" | "enum" | "ref";
/**
* Drops `"null"` / `"notNull"` when `nullable === false`, and (since 0.1.148)
* the pattern conditions when `valueKind` is set and is not `"string"`.
*/
function conditionsForType(
type: ColumnFilterType,
nullable?: boolean,
valueKind?: ColumnValueKind,
): readonly FilterConditionType[];
/** Map a `ColumnDef.type` string to its filter-type bucket (`"datetime"` maps to `"datetime"` since 0.1.148). */
function columnFilterType(columnType: string): ColumnFilterType;
/** Adds `valueKind` since 0.1.148. */
type FilterableColumn = Pick<
ColumnDef,
"type" | "nullable" | "filterable" | "filterOps" | "valueKind"
>;
/**
* The filter kind of a column — what its input and conditions follow; every
* built-in filter UI reads it instead of `columnFilterType(column.type)`.
* `valueKind` wins: `timestamp` → `"datetime"` (`"date"` when shown as a date,
* `"number"` when shown as a number — an opt-out to raw ms), `isoDate` →
* `"datetime"` (`"date"` when shown as a date), `date` → `"date"`; a text kind
* over a numeric / boolean `valueKind` becomes `"number"` / `"boolean"`;
* `"enum"` and `"ref"` keep their kind. Since 0.1.148.
*/
function columnFilterKind(column: Pick<FilterableColumn, "type" | "valueKind">): ColumnFilterType;
/**
* The conditions a column offers; `[]` when it takes no filter. Since 0.1.139.
* Since 0.1.148 follows `columnFilterKind`, drops `contains` / `starts` /
* `ends` / `regex` (`$regex`, string fields only) when `valueKind` is set and
* is not `"string"`, and offers only what the server's reported `filterOps`
* accept when it reports them.
*/
function columnFilterConditions(column: FilterableColumn): readonly FilterConditionType[];
/** `columnFilterConditions(column).length > 0`. Since 0.1.139. */
function isColumnFilterable(column: FilterableColumn): boolean;conditionsForType returns the operator set for a column type. columnFilterConditions is the per-column answer every built-in filter UI reads: the type's set for a value-filterable column, ["null", "notNull"] for an existence-only one (filterable: false with filterOps including "$exists" — a JSON-stored column; dropped when the column is not nullable), [] otherwise. Gate custom filter UIs on isColumnFilterable, not on column.filterable (value comparison only). See Filterable columns.
Filter input format
Tools for parsing and formatting filter values typed by the user.
/**
* Parses operator shorthand (`>100`, `*foo*`, `lo...hi`, `<empty>`,
* `!<empty>`, `/regex/`). Values are coerced per `columnType`: `number`
* columns get numbers, and (since 0.1.133) `boolean` columns understand the
* `true` / `false` vocabulary case-insensitively, so the condition carries a
* real boolean and round-trips through the URL as one. Since 0.1.148 any other
* text on a boolean column is not a filter (`undefined`, so nothing is sent).
*/
function parseFilterInput(
raw: string,
columnType: ColumnFilterType,
nullable?: boolean,
): FilterCondition | undefined;
/**
* `parseFilterInput` for a column: type from `columnFilterKind(column)`,
* accepted operators from `columnFilterConditions(column)`. Since 0.1.139.
* Since 0.1.148 the values are checked against the column's `valueKind`:
* date / date-time columns take the [temporal grammar](/tables/filtering#date-and-time-filters)
* (default operator `eq`; a non-date value returns `undefined`), an `integer`
* column rejects fractions, a `decimal` keeps its typed text as a string,
* a boolean column accepts `true` / `false` only. Since 0.1.165, on a column
* with `options` (a literal union or a boolean) an option's exact label or key
* (case-insensitive) is its typed value: `Active` → `eq true`.
*/
function parseColumnFilterInput(raw: string, column: FilterableColumn): FilterCondition | undefined;
/** Format a condition back into the same operator-shorthand string. Round-trips with `parseFilterInput`. */
function formatFilterCondition(cond: FilterCondition): string;
/** Default operator for a fresh filter picker: `"contains"` for `text`/`enum`/`ref`, else `"eq"`. */
function defaultCondition(columnType: ColumnFilterType): FilterConditionType;
/**
* Default operator for a column's filter input: `defaultCondition(type)` when
* the column offers it, else the first condition it offers (`"null"` on an
* existence-only column). Since 0.1.139.
*/
function columnDefaultCondition(column: FilterableColumn): FilterConditionType;
function escapeRegex(value: string): string;
function unescapeRegex(value: string): string;See Filtering.
Filters and Uniquery
filtersToUniqueryFilter produces a @uniqu/core filter the server consumes; uniqueryFilterToFieldFilters rebuilds FieldFilters from a Uniquery filter (the URL bridge's decoder uses it).
/**
* `opts.encode` (since 0.1.148) is consulted per condition before the default
* conversion — an `undefined` result falls through to it. `ne` and `notNull`
* results stay in the AND-ed exclusion group.
*/
function filtersToUniqueryFilter(
filters: FieldFilters,
opts?: { encode?: ConditionEncoder },
): FilterExpr | undefined;
function uniqueryFilterToFieldFilters(
expr: FilterExpr | undefined,
/** Pieces naming another field (alone or mixed with known ones, since 0.1.141) are ignored silently. */
knownFields?: Iterable<string>,
/** Each AND-ed piece that was left out. Omitted → a dev-mode `console.warn` per piece. Since 0.1.139. */
onUnsupportedFilter?: (issue: UnsupportedFilter) => void,
): FieldFilters;
interface UnsupportedFilter {
reason: UnsupportedFilterReason;
/** The left-out sub-expression, as it appeared in the input. */
expr: FilterExpr;
/** Field paths it references (a relational predicate: the relation name only). */
fields: string[];
/** Reason `"syntax"` only: the URL segment as written (`expr` is `{}`). Since 0.1.147. */
raw?: string;
}
/** `"relation"` and `"syntax"` since 0.1.147. */
type UnsupportedFilterReason =
| "cross-field"
| "operator"
| "negation"
| "conjunction"
| "relation"
| "syntax";
/** Since 0.1.140. Split into exact field filters, carried residual conditions and reports. Never throws, never warns. */
function decomposeUniqueryFilter(
expr: FilterExpr | undefined,
opts?: DecomposeUniqueryFilterOptions,
): DecomposedUniqueryFilter;
interface DecomposeUniqueryFilterOptions {
/** A piece naming another field — alone or mixed with known ones — goes to `unknown`, never carried or `unsupported`. */
knownFields?: Iterable<string>;
/** Keep left-out pieces whose fields are all known as `residual`. Default `false` (the 0.1.139 split). */
carry?: boolean;
}
interface DecomposedUniqueryFilter {
filters: FieldFilters;
/** Carried conditions, AND-ed conjuncts in canonical order. `[]` without `carry`. */
residual: FilterExpr[];
/** Pieces left out and lost (not carried) — the result is broader by exactly these. */
unsupported: UnsupportedFilter[];
/** Since 0.1.141. Whole pieces left out because they name a field outside `knownFields`. `[]` without `knownFields`. Up to 0.1.140 a mixed piece went to `unsupported`. */
unknown: UnknownFilter[];
}
/** Since 0.1.141. */
interface UnknownFilter {
/** The left-out sub-expression, as it appeared in the input. */
expr: FilterExpr;
/** The paths it names that are outside `knownFields`. */
fields: string[];
}
/** Since 0.1.140. Canonical identity of a filter expression (its `@uniqu/url` spelling) — equal keys select the same rows. */
function filterExprKey(expr: FilterExpr): string;
/** Since 0.1.140. Human-readable rendering, worded like the filter chips. `labelOf` maps a path to a display label. */
function formatFilterExpr(
expr: FilterExpr,
labelOf?: (path: string) => string | undefined,
/** Wording for a value on a field (e.g. an epoch number on a timestamp column as a date); `undefined` keeps the plain rendering. Since 0.1.148. */
formatValue?: (path: string, value: unknown) => string | undefined,
/** Reads the wording's UI texts; the active UI locale's by default. */
t?: UiT,
): string;The decoder is exact for everything filtersToUniqueryFilter produces, maps $in / $nin / same-field $or / invertible $not exactly, and leaves out whole — and reports — every AND-ed piece field filters cannot express, so the result never selects fewer rows than the input and never silently more. Up to 0.1.138 such pieces were dropped or reshaped without a report. $not: { $not: p } reads as p (since 0.1.140). decomposeUniqueryFilter(expr, { carry: true }) keeps those pieces as residual conditions instead — with carry, a field with two positive groups keeps neither as a field filter, so an encode/decode round trip is a fixed point. See Converting a Uniquery filter back and Custom filter conditions.
Date and time filters
Since 0.1.148. The filter model keeps date conditions in calendar terms (2026-10-05, today-6, month); these functions resolve and encode them in the viewer's time zone when a query is built. The concepts — values, operators, time zone, shortcuts, URLs — are in Date and time filters.
interface TemporalOptions {
/** IANA zone; the runtime's local zone when omitted (an invalid name falls back to it, with a dev warning). */
timeZone?: string;
/** `1` = Monday … `7` = Sunday. Default `1`. */
weekStart?: number;
/** "Now" in epoch ms. Default: the query's clock reading, else the clock. */
now?: number;
}
/** A day, minute, month, relative token, ISO instant (`Z` / offset) or epoch-ms number. */
function isTemporalValue(v: unknown): boolean;
/**
* `now` is the clock reading of the query being built (`filtersToUniqueryFilter`
* and `buildTableQuery` pass one reading for the whole query); `undefined` =
* "no opinion" — the default conversion runs.
*/
type ConditionEncoder = (
field: string,
cond: FilterCondition,
now?: number,
) => FilterExpr | undefined;
/**
* The one choke point where a typed filter value becomes what the server's
* filter guard accepts, per column. Temporal columns (`columnFilterKind` is
* `date` / `datetime`, with a `valueKind`): periods as epoch ms (`timestamp`,
* numeric columns), ISO strings (`isoDate`) or `YYYY-MM-DD` (`date`; a plain
* `string` column keeps a time of day rather than cutting it). Boolean columns:
* `"true"` / `"false"` → boolean. Number / integer columns: numeric text →
* number. Decimal columns: numbers → strings. Fields without a `valueKind`
* (display columns, older servers): untouched. An unresolvable string is sent
* as typed so the server refuses it; an epoch number against an epoch column
* keeps its plain comparison. Pass the result as `encode` / `encodeCondition`.
*/
function createColumnValueEncoder(
columns: readonly Pick<ColumnDef, "path" | "type" | "valueKind">[],
opts?: TemporalOptions,
): ConditionEncoder;
interface TemporalShortcut {
id: string;
label: string;
conditions: FilterCondition[]; // relative tokens
}
/** Today, Yesterday, Last 7 days (`bw today-6…today`), Last 30 days, This week, Last week, This month, Last month, This year. */
function temporalShortcuts(t?: UiT): TemporalShortcut[];Date shortcuts
Deprecated
dateShortcuts() produces absolute dates, which go stale in a saved filter and ignore the table's time zone. Use temporalShortcuts(), whose conditions carry relative tokens. Its labels follow the active UI texts. It stays exported and will be removed in a future breaking release.
Pre-built absolute date-range presets. Each shortcut produces an ISO date pair (YYYY-MM-DD) intended for a bw (between) condition.
interface DateShortcut {
label: string;
dates: [start: string, end: string];
}
/** Returns the canonical shortcut list relative to `now` (defaults to current date). */
function dateShortcuts(now?: Date): DateShortcut[];
// → Last 7 Days, Last 30 Days, Month to Date, Last 90 Days, Last 6 Months,
// Last 12 Months, Year to DatePresets — wire types
PresetSnapshot
In-memory snapshot of table state for preset persistence. Dict-shaped — aspects mirror the runtime state, not the wire format. The wire form (entries-arrays for atscript validation) is PresetSnapshotWire. Each top-level key is opt-in: a key's presence claims that aspect; absent keys are left untouched on apply.
interface PresetSnapshot {
columns?: {
columnNames: string[];
/** Override-only diff against column defaults — never serialise the default itself. */
columnWidths?: Record<string, string>;
};
/** Displayed filter field paths (the visible-input list). */
filters?: string[];
/** Applied filter conditions keyed by field path. */
filterOps?: FieldFilters;
sorters?: SortControl[];
itemsPerPage?: number;
}PresetSnapshotWire, PresetColumnWidthEntry, PresetFilterOpEntry, PresetSorterEntry
Persisted wire form (what hits the DB / URL). Matches the .as model in @atscript/moost-ui-presets.
PresetAspect, AspectMask, PRESET_ASPECTS, derivePresetAspects
type PresetAspect = "columns" | "filters" | "filterOps" | "sorters" | "itemsPerPage";
type AspectMask = ReadonlySet<PresetAspect> | readonly PresetAspect[];
const PRESET_ASPECTS: readonly PresetAspect[];
function derivePresetAspects(snapshot: PresetSnapshot | PresetSnapshotWire): PresetAspect[];derivePresetAspects(snapshot) returns the list of aspects actually present on a snapshot — used by the controller when stamping aspects[] on a preset row.
toWireSnapshot(snapshot) / fromWireSnapshot(wire)
function toWireSnapshot(snapshot: PresetSnapshot): PresetSnapshotWire;
function fromWireSnapshot(wire: PresetSnapshotWire): PresetSnapshot;Bidirectional bridge between the application shape (sets, ordered arrays, etc.) and the JSON wire shape. Entries-arrays are sorted by field so consumers (server-side aspect derivation, dirty detection, equality checks) see a stable order.
Empty aspects round-trip as empty (since 0.1.133). columnWidths and filterOps used to be dropped when they serialized to zero entries, which silently turned an owned aspect into an absent one. An owned-but-empty aspect CLEARS that state on apply — a saved view with no filters owns filterOps and clears them — while an absent aspect leaves the state alone. The two are never collapsed into each other in either direction.
Presets — application types
interface AsPresetEntryRow {
id: string;
type: "preset" | "userConf" | "appConf";
app: string;
tableKey?: string;
user: string;
userLabel?: string;
public?: boolean;
label?: string;
publicLabel?: string;
aspects?: PresetAspect[];
data: AsPresetEntryData;
createdAt: number;
updatedAt: number;
}
type AsPresetEntryData = PresetData | UserConfData | AppConfData;
interface PresetData {
label: string;
content?: PresetSnapshotWire;
}
interface UserConfData {
defaultPresetId?: string;
favPresetIds?: string[];
}
interface AppConfData {
appearance?: "system" | "light" | "dark";
language?: string;
timezone?: string;
density?: "compact" | "cozy" | "comfortable";
dateFormat?: "iso" | "us" | "eu";
firstDayOfWeek?: 0 | 1 | 6;
customJson?: string;
}
interface PresetCapabilities {
/** Whether the current user may set `public: true` on presets in this scope. */
canPublish: boolean;
/** Per-`(app, tableKey, user)` preset cap. */
presetLimit: number;
/** Server-known opaque identity for the current user. */
userId: string;
}
interface PresetLimitReachedBody {
code: "preset_limit_reached";
limit: number;
count: number;
}
type AsPresetsErrorCode =
| "preset_limit_reached"
| "reserved_id"
| "public_name_conflict"
| "missing_scope"
| "missing_id"
| "invalid_type"
| "type_immutable"
| "identity_immutable"
| "preset_not_found"
| "publish_forbidden"
| "action_unsupported";Presets — id helpers
const SYSTEM_PRESET_PREFIX: "sys:";
const USER_CONF_PREFIX: "uc:";
const APP_CONF_PREFIX: "ac:";
const RESERVED_ID_PREFIXES: readonly string[];
const STANDARD_PRESET_ID: "sys:standard";
function userConfId(user: string, app: string, tableKey: string): string;
function appConfId(user: string, app: string): string;
function isSystemPresetId(id: string): boolean;
function normaliseSystemPresetId(id: string): string;User-authored preset ids must NOT start with any prefix in RESERVED_ID_PREFIXES — the controller rejects writes that try.
Presets — system presets
System presets are read-only, framework-defined snapshots like "Standard view". Apps may also register custom synthetic presets via useTable({ preset.systemPresets }).
interface SystemPreset {
id: string; // "sys:standard" or "sys:<custom>"
label: string;
snapshot: PresetSnapshot;
aspects: PresetAspect[];
}
interface SystemPresetInput {
id: string;
label: string;
snapshot: Partial<PresetSnapshot>;
}
function resolveSystemPresets(
inputs?: SystemPresetInput[],
t?: UiT, // since 0.1.165 — words the default "Standard" label (UI_PRESET_STANDARD)
): SystemPreset[];resolveSystemPresets always emits a sys:standard entry as item 0 and follows it with the consumer-supplied list.
Presets — dirty detection
function stableStringify(value: unknown): string;
function isDirtyAgainst(active: PresetSnapshot, current: PresetSnapshot): boolean;
function canonicalPresetSnapshot(
snapshot: PresetSnapshot,
defaultWidths: Readonly<Record<string, string>>,
): PresetSnapshot;stableStringify produces deterministic JSON (sorted keys) so a snapshot's hash is stable across reorders. isDirtyAgainst returns true when at least one aspect active claims differs in current (pass the full captureSnapshot() output as current).
canonicalPresetSnapshot (since 0.1.142) spells a stored snapshot the way captureSnapshot() spells table state, so the two compare equal; defaultWidths maps column path → default width (the d of each ColumnWidthsMap entry). Returns the input itself when nothing changes. Rules: What counts as a change.
Hidden-field pruning
Since 0.1.141. Pure helpers that drop the parts of a snapshot or of residual conditions that name fields the table cannot use — the rules @atscript/vue-table applies to presets, drafts and URLs. See Fields Hidden by Role.
interface KnownFields {
/** Every column path, client-owned columns included, in column order. Gates column names, widths, sorters. */
columns: ReadonlySet<string>;
/** Server-backed column paths. Gates filter inputs, field filters, residual conditions. */
server: ReadonlySet<string>;
}
interface DroppedFields {
/** The unusable paths behind the drops, deduped, in order of appearance. */
fields: string[];
columns: string[];
filterFields: string[];
filters: FieldFilters;
residual: FilterExpr[];
sorters: SortControl[];
}
/** `dropped: null` when nothing user-visible was removed. Never mutates its input. */
function prunePresetSnapshot(
snapshot: PresetSnapshot,
known: KnownFields,
): { snapshot: PresetSnapshot; dropped: DroppedFields | null };
/** One pass. A condition naming any unknown field is dropped whole (never pruned inside `$or` / `$not`); `dropped` fills `residual` and `fields`, `null` when all are kept. */
function pruneResidualFilters(
exprs: FilterExpr[],
known: ReadonlySet<string>,
): { kept: FilterExpr[]; dropped: DroppedFields | null };
/** Append `dropped` back onto `captured`: column names, filter inputs and sorters after the captured ones; field filters added. Only aspects `captured` carries; hidden widths are not kept. */
function restoreDroppedEntries(captured: PresetSnapshot, dropped: DroppedFields): PresetSnapshot;prunePresetSnapshot falls back to every column when no column name survives, and omits a columnWidths map it emptied. A width-only drop reports nothing (dropped: null) but still returns the pruned snapshot.
Presets — local draft
Opt-in localStorage overlay that captures the user's in-flight tweaks. Persists columns/filters/sorters and optionally itemsPerPage; filterOps, searchTerm, and pagination are never persisted.
/** Subset of `PresetSnapshot` — `filterOps` is excluded by design. */
type PresetDraft = Omit<PresetSnapshot, "filterOps">;
type DraftPersistedAspect = "columns" | "filters" | "sorters" | "itemsPerPage";
const DRAFT_PERSISTED_ASPECTS: readonly DraftPersistedAspect[];
/** Copy the draft-persistable aspects out of a snapshot, gated by `availableAspects`. */
function serializeDraft(
snapshot: PresetSnapshot,
availableAspects: readonly PresetAspect[],
): PresetDraft;
/** Inverse of `serializeDraft` — same gate. */
function deserializeDraft(
draft: PresetDraft,
availableAspects: readonly PresetAspect[],
): PresetSnapshot;
function isEmptyDraft(draft: PresetDraft): boolean;
function draftMatchesPreset(
draft: PresetDraft,
presetSnapshot: PresetSnapshot,
availableAspects: readonly PresetAspect[],
): boolean;Presets — HTTP clients
PresetsClient
Framework-agnostic wrapper over @atscript/db-client's Client for the AsPresetsController endpoint. Owns preset CRUD, userConf upserts, and capability probing. Stateless — every method is a fresh request.
interface PresetsClientConfig {
/** Controller mount URL, e.g. `"/db/_presets"`. */
url: string;
app: string;
tableKey: string;
/** Pre-built `Client` (auth-configured by the host). Wins over `clientFactory`. */
client?: Client;
/** Builds a `Client` for the given URL. Defaults to `getDefaultClientFactory()`. */
clientFactory?: ClientFactory;
/**
* Since 0.1.168: the UI locale to ask in — a string, or a getter read per request.
* The factory is asked for `{ locale }` (one client per locale) and the
* capabilities request sends `Accept-Language`, so errors and preflight
* messages come back translated. A pre-built `client` is used as given.
*/
locale?: PresetsLocale; // string | (() => string | undefined)
/** Fetch impl for the `GET /capabilities` side-channel. Defaults to `globalThis.fetch`. */
fetch?: typeof globalThis.fetch;
}
interface PresetsListResult {
presets: AsPresetEntryRow[];
/** type='userConf' row for this `(user, app, tableKey)`, or null. */
userConf: AsPresetEntryRow | null;
/** `null` when the capabilities load failed; `undefined` when the call skipped capabilities. */
capabilities: PresetCapabilities | null | undefined;
/** True when the controller responded 401/403/404 (404 = controller not mounted) — UI silently hides. */
denied: boolean;
}
interface PresetsSaveAsOptions {
public?: boolean;
}
interface PresetsSaveResult {
id: string;
}
class PresetsClient {
constructor(config: PresetsClientConfig);
/** Lists owned + public preset rows AND the user's userConf row. `{ capabilities: false }` skips the capabilities fetch. */
list(opts?: { capabilities?: boolean }): Promise<PresetsListResult>;
/** `GET ${url}/capabilities?app=...&tableKey=...` — out-of-band of the CRUD plumbing. */
loadCapabilities(): Promise<PresetCapabilities>;
/** Overwrite the active preset's content (label preserved). */
savePreset(id: string, label: string, snapshot: PresetSnapshot): Promise<void>;
/** Create a new preset row. Server stamps `user`, generates `id`, derives `aspects`. */
savePresetAs(
label: string,
snapshot: PresetSnapshot,
opts?: PresetsSaveAsOptions,
): Promise<PresetsSaveResult>;
renamePreset(id: string, label: string): Promise<void>;
setPublic(id: string, value: boolean): Promise<void>;
deletePreset(id: string): Promise<void>;
/** Upsert the userConf row keyed on `${USER_CONF_PREFIX}${user}:${app}:${tableKey}`. */
upsertUserConf(
existing: AsPresetEntryRow | null,
patch: Partial<UserConfData>,
user?: string,
): Promise<void>;
}Presets session cache
Since 0.1.153. Browser-only, identity-bound cache of preset rows, capabilities and the presets db Client, keyed by (url, app, tableKey). Behaviour and guarantees: Presets — Session cache.
function setPresetsCacheMaxAge(ms: number): void; // default 30000; 0 = always revalidate on mount; < 0 = off
function invalidatePresetsCache(): void; // also runs on every `resetMetaCache()` / identity change
function isPresetsCacheActive(): boolean; // browser && identity bound && max age >= 0Building blocks for framework adapters (usePresets in @atscript/vue-table is built on them): presetsCacheKey(url, app, tableKey), cachedPresetRows(key), cachedPresetCapabilities(key), loadPresetRows(key, fetchRows, { force?, origin? }), loadPresetCapabilities(key, fetchCaps, origin?), subscribePresetsCache(key, listener), publishPresetsWrite(key), sharedPresetsClient(url, factory?, locale?) (one client per URL, factory and UI locale — locale since 0.1.168), and the PresetRows / PresetsCacheListener types.
PresetsHttpError / isUnavailableError
class PresetsHttpError extends Error {
readonly status: number;
constructor(status: number, message: string);
}
function isUnavailableError(err: unknown): boolean; // true for HTTP 401/403/404 on `ClientError` or `PresetsHttpError` (404 = presets controller not mounted). `isAuthError` is a deprecated alias (since 0.1.133).AppPrefsClient
Loads the appConf row for (user, app) — app-wide preferences like density, locale, appearance. Independent of any table; devs may use this standalone.
interface AppPrefsClientConfig {
/** Same controller URL the presets table is mounted on. */
url: string;
app: string;
client?: Client;
clientFactory?: ClientFactory;
/**
* Since 0.1.168: the UI locale to ask in, like `PresetsClientConfig.locale`.
* App prefs outlive any view: pass a getter to follow the app's locale.
*/
locale?: PresetsLocale;
}
interface AppPrefsLoadResult {
/** Full row (server-stamped id, user, timestamps), or `null`. */
row: AsPresetEntryRow | null;
/** Convenience accessor for `row.data`, or `null`. */
prefs: AppConfData | null;
/** True when the controller responded 401/403/404 (404 = controller not mounted). */
denied: boolean;
}
class AppPrefsClient {
constructor(config: AppPrefsClientConfig);
load(): Promise<AppPrefsLoadResult>;
/** Upsert the appConf row. `existing` comes from a prior `load()` so the verb is correct. Returns the row id on success. */
save(
existing: AsPresetEntryRow | null,
patch: Partial<AppConfData>,
user?: string,
): Promise<string | null>;
}See Server-Side Presets.
Query builder
buildTableQuery(opts)
Pure function that translates table UI state into a Uniquery request. Merges user filters with force filters, prepends force sorters, projects $select, applies search and the $actions flag.
interface BuildTableQueryOptions {
/** Paths of visible columns — emitted as `controls.$select`. */
visibleColumnPaths: string[];
/** User-configured sorters. */
sorters: SortControl[];
/** Always-applied sorters (prepended before user sorters). */
forceSorters?: SortControl[];
/** When true, user `sorters` are omitted from `$sort`; `forceSorters` still apply. Preserves search relevance ranking — caller computes the search-active condition. */
ignoreSorters?: boolean;
/** User-configured field filters. */
filters: FieldFilters;
/** Column-aware value encoder for `filters` (see `createColumnValueEncoder`) — dates become epoch / ISO / date bounds, boolean text a boolean. Also applied to `residualFilters` (comparison by comparison, including the elements of `$in` / `$nin`), never to `forceFilters`. Since 0.1.148. */
encodeCondition?: ConditionEncoder;
/** Residual filter conditions, AND'd after `filters`. Since 0.1.140. */
residualFilters?: FilterExpr[];
/** Always-applied Uniquery filter (AND'd with user filters). */
forceFilters?: FilterExpr;
/** Full-text search term. */
search?: string;
/** Search index name for `$search:<index>`. */
searchIndex?: string;
/** Set `controls.$actions = true` to receive per-row `$actions: string[]`. */
includeActions?: boolean;
}
function buildTableQuery(opts: BuildTableQueryOptions): Uniquery; // `Uniquery` from `@uniqu/core`mergeSorters / mergeFilters
Used by buildTableQuery to combine force + user controls; safe to call directly when composing presets / URL state.
function mergeSorters(force: SortControl[], user: SortControl[]): SortControl[];
/** AND-merge two `FilterExpr` trees, producing a wire shape that survives the Uniquery parser collapse. */
/** Variadic since 0.1.140 (`undefined` entries skipped); `mergeFilters(force, user)` still works. */
function mergeFilters(...exprs: (FilterExpr | undefined)[]): FilterExpr | undefined;URL query bridge
Two-way bridge between table state and URL query strings. Per-aspect gates (filters / sorters / search / pagination, plus the snapshot marker) are honoured symmetrically by encoder and decoder — pass the same sync config to both so the round-trip matches. A decoded snapshot: true means "restore exactly": clear every filter and sorter the gates own, then apply the URL's; without it the URL is an overlay on the table's starting filters and sorters (see Snapshot URLs).
interface UrlQueryStateLike {
filters: FieldFilters;
/** Residual filter conditions; only those whose fields the filter gate all owns are written. Since 0.1.140. */
residualFilters?: FilterExpr[];
sorters: SortControl[];
/** 1-based page number; `1` is the default and is omitted from the URL. */
page?: number;
/** Per-page size; omitted from the URL when equal to `defaultItemsPerPage`. */
itemsPerPage?: number;
/** Full-text search term; omitted when empty. */
searchTerm?: string;
/** Runtime relevance flag. Serialized as `$relevance=1|0` only while a search term is present AND the value differs from `defaultIgnoreSorters`. */
ignoreSorters?: boolean;
}
/** `"$snapshot"` — the control that marks a URL as a complete filter + sorter snapshot. Read by presence, whatever its value. Since 0.1.139. */
const URL_SNAPSHOT_KEY: "$snapshot";
interface UrlQueryStateSnapshot {
filters: FieldFilters;
sorters: SortControl[];
/** `true` when the URL carried `$snapshot`; omitted otherwise (and when `sync.snapshot` is `false`). Since 0.1.139. */
snapshot?: true;
/** Filter pieces left out of `filters` because field filters cannot express them (see `uniqueryFilterToFieldFilters`) and, since 0.1.147, every URL segment that does not parse (reason `"syntax"`, the segment in `raw` — the other segments still apply); omitted when none. The parser never warns — the caller decides. Since 0.1.139. */
unsupported?: UnsupportedFilter[];
/** Filter pieces field filters cannot express, carried as residual conditions (canonical order); omitted when none or `sync.residual` is `false`. `unsupported` then lists only the pieces left out and lost. Since 0.1.140. */
residual?: FilterExpr[];
/** Filter pieces left out because they name a field outside `knownFields` and `localFields` (a mixed piece included), with those paths. A bare `field=value` is not listed — it reads the same as a host-page flag. Omitted when none. Since 0.1.141; up to 0.1.140 a mixed piece was in `unsupported`. */
unknown?: UnknownFilter[];
/** `$sort` entries left out because their field is outside `knownFields` and `localFields`. Omitted when none. Since 0.1.141. */
unknownSorters?: SortControl[];
/** Raw `$skip` offset when present (no page math — recipients divide by their own `itemsPerPage`). */
skip?: number;
searchTerm: string;
/** Relevance flag decoded from `$relevance`; omitted when the URL carries no explicit value (recipient keeps their default). */
ignoreSorters?: boolean;
}
interface UrlQuerySync {
/** `true` / `undefined` (default): all filters. `false` / `[]`: no filters in URL. `string[]`: allowlist of field paths. */
filters?: boolean | string[];
/** Same `boolean | string[]` semantics; allowlist matches `SortControl.field`. */
sorters?: boolean | string[];
/** Round-trip `searchTerm` as `$search` (and `$relevance`, which rides under this gate). Default `true`. */
search?: boolean;
/** Round-trip pagination (`$skip`). Default `true`. */
pagination?: boolean;
/** Write `$snapshot` on every URL and honour it on read. Default `true`; `false` = neither. Since 0.1.139. */
snapshot?: boolean;
/** Carry filter pieces field filters cannot hold as residual conditions (write + decode). Default `true`; `false` = the 0.1.139 behaviour, byte for byte. Inert when `filters` is off. Since 0.1.140. */
residual?: boolean;
}
interface UrlQueryDefaults {
/** Consumer's `:limit` prop. Used to compute `$skip` and to suppress `$limit` writes. */
defaultItemsPerPage: number;
/** Per-aspect sync gates. Omitted = full sync. */
sync?: UrlQuerySync;
/** Consumer's configured `ignoreSortersWhenSearched` default. `$relevance` is emitted only when the runtime flag differs from this. Default `false`. */
defaultIgnoreSorters?: boolean;
}
interface UrlQueryParseOptions {
/** Field paths the table knows about. Conditions and sorters on fields outside this set are dropped and listed in `unknown` / `unknownSorters`. */
knownFields?: Iterable<string>;
/** Client-owned column paths: never restored, not unknown. Their sorters are ignored; a piece correlating one with a known field is `unsupported` (`"cross-field"`). Since 0.1.141. */
localFields?: Iterable<string>;
/** Per-aspect sync gates — must match the encoder's config. */
sync?: UrlQuerySync;
}
/** Tri-state resolution of a per-aspect gate: `"all"` (pass-through), `"none"` (off), or an allowlist Set. */
type AspectGate = "all" | "none" | Set<string>;
function resolveAspectGate(value: boolean | string[] | undefined): AspectGate;
/**
* Returns the URL query string (no leading `?`), ending in `$snapshot` unless
* `sync.snapshot` is `false` or neither filters nor sorters sync. The default
* view is `"$snapshot"` (`""` with the marker off; `""` always up to 0.1.138).
*/
function stateToUrlQueryString(state: UrlQueryStateLike, defaults: UrlQueryDefaults): string;
/** Robust by design — schema drift never breaks the recipient's view. */
function urlQueryStringToState(
urlString: string,
opts?: UrlQueryParseOptions,
): UrlQueryStateSnapshot;
/** Is the URL authoritative for this field under `gate`? */
function gateOwns(gate: AspectGate, path: string): boolean;gateOwns
Since 0.1.137. The companion to resolveAspectGate, and the single place the tri-state is decided: "all" owns every path, an allowlist owns exactly its members, "none" owns nothing.
"Owns" means the URL is authoritative for that field — it serializes the field on write, and on read its silence about the field is meaningful. Both directions need the same answer or the URL self-echoes: the encoder writes only owned fields, and a history restore must clear the owned ones before overlaying the URL, or a filter the user removed survives the Back that should have removed it. applyUrlQuery(url, { mode: "replace" }) in @atscript/vue-table is the main external consumer; a custom renderer restoring its own state from a URL needs it for the same reason.
urlQueryConsumesKey
function urlQueryConsumesKey(key: string): boolean;Since 0.1.133. true for the keys urlQueryStringToState would read: the $sort / $search / $relevance / $skip / $snapshot (since 0.1.139) controls and operator-bearing filter keys (total>100; since 0.1.140 also groups and lists — keys containing (, ), ^, {, }). useTableUrlQuery treats exactly these (plus keys it wrote itself) as table-owned; everything else in the query is host-owned and preserved.
See URL State.
URL query records
Since 0.1.148. Pure helpers between the table's query string and a router's query record ({ [key]: string | null | (string | null)[] }) — reusable from any framework, for links and custom bridges. useTableUrlQuery is built on them.
type UrlQueryRecord = Record<string, string | null | (string | null)[]>;
/** What the helpers read — vue-router's `LocationQuery` fits. */
type UrlQueryRecordInput = Readonly<
Record<string, string | null | readonly (string | null)[] | undefined>
>;
interface UrlQueryRecordOptions {
/** Own keys are `<prefix>.<key>` — same meaning as the bridge's `prefix`. */
prefix?: string;
/**
* Host keys (wire form) the table never reads, writes or removes, even when
* a column has the same name; covers the operator forms of the field
* (`status!='x'`). A list or a predicate.
*/
preserveKeys?: readonly string[] | ((key: string) => boolean);
}
/** Route query → the table's query string (prefix-filtered, preserved keys skipped, arrays expanded). */
function urlQueryRecordToString(query: UrlQueryRecordInput, opts?: UrlQueryRecordOptions): string;
/** The record for a table state — for links: `<RouterLink :to="{ query: stateToUrlQueryRecord(state, defaults) }">`. */
function stateToUrlQueryRecord(
state: UrlQueryStateLike,
defaults: UrlQueryDefaults,
opts?: UrlQueryRecordOptions,
): UrlQueryRecord;Selection
type SelectionMode = "none" | "single" | "multi";
function togglePk(
selection: readonly unknown[],
pk: unknown,
mode: SelectionMode,
/** Compare by identity instead of reference (e.g. a query selection's excluded rows). Since 0.1.147. */
keyOf?: (value: unknown) => unknown,
): unknown[];
function trimSelection(set: unknown[], pks: Iterable<unknown>): unknown[];
function rowsToPks(
rows: Record<string, unknown>[],
rowValueFn: (row: Record<string, unknown>) => unknown,
): unknown[];togglePk returns a new array — never mutates. trimSelection drops any selected pk not present in pks (used when the row set narrows).
Query selection helpers (since 0.1.147 — the framework-agnostic half of Select All Matching Rows):
interface SelectionQuery {
filter?: FilterExpr;
search?: string;
index?: string;
}
function selectionQueryOf(query: Uniquery): SelectionQuery;
function selectionSignature(query: SelectionQuery): string;selectionQueryOf keeps a table query's filter and $search / $search:<index> term — sorting, projection and paging are left out. selectionSignature is a stable string of it (keys sorted at every depth, empty parts dropped, RegExp / Date spelled out): a change of the live signature is what drops a query selection. To flip one row in the excluded list, use togglePk(excluded, pk, "multi", keyOf).
State contracts
ConfigTab, TableStateData, and TableStateMethods are the framework-agnostic contracts that the Vue ReactiveTableState implements. Reuse them when writing a React/Svelte port so the rest of @atscript/ui-table keeps working.
type ConfigTab = "columns" | "filters" | "sorters";
interface TableStateData {
tableDef: TableDef | null;
columnNames: string[];
allColumns: ColumnDef[];
columnWidths: ColumnWidthsMap;
filterFields: string[];
filters: FieldFilters;
/** AND-ed conditions field filters cannot hold. Since 0.1.140. */
residualFilters: FilterExpr[];
sorters: SortControl[];
searchTerm: string;
pagination: PaginationControl;
selectedRows: unknown[];
results: Record<string, unknown>[];
totalCount: number;
// ...
}
interface TableStateMethods {
query(): Promise<void>;
loadRange(from: number, to: number): Promise<void>;
setColumnNames(names: string[]): void;
setColumnWidths(widths: ColumnWidthsMap): void;
setFilters(filters: FieldFilters, fields?: string[]): void;
/** Since 0.1.140. `resetFilters()` clears these too. */
setResidualFilters(exprs: FilterExpr[]): void;
removeResidualFilter(index: number): void;
setSorters(sorters: SortControl[]): void;
setSearchTerm(value: string): void;
setPagination(p: PaginationControl): void;
setSelectedRows(rows: unknown[]): void;
applyUrlQuery(urlString: string, opts?: { mode?: "merge" | "replace" }): void;
// ...
}The full mutator list mirrors ReactiveTableState in @atscript/vue-table — see that page for the complete enumeration with reactive types.
Window mode helpers
Used by <AsWindowTable> to compute page-aligned fetch ranges and merge incoming results into the universal cache.
const DEFAULT_ROW_HEIGHT_PX: number;
interface PageAlignedBlock {
/** 1-based page number, ready to pass to a server pagination param. */
page: number;
/** Index of the first row in the block. */
firstIndex: number;
}
function pageAlignedBlocksFor(skip: number, limit: number, blockSize: number): PageAlignedBlock[];
function blockStartFor(absIdx: number, blockSize: number): number;
function clampTopIndex(topIndex: number, totalCount: number, viewport: number): number;
interface MergeResult {
/* ... */
}
function walkForwardAbsorb(results: MergeResult): void;
function walkBackwardAbsorb(results: MergeResult): void;
/** `"jump"` — viewport sits in uncached territory; centre a fetch around it. `"steady"` — fetch one block at the edge that's running out. */
type FetchPlanMode = "jump" | "steady";
interface FetchPlan {
skip: number;
limit: number;
mode: FetchPlanMode;
}
interface PlanFetchArgs {
top: number;
viewport: number;
totalCount: number;
cache: Map<number, unknown>;
blockSize: number;
/** Threshold below which a steady prefetch fires. Typically `blockSize / 4`. */
buffer: number;
}
function planFetch(args: PlanFetchArgs): FetchPlan | null;planFetch is the centerpiece: given the viewport and the universal-cache state, it returns the single fetch the renderer should issue next (or null when the cache already satisfies the visible range).
Column widths
interface ColumnWidthEntry {
w: string; // current rendered width
d: string; // computed default
}
type ColumnWidthsMap = Record<string, ColumnWidthEntry>;
const MAX_DEFAULT_COLUMN_WIDTH_PX: number;
function computeDefaultColumnWidth(column: ColumnDef): string;
function reconcileColumnWidthDefaults(
current: ColumnWidthsMap,
columns: ColumnDef[],
): ColumnWidthsMap;computeDefaultColumnWidth prefers @ui.table.width, falls back to type + @expect.maxLen, clamps to MAX_DEFAULT_COLUMN_WIDTH_PX. reconcileColumnWidthDefaults is called whenever the column set changes so widths stay populated for every visible column.
Display columns
Client-owned columns an app adds on top of the server's /meta columns. Since 0.1.134 — see Display-only columns.
interface DisplayColumnDef {
/** Stable key; becomes the column's `path`. Must not collide with a field path. */
key: string;
label: string;
width?: string;
/** Position among the server columns (lower = earlier). Appended when omitted. */
order?: number;
/**
* `'local'` sorts client-side over the loaded page; anything else leaves it
* unsortable. Paged tables only — `<AsWindowTable>` does not offer it.
*/
sortable?: false | "local";
/** Value `sortable: 'local'` orders by. Without it the sorter reads `row[key]`. */
sortValue?: (row: Record<string, unknown>) => unknown;
component?: string;
/** Default `"text"`. */
type?: string;
}
/** Merge into the server's column list, ordered by `order`; stable, so ties keep `/meta` order. Returns `base` when `display` is empty. */
function mergeDisplayColumns(base: ColumnDef[], display: readonly DisplayColumnDef[]): ColumnDef[];ColumnDef gained one optional flag for these: local — never in $select, server sort or filters. A local column with sortable: true is ordered in memory.
Export
Framework-agnostic halves of useTableExport — usable without Vue. Since 0.1.134; full guide: Export.
The CSV writer (toCsv, csvCell, CsvOptions, ExportScalar) is also exported from @atscript/ui-table/csv (since 0.1.164), which imports nothing — for a server that writes CSV without loading the table engine. See Writing CSV on the server.
type ExportScalar = string | number | boolean | null;
interface CsvOptions {
/** Prepend a UTF-8 BOM (Excel needs it to detect UTF-8). Default `false`. */
bom?: boolean;
/** Prefix `=` / `+` / `-` / `@` / TAB / CR STRING cells with `'`. Numbers stay numeric. Default `true`. */
escapeFormulas?: boolean;
/** Default `","`. */
delimiter?: string;
}
/** One RFC 4180 field: formula-escaped, then quoted when it holds the delimiter, a quote, CR or LF. */
function csvCell(value: ExportScalar | undefined, opts?: CsvOptions): string;
/** Header + rows to a CSV string — `\r\n` separators, trailing newline, optional BOM. */
function toCsv(
header: readonly string[],
rows: readonly (readonly ExportScalar[])[],
opts?: CsvOptions,
): string;const DEFAULT_EXPORT_PAGE_SIZE = 500;
/** Rejection raised when an export is cancelled. `name === "AbortError"`. */
class ExportAbortError extends Error {}
type ExportPageFetcher = (
query: Uniquery,
page: number,
size: number,
) => Promise<{ data: Record<string, unknown>[]; count?: number }>;
/**
* Append the primary key(s) to `$sort` as a tiebreaker so paging can neither
* skip nor duplicate rows. Existing sort fields are preserved; returns the
* input query when there is nothing to add. Never mutates.
*/
function withStableOrder(query: Uniquery, primaryKeys: readonly string[]): Uniquery;
/**
* Page through `query` until a short page, the reported `count`, or `maxRows`.
* `signal` is checked before and after every request, so a cancel lands
* between pages.
*/
function collectExportRows<T = Record<string, unknown>>(opts: {
query: Uniquery;
pageSize?: number;
fetchPage: ExportPageFetcher;
signal?: AbortSignal;
onProgress?: (done: number, total?: number) => void;
maxRows?: number;
/** Project each row as it arrives; the result holds the projections, not the raw rows. */
mapRow?: (row: Record<string, unknown>) => T;
}): Promise<{ rows: T[]; total?: number }>;/**
* Resolve a raw cell value to the scalar an export carries, using the same
* column metadata the cells read: union/enum keys → labels, `Date` → ISO 8601,
* arrays joined, other objects JSON, `null`/`undefined` → `null`.
*/
function resolveExportValue(value: unknown, column?: ColumnDef): ExportScalar;Utilities
/** Sort rows in memory: numeric when both sides are numbers, locale-aware otherwise. Returns a NEW array, or the input when there is nothing to sort. Since 0.1.134. */
function sortRowsLocally<T extends Record<string, unknown>>(
rows: T[],
sorters: readonly SortControl[],
getValue?: (row: T, field: string) => unknown,
): T[];
/** The text a cell compares and matches by — `""` for objects, so `[object Object]` never drives an ordering. Since 0.1.134. */
function cellAsString(value: unknown): string;
function debounce<T extends (...args: any[]) => unknown>(fn: T, ms: number): T & { cancel(): void };
function arraysEqual<T>(a: readonly T[], b: readonly T[]): boolean;
function sameColumnSet(a: readonly string[], b: readonly string[]): boolean;
function setsEqual<T>(a: ReadonlySet<T>, b: ReadonlySet<T>): boolean;
function sortersEqual(a: readonly SortControl[], b: readonly SortControl[]): boolean;
/** `true` outside a production build (`process.env.NODE_ENV !== "production"`, replaced by bundlers) — the gate for dev-only warnings. Since 0.1.139. */
const DEV: boolean;
type ColumnReorderPosition = "before" | "after";
/** Pure — returns a new array. Returns input unchanged when paths are missing or the move is a no-op. */
function reorderColumnNames(
names: string[],
fromPath: string,
toPath: string,
position: ColumnReorderPosition,
): string[];Cross-links
- Tables — Filtering
- Tables — Sorting
- Tables — Pagination & Virtualization
- Tables — Presets
- Tables — URL State
- Tables — Export
- @atscript/vue-table — Vue-side
ReactiveTableState - @atscript/moost-ui-presets — server endpoint