@omgbase/oqx 0.21.0 → 0.23.0

package/dist/references.js

@@ -0,0 +1,225 @@
+// The `references` static pass (spec/oqx/AST.md §5b, language 0.23): every
+// NAME a query reads from a row — a bare identifier, a dotted navigation headed
+// by one, an outer reference — with the clause it stands in and the SCOPE whose
+// rows it is read from, described as the chain of expressions that produce
+// those rows (the source, each `from` re-projection, each block receiver, each
+// `follow` walk). The pass knows no data: a host that knows what rows an
+// expression yields maps each scope to a row type and judges the name against
+// it (omgbase: "is `target` a field of links?"). Built on `visit`, so a future
+// node kind is walked here the day it is added to `CHILDREN`.
+//
+// What is a reference and what is not (the rules, pinned by
+// `cases/references.json`):
+//   • a bare `ident` is a reference to the current row's property, with the
+//     name as written; a `member` chain headed by an `ident` or `outer` is ONE
+//     reference whose name is the full dotted path (`doc.layer`, `meta.owner`);
+//     a chain headed by anything else (a call, a block, a literal, a tuple) is
+//     not — its head is walked and the trailing `.name`s are ignored, since the
+//     head's value is not a row of any scope;
+//   • an `outer` (`^name`, `N^name`) is a reference read in the scope `levels`
+//     out; `$it` as a head is the row itself (`$it.title` ≡ `title`,
+//     `^$it.title` ≡ `^title`) and `$it` alone is no reference;
+//   • `$`-names (`$key`, `$depth`, `$stop`, …) are the language's values, never
+//     references; a `binding` is a host value; a function or method NAME is
+//     not a reference, its receiver and arguments are walked
+//     (`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;
+//   • 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,
+//     is skipped; an alias's own name inside its own item is the row field and
+//     IS a reference; `order by`, `frontier`, `limit`/`offset`, `from` and
+//     `follow` are not rewritten against aliases, so a name there is a
+//     reference whatever the `select` says;
+//   • a name read at the ROOT scope — the head of the top-level `source`
+//     (`from people`: clause `source`), an outer reference with as many carets
+//     as there are enclosing scopes (`^docs` from a top-level row) — is
+//     reported with depth 0 and no steps: it names one of the host's roots,
+//     and the host decides what to make of it;
+//   • a `follow` destination that is a plain expression is a reference read
+//     on the frontier row (clause `follow.destination`), like a `from`.
+//
+// The scope: `{ depth, steps }`. `depth` is the scope depth the name is
+// evaluated at (`visit`'s depth; for an outer reference, that depth minus its
+// levels). `steps` are the expressions that produce the scope's rows, root
+// first, each with the depth of the rows it produces: the query's `source`
+// (depth 1), each `from` re-projection in turn (the same depth — a `from`
+// replaces the rows), a block's receiver (one deeper than where it is read),
+// then the block's own `from`s; a `follow` node is a step too — the walk's
+// frontier rows, at the body's depth, which the destinations are read on
+// (a destination block's receiver is then one deeper). A name read inside the
+// k-th `from` sees only the steps before it. For an outer reference the steps
+// are cut after the last step at its scope's depth. The empty list is the root
+// scope.
+import { visit } from "./walk.js";
+/** A dotted name headed by an `ident` or `outer`: the head and the path after it. */
+function dottedName(e) {
+    if (e.kind === "ident" || e.kind === "outer")
+        return { head: e, path: [] };
+    if (e.kind === "member") {
+        const inner = dottedName(e.recv);
+        return inner === null ? null : { head: inner.head, path: [...inner.path, e.name] };
+    }
+    return null;
+}
+/** The alias an item defines (SEMANTICS §14): a named `collect`, or a named non-lift field. */
+function aliasName(it) {
+    if (it.kind === "collect")
+        return it.name === "" ? null : it.name;
+    return it.lift === 0 && it.name !== "" ? it.name : null;
+}
+/** Every name a query (or block body) reads from a row, in canonical source order. */
+export function references(root) {
+    const out = [];
+    const lifts = new Map();
+    visit(root, {
+        enter(node, ctx) {
+            const named = dottedName(node);
+            if (named === null)
+                return;
+            const { head } = named;
+            // The head of a navigation is handled here, once, with the chain's full name.
+            let name = head.name;
+            let path = named.path;
+            if (name === "$it") {
+                if (path.length === 0)
+                    return false; // the row itself
+                name = path[0];
+                path = path.slice(1);
+            }
+            else if (name.startsWith("$"))
+                return false; // a language value
+            if (ctx.clause === null)
+                return false; // unreachable: the root node is never a name
+            if (head.kind === "ident" && isResolvedAlias(name, ctx.path, ctx.clause))
+                return false;
+            const levels = head.kind === "outer" ? head.levels : 0;
+            const depth = ctx.depth - levels;
+            if (isLiftBound(name, depth, ctx.path, lifts))
+                return false;
+            const full = [name, ...path].join(".");
+            const steps = scopeSteps(ctx.path, node);
+            const scoped = levels === 0 ? steps : cutAt(steps, depth);
+            out.push({ name: full, clause: ctx.clause, scope: { depth, steps: scoped }, span: node.span });
+            return false;
+        },
+    });
+    return out;
+}
+/** 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. */
+function isResolvedAlias(name, path, clause) {
+    if (clause !== "where" && clause !== "select")
+        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];
+        if (a.kind !== "query" && a.kind !== "subquery")
+            continue;
+        const index = new Map();
+        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;
+        const item = path[i + 1];
+        const at = item === undefined ? -1 : a.select.indexOf(item);
+        return at >= 0 && j < at;
+    }
+    return false;
+}
+/**
+ * Whether `name`, read at scope `depth`, is bound there by a lift (`^name: expr`
+ * in a nested block, SEMANTICS §19): the lifted value is appended to that
+ * scope's row record, so the name is a binding, not a row property. The body
+ * whose rows are at `depth` is the depth-th body on the path (every nested body
+ * is one scope deeper than the one around it).
+ */
+function isLiftBound(name, depth, path, cache) {
+    if (depth < 1)
+        return false;
+    const bodies = path.filter((a) => a.kind === "query" || a.kind === "subquery");
+    const body = bodies[depth - 1];
+    if (body === undefined)
+        return false;
+    let names = cache.get(body);
+    if (names === undefined) {
+        names = liftsLandingOn(body);
+        cache.set(body, names);
+    }
+    return names.has(name);
+}
+/** The names the nested blocks of `body` lift onto it: a `field` item with `lift` L in a block L scopes below it. */
+function liftsLandingOn(body) {
+    const names = new Set();
+    const own = body.kind === "subquery" ? 1 : 0;
+    visit(body, {
+        enter(node, ctx) {
+            if (node.kind !== "field" || node.lift === 0)
+                return;
+            const below = ctx.path.filter((a) => a.kind === "subquery").length - own;
+            if (node.lift === below)
+                names.add(node.name);
+        },
+    });
+    return names;
+}
+/** The row chain of the scope a node is evaluated in, from its ancestors. */
+function scopeSteps(path, node) {
+    const steps = [];
+    let depth = 0;
+    for (let i = 0; i < path.length; i++) {
+        const a = path[i];
+        const next = path[i + 1] ?? node;
+        switch (a.kind) {
+            case "query": {
+                if (next === a.source || next === a.limit || next === a.offset)
+                    break; // read at the root scope
+                depth = 1;
+                steps.push({ expr: a.source, depth });
+                pushFroms(steps, a.from, next, 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);
+                break;
+            }
+            case "op": {
+                if (next !== a.sub)
+                    break; // inside the receiver: read where the block is read
+                depth += 1;
+                steps.push({ expr: a.receiver, depth });
+                break;
+            }
+            case "follow": {
+                // The destinations are read on the walk's frontier rows, at the body's depth.
+                steps.push({ expr: a, depth });
+                break;
+            }
+            default: break;
+        }
+    }
+    return steps;
+}
+/** The `from` re-projections that apply at `next`: all of them unless `next` is one of them, in which case those before it. */
+function pushFroms(steps, from, next, depth) {
+    const at = from.indexOf(next);
+    const upto = at === -1 ? from.length : at;
+    for (let k = 0; k < upto; k++)
+        steps.push({ expr: from[k], depth });
+}
+/** The steps up to and including the last one producing rows at `depth` (none for the root scope). */
+function cutAt(steps, depth) {
+    let end = 0;
+    steps.forEach((s, i) => { if (s.depth === depth)
+        end = i + 1; });
+    return steps.slice(0, end);
+}
+//# sourceMappingURL=references.js.map

