patram 0.2.0 → 0.4.0

package/lib/parse-where-clause.js

@@ -6,7 +6,7 @@
  *   ParsedAggregateComparison,
  *   ParsedAggregateName,
  *   ParsedAggregateTerm,
- *   ParsedClause,
+ *   ParsedExpression,
  *   ParsedFieldName,
  *   ParsedTerm,
  *   ParsedTraversalTerm,
@@ -17,6 +17,16 @@
  * @typedef {{ index: number, where_clause: string }} ParserState
  */
 
+/**
+ * @typedef {{
+ *   expression: ParsedExpression,
+ *   success: true,
+ * } | {
+ *   diagnostic: PatramDiagnostic,
+ *   success: false,
+ * }} ParseExpressionResult
+ */
+
 /**
  * @typedef {{
  *   success: true,
@@ -28,7 +38,7 @@
  */
 
 /**
- * Parse one where clause into structured clauses.
+ * Parse one where clause into a structured boolean expression.
  *
  * @param {string} where_clause
  * @returns {ParseWhereClauseResult}
@@ -43,10 +53,10 @@ export function parseWhereClause(where_clause) {
     return fail(1, 'Query must not be empty.');
   }
 
-  const clauses_result = parseClauses(parser_state, null);
+  const expression_result = parseExpression(parser_state, null);
 
-  if (!clauses_result.success) {
-    return clauses_result;
+  if (!expression_result.success) {
+    return expression_result;
   }
 
   skipWhitespace(parser_state);
@@ -56,7 +66,7 @@ export function parseWhereClause(where_clause) {
   }
 
   return {
-    clauses: clauses_result.clauses,
+    expression: expression_result.expression,
     success: true,
   };
 }
@@ -64,12 +74,83 @@ export function parseWhereClause(where_clause) {
 /**
  * @param {ParserState} parser_state
  * @param {')' | null} stop_character
- * @returns {ParseWhereClauseResult}
+ * @returns {ParseExpressionResult}
+ */
+function parseExpression(parser_state, stop_character) {
+  return parseOrExpression(parser_state, stop_character);
+}
+
+/**
+ * @param {ParserState} parser_state
+ * @param {')' | null} stop_character
+ * @returns {ParseExpressionResult}
+ */
+function parseOrExpression(parser_state, stop_character) {
+  const first_expression_result = parseAndExpression(
+    parser_state,
+    stop_character,
+  );
+
+  if (!first_expression_result.success) {
+    return first_expression_result;
+  }
+
+  /** @type {ParsedExpression[]} */
+  const expressions = [first_expression_result.expression];
+
+  while (true) {
+    skipWhitespace(parser_state);
+
+    if (
+      currentCharacter(parser_state) === stop_character ||
+      isAtEnd(parser_state)
+    ) {
+      return collapseBooleanExpression('or', expressions);
+    }
+
+    if (!consumeKeyword(parser_state, 'or')) {
+      return collapseBooleanExpression('or', expressions);
+    }
+
+    skipWhitespace(parser_state);
+
+    if (
+      currentCharacter(parser_state) === stop_character ||
+      isAtEnd(parser_state)
+    ) {
+      return failExpectedTerm(parser_state);
+    }
+
+    const next_expression_result = parseAndExpression(
+      parser_state,
+      stop_character,
+    );
+
+    if (!next_expression_result.success) {
+      return next_expression_result;
+    }
+
+    expressions.push(next_expression_result.expression);
+  }
+}
+
+/**
+ * @param {ParserState} parser_state
+ * @param {')' | null} stop_character
+ * @returns {ParseExpressionResult}
  */
