@omgbase/oqx 0.6.0 → 0.8.0

package/src/engine.ts

@@ -6,9 +6,14 @@
 // `first`/`single` stop early when the result is unordered; `count` never
 // materializes rows; and within an `&&` the cheap scalar leaves are evaluated
 // before expensive consumer-op leaves (which each drive a nested traversal).
+//
+// Name resolution is strictly lexical and LOCAL: a bare identifier is read from
+// the current scope only, and an enclosing scope is reached solely through an
+// explicit `^name` (exactly one scope out per caret). There is no implicit
+// fall-through from an inner scope to an outer one — see `resolveIn`.
 
 import type {
-  Query, Where, Expr, OpNode, SelectItem, OrderSpec, Follow,
+  Query, Where, Expr, OpNode, SelectItem, OrderSpec, Follow, Subquery,
 } from "./ast.ts";
 import type { DataContext } from "./context.ts";
 import { DefaultContext } from "./context.ts";
@@ -30,6 +35,11 @@ export interface Engine {
   run(query: Query, bindings: readonly unknown[]): OqxResult;
 }
 
+// One query scope: the row under evaluation plus the chain of enclosing scopes
+// that `^` walks. The root scope (parent === null) has no row; its names are the
+// context's named roots. `lifts` holds values bound INTO this scope by `^name:`
+// items in nested blocks; `meta` holds recursion intrinsics for a follow
+// occurrence.
 interface Scope {
   row: unknown;
   parent: Scope | null;
@@ -41,6 +51,10 @@ interface Scope {
 const RECUR = new Set(["$depth", "$stop", "$leaf", "$frontier", "$ordinal"]);
 const HARD_DEPTH_CAP = 8;
 
+// What a scope projects to: the select list plus the `values` mode flag. Both
+// `Query` and `Subquery` carry this shape.
+type Projection = Pick<Subquery, "select" | "values">;
+
 export class InMemoryEngine implements Engine {
   private ctx: DataContext;
 
@@ -81,8 +95,8 @@ export class InMemoryEngine implements Engine {
       }
     }
     this.sortScopes(kept, query.orderBy);
-    if (query.distinct) kept = this.dedupByProjection(kept, query.select);
-    return this.shape(query.consumer, kept, query.select);
+    if (query.distinct) kept = this.dedupByProjection(kept, query);
+    return this.shape(query.consumer, kept, query);
   }
 
   // A where match that needs no lift capture (exists/count fast paths).
@@ -108,20 +122,20 @@ export class InMemoryEngine implements Engine {
     let scopes: Scope[] = occ.map((o) => ({ row: o.row, parent: root, bindings: root.bindings, lifts: {}, meta: o.meta }));
     if (post) scopes = scopes.filter((s) => this.evalWhere(post, s));
     this.sortScopes(scopes, query.orderBy);
-    if (query.distinct) scopes = this.dedupByProjection(scopes, query.select);
-    return this.shape(query.consumer, scopes, query.select);
+    if (query.distinct) scopes = this.dedupByProjection(scopes, query);
+    return this.shape(query.consumer, scopes, query);
   }
 
   // Dedup scopes by their PROJECTED value (`distinct`): keep the first scope per
   // distinct projection, preserving order. An empty projection dedups by row
   // identity (so `count distinct { }` counts distinct rows).
-  private dedupByProjection(scopes: Scope[], select: SelectItem[]): Scope[] {
+  private dedupByProjection(scopes: Scope[], proj: Projection): Scope[] {
     const seen = new Set<string>();
     const out: Scope[] = [];
     for (const s of scopes) {
-      const key = select.length === 0
+      const key = proj.select.length === 0
         ? `i:${String(this.ctx.identity(s.row))}`
-        : `p:${stableStringify(this.projectRow(select, s))}`;
+        : `p:${stableStringify(this.projectRow(proj, s))}`;
       if (seen.has(key)) continue;
       seen.add(key);
       out.push(s);
@@ -203,27 +217,33 @@ export class InMemoryEngine implements Engine {
 
   // ---- consumer shaping -----------------------------------------------------
 
-  private shape(consumer: Query["consumer"], scopes: Scope[], select: SelectItem[]): OqxResult {
+  private shape(consumer: Query["consumer"], scopes: Scope[], proj: Projection): OqxResult {
     switch (consumer) {
       case "exists": return { consumer, exists: scopes.length > 0 };
       case "count": return { consumer, count: scopes.length };
-      case "collect": return { consumer, rows: scopes.map((s) => this.projectRow(select, s)) };
-      case "first": return { consumer, row: scopes.length > 0 ? this.projectRow(select, scopes[0]!) : null };
+      case "collect": return { consumer, rows: scopes.map((s) => this.projectRow(proj, s)) };
+      case "first": return { consumer, row: scopes.length > 0 ? this.projectRow(proj, scopes[0]!) : null };
       case "single":
         if (scopes.length > 1) throw new OqxError(`single { … } matched ${scopes.length} rows; use first { … } for zero-or-one`, "eval");
-        return { consumer, row: scopes.length > 0 ? this.projectRow(select, scopes[0]!) : null };
+        return { consumer, row: scopes.length > 0 ? this.projectRow(proj, scopes[0]!) : null };
     }
   }
 
-  private projectRow(select: SelectItem[], scope: Scope): unknown {
+  // The per-row result: the raw row (empty projection), the single item's value
+  // itself (`values` mode), or a `{ name: value }` record.
+  private projectRow(proj: Projection, scope: Scope): unknown {
+    const { select } = proj;
     if (select.length === 0) return scope.row;
+    if (proj.values) return this.itemValue(select[0]!, scope);
     const out: Record<string, unknown> = {};
-    for (const item of select) {
-      out[item.name] = item.kind === "field" ? this.evalExpr(item.expr, scope) : this.evalCollectValue(item.op, scope);
-    }
+    for (const item of select) out[item.name] = this.itemValue(item, scope);
     return out;
   }
 
+  private itemValue(item: SelectItem, scope: Scope): unknown {
+    return item.kind === "field" ? this.evalExpr(item.expr, scope) : this.evalCollectValue(item.op, scope);
+  }
+
   // ---- where evaluation -----------------------------------------------------
 
   private evalWhere(w: Where, scope: Scope): boolean {
@@ -261,7 +281,7 @@ export class InMemoryEngine implements Engine {
     }
     if (op.op === "count") {
       let rows = this.matchRows(op, scope);
-      if (op.distinct) rows = this.dedupByProjection(rows, op.sub.select);
+      if (op.distinct) rows = this.dedupByProjection(rows, op.sub);
       const n = rows.length;
       return op.countCmp ? compareCount(n, op.countCmp) : n > 0;
     }
@@ -300,13 +320,13 @@ export class InMemoryEngine implements Engine {
       scopes = this.matchRows(op, scope);
     }
     this.sortScopes(scopes, sub.orderBy);
-    if (op.distinct) scopes = this.dedupByProjection(scopes, sub.select);
+    if (op.distinct) scopes = this.dedupByProjection(scopes, sub);
     switch (op.op) {
-      case "collect": return scopes.map((s) => this.projectRow(sub.select, s));
-      case "first": return scopes.length > 0 ? this.projectRow(sub.select, scopes[0]!) : null;
+      case "collect": return scopes.map((s) => this.projectRow(sub, s));
+      case "first": return scopes.length > 0 ? this.projectRow(sub, scopes[0]!) : null;
       case "single":
         if (scopes.length > 1) throw new OqxError(`single { … } for '${describeReceiver(op.receiver)}' matched ${scopes.length} rows`, "eval");
-        return scopes.length > 0 ? this.projectRow(sub.select, scopes[0]!) : null;
+        return scopes.length > 0 ? this.projectRow(sub, scopes[0]!) : null;
       default: throw new OqxError(`${op.op} { … } is not valid in select position`, "eval");
     }
   }
@@ -341,11 +361,13 @@ export class InMemoryEngine implements Engine {
     switch (e.kind) {
       case "lit": return e.value;
       case "binding": return scope.bindings[e.index];
-      case "ident": return this.resolveFrom(e.name, scope);
+      case "ident": return this.resolveIn(e.name, scope);
       case "outer": {
+        // `^name` reads from EXACTLY `levels` scopes out — the target scope is
+        // resolved locally, never climbed further. Past the root it is absent.
         let s: Scope | null = scope;
         for (let i = 0; i < e.levels && s; i++) s = s.parent;
-        return s ? this.resolveFrom(e.name, s) : undefined;
+        return s ? this.resolveIn(e.name, s) : undefined;
       }
       case "member": {
         const r = this.evalExpr(e.recv, scope);
@@ -377,28 +399,25 @@ export class InMemoryEngine implements Engine {
     }
   }
 
-  // Resolve a bare name starting at `start` and climbing enclosing scopes: `^`
-  // outer references reuse this after skipping the requested number of scopes.
-  private resolveFrom(name: string, start: Scope): unknown {
-    if (RECUR.has(name)) {
-      for (let s: Scope | null = start; s; s = s.parent) if (s.meta && name in s.meta) return s.meta[name];
-      return undefined;
-    }
-    for (let s: Scope | null = start; s; s = s.parent) {
-      if (s.lifts && name in s.lifts) return s.lifts[name];
-      if (s.parent === null) {
-        const v = this.ctx.root(name);
-        if (v !== undefined) return v;
-      } else if (this.has(s.row, name)) {
-        return this.ctx.get(s.row, name);
-      }
-    }
-    return undefined;
-  }
-
-  private has(row: unknown, name: string): boolean {
-    if (this.ctx.has) return this.ctx.has(row, name);
-    return row != null && typeof row === "object" && name in (row as object);
+  // Resolve a name against ONE scope — never its ancestors. A scope provides,
+  // in order: `$value` (the scope's row itself — the current item, whatever its
+  // type, so scalar collections are queryable; absent at the root, which has no
+  // row); the recursion intrinsics (`$depth`, …) when it is a follow occurrence;
+  // values lifted into it by `^name:` items; then either the row's own property
+  // or, for the root scope (no row), the context's named roots.
+  //
+  // A name the scope lacks is simply absent (undefined). It does NOT fall
+  // through to an enclosing scope, so a query's meaning never depends on which
+  // properties an inner row happens to have: adding a same-named property to an
+  // inner row cannot capture an outer reference, and an outer reference is
+  // always spelled explicitly as `^name`. Present-but-falsy values (null, false,
+  // 0, "") need no special case — there is no "absent, so look outward" rule.
+  private resolveIn(name: string, scope: Scope): unknown {
+    if (name === "$value") return scope.parent === null ? undefined : scope.row;
+    if (RECUR.has(name)) return scope.meta ? scope.meta[name] : undefined;
+    if (scope.lifts && name in scope.lifts) return scope.lifts[name];
+    if (scope.parent === null) return this.ctx.root(name);
+    return this.ctx.get(scope.row, name);
   }
 
   private evalCall(e: Extract<Expr, { kind: "call" }>, scope: Scope): unknown {

package/src/parser.ts

@@ -25,7 +25,7 @@ const CONSUMERS = new Set<string>(["collect", "exists", "count", "first", "singl
 // before them rather than consume them as its high bound.
 const CLAUSE_WORDS = new Set<string>([
   "collect", "exists", "count", "first", "single",
-  "order", "by", "asc", "desc", "follow", "distinct", "frontier", "depth", "in",
+  "order", "by", "asc", "desc", "follow", "distinct", "frontier", "depth", "in", "values",
 ]);
 const RELOPS = new Set<string>(["==", "!=", "<", "<=", ">", ">="]);
 const CMP_OPS = new Set<string>(["==", "!=", "<", "<=", ">", ">="]);
@@ -49,6 +49,7 @@ interface BodyClauses {
   orderBy: OrderSpec[] | null;
   follow: Follow | null;
   distinct: boolean;
+  values: boolean;
 }
 
 class Parser {
@@ -89,6 +90,7 @@ class Parser {
         consumer: directive.op,
         follow: directive.sub.follow,
         distinct: directive.distinct ?? false,
+        values: directive.sub.values ?? false,
       };
     }
     if (directive) this.fail(`unexpected ${this.tokDesc()} after the top-level directive`);
@@ -108,6 +110,7 @@ class Parser {
       consumer: "collect",
       follow: body.follow,
       distinct: body.distinct,
+      values: body.values,
     };
   }
 
@@ -124,6 +127,7 @@ class Parser {
     let orderBy: OrderSpec[] | null = null;
     let follow: Follow | null = null;
     let distinct = false;
+    let values = false;
     let sawWhere = false, sawSelect = false, sawOrder = false;
 
     while (!this.at("eof") && !this.at("rbrace")) {
@@ -148,7 +152,7 @@ class Parser {
         if (sawSelect) this.fail("duplicate projection");
         sawSelect = true;
         if (this.at("kw")) { this.next(); if (this.at("ident", "distinct")) { this.next(); distinct = true; } } // consume `select` + optional `distinct`; a leading `^` is part of the item
-        select = this.parseSelectItems();
+        ({ items: select, values } = this.parseProjection());
         continue;
       }
       if (orderByAllowed && this.atOrderBy()) {
@@ -167,12 +171,12 @@ class Parser {
       if (this.at("ident") || this.at("binding")) {
         if (sawSelect) this.fail("duplicate projection (an implicit select cannot follow a `select`)");
         sawSelect = true;
-        select = this.parseSelectItems();
+        ({ items: select, values } = this.parseProjection());
         continue;
       }
       this.fail(`unexpected ${this.tokDesc()} — expected from/where/select${orderByAllowed ? "/order by" : ""}/follow`);
     }
-    return { froms, where, select, orderBy, follow, distinct };
+    return { froms, where, select, orderBy, follow, distinct, values };
   }
 
   // Decide, by syntactic shape only, whether a leading unkeyworded run is a
@@ -263,15 +267,28 @@ class Parser {
     return follow;
   }
 
-  // A receiver/source: a `${…}` binding, or a dotted identifier navigation chain.
+  // A receiver/source: a `${…}` binding, or a dotted identifier navigation chain
+  // whose head may be an outer reference (`^rel`, `^^root.rel`) — since a bare
+  // name is the current row's own property, an enclosing row's relation or a
+  // named root is only reachable as a receiver through `^`.
   private parseReceiver(): Expr {
     if (this.at("binding")) return { kind: "binding", index: this.next().index! };
+    const levels = this.parseCarets();
     if (!this.at("ident")) this.fail("expected a collection navigation (a property/relation name)");
-    return this.parseNavFrom(this.next()).expr;
+    return this.parseNavFrom(this.next(), levels).expr;
   }
 
-  private parseNavFrom(head: Token): { expr: Expr; name: string } {
-    let expr: Expr = { kind: "ident", name: head.value };
+  // Consume a run of `^` and return its length (0 when there is none).
+  private parseCarets(): number {
+    let levels = 0;
+    while (this.at("caret")) { this.next(); levels++; }
+    return levels;
+  }
+
+  // A dotted navigation chain from `head`; `levels` > 0 makes the head an outer
+  // reference read exactly that many scopes out.
+  private parseNavFrom(head: Token, levels = 0): { expr: Expr; name: string } {
+    let expr: Expr = levels > 0 ? { kind: "outer", levels, name: head.value } : { kind: "ident", name: head.value };
     let name = head.value;
     while (this.at("dot")) {
       this.next();
@@ -283,21 +300,36 @@ class Parser {
   }
 
   // ---- select ---------------------------------------------------------------
-  private parseSelectItems(): SelectItem[] {
+  // A projection list, optionally followed by the `values` mode word. Under
+  // `values` the list must be exactly one item, which need not be named: the
+  // row's result IS that value (no `{ name: value }` record), so a name would be
+  // meaningless. Without `values`, every item needs a key — a bare/dotted
+  // navigation supplies its own (the last segment); any other expression must be
+  // aliased (`name: expr`).
+  private parseProjection(): { items: SelectItem[]; values: boolean } {
     const items = [this.parseSelectItem()];
     while (this.at("comma")) { this.next(); items.push(this.parseSelectItem()); }
-    return items;
+    let values = false;
+    if (this.at("ident", "values")) {
+      this.next();
+      values = true;
+      if (items.length !== 1) this.fail("`values` projects exactly one expression (got " + items.length + ")");
+      const only = items[0]!;
+      if (only.kind === "field" && only.lift > 0) this.fail("a lift (^name: …) cannot be combined with `values`");
+    } else {
+      for (const it of items) {
+        if (it.name === "") this.fail("a projection item that is not a plain name needs an alias (`name: expr`) unless it is followed by `values`");
+      }
+    }
+    return { items, values };
   }
 
   private parseSelectItem(): SelectItem {
     // Leading `^`s mark a lift; the count is how many scopes out it binds.
-    let lift = 0;
-    while (this.at("caret")) { this.next(); lift++; }
-    if (!this.at("ident")) this.fail("expected a projection name");
-    const nameTok = this.next();
-    if (this.at("colon")) {
-      this.next();
-      const name = nameTok.value;
+    const lift = this.parseCarets();
+    if (this.at("ident") && this.peekAt(1)?.type === "colon") {
+      const name = this.next().value;
+      this.next(); // ':'
       const op = this.tryOp();
       if (op) {
         if (op.op !== "collect" && op.op !== "first" && op.op !== "single") {
@@ -309,9 +341,12 @@ class Parser {
       const expr = this.parseValueExpr();
       return { kind: "field", name, expr, lift };
     }
-    // bare/dotted projection: key defaults to the last navigation segment.
-    const { expr, name } = this.parseNavFrom(nameTok);
-    return { kind: "field", name, expr, lift };
+    if (!this.at("ident") && !this.canStartValue()) this.fail("expected a projection name");
+    // Unaliased item: a bare/dotted navigation keys by its last segment; any
+    // other expression is unnamed ("") — legal only under `values` (checked by
+    // parseProjection, which sees the whole list).
+    const expr = this.parseValueExpr();
+    return { kind: "field", name: navKey(expr) ?? "", expr, lift };
   }
 
   // ---- order by -------------------------------------------------------------
@@ -393,8 +428,11 @@ class Parser {
     const start = this.pos;
     let receiver: Expr;
     if (this.at("binding")) receiver = { kind: "binding", index: this.next().index! };
-    else if (this.at("ident")) receiver = this.parseNavFrom(this.next()).expr;
-    else return null;
+    else if (this.at("ident") || this.at("caret")) {
+      const levels = this.parseCarets();
+      if (!this.at("ident")) { this.pos = start; return null; }
+      receiver = this.parseNavFrom(this.next(), levels).expr;
+    } else return null;
 
     if (this.at("ident") && CONSUMERS.has(this.peek().value)) {
       const after = this.peekAt(1);
@@ -418,7 +456,10 @@ class Parser {
 
   private parseSubquery(): { sub: Subquery; distinct: boolean } {
     const body = this.parseBody(true);
-    return { sub: { from: body.froms, where: body.where, select: body.select, orderBy: body.orderBy, follow: body.follow }, distinct: body.distinct };
+    return {
+      sub: { from: body.froms, where: body.where, select: body.select, orderBy: body.orderBy, follow: body.follow, values: body.values },
+      distinct: body.distinct,
+    };
   }
 
   // ---- expression Pratt parser ----------------------------------------------
@@ -548,8 +589,7 @@ class Parser {
     // expression position, `^` reads an enclosing row's field even when the
     // current row shadows the name.)
     if (t.type === "caret") {
-      let levels = 0;
-      while (this.at("caret")) { this.next(); levels++; }
+      const levels = this.parseCarets();
       if (!this.at("ident")) this.fail("expected an identifier after '^' (an outer reference)");
       return { kind: "outer", levels, name: this.next().value };
     }
@@ -573,3 +613,14 @@ class Parser {
     this.fail(`unexpected ${this.tokDesc()} — expected a value`);
   }
 }
+
+// The default key of an unaliased projection item: the last segment of a bare /
+// dotted / outer navigation (`name`, `meta.slug` → "slug", `^name`), else null.
+function navKey(e: Expr): string | null {
+  switch (e.kind) {
+    case "ident": return e.name;
+    case "outer": return e.name;
+    case "member": return e.name;
+    default: return null;
+  }
+}

package/src/plan.ts

@@ -8,6 +8,13 @@
 // Deliberately conservative: only positive scalar leaves are pushable. Consumer
 // ops (exists/count/collect), negation, and disjunction stay residual — an
 // adapter that wants to push those can special-case them itself.
+//
+// Because a bare identifier resolves against the current row ONLY (it never
+// climbs to an enclosing scope or a named root), an `ident` in a top-level
+// `where` is unambiguously a column of the scanned rows and is safe to push. An
+// `outer` (`^name`) reference is not a row column and stays residual, and so is
+// the `$value` intrinsic (the row itself, not one of its columns) — adapters
+// gate idents on their known column set, which never includes it.
 
 import type { Query, Where, Expr } from "./ast.ts";
 
@@ -49,7 +56,8 @@ export function constValue(e: Expr, params: readonly unknown[]): unknown {
   throw new Error("constValue: not a constant expression");
 }
 
-/** Recognize `field == const` / `const == field` (field is a bare row column). */
+/** Recognize `field == const` / `const == field` (a bare identifier is always a
+ * column of the current row — see the module note). */
 export function asEquality(e: Expr): { field: string; value: Expr } | null {
   if (e.kind !== "binary" || e.op !== "==") return null;
   if (e.left.kind === "ident" && isConst(e.right)) return { field: e.left.name, value: e.right };