@omgbase/oqx 0.1.0 → 0.3.0

package/dist/plan.js

@@ -0,0 +1,56 @@
+// Pushdown analysis helpers shared by planner adapters (tier 3). The unit of
+// pushdown here is the top-level `where` conjunction: an adapter classifies each
+// AND-conjunct as pushable (translatable into its native query) or residual
+// (must be evaluated in-memory afterward). Whatever it pushes reduces the rows it
+// produces; the residual Query re-runs over those rows in the in-memory engine,
+// which preserves correctness even for partial pushdown.
+//
+// Deliberately conservative: only positive scalar leaves are pushable. Consumer
+// ops (exists/count/collect), negation, and disjunction stay residual — an
+// adapter that wants to push those can special-case them itself.
+/** The synthetic root name the residual query scans — the rows a plan produced. */
+export const ROWS_ROOT = "__oqx_rows__";
+/** Split a top-level where into pushable scalar conjuncts and a residual tree. */
+export function partitionPushable(where, canPush) {
+    if (!where)
+        return { pushed: [], residual: null };
+    const parts = where.kind === "and" ? where.parts : [where];
+    const pushed = [];
+    const rest = [];
+    for (const p of parts) {
+        if (p.kind === "scalar" && canPush(p.expr))
+            pushed.push(p.expr);
+        else
+            rest.push(p);
+    }
+    const residual = rest.length === 0 ? null : rest.length === 1 ? rest[0] : { kind: "and", parts: rest };
+    return { pushed, residual };
+}
+/** Rebuild a query to run in-memory over a plan's produced rows: scan the rows
+ * root, drop pushed top-level `from`/predicates, keep projection/order/consumer. */
+export function residualQuery(query, residualWhere) {
+    return { ...query, source: { kind: "ident", name: ROWS_ROOT }, from: [], where: residualWhere };
+}
+/** A literal or binding — a value known without a row context. */
+export function isConst(e) {
+    return e.kind === "lit" || e.kind === "binding";
+}
+/** Evaluate a constant expression against the query bindings. */
+export function constValue(e, params) {
+    if (e.kind === "lit")
+        return e.value;
+    if (e.kind === "binding")
+        return params[e.index];
+    throw new Error("constValue: not a constant expression");
+}
+/** Recognize `field == const` / `const == field` (field is a bare row column). */
+export function asEquality(e) {
+    if (e.kind !== "binary" || e.op !== "==")
+        return null;
+    if (e.left.kind === "ident" && isConst(e.right))
+        return { field: e.left.name, value: e.right };
+    if (e.right.kind === "ident" && isConst(e.left))
+        return { field: e.right.name, value: e.left };
+    return null;
+}
+//# sourceMappingURL=plan.js.map

package/dist/plan.js.map

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

package/dist/planner.d.ts

@@ -0,0 +1,24 @@
+import type { Query } from "./ast.js";
+import type { Engine, OqxResult } from "./engine.js";
+import type { DataContext } from "./context.js";
+export interface Plan {
+    /** The rows the backend produced (already reduced by whatever it pushed). */
+    rows(): Iterable<unknown>;
+    /** The query to finish in-memory over `rows()`; its source is the rows root. */
+    residual: Query;
+    /** Optional context for evaluating the residual (to navigate relations of the
+     * produced rows). Defaults to plain-object access over `rows()`. */
+    context?: DataContext;
+}
+export interface QueryPlanner {
+    /** Plan a query, or return null to decline it entirely (full in-memory fallback). */
+    plan(query: Query, params: readonly unknown[]): Plan | null;
+}
+/** Runs a planner, finishing the residual on the in-memory engine. */
+export declare class PlannedEngine implements Engine {
+    private planner;
+    private fallback;
+    constructor(planner: QueryPlanner, fallback?: DataContext);
+    run(query: Query, bindings?: readonly unknown[]): OqxResult;
+}
+//# sourceMappingURL=planner.d.ts.map

package/dist/planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../src/planner.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAIhD,MAAM,WAAW,IAAI;IACnB,6EAA6E;IAC7E,IAAI,IAAI,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,EAAE,KAAK,CAAC;IAChB;wEACoE;IACpE,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,qFAAqF;IACrF,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;CAC7D;AAED,sEAAsE;AACtE,qBAAa,aAAc,YAAW,MAAM;IAC1C,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,QAAQ,CAAc;gBAElB,OAAO,EAAE,YAAY,EAAE,QAAQ,GAAE,WAAkC;IAK/E,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,GAAE,SAAS,OAAO,EAAO,GAAG,SAAS;CAOhE"}

