@dxos/assistant 0.8.2-staging.7ac8446 → 0.8.2

package/src/cypher/combinators.test.ts

@@ -1,137 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-/* eslint-disable unused-imports/no-unused-vars */
-/* eslint-disable @typescript-eslint/consistent-type-imports */
-
-import { createRequire } from 'node:module';
-import { type Parjser } from 'parjs';
-import { describe, test } from 'vitest';
-
-import { log } from '@dxos/log';
-
-import {
-  cypherQuery,
-  identifier,
-  matchClause,
-  nodePattern,
-  properties,
-  returnClause,
-  whereClause,
-} from './combinators';
-
-describe('Cypher Combinators', () => {
-  // TODO(dmaretskyi): Must be like this or it breaks vitest.
-  const require = createRequire(import.meta.url);
-  const { string, regexp, whitespace } = require('parjs') as typeof import('parjs');
-  const { between, many, manySepBy, or, map, then, recover } =
-    require('parjs/combinators') as typeof import('parjs/combinators');
-
-  test('string', ({ expect }) => {
-    expect(string('hello').parse('hello')).toMatchObject({ isOk: true });
-  });
-
-  test('string with whitespace', ({ expect }) => {
-    const ws = whitespace(); // Parses whitespace
-    // many;
-    // const optionalWs = many(100)(ws);
-
-    expect(string('hello').parse('hello')).toMatchObject({ isOk: true });
-  });
-
-  test('optional vairable tag', ({ expect }) => {
-    const node = identifier.pipe(
-      then(':'),
-      recover(() => ({ kind: 'Soft' })),
-      or(''),
-      then(identifier),
-      between('(', ')'),
-    );
-    const relation = identifier.pipe(
-      then(':'),
-      recover(() => ({ kind: 'Soft' })),
-      or(''),
-      then(identifier),
-      between('[', ']'),
-    );
-    const parser = or(node)(relation);
-    const input = '[a:b]';
-    const result = parser.parse(input);
-    log('result', { result });
-  });
-
-  test('properties', ({ expect }) => {
-    const input = "{name: 'John'}";
-    const result = properties.parse(input);
-    log('result', { result });
-    expect(result).toMatchObject({ isOk: true });
-  });
-
-  test('node pattern', ({ expect }) => {
-    testParser(nodePattern, '(:Person)');
-    testParser(nodePattern, '(n:Person)');
-    testParser(nodePattern, "(n:Person {name: 'John'})");
-  });
-
-  test('match clause', ({ expect }) => {
-    testParser(matchClause, 'MATCH (n:Person)');
-    testParser(matchClause, 'MATCH (n:Person)-[r:KNOWS]->(m:Person)');
-    testParser(matchClause, 'MATCH (o:Org)-[:HAS_EMPLOYEE]->(e:Employee)');
-  });
-
-  test('where clause', ({ expect }) => {
-    testParser(whereClause, 'WHERE n.name = "John"');
-    testParser(whereClause, 'WHERE o.name = "DXOS" AND p.name = "Composer"');
-  });
-
-  test('return clause', ({ expect }) => {
-    testParser(returnClause, 'RETURN n, m');
-    testParser(returnClause, 'RETURN m.name AS employee');
-
-    const cases = ['RETURN n, m'];
-    for (const input of cases) {
-      const result = returnClause.parse(input);
-      log('result', { result });
-      expect(result).toMatchObject({ isOk: true });
-    }
-  });
-
-  test('query', async ({ expect }) => {
-    testParser(cypherQuery, 'MATCH (n:Person) RETURN n');
-    testParser(
-      cypherQuery,
-      `
-      MATCH (n:Person {name: 'John'})-[r:KNOWS]->(m:Person)
-      RETURN n, m
-    `,
-    );
-    testParser(
-      cypherQuery,
-      `
-      MATCH (n:Person)-[r:KNOWS]->(m:Person)
-      WHERE n.name = "John"
-      RETURN n, m
-    `,
-    );
-    testParser(
-      cypherQuery,
-      'MATCH (o:Org)-[:HAS_EMPLOYEE]->(e:Employee)-[:WORKS_ON]->(p:Project) WHERE o.name = "DXOS" AND p.name = "Composer" RETURN e.name, e.id, p.name, p.id',
-    );
-    testParser(
-      cypherQuery,
-      'MATCH (n:Org {name: "DXOS"})-[:HAS_EMPLOYEE]->(m:Employee)<-[:WORKS_ON]-(p:Project {name: "Composer"}) RETURN m.name AS employee',
-    );
-    testParser(
-      cypherQuery,
-      "MATCH (org:Org {name: 'DXOS'})-[:ORG_EMPLOYEES]->(c:Contact)<-[:TASK_ASSIGNEE]-(t:Task)-[:TASK_PROJECT]->(p:Project {name: 'Composer'}) RETURN c.name",
-    );
-  });
-});
-
-const testParser = (parser: Parjser<any>, input: string) => {
-  const result = parser.parse(input);
-  if (!result.isOk) {
-    throw new Error(`Failed to parse: ${result}`);
-  }
-};

