@omgbase/oqx 0.15.0 → 0.20.0

package/src/ast.ts

@@ -1,8 +1,20 @@
-// OQX query AST for the generic kernel. The parser produces this directly and
-// the interpreter walks it — there is no separate lowering/IR pass, because a
-// "relation" in the generic kernel is just an expression evaluated against the
-// current row (property navigation on the host object model), resolved at run
-// time rather than against a fixed schema.
+// The OQX AST — a first-class, language-level contract (spec/oqx/AST.md, since
+// language 0.16). The parser produces it, the interpreter walks it, and tools
+// reflect on it without re-parsing: every node carries `kind` and `span`, every
+// optional field is materialized (`null` / `false`), and the in-memory objects
+// ARE the JSON shape both implementations serialize (plain data, no parent
+// pointers, no methods). There is no separate lowering/IR pass: a "relation" is
+// just an expression evaluated against the current row.
+//
+// `where` keeps its surface form: a `select` alias referenced in `where` stays a
+// bare identifier here; `resolveAliases` (resolve.ts) performs the substitution
+// before evaluation. Nodes built by a tool rather than the parser carry the
+// empty span `[0, 0]` (see `build.ts`).
+
+/** A half-open source range `[start, end)` in Unicode code points over the raw
+ * source (`rawSource` for a template, where a binding occupies its `${n}`
+ * marker). The empty span `[0, 0]` marks a node that did not come from source. */
+export type Span = [start: number, end: number];
 
 /** Query consumers — how a (sub)query's row set is shaped. `none` is the
  * zero-cardinality complement of `exists` (true iff the block yields no rows). */
@@ -11,50 +23,85 @@ export type Consumer = "collect" | "exists" | "none" | "count" | "first" | "sing
 /** Comparison operators usable in a `count { … } <op> <int>` test. */
 export type RelOp = "==" | "!=" | "<" | "<=" | ">" | ">=";
 
+/** The identity operators (SEMANTICS §5b, since 0.17). */
+export type IdentityOp = "is" | "is not";
+
+/** The operator of a `binary` expression: a comparison, an identity test, or arithmetic. */
+export type BinaryOp = RelOp | IdentityOp | "+" | "-" | "*" | "/" | "%";
+
+/** The operator of a `unary` expression. */
+export type UnaryOp = "!" | "-";
+
+/** The operator of a `logical` expression. */
+export type LogicalOp = "&&" | "||";
+
 /** Scalar value/predicate expression, evaluated against a row scope + bindings. */
 export type Expr =
-  | { kind: "lit"; value: string | number | boolean | null }
-  | { kind: "ident"; name: string } // bare property of the CURRENT row/scope only (never climbs); `$it` is the row itself
-  | { kind: "outer"; levels: number; name: string } // `^name` — read from exactly `levels` scopes out
-  | { kind: "binding"; index: number } // a ${…} interpolated host value
-  | { kind: "member"; recv: Expr; name: string } // .prop navigation on the value to its left
-  | { kind: "index"; recv: Expr; index: Expr } // [expr] navigation
-  | { kind: "call"; recv: Expr | null; name: string; args: Expr[] } // fn / method
-  | { kind: "unary"; op: "!" | "-"; expr: Expr }
-  | { kind: "binary"; op: string; left: Expr; right: Expr } // arithmetic + comparison
-  | { kind: "logical"; op: "&&" | "||"; left: Expr; right: Expr }
-  | { kind: "in"; left: Expr; right: Expr }
+  | { kind: "lit"; span: Span; value: string | number | boolean | null }
+  | { kind: "ident"; span: Span; name: string } // bare property of the CURRENT row/scope only (never climbs); `$it` is the row itself
+  | { kind: "outer"; span: Span; levels: number; name: string } // `^name` — read from exactly `levels` scopes out (also what `N^name` parses to, since 0.18)
+  | { kind: "binding"; span: Span; index: number } // a ${…} interpolated host value
+  | { kind: "member"; span: Span; recv: Expr; name: string } // .prop navigation on the value to its left
+  | { kind: "call"; span: Span; recv: Expr | null; name: string; args: Expr[] } // fn / method
+  | { kind: "unary"; span: Span; op: UnaryOp; expr: Expr }
+  // `x!` — the value of `expr`, or an eval error when it is absent (since 0.17).
+  | { kind: "required"; span: Span; expr: Expr }
+  | { kind: "binary"; span: Span; op: BinaryOp; left: Expr; right: Expr } // arithmetic + comparison + identity
+  | { kind: "logical"; span: Span; op: LogicalOp; left: Expr; right: Expr }
+  | { kind: "in"; span: Span; left: Expr; right: Expr }
   // A Ruby-style range value. `lo`/`hi` are null for the open-ended forms
   // (`..5` / `5..`); `exclusiveEnd` distinguishes `1...5` from `1..5`. Evaluates
   // to a runtime range value (see semantics.makeRange); primarily the RHS of `in`.