package/dist/references.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"references.js","sourceRoot":"","sources":["../src/references.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -1,5 +1,5 @@
 /** 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 declare const LANGUAGE_VERSION = "0.21";
+export declare const LANGUAGE_VERSION = "0.23";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,5 +1,5 @@
 /** 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.21";
+export const LANGUAGE_VERSION = "0.23";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omgbase/oqx",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "OQX (omgbase Query eXpressions): a composable query language and engine for JavaScript collections",
   "keywords": [
     "query",

package/src/ast.ts

@@ -26,8 +26,26 @@ export type RelOp = "==" | "!=" | "<" | "<=" | ">" | ">=";
 /** The identity operators (SEMANTICS §5b, since 0.17). */
 export type IdentityOp = "is" | "is not";
 
-/** The operator of a `binary` expression: a comparison, an identity test, or arithmetic. */
-export type BinaryOp = RelOp | IdentityOp | "+" | "-" | "*" | "/" | "%";
+/** The infix regex operators (SEMANTICS §11, since 0.22): sugar over `matches` —
+ * `a ~ b` ≡ `a.matches(b)`, `a ~* b` ≡ `a.matches(b, "i")`, `a !~ b` ≡
+ * `!a.matches(b)`, `a !~* b` ≡ `!a.matches(b, "i")`. The tree keeps the
+ * operator as written so the canonical print is what the user wrote. */
+export type RegexOp = "~" | "~*" | "!~" | "!~*";
+
+/** The operator of a `binary` expression: a comparison, an identity test, a regex match, or arithmetic. */
+export type BinaryOp = RelOp | IdentityOp | RegexOp | "+" | "-" | "*" | "/" | "%";
+
+/** The regex operators, with the `matches` call each stands for. */
+export const REGEX_OPS: Readonly<Record<RegexOp, { negated: boolean; flags: string | undefined }>> = {
+  "~": { negated: false, flags: undefined },
+  "~*": { negated: false, flags: "i" },
+  "!~": { negated: true, flags: undefined },
+  "!~*": { negated: true, flags: "i" },
+};
+
+export function isRegexOp(op: string): op is RegexOp {
+  return Object.hasOwn(REGEX_OPS, op);
+}
 
 /** The operator of a `unary` expression. */
 export type UnaryOp = "!" | "-";

package/src/engine.ts

@@ -22,6 +22,7 @@
 import type {
   Query, Where, Expr, OpNode, SelectItem, OrderSpec, Follow, Subquery,
 } from "./ast.ts";
+import { isRegexOp, REGEX_OPS } from "./ast.ts";
 import type { DataContext } from "./context.ts";
 import { DefaultContext } from "./context.ts";
 import { OqxError } from "./errors.ts";
@@ -877,6 +878,15 @@ export class InMemoryEngine implements Engine {
           const same = canonicalKey(this.hostIdentity(l)) === canonicalKey(this.hostIdentity(r));
           return e.op === "is" ? same : !same;
         }
+        if (isRegexOp(e.op)) {
+          // The regex operators (SEMANTICS §11, since 0.22) are sugar over
+          // `matches`: `a ~ b` is `a.matches(b)`, `~*` adds the `i` flag, `!~`
+          // / `!~*` negate. They go through the same method dispatch as the
+          // call would, so a host's `matches` (and its regex dialect) applies.
+          const { negated, flags } = REGEX_OPS[e.op];
+          const hit = this.callMethod("matches", l, flags === undefined ? [r] : [r, flags]);
+          return negated ? !truthy(hit) : hit;
+        }
         return isRelOp(e.op) ? relate(e.op, l, r) : arith(e.op, l, r);
       }
       case "logical": {
@@ -978,9 +988,15 @@ export class InMemoryEngine implements Engine {
       throw new OqxError(`unknown function '${e.name}(…)'`, "eval");
     }
     const recv = this.evalExpr(e.recv, scope);
-    const r = this.ctx.callMethod?.(e.name, recv, args);
+    return this.callMethod(e.name, recv, args);
+  }
+
+  // `recv.name(args)` on evaluated values — the dispatch a method call and the
+  // regex operators share.
+  private callMethod(name: string, recv: unknown, args: unknown[]): unknown {
+    const r = this.ctx.callMethod?.(name, recv, args);
     if (r?.handled) return r.value;
-    throw new OqxError(`unknown method '.${e.name}(…)'`, "eval");
+    throw new OqxError(`unknown method '.${name}(…)'`, "eval");
   }
 }
 

