@pythia-software/query-table-core 0.2.0 → 0.3.0

package/README.md

@@ -40,5 +40,13 @@ Query state is bounded whenever it crosses the library's URL, storage, or
 server-projection boundaries. SQL expressions remain trusted server-side schema
 configuration; request values are never SQL fragments.
 
+Text filters include `matches_regex` / `not_matches_regex`. An order term may
+set `extract: { regex: "..." }` to compare the first capture group (or the whole
+match when there is no capture group); non-matches sort as nulls.
+
 See the [repository README](https://github.com/Pythia-Software/query-table#readme)
 for the complete schema and backend documentation.
+
+## Computed SELECT definitions
+
+Exports include `ComputedColumnStore`, `httpComputedColumnStore`, `memoryComputedColumnStore`, `compileFormula`, `FORMULA_FUNCTIONS`, and `formulaRuntime`. Shared source definitions are versioned separately from queries; query SELECT entries use `{ field: "@computed/<id>" }`. The React package executes the interpreter in a bounded worker. Do not run user regex on the browser main thread. See the repository’s `docs/computed-columns.md` for semantics and persistence details.

package/dist/index.d.ts

@@ -1,15 +1,42 @@
 /** All filter operators across both source projects, unioned. Every value can
  *  be NULL, so `is_null`/`is_not_null` are valid for every field type. */
-type FilterOp = "=" | "!=" | ">" | ">=" | "<" | "<=" | "contains" | "starts_with" | "ends_with" | "includes" | "is_null" | "is_not_null";
-/** A single AND-combined filter. `value` is always the raw string the UI
- *  captured; coercion to number/bool/date happens at apply/compile time based on
- *  the field's declared type (never on the value's runtime shape). Unused for
- *  the nullary ops (`is_null`/`is_not_null`). */
+type FilterOp = "=" | "!=" | ">" | ">=" | "<" | "<=" | "contains" | "starts_with" | "ends_with" | "matches_regex" | "not_matches_regex" | "includes" | "is_null" | "is_not_null";
+/** A single filter predicate (a "literal" in CNF terms). `value` is always the
+ *  raw string the UI captured; coercion to number/bool/date happens at
+ *  apply/compile time based on the field's declared type (never on the value's
+ *  runtime shape). Unused for the nullary ops (`is_null`/`is_not_null`).
+ *
+ *  `negated` wraps the predicate in a logical NOT. It is only ever set for ops
+ *  that have no complementary operator (`contains`/`starts_with`/`ends_with`/
+ *  `includes`); ops with a complement negate by flipping the op itself (`>=`→`<`,
+ *  `=`→`!=`, `is_null`→`is_not_null`, `matches_regex`→`not_matches_regex`) — see
+ *  `negateClause` in ops.ts. NOT is null-exclusive: a NULL/empty value satisfies
+ *  neither the predicate nor its negation, matching `not_matches_regex`. */
 interface WhereClause {
     field: string;
     op: FilterOp;
     value: string;
+    negated?: boolean;
+}
+/** A disjunction of predicates — the inner OR of conjunctive normal form. Every
+ *  member is a plain literal; nesting is intentionally not allowed yet (CNF
+ *  only), but the object shape leaves room to grow. */
+interface OrGroup {
+    any: WhereClause[];
 }
+/** One conjunct of the WHERE clause: either a single predicate or an OR group.
+ *  `QueryState.where` is the AND of these terms, so the whole WHERE is
+ *  conjunctive normal form — `(a) AND (b OR c) AND (d)`. A bare literal is
+ *  equivalent to a one-element OR group; normalization flattens singleton groups
+ *  back to a literal so equality/encoding stay canonical. */
+type WhereTerm = WhereClause | OrGroup;
+/** Narrow a term to an OR group. A literal always carries `field`; a group never
+ *  does and always carries an `any` array. */
+declare function isOrGroup(term: WhereTerm): term is OrGroup;
+/** The predicate literals a term contributes, in order: the term itself for a
+ *  literal, or its members for a group. Handy for anything that must visit every
+ *  predicate regardless of grouping (field allowlisting, SELECT projection). */
+declare function predicatesOf(term: WhereTerm): WhereClause[];
 /** One ORDER BY term. Array order in `QueryState.orderBy` is the sort priority. */
 interface OrderByClause {
     field: string;
@@ -17,6 +44,14 @@ interface OrderByClause {
     /** NULL placement. Omitted = "last" (the historical default both projects used,
      *  preserved so old `?q=` links round-trip identically). */
     nulls?: "first" | "last";
+    /** Sort by the first capture group of a regex match (or by the whole match
+     *  when the pattern has no capture group). A non-match produces NULL. Regex
+     *  syntax is interpreted by the executor (JavaScript locally, PostgreSQL on
+     *  the bundled Go backend), so portable patterns should use their common
+     *  syntax subset. */
+    extract?: {
+        regex: string;
+    };
 }
 /** One column in the SELECT list, plus the view state that travels with it.
  *  Order in `QueryState.select` is the left-to-right display order. */
@@ -53,8 +88,10 @@ interface AggregationClause {
 interface QueryState {
     /** Ordered SELECT list + per-column widths. Empty = the schema's default columns. */
     select: SelectColumn[];
-    /** AND-combined filters. */
-    where: WhereClause[];
+    /** WHERE in conjunctive normal form: the AND of these terms, each a single
+     *  predicate or an OR group. A flat list of literals (no groups) is the common
+     *  case and the legacy shape, decoded unchanged. */
+    where: WhereTerm[];
     /** Multi-sort terms in priority order. Empty = the schema's default sort. */
     orderBy: OrderByClause[];
     /** Page size. */
@@ -117,6 +154,10 @@ interface BackendField {
  *  pushed to the server; client-side filtering/sorting (if any) reads `accessor`. */
 interface DerivedField<Row = any, V = unknown> {
     kind: "derived";
+    /** Backend inputs required for accessors and computed formulas. */
+    dependencies?: string[];
+    /** Reusable computed column ID; always select-only. */
+    computedId?: string;
     /** Compute the value from the row for client filter/sort. Omit for render-only
      *  columns (the renderer reads the whole row from CellContext instead). */
     accessor?: (row: Row) => V;
@@ -222,6 +263,35 @@ declare function readFieldValue<Row, V = unknown>(field: FieldDef<Row, V>, row:
  *  renderer at runtime. Throws with a readable message on a malformed document. */
 declare function loadSchema<Row = any>(doc: unknown): FieldSchema<Row>;
 
+/** The logical negation of a predicate. Prefers flipping to the complementary
+ *  operator (nicer to read, and the server's op allowlist already covers it);
+ *  falls back to toggling the `negated` flag when the op has no complement, or
+ *  when the complement is not in `allowedOps` (a field's `filter.ops` override
+ *  could disable it, and the server would reject a disabled op). `allowedOps`,
+ *  when given, is the field's effective operator set from `opsForField`. */
+declare function negateClause(clause: WhereClause, allowedOps?: readonly FilterOp[]): WhereClause;
+/** Whether a predicate is negative — either an op that reads as a negation
+ *  (`!=`, `not_matches_regex`, `is_not_null`) or one carrying the `negated`
+ *  flag. Used to sort candidate filters into the CellMenu's two columns. */
+declare function isNegativePredicate(clause: Pick<WhereClause, "op" | "negated">): boolean;
+/** A specific operator + negation state, e.g. `{ op: "<", negated: false }` or
+ *  `{ op: "contains", negated: true }`. */
+interface OpChoice {
+    op: FilterOp;
+    negated: boolean;
+}
+/** A positive operator ("keep") and its logical negation ("exclude") — the row
+ *  shape rendered by both the CellMenu quick-filters and the WHERE operator
+ *  picker, so the two read identically. */
+interface OpPair {
+    keep: OpChoice;
+    exclude: OpChoice;
+}
+/** The keep/exclude operator pairs offered for a field: each positive op with
+ *  its negation opposite, then a nullity row (`is null`/`is not null`) when the
+ *  field allows it. Derived from the field's effective op set and `negateClause`,
+ *  so a `filter.ops` override narrows the offered pairs too. */
+declare function opPairsForField(field: Pick<FieldDef, "type" | "filter">): OpPair[];
 /** Default operator set per type. A FieldDef.filter.ops overrides this. */
 declare const OPS_BY_TYPE: Record<FieldType, FilterOp[]>;
 /** Operators that take no value (the value input is hidden). */
@@ -269,8 +339,8 @@ declare function decodeQuery(token: string): QueryState;
 interface ServerQuery {
     /** field names to return — visible columns ∪ fields referenced by where/orderBy. */
     select: string[];
-    /** only clauses on pushdown-filterable fields. */
-    where: WhereClause[];
+    /** only terms whose every predicate is on a pushdown-filterable field. */
+    where: WhereTerm[];
     /** only terms on server-sortable fields, with `field` already remapped to the
      *  field's server sort key (FieldDef.sort.field) when set. */
     orderBy: OrderByClause[];
@@ -285,7 +355,7 @@ declare function toServerQuery<Row>(q: QueryState, schema: FieldSchema<Row>): Se
  *  metrics describe every matching row, not the visible page. Mirrors the Go
  *  AggSpec list. */
 interface AggregationRequest {
-    where: WhereClause[];
+    where: WhereTerm[];
     aggregations: AggregationClause[];
 }
 /** One group's result. `keys` has one entry per AggregationClause.groupBy field,
@@ -420,4 +490,117 @@ declare function memoryStorageAdapter(): StorageAdapter;
  * datasets. Falls back to no persistence when storage is unavailable. */
 declare function localStorageAdapter(): StorageAdapter;
 
-export { AGG_OPS_BY_TYPE, AGG_OPS_NEEDING_FIELD, type AggOp, type AggregateConfig, type AggregationBucket, type AggregationClause, type AggregationRequest, type AggregationResult, type AggregationResultEntry, type Align, type ApplyResult, type BackendField, type CellRenderer, type DerivedField, type DistinctValuesQuery, type DistinctValuesResult, EMPTY_QUERY, type FetchRowsResult, type FieldDef, type FieldSchema, type FieldSource, type FieldStats, type FieldType, type FilterConfig, type FilterOp, type FilterValues, MAX_AGGREGATIONS, MAX_GROUP_BY_FIELDS, MAX_ORDER_BY_TERMS, MAX_QUERY_LIMIT, MAX_QUERY_OFFSET, MAX_QUERY_TOKEN_LENGTH, MAX_SELECT_COLUMNS, MAX_WHERE_CLAUSES, NULLARY_OPS, OPS_BY_TYPE, type OrderByClause, type QueryState, type RowId, type SavedQuery, type SelectColumn, type SelectConfig, type ServerQuery, type SortConfig, type StorageAdapter, type Transport, type WhereClause, aggOpAllowedForType, aggOpNeedsField, aggOpsForField, applyAggregations, applyQuery, coerceValue, decodeQuery, encodeQuery, filterValues, indexFields, isFilterable, isGroupable, isMeasurable, isPushdownFilter, isSelectable, isSortable, loadSchema, localStorageAdapter, matchesClause, memoryStorageAdapter, normalizeQueryState, opAllowedForType, opsForField, queriesEqual, readFieldValue, selectedFields, toAggregationQuery, toServerQuery };
+type FormulaType = Exclude<FieldType, "enum"> | "null";
+type FormulaValue = string | number | boolean | string[] | null;
+interface FormulaDiagnostic {
+    message: string;
+    from: number;
+    to: number;
+}
+type FormulaNode = {
+    kind: "literal";
+    value: FormulaValue;
+    from: number;
+    to: number;
+} | {
+    kind: "field";
+    name: string;
+    valueType?: FormulaType;
+    from: number;
+    to: number;
+} | {
+    kind: "call";
+    name: string;
+    args: FormulaNode[];
+    from: number;
+    to: number;
+};
+interface FormulaPlan {
+    ast: FormulaNode;
+    dependencies: string[];
+    type: FormulaType;
+}
+interface RegexInspection {
+    input: string;
+    start: number;
+    end: number;
+    groups: (string | null)[];
+}
+interface FormulaResult {
+    value: FormulaValue;
+    error?: string;
+    regex?: RegexInspection;
+}
+interface FormulaFunction {
+    name: string;
+    signature: string;
+    description: string;
+    min: number;
+    max: number;
+    result: FormulaType | "branch";
+    args: FormulaType[] | "any";
+}
+declare const FORMULA_FUNCTIONS: FormulaFunction[];
+declare class FormulaError extends Error {
+    from: number;
+    to: number;
+    constructor(message: string, from?: number, to?: number);
+}
+declare function compileFormula(source: string, fields: readonly {
+    name: string;
+    type: FieldType;
+}[], resolve?: (name: string) => FormulaPlan | undefined): FormulaPlan;
+/** Self-contained runtime: serialized into the browser worker, never user code. */
+declare function formulaRuntime(ast: FormulaNode, inputs: Record<string, FormulaValue>): FormulaResult;
+
+/** Reserved field token namespace. Query state stores IDs, never formula source. */
+declare const COMPUTED_PREFIX = "@computed/";
+declare const computedFieldName: (id: string) => string;
+declare const isComputedField: (name: string) => boolean;
+interface ComputedColumn {
+    id: string;
+    label: string;
+    expression: {
+        language: "qt-expr";
+        version: 1;
+        source: string;
+    };
+    /** Optimistic concurrency token issued by the store. */
+    revision: string;
+}
+type ComputedColumnDraft = Omit<ComputedColumn, "revision">;
+interface ComputedColumnStore {
+    /** Return the complete authorized catalogue for this dataset. */
+    list(dataset: string, signal?: AbortSignal): Promise<ComputedColumn[]>;
+    /** null creates a new ID; updates must match the current revision. */
+    save(dataset: string, column: ComputedColumnDraft, expectedRevision: string | null): Promise<ComputedColumn>;
+    /** Optional push invalidation, including changes from other sessions. */
+    subscribe?(dataset: string, listener: () => void): () => void;
+}
+declare function validateComputedColumn(input: unknown): ComputedColumn;
+declare function memoryComputedColumnStore(seed?: Record<string, ComputedColumn[]>): ComputedColumnStore;
+/** REST adapter. The implementing server owns authorization and DB persistence.
+ * GET base?dataset=… → ComputedColumn[]
+ * PUT base?dataset=… → {column, expectedRevision} → ComputedColumn
+ * Return HTTP 409 for a stale revision. No formula evaluation happens there. */
+declare function httpComputedColumnStore(base: string, fetcher?: typeof fetch): ComputedColumnStore;
+interface ComputedCellError {
+    computedError: string;
+}
+declare function isComputedCellError(value: unknown): value is ComputedCellError;
+interface PreviewGroup {
+    inputs: FormulaValue[];
+    result: FormulaResult;
+    count: number;
+}
+interface ColumnPreview {
+    dependencies: string[];
+    groups: PreviewGroup[];
+    processed: number;
+    total: number;
+    nulls: number;
+    errors: number;
+}
+declare function groupPreview(dependencies: string[], inputs: Record<string, FormulaValue>[], results: FormulaResult[], total: number): ColumnPreview;
+
+export { AGG_OPS_BY_TYPE, AGG_OPS_NEEDING_FIELD, type AggOp, type AggregateConfig, type AggregationBucket, type AggregationClause, type AggregationRequest, type AggregationResult, type AggregationResultEntry, type Align, type ApplyResult, type BackendField, COMPUTED_PREFIX, type CellRenderer, type ColumnPreview, type ComputedCellError, type ComputedColumn, type ComputedColumnDraft, type ComputedColumnStore, type DerivedField, type DistinctValuesQuery, type DistinctValuesResult, EMPTY_QUERY, FORMULA_FUNCTIONS, type FetchRowsResult, type FieldDef, type FieldSchema, type FieldSource, type FieldStats, type FieldType, type FilterConfig, type FilterOp, type FilterValues, type FormulaDiagnostic, FormulaError, type FormulaFunction, type FormulaNode, type FormulaPlan, type FormulaResult, type FormulaType, type FormulaValue, MAX_AGGREGATIONS, MAX_GROUP_BY_FIELDS, MAX_ORDER_BY_TERMS, MAX_QUERY_LIMIT, MAX_QUERY_OFFSET, MAX_QUERY_TOKEN_LENGTH, MAX_SELECT_COLUMNS, MAX_WHERE_CLAUSES, NULLARY_OPS, OPS_BY_TYPE, type OpChoice, type OpPair, type OrGroup, type OrderByClause, type PreviewGroup, type QueryState, type RegexInspection, type RowId, type SavedQuery, type SelectColumn, type SelectConfig, type ServerQuery, type SortConfig, type StorageAdapter, type Transport, type WhereClause, type WhereTerm, aggOpAllowedForType, aggOpNeedsField, aggOpsForField, applyAggregations, applyQuery, coerceValue, compileFormula, computedFieldName, decodeQuery, encodeQuery, filterValues, formulaRuntime, groupPreview, httpComputedColumnStore, indexFields, isComputedCellError, isComputedField, isFilterable, isGroupable, isMeasurable, isNegativePredicate, isOrGroup, isPushdownFilter, isSelectable, isSortable, loadSchema, localStorageAdapter, matchesClause, memoryComputedColumnStore, memoryStorageAdapter, negateClause, normalizeQueryState, opAllowedForType, opPairsForField, opsForField, predicatesOf, queriesEqual, readFieldValue, selectedFields, toAggregationQuery, toServerQuery, validateComputedColumn };