package/src/cypher/combinators.ts

@@ -1,148 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-/* eslint-disable unused-imports/no-unused-vars */
-/* eslint-disable @typescript-eslint/consistent-type-imports */
-
-import type {
-  CypherQuery,
-  EqualsPredicate,
-  GraphPattern,
-  GraphPatternConnector,
-  Identifier,
-  MatchClause,
-  MemberExpression,
-  NodePattern,
-  Properties,
-  Property,
-  RelationshipPattern,
-  ReturnClause,
-  StringLiteral,
-  WhereClause,
-} from './ast';
-import { Parjser, parjs, parjsCombinators } from './parjs';
-
-// Helper parsers
-const ws = parjs.whitespace(); // Parses whitespace
-
-const nothing = parjs.string('').pipe(parjsCombinators.map(() => null)); // Parses nothing
-
-const optional = <T>(parser: Parjser<T>) =>
-  parser.pipe(
-    parjsCombinators.recover(() => ({ kind: 'Soft' })),
-    parjsCombinators.or(nothing),
-  ); // Makes a parser optional
-
-const keyword = (word: string) => parjs.string(word).pipe(parjsCombinators.map(() => word)); // Parses specific keywords
-
-// Identifiers (node labels, relationship types, variables, etc.)
-export const identifier = parjs.regexp(/[a-zA-Z_][a-zA-Z0-9_]*/).pipe(
-  parjsCombinators.map((match): Identifier => ({ astKind: 'Identifier', name: match[0] })), // Extract the matched string
-);
-
-// Literals (numbers and strings)
-const numberLiteral = parjs.regexp(/-?\d+(\.\d+)?/).pipe(parjsCombinators.map(Number)); // Numbers
-const stringLiteral = parjs.regexp(/"([^"]*)"|'([^']*)'/).pipe(
-  parjsCombinators.map((match): StringLiteral => ({ astKind: 'StringLiteral', value: match[1] || match[2] })), // Extract content without quotes
-);
-
-// Node pattern (e.g., "(n:Person {name: 'John'})"
-const variableTag = identifier.pipe(parjsCombinators.map((variable) => variable)).expects('variable tag');
-export const label = identifier.pipe(parjsCombinators.map((name) => name));
-export const property = identifier.pipe(
-  parjsCombinators.then(parjs.string(':'), ws, stringLiteral),
-  parjsCombinators.map(([key, , , value]): Property => ({ key, value })),
-);
-export const properties = property.pipe(
-  parjsCombinators.manySepBy(','),
-  parjsCombinators.between('{', '}'),
-  parjsCombinators.map((properties): Properties => ({ astKind: 'Properties', properties })),
-);
-export const nodePattern = optional(variableTag).pipe(
-  parjsCombinators.then(':'),
-  parjsCombinators.then(ws, label, ws),
-  parjsCombinators.then(optional(properties)),
-  parjsCombinators.between('(', ')'),
-  parjsCombinators.map(
-    ([[[variable], _, label], properties]): NodePattern => ({ astKind: 'NodePattern', variable, label, properties }),
-  ),
-);
-
-export const relationshipPattern = optional(variableTag).pipe(
-  parjsCombinators.then(':'),
-  parjsCombinators.then(ws, label, ws),
-  parjsCombinators.then(optional(properties)),
-  parjsCombinators.between('[', ']'),
-  parjsCombinators.map(
-    ([[[variable], _, label], properties]): RelationshipPattern => ({
-      astKind: 'RelationshipPattern',
-      variable,
-      label,
-      properties,
-    }),
-  ),
-);
-
-const graphPatternConnector = parjs.string('->').pipe(
-  parjsCombinators.or('<-' as const, '-' as const),
-  parjsCombinators.map((x): GraphPatternConnector => ({ astKind: 'GraphPatternConnector', direction: x })),
-);
-
-export const graphPattern = nodePattern.pipe(
-  parjsCombinators.or(relationshipPattern),
-  parjsCombinators.manySepBy(graphPatternConnector),
-  parjsCombinators.map((segments): GraphPattern => ({ astKind: 'GraphPattern', segments })),
-);
-
-export const matchClause = keyword('MATCH').pipe(
-  parjsCombinators.then(ws),
-  parjsCombinators.then(graphPattern),
-  parjsCombinators.map(([, pattern]): MatchClause => ({ astKind: 'MatchClause', pattern })),
-);
-
-const memberExpression = identifier.pipe(
-  parjsCombinators.manySepBy('.'),
-  parjsCombinators.map((path): MemberExpression => ({ astKind: 'MemberExpression', path })),
-);
-
-const equalsPredicate = memberExpression.pipe(
-  parjsCombinators.then(ws, parjs.string('='), ws, stringLiteral),
-  parjsCombinators.map(([left, , , , right]): EqualsPredicate => ({ astKind: 'EqualsPredicate', left, right })),
-);
-
-export const whereClause = keyword('WHERE').pipe(
-  parjsCombinators.then(
-    ws,
-    equalsPredicate.pipe(parjsCombinators.between(ws, ws), parjsCombinators.manySepBy(parjs.string('AND'))),
-    ws,
-  ),
-  parjsCombinators.map(([, , predicates]): WhereClause => ({ astKind: 'WhereClause', predicates })),
-);
-
-export const returnClause = keyword('RETURN').pipe(
-  parjsCombinators.then(
-    ws,
-    memberExpression.pipe(
-      parjsCombinators.then(
-        optional(parjs.string('AS').pipe(parjsCombinators.between(ws), parjsCombinators.then(identifier))),
-        ws,
-      ),
-      parjsCombinators.manySepBy(parjs.string(',').pipe(parjsCombinators.then(ws))),
-    ),
-    ws,
-  ),
-  parjsCombinators.map(([, , fields]): ReturnClause => ({ astKind: 'ReturnClause', fields: fields.map(([f]) => f) })),
-);
-
-export const cypherQuery = ws.pipe(
-  parjsCombinators.then(matchClause, ws, optional(whereClause), ws, returnClause, ws),
-  parjsCombinators.map(
-    ([, matchClause, , whereClause, , returnClause]): CypherQuery => ({
-      astKind: 'CypherQuery',
-      matchClause,
-      whereClause,
-      returnClause,
-    }),
-  ),
-);