package/src/index.ts

@@ -53,11 +53,13 @@ export { IndexedCollection } from "./adapters/indexed.ts";
 export { ROWS_ROOT, partitionPushable, residualQuery, asEquality, isConst, constValue } from "./plan.ts";
 export * as semantics from "./semantics.ts";
 export type * from "./ast.ts";
-export { isExpr } from "./ast.ts";
+export { isExpr, isRegexOp, REGEX_OPS } from "./ast.ts";
 export { parseTemplate } from "./parser.ts";
 export { rawSource, toUtf16, codePointLength } from "./lexer.ts";
 export { resolveAliases } from "./resolve.ts";
 export type { Clause, VisitContext, Visitor, ChildKey, Stripped } from "./walk.ts";
+export type { Reference, ReferenceScope, ReferenceStep } from "./references.ts";
+export { references } from "./references.ts";
 export { CHILDREN, visit, transform, stripSpans, toJSON } from "./walk.ts";
 export type { Template } from "./print.ts";
 export { print, printTemplate } from "./print.ts";

package/src/lexer.ts

@@ -44,7 +44,7 @@ export type TokType =
   | "caret" // ^ — one-scope lift marker
   | "dot"
   | "range" // `..` (inclusive) or `...` (exclusive end) — a Ruby-style range operator (value carries which)
