@omgbase/oqx 0.18.0 → 0.21.0

package/src/print.ts

@@ -2,7 +2,8 @@
 // Single spaces, double-quoted strings with GRAMMAR §1 escapes, the minimal
 // parentheses the precedence table (GRAMMAR §4) needs, `select` written at the
 // top level, the connectives as the words `and` / `or` (since 0.18; `!` stays
-// `!`), every option in its canonical position. The law both spec runners
+// `!`), every clause in its canonical position (a destination block's
+// `frontier` and `depth` after its `where`, since 0.20). The law both spec runners
 // enforce over every fixture query:
 //
 //   strip(parse(print(parse(q)))) ≡ strip(parse(q))
@@ -65,7 +66,7 @@ const OR = 1, AND = 2, CMP = 3, RANGE = 4, ADD = 5, MUL = 6, UNARY = 7, POSTFIX
 
 function prec(e: Expr): number {
   switch (e.kind) {
-    case "lit": case "ident": case "outer": case "binding": return PRIMARY;
+    case "lit": case "ident": case "outer": case "binding": case "tuple": case "template": return PRIMARY;
     case "member": case "call": case "required": case "op": return POSTFIX;
     case "unary": return UNARY;
     case "binary": return e.op === "+" || e.op === "-" ? ADD : e.op === "*" || e.op === "/" || e.op === "%" ? MUL : CMP;
@@ -113,14 +114,18 @@ function query(q: Query): Out {
   return cat(expr(q.source), ` ${q.consumer}${q.distinct ? " distinct" : ""} `, braces(body(q)));
 }
 
-type Body = Pick<Subquery, "select" | "values" | "from" | "where" | "follow" | "orderBy" | "limit" | "offset">;
+type Body = Pick<Subquery, "select" | "values" | "from" | "where" | "follow" | "orderBy" | "limit" | "offset">
+  & Partial<Pick<Subquery, "frontier" | "depth">>;
 
 // The clauses after `from` (a query) or after the projection (a block): the
-// fixed clause order, each present clause once.
+// fixed clause order, each present clause once. `frontier`/`depth` exist only
+// on a follow destination block's body (a `Query` has neither).
 function tail(b: Omit<Body, "select" | "values">): Out[] {
   const out: Out[] = [];
   for (const e of b.from) out.push(cat("from ", expr(e)));
   if (b.where) out.push(cat("where ", where(b.where)));
+  if (b.frontier) out.push(cat("frontier ", expr(b.frontier)));
+  if (b.depth != null) out.push([`depth ${number(b.depth)}`]);
   if (b.follow) out.push(follow(b.follow));
   if (b.orderBy && b.orderBy.length > 0) out.push(cat("order by ", join(b.orderBy.map(order), ", ")));
   if (b.limit) out.push(cat("limit ", expr(b.limit)));
@@ -170,12 +175,7 @@ function op(o: OpNode): Out {
 
 function follow(f: Follow): Out {
   const dests = join(f.destinations.map((d) => (d.kind === "op" ? op(d) : expr(d))), ", ");
-  const opts: Out[] = [];
-  if (f.where) opts.push(cat("where ", expr(f.where)));
-  if (f.frontier) opts.push(cat("frontier ", expr(f.frontier)));
-  if (f.depth !== null) opts.push([`depth ${f.depth}`]);
-  if (f.by) opts.push(cat("by ", expr(f.by)));
-  return cat(`follow${f.distinct ? " distinct" : ""} `, dests, opts.length > 0 ? cat(" { ", join(opts, " "), " }") : "");
+  return cat(`follow${f.distinct ? " distinct" : ""} `, dests);
 }
 
 // ---- where ------------------------------------------------------------------
@@ -229,6 +229,12 @@ function expr(e: Expr): Out {
     case "in": return cat(operand(e.left, CMP + 1), " in ", operand(e.right, CMP + 1));
     case "range":
       return cat(e.lo ? operand(e.lo, ADD) : "", e.exclusiveEnd ? "..." : "..", e.hi ? operand(e.hi, ADD) : "");
+    // A tuple is self-delimiting; its elements are full expressions.
+    case "tuple": return cat("(", join(e.items.map(expr), ", "), ")");
+    // A template literal prints as one: its text with the GRAMMAR §1 escapes
+    // (`` \` ``, `\\`, `\$` before a `{`, and the control characters), each
+    // interpolation as `${…}` around the full expression.
+    case "template": return cat("`", ...e.parts.map((p) => (typeof p === "string" ? templateText(p) : cat("${", expr(p), "}"))), "`");
   }
 }
 
@@ -262,13 +268,35 @@ function quote(s: string): string {
   for (const ch of s) {
     switch (ch) {
       case '"': out += '\\"'; break;
-      case "\\": out += "\\\\"; break;
-      case "\n": out += "\\n"; break;
-      case "\t": out += "\\t"; break;
-      case "\r": out += "\\r"; break;
-      case "\0": out += "\\0"; break;
-      default: out += ch;
+      default: out += escapeChar(ch);
     }
   }
   return out + '"';
 }
+
+/** The text of a template literal part, escaped so it re-lexes to itself: the
+ * backtick and the backslash, the control characters as in a string, and a `$`
+ * that a `{` follows (which would otherwise open an interpolation). */
+function templateText(s: string): string {
+  const cps = Array.from(s);
+  let out = "";
+  for (let i = 0; i < cps.length; i++) {
+    const ch = cps[i]!;
+    if (ch === "`") out += "\\`";
+    else if (ch === "$" && cps[i + 1] === "{") out += "\\$";
+    else out += escapeChar(ch);
+  }
+  return out;
+}
+
+/** The escapes a string literal and a template literal share (GRAMMAR §1). */
+function escapeChar(ch: string): string {
+  switch (ch) {
+    case "\\": return "\\\\";
+    case "\n": return "\\n";
+    case "\t": return "\\t";
+    case "\r": return "\\r";
+    case "\0": return "\\0";
+    default: return ch;
+  }
+}

package/src/resolve.ts

@@ -61,12 +61,16 @@ function resolveBody<T extends Query | Subquery>(node: T, fail: Fail): T {
   });
   const limit = node.limit === null ? null : resolveExpr(node.limit, fail);
   const offset = node.offset === null ? null : resolveExpr(node.offset, fail);
+  // `frontier` (0.20) is not rewritten against the select: a destination
+  // block's reads the occurrence, a body's reads the seed row — not a projected
+  // record (like `order by`).
+  const frontier = node.frontier === null ? null : resolveExpr(node.frontier, fail);
   const source = node.kind === "query" ? resolveExpr(node.source, fail) : null;
   const same = where2 === node.where && select === node.select && follow === node.follow && from === node.from
-    && orderBy === node.orderBy && limit === node.limit && offset === node.offset
+    && orderBy === node.orderBy && limit === node.limit && offset === node.offset && frontier === node.frontier
     && (node.kind !== "query" || source === node.source);
   if (same) return node;
-  const out = { ...node, where: where2, select, follow, from, orderBy, limit, offset };
+  const out = { ...node, where: where2, select, follow, frontier, from, orderBy, limit, offset };
   if (node.kind === "query") (out as Query).source = source!;
   return out;
 }
@@ -79,11 +83,7 @@ function resolveOp(op: OpNode, fail: Fail): OpNode {
 
 function resolveFollow(f: Follow, fail: Fail): Follow {
   const destinations = mapSame(f.destinations, (d: FollowDestination) => (d.kind === "op" ? resolveOp(d, fail) : resolveExpr(d, fail)));
-  const where = f.where === null ? null : resolveExpr(f.where, fail);
-  const frontier = f.frontier === null ? null : resolveExpr(f.frontier, fail);
-  const by = f.by === null ? null : resolveExpr(f.by, fail);
-  if (destinations === f.destinations && where === f.where && frontier === f.frontier && by === f.by) return f;
-  return { ...f, destinations, where, frontier, by };
+  return destinations === f.destinations ? f : { ...f, destinations };
 }
 
 // Nested blocks inside a where tree are their own scopes: resolve each against
@@ -137,6 +137,14 @@ function mapExpr(e: Expr, f: (e: Expr) => Expr | null): Expr {
       const hi = e.hi ? go(e.hi) : null;
       return lo === e.lo && hi === e.hi ? e : { ...e, lo, hi };
     }
+    case "tuple": {
+      const items = mapSame(e.items, go);
+      return items === e.items ? e : { ...e, items };
+    }
+    case "template": { // the text parts are strings; only the interpolations are expressions
+      const parts = mapSame(e.parts, (p) => (typeof p === "string" ? p : go(p)));
+      return parts === e.parts ? e : { ...e, parts };
+    }
     case "op": { // the receiver is read in this scope; the block is its own scope
       const receiver = go(e.receiver);
       return receiver === e.receiver ? e : { ...e, receiver };

package/src/version.ts

@@ -1,4 +1,4 @@
 /** The OQX language version (`spec/oqx/VERSION`, `major.minor`) this implementation
  * conforms to — distinct from the package's own semver, whose `major.minor` it
  * equals. Stamped on every `toJSON` document. */
-export const LANGUAGE_VERSION = "0.18";
+export const LANGUAGE_VERSION = "0.21";

package/src/walk.ts

@@ -14,13 +14,15 @@ import { LANGUAGE_VERSION } from "./version.ts";
  * The root node has no clause (`null`). */
 export type Clause =
   | "source" | "from" | "where" | "select" | "orderBy" | "limit" | "offset"
-  | "follow" | "follow.destination" | "follow.where" | "follow.frontier" | "follow.by";
+  | "follow" | "follow.destination" | "follow.frontier";
 
 /** Where a visited node sits. `depth` is the scope depth at which the node is
  * evaluated (0 = the root scope: a top-level `source`, `limit`, `offset`; 1 =
  * a top-level row: its `where`, `select`, `order by`, `from` re-projections and
- * `follow`; a block's rows are one deeper than the block's receiver; a follow
- * `where` is one deeper than the frontier row it tests successors of). */
+ * `follow`; a block's rows are one deeper than the block's receiver — a follow
+ * destination block's `where` therefore one deeper than the frontier row —
+ * and a destination block's `frontier` one level out of its rows, under the
+ * walk's enclosing scope). */
 export interface VisitContext {
   /** The ancestors of the node, root first (empty for the root). */
   readonly path: readonly AstNode[];
@@ -52,6 +54,8 @@ export const CHILDREN: { readonly [K in AstKind]: readonly ChildKey[] } = {
     { key: "source", clause: "source" },
     { key: "from", clause: "from", depth: 1 },
     { key: "where", clause: "where", depth: 1 },
+    // The body's `frontier` (0.20) reads each seed in the row scope, like `where`.
+    { key: "frontier", clause: "follow.frontier", depth: 1 },
     { key: "follow", clause: "follow", depth: 1 },
     { key: "orderBy", clause: "orderBy", depth: 1 },
     { key: "limit", clause: "limit" },
@@ -61,18 +65,18 @@ export const CHILDREN: { readonly [K in AstKind]: readonly ChildKey[] } = {
     { key: "select", clause: "select" },
     { key: "from", clause: "from" },
     { key: "where", clause: "where" },
+    // A destination block's `frontier` reads the occurrence under the walk's
+    // enclosing scope — one level OUT of the block's rows (SEMANTICS §20); any
+    // other block's reads its seeds in the row scope, like `where`
+    // (`childDepth` tells the two apart by the block's position).
+    { key: "frontier", clause: "follow.frontier", depth: -1 },
     { key: "follow", clause: "follow" },
     { key: "orderBy", clause: "orderBy" },
     { key: "limit", clause: "limit" },
     { key: "offset", clause: "offset" },
   ],
   op: [{ key: "receiver" }, { key: "sub", depth: 1 }],
-  follow: [
-    { key: "destinations", clause: "follow.destination" },
-    { key: "where", clause: "follow.where", depth: 1 },
-    { key: "frontier", clause: "follow.frontier" },
-    { key: "by", clause: "follow.by" },
-  ],
+  follow: [{ key: "destinations", clause: "follow.destination" }],
   order: [{ key: "expr" }],
   field: [{ key: "expr" }],
   collect: [{ key: "op" }],
@@ -92,14 +96,35 @@ export const CHILDREN: { readonly [K in AstKind]: readonly ChildKey[] } = {
   logical: [{ key: "left" }, { key: "right" }],
   in: [{ key: "left" }, { key: "right" }],
   range: [{ key: "lo" }, { key: "hi" }],
+  tuple: [{ key: "items" }],
+  // The interpolations; the text parts between them are strings, not nodes.
+  template: [{ key: "parts" }],
 };
 
-type Slot = AstNode | AstNode[] | null;
+/** A child slot's value: a node, a list of nodes (a template's `parts` also
+ * holds its text strings, which the walks skip), or `null`. */
+type Slot = AstNode | (AstNode | string)[] | null;
 
 function slot(node: AstNode, key: string): Slot {
   return (node as unknown as Record<string, Slot>)[key] ?? null;
 }
 
+/** A block is a follow destination block when its `op` is a direct destination
+ * of a `follow` node. `path` is the ancestors with the block itself last. */
+function isDestinationBlock(path: readonly AstNode[]): boolean {
+  const op = path[path.length - 2];
+  const owner = path[path.length - 3];
+  return op?.kind === "op" && owner?.kind === "follow";
+}
+
+/** How much deeper a child's scope is: the table's value, except a block's
+ * `frontier`, which is one level OUT only for a destination block (the walk's
+ * enclosing scope) and the row scope itself for a body with its own `follow`. */
+function childDepth(node: AstNode, child: ChildKey, path: readonly AstNode[]): number {
+  if (node.kind === "subquery" && child.key === "frontier" && !isDestinationBlock(path)) return 0;
+  return child.depth ?? 0;
+}
+
 /** Walk a tree depth-first in canonical source order. */
 export function visit(root: AstNode, visitor: Visitor): void {
   const path: AstNode[] = [];
@@ -112,8 +137,8 @@ export function visit(root: AstNode, visitor: Visitor): void {
         const v = slot(node, child.key);
         if (v === null) continue;
         const c = child.clause ?? clause;
-        const d = depth + (child.depth ?? 0);
-        if (Array.isArray(v)) for (const x of v) go(x, c, d);
+        const d = depth + childDepth(node, child, path);
+        if (Array.isArray(v)) { for (const x of v) if (typeof x !== "string") go(x, c, d); }
         else go(v, c, d);
       }
       path.pop();
@@ -137,11 +162,11 @@ export function transform<T extends Query | Subquery>(root: T, f: (expr: Expr, c
       const v = slot(node, child.key);
       if (v === null) continue;
       const c = child.clause ?? clause;
-      const d = depth + (child.depth ?? 0);
+      const d = depth + childDepth(node, child, path);
       let next: Slot;
       if (Array.isArray(v)) {
         let changed = false;
-        const mapped = v.map((x) => { const y = go(x, c, d); if (y !== x) changed = true; return y; });
+        const mapped = v.map((x) => { if (typeof x === "string") return x; const y = go(x, c, d); if (y !== x) changed = true; return y; });
         next = changed ? mapped : v;
       } else next = go(v, c, d);
       if (next !== v) out = { ...out, [child.key]: next } as AstNode;