wizard-ql 1.0.0

package/dist/parse.d.ts

@@ -0,0 +1,51 @@
+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.\
+     * 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 field query is of array type, it will check all entries of the array.
+     * @warn If 42 (the number) is prohibited, "42" (the string) will still be allowed
+     */
+    restricted?: Partial<Record<keyof T | (string & {}), boolean | ['allow' | 'deny', Array<boolean | string | number | RegExp>]>>;
+    /**
+     * The types of fields\
+     * Either provide the field type singularly or permit multiple types with an array of field types
+     */
+    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;
+    /**
+     * Interpret date string values as numbers\
+     * If true, use `new Date()` constructor to make this determination\
+     * If a callback is passed, use that. A value of `NaN` denotes an invalid date
+     */
+    interpretDates?: boolean | ((v: string) => number);
+}
+/**
+ * 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, const V extends boolean>(expression: string | string[] | Token[], constraints?: ExpressionConstraints<T, V>): Expression<ConvertTypeRecord<T>, V> | null;

package/dist/regex.d.ts

@@ -0,0 +1,11 @@
+export declare const ESCAPE_REGEX = "(?<=(?<!\\\\)(?:\\\\\\\\)*)";
+/**
+ * Create a Regex to look for quotes
+ * @returns The regular expression
+ */
+export declare function createQuoteRegexString(): string;
+/**
+ * Create a Regex to find tokens
+ * @returns The regular expression
+ */
+export declare function createTokenRegexString(): string;

package/dist/spec.d.ts

