patram 0.1.1 → 0.2.0

package/lib/query-graph.js

@@ -1,6 +1,16 @@
+/* eslint-disable max-lines */
 /**
  * @import { BuildGraphResult, GraphNode } from './build-graph.types.ts';
  * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import {
+ *   ParsedAggregateTerm,
+ *   ParsedClause,
+ *   ParsedFieldSetTerm,
+ *   ParsedFieldTerm,
+ *   ParsedRelationTargetTerm,
+ *   ParsedTerm,
+ *   ParsedTraversalTerm,
+ * } from './parse-where-clause.types.ts';
  */
 
 import { parseWhereClause } from './parse-where-clause.js';
@@ -26,7 +36,21 @@ import { parseWhereClause } from './parse-where-clause.js';
 export const DEFAULT_QUERY_LIMIT = 25;
 
 /**
- * Filter graph nodes with the v0 query language.
+ * @typedef {{
+ *   incoming: Map<string, Map<string, Set<string>>>,
+ *   outgoing: Map<string, Map<string, Set<string>>>,
+ * }} RelationIndexes
+ */
+
+/**
+ * @typedef {{
+ *   nodes: BuildGraphResult['nodes'],
+ *   relation_indexes: RelationIndexes,
+ * }} EvaluationContext
+ */
+
+/**
+ * Filter graph nodes with the query language.
  *
  * @param {BuildGraphResult} graph
  * @param {string} where_clause
@@ -44,11 +68,13 @@ export function queryGraph(graph, where_clause, pagination_options = {}) {
     };
   }
 
-  const predicates = parse_result.clauses.map(createPredicate);
-  const relation_index = createRelationIndex(graph.edges);
+  const evaluation_context = {
+    nodes: graph.nodes,
+    relation_indexes: createRelationIndexes(graph.edges),
+  };
   const graph_nodes = Object.values(graph.nodes).sort(compareGraphNodes);
   const matching_nodes = graph_nodes.filter((graph_node) =>
-    predicates.every((predicate) => predicate(graph_node, relation_index)),
+    matchesClauses(graph_node, parse_result.clauses, evaluation_context),
   );
   const paginated_nodes = paginateNodes(matching_nodes, pagination_options);
 
@@ -60,178 +86,264 @@ export function queryGraph(graph, where_clause, pagination_options = {}) {
 }
 
 /**
- * @param {{ is_negated: boolean, term: { kind: 'field', field_name: 'id' | 'kind' | 'path' | 'status' | 'title', operator: '=' | '^=' | '~', value: string } | { kind: 'relation', relation_name: string } | { kind: 'relation_target', relation_name: string, target_id: string } }} clause
- * @returns {(graph_node: GraphNode, relation_index: Map<string, Map<string, Set<string>>>) => boolean}
+ * @param {GraphNode} graph_node
+ * @param {ParsedClause[]} clauses
+ * @param {EvaluationContext} evaluation_context
+ * @returns {boolean}
  */
