@omgbase/oqx 0.14.0 → 0.14.1

package/dist/optimize/rules.d.ts

@@ -0,0 +1,8 @@
+import type { Rule } from "./ir.js";
+export declare const correlatedEqualityProbe: Rule;
+export declare const stableReceiver: Rule;
+export declare const invariantBlock: Rule;
+export declare const cardinalityOnly: Rule;
+/** The rules the engine applies by default, in order. */
+export declare const DEFAULT_RULES: readonly Rule[];
+//# sourceMappingURL=rules.d.ts.map

package/dist/optimize/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/optimize/rules.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAe,IAAI,EAAe,MAAM,SAAS,CAAC;AA2B9D,eAAO,MAAM,uBAAuB,EAAE,IAgBrC,CAAC;AA6BF,eAAO,MAAM,cAAc,EAAE,IAI5B,CAAC;AAiBF,eAAO,MAAM,cAAc,EAAE,IAK5B,CAAC;AAkBF,eAAO,MAAM,eAAe,EAAE,IAM7B,CAAC;AAEF,yDAAyD;AACzD,eAAO,MAAM,aAAa,EAAE,SAAS,IAAI,EAA+E,CAAC"}

package/dist/optimize/rules.js

@@ -0,0 +1,136 @@
+// The rule catalog. Each rule states its precondition and the argument that the
+// rewritten plan is indistinguishable from the scan it replaces — same rows in
+// the same order, same lifts, same error (same message) at the same point, or
+// no error — under SEMANTICS §13's strict left-to-right `&&`.
+import { exprRaiseFree, exprReadsCurrentScope, exprReadsScopeIn, localPath, opHasLifts, opReadsScopeIn, whereHasLifts, whereRaiseFree, } from "./analysis.js";
+import { conjunction, conjuncts } from "./ir.js";
+// ---- rule 1: correlated equality → hash probe ------------------------------------
+//
+// Precondition. The block has no `from` re-projection (its rows ARE the
+// receiver's rows) and no `follow`; its `where` has no lift anywhere (a lift
+// into an enclosing scope by one row could change what the outer side reads
+// for the next row); some top-level conjunct k is `local == outer` (either
+// side) with `local` an identifier/member chain on the block's row and `outer`
+// a raise-free expression reading nothing from the block's row; and every
+// conjunct left of k is raise-free (no call, no `single`, no lift, no bound, no
+// binding past the run's count).
+//
+// Argument. The scan evaluates, per receiver row r in order, c1(r) && … &&
+// ck(r) && …, short-circuiting. The probe selects exactly the rows with
+// local(r) == outer (the index reproduces §5 equality, `outer` is evaluated
+// once because nothing in the block can change what it reads) and evaluates the
+// residual conjunction over them, in receiver order. For a selected row every
+// conjunct is evaluated as the scan would (ck is dropped: it is true by
+// construction and, being two reads, cannot raise or bind). For a row the probe
+// rejects, the scan would have evaluated c1..c(k-1) — which cannot raise or
+// bind — then ck, false, and stopped: no result, no error, no lift. So the two
+// paths keep the same rows, raise the same first error, and bind the same
+// lifts. A probe that cannot be built at run time (a receiver that is not
+// stable, an index whose construction throws) falls back to the scan itself.
+export const correlatedEqualityProbe = (plan, ctx) => {
+    if (plan.correlated.length > 0 || plan.from.length > 0 || plan.follow || !plan.where)
+        return null;
+    if (whereHasLifts(plan.where))
+        return null;
+    const correlated = [];
+    const residual = [];
+    let prefixRaiseFree = true;
+    conjuncts(plan.where).forEach((part, index) => {
+        const eq = prefixRaiseFree ? asCorrelation(part, index, ctx) : null;
+        if (eq)
+            correlated.push(eq);
+        else {
+            residual.push(part);
+            prefixRaiseFree &&= whereRaiseFree(part, ctx);
+        }
+    });
+    if (correlated.length === 0)
+        return null;
+    return { ...plan, correlated, residual: conjunction(residual) };
+};
+/** `local == outer` / `outer == local` as a correlation, else null. */
+function asCorrelation(w, index, ctx) {
+    if (w.kind !== "scalar" || w.expr.kind !== "binary" || w.expr.op !== "==")
+        return null;
+    const { left, right } = w.expr;
+    return pair(left, right, index, ctx) ?? pair(right, left, index, ctx);
+}
+function pair(local, outer, index, ctx) {
+    const path = localPath(local);
+    if (path === null)
+        return null;
+    if (exprReadsCurrentScope(outer) || !exprRaiseFree(outer, ctx))
+        return null;
+    return { local, outer, path, index };
+}
+// ---- rule 1b: a receiver stable across enclosing rows ----------------------------
+//
+// Precondition. The receiver expression, read in the enclosing scope (depth
+// `plan.depth`), reads no scope at depth 1..depth: only the root (named roots,
+// `^…^name` reaching it, or past it) and bindings.
+//
+// Argument. Such an expression yields the same value for every enclosing row
+// (evaluation is pure; the root and the bindings do not change within a run),
+// so its rows can be materialized once per run and indexed once per path. A
+// receiver that does read an enclosing row is still indexable when it happens
+// to evaluate to the same object twice (the engine keys indexes by collection
+// identity as well); a receiver that yields a fresh value per row is scanned.
+export const stableReceiver = (plan) => {
+    if (plan.receiverStable)
+        return null;
+    if (exprReadsScopeIn(plan.receiver, plan.depth, plan.depth))
+        return null;
+    return { ...plan, receiverStable: true };
+};
+// ---- rule 2: invariant nested block → evaluate once per run ----------------------
+//
+// Precondition. Nothing in the block — receiver, `from`, `where`, `select`,
+// `order by`, bound, `follow` — reads a scope at depth 1..depth (an enclosing
+// row), and the block lifts nothing (a lift is a side effect on an enclosing
+// scope that must recur per row).
+//
+// Argument. The block's value is a function of the root scope, the bindings
+// and its own rows only, all constant within a run, so every evaluation yields
+// the same value or raises the same error. The engine evaluates it the first
+// time the scan would (so an error surfaces at the same point) and returns the
+// memoized value afterwards; a run that raised never reaches a second
+// evaluation. The memoized value is shared by reference across the enclosing
+// rows that project it.
+export const invariantBlock = (plan) => {
+    if (plan.invariant)
+        return null;
+    if (opHasLifts(plan.node))
+        return null;
+    if (opReadsScopeIn(plan.node, plan.depth, plan.depth))
+        return null;
+    return { ...plan, invariant: true };
+};
+// ---- rule 3: exists / none / count from cardinality -------------------------------
+//
+// Precondition. A where-position `exists`, `none` or `count` without `distinct`
+// (dedup projects every row), without `order by` (`count` evaluates the keys),
+// without `follow`, and with nothing left to evaluate per row: either the block
+// has no `where`, or every conjunct is correlated (so the probe's bucket is the
+// matched set).
+//
+// Argument. With no residual predicate the matched rows are exactly the
+// accessed rows (§13: the receiver's rows filtered by `where`), entering a row
+// as a scope cannot raise, and the consumers only need the count after the
+// bound (§18): `count` is `boundedCount(n)`, `exists` is `boundedCount(n) > 0`,
+// `none` its negation — what the scan computes after materializing. When the
+// probe is unavailable at run time the residual is the whole `where` and the
+// engine takes the per-row path.
+export const cardinalityOnly = (plan) => {
+    if (plan.fromCardinality)
+        return null;
+    if (plan.consumer !== "exists" && plan.consumer !== "none" && plan.consumer !== "count")
+        return null;
+    if (plan.distinct || plan.orderBy || plan.follow)
+        return null;
+    if (plan.where !== null && plan.residual !== null)
+        return null;
+    return { ...plan, fromCardinality: true };
+};
+/** The rules the engine applies by default, in order. */
+export const DEFAULT_RULES = [correlatedEqualityProbe, stableReceiver, invariantBlock, cardinalityOnly];
+//# sourceMappingURL=rules.js.map

