Schema and types

A schema is an object of fields built with f, passed through defineFields. defineFields pins literal types (so 'free' | 'pro' stays a union, not string), flattens struct fields into dotted paths, and attaches custom operators, functions and messages to the field set.

import { defineFields, f } from '@qnot/core';

export const fields = defineFields({
  name: f.text({ minLength: 2 }),
  age: f.number({ min: 0, max: 130, integer: true }),
  plan: f.enum(['free', 'pro', 'team']),
  tags: f.multiEnum(['vip', 'beta', 'churned']),
  verified: f.boolean(),
  signedUp: f.date({ label: 'Signed up' }),
  opensAt: f.time(),
  address: f.struct({ city: f.text(), zip: f.text({ column: 'postal_code' }) }),
  orders: f.array({ product: f.text(), qty: f.number() }),
});

Field kinds

Every builder takes common options: label, description, column (the name exporters use), operators (restrict and order), excludeOperators, extraOperators (custom ones), defaultOperator, defaultValue, required (default true), hidden (not offered in pickers), comparable (can be compared against, default true), validate, and UI hints (widget, placeholder, prefix, suffix, meta). See Field builders.

Enum options can be plain values or { value, label } objects, and can nest with children for a tree select. leafOnly: true makes parents unselectable:

f.enum([
  { value: 'emea', label: 'EMEA', children: [{ value: 'de', label: 'Germany' }, { value: 'fr', label: 'France' }] },
  { value: 'amer', label: 'Americas', children: [{ value: 'us', label: 'United States' }] },
], { leafOnly: true });

The query shape

A query is a tree of groups and rules. It's plain JSON, so you can store it anywhere.

{
  kind: 'group',
  combinator: 'and',        // or 'or'
  not: true,                // optional: negate the group
  children: [
    { kind: 'rule', field: 'age', operator: 'gte', value: 21 },
    { kind: 'rule', field: 'age', operator: 'gt', ref: 'minAge' },          // compare with another field
    { kind: 'rule', field: 'signedUp', operator: 'gt',
      call: { fn: 'relativeDate', args: { amount: { value: 7 }, unit: { value: 'day' }, direction: { value: 'ago' } } } },
    { kind: 'group', combinator: 'or', children: [ /* … */ ] },
  ],
}

A rule's right side is exactly one of value (a literal), ref (another field) or call (a function). Its shape follows the operator: nothing for isNull, one value for eq, a pair for between, a list for in.

Types

QueryOf<typeof fields> is the query typed against your schema. Rules are a discriminated union over every field and operator, so checking field and operator narrows value:

declare const rule: RuleOf<typeof fields>;

if (rule.field === 'age' && rule.operator === 'between' && isLiteralRule(rule)) {
  rule.value;
       
value: readonly [number | null, number | null]
}

isLiteralRule rules out field refs and function calls, which carry no value. Mistakes are compile errors:

const bad: RuleOf<typeof fields> = { kind: 'rule', field: 'plan', operator: 'eq', value: 'gold' };
Type '{ kind: "rule"; field: "plan"; operator: "eq"; value: "gold"; }' is not assignable to type 'FnRule | (RuleMeta & { readonly kind: "rule"; readonly field: "age"; readonly operator: "isNotNull"; readonly value?: null | undefined; readonly ref?: undefined; readonly call?: undefined; }) | ... 24 more ... | (RuleMeta & { ...; })'.
  Types of property 'value' are incompatible.
    Type '"gold"' is not assignable to type '"free" | "pro" | null | undefined'.

Drafts and strict queries

While someone is typing, values can be missing, so QueryOf allows null in value slots. Once a query passes validation it can be narrowed to StrictQueryOf, where they can't:

if (isValidQuery(fields, query)) {
  const first = query.children[0];
  if (first?.kind === 'rule' && first.operator === 'eq' && isLiteralRule(first)) {
    first.value;
          
value: number
  }
}

Rows

RowOf<typeof fields> is the record shape a query is evaluated against. Struct paths become nested objects and array fields become lists of their element rows. compile() uses it for its argument type.