@dxos/echo-query 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/parser/query.grammar

@@ -0,0 +1,130 @@
+//
+// lezer Query grammar
+//
+
+@top Query { expression }
+
+expression {
+  Assignment |
+  Filter |
+  !Not Not expression |
+  expression !ImplicitAnd expression |
+  expression !And And expression |
+  expression !Or Or expression |
+  expression !Relation Relation expression |
+  "(" expression ")"
+}
+
+Assignment {
+  Identifier "=" "(" expression ")"
+}
+
+Not { 
+  @specialize<Identifier, "NOT" | "not" | "!">
+}
+And { 
+  @specialize<Identifier, "AND" | "and">
+}
+Or { 
+  @specialize<Identifier, "OR" | "or">
+}
+
+Relation {
+  ArrowRight | ArrowLeft
+}
+
+//
+// Filters
+//
+
+Filter {
+  TagFilter |
+  TextFilter |
+  TypeFilter |
+  PropertyFilter |
+  ObjectLiteral
+}
+
+TagFilter {
+  Tag
+}
+
+TextFilter {
+  String
+}
+
+TypeFilter {
+  @specialize[@name=TypeKeyword]<Identifier, "type"> ":" Identifier
+}
+
+PropertyFilter {
+  PropertyPath ":" Value
+}
+
+PropertyPath {
+  Identifier ("." Identifier)*
+}
+
+ObjectLiteral {
+  "{" (ObjectProperty ("," ObjectProperty)*)? "}"
+}
+
+ObjectProperty {
+  Identifier ":" Value
+}
+
+ArrayLiteral {
+  "[" (Value ("," Value)*)? "]"
+}
+
+Value {
+  String |
+  Number |
+  Boolean |
+  Null |
+  ObjectLiteral |
+  ArrayLiteral
+}
+
+@tokens {
+  // Supports variables and DXNs
+  Identifier { 
+    $[a-zA-Z_]$[a-zA-Z0-9_./\-]* 
+  }
+
+  Tag {
+    "#" $[a-zA-Z0-9_\-]+
+  }
+
+  String { 
+    '"' (!["\\] | "\\" _)* '"' |
+    "'" (!['\\] | "\\" _)* "'"
+  }
+
+  Number { 
+    "-"? @digit+ ("." @digit+)? (("e" | "E") ("+" | "-")? @digit+)?
+  }
+
+  Boolean { "true" | "false" }
+
+  Null { "null" }
+
+  ArrowRight { "->" }
+  ArrowLeft { "<-" }
+
+  space { @whitespace+ }
+
+  "{" "}" "[" "]" "(" ")"
+  ":" ","  "." "="
+}
+
+@skip { space }
+
+@precedence {
+  Not @right,
+  ImplicitAnd @left,
+  And @left,
+  Or @left,
+  Relation @left,
+  Assignment @right
+}

package/src/parser/query.test.ts

@@ -0,0 +1,536 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Tree } from '@lezer/common';
+import { describe, it, test } from 'vitest';
+
+import { Filter, Tag } from '@dxos/echo';
+import { DXN } from '@dxos/keys';
+
+import { QueryDSL } from './gen';
+import { type BuildResult, QueryBuilder, normalizeInput } from './query-builder';
+
+// TODO(burdon): Ref/Relation traversal.
+
+describe('query', () => {
+  it('parse', ({ expect }) => {
+    const queryParser = QueryDSL.Parser.configure({ strict: true });
+
+    type Test = { input: string; expected: string[] };
+    const tests: Test[] = [
+      // Tags
+      {
+        input: '#foo',
+        expected: ['Query', 'Filter', 'TagFilter', 'Tag'],
+      },
+      {
+        input: '#foo AND #bar',
+        expected: ['Query', 'Filter', 'TagFilter', 'Tag', 'And', 'Filter', 'TagFilter', 'Tag'],
+      },
+      {
+        input: '#foo #bar',
+        expected: ['Query', 'Filter', 'TagFilter', 'Tag', 'Filter', 'TagFilter', 'Tag'],
+      },
+      // Text
+      {
+        input: '"foo"',
+        expected: ['Query', 'Filter', 'TextFilter', 'String'],
+      },
+      {
+        input: '"foo" OR "bar"',
+        expected: ['Query', 'Filter', 'TextFilter', 'String', 'Or', 'Filter', 'TextFilter', 'String'],
+      },
+      // Mixed
+      {
+        input: '#foo AND "bar"',
+        expected: ['Query', 'Filter', 'TagFilter', 'Tag', 'And', 'Filter', 'TextFilter', 'String'],
+      },
+      {
+        input: '#foo "bar"',
+        expected: ['Query', 'Filter', 'TagFilter', 'Tag', 'Filter', 'TextFilter', 'String'],
+      },
+      // Type
+      {
+        input: 'type:org.dxos.type.person',
+        expected: [
+          'Query',
+          // type:org.dxos.type.person
+          'Filter',
+          'TypeFilter',
+          'TypeKeyword',
+          ':',
+          'Identifier',
+        ],
+      },
+      {
+        input: '{ name: "DXOS" }',
+        expected: [
+          'Query',
+          // { name: "DXOS" }
+          'Filter',
+          'ObjectLiteral',
+          '{',
+          'ObjectProperty',
+          'Identifier',
+          ':',
+          'Value',
+          'String',
+          '}',
+        ],
+      },
+      {
+        input: '{ value: 100 }',
+        expected: [
+          'Query',
+          // { value: 100 }
+          'Filter',
+          'ObjectLiteral',
+          '{',
+          'ObjectProperty',
+          'Identifier',
+          ':',
+          'Value',
+          'Number',
+          '}',
+        ],
+      },
+      {
+        input: '{ value: true }',
+        expected: [
+          'Query',
+          // { value: true }
+          'Filter',
+          'ObjectLiteral',
+          '{',
+          'ObjectProperty',
+          'Identifier',
+          ':',
+          'Value',
+          'Boolean',
+          '}',
+        ],
+      },
+      {
+        input: 'type:org.dxos.type.person OR type:org.dxos.type.organization',
+        expected: [
+          'Query',
+          // type:org.dxos.type.person
+          'Filter',
+          'TypeFilter',
+          'TypeKeyword',
+          ':',
+          'Identifier',
+          // OR
+          'Or',
+          // type:org.dxos.type.organization
+          'Filter',
+          'TypeFilter',
+          'TypeKeyword',
+          ':',
+          'Identifier',
+        ],
+      },
+      {
+        input: '(type:org.dxos.type.person OR type:org.dxos.type.organization) AND { name: "DXOS" }',
+        expected: [
+          'Query',
+          '(',
+          // type:org.dxos.type.person
+          'Filter',
+          'TypeFilter',
+          'TypeKeyword',
+          ':',
+          'Identifier',
+          // OR
+          'Or',
+          // type:org.dxos.type.organization
+          'Filter',
+          'TypeFilter',
+          'TypeKeyword',
+          ':',
+          'Identifier',
+          ')',
+          'And',
+          // { name: "DXOS" }
+          'Filter',
+          'ObjectLiteral',
+          '{',
+          'ObjectProperty',
+          'Identifier',
+          ':',
+          'Value',
+          'String',
+          '}',
+        ],
+      },
+      {
+        input: 'type:org.dxos.type.person -> type:org.dxos.type.organization',
+        expected: [
+          'Query',
+          // type:org.dxos.type.person
+          'Filter',
+          'TypeFilter',
+          'TypeKeyword',
+          ':',
+          'Identifier',
+          'Relation',
+          'ArrowRight',
+          // type:org.dxos.type.organization
+          'Filter',
+          'TypeFilter',
+          'TypeKeyword',
+          ':',
+          'Identifier',
+        ],
+      },
+      {
+        input: 'type:org.dxos.type.organization <- type:org.dxos.type.person',
+        expected: [
+          'Query',
+          // type:org.dxos.type.organization
+          'Filter',
+          'TypeFilter',
+          'TypeKeyword',
+          ':',
+          'Identifier',
+          'Relation',
+          'ArrowLeft',
+          // type:org.dxos.type.person
+          'Filter',
+          'TypeFilter',
+          'TypeKeyword',
+          ':',
+          'Identifier',
+        ],
+      },
+      {
+        // Persons for Organizations with name "DXOS"
+        // TODO(burdon): Filter relations.
+        input: '((type:org.dxos.type.organization AND { name: "DXOS" }) -> type:org.dxos.type.person)',
+        expected: [
+          'Query',
+          '(',
+          '(',
+          'Filter',
+          'TypeFilter',
+          'TypeKeyword',
+          ':',
+          'Identifier',
+          'And',
+          'Filter',
+          'ObjectLiteral',
+          '{',
+          'ObjectProperty',
+          'Identifier',
+          ':',
+          'Value',
+          'String',
+          '}',
+          ')',
+          'Relation',
+          'ArrowRight',
+          'Filter',
+          'TypeFilter',
+          'TypeKeyword',
+          ':',
+          'Identifier',
+          ')',
+        ],
+      },
+      {
+        input: 'type:org.dxos.type.person and { name: "DXOS" }',
+        expected: [
+          'Query',
+          'Filter',
+          'TypeFilter',
+          'TypeKeyword',
+          ':',
+          'Identifier',
+          'And',
+          'Filter',
+          'ObjectLiteral',
+          '{',
+          'ObjectProperty',
+          'Identifier',
+          ':',
+          'Value',
+          'String',
+          '}',
+        ],
+      },
+      {
+        input: 'x = ( type: org.dxos.type.person )',
+        expected: [
+          'Query',
+          'Assignment',
+          'Identifier',
+          '=',
+          '(',
+          'Filter',
+          'TypeFilter',
+          'TypeKeyword',
+          ':',
+          'Identifier',
+          ')',
+        ],
+      },
+    ];
+
+    for (const { input, expected } of tests) {
+      let tree: Tree;
+      try {
+        tree = queryParser.parse(input);
+      } catch (err) {
+        console.error(new Error(`Failed to parse: ${input}`, { cause: err }));
+        continue;
+      }
+
+      const cursor = tree.cursor();
+      const result: string[] = [];
+      do {
+        result.push(cursor.node.name);
+      } while (cursor.next());
+      expect(result, input).toEqual(expected);
+    }
+  });
+
+  it('build', ({ expect }) => {
+    const queryBuilder = new QueryBuilder({
+      tag_1: Tag.make({ label: 'foo' }),
+      tag_2: Tag.make({ label: 'bar' }),
+    });
+
+    // TODO(burdon): Test "not"
+    type Test = { input: string; expected: BuildResult };
+    const tests: Test[] = [
+      // Types
+      {
+        input: 'type:org.dxos.type.person',
+        expected: {
+          filter: Filter.type(DXN.make('org.dxos.type.person')),
+        },
+      },
+      // Tags
+      {
+        input: '#foo',
+        expected: {
+          filter: Filter.tag('tag_1'),
+        },
+      },
+      {
+        input: '#foo AND #bar',
+        expected: {
+          filter: Filter.and(Filter.tag('tag_1'), Filter.tag('tag_2')),
+        },
+      },
+      {
+        input: '#foo #bar',
+        expected: {
+          filter: Filter.and(Filter.tag('tag_1'), Filter.tag('tag_2')),
+        },
+      },
+      // Text
+      {
+        input: '"test"',
+        expected: {
+          filter: Filter.text('test'),
+        },
+      },
+      // Mixed
+      {
+        input: '#foo "test"',
+        expected: {
+          filter: Filter.and(Filter.tag('tag_1'), Filter.text('test')),
+        },
+      },
+      // Props
+      {
+        input: '{ name: "DXOS" }',
+        expected: {
+          filter: Filter.props({ name: 'DXOS' }),
+        },
+      },
+      {
+        input: '{ value: 100 }',
+        expected: {
+          filter: Filter.props({ value: 100 }),
+        },
+      },
+      {
+        input: 'type:org.dxos.type.person OR type:org.dxos.type.organization',
+        expected: {
+          filter: Filter.or(
+            Filter.type(DXN.make('org.dxos.type.person')),
+            Filter.type(DXN.make('org.dxos.type.organization')),
+          ),
+        },
+      },
+      {
+        input: '(type:org.dxos.type.person OR type:org.dxos.type.organization) AND { name: "DXOS" }',
+        expected: {
+          filter: Filter.and(
+            Filter.or(
+              Filter.type(DXN.make('org.dxos.type.person')),
+              Filter.type(DXN.make('org.dxos.type.organization')),
+            ),
+            Filter.props({ name: 'DXOS' }),
+          ),
+        },
+      },
+      {
+        input: 'type:org.dxos.type.person and { name: "DXOS" }',
+        expected: {
+          filter: Filter.and(Filter.type(DXN.make('org.dxos.type.person')), Filter.props({ name: 'DXOS' })),
+        },
+      },
+      // Assignment
+      {
+        input: 'x = ( type:org.dxos.type.person )',
+        expected: {
+          name: 'x',
+          filter: Filter.type(DXN.make('org.dxos.type.person')),
+        },
+      },
+      {
+        input: 'x = ( #foo AND "bar" )',
+        expected: {
+          name: 'x',
+          filter: Filter.and(Filter.tag('tag_1'), Filter.text('bar')),
+        },
+      },
+      // TODO(burdon): Convert Query/Filter expr to AST.
+      // TODO(burdon): Person -> Organization (many-to-many relation).
+      // Get Research Note objects for Organization objects for Person objects with jobTitle.
+      //
+      // Cypher: MATCH (p:Person)-[:WorksAt]->(o:Organization)<-[:HasSubject]-(r:ResearchNote) WHERE p.jotTitle IS NOT NULL
+      // ((type:Person AND { jobTitle: "investor" }) -[:WorksAt]-> type:Organization) <-[:HasSubject]- type:ResearchNote
+      //
+      // {
+      //   input: '',
+      //   expected: Query.select(Filter.typename('org.dxos.type.person', { jobTitle: 'investor' }))
+      //     .reference('organization')
+      //     .targetOf(Relation.of('org.dxos.relation.hasSubject')) // TODO(burdon): Invert?
+      //     .source(),
+      // },
+    ];
+
+    tests.forEach(({ input, expected }) => {
+      const result = queryBuilder.build(input);
+      expect(result, JSON.stringify({ input, result, expected }, null, 2)).toEqual(expected);
+    });
+  });
+
+  test('normalizeInput', ({ expect }) => {
+    type Test = { input: string; expected: string };
+    const tests: Test[] = [
+      { input: 'foo', expected: '"foo"' },
+      { input: 'foo bar', expected: '"foo" "bar"' },
+      { input: 'foo  bar', expected: '"foo"  "bar"' },
+      { input: '"already" bare', expected: '"already" "bare"' },
+      { input: 'from:rich@dxos.org', expected: 'from:"rich@dxos.org"' },
+      { input: 'from:rich@dxos.org urgent', expected: 'from:"rich@dxos.org" "urgent"' },
+      { input: 'name:DXOS', expected: 'name:"DXOS"' },
+      { input: 'count:42', expected: 'count:42' },
+      { input: 'active:true', expected: 'active:true' },
+      { input: 'value:null', expected: 'value:null' },
+      { input: 'name:"DXOS"', expected: 'name:"DXOS"' },
+      { input: 'type:org.dxos.type.person', expected: 'type:org.dxos.type.person' },
+      { input: '#tag', expected: '#tag' },
+      { input: '#tag foo', expected: '#tag "foo"' },
+      { input: 'foo AND bar', expected: '"foo" AND "bar"' },
+      { input: 'foo OR bar', expected: '"foo" OR "bar"' },
+      { input: 'NOT foo', expected: 'NOT "foo"' },
+      { input: '!foo', expected: '!"foo"' },
+      { input: '(foo bar)', expected: '("foo" "bar")' },
+      { input: 'x = ( foo )', expected: 'x = ( "foo" )' },
+      { input: '{ name: "DXOS" }', expected: '{ name: "DXOS" }' },
+      // Apostrophes inside barewords don't open a quoted string.
+      { input: "don't", expected: '"don\'t"' },
+      { input: "O'Connor", expected: '"O\'Connor"' },
+      { input: "don't worry", expected: '"don\'t" "worry"' },
+      // Unmatched closing brace/bracket — passed through, no infinite loop.
+      { input: 'foo}', expected: '"foo"}' },
+      { input: 'foo]bar', expected: '"foo"]"bar"' },
+      // Genuine single-quoted string still works.
+      { input: "'foo bar'", expected: "'foo bar'" },
+      // URLs are searched as text rather than auto-promoted to property filters.
+      { input: 'https://dxos.org', expected: '"https://dxos.org"' },
+      { input: 'http://example.com/foo', expected: '"http://example.com/foo"' },
+      { input: 'mailto:rich@dxos.org', expected: '"mailto:rich@dxos.org"' },
+      // Escapes round-trip: backslashes are escaped in the literal body.
+      { input: 'foo\\bar', expected: '"foo\\\\bar"' },
+    ];
+
+    for (const { input, expected } of tests) {
+      expect(normalizeInput(input), input).toEqual(expected);
+    }
+  });
+
+  test('build with property and text fragments', ({ expect }) => {
+    const queryBuilder = new QueryBuilder({
+      tag_1: Tag.make({ label: 'foo' }),
+    });
+
+    type Test = { input: string; expected: BuildResult };
+    const tests: Test[] = [
+      // Property filter from `key:value` text input.
+      {
+        input: 'from:rich@dxos.org',
+        expected: { filter: Filter.props({ from: 'rich@dxos.org' }) },
+      },
+      {
+        input: 'name:DXOS',
+        expected: { filter: Filter.props({ name: 'DXOS' }) },
+      },
+      // Bare text fragment becomes text search.
+      {
+        input: 'urgent',
+        expected: { filter: Filter.text('urgent') },
+      },
+      // Multiple bare fragments are AND-joined.
+      {
+        input: 'urgent review',
+        expected: { filter: Filter.and(Filter.text('urgent'), Filter.text('review')) },
+      },
+      // Mixed property + text fragment.
+      {
+        input: 'from:rich@dxos.org urgent',
+        expected: {
+          filter: Filter.and(Filter.props({ from: 'rich@dxos.org' }), Filter.text('urgent')),
+        },
+      },
+      // Tag + text fragment.
+      {
+        input: '#foo bar',
+        expected: { filter: Filter.and(Filter.tag('tag_1'), Filter.text('bar')) },
+      },
+      // Three fragments AND-joined.
+      {
+        input: 'a b c',
+        expected: {
+          filter: Filter.and(Filter.text('a'), Filter.text('b'), Filter.text('c')),
+        },
+      },
+      // URLs are text-searched, not promoted to property filters.
+      {
+        input: 'https://dxos.org',
+        expected: { filter: Filter.text('https://dxos.org') },
+      },
+      {
+        input: 'mailto:rich@dxos.org',
+        expected: { filter: Filter.text('mailto:rich@dxos.org') },
+      },
+      // Escapes decode back to the original input.
+      {
+        input: 'foo\\bar',
+        expected: { filter: Filter.text('foo\\bar') },
+      },
+    ];
+
+    tests.forEach(({ input, expected }) => {
+      const result = queryBuilder.build(input);
+      expect(result, JSON.stringify({ input, result, expected }, null, 2)).toEqual(expected);
+    });
+  });
+});

package/src/query-lite/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './query-lite';