Core API

Fields

Field unions

export type BuilderFieldType =
  | 'BOOLEAN'
  | 'TEXT'
  | 'DATE'
  | 'NUMBER'
  | 'STATEMENT'
  | 'LIST'
  | 'MULTI_LIST'
  | 'GROUP';

export type IBuilderFieldProps =
  | IBooleanFieldProps
  | ITextFieldProps
  | IDateFieldProps
  | INumberFieldProps
  | IStatementFieldProps
  | IListFieldProps
  | IMultiListFieldProps
  | IGroupFieldProps;

Shared field shape

interface IBuilderFieldBase<TType, TValue, TValidation> {
  field: string;
  label: string;
  value?: TValue;
  type: TType;
  operators?: BuilderFieldOperator[];
  usageLimit?: IBuilderFieldUsageLimit;
  validation?: TValidation;
  fieldComparison?: IBuilderFieldComparisonConfig;
}

Field usage limits

export type BuilderFieldUsageLimitScope = 'global' | 'parent';

export interface IBuilderFieldUsageLimit {
  key?: string;
  max: number;
  scope?: BuilderFieldUsageLimitScope;
  message?: BuilderValidationMessage;
}

Field comparison config

export type BuilderFieldComparisonType =
  | 'string'
  | 'number'
  | 'date'
  | 'boolean';

export interface IBuilderFieldComparisonConfig {
  type?: BuilderFieldComparisonType;
  comparableFields?: string[];
}

Imperative option types

export type BuilderFieldOption = {
  value: string | number;
  label: string;
};

export type BuilderFieldOptionsStatus =
  | 'idle'
  | 'loading'
  | 'success'
  | 'error';

export interface IBuilderFieldOptionState {
  options: BuilderFieldOption[];
  status: BuilderFieldOptionsStatus;
}

export interface IBuilderRuleValueReconciliationConfig {
  strategy: 'clear-if-missing';
}

export interface IBuilderRuleDependencyEntry {
  ruleId: string;
  dependencies: Record<string, INearestFieldMatch | undefined>;
}

export type IBuilderFieldDependencyEntry = IBuilderRuleDependencyEntry;

export interface INearestFieldMatch {
  nodeId: string;
  field: string;
  valueSource?: QueryRuleValueSource;
  value: QueryRuleValue | undefined;
  valueField?: string;
  operator?: QueryOperator;
}

export interface IBuilderFieldChange {
  nodeId: string;
  field: string;
  previousValueSource?: QueryRuleValueSource;
  previousValue: QueryRuleValue | undefined;
  previousValueField?: string;
  valueSource?: QueryRuleValueSource;
  value: QueryRuleValue | undefined;
  valueField?: string;
  data: DenormalizedQuery;
};

Props

field Required stable identifier used in query data and conversion helpers.
label Required user-facing caption shown in the field selector.
type Required field type. This controls which widget and value semantics are used.
value Optional default or backing field value metadata. For LIST and MULTI_LIST, this is the initial static option set.
operators Optional operator whitelist. When omitted, the builder falls back to the default operators for the field type.
usageLimit Optional structural constraint that limits how many rules may use this field or its shared usage bucket.
validation Optional validation config. The shape depends on field type.
fieldComparison Optional semantic config for field-to-field comparisons, including a comparison type override and an allowlist of valid target fields.

usageLimit

max Required maximum number of matching rules allowed in the selected scope.
scope Optional. Defaults to global. Use parent to limit usage only within the same immediate parent group.
key Optional shared bucket identifier. When omitted, the builder uses the field's own field value.
message Optional custom validation message used when persisted or imported data exceeds the allowed limit.

fieldComparison

Semantic field comparison metadata

const fields: IBuilderFieldProps[] = [
  {
    field: 'CUSTOMER_COUNTRY',
    label: 'Customer country',
    type: 'LIST',
    operators: ['EQUAL'],
    value: [
      { value: 'CZ', label: 'Czech Republic' },
      { value: 'SK', label: 'Slovakia' },
    ],
    fieldComparison: {
      type: 'string',
      comparableFields: ['DELIVERY_COUNTRY_CODE'],
    },
  },
  {
    field: 'DELIVERY_COUNTRY_CODE',
    label: 'Delivery country code',
    type: 'TEXT',
    operators: ['EQUAL'],
  },
];

type Optional semantic comparison type. When omitted, TEXT, NUMBER, DATE, and BOOLEAN infer automatically, while LIST can infer from uniform option values.
comparableFields Optional source-owned allowlist that restricts which fields may appear on the right-hand side.
Operator support Field comparisons are only offered for operators that have a direct single-value right-hand side. Range and set-style operators continue to use literal values.

Type notes

BOOLEAN / TEXT / DATE / NUMBER The standard scalar field families with built-in widget and validation behavior.
LIST / MULTI_LIST Option-backed selectors where value holds the initial static option set, field-level runtime options can be shared across all rules of that field, and rule-level runtime options can override them per rule instance.
STATEMENT Advanced field type for free-form statement-like values. Document it carefully in consuming apps because it is less self-explanatory than scalar or list fields.
GROUP Advanced structural field type intended for specialized query models rather than everyday filter fields.

Documentation

Usage, Validation, Dynamic Field Options, and Localization.

Related recipes

Dynamic operators by field type