-  | "op" // == != <= >= < > && || ! + - * / %  (value carries the operator)
+  | "op" // == != <= >= < > && || ! + - * / % ~ ~* !~ !~*  (value carries the operator)
   | "binding" // a ${…} interpolation; `index` names the value slot
   // A template literal (since 0.21): the opening and closing backticks, a run of
   // its decoded text, and the `${` / `}` around an interpolation — whose `}` is a
@@ -72,8 +72,12 @@ export interface Token {
 const KEYWORDS = new Set(["from", "where", "select", "is", "not", "and", "or"]);
 
 // Multi-char operators, longest first (the scanner tries these before singles).
-const MULTI_OPS = ["==", "!=", "<=", ">=", "&&", "||"];
-const SINGLE_OPS = new Set(["<", ">", "!", "+", "-", "*", "/", "%"]);
+// The regex operators (since 0.22) are among them: `!~*` is tried before `!~`,
+// which is tried before `!` — so `name!~"B"` is `name !~ "B"`, not a required
+// `name!` — and `~*` before `~`, so `x~*y` is `x ~* y`.
+const TRIPLE_OPS = ["!~*"];
+const MULTI_OPS = ["==", "!=", "<=", ">=", "&&", "||", "!~", "~*"];
+const SINGLE_OPS = new Set(["<", ">", "!", "+", "-", "*", "/", "%", "~"]);
 
 const isIdentStart = (c: string): boolean => /^[A-Za-z_$]$/.test(c);
 const isIdentPart = (c: string): boolean => /^[A-Za-z0-9_$]$/.test(c);
@@ -246,7 +250,9 @@ function lexFragment(src: string, base: number, out: Token[]): void {
       continue;
     }
 
-    // operators (multi-char first)
+    // operators (multi-char first, longest first)
+    const three = c + at(i + 1) + at(i + 2);
+    if (TRIPLE_OPS.includes(three)) { push("op", three, i, i + 3); i += 3; continue; }
     const two = c + at(i + 1);
     if (MULTI_OPS.includes(two)) { push("op", two, i, i + 2); i += 2; continue; }
     if (SINGLE_OPS.has(c)) { push("op", c, i, i + 1); i++; continue; }

package/src/optimize/analysis.ts

@@ -16,6 +16,7 @@
 //     value into an enclosing scope (§19), observable by later conjuncts.
 
 import type { Expr, Follow, OpNode, SelectItem, Subquery, Where } from "../ast.ts";
+import { isRegexOp } from "../ast.ts";
 import type { RuleContext } from "./ir.ts";
 
 // ---- scope reads --------------------------------------------------------------
@@ -99,7 +100,10 @@ export function exprRaiseFree(e: Expr, ctx: RuleContext): boolean {
     case "op": return opRaiseFree(e, ctx); // a value-position directive projects: never raise-free
     case "member": return exprRaiseFree(e.recv, ctx);
     case "unary": return exprRaiseFree(e.expr, ctx);
-    case "binary": case "logical": case "in": return exprRaiseFree(e.left, ctx) && exprRaiseFree(e.right, ctx);
+    // A regex operator (0.22) is a `matches` call in disguise: the pattern may
+    // be invalid, so it is never raise-free.
+    case "binary": return !isRegexOp(e.op) && exprRaiseFree(e.left, ctx) && exprRaiseFree(e.right, ctx);
+    case "logical": case "in": return exprRaiseFree(e.left, ctx) && exprRaiseFree(e.right, ctx);
     case "range": return (e.lo === null || exprRaiseFree(e.lo, ctx)) && (e.hi === null || exprRaiseFree(e.hi, ctx));
     case "tuple": return e.items.every((x) => exprRaiseFree(x, ctx));
     // A template literal raises on a list or record interpolation (§7b), which

package/src/parser.ts

@@ -109,7 +109,10 @@ const CLAUSE_WORDS = new Set<string>([
   "limit", "offset",
 ]);
 const RELOPS = new Set<string>(["==", "!=", "<", "<=", ">", ">="]);
-const CMP_OPS = new Set<string>(["==", "!=", "<", "<=", ">", ">="]);
+// The comparison level (GRAMMAR §4): the six relational operators and, since
+// 0.22, the four regex operators — sugar over `matches`, non-associative like
+// the rest of the level.
+const CMP_OPS = new Set<string>(["==", "!=", "<", "<=", ">", ">=", "~", "~*", "!~", "!~*"]);
 const ADD_OPS = new Set<string>(["+", "-"]);
 const MUL_OPS = new Set<string>(["*", "/", "%"]);
 // `true`/`false`/`null` are literals in every position, so they can never name a

package/src/print.ts

@@ -69,6 +69,7 @@ function prec(e: Expr): number {
     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;
+    // Comparison, identity and the regex operators (0.22) share the cmp level.
     case "binary": return e.op === "+" || e.op === "-" ? ADD : e.op === "*" || e.op === "/" || e.op === "%" ? MUL : CMP;
     case "in": return CMP;
     case "range": return RANGE;