@c9up/atlas 0.1.18 → 0.1.19

package/dist/ModelQuery.js

@@ -128,6 +128,14 @@ export class Paginator {
     all() {
         return this.items;
     }
+    /** True when there is more than one page of results (AdonisJS `hasPages`). */
+    get hasPages() {
+        return this.meta.lastPage > 1;
+    }
+    /** True when there is at least one more page after the current one (AdonisJS `hasMorePages`). */
+    get hasMorePages() {
+        return this.meta.currentPage < this.meta.lastPage;
+    }
     serialize(opts) {
         const data = this.items.map((item) => {
             if (!opts?.fields)
@@ -199,6 +207,16 @@ export class ModelQuery {
     #debugFlag = false;
     /** Distinct flag — Story 29.5. */
     #distinct = false;
+    /** GROUP BY columns (Lucid parity). */
+    #groupBy = [];
+    /** HAVING clauses — structured + raw (Lucid parity). */
+    #having = [];
+    /** CTEs registered via `.with()` (Lucid parity). */
+    #ctes = [];
+    /** UNION / UNION ALL branches (Lucid parity). */
+    #unions = [];
+    /** m2m pivot-table WHERE constraints — applied to the pivot lookup, not the related query. */
+    #pivotWheres = [];
     /** SQL dialect for compilation — inherited from the owning BaseRepository. */
     #dialect;
     constructor(tableName, db, hydrateFn, entityClass, resolveColumn = (c) => c, softDeletes = false, dialect = getAtlasDialect()) {
@@ -365,6 +383,119 @@ export class ModelQuery {
         });
         return this;
     }
+    // ─── OR-combined variants (AdonisJS orWhere* family) ─────────
+    // Same predicates as the whereX methods above, combined with OR instead of
+    // AND — the named ergonomics Lucid exposes (vs emulating with `orWhere(cb)`).
+    /** `OR col IS NULL`. */
+    orWhereNull(column) {
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "IS NULL",
+            value: null,
+        });
+        return this;
+    }
+    /** `OR col IS NOT NULL`. */
+    orWhereNotNull(column) {
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "IS NOT NULL",
+            value: null,
+        });
+        return this;
+    }
+    /** `OR col != ?`. */
+    orWhereNot(column, value) {
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "!=",
+            value,
+        });
+        return this;
+    }
+    /** `OR col IN (...)` — array or `ModelQuery` subquery source. */
+    orWhereIn(column, source) {
+        if (source instanceof _a) {
+            this.#wheres.push({
+                type: "or",
+                kind: "inSub",
+                negated: false,
+                column: this.#resolveColumn(column),
+                subquery: source.#buildSpec(),
+            });
+            return this;
+        }
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "IN",
+            value: [...source],
+        });
+        return this;
+    }
+    /** `OR col NOT IN (...)` — array or `ModelQuery` subquery source. */
+    orWhereNotIn(column, source) {
+        if (source instanceof _a) {
+            this.#wheres.push({
+                type: "or",
+                kind: "inSub",
+                negated: true,
+                column: this.#resolveColumn(column),
+                subquery: source.#buildSpec(),
+            });
+            return this;
+        }
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "NOT IN",
+            value: [...source],
+        });
+        return this;
+    }
+    /** `OR col BETWEEN ? AND ?`. */
+    orWhereBetween(column, range) {
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "BETWEEN",
+            value: [...range],
+        });
+        return this;
+    }
+    /** `OR col NOT BETWEEN ? AND ?`. */
+    orWhereNotBetween(column, range) {
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "NOT BETWEEN",
+            value: [...range],
+        });
+        return this;
+    }
+    /** `OR col LIKE ?`. */
+    orWhereLike(column, pattern) {
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "LIKE",
+            value: pattern,
+        });
+        return this;
+    }
+    /** `OR col ILIKE ?` (rewritten to LOWER() LIKE LOWER() on sqlite/mysql). */
+    orWhereILike(column, pattern) {
+        this.#wheres.push({
+            type: "or",
+            column: this.#resolveColumn(column),
+            operator: "ILIKE",
+            value: pattern,
+        });
+        return this;
+    }
     /**
      * **⚠ UNSAFE** — append a raw SQL fragment to the WHERE clause with
      * `?`-style bindings. The Rust compiler re-indexes the placeholders so they
@@ -452,6 +583,44 @@ export class ModelQuery {
         this.#wheres.push({ type: "and", column: resolved, operator: op, value });
         return this;
     }
+    /**
+     * Compare two COLUMNS (AdonisJS/Knex `whereColumn`) — `WHERE "a" op "b"`.
+     * Both sides go through the identifier quoter (injection-safe) and the
+     * operator is allow-listed; nothing is bound (it's a column reference, not a
+     * value), which the standard `where`/`whereExpr` value-binding path can't do.
+     */
+    whereColumn(left, operator, right) {
+        return this.#whereColumn("and", left, operator, right);
+    }
+    /** `OR`-combined {@link whereColumn}. */
+    orWhereColumn(left, operator, right) {
+        return this.#whereColumn("or", left, operator, right);
+    }
+    #whereColumn(type, left, operator, right) {
+        if (!WHEREEXPR_OPERATORS.has(operator)) {
+            throw new Error(`whereColumn: operator '${operator}' is not allowed. Use one of ${[...WHEREEXPR_OPERATORS].join(" ")}.`);
+        }
+        // Both operands are interpolated as raw identifiers (no value binding for a
+        // column reference), and #quote is a plain wrapper that does NOT escape an
+        // embedded quote — so validate each RESOLVED identifier against a strict
+        // `[table.]column` charset. This closes the injection surface regardless of
+        // what #resolveColumn returns (it can be an identity resolver on sub-queries).
+        const safe = (name) => {
+            const resolved = this.#resolveColumn(name);
+            if (!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/.test(resolved)) {
+                throw new Error(`whereColumn: '${name}' is not a valid column identifier ([table.]column, alphanumeric + underscore).`);
+            }
+            // Quote each dotted segment separately → `"table"."column"`, never a
+            // single mis-quoted `"table.column"`.
+            return resolved
+                .split(".")
+                .map((part) => this.#quote(part))
+                .join(".");
+        };
+        const sql = `${safe(left)} ${operator} ${safe(right)}`;
+        this.#wheres.push({ type, kind: "raw", sql, bindings: [] });
+        return this;
+    }
     /**
      * `WHERE EXISTS (SELECT * FROM related WHERE <join> AND <cb>)` — filter parent rows
      * by the existence of related rows, optionally constrained by a callback.
@@ -576,6 +745,98 @@ export class ModelQuery {
         this.#orderBys.push({ column: this.#resolveColumn(column), direction });
         return this;
     }
+    /**
+     * `GROUP BY col1, col2, …` (AdonisJS/Lucid `groupBy`). Columns are resolved
+     * through the entity's column map (camelCase → snake_case) like `orderBy`.
+     * For a raw grouping expression, use a `whereRaw`-style construct via the
+     * fluent {@link QueryBuilder}.
+     */
+    groupBy(...columns) {
+        for (const c of columns)
+            this.#groupBy.push(this.#resolveColumn(c));
+        return this;
+    }
+    /**
+     * `HAVING <col> <op> ?` — applied after `groupBy` (AdonisJS/Lucid `having`).
+     * The column is passed verbatim to the Rust HAVING compiler, which quotes a
+     * plain identifier or accepts an allow-listed aggregate expression
+     * (`COUNT(*)`, `SUM(col)`, …) — it is NOT run through the entity column map,
+     * so aggregate expressions and result aliases both work.
+     */
+    having(column, operator, value) {
+        this.#having.push({ column, operator, value, type: "and" });
+        return this;
+    }
+    /** `OR HAVING <col> <op> ?` — OR-combined {@link having}. */
+    orHaving(column, operator, value) {
+        this.#having.push({ column, operator, value, type: "or" });
+        return this;
+    }
+    /**
+     * **⚠ UNSAFE** — append a raw SQL `HAVING` fragment with `?` bindings
+     * (AdonisJS/Lucid `havingRaw`). The Rust compiler re-indexes the placeholders;
+     * everything else in `sql` is trusted verbatim. All values must go through
+     * `bindings`.
+     *
+     * @unsafe Raw SQL fragment — never concatenate user input into `sql`.
+     */
+    havingRaw(sql, bindings = []) {
+        this.#having.push({
+            kind: "raw",
+            sql,
+            bindings: [...bindings],
+            type: "and",
+        });
+        return this;
+    }
+    /**
+     * `UNION (<query>)` (AdonisJS/Lucid `union`). The other query is compiled and
+     * appended as a parenthesised UNION branch; its bindings are re-indexed into
+     * the outer parameter list.
+     */
+    union(query) {
+        this.#unions.push({ query, all: false });
+        return this;
+    }
+    /** `UNION ALL (<query>)` — duplicate-preserving {@link union}. */
+    unionAll(query) {
+        this.#unions.push({ query, all: true });
+        return this;
+    }
+    /**
+     * `WITH <name> AS (<query>)` — register a Common Table Expression
+     * (AdonisJS/Lucid `with`). The CTE name is validated as an identifier; the
+     * sub-query is compiled and its bindings are re-indexed into the outer list.
+     */
+    with(name, query) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+            throw new Error(`with(): CTE name '${name}' is not a valid identifier`);
+        }
+        this.#ctes.push({ name, query });
+        return this;
+    }
+    wherePivot(column, operatorOrValue, value) {
+        if (value === undefined) {
+            this.#pivotWheres.push({ column, operator: "=", value: operatorOrValue });
+        }
+        else {
+            this.#pivotWheres.push({
+                column,
+                operator: operatorOrValue,
+                value,
+            });
+        }
+        return this;
+    }
+    /** `@ManyToMany` only — `WHERE <pivotCol> IN (...)` on the pivot table (Lucid `wherePivotIn`). */
+    wherePivotIn(column, values) {
+        this.#pivotWheres.push({ column, operator: "IN", value: [...values] });
+        return this;
+    }
+    /** Read-only accessor for pivot constraints — consumed by the m2m preload resolver. */
+    get pivotConstraints() {
+        return this.#pivotWheres;
+    }
     limit(n) {
         // Guard here with a clear message — the Rust spec types limit as
         // u64, so a negative/non-integer otherwise surfaces as a cryptic
@@ -611,6 +872,21 @@ export class ModelQuery {
             throw new Error(`No ${this.#tableName} found matching query`);
         return result;
     }
+    /**
+     * Return the single matching row, or throw if there are zero OR more than one
+     * (AdonisJS/Laravel `sole`). Use when exactly one row is a correctness
+     * invariant — a second match signals a bug the silent `first()` would hide.
+     */
+    async sole() {
+        const rows = await this.limit(2).exec();
+        if (rows.length === 0) {
+            throw new Error(`No ${this.#tableName} found matching query (sole()).`);
+        }
+        if (rows.length > 1) {
+            throw new Error(`Expected exactly one ${this.#tableName} but the query matched multiple rows (sole()).`);
+        }
+        return rows[0];
+    }
     /**
      * Thenable — `await someQuery` is equivalent to `await someQuery.exec()`.
      * A chain like `await repo.query().where('active', true).orderBy('id')`
@@ -656,13 +932,19 @@ export class ModelQuery {
             selectSubqueries: this.#selectSubqueries,
             wheres,
             orderBy: this.#orderBys,
-            groupBy: [],
-            having: [],
+            groupBy: this.#groupBy,
+            having: this.#having,
             limit: this.#limit ?? null,
             offset: this.#offset ?? null,
             distinct: this.#distinct,
-            ctes: [],
-            unions: [],
+            ctes: this.#ctes.map((c) => {
+                const { sql, params } = c.query.toSQL();
+                return { name: c.name, sql, params };
+            }),
+            unions: this.#unions.map((u) => {
+                const { sql, params } = u.query.toSQL();
+                return { sql, params, all: u.all };
+            }),
             joins: this.#joins,
             lockMode: this.#lockMode,
         };
@@ -946,8 +1228,19 @@ export class ModelQuery {
         const ids = entities.map((e) => e[pk]).filter((v) => v != null);
         if (ids.length === 0)
             return [];
-        // Step 1 — pivot table: find (foreignKey → otherKey) pairs
-        const pivotRows = await ctx.runInQuery(pivot.pivotTable, foreignKey, ids);
+        // Extract PIVOT-table constraints (wherePivot / wherePivotIn) from the
+        // preload callback by replaying it on a throwaway builder. The callback
+        // also runs (again) inside runRelationQuery against the related table; both
+        // runs are pure builder mutations, and pivot constraints are inert there.
+        const pivotWheres = [];
+        if (ctx.nestedCallback) {
+            const scratch = new _a(ctx.relatedTable, this.#db, (r) => r, ctx.relatedClass, (c) => c, false, this.#dialect);
+            ctx.nestedCallback(scratch);
+            for (const c of scratch.pivotConstraints)
+                pivotWheres.push({ ...c });
+        }
+        // Step 1 — pivot table: find (foreignKey → otherKey) pairs (+ wherePivot)
+        const pivotRows = await this.#runInQuery(pivot.pivotTable, foreignKey, ids, pivotWheres);
         if (pivotRows.length === 0) {
             for (const entity of entities)
                 entity.setProp(relationName, []);
@@ -958,17 +1251,44 @@ export class ModelQuery {
         ];
         // Step 2 — load all related entities in one query
         const relRows = await ctx.runRelationQuery(ctx.relatedPk, otherIds);
+        const pivotCols = pivot.pivotColumns ?? [];
+        const pivotAdapters = pivot.pivotColumnAdapters ?? {};
+        // When pivot extras are projected, each (parent, related) edge gets its OWN
+        // hydrated instance so per-edge `$extras.pivot_<col>` values never clobber
+        // across parents (Lucid gives distinct pivot-bearing instances). Otherwise a
+        // single shared instance per related PK is reused (cheaper, current behaviour).
+        const projectPivot = pivotCols.length > 0;
+        const rawByRelatedPk = new Map();
         const byRelatedPk = new Map();
         const allRelated = [];
         for (const row of relRows) {
-            const hydrated = ctx.hydrate(row);
-            byRelatedPk.set(row[ctx.relatedPk], hydrated);
-            allRelated.push(hydrated);
+            rawByRelatedPk.set(row[ctx.relatedPk], row);
+            if (!projectPivot) {
+                const hydrated = ctx.hydrate(row);
+                byRelatedPk.set(row[ctx.relatedPk], hydrated);
+                allRelated.push(hydrated);
+            }
         }
-        // Step 3 — group via the pivot
+        // Step 3 — group via the pivot, projecting declared pivotColumns into
+        // `$extras.pivot_<col>` (running each column's `consume` adapter if any).
         const grouped = new Map();
         for (const pivotRow of pivotRows) {
-            const related = byRelatedPk.get(pivotRow[otherKey]);
+            let related;
+            if (projectPivot) {
+                const raw = rawByRelatedPk.get(pivotRow[otherKey]);
+                if (!raw)
+                    continue;
+                related = ctx.hydrate(raw);
+                for (const col of pivotCols) {
+                    const rawVal = pivotRow[col];
+                    const adapter = pivotAdapters[col];
+                    related.setExtra(`pivot_${col}`, adapter?.consume ? adapter.consume(rawVal) : rawVal);
+                }
+                allRelated.push(related);
+            }
+            else {
+                related = byRelatedPk.get(pivotRow[otherKey]);
+            }
             if (!related)
                 continue;
             const parentId = pivotRow[foreignKey];
@@ -992,13 +1312,24 @@ export class ModelQuery {
         }
     }
     /** Compile + execute a `SELECT * FROM <table> WHERE <column> IN (...)` via the Rust compiler. */
-    async #runInQuery(table, column, values) {
+    async #runInQuery(table, column, values, extraWheres = []) {
+        const wheres = [
+            { column, operator: "IN", value: values, type: "and" },
+        ];
+        for (const w of extraWheres) {
+            wheres.push({
+                column: w.column,
+                operator: w.operator,
+                value: w.value,
+                type: "and",
+            });
+        }
         const spec = {
             kind: "select",
             table,
             select: ["*"],
             selectSubqueries: [],
-            wheres: [{ column, operator: "IN", value: values, type: "and" }],
+            wheres,
             orderBy: [],
             groupBy: [],
             having: [],
@@ -1086,14 +1417,17 @@ export class ModelQuery {
         switch (relation.type) {
             case "hasOne":
             case "hasMany": {
-                const fk = `${camelToSnake(this.#entityClass.name)}_id`;
-                sub.#pushWhereRaw(`${q(relatedTable)}.${q(fk)} = ${q(parentTable)}.${q(parentPk)}`);
+                // Honour custom foreignKey/localKey exactly like the eager loader —
+                // hard-coding them here produced silently-wrong whereHas/withCount SQL.
+                const fk = relation.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
+                const localKey = relation.localKey ?? parentPk;
+                sub.#pushWhereRaw(`${q(relatedTable)}.${q(fk)} = ${q(parentTable)}.${q(localKey)}`);
                 break;
             }
             case "belongsTo": {
-                const fk = `${camelToSnake(relatedClass.name)}_id`;
-                const relatedPk = getPrimaryKey(relatedClass) ?? "id";
-                sub.#pushWhereRaw(`${q(relatedTable)}.${q(relatedPk)} = ${q(parentTable)}.${q(fk)}`);
+                const fk = relation.foreignKey ?? `${camelToSnake(relatedClass.name)}_id`;
+                const ownerKey = relation.ownerKey ?? getPrimaryKey(relatedClass) ?? "id";
+                sub.#pushWhereRaw(`${q(relatedTable)}.${q(ownerKey)} = ${q(parentTable)}.${q(fk)}`);
                 break;
             }
             case "manyToMany": {
@@ -1106,19 +1440,36 @@ export class ModelQuery {
                 const foreignKey = pivot.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
                 const otherKey = pivot.otherKey ?? `${camelToSnake(relatedClass.name)}_id`;
                 const relatedPk = getPrimaryKey(relatedClass) ?? "id";
+                const localKey = relation.localKey ?? parentPk;
                 sub.#pushWhereRaw(`${q(relatedTable)}.${q(relatedPk)} IN ` +
                     `(SELECT ${q(otherKey)} FROM ${q(pivot.pivotTable)} ` +
-                    `WHERE ${q(pivot.pivotTable)}.${q(foreignKey)} = ${q(parentTable)}.${q(parentPk)})`);
+                    `WHERE ${q(pivot.pivotTable)}.${q(foreignKey)} = ${q(parentTable)}.${q(localKey)})`);
+                break;
+            }
+            case "hasOneThrough":
+            case "hasManyThrough": {
+                // Two-hop correlated EXISTS: parent → through → related. Mirrors the
+                // eager loader's key resolution (`#resolveThrough`) exactly so
+                // whereHas/withCount agree with what preload() would return.
+                if (!relation.through) {
+                    throw new Error(`@HasOneThrough/@HasManyThrough '${relationName}' requires a through model`);
+                }
+                const throughClass = relation.through();
+                const throughMeta = getEntityMetadata(throughClass);
+                if (!throughMeta) {
+                    throw new Error(`Entity metadata missing on through class ${throughClass.name}`);
+                }
+                const throughTable = throughMeta.tableName;
+                const throughPk = getPrimaryKey(throughClass) ?? "id";
+                const parentLocal = relation.localKey ?? parentPk;
+                const firstKey = relation.firstKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
+                const secondKey = relation.secondKey ?? `${camelToSnake(throughClass.name)}_id`;
+                const secondLocal = relation.secondLocalKey ?? throughPk;
+                sub.#pushWhereRaw(`${q(relatedTable)}.${q(secondKey)} IN ` +
+                    `(SELECT ${q(secondLocal)} FROM ${q(throughTable)} ` +
+                    `WHERE ${q(throughTable)}.${q(firstKey)} = ${q(parentTable)}.${q(parentLocal)})`);
                 break;
             }
-            default:
-                // hasOneThrough / hasManyThrough build a 2-hop correlated subquery,
-                // which isn't implemented here. Fail loud — falling through would
-                // leave `sub` WITHOUT a join predicate, so whereHas/withCount would
-                // silently match/count EVERY related row.
-                throw new Error(`whereHas/withCount on a '${relation.type}' relation ` +
-                    `(${this.#entityClass.name}.${relationName}) is not supported yet. ` +
-                    `Use a direct hasMany/belongsTo/manyToMany relation, or filter via a sub-query.`);
         }
         return sub;
     }
@@ -1374,6 +1725,14 @@ export class ModelQuery {
         c.#joins = [...this.#joins];
         c.#lockMode = this.#lockMode;
         c.#distinct = this.#distinct;
+        c.#groupBy = [...this.#groupBy];
+        c.#having = structuredCloneSafe(this.#having);
+        c.#ctes = this.#ctes.map((e) => ({ name: e.name, query: e.query.clone() }));
+        c.#unions = this.#unions.map((u) => ({
+            query: u.query.clone(),
+            all: u.all,
+        }));
+        c.#pivotWheres = structuredCloneSafe(this.#pivotWheres);
         c.#debugFlag = this.#debugFlag;
         return c;
     }