wizard-ql 2.1.1 → 3.0.0

package/dist/spec.d.ts

@@ -1,181 +1,96 @@
-export declare const QUOTES: string[];
-export declare const BRACKETS: Array<[open: string, close: string]>;
-export declare const PARENS: Array<[open: string, close: string]>;
-export declare const NEGATORS: string[];
-export declare const ARRAY_DELIMITERS: string[];
-/** 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 FieldType = 'boolean' | 'string' | 'number' | 'date';
+export type ConditionOperatorComparisonType = 'primitive' | 'boolean' | 'string' | 'number' | 'date' | 'numeric' | 'array';
+export type JunctionOperatorType = 'sumjunction' | 'productjunction';
+export type OperatorType = JunctionOperatorType | ConditionOperatorComparisonType;
+export type FieldTypeRecord = Record<string, FieldType | FieldType[]>;
+export interface OperatorRecordEntry {
+    /** The negation of this operator */
+    negationName: Uppercase<string>;
+    /** The data type this operator acts upon */
+    type: OperatorType;
+    /** Aliases for this operator */
+    aliases?: ReadonlyArray<Uppercase<string>>;
+    /** Aliases for the negation of this operator */
+    negationAliases?: ReadonlyArray<Uppercase<string>>;
+    /**
+     * Does this operator exclude the value being provided?\
+     * The negation's exclusionary trait will be the opposite of this
+     * @default false
+     */
+    exclusionary?: boolean;
 }
-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: "numeric";
-    readonly GREATER: "numeric";
-    readonly LEQ: "numeric";
-    readonly LESS: "numeric";
-    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;
+export type OperatorRecord = Record<Uppercase<string>, OperatorRecordEntry>;
+export type GetConditionOperators<O extends OperatorRecord> = string & {
+    [K in keyof O]: O[K] extends OperatorRecordEntry ? O[K] extends {
+        type: JunctionOperatorType;
+    } ? never : K | O[K]['negationName'] : never;
+}[keyof O];
+export type GetJunctionOperators<O extends OperatorRecord> = string & {
+    [K in keyof O]: O[K] extends OperatorRecordEntry ? O[K] extends {
+        type: JunctionOperatorType;
+    } ? K | O[K]['negationName'] : never : never;
+}[keyof O];
+export type GetOperators<O extends OperatorRecord> = GetConditionOperators<O> | GetJunctionOperators<O>;
+export type GetOperatorDefinition<O extends OperatorRecord, P extends GetOperators<O>> = {
+    [K in keyof O]: O[K] extends OperatorRecordEntry ? P extends K | O[K]['negationName'] | (O[K]['aliases'] extends ReadonlyArray<infer A> ? A : never) | (O[K]['negationAliases'] extends ReadonlyArray<infer NA> ? NA : never) ? O[K] : never : never;
+}[keyof O];
+type Unroll<T> = T extends ReadonlyArray<infer U> ? U : T;
+export type GetFieldTSType<T extends FieldType | FieldType[]> = {
     boolean: boolean;
     string: string;
     number: number;
     date: Date;
-    numeric: number | Date;
-    array: Primitive[];
-}[typeof COMPARISON_TYPE_DICTIONARY[T]];
-export type FieldType = 'boolean' | 'string' | 'number' | 'date';
-export type TypeRecord = Record<string, FieldType | FieldType[]>;
-/** Convert a field type string to a language server type */
-export type FieldTypeToTSType<T extends FieldType> = {
+}[Unroll<T>];
+export type Primitive = GetFieldTSType<FieldType>;
+export type GetConditionTSType<T extends ConditionOperatorComparisonType> = {
+    primitive: Primitive;
     boolean: boolean;
     string: string;
     number: number;
     date: Date;
+    numeric: number | Date;
+    array: Primitive[];
 }[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;
-};
-export declare const TYPE_PRIORITY: ["boolean", "date", "number", "string"];
-/**
- * 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, unknown> = 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, unknown>, F extends keyof R, O extends ComparisonOperation> {
+export interface CheckedCondition<F extends FieldTypeRecord = FieldTypeRecord, O extends OperatorRecord = OperatorRecord, I extends keyof F = keyof F, P extends GetConditionOperators<O> = GetConditionOperators<O>> {
     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]> : Extract<ComparisonTypeToTSType<O>, R[F]>;
-    /** Was this condition validated by the constraints or is its type unknown? */
+    operation: P;
+    field: I;
+    value: GetOperatorDefinition<O, P>['type'] extends 'array' ? Array<GetFieldTSType<F[I]>> : Extract<GetConditionTSType<GetOperatorDefinition<O, P>['type'] & ConditionOperatorComparisonType>, GetFieldTSType<F[I]>>;
     validated: true;
 }
