patram 0.3.0 → 0.5.0

package/lib/patram-config.js

@@ -1,5 +1,4 @@
 /**
- * @import { PatramConfig } from './patram-config.types.ts';
  * @import { RefinementCtx } from 'zod';
  */
 
@@ -11,14 +10,20 @@ const CLAIM_TYPE_SCHEMA = z.string().min(1);
 const KEY_SOURCE_SCHEMA = z.enum(['path', 'value']);
 const TARGET_SCHEMA = z.enum(['path', 'value']);
 
-const class_definition_schema = z
+/**
+ * @typedef {z.output<typeof class_definition_schema>} ClassDefinition
+ */
+export const class_definition_schema = z
   .object({
     builtin: z.boolean().optional(),
     label: z.string().min(1).optional(),
   })
   .strict();
 
-const relation_definition_schema = z
+/**
+ * @typedef {z.output<typeof relation_definition_schema>} RelationDefinition
+ */
+export const relation_definition_schema = z
   .object({
     builtin: z.boolean().optional(),
     from: z.array(CLASS_NAME_SCHEMA).min(1),
@@ -26,6 +31,9 @@ const relation_definition_schema = z
   })
   .strict();
 
+/**
+ * @typedef {z.output<typeof mapping_node_schema>} MappingNodeDefinition
+ */
 const mapping_node_schema = z
   .object({
     class: CLASS_NAME_SCHEMA,
@@ -34,6 +42,9 @@ const mapping_node_schema = z
   })
   .strict();
 
+/**
+ * @typedef {z.output<typeof mapping_emit_schema>} MappingEmitDefinition
+ */
 const mapping_emit_schema = z
   .object({
     relation: RELATION_NAME_SCHEMA,
@@ -42,7 +53,10 @@ const mapping_emit_schema = z
   })
   .strict();
 