-function parseClauses(parser_state, stop_character) {
-  /** @type {ParsedClause[]} */
-  const clauses = [];
-  let is_first_clause = true;
+function parseAndExpression(parser_state, stop_character) {
+  const first_expression_result = parseUnaryExpression(
+    parser_state,
+    stop_character,
+  );
+
+  if (!first_expression_result.success) {
+    return first_expression_result;
+  }
+
+  /** @type {ParsedExpression[]} */
+  const expressions = [first_expression_result.expression];
 
   while (true) {
     skipWhitespace(parser_state);
@@ -78,68 +159,131 @@ function parseClauses(parser_state, stop_character) {
       currentCharacter(parser_state) === stop_character ||
       isAtEnd(parser_state)
     ) {
-      return is_first_clause
-        ? fail(parser_state.where_clause.length + 1, 'Expected a query term.')
-        : { clauses, success: true };
+      return collapseBooleanExpression('and', expressions);
     }
 
-    if (!is_first_clause) {
-      if (!consumeKeyword(parser_state, 'and')) {
-        return failToken(parser_state);
-      }
-
-      skipWhitespace(parser_state);
-
-      if (
-        currentCharacter(parser_state) === stop_character ||
-        isAtEnd(parser_state)
-      ) {
-        return fail(
-          parser_state.where_clause.length + 1,
-          'Expected a query term.',
-        );
-      }
+    if (!consumeKeyword(parser_state, 'and')) {
+      return collapseBooleanExpression('and', expressions);
     }
 
-    const clause_result = parseClause(parser_state);
+    skipWhitespace(parser_state);
 
-    if (!clause_result.success) {
-      return clause_result;
+    if (
+      currentCharacter(parser_state) === stop_character ||
+      isAtEnd(parser_state)
+    ) {
+      return failExpectedTerm(parser_state);
     }
 
-    clauses.push(clause_result.clause);
-    is_first_clause = false;
+    const next_expression_result = parseUnaryExpression(
+      parser_state,
+      stop_character,
+    );
+
+    if (!next_expression_result.success) {
+      return next_expression_result;
+    }
+
+    expressions.push(next_expression_result.expression);
   }
 }
 
 /**
  * @param {ParserState} parser_state
- * @returns {{ clause: ParsedClause, success: true } | { diagnostic: PatramDiagnostic, success: false }}
+ * @param {')' | null} stop_character
+ * @returns {ParseExpressionResult}
  */
-function parseClause(parser_state) {
-  const clause_start = parser_state.index;
-  const is_negated = consumeKeyword(parser_state, 'not');
+function parseUnaryExpression(parser_state, stop_character) {
+  skipWhitespace(parser_state);
+  const start_index = parser_state.index;
+
+  if (!consumeKeyword(parser_state, 'not')) {
+    return parsePrimaryExpression(parser_state, stop_character);
+  }
+
+  const whitespace_length = skipWhitespace(parser_state);
 
-  if (is_negated && !consumeRequiredWhitespace(parser_state)) {
+  if (whitespace_length === 0 && currentCharacter(parser_state) !== '(') {
     return fail(
-      clause_start + 1,
-      `Unsupported query token "${readToken(parser_state, clause_start)}".`,
+      start_index + 1,
+      `Unsupported query token "${readToken(parser_state, start_index)}".`,
     );
   }
 
+  if (
+    currentCharacter(parser_state) === stop_character ||
+    isAtEnd(parser_state)
+  ) {
+    return failExpectedTerm(parser_state);
+  }
+
+  const expression_result = parseUnaryExpression(parser_state, stop_character);
+
+  if (!expression_result.success) {
+    return expression_result;
+  }
+
+  return successExpression({
+    expression: expression_result.expression,
+    kind: 'not',
+  });
+}
+
+/**
+ * @param {ParserState} parser_state
+ * @param {')' | null} stop_character
+ * @returns {ParseExpressionResult}
+ */
+function parsePrimaryExpression(parser_state, stop_character) {
+  skipWhitespace(parser_state);
+
+  if (
+    currentCharacter(parser_state) === stop_character ||
+    isAtEnd(parser_state)
+  ) {
+    return failExpectedTerm(parser_state);
+  }
+
+  if (consumeOperator(parser_state, '(')) {
+    const expression_result = parseExpression(parser_state, ')');
+
+    if (!expression_result.success) {
+      return expression_result;
+    }
+
+    if (!consumeOperator(parser_state, ')')) {
+      return failToken(parser_state);
+    }
+
+    return expression_result;
+  }
+
   const term_result = parseTerm(parser_state);
 
   if (!term_result.success) {
     return term_result;
   }
 
-  return {
-    clause: {
-      is_negated,
-      term: term_result.term,
-    },
-    success: true,
-  };
+  return successExpression({
+    kind: 'term',
+    term: term_result.term,
+  });
+}
+
+/**
+ * @param {'and' | 'or'} kind
+ * @param {ParsedExpression[]} expressions
+ * @returns {ParseExpressionResult}
+ */
+function collapseBooleanExpression(kind, expressions) {
+  if (expressions.length === 1) {
+    return successExpression(expressions[0]);
+  }
+
+  return successExpression({
+    expressions,
+    kind,
+  });
 }
 
 /**
@@ -188,10 +332,10 @@ function parseAggregate(parser_state) {
   }
 
   skipWhitespace(parser_state);
-  const clauses_result = parseClauses(parser_state, ')');
+  const expression_result = parseExpression(parser_state, ')');
 
-  if (!clauses_result.success) {
-    return clauses_result;
+  if (!expression_result.success) {
+    return expression_result;
   }
 
   if (!consumeOperator(parser_state, ')')) {
@@ -202,7 +346,7 @@ function parseAggregate(parser_state) {
     parser_state,
     aggregate_name,
     traversal_result.traversal,
-    clauses_result.clauses,
+    expression_result.expression,
   );
 }
 
@@ -218,30 +362,32 @@ function parseAtomicTerm(parser_state) {
     return failToken(parser_state);
   }
 
-  return (
-    parseFieldSet(parser_state, field_or_relation_name) ??
-    parseOperatorTerm(parser_state, start_index, field_or_relation_name)
-  );
+  return parseOperatorTerm(parser_state, start_index, field_or_relation_name);
 }
 
 /**
  * @param {ParserState} parser_state
  * @param {ParsedAggregateName} aggregate_name
  * @param {ParsedTraversalTerm} traversal
- * @param {ParsedClause[]} clauses
+ * @param {ParsedExpression} expression
  * @returns {ParseTermResult}
  */
-function createAggregateTerm(parser_state, aggregate_name, traversal, clauses) {
+function createAggregateTerm(
+  parser_state,
+  aggregate_name,
+  traversal,
+  expression,
+) {
   /** @type {ParsedAggregateTerm} */
   const aggregate_term = {
     aggregate_name,
-    clauses,
+    expression,
     kind: 'aggregate',
     traversal,
   };
 
   if (aggregate_name !== 'count') {
-    return success(aggregate_term);
+    return successTerm(aggregate_term);
   }
 
   const count_tail = parseCountTail(parser_state);
@@ -250,7 +396,7 @@ function createAggregateTerm(parser_state, aggregate_name, traversal, clauses) {
     return failToken(parser_state);
   }
 
-  return success({
+  return successTerm({
     ...aggregate_term,
     comparison: count_tail.comparison,
     value: count_tail.value,
@@ -259,15 +405,12 @@ function createAggregateTerm(parser_state, aggregate_name, traversal, clauses) {
 
 /**
  * @param {ParserState} parser_state
+ * @param {number} start_index
  * @param {ParsedFieldName | string} field_name
  * @returns {ParseTermResult | null}
  */
-function parseFieldSet(parser_state, field_name) {
-  if (!isSupportedFieldName(field_name)) {
-    return null;
-  }
-
-  const start_index = parser_state.index;
+function parseFieldSet(parser_state, start_index, field_name) {
+  const operator_start_index = parser_state.index;
 
   if (!consumeRequiredWhitespace(parser_state)) {
     return null;
@@ -276,7 +419,7 @@ function parseFieldSet(parser_state, field_name) {
   const operator = parseSetOperator(parser_state);
 
   if (!operator) {
-    parser_state.index = start_index;
+    parser_state.index = operator_start_index;
     return null;
   }
 
@@ -287,7 +430,13 @@ function parseFieldSet(parser_state, field_name) {
   const values = parseList(parser_state);
 
   return values
-    ? success({ field_name, kind: 'field_set', operator, values })
+    ? successTerm({
+        column: start_index + 1,
+        field_name,
+        kind: 'field_set',
+        operator,
+        values,
+      })
     : failToken(parser_state);
 }
 
@@ -298,18 +447,46 @@ function parseFieldSet(parser_state, field_name) {
  * @returns {ParseTermResult}
  */
 function parseOperatorTerm(parser_state, start_index, field_or_relation_name) {
-  const prefix_term = parsePrefixTerm(parser_state, field_or_relation_name);
+  const field_set = parseFieldSet(
+    parser_state,
+    start_index,
+    field_or_relation_name,
+  );
+
+  if (field_set) {
+    return field_set;
+  }
+
+  const prefix_term = parsePrefixTerm(
+    parser_state,
+    start_index,
+    field_or_relation_name,
+  );
 
   if (prefix_term) {
     return prefix_term;
   }
 
-  const contains_term = parseContainsTerm(parser_state, field_or_relation_name);
+  const contains_term = parseContainsTerm(
+    parser_state,
+    start_index,
+    field_or_relation_name,
+  );
 
   if (contains_term) {
     return contains_term;
   }
 
+  const comparison_term = parseFieldComparisonTerm(
+    parser_state,
+    start_index,
+    field_or_relation_name,
+  );
+
+  if (comparison_term) {
+    return comparison_term;
+  }
+
   const equality_term = parseEqualityTerm(
     parser_state,
     start_index,
@@ -321,7 +498,7 @@ function parseOperatorTerm(parser_state, start_index, field_or_relation_name) {
   }
 
   if (consumeOperator(parser_state, ':*')) {
-    return success({
+    return successTerm({
       column: start_index + 1,
       kind: 'relation',
       relation_name: field_or_relation_name,
@@ -395,39 +572,51 @@ function parseSetOperator(parser_state) {
 
 /**
  * @param {ParserState} parser_state
+ * @param {number} start_index
  * @param {string} field_name
  * @returns {ParseTermResult | null}
  */
-function parsePrefixTerm(parser_state, field_name) {
-  if (field_name !== 'id' && field_name !== 'path') {
-    return null;
-  }
-
+function parsePrefixTerm(parser_state, start_index, field_name) {
   if (!consumeOperator(parser_state, '^=')) {
     return null;
   }
 
+  skipWhitespace(parser_state);
   const value = parseBareValue(parser_state);
 
   return value
-    ? success({ field_name, kind: 'field', operator: '^=', value })
+    ? successTerm({
+        column: start_index + 1,
+        field_name,
+        kind: 'field',
+        operator: '^=',
+        value,
+      })
     : failToken(parser_state);
 }
 
 /**
  * @param {ParserState} parser_state
+ * @param {number} start_index
  * @param {string} field_name
  * @returns {ParseTermResult | null}
  */
-function parseContainsTerm(parser_state, field_name) {
-  if (field_name !== 'title' || !consumeOperator(parser_state, '~')) {
+function parseContainsTerm(parser_state, start_index, field_name) {
+  if (!consumeOperator(parser_state, '~')) {
     return null;
   }
 
+  skipWhitespace(parser_state);
   const value = parseBareValue(parser_state);
 
   return value
-    ? success({ field_name: 'title', kind: 'field', operator: '~', value })
+    ? successTerm({
+        column: start_index + 1,
+        field_name,
+        kind: 'field',
+        operator: '~',
+        value,
+      })
     : failToken(parser_state);
 }
 
@@ -442,14 +631,20 @@ function parseEqualityTerm(parser_state, start_index, field_or_relation_name) {
     return null;
   }
 
+  skipWhitespace(parser_state);
   const value = parseBareValue(parser_state);
 
   if (!value) {
     return failToken(parser_state);
   }
 
-  if (isExactMatchField(field_or_relation_name)) {
-    return success({
+  if (
+    field_or_relation_name.startsWith('$') ||
+    field_or_relation_name === 'title' ||
+    !value.includes(':')
+  ) {
+    return successTerm({
+      column: start_index + 1,
       field_name: field_or_relation_name,
       kind: 'field',
       operator: '=',
@@ -457,17 +652,54 @@ function parseEqualityTerm(parser_state, start_index, field_or_relation_name) {
     });
   }
 
-  if (value.includes(':')) {
-    return success({
-      column: start_index + 1,
-      kind: 'relation_target',
-      relation_name: field_or_relation_name,
-      target_id: value,
-    });
+  return successTerm({
+    column: start_index + 1,
+    kind: 'relation_target',
+    relation_name: field_or_relation_name,
+    target_id: value,
+  });
+}
+
+/**
+ * @param {ParserState} parser_state
+ * @param {number} start_index
+ * @param {string} field_name
+ * @returns {ParseTermResult | null}
+ */
+function parseFieldComparisonTerm(parser_state, start_index, field_name) {
+  const operator = parseFieldComparisonOperator(parser_state);
+
+  if (!operator) {
+    return null;
   }
 
-  parser_state.index = start_index;
-  return failToken(parser_state);
+  skipWhitespace(parser_state);
+  const value = parseBareValue(parser_state);
+
+  if (!value) {
+    return failToken(parser_state);
+  }
+
+  return successTerm({
+    column: start_index + 1,
+    field_name,
+    kind: 'field',
+    operator,
+    value,
+  });
+}
+
+/**
+ * @param {ParserState} parser_state
+ * @returns {'!=' | '<=' | '>=' | '<' | '>' | null}
+ */
+function parseFieldComparisonOperator(parser_state) {
+  /** @type {Array<'!=' | '<=' | '>=' | '<' | '>'>} */
+  const comparisons = ['!=', '<=', '>=', '<', '>'];
+
+  return (
+    comparisons.find((value) => consumeOperator(parser_state, value)) ?? null
+  );
 }
 
 /**
@@ -526,7 +758,7 @@ function parseComparison(parser_state) {
  * @returns {string | null}
  */
 function parseIdentifier(parser_state) {
-  return readMatch(parser_state, /^[a-z_]+/u);
+  return readMatch(parser_state, /^\$?[a-z_][a-z0-9_]*/u);
 }
 
 /**
@@ -644,26 +876,18 @@ function isAtEnd(parser_state) {
 }
 
 /**
- * @param {string} field_name
- * @returns {field_name is ParsedFieldName}
- */
-function isSupportedFieldName(field_name) {
-  return ['id', 'kind', 'path', 'status', 'title'].includes(field_name);
-}
-
-/**
- * @param {string} field_name
- * @returns {field_name is 'id' | 'kind' | 'path' | 'status'}
+ * @param {ParsedExpression} expression
+ * @returns {ParseExpressionResult}
  */
-function isExactMatchField(field_name) {
-  return ['id', 'kind', 'path', 'status'].includes(field_name);
+function successExpression(expression) {
+  return { expression, success: true };
 }
 
 /**
  * @param {ParsedTerm} term
  * @returns {ParseTermResult}
  */
-function success(term) {
+function successTerm(term) {
   return { success: true, term };
 }
 
@@ -678,6 +902,19 @@ function failToken(parser_state) {
   );
 }
 
+/**
+ * @param {ParserState} parser_state
+ * @returns {{ diagnostic: PatramDiagnostic, success: false }}
+ */
+function failExpectedTerm(parser_state) {
+  return fail(
+    isAtEnd(parser_state)
+      ? parser_state.where_clause.length + 1
+      : parser_state.index + 1,
+    'Expected a query term.',
+  );
+}
+
 /**
  * @param {number} column
  * @param {string} message