-function createPredicate(clause) {
-  if (clause.term.kind === 'relation') {
-    return createRelationPredicate(
-      clause.term.relation_name,
-      clause.is_negated,
-    );
-  }
+function matchesClauses(graph_node, clauses, evaluation_context) {
+  return clauses.every((clause) =>
+    matchesClause(graph_node, clause, evaluation_context),
+  );
+}
 
-  if (clause.term.kind === 'relation_target') {
-    return createRelationTargetPredicate(
-      clause.term.relation_name,
-      clause.term.target_id,
-      clause.is_negated,
-    );
-  }
+/**
+ * @param {GraphNode} graph_node
+ * @param {ParsedClause} clause
+ * @param {EvaluationContext} evaluation_context
+ * @returns {boolean}
+ */
+function matchesClause(graph_node, clause, evaluation_context) {
+  const is_match = matchesTerm(graph_node, clause.term, evaluation_context);
 
-  return createFieldPredicateFromTerm(clause.term, clause.is_negated);
+  return clause.is_negated ? !is_match : is_match;
 }
 
 /**
- * @param {string} relation_name
- * @param {boolean} is_negated
- * @returns {(graph_node: GraphNode, relation_index: Map<string, Map<string, Set<string>>>) => boolean}
+ * @param {GraphNode} graph_node
+ * @param {ParsedTerm} term
+ * @param {EvaluationContext} evaluation_context
+ * @returns {boolean}
  */
-function createRelationPredicate(relation_name, is_negated) {
-  return (graph_node, relation_index) => {
-    const relation_targets = relation_index.get(graph_node.id);
-    const is_match = relation_targets?.has(relation_name) ?? false;
+function matchesTerm(graph_node, term, evaluation_context) {
+  if (term.kind === 'aggregate') {
+    return matchesAggregateTerm(graph_node, term, evaluation_context);
+  }
 
-    return is_negated ? !is_match : is_match;
-  };
+  if (term.kind === 'field') {
+    return matchesFieldTerm(graph_node, term);
+  }
+
+  if (term.kind === 'field_set') {
+    return matchesFieldSetTerm(graph_node, term);
+  }
+
+  if (term.kind === 'relation') {
+    return hasOutgoingRelation(
+      graph_node.id,
+      term.relation_name,
+      evaluation_context.relation_indexes,
+    );
+  }
+
+  return matchesRelationTargetTerm(graph_node, term, evaluation_context);
 }
 
 /**
- * @param {string} relation_name
- * @param {string} target_id
- * @param {boolean} is_negated
- * @returns {(graph_node: GraphNode, relation_index: Map<string, Map<string, Set<string>>>) => boolean}
+ * @param {GraphNode} graph_node
+ * @param {ParsedAggregateTerm} term
+ * @param {EvaluationContext} evaluation_context
+ * @returns {boolean}
  */
-function createRelationTargetPredicate(relation_name, target_id, is_negated) {
-  return (graph_node, relation_index) => {
-    const relation_targets = relation_index.get(graph_node.id);
-    const matching_targets = relation_targets?.get(relation_name);
-    const is_match = matching_targets?.has(target_id) ?? false;
+function matchesAggregateTerm(graph_node, term, evaluation_context) {
+  const related_nodes = getRelatedNodes(
+    graph_node.id,
+    term.traversal,
+    evaluation_context,
+  );
+  const matching_count = related_nodes.filter((related_node) =>
+    matchesClauses(related_node, term.clauses, evaluation_context),
+  ).length;
 
-    return is_negated ? !is_match : is_match;
-  };
+  if (term.aggregate_name === 'any') {
+    return matching_count > 0;
+  }
+
+  if (term.aggregate_name === 'none') {
+    return matching_count === 0;
+  }
+
+  return compareNumbers(
+    matching_count,
+    term.comparison ?? '=',
+    term.value ?? 0,
+  );
 }
 
 /**
- * @param {BuildGraphResult['edges']} graph_edges
- * @returns {Map<string, Map<string, Set<string>>>}
+ * @param {GraphNode} graph_node
+ * @param {ParsedFieldTerm} term
+ * @returns {boolean}
  */
-function createRelationIndex(graph_edges) {
-  /** @type {Map<string, Map<string, Set<string>>>} */
-  const relation_index = new Map();
-
-  for (const graph_edge of graph_edges) {
-    let relation_targets = relation_index.get(graph_edge.from);
+function matchesFieldTerm(graph_node, term) {
+  const term_key = `${term.field_name}${term.operator}`;
 
-    if (!relation_targets) {
-      relation_targets = new Map();
-      relation_index.set(graph_edge.from, relation_targets);
-    }
+  if (
+    term_key === 'id=' ||
+    term_key === 'kind=' ||
+    term_key === 'path=' ||
+    term_key === 'status='
+  ) {
+    return graph_node[term.field_name] === term.value;
+  }
 
-    let target_ids = relation_targets.get(graph_edge.relation);
+  if (term_key === 'id^=') {
+    return graph_node.id.startsWith(term.value);
+  }
 
-    if (!target_ids) {
-      target_ids = new Set();
-      relation_targets.set(graph_edge.relation, target_ids);
-    }
+  if (term_key === 'path^=') {
+    return (graph_node.path ?? '').startsWith(term.value);
+  }
 
-    target_ids.add(graph_edge.to);
+  if (term_key === 'title~') {
+    return (graph_node.title ?? '')
+      .toLocaleLowerCase('en')
+      .includes(term.value.toLocaleLowerCase('en'));
   }
 
-  return relation_index;
+  throw new Error('Unsupported parsed where clause.');
 }
 
 /**
- * @param {string} field_name
- * @param {string} expected_value
- * @param {boolean} is_negated
- * @returns {(graph_node: GraphNode) => boolean}
+ * @param {GraphNode} graph_node
+ * @param {ParsedFieldSetTerm} term
+ * @returns {boolean}
  */
-function createFieldPredicate(field_name, expected_value, is_negated) {
-  return (graph_node) => {
-    const actual_value = graph_node[field_name];
-    const is_match = actual_value === expected_value;
+function matchesFieldSetTerm(graph_node, term) {
+  const actual_value = graph_node[term.field_name];
+  const is_member = actual_value ? term.values.includes(actual_value) : false;
 
-    return is_negated ? !is_match : is_match;
-  };
+  return term.operator === 'in' ? is_member : !is_member;
 }
 
 /**
- * @param {string} id_prefix
- * @param {boolean} is_negated
- * @returns {(graph_node: GraphNode) => boolean}
+ * @param {GraphNode} graph_node
+ * @param {ParsedRelationTargetTerm} term
+ * @param {EvaluationContext} evaluation_context
+ * @returns {boolean}
  */
-function createIdPrefixPredicate(id_prefix, is_negated) {
-  return (graph_node) => {
-    const id_value = graph_node.id;
-    const is_match = id_value.startsWith(id_prefix);
+function matchesRelationTargetTerm(graph_node, term, evaluation_context) {
+  const relation_targets = evaluation_context.relation_indexes.outgoing.get(
+    graph_node.id,
+  );
+  const matching_targets = relation_targets?.get(term.relation_name);
 
-    return is_negated ? !is_match : is_match;
-  };
+  return matching_targets?.has(term.target_id) ?? false;
 }
 
 /**
- * @param {string} path_prefix
- * @param {boolean} is_negated
- * @returns {(graph_node: GraphNode) => boolean}
+ * @param {string} node_id
+ * @param {string} relation_name
+ * @param {RelationIndexes} relation_indexes
+ * @returns {boolean}
  */
-function createPathPrefixPredicate(path_prefix, is_negated) {
-  return (graph_node) => {
-    const path_value = graph_node.path ?? '';
-    const is_match = path_value.startsWith(path_prefix);
+function hasOutgoingRelation(node_id, relation_name, relation_indexes) {
+  const relation_targets = relation_indexes.outgoing.get(node_id);
 
-    return is_negated ? !is_match : is_match;
-  };
+  return relation_targets?.has(relation_name) ?? false;
 }
 
 /**
- * @param {string} title_text
- * @param {boolean} is_negated
- * @returns {(graph_node: GraphNode) => boolean}
+ * @param {string} node_id
+ * @param {ParsedTraversalTerm} traversal
+ * @param {EvaluationContext} evaluation_context
+ * @returns {GraphNode[]}
  */
-function createTitlePredicate(title_text, is_negated) {
-  const normalized_title_text = title_text.toLocaleLowerCase('en');
+function getRelatedNodes(node_id, traversal, evaluation_context) {
+  const relation_index =
+    traversal.direction === 'in'
+      ? evaluation_context.relation_indexes.incoming
+      : evaluation_context.relation_indexes.outgoing;
+  const relation_targets = relation_index.get(node_id);
+  const target_ids = relation_targets?.get(traversal.relation_name);
+
+  if (!target_ids) {
+    return [];
+  }
 
-  return (graph_node) => {
-    const title_value = graph_node.title ?? '';
-    const is_match = title_value
-      .toLocaleLowerCase('en')
-      .includes(normalized_title_text);
+  return [...target_ids].flatMap((target_id) => {
+    const target_node = evaluation_context.nodes[target_id];
 
-    return is_negated ? !is_match : is_match;
-  };
+    return target_node ? [target_node] : [];
+  });
 }
 
 /**
- * @param {{ field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field', operator: '=' | '^=' | '~', value: string }} term
- * @param {boolean} is_negated
- * @returns {(graph_node: GraphNode, relation_index: Map<string, Map<string, Set<string>>>) => boolean}
+ * @param {number} left_value
+ * @param {'!=' | '<' | '<=' | '=' | '>' | '>='} comparison
+ * @param {number} right_value
+ * @returns {boolean}
  */
-function createFieldPredicateFromTerm(term, is_negated) {
-  const term_key = `${term.field_name}${term.operator}`;
+function compareNumbers(left_value, comparison, right_value) {
+  if (comparison === '!=') {
+    return left_value !== right_value;
+  }
 
-  if (
-    term_key === 'id=' ||
-    term_key === 'kind=' ||
-    term_key === 'status=' ||
-    term_key === 'path='
-  ) {
-    return createFieldPredicate(term.field_name, term.value, is_negated);
+  if (comparison === '<') {
+    return left_value < right_value;
   }
 
-  if (term_key === 'id^=') {
-    return createIdPrefixPredicate(term.value, is_negated);
+  if (comparison === '<=') {
+    return left_value <= right_value;
   }
 
-  if (term_key === 'path^=') {
-    return createPathPrefixPredicate(term.value, is_negated);
+  if (comparison === '=') {
+    return left_value === right_value;
   }
 
-  if (term_key === 'title~') {
-    return createTitlePredicate(term.value, is_negated);
+  if (comparison === '>') {
+    return left_value > right_value;
   }
 
-  throw new Error('Unsupported parsed where clause.');
+  if (comparison === '>=') {
+    return left_value >= right_value;
+  }
+
+  throw new Error('Unsupported aggregate comparison.');
+}
+
+/**
+ * @param {BuildGraphResult['edges']} graph_edges
+ * @returns {RelationIndexes}
+ */
+function createRelationIndexes(graph_edges) {
+  return {
+    incoming: createDirectionalRelationIndex(graph_edges, 'to', 'from'),
+    outgoing: createDirectionalRelationIndex(graph_edges, 'from', 'to'),
+  };
+}
+
+/**
+ * @param {BuildGraphResult['edges']} graph_edges
+ * @param {'from' | 'to'} source_key
+ * @param {'from' | 'to'} target_key
+ * @returns {Map<string, Map<string, Set<string>>>}
+ */
+function createDirectionalRelationIndex(graph_edges, source_key, target_key) {
+  /** @type {Map<string, Map<string, Set<string>>>} */
+  const relation_index = new Map();
+
+  for (const graph_edge of graph_edges) {
+    const source_id = graph_edge[source_key];
+    const target_id = graph_edge[target_key];
+    let relation_targets = relation_index.get(source_id);
+
+    if (!relation_targets) {
+      relation_targets = new Map();
+      relation_index.set(source_id, relation_targets);
+    }
+
+    let target_ids = relation_targets.get(graph_edge.relation);
+
+    if (!target_ids) {
+      target_ids = new Set();
+      relation_targets.set(graph_edge.relation, target_ids);
+    }
+
+    target_ids.add(target_id);
+  }
+
+  return relation_index;
 }
 
 /**