package/src/cypher/echo-data-source.ts

@@ -1,105 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { raise } from '@dxos/debug';
-import { type EchoDatabase, Filter, type ReactiveEchoObject } from '@dxos/echo-db';
-import { type S, getSchemaTypename, StoredSchema, toJsonSchema } from '@dxos/echo-schema';
-import { getSchema } from '@dxos/live-object';
-import { log } from '@dxos/log';
-
-import type { DataSource, Node, Relationship } from './query-executor';
-import { formatInferredRelationshipLabel, formatNodeLabel, isReference } from './schema';
-
-export class EchoDataSource implements DataSource {
-  constructor(private readonly _db: EchoDatabase) {}
-
-  @log.method()
-  async getNodes({ label }: { label?: string }): Promise<Node[]> {
-    if (!label) {
-      const { objects } = await this._db.query().run();
-      return objects.map(this._objectToNode);
-    }
-
-    const schema = (await this._getAllSchema()).find((s) => getSchemaTypename(s)?.endsWith(label));
-
-    if (!schema) {
-      return [];
-    }
-
-    const { objects } = await this._db.query(Filter.schema(schema)).run();
-    return objects.map(this._objectToNode);
-  }
-
-  @log.method()
-  async getRelationships({ label }: { label?: string }): Promise<Relationship[]> {
-    const syntheticRefRelationships = (await this._getAllSchema())
-      .filter((schema) => getSchemaTypename(schema) !== StoredSchema.typename)
-      .flatMap((schema) => {
-        const jsonSchema = toJsonSchema(schema);
-        const relationships = Object.entries(jsonSchema.properties!).filter(([key, prop]) => isReference(prop));
-
-        return relationships.map(([key, value]) => {
-          const relationshipLabel = formatInferredRelationshipLabel(
-            jsonSchema.typename ?? raise(new Error('Schema must have typename')),
-            key,
-          );
-
-          return {
-            label: relationshipLabel,
-            schema,
-            property: key,
-          };
-        });
-      });
-    const relationship = syntheticRefRelationships.find((r) => r.label === label);
-    if (!relationship) {
-      return []; // TODO(dmaretskyi): Handle real relationships.
-    }
-
-    const { objects } = await this._db.query(Filter.schema(relationship.schema)).run();
-    return (
-      await Promise.all(objects.map((object) => this._projectRefRelationship(object, relationship.property)))
-    ).flat();
-  }
-
-  private async _getAllSchema(): Promise<S.Schema.AnyNoContext[]> {
-    return [
-      ...(await this._db.schemaRegistry.query().run()),
-      // TODO(dmaretskyi): Remove once we can serialize recursive schema.
-      ...this._db.graph.schemaRegistry.schemas.filter((s) => getSchemaTypename(s)?.startsWith('example.org')),
-    ].filter((schema) => getSchemaTypename(schema) !== StoredSchema.typename);
-  }
-
-  private _objectToNode(object: ReactiveEchoObject<any>): Node {
-    const { id, ...properties } = object;
-    return {
-      id,
-      kind: 'node',
-      label: formatNodeLabel(getSchemaTypename(getSchema(object)!)!),
-      properties,
-    };
-  }
-
-  private async _projectRefRelationship(object: ReactiveEchoObject<any>, prop: string): Promise<Relationship[]> {
-    if (!object[prop]) {
-      return [];
-    }
-
-    const value = Array.isArray(object[prop]) ? object[prop] : [object[prop]];
-
-    return Promise.all(
-      value.map(async (ref): Promise<Relationship> => {
-        const target = await ref.load();
-        return {
-          id: `${object.id}-${prop}-${target.id}`,
-          kind: 'relationship',
-          label: formatInferredRelationshipLabel(getSchemaTypename(getSchema(object)!)!, prop),
-          properties: {},
-          source: this._objectToNode(object),
-          target: this._objectToNode(target),
-        };
-      }),
-    );
-  }
-}

