@omgbase/oqx 0.1.0 → 0.3.0

package/README.md

@@ -1,4 +1,4 @@
-# oqx
+# @omgbase/oqx
 
 **Generic Object Query eXpression engine for JavaScript.**
 
@@ -9,7 +9,7 @@ the OQX language semantics separated from any particular data model, exposed as
 JavaScript tagged template.
 
 ```js
-import { oqx } from "oqx";
+import { oqx } from "@omgbase/oqx";
 
 const people = [
   { name: "Bob", id: 124, title: "Engineer",
@@ -301,21 +301,29 @@ oqx`id, depth: $depth from ${tree} follow children order by $depth, id`;
 ```
 
 Reached rows expose recursion **intrinsics** in `select` / `order by`:
-`$depth` (1-based), `$leaf` (no successors), `$frontier` (hit a boundary), and
-`$stop` (`"continue"` / `"leaf"` / `"depth"` / `"frontier"`). Options go in a
-trailing block:
+`$depth` (1-based), `$leaf` (no successors), `$frontier` (there is unfollowed
+graph beyond — a boundary or the depth cap), `$ordinal` (a deterministic 1..N
+rank over the walk, ordered by depth then path), and `$stop`
+(`"interior"` / `"leaf"` / `"frontier"` / `"depth"` / `"cycle"`, precedence
+cycle > frontier > depth > leaf > interior — only `interior` rows expand). Options
+go in a trailing block:
 
 ```js
-oqx`id, stop: $stop from ${tree} follow children { depth 2 } order by id`;
+oqx`id, stop: $stop from ${tree} follow children { depth 2 } order by $ordinal`;
 // a1 is never reached; a and b report stop:"depth"
 ```
 
+The walk is **per-path**: a node reached by N distinct paths yields N
+occurrences, and revisiting an identity already on the current path is admitted
+**once** as `$stop == "cycle"` and never re-expanded, so cycles terminate without
+runaway. `follow distinct` collapses occurrences to reached nodes (the minimal
+`(depth, path)` per identity).
+
 The block accepts: `where <succ>` (which successors keep participating),
 `frontier <pred>` (cut a relation that could continue), `depth <n>` (1–8), and
-`by <expr>` (the identity used for cycle/duplicate detection — default `.id` or the
-object reference). Reached rows are de-duplicated by that identity, so cycles
-terminate. Give `follow` a stable identity (`.id` or `by`) when your relation
-returns fresh objects rather than shared references.
+`by <expr>` (the identity used for cycle detection + `distinct` — default `.id`
+or the object reference). Give `follow` a stable identity (`.id` or `by`) when
+your relation returns fresh objects rather than shared references.
 
 ### Cheat-sheet
 
@@ -336,7 +344,7 @@ When you don't need interpolation, `execute` runs a plain string query against a
 **data context** of named roots:
 
 ```js
-import { execute } from "oqx";
+import { execute } from "@omgbase/oqx";
 
 execute("name from people where age >= 18", { people });
 // `from people` resolves the `people` root
@@ -370,7 +378,7 @@ compute identity. Implement it to query an ORM graph, a remote API, or lazily
 loaded relations — the query *semantics* stay in OQX:
 
 ```js