-  | { kind: "range"; lo: Expr | null; hi: Expr | null; exclusiveEnd: boolean };
+  | { kind: "range"; span: Span; lo: Expr | null; hi: Expr | null; exclusiveEnd: boolean }
+  // A tuple `(e1, e2, …)` (since 0.20): two or more expressions whose values
+  // concatenate with one level of flattening (SEMANTICS §3b) — a value and a
+  // receiver (`(a, b) { … }`, `follow (a, b) { depth 2 }`). One expression in
+  // parentheses is grouping and leaves no node.
+  | { kind: "tuple"; span: Span; items: Expr[] }
+  // A value-position directive (since 0.17): `recv first { … }.pay`, and what a
+  // bracket lookup `x[…]` desugars to. `isExpr` is false for it — an op is an
+  // expression only by position; discriminate on `kind === "op"`.
+  | OpNode;
 
+/** One `order by` term. */
 export interface OrderSpec {
+  kind: "order";
+  span: Span;
   expr: Expr;
   desc: boolean;
 }
 
 /** One projection item: a named scalar/navigation value, or a named nested
- * collection consumer. `lift` marks a `^name` one-scope lift. */
+ * collection consumer. `lift` marks a `^name` lift. */
 export type SelectItem =
   // `lift` is the number of `^` carets: 0 = an ordinary projection, N = a lift
-  // that binds this value N scopes out (see the engine's flatten-append).
-  | { kind: "field"; name: string; expr: Expr; lift: number }
-  | { kind: "collect"; name: string; op: OpNode };
+  // that binds this value N scopes out (see the engine's flatten-append). `name`
+  // is `""` for an unaliased non-navigation item, which the parser only admits
+  // under `values`.
+  | { kind: "field"; span: Span; name: string; expr: Expr; lift: number }
+  | { kind: "collect"; span: Span; name: string; op: OpNode };
+
+/** The `count { … } <op> <int>` test attached to an `OpNode` — an attribute of
+ * the directive, not a node of its own. */
+export interface CountCmp {
+  op: RelOp;
+  value: number;
+}
 
 /** A postfix consumer directive over a receiver collection:
  * `<receiver> <op> { <sub> }`, optionally `count { … } <relop> <int>`. */
 export interface OpNode {
   kind: "op";
+  span: Span;
   receiver: Expr;
   op: Consumer;
   sub: Subquery;
-  countCmp?: { op: RelOp; value: number };
+  countCmp: CountCmp | null;
   /** `distinct` — dedup the rows this directive consumes by their projected
    * value (the `select`), so `count distinct { … }` counts distinct projections
    * and `collect distinct { … }` yields distinct rows. Empty select ⇒ dedup by
    * row identity. Spellable as `<op> distinct { … }` or `{ select distinct … }`. */
-  distinct?: boolean;
+  distinct: boolean;
 }
 
 /** One `follow` destination: a relation of the current row (an `Expr` receiver), or a
@@ -62,48 +109,61 @@ export interface OpNode {
  * per frontier row, inside which `^` is that row. Discriminate on `kind === "op"`. */
 export type FollowDestination = Expr | OpNode;
 