package/dist/optimize/rules.js.map

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

package/package.json

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

package/src/adapters/indexed.ts

@@ -1,38 +1,66 @@
 // An in-memory optimizing planner: it hash-indexes a named root collection on
-// chosen fields and, for a query whose where-clause contains equality predicates
-// on those fields, answers from the index (candidate intersection) instead of a
-// full scan. Everything it can't turn into an index probe is left as a residual
-// query the in-memory engine finishes over the candidate rows.
+// chosen fields and, for a query whose where-clause contains equality
+// predicates on those fields, answers from the index (candidate intersection)
+// instead of a full scan. Everything it can't turn into an index probe is left
+// as a residual query the in-memory engine finishes over the candidate rows.
 //
 // This is the smallest honest demonstration of plan optimization: same answers
 // as a naive scan, far fewer rows examined, and partial-pushdown correctness via
 // the residual.
+//
+// The same indexes serve the engine's correlated probes: `context()` is a
+// `DataContext` that resolves the root and answers `indexFor(collection, path)`
+// from them, so a nested `^emp first { where id == ^manager_id }` probes the
+// pre-built index instead of building one per run. The planner's own plans
+// carry that context too, so a residual's nested blocks still see every root.
+//
+// Buckets are keyed under OQX equality (`HashIndex`): absent ≡ null, `-0` ≡ `0`,
+// `NaN` matches nothing, objects by reference — exactly what `==` compares, so
+// a probe returns the rows the scan would keep (a plain `Map` would keep `null`
+// and `undefined` apart and match `NaN` to itself).
 
 import type { Query } from "../ast.ts";
