@omgbase/oqx 0.24.0 → 0.26.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,7 +58,7 @@
 // are cut after the last step at its scope's depth. The empty list is the root
 // scope.
 
-import type { AstNode, Expr, Follow, GroupBy, 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";
 
@@ -122,6 +126,9 @@ 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.
@@ -191,6 +198,31 @@ 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

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, GroupBy, 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
@@ -61,6 +61,13 @@ function resolveBody<T extends Query | Subquery>(node: T, fail: Fail): T {
   // 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);
@@ -75,10 +82,10 @@ 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
+    && 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, groupBy, having: having2, 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;
 }

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.24";
+export const LANGUAGE_VERSION = "0.26";

package/src/walk.ts

@@ -15,6 +15,7 @@ import { LANGUAGE_VERSION } from "./version.ts";
 export type Clause =
   | "source" | "from" | "where" | "select" | "orderBy" | "limit" | "offset"
   | "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
@@ -58,6 +59,9 @@ 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 },
@@ -76,6 +80,7 @@ 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" },
@@ -84,6 +89,7 @@ export const CHILDREN: { readonly [K in AstKind]: readonly ChildKey[] } = {
   ],
   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" }],