@dxos/datalog 0.0.1 → 0.13.0

package/src/Parser.test.ts

@@ -0,0 +1,84 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Ast from './Ast.ts';
+import * as Parser from './Parser.ts';
+
+describe('Parser', () => {
+  test('parses facts, rules, strings, numbers and anonymous variables', ({ expect }) => {
+    const program = Parser.parse(`
+      % a comment
+      edge(a, "b c", 3).
+      path(X, Y) :- edge(X, Y, _). // trailing comment
+      /* block
+         comment */
+      wake(followup) :- elapsed(goal, 2d), not achieved(goal).
+    `);
+    expect(program.rules).toHaveLength(3);
+    expect(program.rules[0].head.terms).toEqual([Ast.constant('a'), Ast.constant('b c'), Ast.constant(3)]);
+    expect(program.rules[1].body[0]).toMatchObject({
+      type: 'atom',
+      negated: false,
+      atom: { predicate: 'edge', terms: [{ name: 'X' }, { name: 'Y' }, { anonymous: true }] },
+    });
+    expect(program.rules[2].body[0]).toMatchObject({ atom: { terms: [{ value: 'goal' }, { value: '2d' }] } });
+    expect(program.rules[2].body[1]).toMatchObject({ type: 'atom', negated: true, atom: { predicate: 'achieved' } });
+    expect(program.rules[1].position).toEqual({ line: 4, column: 7 });
+  });
+
+  test('parses negation forms, comparisons and zero-arity atoms', ({ expect }) => {
+    const program = Parser.parse('p :- q(X), !r(X), not(s(X)), X != "x", X >= -2.5, done.');
+    const [q, r, s, notEqual, greater, done] = program.rules[0].body;
+    expect(q).toMatchObject({ type: 'atom', negated: false });
+    expect(r).toMatchObject({ type: 'atom', negated: true, atom: { predicate: 'r' } });
+    expect(s).toMatchObject({ type: 'atom', negated: true, atom: { predicate: 's' } });
+    expect(notEqual).toMatchObject({ type: 'comparison', operator: '!=', right: { value: 'x' } });
+    expect(greater).toMatchObject({ type: 'comparison', operator: '>=', right: { value: -2.5 } });
+    expect(done).toMatchObject({ type: 'atom', atom: { predicate: 'done', terms: [] } });
+  });
+
+  test('parses aggregates', ({ expect }) => {
+    const program = Parser.parse(`
+      total(N) :- N = count : { item(_) }.
+      cheapest(M) :- M = min P : { price(_, P) }.
+      spend(C, S) :- customer(C), S = sum A : order(C, A).
+    `);
+    expect(program.rules[0].body[0]).toMatchObject({ type: 'aggregate', function: 'count', target: undefined });
+    expect(program.rules[1].body[0]).toMatchObject({ type: 'aggregate', function: 'min', target: { name: 'P' } });
+    expect(program.rules[2].body[1]).toMatchObject({
+      type: 'aggregate',
+      function: 'sum',
+      body: [{ type: 'atom', atom: { predicate: 'order' } }],
+    });
+  });
+
+  test('round-trips through format', ({ expect }) => {
+    const source =
+      'achieved(goal) :- fact(F, dima, helps_with, "agent plugin"), polarity(F, "+"), N = count : { p(F) }, N > 1.';
+    expect(Ast.format(Parser.parse(source))).toBe(source);
+    expect(Parser.parse(Ast.format(Parser.parse(source)))).toEqual(Parser.parse(source));
+  });
+
+  test.for([
+    ['p(X) :- q(X)', 1, 13, "Expected '.', ',' or ':-' but reached end of input"],
+    ['p(X) :- q(X)\n.\nr(', 3, 3, 'Expected a term but reached end of input'],
+    ['p(X :- q(X).', 1, 5, "Expected ',' or ')' but found ':-'"],
+    ['p(X) :- \n  q(X), "a".', 2, 12, "Expected a comparison operator but found '.'"],
+    ['p("unterminated) .', 1, 3, 'Unterminated string'],
+    ['p(X) :- q(X) ; r(X).', 1, 14, "Unexpected character ';'"],
+    ['Foo(X).', 1, 1, "Expected a predicate name but found 'Foo'"],
+    ['p(N) :- N = avg X : { q(X) }.', 1, 13, "Expected count, min, max or sum but found 'avg'"],
+  ] as const)('rejects %j at %i:%i', ([source, line, column, reason], { expect }) => {
+    let error: unknown;
+    try {
+      Parser.parse(source);
+    } catch (caught) {
+      error = caught;
+    }
+    expect(error).toBeInstanceOf(Parser.ParseError);
+    expect(error).toMatchObject({ position: { line, column }, reason });
+  });
+});