+import type { DataContext } from "../context.ts";
+import { DefaultContext } from "../context.ts";
 import type { Plan, QueryPlanner } from "../planner.ts";
-import { partitionPushable, residualQuery, asEquality, constValue } from "../plan.ts";
+import { partitionPushable, residualQuery, asEquality, constValue, ROWS_ROOT } from "../plan.ts";
+import type { RowIndex } from "../optimize/hash-index.ts";
+import { HashIndex, intersectPositions } from "../optimize/hash-index.ts";
 
 export class IndexedCollection implements QueryPlanner {
   private name: string;
   private rows: readonly unknown[];
-  private indexes = new Map<string, Map<unknown, unknown[]>>();
+  private indexes = new Map<string, HashIndex>();
 
-  /** Index `rows` (exposed as root `name`) on each field in `indexFields`. */
+  /** Index `rows` (exposed as root `name`) on each field in `indexFields`. A
+   * field is read as the engine reads a bare identifier (own property; array
+   * element for an integer-spelled name); a row without it keys as absent. */
   constructor(name: string, rows: readonly unknown[], indexFields: readonly string[]) {
     this.name = name;
     this.rows = rows;
+    const read = new DefaultContext();
     for (const field of indexFields) {
-      const idx = new Map<unknown, unknown[]>();
-      for (const row of rows) {
-        const key = (row as Record<string, unknown>)?.[field];
-        let bucket = idx.get(key);
-        if (!bucket) idx.set(key, (bucket = []));
-        bucket.push(row);
-      }
+      const idx = new HashIndex();
+      rows.forEach((row, i) => idx.add(read.get(row, field), i));
       this.indexes.set(field, idx);
     }
   }
 
+  /** The pre-built index for `collection` on `path` when `collection` is this
+   * collection's rows and `path` is one indexed field — the `DataContext.indexFor`
+   * seam, which `context()` wires up. */
+  indexFor(collection: unknown, path: readonly string[]): RowIndex | undefined {
+    if (collection !== this.rows || path.length !== 1) return undefined;
+    return this.indexes.get(path[0]!);
+  }
+
+  /** A `DataContext` over plain objects that serves this collection as the
+   * root `name` (plus `extraRoots`) and exposes the indexes through
+   * `indexFor`, so the engine's correlated probes reuse them. */
+  context(extraRoots: Record<string, unknown> = {}): DataContext {
+    return new IndexedContext(this, { ...extraRoots, [this.name]: this.rows });
+  }
+
   plan(query: Query, params: readonly unknown[]): Plan | null {
     if (query.source.kind !== "ident" || query.source.name !== this.name) return null;
     if (query.from.length > 0 || query.follow) return null;
@@ -44,18 +72,26 @@ export class IndexedCollection implements QueryPlanner {
     if (pushed.length === 0) return null; // no index probe available — let the scan handle it
 
     // Intersect the candidate sets from each indexed equality (smallest first).
-    let candidate: unknown[] | null = null;
-    for (const e of pushed) {
+    const buckets = pushed.map((e) => {
       const eq = asEquality(e)!;
-      const bucket = this.indexes.get(eq.field)!.get(constValue(eq.value, params)) ?? [];
-      candidate = candidate === null ? bucket.slice() : intersect(candidate, bucket);
-    }
-    const rows = candidate ?? [];
-    return { rows: () => rows, residual: residualQuery(query, residual) };
+      return this.indexes.get(eq.field)!.lookup(constValue(eq.value, params));
+    }).sort((a, b) => a.length - b.length);
+    let candidate = buckets[0]!;
+    for (let i = 1; i < buckets.length && candidate.length > 0; i++) candidate = intersectPositions(candidate, buckets[i]!);
+    const rows = candidate.map((i) => this.rows[i]);
+    return { rows: () => rows, residual: residualQuery(query, residual), context: this.context({ [ROWS_ROOT]: rows }) };
   }
 }
 
-function intersect(a: unknown[], b: unknown[]): unknown[] {
-  const set = new Set(b);
-  return a.filter((x) => set.has(x));
+class IndexedContext extends DefaultContext {
+  private owner: IndexedCollection;
+
+  constructor(owner: IndexedCollection, roots: Record<string, unknown>) {
+    super(roots);
+    this.owner = owner;
+  }
+
+  indexFor(collection: unknown, path: readonly string[]): RowIndex | undefined {
+    return this.owner.indexFor(collection, path);
+  }
 }

package/src/context.ts

@@ -10,6 +10,7 @@
 
 import { coerceCollection, regexMatches, BUILTIN_FUNCTIONS, BUILTIN_METHODS } from "./semantics.ts";
 import type { RegexDialect } from "./regex.ts";
+import type { RowIndex } from "./optimize/hash-index.ts";
 
 // An array's only properties are its integer indices, spelled canonically
 // (`"0"`, `"12"`; never `"01"`, `"length"`, or a method name).
@@ -36,6 +37,18 @@ export interface DataContext {
   get(row: unknown, key: string): unknown;
   /** Coerce a relation/source value into rows (may be lazy). */
   toRows(value: unknown): Iterable<unknown>;
+  /** Optional: a value this context handed out as a stand-in for a collection
+   * it has not read yet (a lazy table handle), resolved to what it stands for.
+   * The engine calls it on every value it is about to observe AS A VALUE — an
+   * operand of `==`/`in`/arithmetic, a function or method argument, a projected
+   * item, an `order by` or `distinct` key, a `where` scalar, a lift — and never
+   * on a value it reads in ROW POSITION (the query source, a block receiver, a
+   * body-level `from`, a `follow` destination), which reaches `toRows` and
+   * `indexFor` as handed out, so a store-backed context can answer a probe on
+   * the handle without reading the table and still never lets the stand-in be
+   * seen by the language. Absent = identity; a context whose handle already
+   * behaves as the collection (a `Proxy` over an array) needs none. */
+  materialize?(value: unknown): unknown;
   /** Identity of a row for `follow` cycle detection / dedup. */
   identity(row: unknown): unknown;
   /** Optional custom free function; return `{ handled: false }` to defer. */
@@ -50,6 +63,17 @@ export interface DataContext {
    * `regexMatches(recv, args, dialect)` is the helper). `BUILTIN_METHODS.matches`
    * is always the baseline. */
   readonly regexDialect?: RegexDialect;
+  /** Optional: a pre-built equality index over `collection` (a value this
+   * context served as a root or relation) on the property path `path`
+   * (`["customer_id"]`, `["meta", "id"]`; `[]` keys by the row itself). The
+   * engine asks before building its own hash index for a correlated equality
+   * in a nested block (`where id == ^customer_id`); return `undefined` to let
+   * it build one. `lookup(value)` must return the ascending positions, into
+   * `toRows(collection)` in order, of the rows whose value at `path` equals
+   * `value` under OQX equality (SEMANTICS §5: absent ≡ null, `-0` ≡ `0`, `NaN`
+   * matches nothing, objects by reference). `IndexedCollection.context()`
+   * implements it over its indexes. */
+  indexFor?(collection: unknown, path: readonly string[]): RowIndex | undefined;
 }
 
 export interface DefaultContextOptions {