package/src/cypher/execution-plan.test.ts

@@ -1,44 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { describe, test } from 'vitest';
-
-import { log } from '@dxos/log';
-
-import { createExecutionPlan } from './execution-plan';
-import { parseCypherQuery } from './parser';
-
-// log.config({ filter: 'debug' });
-
-describe('Execution Plan', () => {
-  test('trivial', ({ expect }) => {
-    const plan = createExecutionPlan(parseCypherQuery('MATCH (n:Person) RETURN n'));
-    log('', { plan });
-    expect(plan.steps.map((step) => step.type)).toEqual(['NodeScan', 'ProduceResults']);
-  });
-
-  test('complex query', ({ expect }) => {
-    const plan = createExecutionPlan(
-      parseCypherQuery(
-        "MATCH (org:Org {name: 'DXOS'})-[:ORG_EMPLOYEES]->(c:Contact)<-[:TASK_ASSIGNEE]-(:Task)-[:TASK_PROJECT]->(p:Project {name: 'Composer'}) RETURN c.name",
-      ),
-    );
-    log('', { plan });
-    for (const step of plan.steps) {
-      log('step', { step });
-    }
-    expect(plan.steps.map((step) => step.type)).toEqual([
-      'NodeScan',
-      'FilterByProperty',
-      'RelationshipScan',
-      'FilterByLabel',
-      'RelationshipScan',
-      'FilterByLabel',
-      'RelationshipScan',
-      'FilterByLabel',
-      'FilterByProperty',
-      'ProduceResults',
-    ]);
-  });
-});