package/src/Parser.ts

@@ -0,0 +1,180 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import { BaseError } from '@dxos/errors';
+
+import type * as Ast from './Ast.ts';
+import { LexError, type Token, tokenize } from './internal/lexer.ts';
+
+/** A syntax error with the 1-based position of the offending token. */
+export class ParseError extends BaseError.extend('ParseError', 'Syntax error') {
+  constructor(
+    readonly reason: string,
+    readonly position: Ast.Position,
+  ) {
+    super({ message: reason, context: { line: position.line, column: position.column } });
+  }
+}
+
+const AGGREGATES: ReadonlyArray<Ast.AggregateFunction> = ['count', 'min', 'max', 'sum'];
+
+const isAggregateFunction = (text: string): text is Ast.AggregateFunction => AGGREGATES.some((name) => name === text);
+
+const OPERATORS: ReadonlyArray<Ast.ComparisonOperator> = ['=', '!=', '<', '<=', '>', '>='];
+
+const toOperator = (text: string): Ast.ComparisonOperator | undefined => OPERATORS.find((op) => op === text);
+
+/**
+ * Parses dialect source (Soufflé-like: `head :- body.`, `not`/`!` negation, comparisons and
+ * `N = count : { … }` aggregates) into a program.
+ * @throws ParseError on the first syntax error.
+ */
+export const parse = (source: string): Ast.Program => {
+  let tokens: Token[];
+  try {
+    tokens = tokenize(source);
+  } catch (error) {
+    if (error instanceof LexError) {
+      throw new ParseError(error.reason, error.position);
+    }
+    throw error;
+  }
+
+  let cursor = 0;
+  let anonymous = 0;
+  const end = (): Ast.Position => {
+    const last = tokens.at(-1);
+    return last
+      ? { line: last.position.line, column: last.position.column + last.text.length }
+      : { line: 1, column: 1 };
+  };
+  const peek = (ahead = 0): Token | undefined => tokens[cursor + ahead];
+  const fail = (expected: string, token = peek()): never => {
+    throw new ParseError(
+      token ? `Expected ${expected} but found '${token.text}'` : `Expected ${expected} but reached end of input`,
+      token?.position ?? end(),
+    );
+  };
+  const expect = (type: Token['type'], description = `'${type}'`): Token => {
+    const token = peek();
+    if (!token || token.type !== type) {
+      return fail(description);
+    }
+    cursor++;
+    return token;
+  };
+
+  const term = (): Ast.Term => {
+    const token = peek();
+    switch (token?.type) {
+      case 'variable':
+        cursor++;
+        return token.text === '_'
+          ? { type: 'variable', name: `_${anonymous++}`, anonymous: true }
+          : { type: 'variable', name: token.text };
+      case 'identifier':
+      case 'string':
+      case 'number':
+        cursor++;
+        return { type: 'constant', value: token.value ?? token.text };
+      default:
+        return fail('a term');
+    }
+  };
+
+  const atom = (): Ast.Atom => {
+    const name = expect('identifier', 'a predicate name');
+    const terms: Ast.Term[] = [];
+    if (peek()?.type === '(') {
+      cursor++;
+      if (peek()?.type !== ')') {
+        terms.push(term());
+        while (peek()?.type === ',') {
+          cursor++;
+          terms.push(term());
+        }
+      }
+      expect(')', "',' or ')'");
+    }
+    return { predicate: name.text, terms };
+  };
+
+  const aggregate = (result: Ast.Term, position: Ast.Position): Ast.AggregateLiteral => {
+    const name = expect('identifier', 'an aggregate function');
+    if (!isAggregateFunction(name.text)) {
+      return fail('count, min, max or sum', name);
+    }
+    const target = name.text === 'count' ? undefined : term();
+    expect(':', "':'");
+    let body: Ast.Literal[];
+    if (peek()?.type === '{') {
+      cursor++;
+      body = conjunction();
+      expect('}', "',' or '}'");
+    } else {
+      body = [literal()];
+    }
+    if (body.some((item) => item.type === 'aggregate')) {
+      throw new ParseError('Aggregates cannot be nested', position);
+    }
+    return { type: 'aggregate', function: name.text, result, target, body, position };
+  };
+
+  /** `fn :` or `fn Term :` after `=`; unknown function names are reported by `aggregate`. */
+  const isAggregateAhead = (): boolean =>
+    peek()?.type === 'identifier' && (peek(1)?.type === ':' || peek(2)?.type === ':');
+
+  const literal = (): Ast.Literal => {
+    const token = peek();
+    if (!token) {
+      return fail('a literal');
+    }
+    const position = token.position;
+    if (token.type === '!' || (token.type === 'identifier' && token.text === 'not' && peek(1)?.type !== ':-')) {
+      cursor++;
+      if (peek()?.type === '(' && token.type === 'identifier') {
+        cursor++;
+        const negated = atom();
+        expect(')', "')'");
+        return { type: 'atom', atom: negated, negated: true, position };
+      }
+      return { type: 'atom', atom: atom(), negated: true, position };
+    }
+    if (peek(1)?.type === 'operator' || token.type !== 'identifier') {
+      const left = term();
+      const operatorToken = expect('operator', 'a comparison operator');
+      const operator = toOperator(operatorToken.text) ?? fail('a comparison operator', operatorToken);
+      if (operator === '=' && isAggregateAhead()) {
+        return aggregate(left, position);
+      }
+      return { type: 'comparison', operator, left, right: term(), position };
+    }
+    return { type: 'atom', atom: atom(), negated: false, position };
+  };
+
+  const conjunction = (): Ast.Literal[] => {
+    const literals = [literal()];
+    while (peek()?.type === ',') {
+      cursor++;
+      literals.push(literal());
+    }
+    return literals;
+  };
+
+  const rules: Ast.Rule[] = [];
+  while (cursor < tokens.length) {
+    const position = peek()?.position;
+    const head = atom();
+    let body: Ast.Literal[] = [];
+    if (peek()?.type === ':-') {
+      cursor++;
+      body = conjunction();
+    }
+    expect('.', "'.', ',' or ':-'");
+    rules.push({ head, body, position });
+  }
+  return { rules };
+};

