wizard-ql 1.0.0 → 2.0.1

package/README.md

@@ -258,7 +258,7 @@ Values can be direct values (string, number, boolean) or regex expressions
 "deny" will deny the values/patterns and allow all others
 
 ### `types`
-A record mapping field names to (`boolean`, `string`, `number`). The value in the record can either be a single allowed type or an array of allowed types. Only operators that can function on that type can be used for that field. By default, fields will be treated as being able to be any of the three types.
+A record mapping field names to (`boolean`, `string`, `number`, `date`). The value in the record can either be a single allowed type or an array of allowed types. Only operators that can function on that type can be used for that field. By default, fields will be treated as being able to be any of the three types.
 
 > Example:
 > ```js
@@ -270,6 +270,15 @@ A record mapping field names to (`boolean`, `string`, `number`). The value in th
 > })
 > ```
 
+> [!NOTE]
+> A value will only be attempted to be parsed as a date if `'date'` is included in the field's type record.
+> If the value is a number, it will be parsed as number of milliseconds. Any non-number character will cause the value to be parsed as a string
+
+The type coercion priority chain is as follows:
+`boolean` -> `date` -> `number` -> `string`
+> [!WARNING]
+> This can cause issues for numbers with leading zeros. If this is a potential problem, make sure to exclude `number` from the types and include `string`
+
 ### Regarding constraints: `validated` property
 When a field has matched either a key in `types` or a field in `restricted`, the `validated` property on the parsed condition will be true. This is due to a limitation with TypeScript's type checking.
 
@@ -306,10 +315,10 @@ Type/constraint checks will be case-insensitive on the field name
 ### `disallowUnvalidated`
 Fields that are not present in the type or restriction record will considered invalid fields
 
-### `interpretDates`
-If a field is set as a number, dates-like strings will still be interpreted and converted to their millisecond representations.
+### `dateInterpreter`
+A callback that determines how WizardQL interprets dates. Wizard will attempt to parse a value as a date if `'date'` is supplied in its type record
 
-`true` can be passed to enable this feature, using `new Date()` to parse dates or a custom callback can be passed.
+By default, this is simply `(v) => new Date(v)`
 
 ## Stringification
 Parsed expressions can be converted back into strings using the `stringify` function. The stringify function comes with its own slew of options as its second parameter

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { type Operation, type ComparisonOperation, type JunctionOperation, type Expression, type Condition, type UncheckedCondition, type Group, type Primitive, type TypeRecord, type Token, type ComparisonTypeToTSType, OPERATION_PURPOSE_DICTIONARY, COMPARISON_TYPE_DICTIONARY, OPERATION_ALIAS_DICTIONARY } from './spec';
+export { type Operation, type ComparisonOperation, type JunctionOperation, type Expression, type UncheckedExpression, type Condition, type UncheckedCondition, type Group, type Primitive, type TypeRecord, type Token, type ComparisonTypeToTSType, OPERATION_PURPOSE_DICTIONARY, COMPARISON_TYPE_DICTIONARY, OPERATION_ALIAS_DICTIONARY } from './spec';
 export { type ExpressionConstraints, QUOTE_EDGE_REGEX, parse, tokenize } from './parse';
 export { executeAsKnex } from './execute';
 export { type AggregationValue, summarize } from './summarize';

package/dist/index.js

