@c9up/atlas 0.1.19 → 0.2.1

package/dist/ModelQuery.d.ts

@@ -6,27 +6,82 @@
  *
  * Builds SQL fluently and executes against the database connection.
  */
-import type { BaseEntity } from "./BaseEntity.js";
-import type { DatabaseConnection } from "./BaseRepository.js";
-import { type AtlasDialect } from "./query/native.js";
+import { type BaseEntity, type DomainEvent } from "./BaseEntity.js";
+import { type DatabaseConnection } from "./BaseRepository.js";
+import { DmlBuilder } from "./query/DmlBuilder.js";
+import { type CompiledStatement } from "./query/interpolate.js";
+import { type AtlasDialect, type DialectName } from "./query/native.js";
+import { RawSql } from "./query/QueryBuilder.js";
 type PreloadCallback = (query: ModelQuery<BaseEntity>) => void;
 type ColumnResolver = (column: string) => string;
+/**
+ * Lower a value bound for a given property to its DB form — mirrors
+ * `BaseRepository.#applyPrepare` (a `@column.dateTime` DateTime → ISO string, a
+ * `@Column({ prepare })` adapter runs). Threaded into ModelQuery so the fluent
+ * `update()` / WHERE paths don't bypass prepare the way direct repo writes don't.
+ */
+type ValuePreparer = (column: string, value: unknown) => unknown;
 type WhereCallback = (q: ModelQuery<BaseEntity>) => void;
-/** Enable or disable Atlas strict mode. When enabled, whereRaw/joinRaw throw in user code. */
+/** A compound-query (union/intersect/except) arg — a query OR a callback building one. */
+type UnionArg = ModelQuery<BaseEntity> | ((q: ModelQuery<BaseEntity>) => void);
+/** Enable or disable Atlas strict mode. When enabled, whereRaw/joinRaw/havingRaw throw in user code. */
 export declare function setAtlasStrictMode(enabled: boolean): void;
 /** Current strict mode state — lazy env var read on first access. */
 export declare function isAtlasStrictMode(): boolean;
 export declare function runWithAtlasInternalBypass<T>(fn: () => T): T;
-/** Multi-condition join builder passed to innerJoin/leftJoin/rightJoin callbacks. */
+/**
+ * Multi-condition join builder passed to innerJoin/leftJoin/rightJoin callbacks.
+ * `on`/`andOn`/`orOn` join two COLUMNS; `onVal`/`andOnVal`/`orOnVal` join a column
+ * to a bound VALUE (AdonisJS/Knex parity) — the value flows through the join-params
+ * channel into the compiled parameter list.
+ */
+interface JoinPartMQ {
+    kind: "and" | "or";
+    left?: string;
+    operator?: string;
+    right?: string;
+    value?: {
+        v: unknown;
+    };
+    values?: unknown[];
+    notIn?: boolean;
+    between?: [unknown, unknown];
+    notBetween?: boolean;
+    nullOp?: "IS NULL" | "IS NOT NULL";
+    exists?: {
+        sql: string;
+        params: unknown[];
+        not: boolean;
+    };
+}
 interface JoinBuilder {
-    parts: Array<{
-        kind: "and" | "or";
-        left: string;
-        right: string;
-    }>;
+    /** Accumulated `ON` parts — column-to-column, column-to-value, IN, BETWEEN, NULL, EXISTS. */
+    parts: JoinPartMQ[];
     on(left: string, right: string): JoinBuilder;
+    on(left: string, operator: string, right: string): JoinBuilder;
     andOn(left: string, right: string): JoinBuilder;
+    andOn(left: string, operator: string, right: string): JoinBuilder;
+    orOn(left: string, right: string): JoinBuilder;
+    orOn(left: string, operator: string, right: string): JoinBuilder;
+    onVal(left: string, value: unknown): JoinBuilder;
     andOnVal(left: string, value: unknown): JoinBuilder;
+    orOnVal(left: string, value: unknown): JoinBuilder;
+    /** `ON col IN (?, ?)` (Lucid/Knex `onIn`). */
+    onIn(left: string, values: unknown[]): JoinBuilder;
+    /** `ON col NOT IN (?, ?)` (Lucid/Knex `onNotIn`). */
+    onNotIn(left: string, values: unknown[]): JoinBuilder;
+    /** `ON col IS NULL` (Lucid/Knex `onNull`). */
+    onNull(left: string): JoinBuilder;
+    /** `ON col IS NOT NULL` (Lucid/Knex `onNotNull`). */
+    onNotNull(left: string): JoinBuilder;
+    /** `ON col BETWEEN ? AND ?` — inclusive (Lucid/Knex `onBetween`). */
+    onBetween(left: string, range: readonly [unknown, unknown]): JoinBuilder;
+    /** `ON col NOT BETWEEN ? AND ?` (Lucid/Knex `onNotBetween`). */
+    onNotBetween(left: string, range: readonly [unknown, unknown]): JoinBuilder;
+    /** `ON EXISTS (subquery)` — a builder or a callback (Lucid/Knex `onExists`). */
+    onExists(subquery: UnionArg): JoinBuilder;
+    /** `ON NOT EXISTS (subquery)` (Lucid/Knex `onNotExists`). */
+    onNotExists(subquery: UnionArg): JoinBuilder;
 }
 /** Offset-based paginator (Story 29.10). */
 export declare class Paginator<T> {
@@ -43,8 +98,18 @@ export declare class Paginator<T> {
         total: number;
         perPage: number;
         currentPage: number;
-    });
+    }, metaKeys?: Record<string, string>);
     all(): T[];
+    /** Total row count across all pages. */
+    get total(): number;
+    /** Rows per page. */
+    get perPage(): number;
+    /** The current page number. */
+    get currentPage(): number;
+    /** The last page number. */
+    get lastPage(): number;
+    /** The first page number (always 1). */
+    get firstPage(): number;
     /** True when there is more than one page of results (AdonisJS `hasPages`). */
     get hasPages(): boolean;
     /** True when there is at least one more page after the current one (AdonisJS `hasMorePages`). */