@@ -0,0 +1,169 @@
+/** All available operation aliases (alias -> operation) */
+export declare const OPERATION_ALIAS_DICTIONARY: {
+    readonly AND: "AND";
+    readonly '&&': "AND";
+    readonly '&': "AND";
+    readonly '^': "AND";
+    readonly OR: "OR";
+    readonly '||': "OR";
+    readonly '|': "OR";
+    readonly V: "OR";
+    readonly GEQ: "GEQ";
+    readonly '>=': "GEQ";
+    readonly '=>': "GEQ";
+    readonly LEQ: "LEQ";
+    readonly '<=': "LEQ";
+    readonly '=<': "LEQ";
+    readonly NOTEQUALS: "NOTEQUAL";
+    readonly NOTEQUAL: "NOTEQUAL";
+    readonly NEQ: "NOTEQUAL";
+    readonly ISNT: "NOTEQUAL";
+    readonly '!==': "NOTEQUAL";
+    readonly '!=': "NOTEQUAL";
+    readonly EQUALS: "EQUAL";
+    readonly EQUAL: "EQUAL";
+    readonly EQ: "EQUAL";
+    readonly IS: "EQUAL";
+    readonly '==': "EQUAL";
+    readonly '=': "EQUAL";
+    readonly LESS: "LESS";
+    readonly '<': "LESS";
+    readonly GREATER: "GREATER";
+    readonly '>': "GREATER";
+    readonly MORE: "GREATER";
+    readonly NOTIN: "NOTIN";
+    readonly '!:': "NOTIN";
+    readonly IN: "IN";
+    readonly ':': "IN";
+    readonly NOTMATCHES: "NOTMATCH";
+    readonly NOTMATCH: "NOTMATCH";
+    readonly '!~': "NOTMATCH";
+    readonly MATCHES: "MATCH";
+    readonly MATCH: "MATCH";
+    readonly '~': "MATCH";
+};
+export interface Token {
+    /** The text content of the token */
+    content: string;
+    /** The index in the original expression this token originates from */
+    index: number;
+}
+export type Operation = (typeof OPERATION_ALIAS_DICTIONARY)[keyof typeof OPERATION_ALIAS_DICTIONARY];
+export declare const ALIASES: string[];
+/** All base operations and their type */
+export declare const OPERATION_PURPOSE_DICTIONARY: {
+    readonly AND: "junction";
+    readonly OR: "junction";
+    readonly EQUAL: "comparison";
+    readonly NOTEQUAL: "comparison";
+    readonly LESS: "comparison";
+    readonly GREATER: "comparison";
+    readonly GEQ: "comparison";
+    readonly LEQ: "comparison";
+    readonly IN: "comparison";
+    readonly NOTIN: "comparison";
+    readonly MATCH: "comparison";
+    readonly NOTMATCH: "comparison";
+};
+type KeysWhereValue<T, V> = Exclude<{
+    [K in keyof T]: T[K] extends V ? K : never;
+}[keyof T], never>;
+export type JunctionOperation = KeysWhereValue<typeof OPERATION_PURPOSE_DICTIONARY, 'junction'>;
+export type ComparisonOperation = KeysWhereValue<typeof OPERATION_PURPOSE_DICTIONARY, 'comparison'>;
+/** All comparison operations and their types */
+export declare const COMPARISON_TYPE_DICTIONARY: {
+    readonly EQUAL: "primitive";
+    readonly NOTEQUAL: "primitive";
+    readonly GEQ: "number";
+    readonly GREATER: "number";
+    readonly LEQ: "number";
+    readonly LESS: "number";
+    readonly IN: "array";
+    readonly NOTIN: "array";
+    readonly MATCH: "string";
+    readonly NOTMATCH: "string";
+};
+/** Convert an operation's comparison type to a language server type */
+export type ComparisonTypeToTSType<T extends keyof typeof COMPARISON_TYPE_DICTIONARY> = {
+    primitive: Primitive;
+    boolean: boolean;
+    string: string;
+    number: number;
+    array: Primitive[];
+}[typeof COMPARISON_TYPE_DICTIONARY[T]];
+export type FieldType = 'boolean' | 'string' | 'number';
+export type TypeRecord = Record<string, FieldType | FieldType[]>;
+/** Convert a field type string to a language server type */
+export type FieldTypeToTSType<T extends FieldType> = {
+    boolean: boolean;
+    string: string;
+    number: number;
+}[T];
+/** Primitive values that can be used in comparisons */
+export type Primitive = FieldTypeToTSType<FieldType>;
+/** Convert input type record to language server type record */
+export type ConvertTypeRecord<T extends TypeRecord> = {
+    [K in keyof T]: (T[K] extends FieldType[] ? FieldTypeToTSType<T[K][number]> : T[K] extends FieldType ? FieldTypeToTSType<T[K]> : Primitive) & Primitive;
+};
+/**
+ * A group of conditions joined by a junction operator
+ * @template R A record mapping field names to values
+ */
+export interface Group<R extends Record<string, Primitive> = Record<string, Primitive>, V extends boolean = false> {
+    type: 'group';
+    /** The junction operator */
+    operation: JunctionOperation;
+    /** The members of the group */
+    constituents: Array<Expression<R, V>>;
+}
+/**
+ * A query on a field, validated by type constraints
+ * @template R A record mapping field names to values
+ * @template F The name of the field being queried
+ */
+export interface Condition<R extends Record<string, Primitive>, F extends keyof R, O extends ComparisonOperation> {
+    type: 'condition';
+    /** The operation */
+    operation: O;
+    /** The name of the field */
+    field: F;
+    /** The value being checked */
+    value: typeof COMPARISON_TYPE_DICTIONARY[O] extends 'array' ? Array<R[F]> : R[F] & ComparisonTypeToTSType<O>;
+    /** Was this condition validated by the constraints or is its type unknown? */
+    validated: true;
+}
+/**
+ * A query on a field
+ */
+export interface UncheckedCondition<O extends ComparisonOperation = ComparisonOperation> {
+    type: 'condition';
+    /** The operation */
+    operation: O;
+    /** The name of the field */
+    field: string;
+    /** The value being checked */
+    value: ComparisonTypeToTSType<O>;
+    /** Was this condition validated by the constraints or is its type unknown? */
+    validated: false;
+}
+/**
+ * Reverse the keys and values of a type and aggregate by common value
+ */
+type ReverseAggregate<T extends Record<any, any>> = {
+    [V in T[keyof T]]: {
+        [K in keyof T]: T[K] extends V ? K : never;
+    }[keyof T];
+};
+type ReverseAggregatedTypes = ReverseAggregate<typeof COMPARISON_TYPE_DICTIONARY>;
+/** Create a union of conditions; an intersection of the operation type validation and constraint type validation */
+export type CheckedConditionSpread<R extends Record<string, Primitive>> = {
+    [K in keyof R]: {
+        [O in keyof ReverseAggregatedTypes]: Condition<R, K, ReverseAggregatedTypes[O]>;
+    }[keyof ReverseAggregatedTypes];
+}[keyof R];
+/** Create a union of conditions that are operation type validated */
+export type UncheckedConditionSpread = {
+    [O in keyof ReverseAggregatedTypes]: UncheckedCondition<ReverseAggregatedTypes[O]>;
+}[keyof ReverseAggregatedTypes];
+export type Expression<R extends Record<string, Primitive> = Record<string, Primitive>, V extends boolean = false> = Group<R, V> | (V extends true ? CheckedConditionSpread<R> : CheckedConditionSpread<R> | UncheckedConditionSpread);
+export {};

