wizard-ql 2.1.1 → 4.0.0

package/dist/parser.d.ts

@@ -0,0 +1,402 @@
+import { type ConditionOperatorComparisonType, type Expression, type FieldType, type FieldTypeRecord, type GetConditionOperators, type GetConditionTSType, type GetJunctionOperators, type GetOperators, type Group, type JunctionOperatorType, type OperatorRecord, type OperatorRecordEntry, type PartType, type Primitive, type Token, type UncheckedCondition } from './spec';
+interface InternalConditionOperatorDefinition<O extends OperatorRecord> {
+    name: GetConditionOperators<O>;
+    negation: GetConditionOperators<O>;
+    type: ConditionOperatorComparisonType;
+    exclusionary: boolean;
+}
+interface InternalJunctionOperatorDefinition<O extends OperatorRecord> {
+    name: GetJunctionOperators<O>;
+    negation: GetJunctionOperators<O>;
+    type: JunctionOperatorType;
+    exclusionary: boolean;
+}
+interface Context {
+    tokens: readonly Token[];
+    startToken: Token | undefined;
+    startIndex: number | undefined;
+    endToken?: Token | undefined;
+    endIndex?: number | undefined;
+}
+interface ProcessedToken {
+    /** The raw token */
+    raw: string;
+    /** The token's quote contents, if surrounded by quotes */
+    unquoted: string | undefined;
+    /** The token's resolved contents or quote contents, including escape backslashes */
+    escaped: string;
+    /** The token's resolved contents, with the escape backslashes removed */
+    unescaped: string;
+}
+type StringsInOtherEntries<T, CurrentK> = {
+    [K in keyof T]: K extends CurrentK ? never : AllStringsInEntry<T[K]> | K;
+}[keyof T];
+type AllStringsInEntry<E> = E extends OperatorRecordEntry ? E['negationName'] | (E['aliases'] extends ReadonlyArray<infer A> ? A : never) | (E['negationAliases'] extends ReadonlyArray<infer NA> ? NA : never) : never;
+type ValidationError<Msg extends string> = string & {
+    __error: `Error: ${Msg}`;
+};
+type ValidateGlobalUniqueness<O extends OperatorRecord> = {
+    [K in keyof O]: O[K] extends OperatorRecordEntry ? O[K] & ({
+        negationName: O[K]['negationName'] extends K | StringsInOtherEntries<O, K> ? ValidationError<`Negation '${O[K]['negationName'] & string}' is already used as a key or in another entry (or not all uppercase) ${(K | StringsInOtherEntries<O, K>) & string}`> : O[K]['negationName'];
+        aliases?: O[K] extends (OperatorRecordEntry & {
+            aliases: ReadonlyArray<infer A>;
+        }) ? {
+            [I in keyof O[K]['aliases']]: O[K]['aliases'][I] extends K | O[K]['negationName'] | StringsInOtherEntries<O, K> | Exclude<A, O[K]['aliases'][I]> ? ValidationError<`Alias '${O[K]['aliases'][I] & string}' is already used as a key or in another entry (or not all uppercase) ${(K | O[K]['negationName'] | StringsInOtherEntries<O, K> | Exclude<A, O[K]['aliases'][I]>) & string}`> : O[K]['aliases'][I];
+        } : never;
+        negationAliases?: O[K] extends (OperatorRecordEntry & {
+            negationAliases: ReadonlyArray<infer NA>;
+        }) ? {
+            [I in keyof O[K]['negationAliases']]: O[K]['negationAliases'][I] extends K | O[K]['negationName'] | (O[K] extends {
+                aliases: ReadonlyArray<infer A>;
+            } ? A : never) | StringsInOtherEntries<O, K> | Exclude<NA, O[K]['negationAliases'][I]> ? ValidationError<`NegationAlias '${O[K]['negationAliases'][I] & string}' is already used as a key or in another entry (or not all uppercase) ${(K | O[K]['negationName'] | (O[K] extends {
+                aliases: ReadonlyArray<infer A>;
+            } ? A : never) | StringsInOtherEntries<O, K> | Exclude<NA, O[K]['negationAliases'][I]>) & string}`> : O[K]['negationAliases'][I];
+        } : never;
+    }) : ValidationError<`Invalid operator record key '${K & string}' (is it all uppercase?)`>;
+};
+type ValidateUppercaseKeys<O extends OperatorRecord> = {
+    [K in keyof O]: K extends Uppercase<K & string> ? O[K] : ValidationError<`Operator Record contains non-uppercase key: '${K & string}'`>;
+};
+type InternalOperationDictionary<O extends OperatorRecord> = Record<GetConditionOperators<O> | GetJunctionOperators<O> | string, InternalConditionOperatorDefinition<O> | InternalJunctionOperatorDefinition<O>>;
+type ReadonlyNonemptyArray<T> = readonly [T, ...T[]];
+export interface WizardParserConfig<F extends FieldTypeRecord, O extends OperatorRecord, out V extends boolean, D extends string> {
+    /**
+     * 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 coercion so the value checked will always be a string. However, quotes and escapes WILL be removed
+     */
+    restricted?: Partial<Record<keyof F | (string & {}), boolean | ['allow' | 'deny', ReadonlyArray<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?: F;
+    /**
+     * 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;
+    /**
+     * A callback that determines how dates are stringified\
+     * By default, uses `.toISOString()`
+     */
+    dateSerializer?: (v: Date) => string;
+    operators?: (O | ValidateGlobalUniqueness<O> | ValidateUppercaseKeys<O>) & ValidateGlobalUniqueness<O> & ValidateUppercaseKeys<O>;
+    /**
+     * The default operator and value (in string form) for an implicit condition (positive variant)\
+     * Example: `field` or negative: `!field`\
+     * The negative will be taken by taking the complement of the default condition\
+     * By default, on the default operator definition, this is "EQUAL true". Thus, `field` -> `field EQUAL true` and `!field` -> `field NOTEQUAL true`\
+     * If undefined with a custom operator definition or specified false, implicit conditions will not be parsed
+     */
+    implicitCondition?: false | {
+        /** The default implicit operator */
+        operator: GetConditionOperators<O>;
+        /** The default implicit value in string form */
+        value: string;
+        /** How the value should be parsed (as a type) */
+        asType: FieldType | readonly FieldType[];
+    };
+    /**
+     * A specification of how to stringify a parsed expression.\
+     * Provide a record that maps dialect names to a record which maps operator names to their stringified expressions
+     */
+    dialects?: Record<D, Record<GetOperators<O>, string>>;
+    /**
+     * Symbol overrides.\
+     * Stringification will use the first symbol entry of each symbol type.
+     */
+    symbols?: {
+        quotes?: ReadonlyNonemptyArray<string>;
+        negators?: ReadonlyNonemptyArray<string>;
+        arrayDelimiters?: ReadonlyNonemptyArray<string>;
+        arrayBrackets?: ReadonlyNonemptyArray<[opening: string, closing: string]>;
+        groupBrackets?: ReadonlyNonemptyArray<[opening: string, closing: string]>;
+    };
+}
+export interface StringifyOptions<D extends string> {
+    /**
+     * The dialect to use for expressing operations
+     */
+    dialect: D;
+    /**
+     * Always surround a group with parentheses, even if unnecessary
+     * @default false
+     */
+    alwaysParenthesize?: boolean;
+    /**
+     * Don't include spaces (Spaces will be included around operators that are "linguistic")
+     * @default false
+     */
+    compact?: boolean;
+    /**
+     * Condense implicit-able value conditions to their implicit denotations\
+     * With the default operator definitions, this is booleans
+     * @example 'field'
+     * @example '!field'
+     * @default false
+     */
+    condenseImplicit?: boolean;
+}
+export interface AggregationValue<O extends OperatorRecord = OperatorRecord> {
+    /** The value being checked */
+    value: GetConditionTSType<(O[GetConditionOperators<O>] & OperatorRecordEntry & {
+        type: ConditionOperatorComparisonType;
+    })['type']>;
+    /** The operator being used */
+    operation: GetOperators<O>;
+    /** Is this an exclusionary operator? (The negation of a defined operator) */
+    exclusionary: boolean;
+}
+/**
+ * A WizardQL parser instance
+ */
+export declare class WizardParser<const F extends FieldTypeRecord, const O extends OperatorRecord = typeof WizardParser.DEFAULT_OPERATORS, const V extends boolean = false, const D extends string = typeof WizardParser.DEFAULT_OPERATORS extends O ? keyof typeof WizardParser.DEFAULT_DIALECTS : string> {
+    static readonly DEFAULT_OPERATORS: {
+        readonly AND: {
+            readonly negationName: "OR";
+            readonly type: "productjunction";
+            readonly aliases: readonly ["&&", "&", "^", "∧"];
+            readonly negationAliases: readonly ["||", "|", "V", "∨"];
+        };
+        readonly EQUAL: {
+            readonly negationName: "NOTEQUAL";
+            readonly type: "primitive";
+            readonly aliases: readonly ["EQUALS", "EQ", "IS", "=", "=="];
+            readonly negationAliases: readonly ["NOTEQUALS", "NEQ", "ISNT", "!=", "!==", "≠"];
+        };
+        readonly LESS: {
+            readonly negationName: "GEQ";
+            readonly type: "numeric";
+            readonly aliases: readonly ["<"];
+            readonly negationAliases: readonly [">=", "=>", "≥"];
+            readonly exclusionary: true;
+        };
+        readonly GREATER: {
+            readonly negationName: "LEQ";
+            readonly type: "numeric";
+            readonly aliases: readonly [">", "MORE", "MORETHAN"];
+            readonly negationAliases: readonly ["<=", "=<", "≤"];
+            readonly exclusionary: true;
+        };
+        readonly IN: {
+            readonly negationName: "NOTIN";
+            readonly type: "array";
+            readonly aliases: readonly [":", "∈"];
+            readonly negationAliases: readonly ["!:", "∉"];
+        };
+        readonly MATCH: {
+            readonly negationName: "NOTMATCH";
+            readonly type: "string";
+            readonly aliases: readonly ["MATCHES", "~", "≅"];
+            readonly negationAliases: readonly ["NOTMATCHES", "!~", "≇"];
+        };
+    };
+    static readonly DEFAULT_DIALECTS: {
+        readonly programmatic: {
+            readonly AND: "&";
+            readonly OR: "|";
+            readonly EQUAL: "=";
+            readonly NOTEQUAL: "!=";
+            readonly GEQ: ">=";
+            readonly GREATER: ">";
+            readonly LEQ: "<=";
+            readonly LESS: "<";
+            readonly IN: ":";
+            readonly NOTIN: "!:";
+            readonly MATCH: "~";
+            readonly NOTMATCH: "!~";
+        };
+        readonly linguistic: {
+            readonly AND: "AND";
+            readonly OR: "OR";
+            readonly EQUAL: "EQUALS";
+            readonly NOTEQUAL: "NOTEQUALS";
+            readonly GEQ: "GEQ";
+            readonly GREATER: "GREATER";
+            readonly LEQ: "LEQ";
+            readonly LESS: "LESS";
+            readonly IN: "IN";
+            readonly NOTIN: "NOTIN";
+            readonly MATCH: "MATCHES";
+            readonly NOTMATCH: "NOTMATCHES";
+        };
+        readonly formal: {
+            readonly AND: "∧";
+            readonly OR: "∨";
+            readonly EQUAL: "=";
+            readonly NOTEQUAL: "≠";
+            readonly GEQ: "≥";
+            readonly GREATER: ">";
+            readonly LEQ: "≤";
+            readonly LESS: "<";
+            readonly IN: "∈";
+            readonly NOTIN: "∉";
+            readonly MATCH: "≅";
+            readonly NOTMATCH: "≇";
+        };
+    };
+    static readonly DEFAULT_QUOTES: readonly ["\"", "'", "`"];
+    static readonly DEFAULT_NEGATORS: readonly ["!"];
+    static readonly DEFAULT_ARRAY_DELIMITERS: readonly [","];
+    static readonly DEFAULT_ARRAY_BRACKETS: [["[", "]"], ["{", "}"]];
+    static readonly DEFAULT_GROUP_BRACKETS: [["(", ")"]];
+    protected readonly OPERATOR_DICTIONARY: InternalOperationDictionary<O>;
+    protected readonly CONFIG: WizardParserConfig<F, O, V, D> & Required<Pick<WizardParserConfig<F, O, V, D>, 'operators'>> & {
+        symbols: Required<Exclude<WizardParserConfig<F, O, V, D>['symbols'], undefined>>;
+    };
+    protected readonly TOKEN_REGEX: RegExp;
+    protected readonly QUOTE_REGEX: RegExp;
+    protected readonly QUOTE_EDGE_REGEX: RegExp;
+    protected readonly ARRAY_DELIMITER_REGEX: RegExp;
+    protected readonly FIELD_LIST: Map<string, string>;
+    /**
+     * Construct a WizardQL parser
+     * @param config The parser configuration
+     */
+    constructor(config?: WizardParserConfig<F, O, V, D>);
+    /**
+     * Take a string, sanitize it, and push it to an array if it has a length
+     * @param array The array to push to
+     * @param item  The item to sanitize and push
+     * @param index The index of the token in the original string
+     * @returns     The token, if pushed
+     */
+    protected static pushSanitized(array: Token[], item: string, index: number): Token | undefined;
+    /**
+     * Given an input, parse a date using the provided parse function or the default method
+     * @param v The input to parse
+     * @returns The date value
+     */
+    protected interpretDate(v: string | number): Date;
+    /**
+     * Take a string and tokenize it for parsing with a specific pattern
+     * @param expression The expression to tokenize
+     * @param pattern    The tokenization pattern
+     * @returns          An array of tokens
+     */
+    protected _tokenize(expression: string, pattern: RegExp): Token[];
+    /**
+     * Take a string and tokenize it for parsing
+     * @param expression The expression to tokenize
+     * @returns          An array of tokens
+     */
+    tokenize(expression: string): Token[];
+    /**
+     * Get an opening closure's closing index
+     * @param tokens  The token array
+     * @param start   The index of the opening closure
+     * @param opening The token to consider as opening
+     * @param closing The token to consider as closing
+     * @returns       The index of the closing token or -1 if not found
+     */
+    protected static getClosingIndex(tokens: readonly Token[], start: number, opening: string, closing: string): number;
+    /**
+     * Process a token to get its unquoted, escaped, and unescaped varients\
+     * Order: unquote -> escaped -> unescaped
+     * @param token The token to process
+     * @returns     An object containing the variants
+     */
+    protected processToken(token: string): ProcessedToken;
+    /**
+     * Apply De Morgan's Law to an expression and complement it\
+     * (Mutating operation)
+     * @param          expression The expression
+     * @throws {Error}            If the inverse operation cannot be found
+     */
+    protected complementExpression(expression: Expression<F, O, V>): void;
+    /**
+     * Coerce a string into the appropriate type for the operation based on the field type and operator
+     * @param           processedToken The value to coerce (already processed)
+     * @param           fieldTypes     The supported field types
+     * @param           operatorTypes  The supported operator types
+     * @returns                        The coerced type
+     * @throws  {Error}                Message is 'operator' if the operator type cannot be coerced, 'field' if the field type cannot be coerced and 'disagreement' if the allowed types for the field and operator have no overlap
+     */
+    protected coerceType(processedToken: ProcessedToken, fieldTypes: FieldType[], operatorTypes: FieldType[]): Primitive;
+    /**
+     * Validate that a condition meets constraints
+     * @warn This operation mutates the condition to apply the validated field and perform type coercion
+     * @param                     condition       The condition to validate
+     * @param                     valueIsImplicit Was this value implicitly inferred? If so, don't attempt stringification
+     * @param                     ctx             Error Context
+     * @throws  {ConstraintError}
+     * @returns                                   The same reference to the condition
+     */
+    protected validateCondition(condition: Omit<UncheckedCondition<O>, 'validated' | 'value'> & {
+        value: string | string[];
+    }, valueIsImplicit?: boolean, ctx?: Context): Exclude<Expression<F, O, V>, Group<F, O, V>>;
+    /**
+     * Parse tokens into an object expression
+     * @param                                  tokens  The tokens to parse into an object expression
+     * @param                                  _offset The token offset
+     * @returns                                        An expression
+     * @throws  {ParseError | ConstraintError}
+     */
+    protected _parse(tokens: readonly Token[], _offset: number): Expression<F, O, V> | null;
+    /**
+     * Parse a Wizard expression into its object form
+     * @param                                  expression The Wizard expression as a string or as an array of tokens
+     * @returns                                           The object representation
+     * @throws  {ParseError | ConstraintError}
+     */
+    parse(expression: string | string[] | Token[]): Expression<F, O, V> | null;
+    /**
+     * Add quotes to a string value if it resembles another primitive
+     * @param value The value
+     * @returns     The value, possibly quoted, stringified
+     */
+    protected addQuotesIfNecessary(value: Primitive): string;
+    /**
+     * Convert a parsed WizardQL expression to a string
+     * @param           expression The expression
+     * @param           opts       Formatting options
+     * @throws  {Error}            If no dialect dictionary is defined or dialect supplied is unknown
+     * @returns                    The formatted string
+     */
+    stringify(expression: Expression<F, O>, opts: D | StringifyOptions<D>): string;
+    /**
+     * (Get an array entry from a map or insert one) and return it
+     * @param map The map
+     * @param key The key the access
+     * @returns   The entry array
+     */
+    protected static getOrPutArrayInMap<T, U>(map: Map<T, U[]>, key: T): U[];
+    /**
+     * Summarize a parsed expression by aggregating its queries by field
+     * @param expressions The expression or expressions to aggregate
+     * @returns           The aggregation as a map, mapping field name to queries
+     */
+    summarize(expressions: Expression<F, O> | Array<Expression<F, O>>): Map<string, Array<AggregationValue<O>>>;
+    /**
+     * Given an expression part, return its type
+     * @param segment                   The segment/part
+     * @param activeArrayOpeningBracket If actively in an array, the opening bracket
+     * @returns                         The part type
+     */
+    getPartType(segment: string, activeArrayOpeningBracket?: string): PartType;
+    /**
+     * Resolve an alias to get an operator's core name
+     * @param alias The alias
+     * @returns     The core name
+     */
+    resolveOperatorAlias(alias: string): GetOperators<O> | undefined;
+}
+export {};

package/dist/regex.d.ts

@@ -1,11 +1,30 @@
 export declare const ESCAPE_REGEX = "(?<=(?<!\\\\)(?:\\\\\\\\)*)";
 /**
  * Create a Regex to look for quotes
- * @returns The regular expression
+ * @param           quotes Characters to consider quotes
+ * @throws  {Error}        If the runtime does not have a RegExp.escape function
+ * @returns                The regular expression string
  */
-export declare function createQuoteRegexString(): string;
+export declare function createQuoteRegexString(quotes: readonly string[]): string;
+/**
+ * Create a Regex to look for array delimiting
+ * @param           quotes     Characters to consider quotes
+ * @param           delimiters Characters to consider array delimiters
+ * @throws  {Error}            If the runtime does not have a RegExp.escape function
+ * @returns                    The regular expression string
+ */
+export declare function createArrayDelimitRegexString(quotes: readonly string[], delimiters: readonly string[]): string;
+/**
+ * Check if a string is entirely alpha characters
+ * @param text The text
+ * @returns    Whether the text is solely alpha or not
+ */
+export declare function isAlpha(text: string): boolean;
 /**
  * Create a Regex to find tokens
- * @returns The regular expression
+ * @param           keywords Keywords to isolate
+ * @param           quotes   Characters to consider quotes
+ * @throws  {Error}          If the runtime does not have a RegExp.escape function
+ * @returns                  The regular expression string
  */
-export declare function createTokenRegexString(): string;
+export declare function createTokenRegexString(keywords: string[], quotes: readonly string[]): string;