@@ -53,22 +118,42 @@ export declare class Paginator<T> {
         fields?: string[];
     }): {
         data: unknown[];
-        meta: Paginator<T>["meta"];
+        meta: Record<string, unknown>;
     };
     baseUrl(url: string): this;
     queryString(qs: Record<string, unknown>): this;
+    /**
+     * Build the URL for a page number, honouring `baseUrl` + `queryString`.
+     * Returns `''` when no `baseUrl` was set (AdonisJS `getUrl`).
+     */
+    getUrl(page: number): string;
+    /** URL of the next page, or `null` when on the last page (AdonisJS `getNextPageUrl`). */
+    getNextPageUrl(): string | null;
+    /** URL of the previous page, or `null` when on the first page (AdonisJS `getPreviousPageUrl`). */
+    getPreviousPageUrl(): string | null;
+    /** URLs for an inclusive page range, clamped to `[1, lastPage]` (AdonisJS `getUrlsForRange`). */
+    getUrlsForRange(start: number, end: number): Array<{
+        page: number;
+        url: string;
+        isActive: boolean;
+    }>;
     toJSON(): {
         data: unknown[];
-        meta: Paginator<T>["meta"] & Record<string, unknown>;
+        meta: Record<string, unknown>;
     };
 }
 export declare class ModelQuery<T extends BaseEntity> {
     #private;
-    constructor(tableName: string, db: DatabaseConnection, hydrateFn: (row: Record<string, unknown>) => T, entityClass: new () => T, resolveColumn?: ColumnResolver, softDeletes?: boolean, dialect?: AtlasDialect);
+    constructor(tableName: string, db: DatabaseConnection, hydrateFn: (row: Record<string, unknown>) => T, entityClass: new () => T, resolveColumn?: ColumnResolver, softDeletes?: boolean, dialect?: AtlasDialect, prepareValue?: ValuePreparer, onDomainEvents?: (events: DomainEvent[]) => Promise<void>);
     /** Include soft-deleted rows in the result (default behavior excludes them). */
     withTrashed(): this;
     /** Return ONLY soft-deleted rows (deleted_at IS NOT NULL). */
     onlyTrashed(): this;
+    /**
+     * Apply the first `[guard, callback]` whose guard is truthy (Adonis Lucid
+     * `match`); a trailing bare callback is the default, run when none matched.
+     */
+    match(...blocks: Array<[unknown, (query: this) => void] | ((query: this) => void)>): this;
     /**
      * Eager-load a relation (AdonisJS-style).
      * Relations are never loaded automatically — you must call .preload() explicitly.
@@ -78,8 +163,29 @@ export declare class ModelQuery<T extends BaseEntity> {
      *   repo.query().preload('posts', q => q.where('published', true)).exec()
      */
     preload(relationName: string, callback?: PreloadCallback): this;
-    /** Select specific columns (default: `*`). Accepts a comma-separated string or an array. */
-    select(columns: string | string[]): this;
+    /**
+     * Eager-load a relation only if it hasn't been registered yet (Adonis Lucid
+     * `preloadOnce`) — a later `preload`/`preloadOnce` for the same relation is
+     * ignored, so a shared scope can safely add a preload without clobbering one
+     * the caller already set.
+     */
+    preloadOnce(relationName: string, callback?: PreloadCallback): this;
+    /**
+     * Register a callback run for every hydrated instance after loading (preloads
+     * included) but before the query resolves (Adonis Lucid `rowTransformer`). The
+     * callback mutates the instance in place — decorate rows with per-query
+     * computed values without a model hook/accessor. Multiple transformers run in
+     * registration order.
+     */
+    rowTransformer(callback: (row: T) => void): this;
+    /**
+     * Select columns (default: `*`). The model query builder extends the database
+     * query builder's `select` surface (Lucid parity): bare names, multiple args,
+     * a comma-separated string, an array, an `{ alias: 'column' }` object map, a
+     * `db.raw(...)` fragment, and a named subquery — `select(subquery.as('x'))`.
+     * Plain columns are resolved to their DB column (honouring `@Column`).
+     */
+    select(...columns: Array<string | string[] | Record<string, string> | RawSql | ModelQuery<BaseEntity>>): this;
     where(callback: WhereCallback): this;
     where(column: string, value: unknown): this;
     where(column: string, operator: string, value: unknown): this;
@@ -88,9 +194,40 @@ export declare class ModelQuery<T extends BaseEntity> {
     orWhere(column: string, operator: string, value: unknown): this;
     whereNull(column: string): this;
     whereNotNull(column: string): this;
-    /** `WHERE col != ?` — negation of `where`. */
+    andWhere(callback: WhereCallback): this;
+    andWhere(column: string, value: unknown): this;
+    andWhere(column: string, operator: string, value: unknown): this;
+    /** Alias of {@link whereNot} (Lucid parity). */
+    andWhereNot(column: string, value: unknown): this;
+    /** Alias of {@link whereIn} (Lucid parity). */
+    andWhereIn(column: string, values: readonly unknown[]): this;
+    /** Alias of {@link whereNotIn} (Lucid parity). */
+    andWhereNotIn(column: string, values: readonly unknown[]): this;
+    /** Alias of {@link whereNull} (Lucid parity). */
+    andWhereNull(column: string): this;
+    /** Alias of {@link whereNotNull} (Lucid parity). */
+    andWhereNotNull(column: string): this;
+    /** Alias of {@link whereBetween} (Lucid parity). */
+    andWhereBetween(column: string, range: readonly [unknown, unknown]): this;
+    /** Alias of {@link whereNotBetween} (Lucid parity). */
+    andWhereNotBetween(column: string, range: readonly [unknown, unknown]): this;
+    /** Alias of {@link whereLike} (Lucid parity). */
+    andWhereLike(column: string, pattern: string): this;
+    /** Alias of {@link whereILike} (Lucid parity). */
+    andWhereILike(column: string, pattern: string): this;
+    /** Alias of {@link whereColumn} (Lucid parity). */
+    andWhereColumn(left: string, operator: string, right: string): this;
+    /**
+     * Negated WHERE (Lucid/Knex `whereNot`) — the same forms as {@link where}: a
+     * `(column, [operator,] value)` comparison, an object (`whereNot({ a: 1 })` →
+     * `a != 1`), or a callback group (`whereNot((q) => …)` → `NOT (…)`).
+     */
+    whereNot(callback: WhereCallback): this;
+    whereNot(conditions: Record<string, unknown>): this;
     whereNot(column: string, value: unknown): this;
+    whereNot(column: string, operator: string, value: unknown): this;
     /** `WHERE col IN (...)` — accepts an array of values OR a `ModelQuery` subquery source. */
+    whereIn(columns: string[], rows: unknown[][]): this;
     whereIn(column: string, source: readonly unknown[] | ModelQuery<BaseEntity>): this;
     /** `WHERE col NOT IN (...)` — accepts an array of values OR a `ModelQuery` subquery source. */
     whereNotIn(column: string, source: readonly unknown[] | ModelQuery<BaseEntity>): this;
@@ -147,6 +284,29 @@ export declare class ModelQuery<T extends BaseEntity> {
      * @unsafe Raw SQL fragment — never concatenate user input into `sql`.
      */
     whereRaw(sql: string, bindings?: readonly unknown[]): this;
+    /** Alias of {@link whereRaw} (Lucid parity). Subject to the same strict-mode gate. */
+    andWhereRaw(sql: string, bindings?: readonly unknown[]): this;
+    /**
+     * `OR <raw fragment>` (Lucid parity).
+     *
+     * @unsafe Raw SQL fragment — never concatenate user input into `sql`.
+     * Subject to the same strict-mode gate as {@link whereRaw}.
+     */
+    orWhereRaw(sql: string, bindings?: readonly unknown[]): this;
+    /**
+     * Framework-internal: register the deferred m2m EXISTS predicate for a lazy
+     * `related().query()`. The builder is re-invoked on every `#buildSpec()` with
+     * the pivot constraints known at that moment, so `.wherePivot()` added after
+     * the proxy returned still applies. Not exported from the barrel.
+     */
+    setPivotExistsBuilder(builder: (pivotWheres: ReadonlyArray<{
+        column: string;
+        operator: string;
+        value: unknown;
+    }>) => {
+        sql: string;
+        bindings: unknown[];
+    }): this;
     /**
      * **SAFE** alternative to `whereRaw` for the common case of a single
      * SQL expression built from a validated column + operator + bound value.
@@ -171,9 +331,105 @@ export declare class ModelQuery<T extends BaseEntity> {
      * 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.
      */
+    /** `WHERE EXISTS (subquery)` (Lucid parity). */
+    whereExists(subquery: ModelQuery<BaseEntity>): this;
+    /** Alias of {@link whereExists} (Lucid parity). */
+    andWhereExists(subquery: ModelQuery<BaseEntity>): this;
+    /** `OR EXISTS (subquery)` (Lucid parity). */
+    orWhereExists(subquery: ModelQuery<BaseEntity>): this;
+    /** `WHERE NOT EXISTS (subquery)` (Lucid parity). */
+    whereNotExists(subquery: ModelQuery<BaseEntity>): this;
+    /** Alias of {@link whereNotExists} (Lucid parity). */
+    andWhereNotExists(subquery: ModelQuery<BaseEntity>): this;
+    /** `OR NOT EXISTS (subquery)` (Lucid parity). */
+    orWhereNotExists(subquery: ModelQuery<BaseEntity>): this;
+    /**
+     * `WHERE <col at path> <op> ?` — compare a value inside a JSON column
+     * (Lucid/Knex `whereJsonPath`). `path` is a JSONPath (`$.a.b`, `$.items[0]`).
+     *
+     *     query.whereJsonPath('data', '$.address.city', '=', 'Paris')
+     */
+    whereJsonPath(column: string, path: string, value: unknown): this;
+    whereJsonPath(column: string, path: string, operator: string, value: unknown): this;
+    /** Alias of {@link whereJsonPath} (Lucid parity). Operator defaults to `=`. */
+    andWhereJsonPath(column: string, path: string, value: unknown): this;
+    andWhereJsonPath(column: string, path: string, operator: string, value: unknown): this;
+    /** `OR <col at path> <op> ?` (Lucid parity). Operator defaults to `=`. */
+    orWhereJsonPath(column: string, path: string, value: unknown): this;
+    orWhereJsonPath(column: string, path: string, operator: string, value: unknown): this;
+    /**
+     * Structural JSON match (Lucid `whereJson`) — the column's JSON must equal
+     * `value` (canonical comparison on Postgres/MySQL). AND is the default.
+     */
+    whereJson(column: string, value: unknown): this;
+    /** Alias of {@link whereJson} (Lucid `andWhereJson`). */
+    andWhereJson(column: string, value: unknown): this;
+    /** OR form of {@link whereJson} (Lucid `orWhereJson`). */
+    orWhereJson(column: string, value: unknown): this;
+    /** WHERE NOT structural JSON match (Lucid `whereNotJson`). */
+    whereNotJson(column: string, value: unknown): this;
+    /** Alias of {@link whereNotJson} (Lucid `andWhereNotJson`). */
+    andWhereNotJson(column: string, value: unknown): this;
+    /** OR NOT structural JSON match (Lucid `orWhereNotJson`). */
+    orWhereNotJson(column: string, value: unknown): this;
+    /**
+     * `WHERE <col> @> ?` — the JSON column contains `value` (Lucid/Knex
+     * `whereJsonSupersetOf`). `value` is any JSON-serialisable value.
+     *
+     * Postgres and MySQL only — SQLite has no JSON containment operator and the
+     * compiler raises `E_UNSUPPORTED` there.
+     */
+    whereJsonSupersetOf(column: string, value: unknown): this;
+    /** Alias of {@link whereJsonSupersetOf} (Lucid parity). */
+    andWhereJsonSupersetOf(column: string, value: unknown): this;
+    /** `OR <col> @> ?` (Lucid parity). See {@link whereJsonSupersetOf}. */
+    orWhereJsonSupersetOf(column: string, value: unknown): this;
+    /** `WHERE NOT (<col> @> ?)` (Lucid parity). */
+    whereNotJsonSupersetOf(column: string, value: unknown): this;
+    /** `OR NOT (<col> @> ?)` (Lucid parity). */
+    orWhereNotJsonSupersetOf(column: string, value: unknown): this;
+    /**
+     * `WHERE <col> <@ ?` — the JSON column is contained in `value` (Lucid/Knex
+     * `whereJsonSubsetOf`). Postgres/MySQL only; see {@link whereJsonSupersetOf}.
+     */
+    whereJsonSubsetOf(column: string, value: unknown): this;
+    /** Alias of {@link whereJsonSubsetOf} (Lucid parity). */
+    andWhereJsonSubsetOf(column: string, value: unknown): this;
+    /** `OR <col> <@ ?` (Lucid parity). See {@link whereJsonSubsetOf}. */
+    orWhereJsonSubsetOf(column: string, value: unknown): this;
+    /** `WHERE NOT (<col> <@ ?)` (Lucid parity). */
+    whereNotJsonSubsetOf(column: string, value: unknown): this;
+    /** `OR NOT (<col> <@ ?)` (Lucid parity). */
+    orWhereNotJsonSubsetOf(column: string, value: unknown): this;
+    /** Lucid `whereJsonSuperset` (alias of {@link whereJsonSupersetOf}). */
+    whereJsonSuperset(column: string, value: unknown): this;
+    /** Lucid `andWhereJsonSuperset`. */
+    andWhereJsonSuperset(column: string, value: unknown): this;
+    /** Lucid `orWhereJsonSuperset`. */
+    orWhereJsonSuperset(column: string, value: unknown): this;
+    /** Lucid `whereNotJsonSuperset`. */
+    whereNotJsonSuperset(column: string, value: unknown): this;
+    /** Lucid `orWhereNotJsonSuperset`. */
+    orWhereNotJsonSuperset(column: string, value: unknown): this;
+    /** Lucid `whereJsonSubset` (alias of {@link whereJsonSubsetOf}). */
+    whereJsonSubset(column: string, value: unknown): this;
+    /** Lucid `andWhereJsonSubset`. */
+    andWhereJsonSubset(column: string, value: unknown): this;
+    /** Lucid `orWhereJsonSubset`. */
+    orWhereJsonSubset(column: string, value: unknown): this;
+    /** Lucid `whereNotJsonSubset`. */
+    whereNotJsonSubset(column: string, value: unknown): this;
+    /** Lucid `orWhereNotJsonSubset`. */
+    orWhereNotJsonSubset(column: string, value: unknown): this;
     whereColumn(left: string, operator: string, right: string): this;
     /** `OR`-combined {@link whereColumn}. */
     orWhereColumn(left: string, operator: string, right: string): this;
+    /** `WHERE NOT (left <op> right)` — negation of {@link whereColumn} (Lucid parity). */
+    whereNotColumn(left: string, operator: string, right: string): this;
+    /** Alias of {@link whereNotColumn} (Lucid parity). */
+    andWhereNotColumn(left: string, operator: string, right: string): this;
+    /** `OR NOT (left <op> right)` (Lucid parity). */
+    orWhereNotColumn(left: string, operator: string, right: string): this;
     /**
      * `WHERE EXISTS (SELECT * FROM related WHERE <join> AND <cb>)` — filter parent rows
      * by the existence of related rows, optionally constrained by a callback.
@@ -186,6 +442,10 @@ export declare class ModelQuery<T extends BaseEntity> {
     /** `WHERE NOT EXISTS (...)` — negation of whereHas. */
     whereDoesntHave(relationName: string, callback?: (query: ModelQuery<BaseEntity>) => void): this;
     orWhereDoesntHave(relationName: string, callback?: (query: ModelQuery<BaseEntity>) => void): this;
+    /** Alias of {@link whereHas} (Lucid parity) — `whereHas` is already AND. */
+    andWhereHas(relationName: string, callback?: (query: ModelQuery<BaseEntity>) => void): this;
+    /** Alias of {@link whereDoesntHave} (Lucid parity). */
+    andWhereDoesntHave(relationName: string, callback?: (query: ModelQuery<BaseEntity>) => void): this;
     /**
      * Short form of `whereHas`. With an operator + count, emits a count threshold:
      *   has('comments')          → EXISTS (SELECT * FROM comments WHERE <join>)
@@ -195,6 +455,12 @@ export declare class ModelQuery<T extends BaseEntity> {
     orHas(relationName: string, countOp?: string, countThreshold?: number): this;
     /** `WHERE NOT EXISTS (...)` — short form. */
     doesntHave(relationName: string): this;
+    /** `OR NOT EXISTS (...)` — the OR form of {@link doesntHave} (Lucid parity). */
+    orDoesntHave(relationName: string): this;
+    /** Alias of {@link has} (Lucid parity) — `has` is already AND. */
+    andHas(relationName: string, countOp?: string, countThreshold?: number): this;
+    /** Alias of {@link doesntHave} (Lucid parity). */
+    andDoesntHave(relationName: string): this;
     /**
      * Set this query's projection alias — only meaningful when this ModelQuery
      * is used as the sub-builder callback argument of `withCount` / `withAggregate`.
@@ -234,22 +500,65 @@ export declare class ModelQuery<T extends BaseEntity> {
      *     userRepo.query().withAggregate('posts', q => q.sum('views').as('total_views'))
      */
     withAggregate(relationName: string, callback: (query: ModelQuery<BaseEntity>) => void): this;
-    orderBy(column: string, direction?: "asc" | "desc"): this;
+    /** ORDER BY a column, a `db.ref()` fragment, or an array of terms (Lucid/Knex `orderBy`). */
+    orderBy(column: string | RawSql, direction?: "asc" | "desc"): this;
+    orderBy(terms: Array<string | {
+        column: string;
+        order?: "asc" | "desc";
+    }>): this;
+    /**
+     * `ORDER BY <raw fragment>` (Lucid/Knex `orderByRaw`) — for orderings with
+     * no typed form: `NULLS LAST`, `RANDOM()`, a CASE expression, a computed
+     * alias.
+     *
+     *     query.orderBy('rank').orderByRaw('created_at DESC NULLS LAST')
+     *
+     * The fragment keeps its position among the plain `orderBy` terms.
+     *
+     * **Strict mode**: like {@link whereRaw}, this throws when
+     * `setAtlasStrictMode(true)` (or `ATLAS_STRICT`) is on.
+     *
+     * @unsafe Raw SQL fragment — never concatenate user input into `sql`.
+     */
+    orderByRaw(sql: string): 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}.
+     * For a grouping expression with no typed form, see {@link groupByRaw}.
      */
     groupBy(...columns: string[]): this;
+    /**
+     * `GROUP BY <raw fragment>` (Lucid/Knex `groupByRaw`) — for groupings with
+     * no typed form, e.g. `DATE_TRUNC('day', created_at)`.
+     *
+     * The fragment keeps its position among the plain `groupBy` terms.
+     *
+     * **Strict mode**: like {@link whereRaw}, this throws when
+     * `setAtlasStrictMode(true)` (or `ATLAS_STRICT`) is on.
+     *
+     * @unsafe Raw SQL fragment — never concatenate user input into `sql`.
+     */
+    groupByRaw(sql: string): 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.
+     * A bare model property is resolved through the entity column map (honouring
+     * `@Column({ columnName })`) via {@link #resolveHavingCol}; an aggregate
+     * expression (`COUNT(*)`, `SUM(col)`, …) or a result alias is left verbatim so
+     * `having` can still reference `withCount`/`withAggregate` aliases.
      */
     having(column: string, operator: string, value: unknown): this;
+    /** HAVING col IS NULL (Lucid/Knex `havingNull`). */
+    havingNull(column: string): this;
+    /** HAVING col IS NOT NULL (Lucid/Knex `havingNotNull`). */
+    havingNotNull(column: string): this;
+    /** HAVING col IN (...) (Lucid/Knex `havingIn`). */
+    havingIn(column: string, values: unknown[]): this;
+    /** HAVING col NOT IN (...) (Lucid/Knex `havingNotIn`). */
+    havingNotIn(column: string, values: unknown[]): this;
+    /** HAVING col BETWEEN ? AND ? (Lucid/Knex `havingBetween`). */
+    havingBetween(column: string, range: readonly [unknown, unknown]): this;
+    /** HAVING col NOT BETWEEN ? AND ? (Lucid/Knex `havingNotBetween`). */
+    havingNotBetween(column: string, range: readonly [unknown, unknown]): this;
     /** `OR HAVING <col> <op> ?` — OR-combined {@link having}. */
     orHaving(column: string, operator: string, value: unknown): this;
     /**
@@ -266,15 +575,59 @@ export declare class ModelQuery<T extends BaseEntity> {
      * appended as a parenthesised UNION branch; its bindings are re-indexed into
      * the outer parameter list.
      */
-    union(query: ModelQuery<BaseEntity>): this;
+    union(query: UnionArg): this;
     /** `UNION ALL (<query>)` — duplicate-preserving {@link union}. */
-    unionAll(query: ModelQuery<BaseEntity>): this;
+    unionAll(query: UnionArg): this;
+    /** `INTERSECT (<query>)` — rows present in both (Lucid/Knex `intersect`). */
+    intersect(query: UnionArg): this;
+    /**
+     * `INTERSECT ALL (<query>)` — duplicate-preserving {@link intersect}.
+     *
+     * Postgres and MySQL only: SQLite's compound operators are UNION, UNION ALL,
+     * INTERSECT and EXCEPT — there is no INTERSECT ALL — so the compiler raises
+     * `E_UNSUPPORTED` there rather than emitting a syntax error.
+     */
+    intersectAll(query: UnionArg): this;
+    /** `EXCEPT (<query>)` — rows in this query but not the other (Lucid/Knex `except`). */
+    except(query: UnionArg): this;
+    /** `EXCEPT ALL (<query>)` — duplicate-preserving {@link except}. Not on SQLite; see {@link intersectAll}. */
+    exceptAll(query: UnionArg): 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: string, query: ModelQuery<BaseEntity>): this;
+    with(name: string, query: UnionArg): this;
+    /**
+     * `WITH RECURSIVE <name> AS (<query>)` — a self-referencing CTE
+     * (Lucid/Knex `withRecursive`), for trees and graph walks.
+     *
+     * RECURSIVE is a property of the WITH clause rather than of one CTE, so a
+     * single recursive entry makes the whole clause recursive — which is what
+     * all three dialects require. Mixing `with()` and `withRecursive()` is fine.
+     *
+     * The recursive term itself is a `UNION`/`UNION ALL` inside `query`, e.g.
+     * an anchor `SELECT` unioned with a select that references `<name>`.
+     */
+    withRecursive(name: string, query: UnionArg, columns?: string[]): this;
+    /**
+     * `WITH <name> AS MATERIALIZED (<query>)` — force the CTE to be evaluated
+     * once and stashed (Lucid/Knex `withMaterialized`).
+     *
+     * Postgres 12+ and SQLite 3.35+ only; MySQL has no such hint and the
+     * compiler raises `E_UNSUPPORTED` rather than emitting a syntax error.
+     */
+    withMaterialized(name: string, query: UnionArg): this;
+    /** `WITH <name> AS NOT MATERIALIZED (<query>)` — let it be inlined (Lucid/Knex `withNotMaterialized`). See {@link withMaterialized}. */
+    withNotMaterialized(name: string, query: UnionArg): this;
+    /**
+     * `@ManyToMany` only — project EXTRA pivot columns at query time (AdonisJS/Lucid
+     * `pivotColumns([...])`), on top of any declared in the relation decorator. Read
+     * off each loaded relation as `$extras.pivot_<col>`. Inert on non-m2m relations.
+     *
+     *     userRepo.query().preload('skills', q => q.pivotColumns(['notes']))
+     */
+    pivotColumns(columns: string[]): this;
     /**
      * `@ManyToMany` only — filter loaded relations by a PIVOT-table column
      * (AdonisJS/Lucid `wherePivot`). Recorded separately from the related-table
@@ -285,15 +638,76 @@ export declare class ModelQuery<T extends BaseEntity> {
      */
     wherePivot(column: string, value: unknown): this;
     wherePivot(column: string, operator: string, value: unknown): this;
-    /** `@ManyToMany` only — `WHERE <pivotCol> IN (...)` on the pivot table (Lucid `wherePivotIn`). */
+    /** Alias of {@link wherePivot} (Lucid parity) — pivot filters already AND together. */
+    andWherePivot(column: string, value: unknown): this;
+    andWherePivot(column: string, operator: string, value: unknown): this;
+    /**
+     * `@ManyToMany` only — OR form of {@link wherePivot} (Lucid parity).
+     *
+     * The pivot filters are compiled as a parenthesised group, so an OR joins
+     * the other pivot filters and cannot escape the `pivot_fk IN (parents)`
+     * scoping that makes the preload correct.
+     */
+    orWherePivot(column: string, value: unknown): this;
+    orWherePivot(column: string, operator: string, value: unknown): this;
+    /** `@ManyToMany` only — `WHERE <pivotCol> IN (...)` on the pivot table (AdonisJS Lucid `whereInPivot`). */
+    whereInPivot(column: string, values: readonly unknown[]): this;
+    /** Alias of {@link whereInPivot} (Lucid parity). */
+    andWhereInPivot(column: string, values: readonly unknown[]): this;
+    /** `@ManyToMany` only — OR form of {@link whereInPivot} (Lucid parity). */
+    orWhereInPivot(column: string, values: readonly unknown[]): this;
+    /** Alias of {@link whereInPivot} kept for the earlier atlas name. */
     wherePivotIn(column: string, values: readonly unknown[]): this;
+    /**
+     * `@ManyToMany` only — negated pivot filter (AdonisJS Lucid `whereNotPivot`).
+     * `whereNotPivot(col, value)` → `col != value`; `whereNotPivot(col, op, value)`
+     * → the negated comparison (`whereNotPivot('proficiency', '>=', 4)` → `< 4`).
+     */
+    whereNotPivot(column: string, value: unknown): this;
+    whereNotPivot(column: string, operator: string, value: unknown): this;
+    /** Alias of {@link whereNotPivot} (Lucid parity). Operator form supported too. */
+    andWhereNotPivot(column: string, value: unknown): this;
+    andWhereNotPivot(column: string, operator: string, value: unknown): this;
+    /** `@ManyToMany` only — OR form of {@link whereNotPivot} (Lucid parity). */
+    orWhereNotPivot(column: string, value: unknown): this;
+    orWhereNotPivot(column: string, operator: string, value: unknown): this;
+    /** `@ManyToMany` only — `WHERE <pivotCol> NOT IN (...)` on the pivot table (AdonisJS Lucid `whereNotInPivot`). */
+    whereNotInPivot(column: string, values: readonly unknown[]): this;
+    /** Alias of {@link whereNotInPivot} (Lucid parity). */
+    andWhereNotInPivot(column: string, values: readonly unknown[]): this;
+    /** `@ManyToMany` only — OR form of {@link whereNotInPivot} (Lucid parity). */
+    orWhereNotInPivot(column: string, values: readonly unknown[]): this;
+    /** `@ManyToMany` only — `WHERE <pivotCol> IS NULL` on the pivot table (Lucid `whereNullPivot`). */
+    whereNullPivot(column: string): this;
+    /** Alias of {@link whereNullPivot} (Lucid parity). */
+    andWhereNullPivot(column: string): this;
+    /** `@ManyToMany` only — OR form of {@link whereNullPivot} (Lucid parity). */
+    orWhereNullPivot(column: string): this;
+    /** `@ManyToMany` only — `WHERE <pivotCol> IS NOT NULL` on the pivot table (Lucid `whereNotNullPivot`). */
+    whereNotNullPivot(column: string): this;
+    /** Alias of {@link whereNotNullPivot} (Lucid parity). */
+    andWhereNotNullPivot(column: string): this;
+    /** `@ManyToMany` only — OR form of {@link whereNotNullPivot} (Lucid parity). */
+    orWhereNotNullPivot(column: string): this;
     /** Read-only accessor for pivot constraints — consumed by the m2m preload resolver. */
     get pivotConstraints(): ReadonlyArray<{
         column: string;
         operator: string;
         value: unknown;
+        type: "and" | "or";
     }>;
+    /** Read-only accessor for query-time pivot columns — consumed by the m2m preload resolver. */
+    get pivotColumnRequests(): readonly string[];
     limit(n: number): this;
+    /**
+     * In a has-many preload callback, cap the related rows PER PARENT (Lucid
+     * `groupLimit`) — a plain `.limit()` caps the whole result set across parents.
+     * Compiled with a `ROW_NUMBER() OVER (PARTITION BY <fk> …)` window. Pair with
+     * {@link groupOrderBy} to pick which N per parent.
+     */
+    groupLimit(n: number): this;
+    /** ORDER BY for the {@link groupLimit} per-parent window (Lucid `groupOrderBy`). */
+    groupOrderBy(column: string, direction?: "asc" | "desc"): this;
     offset(n: number): this;
     /** Execute and return the first matching entity or null. Fires beforeFind/afterFind. */
     first(): Promise<T | null>;
@@ -317,13 +731,53 @@ export declare class ModelQuery<T extends BaseEntity> {
      * get a fresh builder that re-executes.
      */
     then<TResult1 = T[], TResult2 = never>(onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null | undefined): Promise<TResult1 | TResult2>;
-    /** Build SQL + params via the Rust query compiler. */
-    toSQL(): {
+    /**
+     * Build SQL via the Rust query compiler (Lucid `toSQL`). `.sql` uses `?`
+     * placeholders (Knex-normalized, like Lucid); `.toNative()` yields the native
+     * form. Returns `bindings` (Lucid's name) and `params` (atlas's) — same array.
+     */
+    toSQL(): CompiledStatement;
+    /** `{ sql, bindings }` — the compiled native query (Lucid/Knex `toNative`). */
+    toNative(): {
         sql: string;
-        params: unknown[];
+        bindings: unknown[];
     };
+    /** The model class this query targets (Adonis Lucid `query.model`). */
+    get model(): new () => T;
+    /** Apply `cb` only on the given dialect(s) (Lucid `ifDialect`; Lucid names accepted). */
+    ifDialect(dialect: DialectName | DialectName[], cb: (query: this) => void): this;
+    /** Apply `cb` on every dialect EXCEPT the given one(s) (Lucid `unlessDialect`). */
+    unlessDialect(dialect: DialectName | DialectName[], cb: (query: this) => void): this;
+    /** Prepend a `/* … *​/` SQL comment to the compiled query (Lucid/Knex `comment`). */
+    comment(text: string): this;
+    /**
+     * Set a caller-facing statement timeout in milliseconds (Lucid `timeout(ms)`).
+     * The awaiting promise rejects after `ms` on the primary result fetch. With
+     * `{ cancel: true }` a SERVER-side statement timeout is also applied — Postgres
+     * `statement_timeout`, MySQL `MAX_EXECUTION_TIME` (SELECT) — so the server
+     * aborts the query, not just the client. (SQLite has no server timeout; the
+     * client race applies.) Called with no argument it clears the timeout.
+     */
+    timeout(ms?: number, options?: {
+        cancel?: boolean;
+    }): this;
     /** Execute and return all matching entities, with preloaded relations. Fires beforeFetch/afterFetch. */
     exec(): Promise<T[]>;
+    /**
+     * Execute and return PLAIN row objects (raw snake_case DB columns), skipping
+     * model hydration, `@column({ consume })`, dirty-tracking and preloads —
+     * AdonisJS Lucid `pojo()`. Fast read path for reports/exports where model
+     * instances aren't needed.
+     */
+    pojo<R = Record<string, unknown>>(): Promise<R[]>;
+    /**
+     * Thread arbitrary context onto every instance this query hydrates, exposed as
+     * `entity.$sideloaded` (AdonisJS Lucid `sideload`) — e.g. the current tenant or
+     * user, so hooks/computed can read it. REPLACES the current sideloaded data by
+     * default (Lucid); pass `merge = true` to merge instead. The data also
+     * propagates to preloaded relation queries. Chainable.
+     */
+    sideload(values: Record<string, unknown>, merge?: boolean): this;
     /**
      * Resolve a relation to its table + correlated join predicate and return an
      * `ExistsWhere` clause. Used by whereHas / has / doesntHave / whereDoesntHave.
@@ -336,13 +790,32 @@ export declare class ModelQuery<T extends BaseEntity> {
      * without GROUP BY — SQL treats the whole sub-result as one group, so
      * COUNT(*) against the correlated rows returns the right number.
      */
-    /** `INNER JOIN <table> ON <left> = <right>`. */
+    /** `INNER JOIN` — alias of {@link innerJoin} (Lucid/Knex `join`). */
+    join(table: string, left: string, right: string): this;
+    join(table: string, left: string, operator: string, right: string): this;
+    join(table: string, build: (j: JoinBuilder) => void): this;
+    /** `INNER JOIN <table> ON <left> [op] <right>` or a callback `ON` builder. */
     innerJoin(table: string, left: string, right: string): this;
+    innerJoin(table: string, left: string, operator: string, right: string): this;
     innerJoin(table: string, build: (j: JoinBuilder) => void): this;
     leftJoin(table: string, left: string, right: string): this;
+    leftJoin(table: string, left: string, operator: string, right: string): this;
     leftJoin(table: string, build: (j: JoinBuilder) => void): this;
+    /** `LEFT OUTER JOIN` — alias of {@link leftJoin} (Lucid/Knex `leftOuterJoin`). */
+    leftOuterJoin(table: string, left: string, right: string): this;
+    leftOuterJoin(table: string, left: string, operator: string, right: string): this;
+    leftOuterJoin(table: string, build: (j: JoinBuilder) => void): this;
     rightJoin(table: string, left: string, right: string): this;
+    rightJoin(table: string, left: string, operator: string, right: string): this;
     rightJoin(table: string, build: (j: JoinBuilder) => void): this;
+    /** `RIGHT OUTER JOIN` — alias of {@link rightJoin} (Lucid/Knex `rightOuterJoin`). */
+    rightOuterJoin(table: string, left: string, right: string): this;
+    rightOuterJoin(table: string, left: string, operator: string, right: string): this;
+    rightOuterJoin(table: string, build: (j: JoinBuilder) => void): this;
+    /** `FULL OUTER JOIN` (Lucid/Knex `fullOuterJoin`; Postgres — MySQL/SQLite lack it). */
+    fullOuterJoin(table: string, left: string, right: string): this;
+    fullOuterJoin(table: string, left: string, operator: string, right: string): this;
+    fullOuterJoin(table: string, build: (j: JoinBuilder) => void): this;
     crossJoin(table: string): this;
     /**
      * **⚠ UNSAFE** — append a raw JOIN fragment verbatim. No identifier quoting,
@@ -360,7 +833,7 @@ export declare class ModelQuery<T extends BaseEntity> {
      *
      * @unsafe Raw SQL fragment — never concatenate user input into `fragment`.
      */
-    joinRaw(fragment: string): this;
+    joinRaw(fragment: string, bindings?: readonly unknown[]): this;
     /**
      * **SAFE** helper that builds an `INNER JOIN <table> ON <left> = <right>`
      * with dialect-correct identifier quoting on both sides. Thin sugar over
@@ -373,9 +846,31 @@ export declare class ModelQuery<T extends BaseEntity> {
      * you need multiple join conditions.
      */
     joinOn(table: string, left: string, right: string): this;
-    distinct(): this;
+    /**
+     * SELECT DISTINCT (Lucid/Knex `distinct`). With columns, those replace the
+     * projection too — `distinct('a', 'b')` ≈ `SELECT DISTINCT a, b`.
+     */
+    distinct(...columns: string[]): this;
+    /**
+     * `SELECT DISTINCT ON (cols) …` — keep the first row per distinct set of
+     * `columns` (Lucid/Knex `distinctOn`). Takes precedence over
+     * {@link distinct}.
+     *
+     * Postgres-only, and the compiler refuses it elsewhere: MySQL and SQLite
+     * would parse `DISTINCT (a, b)` as a plain DISTINCT over a row value and
+     * return a *different* result set rather than fail — a silent wrong answer
+     * is worse than an error.
+     *
+     * Postgres also requires the leading `ORDER BY` terms to match `columns`;
+     * that is left to the database to enforce.
+     */
+    distinctOn(...columns: string[]): this;
     /** `SELECT COUNT(DISTINCT col)`. */
     countDistinct(column: string): Promise<number>;
+    /** `SUM(DISTINCT col)` (Lucid parity). */
+    sumDistinct(column: string): Promise<number | null>;
+    /** `AVG(DISTINCT col)` (Lucid parity). */
+    avgDistinct(column: string): Promise<number | null>;
     /** `SELECT 1 FROM ... LIMIT 1` — returns boolean. */
     exists(): Promise<boolean>;
     doesntExist(): Promise<boolean>;
@@ -386,7 +881,7 @@ export declare class ModelQuery<T extends BaseEntity> {
     /** Alias for `apply` — Lucid compatibility. */
     withScopes(callback: (scopes: Record<string, (...args: unknown[]) => ModelQuery<T>>) => void): this;
     if<V>(condition: V | undefined | null | false, ifFn: (q: this, value: V) => void, elseFn?: (q: this) => void): this;
-    unless<V>(condition: V | undefined | null | false, fn: (q: this) => void): this;
+    unless<V>(condition: V | undefined | null | false, fn: (q: this) => void, elseFn?: (q: this) => void): this;
     /** Offset-based paginator. */
     paginate(page: number, perPage: number): Promise<Paginator<T>>;
     /**
@@ -414,20 +909,61 @@ export declare class ModelQuery<T extends BaseEntity> {
     /** Thin alias for `offset((page-1)*perPage).limit(perPage)`. */
     forPage(page: number, perPage: number): this;
     debug(flag?: boolean): this;
+    /**
+     * Attach arbitrary metadata to the `db:query` event this query emits (Adonis
+     * Lucid `reporterData`) — request id, user id, feature flag, … A listener
+     * reads it off `event.reporterData`. Repeated calls merge. Setting it also
+     * forces emission (like {@link debug}), so the data actually reaches a listener.
+     */
+    reporterData(data: Record<string, unknown>): this;
     /** Returns the compiled SQL with bindings interpolated as dialect-safe literals. */
     toQuery(): string;
     /** Deep clone of this query — mutations on the clone never affect the original. */
     clone(): ModelQuery<T>;
-    /** Execute a fluent UPDATE. Returns affected rows (or rows when `returning` is set). */
-    update(patch: Record<string, unknown>, returning?: string[]): Promise<number | Record<string, unknown>[]>;
-    /** Execute a fluent DELETE. Returns affected rows (or rows when `returning` is set). */
-    delete(returning?: string[]): Promise<number | Record<string, unknown>[]>;
-    increment(column: string, amount: number): Promise<number>;
+    /**
+     * Execute a fluent UPDATE (Lucid/Knex `update`). Accepts a `{ col: value }` map
+     * OR a single `(column, value)` pair; a value may be a `db.raw(...)` expression.
+     * Returns affected rows (or the RETURNING rows when `returning` is set).
+     */
+    update(column: string, value: unknown): DmlBuilder<number | Record<string, unknown>[]>;
+    update(patch: Record<string, unknown>, returning?: string[]): DmlBuilder<number | Record<string, unknown>[]>;
+    /**
+     * Execute a fluent DELETE. For a `@SoftDeletes` model this SOFT-deletes the
+     * scoped rows (stamps `deleted_at`) — consistent with the entity-level
+     * `delete()`; use {@link forceDelete} for a hard `DELETE`. For a non-soft-delete
+     * model it issues a hard `DELETE`. Returns affected rows (or rows when
+     * `returning` is set).
+     */
+    delete(returning?: string[]): DmlBuilder<number | Record<string, unknown>[]>;
+    /** Hard `DELETE` of the scoped rows, bypassing `@SoftDeletes` (AdonisJS/Lucid `forceDelete`). */
+    forceDelete(returning?: string[]): DmlBuilder<number | Record<string, unknown>[]>;
+    /**
+     * Bulk restore: clear `deleted_at` on the trashed rows matching the user's
+     * predicates (the soft-delete counterpart of {@link delete}). No-op count `0`
+     * on a non-soft-delete model. Independent of the current soft-scope — it always
+     * targets trashed rows (`deleted_at IS NOT NULL`).
+     */
+    restore(returning?: string[]): DmlBuilder<number | Record<string, unknown>[]>;
+    increment(column: string, amount?: number): Promise<number>;
     increment(patch: Record<string, number>): Promise<number>;
-    decrement(column: string, amount: number): Promise<number>;
+    decrement(column: string, amount?: number): Promise<number>;
     decrement(patch: Record<string, number>): Promise<number>;
     forUpdate(): this;
     forShare(): this;
+    /** Postgres `FOR NO KEY UPDATE` — a weaker lock that doesn't block FK checks (AdonisJS/Knex). */
+    forNoKeyUpdate(): this;
+    /** Postgres `FOR KEY SHARE` — the weakest share lock (AdonisJS/Knex). */
+    forKeyShare(): this;
+    /**
+     * Append `SKIP LOCKED` to the lock clause — locked rows are skipped instead of
+     * waited on (AdonisJS/Knex). Requires a base lock (`forUpdate`/`forShare`/…).
+     */
+    skipLocked(): this;
+    /**
+     * Append `NOWAIT` to the lock clause — error immediately instead of waiting on
+     * a locked row (AdonisJS/Knex). Requires a base lock (`forUpdate`/`forShare`/…).
+     */
+    noWait(): this;
 }
 export {};
 //# sourceMappingURL=ModelQuery.d.ts.map