-import { parse, run } from "oqx";
+import { parse, run } from "@omgbase/oqx";
 
 const graph = {
   root: (name) => name === "tree" ? [nodes.get(1)] : undefined,
@@ -391,14 +399,14 @@ likes and stay correct. Two adapters ship:
 
 - `IndexedCollection` — hash-indexes a collection and answers equality predicates
   from the index instead of scanning, leaving other predicates as residual.
-- `oqx/sqlite` — real pushdown to a `node:sqlite` database: the flat query core
+- `@omgbase/oqx/sqlite` — real pushdown to a `node:sqlite` database: the flat query core
   (scan + translatable conjunctive predicates, `LIMIT` for unordered
   `first`/`single`) becomes SQL; `matches()`, nested consumer ops, `follow`, etc.
   fall back to the in-memory residual.
 
 ```js
-import { parse, PlannedEngine } from "oqx";
-import { SqliteTable } from "oqx/sqlite";
+import { parse, PlannedEngine } from "@omgbase/oqx";
+import { SqliteTable } from "@omgbase/oqx/sqlite";
 
 const planner = new SqliteTable(db, "emp", { columns: ["id", "name", "dept", "level"] });
 new PlannedEngine(planner).run(parse('name from emp where dept == "eng" && level >= 5'), []);

package/dist/adapters/indexed.d.ts

@@ -0,0 +1,11 @@
+import type { Query } from "../ast.js";
+import type { Plan, QueryPlanner } from "../planner.js";
+export declare class IndexedCollection implements QueryPlanner {
+    private name;
+    private rows;
+    private indexes;
+    /** Index `rows` (exposed as root `name`) on each field in `indexFields`. */
+    constructor(name: string, rows: readonly unknown[], indexFields: readonly string[]);
+    plan(query: Query, params: readonly unknown[]): Plan | null;
+}
+//# sourceMappingURL=indexed.d.ts.map

package/dist/adapters/indexed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexed.d.ts","sourceRoot":"","sources":["../../src/adapters/indexed.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGxD,qBAAa,iBAAkB,YAAW,YAAY;IACpD,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,OAAO,CAA8C;IAE7D,4EAA4E;gBAChE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE;IAelF,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,GAAG,IAAI;CAoB5D"}

package/dist/adapters/indexed.js

@@ -0,0 +1,57 @@
+// 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.
+//
+// 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.
+import { partitionPushable, residualQuery, asEquality, constValue } from "../plan.js";
+export class IndexedCollection {
+    name;
+    rows;
+    indexes = new Map();
+    /** Index `rows` (exposed as root `name`) on each field in `indexFields`. */
+    constructor(name, rows, indexFields) {
+        this.name = name;
+        this.rows = rows;
+        for (const field of indexFields) {
+            const idx = new Map();
+            for (const row of rows) {
+                const key = row?.[field];
+                let bucket = idx.get(key);
+                if (!bucket)
+                    idx.set(key, (bucket = []));
+                bucket.push(row);
+            }
+            this.indexes.set(field, idx);
+        }
+    }
+    plan(query, params) {
+        if (query.source.kind !== "ident" || query.source.name !== this.name)
+            return null;
+        if (query.from.length > 0 || query.follow)
+            return null;
+        const { pushed, residual } = partitionPushable(query.where, (e) => {
+            const eq = asEquality(e);
+            return eq != null && this.indexes.has(eq.field);
+        });
+        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 = null;
+        for (const e of pushed) {
+            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) };
+    }
+}
+function intersect(a, b) {
+    const set = new Set(b);
+    return a.filter((x) => set.has(x));
+}
+//# sourceMappingURL=indexed.js.map

package/dist/adapters/indexed.js.map

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

package/dist/adapters/sqlite.d.ts

@@ -0,0 +1,23 @@
+import { DatabaseSync } from "node:sqlite";
+import type { Query } from "../ast.js";
+import type { Plan, QueryPlanner } from "../planner.js";
+export interface SqliteTableOptions {
+    /** Columns that map to bare OQX fields (only these are pushable). */
+    columns: readonly string[];
+    /** Columns whose stored text should be JSON.parse'd back into row values. */
+    jsonColumns?: readonly string[];
+    /** Custom mapper from a raw SQL row to a query row (overrides jsonColumns). */
+    map?: (raw: Record<string, unknown>) => unknown;
+}
+export declare class SqliteTable implements QueryPlanner {
+    private db;
+    private table;
+    private columns;
+    private opts;
+    constructor(db: DatabaseSync, table: string, opts: SqliteTableOptions);
+    plan(query: Query, params: readonly unknown[]): Plan | null;
+    private translatable;
+    private translate;
+    private mapRow;
+}
+//# sourceMappingURL=sqlite.d.ts.map

package/dist/adapters/sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/adapters/sqlite.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAQ,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGxD,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,+EAA+E;IAC/E,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;CACjD;AAOD,qBAAa,WAAY,YAAW,YAAY;IAC9C,OAAO,CAAC,EAAE,CAAe;IACzB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,IAAI,CAAqB;gBAErB,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB;IAOrE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,GAAG,IAAI;IAsB3D,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,SAAS;IAkBjB,OAAO,CAAC,MAAM;CAWf"}

package/dist/adapters/sqlite.js

@@ -0,0 +1,113 @@
+// A real storage adapter: pushes the flat core of an OQX query (source scan +
+// translatable conjunctive predicates, and a LIMIT for unordered first/single)
+// into SQL over Node's built-in `node:sqlite`, and leaves everything it can't
+// translate — nested consumer ops, `follow`, negation/disjunction, method calls
+// like matches(), custom functions — as a residual the in-memory engine finishes
+// over the rows SQL returned.
+//
+// This is imported on its own subpath (`oqx/sqlite`) so that plain consumers of
+// `oqx` never pull in the experimental `node:sqlite` module.
+//
+// Semantics note: OQX equality is typed and strict (see semantics.ts). SQL `=`
+// uses column affinity, so this adapter assumes a well-typed schema for the
+// columns it pushes; anything it cannot translate faithfully stays residual.
+import { DatabaseSync } from "node:sqlite";
+import { partitionPushable, residualQuery } from "../plan.js";
+const RELOP_SQL = {
+    "==": "=", "!=": "<>", "<": "<", "<=": "<=", ">": ">", ">=": ">=",
+};
+const ARITH_SQL = new Set(["+", "-", "*", "/", "%"]);
+export class SqliteTable {
+    db;
+    table;
+    columns;
+    opts;
+    constructor(db, table, opts) {
+        this.db = db;
+        this.table = table;
+        this.columns = new Set(opts.columns);
+        this.opts = opts;
+    }
+    plan(query, params) {
+        if (query.source.kind !== "ident" || query.source.name !== this.table)
+            return null;
+        if (query.from.length > 0 || query.follow)
+            return null;
+        const { pushed, residual } = partitionPushable(query.where, (e) => this.translatable(e));
+        const sqlParams = [];
+        const whereSql = pushed.map((e) => this.translate(e, params, sqlParams)).join(" AND ");
+        // A LIMIT is only safe when nothing is left to filter in-memory and the
+        // result is unordered (first/single are "some row" without an order by).
+        let tail = "";
+        if (!residual && !query.orderBy) {
+            if (query.consumer === "first")
+                tail = " LIMIT 1";
+            else if (query.consumer === "single")
+                tail = " LIMIT 2";
+        }
+        const sql = `SELECT * FROM "${this.table}"${whereSql ? ` WHERE ${whereSql}` : ""}${tail}`;
+        const raw = this.db.prepare(sql).all(...sqlParams.map(toSqlParam));
+        const rows = raw.map((r) => this.mapRow(r));
+        return { rows: () => rows, residual: residualQuery(query, residual) };
+    }
+    translatable(e) {
+        switch (e.kind) {
+            case "lit":
+            case "binding": return true;
+            case "ident": return this.columns.has(e.name);
+            case "unary": return (e.op === "!" || e.op === "-") && this.translatable(e.expr);
+            case "logical": return this.translatable(e.left) && this.translatable(e.right);
+            case "binary":
+                return (e.op in RELOP_SQL || ARITH_SQL.has(e.op)) && this.translatable(e.left) && this.translatable(e.right);
+            default: return false; // member/index/call/in → residual
+        }
+    }
+    translate(e, params, out) {
+        switch (e.kind) {
+            case "lit":
+                out.push(e.value);
+                return "?";
+            case "binding":
+                out.push(params[e.index]);
+                return "?";
+            case "ident": return `"${e.name}"`;
+            case "unary": return e.op === "!" ? `(NOT ${this.translate(e.expr, params, out)})` : `(-${this.translate(e.expr, params, out)})`;
+            case "logical": {
+                const op = e.op === "&&" ? "AND" : "OR";
+                return `(${this.translate(e.left, params, out)} ${op} ${this.translate(e.right, params, out)})`;
+            }
+            case "binary": {
+                const op = e.op in RELOP_SQL ? RELOP_SQL[e.op] : e.op;
+                return `(${this.translate(e.left, params, out)} ${op} ${this.translate(e.right, params, out)})`;
+            }
+            default: throw new Error(`sqlite: not translatable: ${e.kind}`);
+        }
+    }
+    mapRow(raw) {
+        if (this.opts.map)
+            return this.opts.map(raw);
+        if (this.opts.jsonColumns) {
+            const out = { ...raw };
+            for (const c of this.opts.jsonColumns) {
+                if (typeof out[c] === "string")
+                    out[c] = JSON.parse(out[c]);
+            }
+            return out;
+        }
+        return raw;
+    }
+}
+// node:sqlite accepts null | number | bigint | string | Uint8Array. Map the
+// common host values that appear as bound params.
+function toSqlParam(v) {
+    if (v === undefined || v === null)
+        return null;
+    if (typeof v === "boolean")
+        return v ? 1 : 0;
+    if (typeof v === "number" || typeof v === "bigint" || typeof v === "string")
+        return v;
+    if (v instanceof Uint8Array)
+        return v;
+    return String(v);
+}
+//# sourceMappingURL=sqlite.js.map

package/dist/adapters/sqlite.js.map

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

package/dist/ast.d.ts

@@ -0,0 +1,121 @@
+/** Query consumers — how a (sub)query's row set is shaped. */
+export type Consumer = "collect" | "exists" | "count" | "first" | "single";
+/** Comparison operators usable in a `count { … } <op> <int>` test. */
+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;
+} | {
+    kind: "outer";
+    levels: number;
+    name: string;
+} | {
+    kind: "binding";
+    index: number;
+} | {
+    kind: "member";
+    recv: Expr;
+    name: string;
+} | {
+    kind: "index";
+    recv: Expr;
+    index: Expr;
+} | {
+    kind: "call";
+    recv: Expr | null;
+    name: string;
+    args: Expr[];
+} | {
+    kind: "unary";
+    op: "!" | "-";
+    expr: Expr;
+} | {
+    kind: "binary";
+    op: string;
+    left: Expr;
+    right: Expr;
+} | {
+    kind: "logical";
+    op: "&&" | "||";
+    left: Expr;
+    right: Expr;
+} | {
+    kind: "in";
+    left: Expr;
+    right: Expr;
+};
+export interface OrderSpec {
+    expr: Expr;
+    desc: boolean;
+}
+/** One projection item: a named scalar/navigation value, or a named nested
+ * collection consumer. `lift` marks a `^name` one-scope lift. */
+export type SelectItem = {
+    kind: "field";
+    name: string;
+    expr: Expr;
+    lift: number;
+} | {
+    kind: "collect";
+    name: string;
+    op: OpNode;
+};
+/** A postfix consumer directive over a receiver collection:
+ * `<receiver> <op> { <sub> }`, optionally `count { … } <relop> <int>`. */
+export interface OpNode {
+    kind: "op";
+    receiver: Expr;
+    op: Consumer;
+    sub: Subquery;
+    countCmp?: {
+        op: RelOp;
+        value: number;
+    };
+}
+/** The recursive `follow` clause. */
+export interface Follow {
+    receiver: Expr;
+    distinct: boolean;
+    where: Expr | null;
+    frontier: Expr | null;
+    depth: number | null;
+    by: Expr | null;
+}
+/** A nested (sub)query body. */
+export interface Subquery {
+    from: Expr[];
+    where: Where | null;
+    select: SelectItem[];
+    orderBy: OrderSpec[] | null;
+    follow: Follow | null;
+}
+/** The where-clause boolean tree: OQX owns &&/||/!/grouping so consumer ops
+ * (invisible to the scalar evaluator) compose with scalar predicates. */
+export type Where = {
+    kind: "and";
+    parts: Where[];
+} | {
+    kind: "or";
+    parts: Where[];
+} | {
+    kind: "not";
+    expr: Where;
+} | {
+    kind: "scalar";
+    expr: Expr;
+} | OpNode;
+/** A top-level OQX query. */
+export interface Query {
+    source: Expr;
+    from: Expr[];
+    where: Where | null;
+    select: SelectItem[];
+    orderBy: OrderSpec[] | null;
+    consumer: Consumer;
+    follow: Follow | null;
+}
+//# sourceMappingURL=ast.d.ts.map

package/dist/ast.d.ts.map

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

package/dist/ast.js

@@ -0,0 +1,7 @@
+// OQX query AST for the generic kernel. The parser produces this directly and
+// the interpreter walks it — there is no separate lowering/IR pass, because a
+// "relation" in the generic kernel is just an expression evaluated against the
+// current row (property navigation on the host object model), resolved at run
+// time rather than against a fixed schema.
+export {};
+//# sourceMappingURL=ast.js.map

package/dist/ast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.js","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,8EAA8E;AAC9E,+EAA+E;AAC/E,8EAA8E;AAC9E,2CAA2C"}

package/dist/context.d.ts

@@ -0,0 +1,38 @@
+/** Result of a context-provided function/method call: `handled: false` tells the
+ * engine to fall back to the builtin table (or error if none). */
+export interface CallResult {
+    handled: boolean;
+    value?: unknown;
+}
+export interface DataContext {
+    /** Resolve a named root collection (the `from <name>` / directive receiver). */
+    root(name: string): unknown;
+    /** Read a property/relation off a row (`.field`, or a nav-expression segment). */
+    get(row: unknown, key: string): unknown;
+    /** Whether a row has a property — decides scope-climbing for a bare identifier
+     * (a present-but-undefined field stops the climb). Defaults to a key check. */
+    has?(row: unknown, key: string): boolean;
+    /** Coerce a relation/source value into rows (may be lazy). */
+    toRows(value: unknown): Iterable<unknown>;
+    /** Identity of a row for `follow` cycle detection / dedup. */
+    identity(row: unknown): unknown;
+    /** Optional custom free function; return `{ handled: false }` to defer. */
+    callFunction?(name: string, args: unknown[]): CallResult;
+    /** Optional custom method; return `{ handled: false }` to defer. */
+    callMethod?(name: string, recv: unknown, args: unknown[]): CallResult;
+}
+/** The default context: ordinary JavaScript objects. Named roots come from a
+ * plain `{ name: collection }` map; properties are own/inherited keys; identity
+ * is `.id` when present, else the object itself (reference identity). */
+export declare class DefaultContext implements DataContext {
+    private roots;
+    constructor(roots?: Record<string, unknown>);
+    root(name: string): unknown;
+    get(row: unknown, key: string): unknown;
+    has(row: unknown, key: string): boolean;
+    toRows(value: unknown): Iterable<unknown>;
+    identity(row: unknown): unknown;
+    callFunction(name: string, args: unknown[]): CallResult;
+    callMethod(name: string, recv: unknown, args: unknown[]): CallResult;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAYA;kEACkE;AAClE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,kFAAkF;IAClF,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC;mFAC+E;IAC/E,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACzC,8DAA8D;IAC9D,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC1C,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;IAChC,2EAA2E;IAC3E,YAAY,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,UAAU,CAAC;IACzD,oEAAoE;IACpE,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,UAAU,CAAC;CACvE;AAED;;yEAEyE;AACzE,qBAAa,cAAe,YAAW,WAAW;IAChD,OAAO,CAAC,KAAK,CAA0B;gBAE3B,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAI/C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI3B,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAKvC,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAIvC,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;IAIzC,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO;IAK/B,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,UAAU;IAKvD,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,UAAU;CAIrE"}

package/dist/context.js

@@ -0,0 +1,47 @@
+// The tier-2 seam: a DataContext binds OQX's query semantics to a concrete data
+// model. The engine never touches host objects directly — it asks the context to
+// resolve named roots, read properties/relations, coerce a relation result into
+// rows, compute identity (for `follow` dedup), and optionally supply custom
+// scalar functions/methods. This is what lets the same query semantics run over
+// plain objects, a lazy ORM graph, or a remote API without changing the engine.
+//
+// (Performant execution over a real store is the tier-3 seam — see planner.ts —
+// which pushes work into the store instead of driving it row-by-row here.)
+import { coerceCollection, BUILTIN_FUNCTIONS, BUILTIN_METHODS } from "./semantics.js";
+/** The default context: ordinary JavaScript objects. Named roots come from a
+ * plain `{ name: collection }` map; properties are own/inherited keys; identity
+ * is `.id` when present, else the object itself (reference identity). */
+export class DefaultContext {
+    roots;
+    constructor(roots = {}) {
+        this.roots = roots;
+    }
+    root(name) {
+        return this.roots[name];
+    }
+    get(row, key) {
+        if (row == null)
+            return undefined;
+        return Object(row)[key];
+    }
+    has(row, key) {
+        return row != null && typeof row === "object" && key in row;
+    }
+    toRows(value) {
+        return coerceCollection(value);
+    }
+    identity(row) {
+        if (row != null && typeof row === "object" && "id" in row)
+            return row.id;
+        return row;
+    }
+    callFunction(name, args) {
+        const fn = BUILTIN_FUNCTIONS[name];
+        return fn ? { handled: true, value: fn(args) } : { handled: false };
+    }
+    callMethod(name, recv, args) {
+        const fn = BUILTIN_METHODS[name];
+        return fn ? { handled: true, value: fn(recv, args) } : { handled: false };
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,iFAAiF;AACjF,gFAAgF;AAChF,4EAA4E;AAC5E,gFAAgF;AAChF,gFAAgF;AAChF,EAAE;AACF,gFAAgF;AAChF,2EAA2E;AAE3E,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AA2BtF;;yEAEyE;AACzE,MAAM,OAAO,cAAc;IACjB,KAAK,CAA0B;IAEvC,YAAY,QAAiC,EAAE;QAC7C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,IAAI,CAAC,IAAY;QACf,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,GAAG,CAAC,GAAY,EAAE,GAAW;QAC3B,IAAI,GAAG,IAAI,IAAI;YAAE,OAAO,SAAS,CAAC;QAClC,OAAQ,MAAM,CAAC,GAAG,CAA6B,CAAC,GAAG,CAAC,CAAC;IACvD,CAAC;IAED,GAAG,CAAC,GAAY,EAAE,GAAW;QAC3B,OAAO,GAAG,IAAI,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,IAAK,GAAc,CAAC;IAC1E,CAAC;IAED,MAAM,CAAC,KAAc;QACnB,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IAED,QAAQ,CAAC,GAAY;QACnB,IAAI,GAAG,IAAI,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,IAAI,IAAI,GAAG;YAAE,OAAQ,GAA+B,CAAC,EAAE,CAAC;QACtG,OAAO,GAAG,CAAC;IACb,CAAC;IAED,YAAY,CAAC,IAAY,EAAE,IAAe;QACxC,MAAM,EAAE,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACnC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACtE,CAAC;IAED,UAAU,CAAC,IAAY,EAAE,IAAa,EAAE,IAAe;QACrD,MAAM,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QACjC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5E,CAAC;CACF"}

package/dist/engine.d.ts

@@ -0,0 +1,49 @@
+import type { Query } from "./ast.js";
+import type { DataContext } from "./context.js";
+/** The shaped result of a top-level query, discriminated by consumer. */
+export type OqxResult = {
+    consumer: "collect";
+    rows: unknown[];
+} | {
+    consumer: "exists";
+    exists: boolean;
+} | {
+    consumer: "count";
+    count: number;
+} | {
+    consumer: "first";
+    row: unknown | null;
+} | {
+    consumer: "single";
+    row: unknown | null;
+};
+/** A backend that runs a parsed Query with the given positional bindings. */
+export interface Engine {
+    run(query: Query, bindings: readonly unknown[]): OqxResult;
+}
+export declare class InMemoryEngine implements Engine {
+    private ctx;
+    constructor(context?: DataContext);
+    run(query: Query, bindings?: readonly unknown[]): OqxResult;
+    private matches;
+    private rowsOf;
+    private child;
+    private runFollow;
+    private followWalk;
+    private shape;
+    private projectRow;
+    private evalWhere;
+    private evalWhereOp;
+    private anyMatch;
+    private iterMatchRows;
+    private matchRows;
+    private evalCollectValue;
+    private sortScopes;
+    private evalExpr;
+    private resolveFrom;
+    private has;
+    private evalCall;
+}
+/** Convenience: run a query with plain-object roots (the default context). */
+export declare function runQuery(query: Query, bindings: readonly unknown[], roots: unknown): OqxResult;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,KAAK,EACN,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAOhD,yEAAyE;AACzE,MAAM,MAAM,SAAS,GACjB;IAAE,QAAQ,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,OAAO,EAAE,CAAA;CAAE,GACxC;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACvC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,GAC1C;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,CAAC;AAEhD,6EAA6E;AAC7E,MAAM,WAAW,MAAM;IACrB,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC;CAC5D;AAaD,qBAAa,cAAe,YAAW,MAAM;IAC3C,OAAO,CAAC,GAAG,CAAc;gBAEb,OAAO,GAAE,WAAkC;IAIvD,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,GAAE,SAAS,OAAO,EAAO,GAAG,SAAS;IAoC/D,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,SAAS;IAuBjB,OAAO,CAAC,UAAU;IA6DlB,OAAO,CAAC,KAAK;IAYb,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,SAAS;IAcjB,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAE,aAAa;IAStB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,gBAAgB;IAwBxB,OAAO,CAAC,UAAU;IAwBlB,OAAO,CAAC,QAAQ;IAsChB,OAAO,CAAC,WAAW;IAiBnB,OAAO,CAAC,GAAG;IAKX,OAAO,CAAC,QAAQ;CAYjB;AAiED,8EAA8E;AAC9E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,CAG9F"}