package/dist/planner.js

@@ -0,0 +1,27 @@
+// The tier-3 seam: a QueryPlanner delegates a query (or part of one) to an
+// underlying store or query system, returning the rows it produced plus a
+// RESIDUAL query for whatever it could not push down. `PlannedEngine` wires this
+// to the in-memory engine: it hands the query to the planner, then finishes the
+// residual over the produced rows — so a planner may be as partial as it likes
+// and correctness is always preserved by the in-memory fallback.
+import { InMemoryEngine } from "./engine.js";
+import { DefaultContext } from "./context.js";
+import { ROWS_ROOT } from "./plan.js";
+/** Runs a planner, finishing the residual on the in-memory engine. */
+export class PlannedEngine {
+    planner;
+    fallback;
+    constructor(planner, fallback = new DefaultContext()) {
+        this.planner = planner;
+        this.fallback = fallback;
+    }
+    run(query, bindings = []) {
+        const plan = this.planner.plan(query, bindings);
+        if (!plan)
+            return new InMemoryEngine(this.fallback).run(query, bindings);
+        const produced = Array.from(plan.rows());
+        const ctx = plan.context ?? new DefaultContext({ [ROWS_ROOT]: produced });
+        return new InMemoryEngine(ctx).run(plan.residual, bindings);
+    }
+}
+//# sourceMappingURL=planner.js.map

package/dist/planner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.js","sourceRoot":"","sources":["../src/planner.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,0EAA0E;AAC1E,iFAAiF;AACjF,gFAAgF;AAChF,+EAA+E;AAC/E,iEAAiE;AAIjE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAiBtC,sEAAsE;AACtE,MAAM,OAAO,aAAa;IAChB,OAAO,CAAe;IACtB,QAAQ,CAAc;IAE9B,YAAY,OAAqB,EAAE,WAAwB,IAAI,cAAc,EAAE;QAC7E,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,GAAG,CAAC,KAAY,EAAE,WAA+B,EAAE;QACjD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAChD,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACzE,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACzC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,cAAc,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC1E,OAAO,IAAI,cAAc,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC9D,CAAC;CACF"}

package/dist/semantics.d.ts

@@ -0,0 +1,22 @@
+/** Equality with absence-normalization (undefined ≡ null) and strict typing. */
+export declare function equals(a: unknown, b: unknown): boolean;
+/** The six relational operators. Absent operands (for ordering ops) yield false. */
+export declare function relate(op: string, a: unknown, b: unknown): boolean;
+/** Arithmetic. `+` concatenates when either side is a string. */
+export declare function arith(op: string, a: unknown, b: unknown): unknown;
+export declare function membership(needle: unknown, haystack: unknown): boolean;
+export declare function truthy(v: unknown): boolean;
+export declare function toNumber(v: unknown): number;
+export declare function sizeOf(v: unknown): number;
+export declare function toList(v: unknown): unknown[];
+/** Normalize a host value into a queryable collection: arrays pass through,
+ * non-string iterables are materialized, absence is empty, any other single
+ * value becomes a one-element collection (a to-one relation). */
+export declare function coerceCollection(v: unknown): unknown[];
+/** Total order for `order by`, with absent values sorting last. */
+export declare function compareForSort(a: unknown, b: unknown): number;
+/** Free functions callable as `name(args)`. */
+export declare const BUILTIN_FUNCTIONS: Record<string, (args: unknown[]) => unknown>;
+/** Methods callable as `recv.name(args)`. */
+export declare const BUILTIN_METHODS: Record<string, (recv: unknown, args: unknown[]) => unknown>;
+//# sourceMappingURL=semantics.d.ts.map