package/src/cypher/execution-plan.ts

@@ -1,208 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import type { JsonPath } from '@dxos/echo-schema';
-import { invariant } from '@dxos/invariant';
-import { log } from '@dxos/log';
-
-import type { GraphPatternConnector, MatchClause, ReturnClause, WhereClause } from './ast';
-import type { ParsedQuery } from './parser';
-
-export type VariableName = string & { __VariableName: never };
-
-export type ExecutionPlanStep =
-  | {
-      type: 'NodeScan';
-      label: string;
-      into: VariableName;
-    }
-  | {
-      type: 'FilterByLabel';
-      variable: VariableName;
-      label: string;
-    }
-  | {
-      type: 'FilterByProperty';
-      variable: VariableName;
-      property: JsonPath;
-      value: unknown;
-    }
-  | {
-      /**
-       * Scans (anchor)-[relationshipInto:label]->(nodeInto).
-       */
-      type: 'RelationshipScan';
-      label: string;
-      anchor: VariableName;
-      relationshipInto: VariableName;
-      nodeInto: VariableName;
-
-      /**
-       * `in`: (anchor)<-[relationshipInto:label]-(nodeInto)
-       * `out`: (anchor)-[relationshipInto:label]->(nodeInto)
-       * `both`: (anchor)-[relationshipInto:label]-(nodeInto)
-       */
-      direction: 'in' | 'out' | 'both';
-    }
-  | {
-      type: 'ProduceResults';
-      fields: {
-        name: string;
-        variable: VariableName;
-        path: JsonPath;
-      }[];
-    };
-
-export type ExecutionPlan = {
-  steps: ExecutionPlanStep[];
-  output: {
-    fields: string[];
-  };
-};
-
-export const createExecutionPlan = (query: ParsedQuery): ExecutionPlan => {
-  return new ExecutionPlanBuilder().build(query);
-};
-
-class ExecutionPlanBuilder {
-  private counter = 0;
-
-  newVariable(): VariableName {
-    return `anon_${this.counter++}` as VariableName;
-  }
-
-  build(query: ParsedQuery): ExecutionPlan {
-    log('Creating execution plan for query', { query });
-    return {
-      steps: [
-        ...this.createStepsForMatchClause(query.ast.matchClause),
-        ...(query.ast.whereClause ? this.createStepsForWhereClause(query.ast.whereClause) : []),
-        ...this.createStepsForReturnClause(query.ast.returnClause),
-      ],
-      output: {
-        fields: this.getOutputFields(query.ast.returnClause),
-      },
-    };
-  }
-
-  createStepsForMatchClause(match: MatchClause): ExecutionPlanStep[] {
-    invariant(match.pattern.segments.length > 0);
-    const firstSegment = match.pattern.segments[0];
-    invariant(firstSegment.astKind === 'NodePattern');
-    let lastNodeVariable = (firstSegment.variable?.name as VariableName) ?? this.newVariable();
-
-    const steps: ExecutionPlanStep[] = [];
-    steps.push({
-      type: 'NodeScan',
-      label: firstSegment.label.name,
-      into: lastNodeVariable,
-    });
-
-    if (firstSegment.properties) {
-      for (const property of firstSegment.properties.properties) {
-        steps.push({
-          type: 'FilterByProperty',
-          variable: lastNodeVariable,
-          property: property.key.name as JsonPath,
-          value: property.value.value,
-        });
-      }
-    }
-
-    for (let i = 1; i < match.pattern.segments.length; i++) {
-      const relationshipSegment = match.pattern.segments[i++];
-      invariant(relationshipSegment.astKind === 'RelationshipPattern');
-      const nodeSegment = match.pattern.segments[i];
-      invariant(nodeSegment.astKind === 'NodePattern');
-      const leftSeparator = match.pattern.segments.separators[i - 2];
-      const rightSeparator = match.pattern.segments.separators[i - 1];
-      const direction = getDirection(leftSeparator.direction, rightSeparator.direction);
-
-      const relationshipVariable = (relationshipSegment.variable?.name as VariableName) ?? this.newVariable();
-      const nodeVariable = (nodeSegment.variable?.name as VariableName) ?? this.newVariable();
-
-      steps.push({
-        type: 'RelationshipScan',
-        label: relationshipSegment.label.name,
-        direction,
-        anchor: lastNodeVariable,
-        relationshipInto: relationshipVariable,
-        nodeInto: nodeVariable,
-      });
-
-      if (relationshipSegment.properties) {
-        for (const property of relationshipSegment.properties.properties) {
-          steps.push({
-            type: 'FilterByProperty',
-            variable: relationshipVariable,
-            property: property.key.name as JsonPath,
-            value: property.value.value,
-          });
-        }
-      }
-      if (nodeSegment.label) {
-        steps.push({
-          type: 'FilterByLabel',
-          variable: nodeVariable,
-          label: nodeSegment.label.name,
-        });
-      }
-      if (nodeSegment.properties) {
-        for (const property of nodeSegment.properties.properties) {
-          steps.push({
-            type: 'FilterByProperty',
-            variable: nodeVariable,
-            property: property.key.name as JsonPath,
-            value: property.value.value,
-          });
-        }
-      }
-
-      lastNodeVariable = nodeVariable;
-    }
-
-    return steps;
-  }
-
-  createStepsForWhereClause(where: WhereClause): ExecutionPlanStep[] {
-    return [];
-  }
-
-  createStepsForReturnClause(returnClause: ReturnClause): ExecutionPlanStep[] {
-    return [
-      {
-        type: 'ProduceResults',
-        fields: returnClause.fields.map((field) => ({
-          name: field.path.map((p) => p.name).join('_'),
-          variable: field.path[0].name as VariableName,
-          path:
-            field.path.length > 1
-              ? (field.path
-                  .slice(1)
-                  .map((p) => p.name)
-                  .join('.') as JsonPath)
-              : ('$' as JsonPath),
-        })),
-      },
-    ];
-  }
-
-  getOutputFields(returnClause: ReturnClause): string[] {
-    return returnClause.fields.map((field) => field.path.map((p) => p.name).join('_'));
-  }
-}
-
-const getDirection = (
-  left: GraphPatternConnector['direction'],
-  right: GraphPatternConnector['direction'],
-): 'in' | 'out' | 'both' => {
-  if (left === '-' && right === '->') {
-    return 'out';
-  } else if (left === '<-' && right === '-') {
-    return 'in';
-  } else if (left === '-' && right === '-') {
-    return 'both';
-  }
-  throw new Error(`Invalid direction: ()${left}[]${right}()`);
-};

package/src/cypher/index.ts

@@ -1,8 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-export * from './parser';
-export * from './query-executor';
-export * from './schema';
-export * from './echo-data-source';

package/src/cypher/parjs-shims.d.ts

@@ -1,10 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-declare module '#parjs' {
-  import * as parjs from 'parjs';
-  import * as parjsCombinators from 'parjs/combinators';
-
-  export { parjsCombinators, parjs };
-}

package/src/cypher/parjs.ts

@@ -1,10 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-// Workaround for https://github.com/vitest-dev/vitest/issues/7174.
-import type { Parjser } from 'parjs';
-
-import { parjsCombinators, parjs } from '#parjs';
-
-export { type Parjser, parjsCombinators, parjs };

package/src/cypher/parser.ts

@@ -1,19 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import type { CypherQuery } from './ast';
-import { cypherQuery } from './combinators';
-
-export type ParsedQuery = {
-  ast: CypherQuery;
-};
-
-export const parseCypherQuery = (query: string): ParsedQuery => {
-  const parseResult = cypherQuery.parse(query);
-  if (parseResult.isOk) {
-    return { ast: parseResult.value };
-  } else {
-    throw new Error(`Failed to parse query: ${parseResult}`);
-  }
-};