package/dist/stringify.d.ts

@@ -0,0 +1,42 @@
+import type { Expression } from './spec';
+export interface StringifyOptions {
+    /**
+     * The notation to use for junction operations
+     * @example Programmatic: foo & bar
+     * @example Linguistic: foo AND bar
+     * @example Formal: foo ^ bar
+     * @default 'programmatic'
+     */
+    junctionNotation?: 'programmatic' | 'linguistic' | 'formal';
+    /**
+     * The notation to use for comparison expressions
+     * @example Programmatic: foo = bar
+     * @example Linguistic: foo EQUALS bar
+     * @default 'programmatic'
+     */
+    comparisonNotation?: 'programmatic' | 'linguistic';
+    /**
+     * 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 boolean values to their implicit denotations
+     * @example 'field'
+     * @example '!field'
+     * @default false
+     */
+    condenseBooleans?: boolean;
+}
+/**
+ * Convert a parsed WizardQL expression to a string
+ * @param expression The expression
+ * @param opts       Formatting options
+ * @returns          The formatted string
+ */
+export declare function stringify(expression: Expression, opts?: StringifyOptions): string;

package/dist/summarize.d.ts

@@ -0,0 +1,15 @@
+import type { ComparisonOperation, Expression, ComparisonTypeToTSType } from './spec';
+export interface AggregationValue<O extends ComparisonOperation = ComparisonOperation> {
+    /** The value being checked */
+    value: ComparisonTypeToTSType<O>;
+    /** The operator being used */
+    operation: O;
+    /** Is this an exclusionary operator? (Ex: NOT, NOTIN) */
+    exclusionary: boolean;
+}
+/**
+ * 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
+ */
+export declare function summarize(expressions: Expression | Expression[]): Map<string, AggregationValue[]>;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "wizard-ql",
+  "author": {
+    "name": "Arthur Neuman",
+    "url": "https://github.com/exoRift"
+  },
+  "homepage": "https://github.com/guidance-analytics/wizard-ql",
+  "description": "WizardQL is a natural-language-like query language for constructing data queries for resources that meet conditions.",
+  "version": "1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/guidance-analytics/wizard-ql.git"
+  },
+  "keywords": ["query", "language", "querylanguage", "parser", "cel", "expression"],
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "files": ["dist/"],
+  "scripts": {
+    "build": "[ -d dist ] && rm -r dist; bun build --target=node --format=esm --packages external src/index.ts --outfile dist/index.js && tsc --project tsconfig.build.json",
+    "lint": "eslint ."
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "eslint": "^9.25.1",
+    "eslint-plugin-jsdoc": "^50.6.11",
+    "neostandard": "^0.12.1"
+  },
+  "optionalDependencies": {
+    "knex": "^3.1.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.8.3"
+  }
+}