@omgbase/oqx 0.14.0 → 0.15.0

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/ast.ts

@@ -14,7 +14,7 @@ export type RelOp = "==" | "!=" | "<" | "<=" | ">" | ">=";
 /** Scalar value/predicate expression, evaluated against a row scope + bindings. */
 export type Expr =
   | { kind: "lit"; value: string | number | boolean | null }
-  | { kind: "ident"; name: string } // bare property of the CURRENT row/scope only (never climbs); `$value` is the row itself
+  | { kind: "ident"; name: string } // bare property of the CURRENT row/scope only (never climbs); `$it` is the row itself
   | { kind: "outer"; levels: number; name: string } // `^name` — read from exactly `levels` scopes out
   | { kind: "binding"; index: number } // a ${…} interpolated host value
   | { kind: "member"; recv: Expr; name: string } // .prop navigation on the value to its left
@@ -81,7 +81,7 @@ export interface Subquery {
   follow: Follow | null;
   /** `values` — scalar projection mode: the (single) projected expression is the
    * row's result itself rather than being wrapped in a `{ name: value }` record,
-   * so `name values` yields `["Bob", …]` and `$value values` yields the rows. */
+   * so `name values` yields `["Bob", …]` and `$it values` yields the rows. */
   values?: boolean;
   /** `limit N` / `offset N` — bound the row set AFTER where/order/distinct and
    * BEFORE the consumer reduces it, so `count { … limit 5 }` is at most 5 and

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 {