wizard-ql/dist/parse.d.ts

WizardQL is a natural-language-like query language for constructing data queries for resources that meet conditions.

import { type ConvertTypeRecord, type Expression, type Token, type TypeRecord } from './spec';
export declare const TOKEN_REGEX: RegExp;
export declare const QUOTE_REGEX: RegExp;
export declare const QUOTE_EDGE_REGEX: RegExp;
/**
 * Take a string and tokenize it for parsing
 * @param expression The expression to tokenize
 * @returns          An array of tokens
 */
export declare function tokenize(expression: string): Token[];
export interface ExpressionConstraints<T extends TypeRecord, V extends boolean> {
    /**
     * Restricted fields.\
     * Restrict an entire field by setting it to true.\
     * Restrict an exact value by providing a string.\
     * Restrict a pattern by providing a Regex expression.\
     * By default allow any value and restrict a collection of values by passing ['deny', VALUES[]]\
     * By default restrict any value and allow a collection of values by passing ['allow', VALUES[]]\
     * If the query value is of array type, it will check all entries of the array and ensure they're all allowed.\
     * This check runs before type coercsion so the value checked will always be a string.
     */
    restricted?: Partial<Record<keyof T | (string & {}), boolean | ['allow' | 'deny', Array<string | RegExp>]>>;
    /**
     * The types of fields\
     * Either provide the field type singularly or permit multiple types with an array of field types\
     * A field with type 'date' will parse the value into a Date object if possible (Wizard will not attempt to do this otherwise)\
     * Type coercion priority: boolean -> date -> number -> string
     */
    types?: T;
    /**
     * Field names in restriction checks and type checks are case insensitive
     * @note If enabled, all fields will be returned as their casing denoted by the types or restricted record
     * @warn Mismatching casing between the restricted record and the type record will prioritize the restricted record
     */
    caseInsensitive?: boolean;
    /**
     * Disallow fields that are not present in the "restricted" record or the "types" record
     */
    disallowUnvalidated?: V;
    /**
     * A callback that determines how dates are interpreted\
     * By default, uses `new Date()`
     */
    dateInterpreter?: (v: string | number) => Date;
}
/**
 * Parse a Wizard expression into its object form
 * @template T A type record, mapping field names to their types
 * @param                                  expression  The Wizard expression as a string or as an array of tokens
 * @param                                  constraints Constraints to add on parsing such as forced types or restricted columns
 * @returns                                            The object representation
 * @throws  {ParseError | ConstraintError}
 */
export declare function parse<const T extends TypeRecord = {}, // eslint-disable-line @typescript-eslint/no-empty-object-type
const V extends boolean = false>(expression: string | string[] | Token[], constraints?: ExpressionConstraints<T, V>): Expression<ConvertTypeRecord<T>, V> | null;