wizard-ql 1.0.0 → 2.0.0

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.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

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,15 +89,18 @@ 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>;
@@ -105,6 +108,7 @@ export type Primitive = FieldTypeToTSType<FieldType>;
 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;
 };
+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

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.0",
   "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 ."