-const mapping_definition_schema = z
+/**
+ * @typedef {z.output<typeof mapping_definition_schema>} MappingDefinition
+ */
+export const mapping_definition_schema = z
   .object({
     emit: mapping_emit_schema.optional(),
     node: mapping_node_schema.optional(),
@@ -50,6 +64,9 @@ const mapping_definition_schema = z
   .strict()
   .superRefine(validateMappingDefinition);
 
+/**
+ * @typedef {z.output<typeof patramConfigSchema>} PatramGraphConfig
+ */
 export const patramConfigSchema = z
   .object({
     $schema: z.url().optional(),
@@ -64,7 +81,7 @@ export const patramConfigSchema = z
  * Parse and validate Patram JSON configuration.
  *
  * @param {unknown} config_json
- * @returns {PatramConfig}
+ * @returns {PatramGraphConfig}
  */
 export function parsePatramConfig(config_json) {
   return patramConfigSchema.parse(config_json);
@@ -86,7 +103,7 @@ function validateMappingDefinition(mapping_definition, refinement_context) {
 }
 
 /**
- * @param {PatramConfig} config_json
+ * @param {PatramGraphConfig} config_json
  * @param {RefinementCtx} refinement_context
  */
 function validatePatramConfigReferences(config_json, refinement_context) {
@@ -96,7 +113,7 @@ function validatePatramConfigReferences(config_json, refinement_context) {
 }
 
 /**
- * @param {PatramConfig} config_json
+ * @param {PatramGraphConfig} config_json
  * @param {RefinementCtx} refinement_context
  */
 function validateRelationClasses(config_json, refinement_context) {
@@ -119,7 +136,7 @@ function validateRelationClasses(config_json, refinement_context) {
 }
 
 /**
- * @param {PatramConfig} config_json
+ * @param {PatramGraphConfig} config_json
  * @param {RefinementCtx} refinement_context
  */
 function validateMappingClasses(config_json, refinement_context) {
@@ -147,7 +164,7 @@ function validateMappingClasses(config_json, refinement_context) {
 }
 
 /**
- * @param {PatramConfig} config_json
+ * @param {PatramGraphConfig} config_json
  * @param {RefinementCtx} refinement_context
  */
 function validateMappingRelations(config_json, refinement_context) {

package/lib/patram-config.types.ts

@@ -1,40 +1,22 @@
-export interface ClassDefinition {
-  builtin?: boolean;
-  label?: string;
-}
-
-export interface RelationDefinition {
-  builtin?: boolean;
-  from: string[];
-  to: string[];
-}
-
-export interface MappingNodeDefinition {
-  class: string;
-  field: string;
-  key?: 'path' | 'value';
-}
-
-export interface MappingEmitDefinition {
-  relation: string;
-  target: 'path' | 'value';
-  target_class: string;
-}
-
-export interface MappingDefinition {
-  emit?: MappingEmitDefinition;
-  node?: MappingNodeDefinition;
-}
-
-export interface PatramConfig {
-  $schema?: string;
-  classes: Record<string, ClassDefinition>;
-  class_schemas?: Record<string, ClassSchemaConfig>;
-  fields?: Record<string, MetadataFieldConfig>;
-  mappings: Record<string, MappingDefinition>;
-  relations: Record<string, RelationDefinition>;
-}
 import type {
   ClassSchemaConfig,
   MetadataFieldConfig,
 } from './load-patram-config.types.ts';
+
+export type ClassDefinition = import('./patram-config.js').ClassDefinition;
+export type RelationDefinition =
+  import('./patram-config.js').RelationDefinition;
+export type MappingNodeDefinition =
+  import('./patram-config.js').MappingNodeDefinition;
+export type MappingEmitDefinition =
+  import('./patram-config.js').MappingEmitDefinition;
+export type MappingDefinition = import('./patram-config.js').MappingDefinition;
+export type PatramGraphConfig = import('./patram-config.js').PatramGraphConfig;
+export type PatramClassConfig = ClassDefinition & {
+  schema?: ClassSchemaConfig;
+};
+
+export type PatramConfig = Omit<PatramGraphConfig, 'classes'> & {
+  classes: Record<string, PatramClassConfig>;
+  fields?: Record<string, MetadataFieldConfig>;
+};

package/lib/query-graph.js

@@ -4,7 +4,7 @@
  * @import { PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
  * @import {
  *   ParsedAggregateTerm,
- *   ParsedClause,
+ *   ParsedExpression,
  *   ParsedFieldSetTerm,
  *   ParsedFieldTerm,
  *   ParsedRelationTargetTerm,
@@ -82,7 +82,7 @@ export function queryGraph(
     const diagnostics = getQuerySemanticDiagnostics(
       repo_config,
       { kind: 'ad_hoc' },
-      parse_result.clauses,
+      parse_result.expression,
     );
 
     if (diagnostics.length > 0) {
@@ -100,7 +100,7 @@ export function queryGraph(
   };
   const graph_nodes = Object.values(graph.nodes).sort(compareGraphNodes);
   const matching_nodes = graph_nodes.filter((graph_node) =>
-    matchesClauses(graph_node, parse_result.clauses, evaluation_context),
+    matchesExpression(graph_node, parse_result.expression, evaluation_context),
   );
   const paginated_nodes = paginateNodes(
     matching_nodes,
@@ -116,26 +116,36 @@ export function queryGraph(
 
 /**
  * @param {GraphNode} graph_node
- * @param {ParsedClause[]} clauses
+ * @param {ParsedExpression} expression
  * @param {EvaluationContext} evaluation_context
  * @returns {boolean}
  */
-function matchesClauses(graph_node, clauses, evaluation_context) {
-  return clauses.every((clause) =>
-    matchesClause(graph_node, clause, evaluation_context),
-  );
-}
+function matchesExpression(graph_node, expression, evaluation_context) {
+  if (expression.kind === 'and') {
+    return expression.expressions.every((subexpression) =>
+      matchesExpression(graph_node, subexpression, evaluation_context),
+    );
+  }
 
-/**
- * @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);
+  if (expression.kind === 'or') {
+    return expression.expressions.some((subexpression) =>
+      matchesExpression(graph_node, subexpression, evaluation_context),
+    );
+  }
+
+  if (expression.kind === 'not') {
+    return !matchesExpression(
+      graph_node,
+      expression.expression,
+      evaluation_context,
+    );
+  }
+
+  if (expression.kind === 'term') {
+    return matchesTerm(graph_node, expression.term, evaluation_context);
+  }
 
-  return clause.is_negated ? !is_match : is_match;
+  throw new Error('Unsupported parsed boolean expression.');
 }
 
 /**
@@ -181,7 +191,7 @@ function matchesAggregateTerm(graph_node, term, evaluation_context) {
     evaluation_context,
   );
   const matching_count = related_nodes.filter((related_node) =>
-    matchesClauses(related_node, term.clauses, evaluation_context),
+    matchesExpression(related_node, term.expression, evaluation_context),
   ).length;
 
   if (term.aggregate_name === 'any') {

package/lib/query-inspection.js

@@ -1,10 +1,9 @@
-/** @import * as $k$$l$parse$j$where$j$clause$k$types$k$ts from './parse-where-clause.types.ts'; */
 /* eslint-disable max-lines */
 /**
  * @import { PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
  * @import { ResolvedOutputMode } from './output-view.types.ts';
  * @import {
- *   ParsedClause,
+ *   ParsedExpression,
  *   ParsedRelationTargetTerm,
  *   ParsedRelationTerm,
  *   ParsedTerm,
@@ -38,10 +37,10 @@ import { parseWhereClause } from './parse-where-clause.js';
  *     limit: number | null,
  *     offset: number,
  *   },
+ *   expression?: ParsedExpression,
  *   inspection_mode: 'explain' | 'lint',
  *   query_source: QuerySource,
  *   where_clause: string,
- *   clauses?: ParsedClause[],
  * }} QueryInspectionSuccess
  */
 
@@ -75,7 +74,7 @@ export function inspectQuery(
   const diagnostics = getQuerySemanticDiagnostics(
     repo_config,
     resolved_where_clause.query_source,
-    parse_result.clauses,
+    parse_result.expression,
   );
 
   if (diagnostics.length > 0) {
@@ -99,11 +98,11 @@ export function inspectQuery(
   return {
     success: true,
     value: {
-      clauses: parse_result.clauses,
       execution: {
         limit: inspection_options.limit,
         offset: inspection_options.offset,
       },
+      expression: parse_result.expression,
       inspection_mode: 'explain',
       query_source: resolved_where_clause.query_source,
       where_clause: resolved_where_clause.where_clause,
@@ -143,20 +142,26 @@ export function renderQueryInspection(query_inspection, output_mode) {
 }
 
 /**
+ * Collect schema-aware diagnostics for one parsed where clause.
+ *
  * @param {PatramRepoConfig} repo_config
  * @param {QuerySource} query_source
- * @param {ParsedClause[]} clauses
+ * @param {ParsedExpression} expression
  * @returns {PatramDiagnostic[]}
  */
-function collectSemanticDiagnostics(repo_config, query_source, clauses) {
+export function getQuerySemanticDiagnostics(
+  repo_config,
+  query_source,
+  expression,
+) {
   const known_relation_names = new Set(
     Object.keys(repo_config.relations ?? {}),
   );
   /** @type {PatramDiagnostic[]} */
   const diagnostics = [];
 
-  collectClauseDiagnostics(
-    clauses,
+  collectExpressionDiagnostics(
+    expression,
     diagnostics,
     known_relation_names,
     repo_config.fields ?? {},
@@ -167,44 +172,58 @@ function collectSemanticDiagnostics(repo_config, query_source, clauses) {
 }
 
 /**
- * Collect schema-aware diagnostics for one parsed where clause.
- *
- * @param {PatramRepoConfig} repo_config
- * @param {QuerySource} query_source
- * @param {ParsedClause[]} clauses
- * @returns {PatramDiagnostic[]}
- */
-export function getQuerySemanticDiagnostics(
-  repo_config,
-  query_source,
-  clauses,
-) {
-  return collectSemanticDiagnostics(repo_config, query_source, clauses);
-}
-
-/**
- * @param {ParsedClause[]} clauses
+ * @param {ParsedExpression} expression
  * @param {PatramDiagnostic[]} diagnostics
  * @param {Set<string>} known_relation_names
  * @param {Record<string, import('./load-patram-config.types.ts').MetadataFieldConfig>} known_field_definitions
  * @param {string} diagnostic_path
  */
-function collectClauseDiagnostics(
-  clauses,
+function collectExpressionDiagnostics(
+  expression,
   diagnostics,
   known_relation_names,
   known_field_definitions,
   diagnostic_path,
 ) {
-  for (const clause of clauses) {
+  if (expression.kind === 'and' || expression.kind === 'or') {
+    for (const subexpression of expression.expressions) {
+      collectExpressionDiagnostics(
+        subexpression,
+        diagnostics,
+        known_relation_names,
+        known_field_definitions,
+        diagnostic_path,
+      );
+    }
+
+    return;
+  }
+
+  if (expression.kind === 'not') {
+    collectExpressionDiagnostics(
+      expression.expression,
+      diagnostics,
+      known_relation_names,
+      known_field_definitions,
+      diagnostic_path,
+    );
+
+    return;
+  }
+
+  if (expression.kind === 'term') {
     collectTermDiagnostics(
-      clause.term,
+      expression.term,
       diagnostics,
       known_relation_names,
       known_field_definitions,
       diagnostic_path,
     );
+
+    return;
   }
+
+  throw new Error('Unsupported query inspection expression.');
 }
 
 /**
@@ -228,8 +247,8 @@ function collectTermDiagnostics(
       known_relation_names,
       diagnostic_path,
     );
-    collectClauseDiagnostics(
-      term.clauses,
+    collectExpressionDiagnostics(
+      term.expression,
       diagnostics,
       known_relation_names,
       known_field_definitions,
@@ -577,9 +596,9 @@ function formatJsonQueryInspection(query_inspection) {
   }
 
   return {
-    clauses: query_inspection.clauses,
     diagnostics: [],
     execution: query_inspection.execution,
+    expression: query_inspection.expression,
     mode: 'explain',
     source: query_inspection.query_source,
     where: query_inspection.where_clause,
@@ -625,9 +644,12 @@ function renderTextQueryInspection(query_inspection, render_options) {
         : String(query_inspection.execution?.limit ?? ''),
     ),
     '',
-    `${render_options.label('clauses:')}`,
-    ...formatExplainClauseBlock(
-      query_inspection.clauses ?? [],
+    `${render_options.label('expression:')}`,
+    ...formatExplainExpressionBlock(
+      query_inspection.expression ?? {
+        expressions: [],
+        kind: 'and',
+      },
       render_options,
       '',
     ),
@@ -637,42 +659,49 @@ function renderTextQueryInspection(query_inspection, render_options) {
 }
 
 /**
- * @param {ParsedClause[]} clauses
+ * @param {ParsedExpression} expression
  * @param {{ header: (value: string) => string, label: (value: string) => string }} render_options
  * @param {string} indentation
  * @returns {string[]}
  */
-function formatExplainClauseBlock(clauses, render_options, indentation) {
-  /** @type {string[]} */
-  const output_lines = [];
+function formatExplainExpressionBlock(expression, render_options, indentation) {
+  if (expression.kind === 'and') {
+    return formatExplainExpressionItems(
+      expression.expressions,
+      render_options,
+      indentation,
+    );
+  }
 
-  clauses.forEach((clause, clause_index) => {
-    const clause_number = clause_index + 1;
-    const clause_text = formatClauseSummary(clause);
+  return formatExplainExpressionItems(
+    [expression],
+    render_options,
+    indentation,
+  );
+}
 
-    output_lines.push(`${indentation}${clause_number}. ${clause_text}`);
+/**
+ * @param {ParsedExpression[]} expressions
+ * @param {{ header: (value: string) => string, label: (value: string) => string }} render_options
+ * @param {string} indentation
+ * @returns {string[]}
+ */
+function formatExplainExpressionItems(
+  expressions,
+  render_options,
+  indentation,
+) {
+  /** @type {string[]} */
+  const output_lines = [];
 
-    if (clause.term.kind !== 'aggregate') {
-      return;
-    }
+  expressions.forEach((expression, expression_index) => {
+    const expression_number = expression_index + 1;
 
     output_lines.push(
-      `${indentation}   ${render_options.label('traversal:')} ${formatTraversal(clause.term.traversal)}`,
+      `${indentation}${expression_number}. ${formatExpressionSummary(expression)}`,
     );
-
-    if (clause.term.aggregate_name === 'count') {
-      output_lines.push(
-        `${indentation}   ${render_options.label('comparison:')} ${clause.term.comparison} ${clause.term.value}`,
-      );
-    }
-
     output_lines.push(
-      `${indentation}   ${render_options.label('nested clauses:')}`,
-      ...formatExplainClauseBlock(
-        clause.term.clauses,
-        render_options,
-        `${indentation}     `,
-      ),
+      ...formatExpressionDetailLines(expression, render_options, indentation),
     );
   });
 
@@ -680,17 +709,89 @@ function formatExplainClauseBlock(clauses, render_options, indentation) {
 }
 
 /**
- * @param {ParsedClause} clause
+ * @param {ParsedExpression} expression
  * @returns {string}
  */
-function formatClauseSummary(clause) {
-  const clause_prefix = clause.is_negated ? 'not ' : '';
+function formatExpressionSummary(expression) {
+  if (expression.kind === 'and') {
+    return 'all of';
+  }
 
-  if (clause.term.kind === 'aggregate') {
-    return `${clause_prefix}aggregate ${clause.term.aggregate_name}`;
+  if (expression.kind === 'or') {
+    return 'any of';
   }
 
-  return `${clause_prefix}${formatTermSummary(clause.term)}`;
+  if (expression.kind === 'not') {
+    if (expression.expression.kind === 'term') {
+      return `not ${formatTermSummary(expression.expression.term)}`;
+    }
+
+    return 'not';
+  }
+
+  if (expression.kind === 'term') {
+    return formatTermSummary(expression.term);
+  }
+
+  throw new Error('Unsupported explain expression.');
+}
+
+/**
+ * @param {ParsedExpression} expression
+ * @param {{ header: (value: string) => string, label: (value: string) => string }} render_options
+ * @param {string} indentation
+ * @returns {string[]}
+ */
+function formatExpressionDetailLines(expression, render_options, indentation) {
+  if (expression.kind === 'and' || expression.kind === 'or') {
+    return formatExplainExpressionItems(
+      expression.expressions,
+      render_options,
+      `${indentation}   `,
+    );
+  }
+
+  if (expression.kind === 'not') {
+    if (expression.expression.kind === 'term') {
+      return [];
+    }
+
+    return formatExplainExpressionBlock(
+      expression.expression,
+      render_options,
+      `${indentation}   `,
+    );
+  }
+
+  if (expression.kind !== 'term') {
+    throw new Error('Unsupported explain expression details.');
+  }
+
+  if (expression.term.kind !== 'aggregate') {
+    return [];
+  }
+
+  /** @type {string[]} */
+  const output_lines = [
+    `${indentation}   ${render_options.label('traversal:')} ${formatTraversal(expression.term.traversal)}`,
+  ];
+
+  if (expression.term.aggregate_name === 'count') {
+    output_lines.push(
+      `${indentation}   ${render_options.label('comparison:')} ${expression.term.comparison} ${expression.term.value}`,
+    );
+  }
+
+  output_lines.push(
+    `${indentation}   ${render_options.label('nested expression:')}`,
+    ...formatExplainExpressionBlock(
+      expression.term.expression,
+      render_options,
+      `${indentation}     `,
+    ),
+  );
+
+  return output_lines;
 }
 
 /**
@@ -698,6 +799,10 @@ function formatClauseSummary(clause) {
  * @returns {string}
  */
 function formatTermSummary(term) {
+  if (term.kind === 'aggregate') {
+    return `aggregate ${term.aggregate_name}`;
+  }
+
   if (term.kind === 'field') {
     return `${term.field_name} ${term.operator} ${term.value}`;
   }
@@ -714,7 +819,7 @@ function formatTermSummary(term) {
     return `${term.relation_name} = ${term.target_id}`;
   }
 
-  throw new Error('Expected a non-aggregate query term.');
+  throw new Error('Expected a parsed query term.');
 }
 
 /**