-/** The recursive `follow` clause. */
+/** The recursive `follow` clause (since 0.20 just the destinations: a
+ * destination's `where`, `frontier` and `depth` live in its own block). */
 export interface Follow {
+  kind: "follow";
+  span: Span;
   destinations: FollowDestination[]; // ≥ 1, in source order; the walk is their union
   distinct: boolean;
-  where: Expr | null; // successor predicate: which successors keep participating
-  frontier: Expr | null; // boundary predicate: cut a relation that could continue
-  depth: number | null; // 1..8 cap; null = the hard cap
-  by: Expr | null; // identity expression for cycle detection / dedup
 }
 
-/** A nested (sub)query body. */
+/** A nested (sub)query body — the `{ … }` of a directive. */
 export interface Subquery {
+  kind: "subquery";
+  span: Span;
   from: Expr[]; // body-level `from E` re-projections (flatMap chain)
   where: Where | null;
   select: SelectItem[];
   orderBy: OrderSpec[] | null;
   follow: Follow | null;
+  /** `frontier P` / `depth n` (since 0.20). In a `follow` destination block
+   * `frontier` marks the occurrences reached through this destination for
+   * which `P` holds (not expanded; `P` read one level out, under the walk's
+   * enclosing scope), and `depth n` makes the destination expand a frontier
+   * row only while that row's `$depth < n` (1..8; `null` = the hard cap 8).
+   * In any other block `frontier` is legal only with a `follow` and marks the
+   * walk's SEEDS, read in the seed's scope like `where` (as on `Query`);
+   * `depth` is destination-only. Both `null` when absent. */
+  frontier: Expr | null;
+  depth: number | null;
   /** `values` — scalar projection mode: the (single) projected expression is the
    * row's result itself rather than being wrapped in a `{ name: value }` record,
    * so `name values` yields `["Bob", …]` and `$it values` yields the rows. */
-  values?: boolean;
+  values: boolean;
   /** `limit N` / `offset N` — bound the row set AFTER where/order/distinct and
    * BEFORE the consumer reduces it, so `count { … limit 5 }` is at most 5 and
    * `first { … offset 1 }` is the second row. Each is a value expression
    * (a literal, a `${…}` binding, or an outer reference) read as part of the
    * block — `^n` is the enclosing row's field, as everywhere inside `{ … }` —
    * and must yield a non-negative integer. */
-  limit?: Expr;
-  offset?: Expr;
+  limit: Expr | null;
+  offset: Expr | null;
 }
 
 /** The where-clause boolean tree: OQX owns &&/||/!/grouping so consumer ops
  * (invisible to the scalar evaluator) compose with scalar predicates. */
 export type Where =