-/**
- * A query on a field
- */
-export interface UncheckedCondition<O extends ComparisonOperation = ComparisonOperation> {
+export interface UncheckedCondition<O extends OperatorRecord = OperatorRecord, P extends GetConditionOperators<O> = GetConditionOperators<O>> {
     type: 'condition';
-    /** The operation */
-    operation: O;
-    /** The name of the field */
+    operation: P;
     field: string;
-    /** The value being checked */
-    value: Exclude<ComparisonTypeToTSType<O>, Date>;
-    /** Was this condition validated by the constraints or is its type unknown? */
+    value: GetOperatorDefinition<O, P>['type'] extends 'array' ? Primitive[] : GetConditionTSType<GetOperatorDefinition<O, P>['type'] & ConditionOperatorComparisonType>;
     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>;
+export interface Group<F extends FieldTypeRecord = FieldTypeRecord, O extends OperatorRecord = OperatorRecord, V extends boolean = false> {
+    type: 'group';
+    operation: GetJunctionOperators<O> & string;
+    constituents: Array<Expression<F, O, V>>;
+}
 /** Create a union of conditions; an intersection of the operation type validation and constraint type validation */
-export type CheckedConditionSpread<R extends Record<string, unknown>> = {
-    [K in keyof R]: {
-        [O in keyof ReverseAggregatedTypes]: Condition<R, K, ReverseAggregatedTypes[O]>;
-    }[keyof ReverseAggregatedTypes];
-}[keyof R];
+type CheckedConditionSpread<F extends FieldTypeRecord, O extends OperatorRecord> = {
+    [I in keyof F]: {
+        [P in GetConditionOperators<O>]: [CheckedCondition<F, O, I, P>['value']] extends [never] ? never : CheckedCondition<F, O, I, P>;
+    }[GetConditionOperators<O>];
+}[keyof F];
 /** 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, unknown> = Record<string, Primitive>, V extends boolean = false> = Group<R, V> | (V extends true ? CheckedConditionSpread<R> : CheckedConditionSpread<R> | UncheckedConditionSpread);
-export type UncheckedExpression = (Omit<Group, 'constituents'> & {
-    constituents: UncheckedExpression[];
-}) | UncheckedConditionSpread;
+type UncheckedConditionSpread<O extends OperatorRecord> = {
+    [P in GetConditionOperators<O>]: [UncheckedCondition<O, P>['value']] extends [never] ? never : UncheckedCondition<O, P>;
+}[GetConditionOperators<O>];
+export type Expression<F extends FieldTypeRecord = FieldTypeRecord, O extends OperatorRecord = OperatorRecord, V extends boolean = false> = Group<F, O, V> | (V extends true ? CheckedConditionSpread<F, O> : CheckedConditionSpread<F, O> | UncheckedConditionSpread<O>);
+export declare const TYPE_PRIORITY: ["boolean", "date", "number", "string"];
+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 PartType = 'literal' | 'junctionoperator' | 'conditionoperator' | 'quoted' | 'number' | 'openingarraybracket' | 'closingarraybracket' | 'arraydelimiter' | 'openinggroupbracket' | 'closinggroupbracket' | 'negator';
+export interface ClassifiedToken extends Token {
+    /** The part type of the token */
+    partType: PartType;
+}
 export {};

package/package.json

@@ -4,12 +4,12 @@
     "name": "Arthur Neuman",
     "url": "https://github.com/exoRift"
   },
-  "homepage": "https://github.com/guidance-analytics/wizard-ql",
+  "homepage": "https://github.com/exoRift/wizard-ql",
   "description": "WizardQL is a natural-language-like query language for constructing data queries for resources that meet conditions.",
-  "version": "2.1.1",
+  "version": "3.0.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/guidance-analytics/wizard-ql.git"
+    "url": "git+https://github.com/exoRift/wizard-ql.git"
   },
   "keywords": [
     "query",
@@ -29,13 +29,21 @@
   ],
   "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 ."
+    "lint": "eslint .",
+    "pretest:types": "bun run build && find test -name '*.test-d.ts' -exec perl -pi -e 's|// \\@ts-expect-error|// ts-expect-error|g' {} +",
+    "test:types": "tsd --files 'test/**/*.test-d.ts'",
+    "posttest:types": "find test -name '*.test-d.ts' -exec perl -pi -e 's|// ts-expect-error|// \\@ts-expect-error|g' {} +",
+    "test": "bun run test:types && bun test",
+    "preview": "bun run build && bunx serve ./test/preview",
+    "prepack": "bun run build"
   },
   "devDependencies": {
-    "@types/bun": "latest",
+    "@types/bun": "^1.3.13",
+    "custom-types": "github:exoRift/custom-types",
     "eslint": "^9.25.1",
+    "eslint-config": "github:exoRift/eslint-config",
     "eslint-plugin-jsdoc": "^50.6.11",
-    "neostandard": "^0.12.1"
+    "tsd": "^0.33.0"
   },
   "optionalDependencies": {
     "knex": "^3.1.0"

package/dist/parse.d.ts

@@ -1,55 +0,0 @@
-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 coercion so the value checked will always be a string. However, quotes and escapes WILL be removed
-     */
-    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;

package/dist/stringify.d.ts

@@ -1,42 +0,0 @@
-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

@@ -1,15 +0,0 @@
-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[]>;