@omgbase/oqx 0.24.0 → 0.26.0

package/dist/parser.js

@@ -13,7 +13,7 @@
 // consumer block — each clause appears at most once, in exactly this order:
 //
 //   select <projection>  from <source>  where <predicate>  follow <dest>, … {…}
-//   order by …  limit N  offset N
+//   flatten <expr> [{…}] [as <name>] …  group by …  having …  order by …  limit N  offset N
 //
 // A `follow` destination is a relation of the current row (a receiver, never
 // an outer reference) or a destination block — a receiver (which MAY be an
@@ -24,17 +24,27 @@
 // that destination's block, whose body admits two clauses no other block has —
 // `frontier P` and `depth n`, in the clause order after `where`.
 //
-// Every clause is optional except that a top-level body needs `from` (the
-// receiver-plus-consumer form `<receiver> <consumer> { block }` supplies the
-// source itself, so its block's `from` is an optional re-projection). Only
+// A query names its source BEFORE its body (0.26, the collection-scoped form):
+// `<collection> [<consumer>] [distinct] { body }` — the receiver supplies the
+// rows, so the body never names its source and its `from` is the re-projection
+// (a flatMap). The clause form `select … from S …` is still read as the same
+// tree (its top-level body needs `from`); the printer never writes it. Only
 // `select` may drop its keyword, and only when it is the first clause written
-// (`name, age from people`); every other clause always carries its keyword. A
-// BLOCK may instead lead with a predicate (since 0.17): a leading expression that
-// is syntactically a predicate — not a bare name, a dotted navigation or a lift —
-// opens a `where`-first body (`people exists { age > 50 }`); at the top level a
-// leading predicate is still an error, since `where` would precede `from`. An
+// (`people { name, age }`); every other clause always carries its keyword. A
+// body with a receiver may instead lead with a predicate (since 0.17): a
+// leading expression that is syntactically a predicate — not a bare name, a
+// dotted navigation or a lift — opens a `where`-first body (`people { age > 50
+// }`, `people exists { age > 50 }`); at the clause form's top level a leading
+// predicate is still an error, since `where` would precede `from`. An
 // out-of-order clause is a parse error naming the order.
 //
+// Two 0.26 shapes desugar HERE as well: a consumer word with no block is the
+// directive over the empty block (`jobs first` ≡ `jobs first { }`, `jobs count
+// > 1`, `_nodes exists`; a consumer word right after a complete receiver can be
+// nothing else), and a projection-only block over a `collect`/`first`/`single`
+// directive whose block projects nothing is that directive's projection
+// (`jobs[0] { name }` ≡ `jobs first { name offset 0 }`, `mergeProjectionBlock`).
+//
 // Sugar (0.17) desugars HERE, to existing nodes: `x { … }` is `x collect { … }`
 // wherever a value stands (a select item, a where leaf, a follow destination, a
 // call argument — since 0.20 without exception) and `x distinct { … }` is
@@ -81,6 +91,7 @@ import { lexTemplate, lexString } from "./lexer.js";
 import { OqxError } from "./errors.js";
 import { AGGREGATE_NAMES, isAggregateName } from "./ast.js";
 import { resolveSelect, resolveWhere } from "./resolve.js";
+import { visit } from "./walk.js";
 import { printTemplate } from "./print.js";
 const CONSUMERS = new Set(["collect", "exists", "none", "count", "first", "single"]);
 // The fixed clause order of a body (ADR-020). Each clause appears at most once.