@@ -60,15 +60,16 @@ var OPERATION_PURPOSE_DICTIONARY = {
 var COMPARISON_TYPE_DICTIONARY = {
   EQUAL: "primitive",
   NOTEQUAL: "primitive",
-  GEQ: "number",
-  GREATER: "number",
-  LEQ: "number",
-  LESS: "number",
+  GEQ: "numeric",
+  GREATER: "numeric",
+  LEQ: "numeric",
+  LESS: "numeric",
   IN: "array",
   NOTIN: "array",
   MATCH: "string",
   NOTMATCH: "string"
 };
+var TYPE_PRIORITY = ["boolean", "date", "number", "string"];
 // src/regex.ts
 var ESCAPE_REGEX = "(?<=(?<!\\\\)(?:\\\\\\\\)*)";
 var QUOTES = ["'", '"', "`"];
@@ -194,10 +195,6 @@ function _tokenize(expression, pattern) {
 function tokenize(expression) {
   return _tokenize(expression, TOKEN_REGEX);
 }
-function parseValue(token, isQuoted) {
-  const number = Number(token);
-  return isQuoted || isNaN(number) ? token === "true" ? true : token === "false" ? false : token : number;
-}
 function processToken(token) {
   const unquoted = token.match(QUOTE_EDGE_REGEX)?.groups?.quotecontent;
   const escaped = unquoted ?? token;
@@ -273,6 +270,53 @@ function complementExpression(expression) {
       break;
   }
 }
+function coerceType(value, fieldTypes, operatorTypes, dateInterpreter) {
+  const { unescaped } = processToken(value);
+  let operatorHits = 0;
+  let fieldHits = 0;
+  for (const type of TYPE_PRIORITY) {
+    const operatorHit = operatorTypes.includes(type);
+    const fieldHit = fieldTypes.includes(type);
+    if (operatorHit)
+      ++operatorHits;
+    if (fieldHit)
+      ++fieldHits;
+    if (!operatorHit || !fieldHit)
+      continue;
+    switch (type) {
+      case "boolean":
+        if (value === "true")
+          return true;
+        else if (value === "false")
+          return false;
+        break;
+      case "number": {
+        const num = Number(value);
+        if (isNaN(num))
+          break;
+        return num;
+      }
+      case "string":
+        return unescaped;
+      case "date": {
+        const num = Number(value);
+        const date = dateInterpreter(isNaN(num) ? unescaped : num);
+        if (isNaN(+date))
+          break;
+        return date;
+      }
+    }
+    if (operatorTypes.includes(type))
+      --operatorHits;
+    if (fieldTypes.includes(type))
+      --fieldHits;
+  }
+  if (!operatorHits)
+    throw new Error("operator");
+  if (!fieldHits)
+    throw new Error("field");
+  throw new Error("operator");
+}
 function validateCondition(condition, constraints, valueIsImplicit, ctx) {
   let validated = false;
   const field = constraints?.caseInsensitive ? [...Object.keys(constraints.types ?? {}), ...Object.keys(constraints.restricted ?? {})].find((k) => k.toLowerCase() === condition.field.toLowerCase()) ?? condition.field : condition.field;
@@ -282,26 +326,6 @@ function validateCondition(condition, constraints, valueIsImplicit, ctx) {
     throw new ConstraintError(`Unknown field "${condition.field}"`, ctx?.startToken, ctx?.startIndex, ctx?.endToken, ctx?.endIndex);
   const operationType = COMPARISON_TYPE_DICTIONARY[condition.operation];
   const types = type && (Array.isArray(type) ? type : [type]);
-  if (!valueIsImplicit && constraints?.interpretDates && (!types || types.includes("number")) && ["primitive", "number"].includes(operationType)) {
-    const validator = constraints.interpretDates === true ? (v) => +new Date(v) : constraints.interpretDates;
-    if (Array.isArray(condition.value)) {
-      for (let v = 0;v < condition.value.length; ++v) {
-        const val = condition.value[v];
-        if (typeof val === "string") {
-          const numberized = validator(val);
-          if (!isNaN(numberized))
-            condition.value[v] = numberized;
-        }
-      }
-    } else {
-      const val = condition.value;
-      if (typeof val === "string") {
-        const numberized = validator(val);
-        if (!isNaN(numberized))
-          condition.value = numberized;
-      }
-    }
-  }
   const values = Array.isArray(condition.value) ? condition.value : [condition.value];
   if (restriction === true)
     throw new ConstraintError(`Field "${condition.field}" is restricted`, ctx?.startToken, ctx?.startIndex, ctx?.endToken, ctx?.endIndex);
@@ -328,50 +352,50 @@ function validateCondition(condition, constraints, valueIsImplicit, ctx) {
     }
     validated = true;
   }
-  if (!valueIsImplicit && operationType === "string" && (typeof condition.value === "number" || typeof condition.value === "boolean"))
-    condition.value = condition.value.toString();
-  let operationAllowed;
-  switch (operationType) {
-    case "primitive":
-      operationAllowed = !Array.isArray(condition.value);
-      break;
-    case "string":
-      operationAllowed = typeof condition.value === "string";
-      break;
-    case "number":
-      operationAllowed = typeof condition.value === "number";
-      break;
-    case "array":
-      operationAllowed = Array.isArray(condition.value);
-      break;
-  }
-  if (!operationAllowed)
-    throw new ConstraintError(`Value "${condition.value.toString()}" not allowed for operation "${condition.operation}" which only allows for "${operationType}" type`, ctx?.startToken, ctx?.startIndex, ctx?.endToken, ctx?.endIndex);
-  if (types) {
-    const meets = values.every((v, i) => {
-      if (!valueIsImplicit && (typeof v === "number" && !types.includes("number") || typeof v === "boolean" && !types.includes("boolean")) && types.includes("string")) {
-        v = v.toString();
-        values[i] = v;
-        if (!Array.isArray(condition.value))
-          condition.value = v;
+  if (operationType === "array" && !Array.isArray(condition.value))
+    throw new ConstraintError(`Value "${condition.value.toString()}" is not permitted for "${condition.operation}" which expects an array`, ctx?.startToken, ctx?.startIndex, ctx?.endToken, ctx?.endIndex);
+  else if (operationType !== "array" && Array.isArray(condition.value))
+    throw new ConstraintError(`Value "${condition.value.toString()}" is not permitted for "${condition.operation}" which expects a non-array value`, ctx?.startToken, ctx?.startIndex, ctx?.endToken, ctx?.endIndex);
+  const dateInterpreter = constraints?.dateInterpreter ?? ((v) => new Date(v));
+  for (let i = 0;i < values.length; ++i) {
+    const v = values[i];
+    let opTypes;
+    if (valueIsImplicit)
+      opTypes = ["boolean"];
+    else {
+      switch (operationType) {
+        case "primitive":
+        case "array":
+          opTypes = ["boolean", "number", "string"];
+          if (types?.includes("date"))
+            opTypes.push("date");
+          break;
+        case "numeric":
+          opTypes = ["number"];
+          if (types?.includes("date"))
+            opTypes.push("date");
+          break;
+        case "string":
+          opTypes = ["string"];
+          break;
       }
-      return types.some((t) => {
-        switch (t) {
-          case "boolean":
-            return typeof v === "boolean";
-          case "number":
-            return typeof v === "number";
-          case "string":
-            return typeof v === "string";
-          default:
-            return false;
-        }
-      });
-    });
-    if (!meets)
-      throw new ConstraintError(`Value "${condition.value.toString()}" includes a type not permitted for field "${condition.field}". Allowed types: ${types.join(", ")}`, ctx?.startToken, ctx?.startIndex, ctx?.endToken, ctx?.endIndex);
-    validated = true;
+    }
+    try {
+      const value = coerceType(v, types ?? opTypes, opTypes, dateInterpreter);
+      values[i] = value;
+      if (!Array.isArray(condition.value))
+        condition.value = value;
+    } catch (err) {
+      switch (err.message) {
+        case "operator":
+          throw new ConstraintError(`Value "${condition.value.toString()}" not allowed for operation "${condition.operation}" which only allows for "${operationType}" type`, ctx?.startToken, ctx?.startIndex, ctx?.endToken, ctx?.endIndex);
+        case "field":
+          throw new ConstraintError(`Value "${condition.value.toString()}" includes a type not permitted for field "${condition.field}". Allowed types: ${(types ?? opTypes).join(", ")}`, ctx?.startToken, ctx?.startIndex, ctx?.endToken, ctx?.endIndex);
+      }
+    }
   }
+  if (types)
+    validated = true;
   const edit = condition;
   edit.field = field;
   edit.validated = validated;
@@ -424,7 +448,7 @@ function _parse(tokens, _offset, constraints) {
         type: "condition",
         field: field.content,
         operation: "EQUAL",
-        value: true
+        value: "true"
       }, constraints, true, baseCtx));
       inConjunction = false;
       expectingExpression = false;
@@ -436,10 +460,6 @@ function _parse(tokens, _offset, constraints) {
   }
   for (let t = 0;t < tokens.length; ++t) {
     const token = tokens[t];
-    const {
-      unquoted,
-      unescaped
-    } = processToken(token.content);
     if (token.content === ")")
       throw new ParseError("Unexpected closing parenthesis", token, _offset + t);
     if (["]", "}"].includes(token.content))
@@ -588,7 +608,7 @@ function _parse(tokens, _offset, constraints) {
           content: "EQUAL"
         };
         value = {
-          content: false,
+          content: "false",
           implicit: true
         };
         resolveCondition({
@@ -599,7 +619,7 @@ function _parse(tokens, _offset, constraints) {
         });
       } else {
         field = {
-          content: unescaped,
+          content: processToken(token.content).unescaped,
           token,
           index: _offset + t
         };
@@ -611,15 +631,14 @@ function _parse(tokens, _offset, constraints) {
         let resolveEntry = function(subtoken, subindex) {
           if (workingEntry) {
             const {
-              unquoted: unquotedWorkingEntry,
-              unescaped: unescapedWorkingEntry
+              unquoted: unquotedWorkingEntry
             } = processToken(workingEntry);
             const subquotes = workingEntry.match(QUOTE_REGEX);
             if (subquotes && (subquotes.index !== 0 || subquotes[0].length !== workingEntry.length))
               throw new ParseError("Quotes must surround entire values in arrays", firstEntryToken ?? subtoken, firstEntryTokenIndex ?? subindex, lastEntryToken ?? subtoken, lastEntryTokenIndex ?? subindex);
             if (!unquotedWorkingEntry && (token.content === "[" && new RegExp(`${ESCAPE_REGEX}(?:\\[|\\])`).test(workingEntry) || token.content === "{" && new RegExp(`${ESCAPE_REGEX}(?:\\{|\\})`).test(workingEntry)))
               throw new ParseError("Unescaped bracket in an array value", firstEntryToken ?? subtoken, firstEntryTokenIndex ?? subindex, lastEntryToken ?? subtoken, lastEntryTokenIndex ?? subindex);
-            arr.push(parseValue(unescapedWorkingEntry, unquotedWorkingEntry !== undefined));
+            arr.push(workingEntry);
             workingEntry = "";
             firstEntryToken = undefined;
             firstEntryTokenIndex = undefined;
@@ -666,7 +685,7 @@ function _parse(tokens, _offset, constraints) {
         t = closingIndex;
       } else {
         value = {
-          content: parseValue(unescaped, unquoted !== undefined),
+          content: token.content,
           token,
           index: _offset + t
         };

package/dist/parse.d.ts

@@ -12,15 +12,19 @@ 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 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
+     * 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<boolean | string | number | RegExp>]>>;
+    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
+     * 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;
     /**
@@ -34,11 +38,10 @@ export interface ExpressionConstraints<T extends TypeRecord, V extends boolean>
      */
     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
+     * A callback that determines how dates are interpreted\
+     * By default, uses `new Date()`
      */
-    interpretDates?: boolean | ((v: string) => number);
+    dateInterpreter?: (v: string | number) => Date;
 }
 /**
  * Parse a Wizard expression into its object form
@@ -48,4 +51,5 @@ export interface ExpressionConstraints<T extends TypeRecord, V extends boolean>
  * @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;
+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/spec.d.ts

@@ -74,10 +74,10 @@ export type ComparisonOperation = KeysWhereValue<typeof OPERATION_PURPOSE_DICTIO
 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 GEQ: "numeric";
+    readonly GREATER: "numeric";
+    readonly LEQ: "numeric";
+    readonly LESS: "numeric";
     readonly IN: "array";
     readonly NOTIN: "array";
     readonly MATCH: "string";
@@ -89,27 +89,31 @@ export type ComparisonTypeToTSType<T extends keyof typeof COMPARISON_TYPE_DICTIO
     boolean: boolean;
     string: string;
     number: number;
+    date: Date;
+    numeric: number | Date;
     array: Primitive[];
 }[typeof COMPARISON_TYPE_DICTIONARY[T]];
-export type FieldType = 'boolean' | 'string' | 'number';
+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> = {
     boolean: boolean;
     string: string;
     number: number;
+    date: Date;
 }[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;
+    [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, Primitive> = Record<string, Primitive>, V extends boolean = false> {
+export interface Group<R extends Record<string, unknown> = Record<string, Primitive>, V extends boolean = false> {
     type: 'group';
     /** The junction operator */
     operation: JunctionOperation;
@@ -121,14 +125,14 @@ export interface Group<R extends Record<string, Primitive> = Record<string, Prim
  * @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> {
+export interface Condition<R extends Record<string, unknown>, 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>;
+    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? */
     validated: true;
 }
@@ -142,7 +146,7 @@ export interface UncheckedCondition<O extends ComparisonOperation = ComparisonOp
     /** The name of the field */
     field: string;
     /** The value being checked */
-    value: ComparisonTypeToTSType<O>;
+    value: Exclude<ComparisonTypeToTSType<O>, Date>;
     /** Was this condition validated by the constraints or is its type unknown? */
     validated: false;
 }
@@ -156,7 +160,7 @@ type ReverseAggregate<T extends Record<any, any>> = {
 };
 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>> = {
+export type CheckedConditionSpread<R extends Record<string, unknown>> = {
     [K in keyof R]: {
         [O in keyof ReverseAggregatedTypes]: Condition<R, K, ReverseAggregatedTypes[O]>;
     }[keyof ReverseAggregatedTypes];
@@ -165,5 +169,8 @@ export type CheckedConditionSpread<R extends Record<string, Primitive>> = {
 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 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;
 export {};

package/package.json

@@ -6,18 +6,27 @@
   },
   "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",
+  "version": "2.0.1",
   "repository": {
     "type": "git",
-    "url": "https://github.com/guidance-analytics/wizard-ql.git"
+    "url": "git+https://github.com/guidance-analytics/wizard-ql.git"
   },
-  "keywords": ["query", "language", "querylanguage", "parser", "cel", "expression"],
+  "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/"],
+  "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 ."