@omgbase/oqx 0.23.0 → 0.25.0

package/src/references.ts

@@ -25,7 +25,11 @@
 //     (`target.contains("x")` references `target`); a name a nested block
 //     LIFTS onto a scope (`^open: value`, SEMANTICS §19) is a binding of that
 //     scope, so reading it there (`select open`, `^open` from deeper) is not a
-//     reference either;
+//     reference either — and neither is a name a `flatten` bound (0.25,
+//     SEMANTICS §25) in the clauses after it: a later `flatten`, `group by`,
+//     `having`, the select, `order by`, or `^name` from a block under them; in
+//     its own expression and before the clause (`where`, `frontier`, `follow`)
+//     the name is still the row's property;
 //   • a `select` alias is not a reference where the language resolves it
 //     (SEMANTICS §14): in the same body's `where`, and in the items to its
 //     right — a bare identifier naming such an alias, or a chain headed by it,
@@ -54,15 +58,17 @@
 // are cut after the last step at its scope's depth. The empty list is the root
 // scope.
 
-import type { AstNode, Expr, Follow, Query, SelectItem, Span, Subquery } from "./ast.ts";
+import type { AstNode, Expr, Flatten, Follow, GroupBy, Query, SelectItem, Span, Subquery } from "./ast.ts";
 import type { Clause } from "./walk.ts";
 import { visit } from "./walk.ts";
 
 /** One step of a scope's row chain: an expression (a source, a `from`, a block
- * receiver, a plain destination) or a `follow` node (the walk's frontier rows),
- * with the scope depth of the rows it produces. */
+ * receiver, a plain destination), a `follow` node (the walk's frontier rows), or
+ * — since 0.24 — a `groupBy` node (the body's groups: the rows at the same depth
+ * replaced by one key record per group), with the scope depth of the rows it
+ * produces. */
 export interface ReferenceStep {
-  readonly expr: Expr | Follow;
+  readonly expr: Expr | Follow | GroupBy;
   readonly depth: number;
 }
 
@@ -120,6 +126,13 @@ export function references(root: Query | Subquery): Reference[] {
       const levels = head.kind === "outer" ? head.levels : 0;
       const depth = ctx.depth - levels;
       if (isLiftBound(name, depth, ctx.path, lifts)) return false;
+      // A name a `flatten` bound (0.25) is an alias of the expression already
+      // reported in clause `flatten`, read in the clauses after it.
+      if (isFlattenBound(name, depth, ctx.path, node)) return false;
+      // At a group scope (0.24) a bare key name is the key — an alias of the
+      // expression reported in clause `groupBy` — and `rows` is the language's
+      // value; neither reads a row.
+      if (isGroupValue(name, depth, ctx.path, node)) return false;
       const full = [name, ...path].join(".");
       const steps = scopeSteps(ctx.path, node);
       const scoped = levels === 0 ? steps : cutAt(steps, depth);
@@ -132,9 +145,9 @@ export function references(root: Query | Subquery): Reference[] {
 
 /** Whether a bare `name` in this position is a `select` alias the language
  * substitutes (so the name is the alias, not a row property): in the body's
- * `where`, any alias; in a `select` item, an alias defined to its LEFT. */
+ * `where` or `having`, any alias; in a `select` item, an alias defined to its LEFT. */
 function isResolvedAlias(name: string, path: readonly AstNode[], clause: Clause): boolean {
-  if (clause !== "where" && clause !== "select") return false;
+  if (clause !== "where" && clause !== "select" && clause !== "having") return false;
   // The nearest body, and the item under it when we are inside its select.
   for (let i = path.length - 1; i >= 0; i--) {
     const a = path[i]!;
@@ -143,7 +156,7 @@ function isResolvedAlias(name: string, path: readonly AstNode[], clause: Clause)
     a.select.forEach((it, j) => { const n = aliasName(it); if (n !== null) index.set(n, j); });
     const j = index.get(name);
     if (j === undefined) return false;
-    if (clause === "where") return true;
+    if (clause === "where" || clause === "having") return true;
     const item = path[i + 1];
     const at = item === undefined ? -1 : a.select.indexOf(item as SelectItem);
     return at >= 0 && j < at;
@@ -185,6 +198,76 @@ function liftsLandingOn(body: Query | Subquery): ReadonlySet<string> {
   return names;
 }
 
+/**
+ * Whether `name`, read at scope `depth`, is bound there by a `flatten` of the
+ * body whose rows are at `depth` (SEMANTICS §25) — the position lies in a
+ * clause evaluated after that flatten: a later `flatten`, `group by`, `having`,
+ * the select, or `order by` (`where`, `frontier`, `follow` and the body's
+ * sources run before any flatten, and a flatten's own expression before itself).
+ */
+function isFlattenBound(name: string, depth: number, path: readonly AstNode[], node: AstNode): boolean {
+  const i = bodyIndexAt(path, depth);
+  if (i === -1) return false;
+  const body = path[i] as Query | Subquery;
+  if (body.flatten.length === 0) return false;
+  const child = path[i + 1] ?? node;
+  let upto: number;
+  if (body.select.includes(child as SelectItem) || child === body.groupBy || child === body.having || (body.orderBy?.includes(child as never) ?? false)) {
+    upto = body.flatten.length;
+  } else {
+    const k = body.flatten.indexOf(child as Flatten);
+    if (k === -1) return false;
+    upto = k;
+  }
+  for (let j = 0; j < upto; j++) if (body.flatten[j]!.name === name) return true;
+  return false;
+}
+
+/**
+ * Whether `name`, read at scope `depth`, is a value of a GROUP scope there
+ * (SEMANTICS §24): the body whose rows are at `depth` has a `group by`, the
+ * position is one of its post-group clauses — a select item, `having`, `order
+ * by` — not inside an aggregate's argument (which reads the group's rows), and
+ * the name is a key or `rows`.
+ */
+function isGroupValue(name: string, depth: number, path: readonly AstNode[], node: AstNode): boolean {
+  const i = bodyIndexAt(path, depth);
+  if (i === -1) return false;
+  const body = path[i] as Query | Subquery;
+  if (!atGroupScope(body, path, i, node)) return false;
+  return name === "rows" || body.groupBy!.keys.some((k) => k.name === name);
+}
+
+/** The index in `path` of the body whose rows are at scope `depth` (every nested body is one scope deeper), or -1. */
+function bodyIndexAt(path: readonly AstNode[], depth: number): number {
+  if (depth < 1) return -1;
+  let seen = 0;
+  for (let i = 0; i < path.length; i++) {
+    const a = path[i]!;
+    if (a.kind !== "query" && a.kind !== "subquery") continue;
+    if (++seen === depth) return i;
+  }
+  return -1;
+}
+
+/** Whether a position under `body` (at `path[i]`) reads the body's GROUP scope:
+ * the body is grouped, the position lies in a select item, `having` or `order
+ * by`, and no aggregate stands between the body and the position (an
+ * aggregate's argument reads the group's rows; a nested body is its own scope
+ * and ends the search). */
+function atGroupScope(body: Query | Subquery, path: readonly AstNode[], i: number, node: AstNode): boolean {
+  if (body.groupBy === null) return false;
+  const child = path[i + 1] ?? node;
+  const post = body.select.includes(child as SelectItem) || child === body.having || (body.orderBy?.includes(child as never) ?? false);
+  if (!post) return false;
+  for (let j = i + 1; j < path.length; j++) {
+    const a = path[j]!;
+    if (a.kind === "query" || a.kind === "subquery") break;
+    if (a.kind === "aggregate") return false;
+  }
+  return true;
+}
+
 /** The row chain of the scope a node is evaluated in, from its ancestors. */
 function scopeSteps(path: readonly AstNode[], node: AstNode): ReferenceStep[] {
   const steps: ReferenceStep[] = [];
@@ -198,12 +281,16 @@ function scopeSteps(path: readonly AstNode[], node: AstNode): ReferenceStep[] {
         depth = 1;
         steps.push({ expr: a.source, depth });
         pushFroms(steps, a.from, next, depth);
+        // A grouped body's post-group clauses read its groups (0.24): the rows
+        // at this depth replaced by one key record per group.
+        if (atGroupScope(a, path, i, node)) steps.push({ expr: a.groupBy!, depth });
         break;
       }
       case "subquery": {
         // The receiver step was pushed by the enclosing `op`; this body's rows
         // are one deeper than where that receiver was read.
         pushFroms(steps, a.from, next, depth);
+        if (atGroupScope(a, path, i, node)) steps.push({ expr: a.groupBy!, depth });
         break;
       }
       case "op": {

package/src/resolve.ts

@@ -26,7 +26,7 @@
 // given. Untouched nodes are returned by reference, so a cached query keeps the
 // identity of every block the rewrite did not reach.
 
-import type { Expr, Follow, FollowDestination, OpNode, Query, SelectItem, Subquery, Where } from "./ast.ts";
+import type { Expr, Flatten, Follow, FollowDestination, GroupBy, OpNode, Query, SelectItem, Subquery, Where } from "./ast.ts";
 import { OqxError } from "./errors.ts";
 
 /** How a resolution failure is reported: the parser raises its positioned parse
@@ -52,8 +52,22 @@ function resolveBody<T extends Query | Subquery>(node: T, fail: Fail): T {
   // cycle report follows the where's own path (`c → a → b → c`), as pinned.
   const where = node.where === null ? null : resolveWhere(node.select, node.where, fail);
   const where2 = where === null ? null : resolveNestedWhere(where, fail);
+  // `having` (0.24) is the post-group `where`: rewritten against the select
+  // exactly as `where` is (`select n: count() … having n > 1`).
+  const having = node.having === null ? null : resolveWhere(node.select, node.having, fail);
+  const having2 = having === null ? null : resolveNestedWhere(having, fail);
   const select = resolveSelect(node.select, fail);
   const follow = node.follow === null ? null : resolveFollow(node.follow, fail);
+  // The keys are read on the rows, not rewritten (a key IS the name the post-group
+  // clauses read); their nested blocks resolve against their own select.
+  const groupBy = node.groupBy === null ? null : resolveGroupBy(node.groupBy, fail);
+  // A `flatten` expression (0.25) reads the row, not the projection — like
+  // `order by` and `frontier` it is not rewritten against the select; its
+  // nested blocks resolve against their own select.
+  const flatten = mapSame(node.flatten, (f: Flatten) => {
+    const expr = resolveExpr(f.expr, fail);
+    return expr === f.expr ? f : { ...f, expr };
+  });
   const from = mapSame(node.from, (e) => resolveExpr(e, fail));
   const orderBy = node.orderBy === null ? null : mapSame(node.orderBy, (o) => {
     const expr = resolveExpr(o.expr, fail);
@@ -68,13 +82,22 @@ function resolveBody<T extends Query | Subquery>(node: T, fail: Fail): T {
   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 && frontier === node.frontier
+    && groupBy === node.groupBy && having2 === node.having && flatten === node.flatten
     && (node.kind !== "query" || source === node.source);
   if (same) return node;
-  const out = { ...node, where: where2, select, follow, frontier, from, orderBy, limit, offset };
+  const out = { ...node, where: where2, select, follow, frontier, flatten, groupBy, having: having2, from, orderBy, limit, offset };
   if (node.kind === "query") (out as Query).source = source!;
   return out;
 }
 
+function resolveGroupBy(g: GroupBy, fail: Fail): GroupBy {
+  const keys = mapSame(g.keys, (k) => {
+    const expr = resolveExpr(k.expr, fail);
+    return expr === k.expr ? k : { ...k, expr };
+  });
+  return keys === g.keys ? g : { ...g, keys };
+}
+
 function resolveOp(op: OpNode, fail: Fail): OpNode {
   const receiver = resolveExpr(op.receiver, fail);
   const sub = resolveBody(op.sub, fail);
@@ -145,6 +168,10 @@ function mapExpr(e: Expr, f: (e: Expr) => Expr | null): Expr {
       const parts = mapSame(e.parts, (p) => (typeof p === "string" ? p : go(p)));
       return parts === e.parts ? e : { ...e, parts };
     }
+    case "aggregate": {
+      const arg = e.arg ? go(e.arg) : null;
+      return arg === e.arg ? e : { ...e, arg };
+    }
     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.23";
+export const LANGUAGE_VERSION = "0.25";

package/src/walk.ts

@@ -14,7 +14,9 @@ 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.frontier";
+  | "follow" | "follow.destination" | "follow.frontier"
+  | "flatten" // a `flatten` node and its expression (0.25)
+  | "groupBy" | "having"; // the `group by` keys and the post-group predicate (0.24)
 
 /** 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 =
@@ -57,6 +59,13 @@ export const CHILDREN: { readonly [K in AstKind]: readonly ChildKey[] } = {
     // 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 },
+    // A `flatten` expression is read on each row, like `where` (0.25); a
+    // flattened row sits at the same depth as its parent.
+    { key: "flatten", clause: "flatten", depth: 1 },
+    // `group by` keys are read on the rows, `having` on the groups — both at
+    // the row depth (the group scope sits where the rows did; 0.24).
+    { key: "groupBy", clause: "groupBy", depth: 1 },
+    { key: "having", clause: "having", depth: 1 },
     { key: "orderBy", clause: "orderBy", depth: 1 },
     { key: "limit", clause: "limit" },
     { key: "offset", clause: "offset" },
@@ -71,12 +80,18 @@ export const CHILDREN: { readonly [K in AstKind]: readonly ChildKey[] } = {
     // (`childDepth` tells the two apart by the block's position).
     { key: "frontier", clause: "follow.frontier", depth: -1 },
     { key: "follow", clause: "follow" },
+    { key: "flatten", clause: "flatten" },
+    { key: "groupBy", clause: "groupBy" },
+    { key: "having", clause: "having" },
     { 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" }],
+  flatten: [{ key: "expr" }],
+  groupBy: [{ key: "keys" }],
+  key: [{ key: "expr" }],
   order: [{ key: "expr" }],
   field: [{ key: "expr" }],
   collect: [{ key: "op" }],
@@ -99,6 +114,8 @@ export const CHILDREN: { readonly [K in AstKind]: readonly ChildKey[] } = {
   tuple: [{ key: "items" }],
   // The interpolations; the text parts between them are strings, not nodes.
   template: [{ key: "parts" }],
+  // The argument is read on each of the group's rows (0.24); `null` for `count()`.
+  aggregate: [{ key: "arg" }],
 };
 
 /** A child slot's value: a node, a list of nodes (a template's `parts` also