@@ -89,8 +100,11 @@ const CONSUMERS = new Set(["collect", "exists", "none", "count", "first", "singl
 // `depth` is legal only in a follow destination block, and the order sentence
 // names it only there. `group by` and `having` (0.24) sit after `follow`: the
 // rows a body yields — the walk's occurrences, when it has one — are what gets
-// grouped, and the bound and the ordering then apply to the groups.
-const CLAUSE_ORDER = ["select", "from", "where", "frontier", "depth", "follow", "group by", "having", "order by", "limit", "offset"];
+// grouped, and the bound and the ordering then apply to the groups. `flatten`
+// (0.25) sits between them: it fans the rows a body yields — the occurrences,
+// after a walk — out per element, and is the one clause that may repeat (each
+// `flatten` fans out the rows the previous produced, SEMANTICS §25).
+const CLAUSE_ORDER = ["select", "from", "where", "frontier", "depth", "follow", "flatten", "group by", "having", "order by", "limit", "offset"];
 const DESTINATION_ONLY = new Set(["depth"]);
 // The clauses a body may hold, in order.
 function clausesOf(ctx) {
@@ -101,7 +115,7 @@ function clausesOf(ctx) {
 const CLAUSE_WORDS = new Set([
     "collect", "exists", "none", "count", "first", "single",
     "order", "by", "asc", "desc", "follow", "distinct", "frontier", "depth", "in", "values",
-    "limit", "offset", "group", "having",
+    "limit", "offset", "group", "having", "flatten", "as",
 ]);
 // The names a group scope resolves besides its keys (SEMANTICS §24): the
 // group's rows, the key record itself, and its identity.
@@ -125,6 +139,29 @@ export function parseTemplate(fragments, values) {
 export function parseString(src) {
     return new Parser(lexString(src)).parseQuery();
 }
+/** The clauses of an omitted block (`jobs first` — the empty block `{ }`). */
+function emptyBody() {
+    return { froms: [], where: null, select: [], orderBy: null, follow: null, frontier: null, depth: null, flatten: [], groupBy: null, having: null, distinct: false, values: false, limit: null, offset: null };
+}
+/** The names a projection would shadow in a `where` of the same body: every
+ * item's name except a plain self-projection (`pay: pay`, `pay`), which
+ * substitutes a name for itself. */
+function shadowingNames(items) {
+    return items
+        .filter((it) => it.name !== "" && !(it.kind === "field" && it.lift === 0 && it.expr.kind === "ident" && it.expr.name === it.name))
+        .map((it) => it.name);
+}
+/** Whether a bare identifier anywhere under `w` has one of `names` (the alias
+ * guard of the projection-block merge; conservative: nested blocks included). */
+function readsAnyOf(w, names) {
+    const wanted = new Set(names.filter((n) => n !== ""));
+    if (wanted.size === 0)
+        return false;
+    let found = false;
+    visit(w, { enter(node) { if (node.kind === "ident" && wanted.has(node.name))
+            found = true; return !found; } });
+    return found;
+}
 // A copy of a node with another span (a parenthesized operand takes the span of
 // its parentheses).
 function withSpan(node, span) {
@@ -142,6 +179,11 @@ class Parser {
      * top-level row's clauses, one deeper per block body and per follow `where`.
      * An absolute reference `N^name` reads `depth − N` scopes out. */
     depth = 0;
+    /** Whether a consumer word with no block is read as a directive over the
+     * empty block (`jobs first` ≡ `jobs first { }`, since 0.26). Off only while
+     * the clause form's top-level `from` expression is read, so `from people
+     * count` keeps its whole-query hint (a count is never a source). */
+    bareDirectives = true;
     constructor(tokens) {
         this.tokens = tokens;
     }
@@ -185,9 +227,10 @@ class Parser {
         const start = this.start();
         // Directive form: `<receiver> <consumer> { … }` consuming the whole query.
         let directive = this.tryOp(false);
-        if (directive && !this.at("eof") && (this.at("lbracket") || this.atValueDirective())) {
+        if (directive && !this.at("eof") && (this.at("lbracket") || this.atBlock() !== null)) {
             // A longer chain whose outermost node is still a directive
-            // (`people first { } first { }` — how `people[p][0]` prints back).
+            // (`people first { } first { }` — how `people[p][0]` prints back; a block
+            // over the directive, `people[0] { name }`, merges into it, 0.26).
             const save = this.pos;
             try {
                 const e = this.parsePostfix(directive);
@@ -228,7 +271,7 @@ class Parser {
         if (!this.at("eof"))
             this.fail(`unexpected ${this.tokDesc()} after the query — nothing may follow the last clause`);
         if (body.froms.length === 0) {
-            this.fail("a query must name its source with `from <collection>` (or be `<collection> <consumer> { … }`)");
+            this.fail("a query must name its source before its body: `<collection> { … }` (or `<collection> <consumer> { … }`; the clause form `select … from <collection> …` is still read)");
         }
         return {
             kind: "query",
@@ -241,6 +284,7 @@ class Parser {
             consumer: "collect",
             follow: body.follow,
             frontier: body.frontier,
+            flatten: body.flatten,
             groupBy: body.groupBy,
             having: body.having,
             distinct: body.distinct,
@@ -254,7 +298,7 @@ class Parser {
     queryFromOp(e, start) {
         return {
             kind: "query", span: this.sp(start), source: e.receiver, from: e.sub.from, where: e.sub.where, select: e.sub.select,
-            orderBy: e.sub.orderBy, consumer: e.op, follow: e.sub.follow, frontier: e.sub.frontier, groupBy: e.sub.groupBy, having: e.sub.having,
+            orderBy: e.sub.orderBy, consumer: e.op, follow: e.sub.follow, frontier: e.sub.frontier, flatten: e.sub.flatten, groupBy: e.sub.groupBy, having: e.sub.having,
             distinct: e.distinct, values: e.sub.values, limit: e.sub.limit, offset: e.sub.offset,
         };
     }
@@ -275,6 +319,7 @@ class Parser {
         let follow = null;
         let frontier = null;
         let depth = null;
+        const flatten = [];
         let groupBy = null;
         let having = null;
         let distinct = false;
@@ -288,7 +333,9 @@ class Parser {
         const rowDepth = ctx.top ? 1 : this.depth;
         const enter = (clause) => {
             const idx = CLAUSE_ORDER.indexOf(clause);
-            if (idx === stage)
+            // `flatten` is the one clause that may repeat (0.25): each fans out the
+            // rows the previous produced.
+            if (idx === stage && clause !== "flatten")
                 this.fail(`duplicate \`${clause}\` clause`);
             if (idx < stage) {
                 this.fail(`\`${clause}\` must come before \`${CLAUSE_ORDER[stage]}\` — OQX clause order is ${clausesOf(ctx).join(", ")}`);
@@ -309,7 +356,18 @@ class Parser {
             if (this.at("kw", "from")) {
                 enter("from");
                 this.next();
-                froms.push(this.parseValueExpr());
+                // At the clause form's top level a consumer word after the source is the
+                // whole-query mistake (`from people count`): kept as the hint below,
+                // not read as a braceless directive (a count is never a source).
+                const bare = this.bareDirectives;
+                if (ctx.top)
+                    this.bareDirectives = false;
+                try {
+                    froms.push(this.parseValueExpr());
+                }
+                finally {
+                    this.bareDirectives = bare;
+                }
                 continue;
             }
             if (this.at("kw", "where")) {
@@ -345,6 +403,14 @@ class Parser {
                 follow = this.atDepth(rowDepth, () => this.parseFollow());
                 continue;
             }
+            // `flatten <expr> [{ … }] [as <name>]` (0.25): the value is read on each
+            // row, like `where`; a brace after a receiver is the receiver-block sugar
+            // (the `collect` op), so the block needs no slot of its own.
+            if (this.atFlatten()) {
+                enter("flatten");
+                flatten.push(this.atDepth(rowDepth, () => this.parseFlatten(flatten)));
+                continue;
+            }
             // `group by k, name: expr` (0.24): the keys are read on the rows, like `where`.
             if (this.atGroupBy()) {
                 enter("group by");
@@ -426,12 +492,56 @@ class Parser {
         if (groupBy) {
             if (distinct)
                 this.failAt(groupBy.span[0], DISTINCT_WITH_GROUP);
-            this.checkGroupedBody({ select, resolvedSelect, having, resolvedHaving, orderBy, froms, where: resolvedWhere, frontier, limit, offset, groupBy });
+            this.checkGroupedBody({ select, resolvedSelect, having, resolvedHaving, orderBy, froms, where: resolvedWhere, frontier, flatten, limit, offset, groupBy });
         }
         else {
-            this.rejectAggregates({ select, resolvedSelect, having: null, resolvedHaving: null, orderBy, froms, where: resolvedWhere, frontier, limit, offset, groupBy: null });
+            this.rejectAggregates({ select, resolvedSelect, having: null, resolvedHaving: null, orderBy, froms, where: resolvedWhere, frontier, flatten, limit, offset, groupBy: null });
         }
-        return { froms, where, select, orderBy, follow, frontier, depth, groupBy, having, distinct, values, limit, offset };
+        return { froms, where, select, orderBy, follow, frontier, depth, flatten, groupBy, having, distinct, values, limit, offset };
+    }
+    // ---- flatten (0.25) -------------------------------------------------------
+    // `flatten` is a clause when a value can follow the word; otherwise it is a
+    // field name (`select flatten from r`).
+    atFlatten() {
+        if (!this.at("ident", "flatten"))
+            return false;
+        const nx = this.peekAt(1);
+        // A value start — or an aggregate call whose name is a consumer word
+        // (`flatten collect(x)`), admitted so the aggregate check can name it.
+        return this.startsValue(nx) || (nx?.type === "ident" && isAggregateName(nx.value) && this.peekAt(2)?.type === "lparen");
+    }
+    // `flatten <expr> [as <name>]`. The expression is any value — a block after a
+    // receiver is read by the postfix grammar as the implicit `collect` op (0.20),
+    // which is exactly the block over the coerced collection SEMANTICS §25 wants.
+    // The name defaults to a plain navigation's last segment (as a select item's
+    // or a group key's does); anything else needs `as`. Names are unique within
+    // the body, never a `$`-name (the language's), a keyword or a literal word.
+    parseFlatten(earlier) {
+        const start = this.start();
+        this.next(); // `flatten`
+        const expr = this.parseValueExpr();
+        let name;
+        if (this.at("ident", "as")) {
+            this.next();
+            const t = this.peek();
+            if (t.type !== "ident")
+                this.fail("expected a name after `as` (`flatten <expr> as <name>`)");
+            if (LITERAL_WORDS.has(t.value))
+                this.fail(`\`${t.value}\` is a literal and cannot name a flattened value (\`flatten <expr> as <name>\`)`);
+            if (t.value.startsWith("$"))
+                this.fail(`a flattened value cannot be bound to a \`$\`-name (\`${t.value}\`) — \`$\` belongs to the language; choose another name`);
+            name = this.next().value;
+        }
+        else {
+            const key = navKey(expr);
+            if (key === null) {
+                this.failAt(start, `\`flatten ${describe(expr)}\` needs a name (\`flatten ${describe(expr)} as <name>\`) — only a plain navigation names itself by its last segment`);
+            }
+            name = key;
+        }
+        if (earlier.some((f) => f.name === name))
+            this.failAt(start, `duplicate flatten name '${name}' — each flatten binds its own name (\`flatten <expr> as <other>\`)`);
+        return { kind: "flatten", span: this.sp(start), expr, name };
     }
     // ---- grouping (0.24) ------------------------------------------------------
     // `group by` is a clause only as the two-word sequence (a field named `group`
@@ -542,6 +652,7 @@ class Parser {
             found.push([a, "`where`"]);
         collect(b.froms, "`from`");
         collect([b.frontier], "`frontier`");
+        collect(b.flatten.map((f) => f.expr), "`flatten`");
         collect([b.limit], "`limit`");
         collect([b.offset], "`offset`");
         if (b.groupBy)
@@ -750,6 +861,8 @@ class Parser {
                 this.fail("expected an integer after `depth` (`depth 1`..`depth 8`)");
             if (t.value === "frontier")
                 this.fail(`unexpected 'frontier' after \`${last}\` — \`frontier\` takes an expression (\`frontier <expr>\`) and belongs to a body that has a \`follow\``);
+            if (t.value === "flatten")
+                this.fail(`unexpected 'flatten' after \`${last}\` — \`flatten\` takes a value to split into rows (\`flatten <expr> [{ … }] [as <name>]\`)`);
             if (t.value === "group")
                 this.fail(`unexpected 'group' after \`${last}\` — a grouping is written \`group by <key>[, <key>…]\` (a key is a name or \`alias: <expr>\`)`);
             if (t.value === "having")
@@ -966,7 +1079,7 @@ class Parser {
                     if (it.kind === "collect")
                         this.fail("a nested block in a projection needs a name (`name: <relation> collect { … }`); as a predicate, a consumer test is written `where <relation> exists { … }`");
                     if (ctx.top)
-                        this.fail("a leading expression is a projection (select): an item that is not a plain name needs an alias (`name: expr`) or `values`; to filter by it write `where …` after `from` — at the top level a predicate is never implicit (the clause order puts `from` first)");
+                        this.fail("a leading expression is a projection (select): an item that is not a plain name needs an alias (`name: expr`) or `values`; to filter by it write `<collection> { <predicate> }`, or write `where …` after `from` — at the top level of the clause form a predicate is never implicit (the clause order puts `from` first)");
                     this.fail("an item that is not a plain name needs an alias (`name: expr`) or `values`; to filter by it write `where …` after the projection (a block may lead with a predicate only when nothing is projected: `{ age > 18 }`)");
                 }
                 const key = `${"^".repeat(it.kind === "field" ? it.lift : 0)}${it.name}`;
@@ -996,8 +1109,9 @@ class Parser {
             this.next(); // ':'
             const op = this.tryOp(false);
             if (op) {
-                // `name: jobs first { }.pay`: the directive is the head of a longer value.
-                if (this.atScalarContinuation() || this.atValueDirective())
+                // `name: jobs first { }.pay`: the directive is the head of a longer value
+                // (a block over it, `jobs[0] { name }`, merges into it — 0.26).
+                if (this.atScalarContinuation() || this.atBlock() !== null)
                     return this.finishItem(name, this.parseOr(op), lift, start);
                 if (op.op !== "collect" && op.op !== "first" && op.op !== "single" && op.op !== "count") {
                     this.fail(`projection '${name}' must use collect/first/single/count, not ${op.op} (exists/none are where-position tests; \`count { … }\` is a value since 0.24)`);
@@ -1298,14 +1412,19 @@ class Parser {
         return this.atConsumerBlock();
     }
     // The cursor is at a consumer word that opens a block — `<op> {` or
-    // `<op> distinct {`. Consumes nothing.
+    // `<op> distinct {` — or, since 0.26, at the word alone: a consumer word
+    // right after a complete receiver can be nothing else (OQX never places two
+    // operands side by side), and it reads as the directive over the empty block
+    // (`jobs first` ≡ `jobs first { }`, `_nodes exists`, `jobs count > 1`). The
+    // braceless reading is off only inside the clause form's top-level `from`
+    // (`bareDirectives`). Consumes nothing.
     atConsumerBlock() {
         if (!this.at("ident") || !CONSUMERS.has(this.peek().value))
             return null;
         const after = this.peekAt(1);
         const opThenBrace = after?.type === "lbrace";
         const opDistinctBrace = after?.type === "ident" && after.value === "distinct" && this.peekAt(2)?.type === "lbrace";
-        return opThenBrace || opDistinctBrace ? this.peek().value : null;
+        return opThenBrace || opDistinctBrace || this.bareDirectives ? this.peek().value : null;
     }
     // `[<op>] [distinct] { <sub> }` over an already-parsed receiver; the cursor is
     // at the consumer word, at `distinct`, or at the `{` of the implicit `collect`.
@@ -1320,22 +1439,35 @@ class Parser {
             this.next();
             distinct = true;
         }
-        const lbrace = this.next().pos; // '{'
-        const defer = this.deferLookup;
-        this.deferLookup = false;
-        // The receiver was read at the enclosing depth; the block's rows are one deeper.
-        const body = this.atDepth(this.depth + 1, () => this.parseBody({ top: false, op, liftsAllowed: inWhere && op === "collect", destination }));
-        this.deferLookup = defer;
-        if (!this.at("rbrace"))
-            this.fail(`expected '}' to close the ${op} { … } block`);
-        this.next();
-        // `x collect distinct { group by k }`: the directive's distinct is as
-        // redundant as the body's own (checked in parseBody).
-        if (distinct && body.groupBy)
-            this.failAt(body.groupBy.span[0], DISTINCT_WITH_GROUP);
+        let body;
+        let subSpan;
+        if (this.at("lbrace")) {
+            const lbrace = this.next().pos; // '{'
+            const defer = this.deferLookup;
+            this.deferLookup = false;
+            // The receiver was read at the enclosing depth; the block's rows are one deeper.
+            body = this.atDepth(this.depth + 1, () => this.parseBody({ top: false, op, liftsAllowed: inWhere && op === "collect", destination }));
+            this.deferLookup = defer;
+            if (!this.at("rbrace"))
+                this.fail(`expected '}' to close the ${op} { … } block`);
+            this.next();
+            // `x collect distinct { group by k }`: the directive's distinct is as
+            // redundant as the body's own (checked in parseBody).
+            if (distinct && body.groupBy)
+                this.failAt(body.groupBy.span[0], DISTINCT_WITH_GROUP);
+            subSpan = this.sp(lbrace);
+        }
+        else {
+            // A consumer word with no block (0.26) is the directive over the empty
+            // block `{ }` — the word was written (only a brace makes a bare
+            // `collect`), so nothing more is consumed; the block spans nothing, at
+            // the end of the word.
+            body = emptyBody();
+            subSpan = [this.end(), this.end()];
+        }
         const sub = {
             kind: "subquery",
-            span: this.sp(lbrace),
+            span: subSpan,
             from: body.froms,
             where: body.where,
             select: body.select,
@@ -1343,13 +1475,45 @@ class Parser {
             follow: body.follow,
             frontier: body.frontier,
             depth: body.depth,
+            flatten: body.flatten,
             groupBy: body.groupBy,
             having: body.having,
             values: body.values,
             limit: body.limit,
             offset: body.offset,
         };
-        return { kind: "op", span: this.sp(startPos), receiver, op, sub, countCmp: null, distinct: distinct || body.distinct };
+        return this.mergeProjectionBlock(receiver, op, distinct || body.distinct, sub, startPos);
+    }
+    // A projection-only block over a `collect`/`first`/`single` directive whose
+    // own block projects nothing IS that directive's projection (0.26):
+    // `jobs[0] { name }` ≡ `jobs first { name offset 0 }`, `jobs[p] { name }` ≡
+    // `jobs first { name where p }`, `jobs[0] { }` ≡ `jobs[0]`. The outer items
+    // are read on the very rows the inner block filtered, at the same depth, so
+    // the merge is exact — except when the outer block carries a clause of its
+    // own (those run AFTER the pick: `jobs[0] { name where pay > 2 }` is the
+    // first job, kept only if it pays), when the inner directive dedups
+    // (`distinct` compares the projection), or when an outer alias would shadow a
+    // bare name the inner `where` reads (`jobs[pay > 2] { pay: employer }`): then
+    // the two directives stay.
+    mergeProjectionBlock(receiver, op, distinct, sub, startPos) {
+        const plain = { kind: "op", span: this.sp(startPos), receiver, op, sub, countCmp: null, distinct };
+        if (receiver.kind !== "op" || op !== "collect")
+            return plain;
+        const inner = receiver;
+        if ((inner.op !== "collect" && inner.op !== "first" && inner.op !== "single") || inner.distinct || inner.countCmp !== null)
+            return plain;
+        if (inner.sub.select.length > 0 || inner.sub.values)
+            return plain;
+        const projectionOnly = sub.from.length === 0 && sub.where === null && sub.orderBy === null && sub.follow === null && sub.frontier === null
+            && sub.depth === null && sub.flatten.length === 0 && sub.groupBy === null && sub.having === null && sub.limit === null && sub.offset === null;
+        if (!projectionOnly)
+            return plain;
+        if (inner.sub.where && readsAnyOf(inner.sub.where, shadowingNames(sub.select)))
+            return plain;
+        return {
+            kind: "op", span: this.sp(startPos), receiver: inner.receiver, op: inner.op, countCmp: null, distinct,
+            sub: { ...inner.sub, select: sub.select, values: sub.values, span: [inner.sub.span[0], sub.span[1]] },
+        };
     }
     // A tuple `(e1, e2, …)` at the cursor's `(` (0.20): two or more comma-separated
     // expressions. A single parenthesized expression is grouping, not a tuple —
@@ -1416,7 +1580,7 @@ class Parser {
         this.next();
         const subSpan = [lbracket, this.end()];
         const sub = (parts) => ({
-            kind: "subquery", span: subSpan, from: [], where: null, select: [], orderBy: null, follow: null, frontier: null, depth: null, groupBy: null, having: null, values: false, limit: null, offset: null, ...parts,
+            kind: "subquery", span: subSpan, from: [], where: null, select: [], orderBy: null, follow: null, frontier: null, depth: null, flatten: [], groupBy: null, having: null, values: false, limit: null, offset: null, ...parts,
         });
         const bang = this.atOp("!") ? this.next() : null;
         if (index) {