Skip to content

@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 ​

FilterConditionType ​

Canonical operator names used in filter conditions. bw ("between") is the range operator — there is no separate between alias.

typescript
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.

typescript
interface FilterCondition {
  type: FilterConditionType;
  value: (string | number | boolean)[];
}

FieldFilters ​

Per-field map of applied conditions. The framework treats absence and empty array as equivalent.

typescript
type FieldFilters = Record<string, FilterCondition[]>;

Condition helpers ​

typescript
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 ​

typescript
/** `"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.

typescript
/**
 * 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).

typescript
/**
 * `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.

typescript
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.

typescript
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 Date

Presets — 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.

typescript
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 ​

typescript
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) ​

typescript
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 ​

typescript
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 ​

typescript
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 }).

typescript
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 ​

typescript
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.

typescript
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.

typescript
/** 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.

typescript
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.

typescript
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 >= 0

Building 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 ​

typescript
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.

typescript
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.

typescript
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.

typescript
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).

typescript
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 ​

typescript
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.

typescript
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 ​

typescript
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):

typescript
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.

typescript
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.

typescript
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 ​

typescript
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.

typescript
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.

typescript
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;
typescript
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 }>;
typescript
/**
 * 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 ​

typescript
/** 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[];

Released under the MIT License.