-  | { kind: "and"; parts: Where[] }
-  | { kind: "or"; parts: Where[] }
-  | { kind: "not"; expr: Where }
-  | { kind: "scalar"; expr: Expr }
+  | { kind: "and"; span: Span; parts: Where[] }
+  | { kind: "or"; span: Span; parts: Where[] }
+  | { kind: "not"; span: Span; expr: Where }
+  | { kind: "scalar"; span: Span; expr: Expr }
   | OpNode;
 
 /** A top-level OQX query. */
 export interface Query {
+  kind: "query";
+  span: Span;
   source: Expr; // the root collection (`from <source>` or the directive receiver)
   from: Expr[]; // further top-level `from E` re-projections
   where: Where | null;
@@ -111,11 +171,37 @@ export interface Query {
   orderBy: OrderSpec[] | null;
   consumer: Consumer;
   follow: Follow | null;
+  /** `frontier P` (since 0.20) — legal only when the body has a `follow`: a
+   * seed for which `P` holds (read in the seed's own scope, `^` the enclosing
+   * scope, like `where`) is a frontier (`$stop == "frontier"`, not expanded).
+   * `null` without one. */
+  frontier: Expr | null;
   /** `distinct` — dedup the result rows by their projected value (see OpNode). */
-  distinct?: boolean;
+  distinct: boolean;
   /** `values` — scalar projection mode (see Subquery). */
-  values?: boolean;
+  values: boolean;
   /** `limit N` / `offset N` (see Subquery); evaluated at the root scope. */
-  limit?: Expr;
-  offset?: Expr;
+  limit: Expr | null;
+  offset: Expr | null;
+}
+
+/** Every node of the tree. `AstNode["kind"]` is the closed set of node kinds. */
+export type AstNode = Query | Subquery | OpNode | Follow | OrderSpec | SelectItem | Where | Expr;
+
+/** The closed set of node kinds. */
+export type AstKind = AstNode["kind"];
+
+/** The expression kinds (`Expr["kind"]`), for `isExpr`. */
+const EXPR_KINDS: ReadonlySet<string> = new Set([
+  "lit", "ident", "outer", "binding", "member", "call", "unary", "required", "binary", "logical", "in", "range", "tuple",
+]);
+
+/** Whether a node is a scalar `Expr` (an `op` in expression position is not: it
+ * is an expression only by position, see AST.md §1). */
+export function isExpr(node: AstNode): node is Expr {
+  return EXPR_KINDS.has(node.kind);
 }
+
+/** The parsed query's JSON form (`toJSON`): the tree with the language version
+ * it was produced under. */
+export type QueryJson = Query & { oqx: string };

package/src/build.ts

@@ -0,0 +1,73 @@
+// Builders for AST nodes a tool constructs itself (spec/oqx/AST.md §7). Every
+// node they make carries the empty span `[0, 0]` — "not from source" — and the
+// materialized defaults (`distinct: false`, `limit: null`, …), so a hand-built
+// tree has the same shape as a parsed one and prints with `print`.
+
+import type {
+  BinaryOp, Consumer, CountCmp, Expr, Follow, FollowDestination, LogicalOp, OpNode, OrderSpec, Query, SelectItem, Span,
+  Subquery, UnaryOp, Where,
+} from "./ast.ts";
+
+/** A fresh empty span (never shared: spans are mutable tuples). */
+export const span = (): Span => [0, 0];
+
+export const lit = (value: string | number | boolean | null): Expr => ({ kind: "lit", span: span(), value });
+export const ident = (name: string): Expr => ({ kind: "ident", span: span(), name });
+export const outer = (levels: number, name: string): Expr => ({ kind: "outer", span: span(), levels, name });
+export const binding = (index: number): Expr => ({ kind: "binding", span: span(), index });
+export const member = (recv: Expr, name: string): Expr => ({ kind: "member", span: span(), recv, name });
+/** `a.b.c` from a dotted path. */
+export const path = (first: string, ...rest: string[]): Expr => rest.reduce<Expr>((e, n) => member(e, n), ident(first));
+export const call = (recv: Expr | null, name: string, args: Expr[] = []): Expr => ({ kind: "call", span: span(), recv, name, args });
+export const unary = (op: UnaryOp, expr: Expr): Expr => ({ kind: "unary", span: span(), op, expr });
+/** `expr!` — the required value (SEMANTICS §5b). */
+export const required = (expr: Expr): Expr => ({ kind: "required", span: span(), expr });
+export const binary = (op: BinaryOp, left: Expr, right: Expr): Expr => ({ kind: "binary", span: span(), op, left, right });
+export const logical = (op: LogicalOp, left: Expr, right: Expr): Expr => ({ kind: "logical", span: span(), op, left, right });
+export const inOp = (left: Expr, right: Expr): Expr => ({ kind: "in", span: span(), left, right });
+export const range = (lo: Expr | null, hi: Expr | null, exclusiveEnd = false): Expr => ({ kind: "range", span: span(), lo, hi, exclusiveEnd });
+/** `(e1, e2, …)` — a tuple of two or more expressions (SEMANTICS §3b). */
+export const tuple = (items: Expr[]): Expr => ({ kind: "tuple", span: span(), items });
+
+export const scalar = (expr: Expr): Where => ({ kind: "scalar", span: span(), expr });
+export const and = (parts: Where[]): Where => ({ kind: "and", span: span(), parts });
+export const or = (parts: Where[]): Where => ({ kind: "or", span: span(), parts });
+export const not = (expr: Where): Where => ({ kind: "not", span: span(), expr });
+
+export const field = (name: string, expr: Expr, lift = 0): SelectItem => ({ kind: "field", span: span(), name, expr, lift });
+export const collect = (name: string, op: OpNode): SelectItem => ({ kind: "collect", span: span(), name, op });
+export const order = (expr: Expr, desc = false): OrderSpec => ({ kind: "order", span: span(), expr, desc });
+
+/** A block body; every clause defaults to empty/absent. */
+export function subquery(parts: Partial<Omit<Subquery, "kind" | "span">> = {}): Subquery {
+  return {
+    kind: "subquery", span: span(),
+    from: [], where: null, select: [], orderBy: null, follow: null, frontier: null, depth: null, values: false, limit: null, offset: null,
+    ...parts,
+  };
+}
+
+/** `<receiver> <op> [distinct] { sub } [<relop> N]`. */
+export function op(
+  receiver: Expr, consumer: Consumer, sub: Subquery = subquery(),
+  opts: { distinct?: boolean; countCmp?: CountCmp | null } = {},
+): OpNode {
+  return { kind: "op", span: span(), receiver, op: consumer, sub, countCmp: opts.countCmp ?? null, distinct: opts.distinct ?? false };
+}
+
+/** `follow [distinct] <destinations>`; a destination's `where`/`frontier`/`depth`
+ * belong to its block (`op(recv, "collect", subquery({ depth: 2 }))`). */
+export function follow(destinations: FollowDestination[], opts: { distinct?: boolean } = {}): Follow {
+  return { kind: "follow", span: span(), destinations, distinct: opts.distinct ?? false };
+}
+
+/** A top-level query over `source`; every other clause defaults to empty/absent
+ * and the consumer to `collect`. */
+export function query(source: Expr, parts: Partial<Omit<Query, "kind" | "span" | "source">> = {}): Query {
+  return {
+    kind: "query", span: span(), source,
+    from: [], where: null, select: [], orderBy: null, consumer: "collect", follow: null, frontier: null,
+    distinct: false, values: false, limit: null, offset: null,
+    ...parts,
+  };
+}

package/src/context.ts

@@ -1,8 +1,9 @@
 // The tier-2 seam: a DataContext binds OQX's query semantics to a concrete data
 // model. The engine never touches host objects directly — it asks the context to
 // resolve named roots, read properties/relations, coerce a relation result into
-// rows, compute identity (for `follow` dedup), and optionally supply custom
-// scalar functions/methods. This is what lets the same query semantics run over
+// rows (and say which objects are one row rather than a collection), name a
+// row's identity (`$key`: `follow` dedup, `distinct`, `is`), and optionally
+// supply custom scalar functions/methods. This is what lets the same query semantics run over
 // plain objects, a lazy ORM graph, or a remote API without changing the engine.
 //
 // (Performant execution over a real store is the tier-3 seam — see planner.ts —
@@ -28,6 +29,14 @@ export interface CallResult {
 export interface DataContext {
   /** Resolve a named root collection (the `from <name>` / directive receiver). */
   root(name: string): unknown;
+  /** The root scope's row — the host's root object: what `$it` is at the root
+   * scope and `^$it` from a top-level row (SEMANTICS §2, since 0.18), so
+   * `^$it.people` navigates it through `get` and `entries(^$it)` enumerates it.
+   * Bare names at the root still resolve through `root(name)`, so a host with
+   * lazy roots is unaffected. Optional: a context without it (or returning
+   * `undefined`) has no root row — `$it` at the root is absent, the pre-0.18
+   * behavior. `DefaultContext` returns its roots record. */
+  rootObject?(): unknown;
   /** Read a property/relation off a row: a bare identifier (`field`), a
    * `.field` segment, or a `^field` outer reference all come through here, each
    * against exactly the row of the scope it names. An absent property is
@@ -37,6 +46,13 @@ export interface DataContext {
   get(row: unknown, key: string): unknown;
   /** Coerce a relation/source value into rows (may be lazy). */
   toRows(value: unknown): Iterable<unknown>;
+  /** Optional: whether an object this context handed out in row position is
+   * ONE row — a record, not a collection (SEMANTICS §3, since 0.20) — so a block
+   * over it yields one result rather than a one-element list (`doc { title }`
+   * is a record; `docs { title }` a list). Asked only for non-array objects;
+   * absent, any non-iterable object is one row and any iterable (a `Set`, a
+   * lazy handle with `Symbol.iterator`) is a collection. */
+  isSingle?(value: unknown): boolean;
   /** Optional: a value this context handed out as a stand-in for a collection
    * it has not read yet (a lazy table handle), resolved to what it stands for.
    * The engine calls it on every value it is about to observe AS A VALUE — an
@@ -49,8 +65,15 @@ export interface DataContext {
    * seen by the language. Absent = identity; a context whose handle already
    * behaves as the collection (a `Proxy` over an array) needs none. */
   materialize?(value: unknown): unknown;
-  /** Identity of a row for `follow` cycle detection / dedup. */
-  identity(row: unknown): unknown;
+  /** Optional: the identity a row is known by — `$key` (SEMANTICS §16, since
+   * 0.20): what `follow` cycle detection, the per-step union, `follow distinct`,
+   * `distinct` over unprojected rows and `is` compare, and what reading `$key`
+   * on the row returns. Absent, a row's identity is its structural value (an
+   * entry's is its key either way). A store-backed context answers its row id. */
+  identityOf?(row: unknown): unknown;
+  /** @deprecated The pre-0.20 spelling of `identityOf`; read when `identityOf`
+   * is absent. Removed in the next minor. */
+  identity?(row: unknown): unknown;
   /** Optional custom free function; return `{ handled: false }` to defer. */
   callFunction?(name: string, args: unknown[]): CallResult;
   /** Optional custom method; return `{ handled: false }` to defer. */
@@ -82,9 +105,11 @@ export interface DefaultContextOptions {
 }
 
 /** The default context: ordinary JavaScript objects. Named roots come from a
- * plain `{ name: collection }` map; properties are OWN keys only (an array
- * exposes only its integer indices, a primitive has none); identity is `.id`
- * when present, else the row itself (the engine keys it structurally). */
+ * plain `{ name: collection }` map, which is also the root object (`^$it` from
+ * a top-level row); properties are OWN keys only (an array exposes only its
+ * integer indices, a primitive has none); it names no identity of its own, so a
+ * row's `$key` is its structural value (SEMANTICS §16) unless a query projects
+ * one (`$key: id`). */
 export class DefaultContext implements DataContext {
   private roots: Record<string, unknown>;
   readonly regexDialect: RegexDialect;
@@ -98,6 +123,10 @@ export class DefaultContext implements DataContext {
     return Object.hasOwn(this.roots, name) ? this.roots[name] : undefined;
   }
 
+  rootObject(): unknown {
+    return this.roots;
+  }
+
   get(row: unknown, key: string): unknown {
     if (row == null || typeof row !== "object") return undefined;
     if (Array.isArray(row)) return isIndexKey(key) ? row[Number(key)] : undefined;
@@ -108,11 +137,6 @@ export class DefaultContext implements DataContext {
     return coerceCollection(value);
   }
 
-  identity(row: unknown): unknown {
-    if (row != null && typeof row === "object" && "id" in row) return (row as Record<string, unknown>).id;
-    return row;
-  }
-
   callFunction(name: string, args: unknown[]): CallResult {
     const fn = Object.hasOwn(BUILTIN_FUNCTIONS, name) ? BUILTIN_FUNCTIONS[name] : undefined;
     return fn ? { handled: true, value: fn(args) } : { handled: false };