package/src/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * as Ast from './Ast.ts';
+export * as Builtin from './Builtin.ts';
+export * as Checker from './Checker.ts';
+export * as Engine from './Engine.ts';
+export * as Parser from './Parser.ts';

package/src/internal/lexer.ts

@@ -0,0 +1,154 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { BaseError } from '@dxos/errors';
+
+import type * as Ast from '../Ast.ts';
+
+export type TokenType =
+  | 'identifier'
+  | 'variable'
+  | 'string'
+  | 'number'
+  | 'operator'
+  | ':-'
+  | ':'
+  | '('
+  | ')'
+  | '{'
+  | '}'
+  | ','
+  | '.'
+  | '!';
+
+export type Token = {
+  readonly type: TokenType;
+  readonly text: string;
+  readonly value?: Ast.Value;
+  readonly position: Ast.Position;
+};
+
+/** A malformed token with the 1-based position where it starts. */
+export class LexError extends BaseError.extend('LexError', 'Invalid token') {
+  constructor(
+    readonly reason: string,
+    readonly position: Ast.Position,
+  ) {
+    super({ message: reason, context: { line: position.line, column: position.column } });
+  }
+}
+
+const PUNCTUATION: Record<string, TokenType | undefined> = {
+  ':': ':',
+  '(': '(',
+  ')': ')',
+  '{': '{',
+  '}': '}',
+  ',': ',',
+  '.': '.',
+  '!': '!',
+};
+
+const ESCAPES: Record<string, string> = { 'n': '\n', 't': '\t', 'r': '\r', '\\': '\\', '"': '"', "'": "'" };
+
+/** Splits dialect source into tokens with 1-based positions. */
+export const tokenize = (source: string): Token[] => {
+  const tokens: Token[] = [];
+  let offset = 0;
+  let line = 1;
+  let lineStart = 0;
+  const here = (): Ast.Position => ({ line, column: offset - lineStart + 1 });
+  const advance = (count: number) => {
+    for (let index = 0; index < count; index++) {
+      if (source[offset] === '\n') {
+        line++;
+        lineStart = offset + 1;
+      }
+      offset++;
+    }
+  };
+
+  while (offset < source.length) {
+    const char = source[offset];
+    const rest = source.slice(offset);
+    if (/\s/.test(char)) {
+      advance(1);
+      continue;
+    }
+    if (char === '%' || rest.startsWith('//')) {
+      while (offset < source.length && source[offset] !== '\n') {
+        advance(1);
+      }
+      continue;
+    }
+    if (rest.startsWith('/*')) {
+      const start = here();
+      const end = source.indexOf('*/', offset + 2);
+      if (end < 0) {
+        throw new LexError('Unterminated comment', start);
+      }
+      advance(end + 2 - offset);
+      continue;
+    }
+
+    const position = here();
+    if (char === '"' || char === "'") {
+      let value = '';
+      let cursor = offset + 1;
+      while (cursor < source.length && source[cursor] !== char) {
+        if (source[cursor] === '\n') {
+          throw new LexError('Unterminated string', position);
+        }
+        if (source[cursor] === '\\') {
+          const escaped = source[cursor + 1];
+          value += ESCAPES[escaped] ?? escaped ?? '';
+          cursor += 2;
+        } else {
+          value += source[cursor++];
+        }
+      }
+      if (cursor >= source.length) {
+        throw new LexError('Unterminated string', position);
+      }
+      tokens.push({ type: 'string', text: source.slice(offset, cursor + 1), value, position });
+      advance(cursor + 1 - offset);
+      continue;
+    }
+
+    // A digit run glued to letters (`2d`, `30d`) is a symbol, which keeps durations unquoted.
+    const numeric = /^-?\d+(\.\d+)?(?![A-Za-z_\d])/.exec(rest);
+    if (numeric) {
+      tokens.push({ type: 'number', text: numeric[0], value: Number(numeric[0]), position });
+      advance(numeric[0].length);
+      continue;
+    }
+    const word = /^[A-Za-z0-9_][A-Za-z0-9_]*/.exec(rest);
+    if (word) {
+      const text = word[0];
+      const type: TokenType = /^[A-Z_]/.test(text) ? 'variable' : 'identifier';
+      tokens.push({ type, text, value: type === 'identifier' ? text : undefined, position });
+      advance(text.length);
+      continue;
+    }
+    const operator = /^(<=|>=|!=|=|<|>)/.exec(rest);
+    if (operator) {
+      tokens.push({ type: 'operator', text: operator[0], position });
+      advance(operator[0].length);
+      continue;
+    }
+    if (rest.startsWith(':-')) {
+      tokens.push({ type: ':-', text: ':-', position });
+      advance(2);
+      continue;
+    }
+    const punctuation = PUNCTUATION[char];
+    if (punctuation) {
+      tokens.push({ type: punctuation, text: char, position });
+      advance(1);
+      continue;
+    }
+    throw new LexError(`Unexpected character '${char}'`, position);
+  }
+  return tokens;
+};