package/dist/semantics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantics.d.ts","sourceRoot":"","sources":["../src/semantics.ts"],"names":[],"mappings":"AAmBA,gFAAgF;AAChF,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAItD;AAED,oFAAoF;AACpF,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAWlE;AAED,iEAAiE;AACjE,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAYjE;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAMtE;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAE1C;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAE3C;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAKzC;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,EAAE,CAO5C;AAED;;iEAEiE;AACjE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,EAAE,CAOtD;AAED,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,MAAM,CAQ7D;AAED,+CAA+C;AAC/C,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAI1E,CAAC;AAEF,6CAA6C;AAC7C,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAYvF,CAAC"}

package/dist/semantics.js

@@ -0,0 +1,142 @@
+// Normative scalar semantics — the single source of truth for how OQX values
+// compare, combine, and coerce. Both the in-memory engine AND any pushdown
+// adapter (SQL, remote, …) MUST produce results consistent with these rules; the
+// conformance suite (test/conformance.test.ts) is what verifies a backend obeys
+// them. When a backend cannot reproduce a rule in its native query language, it
+// must leave that fragment as an in-memory RESIDUAL rather than approximate it.
+//
+// The rules (deliberately CEL-flavored, since OQX descends from omgbase's CEL
+// layer):
+//   • Absence: `undefined` and `null` are the same absent value.
+//   • Equality (== / !=): typed and strict — no cross-type coercion, so
+//     `5 == "5"` is false. Two absent values are equal.
+//   • Ordering (< <= > >=): a comparison with an absent operand is false (never
+//     throws, never orders). Numbers and strings order naturally; mixed types do
+//     not order (false).
+//   • Truthiness: JavaScript truthiness of the value.
+//   • `in`: membership in an array (by ==), substring in a string, or key in an
+//     object.
+/** Equality with absence-normalization (undefined ≡ null) and strict typing. */
+export function equals(a, b) {
+    const x = a === undefined ? null : a;
+    const y = b === undefined ? null : b;
+    return x === y;
+}
+/** The six relational operators. Absent operands (for ordering ops) yield false. */
+export function relate(op, a, b) {
+    if (op === "==")
+        return equals(a, b);
+    if (op === "!=")
+        return !equals(a, b);
+    if (a == null || b == null)
+        return false;
+    switch (op) {
+        case "<": return a < b;
+        case "<=": return a <= b;
+        case ">": return a > b;
+        case ">=": return a >= b;
+        default: throw new Error(`not a relational operator: ${op}`);
+    }
+}
+/** Arithmetic. `+` concatenates when either side is a string. */
+export function arith(op, a, b) {
+    if (op === "+" && (typeof a === "string" || typeof b === "string"))
+        return String(a) + String(b);
+    const x = toNumber(a);
+    const y = toNumber(b);
+    switch (op) {
+        case "+": return x + y;
+        case "-": return x - y;
+        case "*": return x * y;
+        case "/": return x / y;
+        case "%": return x % y;
+        default: throw new Error(`not an arithmetic operator: ${op}`);
+    }
+}
+export function membership(needle, haystack) {
+    if (haystack == null)
+        return false;
+    if (Array.isArray(haystack))
+        return haystack.some((x) => equals(x, needle));
+    if (typeof haystack === "string")
+        return haystack.includes(String(needle));
+    if (typeof haystack === "object")
+        return String(needle) in haystack;
+    return false;
+}
+export function truthy(v) {
+    return Boolean(v);
+}
+export function toNumber(v) {
+    return typeof v === "number" ? v : Number(v);
+}
+export function sizeOf(v) {
+    if (v == null)
+        return 0;
+    if (typeof v === "string" || Array.isArray(v))
+        return v.length;
+    if (typeof v === "object")
+        return Object.keys(v).length;
+    return 0;
+}
+export function toList(v) {
+    if (v == null)
+        return [];
+    if (Array.isArray(v))
+        return v;
+    if (typeof v === "object" && typeof v[Symbol.iterator] === "function") {
+        return Array.from(v);
+    }
+    return [v];
+}
+/** Normalize a host value into a queryable collection: arrays pass through,
+ * non-string iterables are materialized, absence is empty, any other single
+ * value becomes a one-element collection (a to-one relation). */
+export function coerceCollection(v) {
+    if (v == null)
+        return [];
+    if (Array.isArray(v))
+        return v;
+    if (typeof v === "object" && typeof v[Symbol.iterator] === "function") {
+        return Array.from(v);
+    }
+    return [v];
+}
+/** Total order for `order by`, with absent values sorting last. */
+export function compareForSort(a, b) {
+    const an = a == null, bn = b == null;
+    if (an && bn)
+        return 0;
+    if (an)
+        return 1;
+    if (bn)
+        return -1;
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
+/** Free functions callable as `name(args)`. */
+export const BUILTIN_FUNCTIONS = {
+    list: (args) => toList(args[0]),
+    size: (args) => sizeOf(args[0]),
+    has: (args) => args[0] != null,
+};
+/** Methods callable as `recv.name(args)`. */
+export const BUILTIN_METHODS = {
+    contains: (recv, args) => {
+        if (typeof recv === "string")
+            return recv.includes(String(args[0]));
+        if (Array.isArray(recv))
+            return recv.some((x) => equals(x, args[0]));
+        return false;
+    },
+    startsWith: (recv, args) => typeof recv === "string" && recv.startsWith(String(args[0])),
+    endsWith: (recv, args) => typeof recv === "string" && recv.endsWith(String(args[0])),
+    matches: (recv, args) => recv != null && new RegExp(String(args[0])).test(String(recv)),
+    size: (recv) => sizeOf(recv),
+    lower: (recv) => String(recv).toLowerCase(),
+    upper: (recv) => String(recv).toUpperCase(),
+};
+//# sourceMappingURL=semantics.js.map

package/dist/semantics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantics.js","sourceRoot":"","sources":["../src/semantics.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,2EAA2E;AAC3E,iFAAiF;AACjF,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,UAAU;AACV,iEAAiE;AACjE,wEAAwE;AACxE,wDAAwD;AACxD,gFAAgF;AAChF,iFAAiF;AACjF,yBAAyB;AACzB,sDAAsD;AACtD,gFAAgF;AAChF,cAAc;AAEd,gFAAgF;AAChF,MAAM,UAAU,MAAM,CAAC,CAAU,EAAE,CAAU;IAC3C,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,OAAO,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,MAAM,CAAC,EAAU,EAAE,CAAU,EAAE,CAAU;IACvD,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACrC,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI;QAAE,OAAO,KAAK,CAAC;IACzC,QAAQ,EAAE,EAAE,CAAC;QACX,KAAK,GAAG,CAAC,CAAC,OAAQ,CAAW,GAAI,CAAW,CAAC;QAC7C,KAAK,IAAI,CAAC,CAAC,OAAQ,CAAW,IAAK,CAAW,CAAC;QAC/C,KAAK,GAAG,CAAC,CAAC,OAAQ,CAAW,GAAI,CAAW,CAAC;QAC7C,KAAK,IAAI,CAAC,CAAC,OAAQ,CAAW,IAAK,CAAW,CAAC;QAC/C,OAAO,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,8BAA8B,EAAE,EAAE,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,CAAU,EAAE,CAAU;IACtD,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACjG,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACtB,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACtB,QAAQ,EAAE,EAAE,CAAC;QACX,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACvB,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACvB,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACvB,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACvB,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACvB,OAAO,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,+BAA+B,EAAE,EAAE,CAAC,CAAC;IAChE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAe,EAAE,QAAiB;IAC3D,IAAI,QAAQ,IAAI,IAAI;QAAE,OAAO,KAAK,CAAC;IACnC,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5E,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3E,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,IAAK,QAAmB,CAAC;IAChF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,CAAU;IAC/B,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,CAAU;IACjC,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,CAAU;IAC/B,IAAI,CAAC,IAAI,IAAI;QAAE,OAAO,CAAC,CAAC;IACxB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC;IAC/D,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACxD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,CAAU;IAC/B,IAAI,CAAC,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IACzB,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAQ,CAAuB,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,UAAU,EAAE,CAAC;QAC7F,OAAO,KAAK,CAAC,IAAI,CAAC,CAAsB,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,CAAC,CAAC,CAAC,CAAC;AACb,CAAC;AAED;;iEAEiE;AACjE,MAAM,UAAU,gBAAgB,CAAC,CAAU;IACzC,IAAI,CAAC,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IACzB,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAQ,CAAuB,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,UAAU,EAAE,CAAC;QAC7F,OAAO,KAAK,CAAC,IAAI,CAAC,CAAsB,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,CAAC,CAAC,CAAC,CAAC;AACb,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,cAAc,CAAC,CAAU,EAAE,CAAU;IACnD,MAAM,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC;IACrC,IAAI,EAAE,IAAI,EAAE;QAAE,OAAO,CAAC,CAAC;IACvB,IAAI,EAAE;QAAE,OAAO,CAAC,CAAC;IACjB,IAAI,EAAE;QAAE,OAAO,CAAC,CAAC,CAAC;IAClB,IAAK,CAAW,GAAI,CAAW;QAAE,OAAO,CAAC,CAAC,CAAC;IAC3C,IAAK,CAAW,GAAI,CAAW;QAAE,OAAO,CAAC,CAAC;IAC1C,OAAO,CAAC,CAAC;AACX,CAAC;AAED,+CAA+C;AAC/C,MAAM,CAAC,MAAM,iBAAiB,GAAiD;IAC7E,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/B,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/B,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI;CAC/B,CAAC;AAEF,6CAA6C;AAC7C,MAAM,CAAC,MAAM,eAAe,GAAgE;IAC1F,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE;QACvB,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpE,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACrE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACxF,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACpF,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,IAAI,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvF,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC;IAC5B,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE;IAC3C,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE;CAC5C,CAAC"}

package/package.json

@@ -1,28 +1,38 @@
 {
   "name": "@omgbase/oqx",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Generic Object Query eXpression engine for JavaScript",
   "license": "ISC",
   "author": "",
   "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "publishConfig": {
     "access": "public"
   },
   "exports": {
-    ".": "./src/index.ts",
-    "./sqlite": "./src/adapters/sqlite.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./sqlite": {
+      "types": "./dist/adapters/sqlite.d.ts",
+      "import": "./dist/adapters/sqlite.js"
+    }
   },
   "files": [
+    "dist",
     "src"
   ],
   "engines": {
     "node": ">=22.6.0"
   },
   "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/fix-dts-extensions.mjs",
+    "clean": "rm -rf dist",
     "test": "node --test test/*.test.ts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
   },
   "devDependencies": {
     "@types/node": "^22.20.2",

package/src/engine.ts

@@ -109,35 +109,76 @@ export class InMemoryEngine implements Engine {
     return this.shape(query.consumer, scopes, query.select);
   }
 
+  // A bounded, per-path recursive walk. Each occurrence carries recursion
+  // metadata: `$depth` (seed = 1), a categorical `$stop`, and a deterministic
+  // `$ordinal`. Semantics:
+  //   • per-path — a node reached by N distinct paths yields N occurrences
+  //     (unless `distinct`, which keeps the minimal (depth, path) per identity);
+  //   • cycles are safe — revisiting a key already on the current path admits ONE
+  //     occurrence with `$stop == "cycle"` and does not expand it (no runaway);
+  //   • `$stop` ∈ interior | leaf | frontier | depth | cycle, with precedence
+  //     cycle > frontier > depth > leaf > interior; only `interior` rows expand;
+  //   • `$leaf` = (stop == leaf); `$frontier` = (stop ∈ {frontier, depth}) — the
+  //     "there is unfollowed graph beyond me" signal;
+  //   • identity for cycle detection + `distinct` is `by <expr>` when given, else
+  //     `ctx.identity(row)`.
   private followWalk(seedRows: unknown[], follow: Follow, parent: Scope): Occurrence[] {
     const cap = follow.depth ?? HARD_DEPTH_CAP;
-    const idOf = (row: unknown): unknown =>
-      follow.by ? this.evalExpr(follow.by, { row, parent, bindings: parent.bindings }) : this.ctx.identity(row);
-    const occ: Occurrence[] = [];
-    const seen = new Set<unknown>();
-    let level: { row: unknown; depth: number }[] = seedRows.map((r) => ({ row: r, depth: 1 }));
-
-    while (level.length > 0) {
-      const next: { row: unknown; depth: number }[] = [];
-      for (const cur of level) {
-        const key = idOf(cur.row);
-        if (seen.has(key)) continue;
-        seen.add(key);
-        const s: Scope = { row: cur.row, parent, bindings: parent.bindings };
-        const raw = this.rowsOf(this.evalExpr(follow.receiver, s));
-        const succ = follow.where
-          ? raw.filter((x) => truthy(this.evalExpr(follow.where!, { row: x, parent, bindings: parent.bindings })))
-          : raw;
-        const atCap = cur.depth >= cap;
-        const frontierHit = follow.frontier ? truthy(this.evalExpr(follow.frontier, s)) : false;
-        const isLeaf = succ.length === 0;
-        const stop = frontierHit ? "frontier" : atCap ? "depth" : isLeaf ? "leaf" : "continue";
-        occ.push({ row: cur.row, meta: { $depth: cur.depth, $stop: stop, $leaf: isLeaf, $frontier: frontierHit } });
-        if (!atCap && !frontierHit && !isLeaf) for (const x of succ) next.push({ row: x, depth: cur.depth + 1 });
+    const scopeFor = (row: unknown): Scope => ({ row, parent, bindings: parent.bindings });
+    const keyOf = (row: unknown): string =>
+      String(follow.by ? this.evalExpr(follow.by, scopeFor(row)) : this.ctx.identity(row));
+    const succOf = (row: unknown): unknown[] => {
+      const raw = this.rowsOf(this.evalExpr(follow.receiver, scopeFor(row)));
+      return follow.where ? raw.filter((x) => truthy(this.evalExpr(follow.where!, scopeFor(x)))) : raw;
+    };
+    const frontierHit = (row: unknown): boolean =>
+      follow.frontier ? truthy(this.evalExpr(follow.frontier, scopeFor(row))) : false;
+
+    interface Walked { row: unknown; depth: number; path: string; key: string; stop: string; }
+    const walked: Walked[] = [];
+
+    const visit = (row: unknown, depth: number, ancestors: string[]): void => {
+      const key = keyOf(row);
+      const path = `/${[...ancestors, key].join("/")}/`;
+      let stop: string;
+      if (ancestors.includes(key)) stop = "cycle";
+      else if (frontierHit(row)) stop = "frontier";
+      else if (depth >= cap) stop = "depth";
+      else {
+        const succ = succOf(row);
+        if (succ.length === 0) stop = "leaf";
+        else {
+          walked.push({ row, depth, path, key, stop: "interior" });
+          for (const s of succ) visit(s, depth + 1, [...ancestors, key]);
+          return;
+        }
       }
-      level = next;
+      walked.push({ row, depth, path, key, stop });
+    };
+    for (const r of seedRows) visit(r, 1, []);
+
+    let rows = walked;
+    if (follow.distinct) {
+      // keep the minimal (depth, path) occurrence per identity key.
+      const best = new Map<string, Walked>();
+      for (const w of rows) {
+        const prev = best.get(w.key);
+        if (!prev || w.depth < prev.depth || (w.depth === prev.depth && w.path < prev.path)) best.set(w.key, w);
+      }
+      rows = [...best.values()];
     }
-    return occ;
+    // $ordinal: a deterministic 1..N rank over (depth, path).
+    rows = rows.slice().sort((a, b) => a.depth - b.depth || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return rows.map((w, i) => ({
+      row: w.row,
+      meta: {
+        $depth: w.depth,
+        $stop: w.stop,
+        $leaf: w.stop === "leaf",
+        $frontier: w.stop === "frontier" || w.stop === "depth",
+        $ordinal: i + 1,
+      },
+    }));
   }
 
   // ---- consumer shaping -----------------------------------------------------
@@ -253,7 +294,18 @@ export class InMemoryEngine implements Engine {
     if (!orderBy || orderBy.length === 0) return;
     scopes.sort((a, b) => {
       for (const spec of orderBy) {
-        const c = compareForSort(this.evalExpr(spec.expr, a), this.evalExpr(spec.expr, b));
+        const av = this.evalExpr(spec.expr, a);
+        const bv = this.evalExpr(spec.expr, b);
+        // Absent (null/undefined) sorts LAST regardless of direction: `desc`
+        // reverses the ordering of PRESENT values only, and must not hoist rows
+        // that lack the sort key to the top. (Negating the direction over
+        // `compareForSort`'s absent-handling result would flip absent-last to
+        // absent-first under `desc` — the bug this guards against.)
+        const an = av == null, bn = bv == null;
+        if (an && bn) continue;
+        if (an) return 1;
+        if (bn) return -1;
+        const c = compareForSort(av, bv);
         if (c !== 0) return spec.desc ? -c : c;
       }
       return 0;