vsrepo 2.5.0 → 2.7.0

package/dist/internal/utils/vs-query-builder.util.js

@@ -0,0 +1,401 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VSQueryBuilder = void 0;
+const VSRepoError_1 = require("../../errors/VSRepoError");
+const vsrepo_error_type_enum_1 = require("../enums/vsrepo-error-type.enum");
+const ordering_schema_1 = __importDefault(require("../validators/schemas/ordering.schema"));
+const relations_schema_1 = __importDefault(require("../validators/schemas/relations.schema"));
+const see_mode_schema_1 = __importDefault(require("../validators/schemas/see-mode.schema"));
+const select_schema_1 = __importDefault(require("../validators/schemas/select.schema"));
+const where_schema_1 = __importDefault(require("../validators/schemas/where.schema"));
+const v = __importStar(require("valibot"));
+/**
+ * Fluent builder for queries whose shape is only known at runtime (optional filters, user-controlled
+ * ordering and pagination, ...). Get one from `VSRepository.createQueryBuilder()`.
+ *
+ * Chain the configuration methods (`select`, `relations`, `where`, `orderBy`, `limit`, `offset`,
+ * `distinctOn`, `see`) and run the query with a terminal method (`getResult`,
+ * `getOneResult`, `getOneResultOrThrow`, `getCount`, `getExistence` or `getResultAndCount`). Nothing
+ * reaches the database until a terminal method is called.
+ *
+ * The builder is **mutable**: every chained call changes the same instance and returns it. Use
+ * {@link VSQueryBuilder.clone} to derive variations from a common base.
+ *
+ * Soft-delete is respected the same way as in the repository methods: when the repository has a
+ * `softRemoveKey`, only non-deleted records are seen unless {@link VSQueryBuilder.see} says otherwise.
+ *
+ * Arguments are validated as soon as they are passed to a chained method; an invalid one throws a
+ * `VSRepoError` of type `QUERY_BUILDER` and leaves the builder unchanged.
+ *
+ * @template Entity Type of the entity being queried.
+ * @template OrmTypes ORM-specific client/transaction types. See `VSRepoOrmTypes`.
+ *
+ * @example
+ * ```typescript
+ * const { result, count } = await userRepository
+ *     .createQueryBuilder()
+ *     .where({ active: true, balance: { gte: 100 } })
+ *     .relations({ address: true })
+ *     .orderBy({ createdAt: "desc" })
+ *     .limit(20)
+ *     .offset(40)
+ *     .getResultAndCount();
+ * ```
+ *
+ * @publicApi
+ */
+class VSQueryBuilder {
+    db;
+    adapter;
+    mergeWheresResolver;
+    logger;
+    options = {};
+    distinct;
+    seeMode = "active";
+    whereFilter;
+    /**
+     * @internal
+     */
+    constructor(db, adapter, mergeWheresResolver, logger) {
+        this.db = db;
+        this.adapter = adapter;
+        this.mergeWheresResolver = mergeWheresResolver;
+        this.logger = logger;
+    }
+    failValidation(issue, fallbackPath = "options") {
+        const path = issue?.path?.length ? issue.path.map(p => String(p.key)).join(".") : fallbackPath;
+        const message = `${path}: ${issue?.message ?? "validation failed"}`;
+        this.logger?.logError(`Validation failed (${vsrepo_error_type_enum_1.VSRepoErrorType.QUERY_BUILDER}): ${message}`);
+        throw new VSRepoError_1.VSRepoError(message, vsrepo_error_type_enum_1.VSRepoErrorType.QUERY_BUILDER);
+    }
+    validate(value, schema, fallbackPath) {
+        const parsed = v.safeParse(schema, value);
+        if (!parsed.success) {
+            this.failValidation(parsed.issues[0], fallbackPath);
+        }
+    }
+    resolveWhere() {
+        return this.mergeWheresResolver.resolve(this.seeMode, this.whereFilter ?? {});
+    }
+    // * Log de debug dos passos do builder e das queries. O objeto só é serializado se o nível for DEBUG
+    trace(message, obj) {
+        this.logger?.logDebug(`VSQueryBuilder: ${message}`, obj);
+    }
+    // * Nunca logar o `db` aqui (client/transação do ORM), só os parâmetros da query
+    async execute(operation, params, run) {
+        this.trace(operation, { see: this.seeMode, ...params });
+        const start = this.logger?.startPerformLog(`run query builder ${operation}`);
+        try {
+            return await run();
+        }
+        finally {
+            this.logger?.endPerformLog(start);
+        }
+    }
+    setOptions(options) {
+        this.options = options;
+    }
+    setWhereFilter(whereFilter) {
+        this.whereFilter = whereFilter;
+    }
+    setDistinct(distinct) {
+        this.distinct = distinct;
+    }
+    setSeeMode(seeMode) {
+        this.seeMode = seeMode;
+    }
+    /**
+     * Sets the client or transaction the query runs on, replacing the one given to `createQueryBuilder()`.
+     *
+     * It's lazy — it only matters when a terminal method runs — so a builder can be created before a
+     * transaction and pointed at it from inside, or a {@link VSQueryBuilder.clone} can be pointed at another
+     * client without touching the original builder.
+     *
+     * @param db Client or transaction that every following terminal call will use.
+     *
+     * @example
+     * ```typescript
+     * const qb = userRepository.createQueryBuilder().where({ active: true });
+     *
+     * await userRepository.transaction(async tx => {
+     *     qb.setDb(tx);
+     *     return qb.getResult();
+     * });
+     * ```
+     */
+    setDb(db) {
+        this.db = db;
+        this.trace("db replaced");
+    }
+    /**
+     * Runs the query and returns every matching record.
+     *
+     * Uses everything configured on the builder: filter, `select`, `relations`, `orderBy`, `limit`/`offset`
+     * and `distinctOn` (the only terminal method that applies `distinct`).
+     *
+     * @returns The matching records (an empty array if none).
+     */
+    async getResult() {
+        const where = this.resolveWhere();
+        const options = { ...this.options, distinct: this.distinct };
+        return this.execute("getResult", { where, options }, () => this.adapter.findMany(where, { ...options, db: this.db }));
+    }
+    /**
+     * Runs the query and returns the first matching record, or `null` if there is none.
+     *
+     * Uses the filter, `select`, `relations`, `orderBy` and `limit`/`offset`. `distinctOn` is not applied.
+     *
+     * @returns The record, or `null` when nothing matches.
+     */
+    async getOneResult() {
+        const where = this.resolveWhere();
+        const options = { ...this.options };
+        return this.execute("getOneResult", { where, options }, () => this.adapter.findOne(where, { ...options, db: this.db }));
+    }
+    /**
+     * Same as {@link VSQueryBuilder.getOneResult}, but throws instead of returning `null`.
+     *
+     * The error thrown when nothing matches is the one the adapter's `findOneOrThrow` raises; it is not wrapped.
+     *
+     * @returns The first matching record.
+     */
+    async getOneResultOrThrow() {
+        const where = this.resolveWhere();
+        const options = { ...this.options };
+        return this.execute("getOneResultOrThrow", { where, options }, () => this.adapter.findOneOrThrow(where, { ...options, db: this.db }));
+    }
+    /**
+     * Counts the records matching the filter.
+     *
+     * Forwards `orderBy` and `limit`/`offset` to the adapter's `count` as configured, so if you want the
+     * total of a builder that has pagination use {@link VSQueryBuilder.getResultAndCount} or count from a
+     * {@link VSQueryBuilder.clone} without it. `select`, `relations` and `distinctOn` are not used
+     * (`count` doesn't support `distinct`).
+     *
+     * @returns The number of matching records.
+     */
+    async getCount() {
+        const where = this.resolveWhere();
+        const options = { order: this.options.order, pagination: this.options.pagination };
+        return this.execute("getCount", { where, options }, () => this.adapter.count(where, { ...options, db: this.db }));
+    }
+    /**
+     * Checks whether at least one record matches the filter. Only the filter (and soft-delete visibility) is used.
+     *
+     * @returns `true` if a matching record exists, `false` otherwise.
+     */
+    async getExistence() {
+        const where = this.resolveWhere();
+        return this.execute("getExistence", { where }, () => this.adapter.exists(where, { db: this.db }));
+    }
+    /**
+     * Fetches a page of records and the total of records matching the filter, in a single call
+     * (like MikroORM's `getResultAndCount()`).
+     *
+     * `result` honors `orderBy` and `limit`/`offset`; `count` deliberately ignores `orderBy` and
+     * pagination, so it is the total that lets you compute the number of pages. Both queries run in
+     * parallel with the same filter and the same `db`. `distinctOn` is not used by either.
+     *
+     * @returns The page (`result`) and the total of matching records (`count`).
+     *
+     * @example
+     * ```typescript
+     * const { result, count } = await userRepository
+     *     .createQueryBuilder()
+     *     .where({ active: true })
+     *     .limit(20)
+     *     .offset(40)
+     *     .getResultAndCount();
+     *
+     * const totalPages = Math.ceil(count / 20);
+     * ```
+     */
+    async getResultAndCount() {
+        const where = this.resolveWhere();
+        const options = { ...this.options };
+        return this.execute("getResultAndCount", { where, options }, async () => {
+            const [result, count] = await Promise.all([
+                this.adapter.findMany(where, { ...options, db: this.db }),
+                this.adapter.count(where, { db: this.db }),
+            ]);
+            return { result, count };
+        });
+    }
+    /**
+     * Returns an independent builder with the same filter, options, `distinctOn` fields, `see` mode and `db`.
+     * Changes made to either builder afterwards don't affect the other.
+     *
+     * @returns The new builder.
+     *
+     * @example
+     * ```typescript
+     * const active = userRepository.createQueryBuilder().where({ active: true });
+     *
+     * const total = await active.clone().getCount();
+     * const firstPage = await active.clone().orderBy({ name: "asc" }).limit(10).getResult();
+     * ```
+     */
+    clone() {
+        const qbClone = new VSQueryBuilder(this.db, this.adapter, this.mergeWheresResolver, this.logger);
+        qbClone.setOptions(structuredClone(this.options));
+        qbClone.setWhereFilter(this.whereFilter);
+        qbClone.setDistinct(this.distinct);
+        qbClone.setSeeMode(this.seeMode);
+        this.trace("clone");
+        return qbClone;
+    }
+    /**
+     * Sets the fields (and nested relation fields) to select. Replaces any previous `select`.
+     *
+     * @param select Fields to select, e.g. `{ id: true, name: true, address: { city: true } }`.
+     * @throws {VSRepoError} `QUERY_BUILDER` if `select` doesn't have a valid shape.
+     */
+    select(select) {
+        this.validate(select, select_schema_1.default, "select");
+        this.options.select = select;
+        this.trace("select", select);
+        return this;
+    }
+    /**
+     * Sets the relations to load together with the records. Replaces any previous `relations`.
+     *
+     * @param relations Relations to load, e.g. `{ address: true, products: true }`.
+     * @throws {VSRepoError} `QUERY_BUILDER` if `relations` doesn't have a valid shape.
+     */
+    relations(relations) {
+        this.validate(relations, relations_schema_1.default, "relations");
+        this.options.relations = relations;
+        this.trace("relations", relations);
+        return this;
+    }
+    /**
+     * Sets the filter, replacing any previous one. It accepts the same `VSRepoWhere` used by the rest of
+     * the library: field-level filters (`{ active: true, balance: { gte: 100 } }`), relation filters
+     * (`_some`/`_every`/`_none`, `_with`/`_without`) and the logical operators `AND`, `OR` and `NOT`.
+     *
+     * The soft-delete filter (see {@link VSQueryBuilder.see}) is added on top of it when the query runs.
+     *
+     * @param where Filter of the query.
+     * @throws {VSRepoError} `QUERY_BUILDER` if `where` doesn't have a valid shape.
+     *
+     * @example
+     * ```typescript
+     * qb.where({
+     *     active: true,
+     *     OR: [{ name: { contains: "Maria" } }, { email: { contains: "maria" } }],
+     * });
+     * ```
+     */
+    where(where) {
+        this.validate(where, where_schema_1.default, "where");
+        this.whereFilter = where;
+        this.trace("where", where);
+        return this;
+    }
+    /**
+     * Sets the ordering. Replaces any previous ordering.
+     *
+     * @param order An object, or an array of objects, mapping primitive fields to `"asc"`/`"desc"`
+     * (lower or upper case), e.g. `{ createdAt: "desc" }`.
+     * @throws {VSRepoError} `QUERY_BUILDER` if `order` doesn't have a valid shape.
+     */
+    orderBy(order) {
+        this.validate(order, ordering_schema_1.default, "order");
+        this.options.order = order;
+        this.trace("orderBy", order);
+        return this;
+    }
+    /**
+     * Sets the maximum number of records to return. Can be combined with {@link VSQueryBuilder.offset}.
+     *
+     * @param limit Non-negative integer.
+     * @throws {VSRepoError} `QUERY_BUILDER` if `limit` isn't a non-negative integer.
+     */
+    limit(limit) {
+        this.validate(limit, v.pipe(v.number(), v.integer(), v.minValue(0)), "limit");
+        this.options.pagination ??= {};
+        this.options.pagination.limit = limit;
+        this.trace(`limit ${limit}`);
+        return this;
+    }
+    /**
+     * Sets how many records to skip. Can be combined with {@link VSQueryBuilder.limit}.
+     *
+     * @param offset Non-negative integer.
+     * @throws {VSRepoError} `QUERY_BUILDER` if `offset` isn't a non-negative integer.
+     */
+    offset(offset) {
+        this.validate(offset, v.pipe(v.number(), v.integer(), v.minValue(0)), "offset");
+        this.options.pagination ??= {};
+        this.options.pagination.offset = offset;
+        this.trace(`offset ${offset}`);
+        return this;
+    }
+    /**
+     * Sets the field(s) to apply `distinct` on. Replaces any previous `distinctOn`.
+     *
+     * Only {@link VSQueryBuilder.getResult} uses it: the ecosystem's `count` doesn't support `distinct`.
+     *
+     * @param fields A primitive field, or an array of them.
+     * @throws {VSRepoError} `QUERY_BUILDER` if `fields` isn't a string or an array of strings.
+     */
+    distinctOn(fields) {
+        this.validate(fields, v.union([v.string(), v.array(v.string())]), "fields");
+        this.distinct = Array.isArray(fields) ? fields : [fields];
+        this.trace("distinctOn", this.distinct);
+        return this;
+    }
+    /**
+     * Sets which records the query sees when the repository has a `softRemoveKey`. Applies to every
+     * terminal method (both queries of `getResultAndCount` included) and is ignored by repositories
+     * without soft-delete.
+     *
+     * @param seeMode `"active"` (default) for non-deleted records, `"removed"` for soft-deleted ones
+     * or `"all"` to ignore soft-delete.
+     * @throws {VSRepoError} `QUERY_BUILDER` if `seeMode` isn't one of the modes above.
+     */
+    see(seeMode) {
+        this.validate(seeMode, see_mode_schema_1.default, "seeMode");
+        this.seeMode = seeMode;
+        this.trace(`see '${seeMode}'`);
+        return this;
+    }
+}
+exports.VSQueryBuilder = VSQueryBuilder;
+//# sourceMappingURL=vs-query-builder.util.js.map

package/dist/internal/utils/vs-query-builder.util.js.map

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

package/dist/internal/utils/vs-raw-query-builder.util.d.ts

@@ -0,0 +1,238 @@
+import { VSRawQueryBuilderCteQuery } from "../../types/vsrepo/vs-raw-query-builder-cte-query.type";
+import { VSRawQueryBuilderTarget } from "../../types/vsrepo/vs-raw-query-builder-target.type";
+import { VSRepoOrmTypes } from "../../types/vsrepo/vsrepo-orm-types.type";
+import { VSSql } from "./vs-sql.util";
+/**
+ * Fluent, SQL-agnostic builder for hand-written **`SELECT`** queries whose shape is only known
+ * at runtime, but whose SQL is too specific (window functions, CTEs referenced elsewhere,
+ * vendor-specific syntax, ...) to express through {@link VSQueryBuilder}'s `where`/`relations`
+ * model. Compiles down to a single {@link VSSql} fragment — get one from
+ * `VSRepository.createRawQueryBuilder()`.
+ *
+ * Nothing reaches the database until {@link VSRawQueryBuilder.execute} is called. The builder is
+ * **mutable**: every chained call changes the same instance and returns it. Use
+ * {@link VSRawQueryBuilder.clone} to derive variations from a common base.
+ *
+ * @example
+ * ```typescript
+ * import { VSSql } from "vsrepo";
+ *
+ * const rows = await orderRepository
+ *     .createRawQueryBuilder()
+ *     .select("o.id", "o.total", "u.name")
+ *     .from("order", "o")
+ *     .innerJoin("user", "u", "u.id = o.user_id")
+ *     .where(VSSql.sql`u.active = ${true}`)
+ *     .andWhere(VSSql.sql`o.total > ${100}`)
+ *     .andWhere("o.deleted_at is null")
+ *     .groupBy("o.id", "u.name")
+ *     .having(VSSql.sql`count(*) > ${1}`)
+ *     .orderBy("o.total", "desc")
+ *     .limit(20)
+ *     .offset(0)
+ *     .execute<{ id: string; total: number; name: string }[]>();
+ * ```
+ *
+ * @publicApi
+ */
+export declare class VSRawQueryBuilder<OrmTypes extends VSRepoOrmTypes = VSRepoOrmTypes> {
+    private db;
+    private readonly adapter;
+    private readonly logger?;
+    private cteClauses;
+    private recursiveWith;
+    private selectColumns;
+    private fromTarget?;
+    private joinClauses;
+    private whereConditions;
+    private groupByColumns;
+    private havingConditions;
+    private orderByClauses;
+    private limitValue?;
+    private offsetValue?;
+    private trace;
+    private static validateNonEmptyString;
+    /** Converts a raw string into a `VSSql.raw` fragment (validating it isn't empty/blank first,
+     * since that would silently compile into broken SQL — e.g. a trailing comma or an empty
+     * `WHERE ()`) or passes an already-built `VSSql` fragment through untouched.
+     *
+     * @param context Name of the calling method/argument, used in the `VSRepoError` message. */
+    private static toFragment;
+    private newSubBuilder;
+    private resolveSubquery;
+    private resolveTarget;
+    private resolveCteQuery;
+    private static combine;
+    private static validateNonNegativeInt;
+    /**
+     * Sets the columns to select, replacing any previous `select`. Each column is either a raw,
+     * trusted string (an identifier, passed through as-is — like `VSSql.raw`, never pass
+     * user-controlled input) or a `VSSql` fragment for anything parameterized or aliased
+     * (**VSSql.sql\`count(*) AS total\`**).
+     *
+     * @param columns One or more columns/expressions. `select()` with no arguments is equivalent
+     * to `SELECT *`.
+     */
+    select(...columns: (string | VSSql)[]): this;
+    /**
+     * Sets the `FROM` target, replacing any previous one.
+     *
+     * @param target A raw table name, a `VSSql` fragment, or another `VSRawQueryBuilder`
+     * (compiled inline as a subquery, wrapped in parentheses).
+     * @param alias Optional alias, appended as `AS alias` (raw, trusted text).
+     */
+    from(target: VSRawQueryBuilderTarget, alias?: string): this;
+    private addCte;
+    /**
+     * Adds a `WITH` (common table expression). Each call adds one CTE; call it
+     * again to add more — they're all listed under a single `WITH`, in the order added.
+     *
+     * @param name Name the CTE is referenced by elsewhere in the query (raw, trusted text).
+     * @param query The CTE's body: a `VSRawQueryBuilder`, a subquery function, or a `VSSql` fragment — needed for
+     * anything a single `SELECT` builder can't express (e.g. a `UNION`).
+     * @param columns Optional explicit column list, rendered as `name(col1, col2) AS (...)`.
+     *
+     * @example
+     * ```typescript
+     * const rows = await orderRepository
+     *     .createRawQueryBuilder()
+     *     .with("big_spenders", qb => qb.select("user_id").from("order").groupBy("user_id").having("sum(total) > 1000"))
+     *     .select("u.*")
+     *     .from("user", "u")
+     *     .innerJoin("big_spenders", "bs", "bs.user_id = u.id")
+     *     .execute();
+     * ```
+     */
+    with(name: string, query: VSRawQueryBuilderCteQuery, columns?: string[]): this;
+    /**
+     * Same as {@link VSRawQueryBuilder.with}, but marks the whole `WITH` clause as `RECURSIVE`
+     * (required by the SQL standard for a CTE that references itself in its own body — usually
+     * a `VSSql` fragment with a `... UNION ALL SELECT ... FROM name ...` shape). One recursive
+     * CTE is enough to make the whole clause `WITH RECURSIVE`, even when combined with other,
+     * non-recursive ones added via {@link VSRawQueryBuilder.with}.
+     *
+     * @example
+     * ```typescript
+     * const orgChart = await employeeRepository
+     *     .createRawQueryBuilder()
+     *     .withRecursive(
+     *         "subordinates",
+     *         VSSql.sql`
+     *             SELECT id, manager_id, 1 AS depth FROM employee WHERE id = ${managerId}
+     *             UNION ALL
+     *             SELECT e.id, e.manager_id, s.depth + 1 FROM employee e
+     *             INNER JOIN subordinates s ON e.manager_id = s.id
+     *         `,
+     *         ["id", "manager_id", "depth"],
+     *     )
+     *     .select("*")
+     *     .from("subordinates")
+     *     .orderBy("depth")
+     *     .execute();
+     * ```
+     */
+    withRecursive(name: string, query: VSRawQueryBuilderCteQuery, columns?: string[]): this;
+    private addJoin;
+    /**
+     * Adds an `INNER JOIN`.
+     */
+    innerJoin(target: VSRawQueryBuilderTarget, alias: string, on: string | VSSql): this;
+    /**
+     * Adds a `LEFT JOIN`.
+     */
+    leftJoin(target: VSRawQueryBuilderTarget, alias: string, on: string | VSSql): this;
+    /**
+     * Adds a `RIGHT JOIN`.
+     */
+    rightJoin(target: VSRawQueryBuilderTarget, alias: string, on: string | VSSql): this;
+    /**
+     * Adds a `FULL JOIN`.
+     */
+    fullJoin(target: VSRawQueryBuilderTarget, alias: string, on: string | VSSql): this;
+    /**
+     * Adds a `WHERE` condition. The first call sets the filter; every later call (`where` or
+     * {@link VSRawQueryBuilder.andWhere}) is `AND`-combined with it, each wrapped in parentheses.
+     * Use {@link VSRawQueryBuilder.orWhere} to `OR`-combine instead.
+     */
+    where(condition: string | VSSql): this;
+    /** Alias for {@link VSRawQueryBuilder.where} — `AND`-combines `condition` with the existing filter. */
+    andWhere(condition: string | VSSql): this;
+    /** `OR`-combines `condition` with the existing `WHERE` filter. */
+    orWhere(condition: string | VSSql): this;
+    /**
+     * Adds columns to `GROUP BY`. Each call appends; call {@link VSRawQueryBuilder.clone} from a
+     * common base if you need independent variations.
+     */
+    groupBy(...columns: (string | VSSql)[]): this;
+    /**
+     * Adds a `HAVING` condition, `AND`-combined with any previous one (same semantics as
+     * {@link VSRawQueryBuilder.where}). Use {@link VSRawQueryBuilder.orHaving} to `OR`-combine.
+     */
+    having(condition: string | VSSql): this;
+    /** Alias for {@link VSRawQueryBuilder.having} — `AND`-combines `condition` with the existing `HAVING` filter. */
+    andHaving(condition: string | VSSql): this;
+    /** `OR`-combines `condition` with the existing `HAVING` filter. */
+    orHaving(condition: string | VSSql): this;
+    /**
+     * Adds a column to `ORDER BY`. Each call appends, in order, so call it once per column for a
+     * multi-column ordering.
+     */
+    orderBy(column: string | VSSql, direction?: "asc" | "desc" | "ASC" | "DESC"): this;
+    /**
+     * Sets the maximum number of rows to return, replacing any previous `limit`.
+     */
+    limit(limit: number): this;
+    /**
+     * Sets how many rows to skip, replacing any previous `offset`.
+     */
+    offset(offset: number): this;
+    /**
+     * Sets the client or transaction the query runs on, replacing the one given to
+     * `createRawQueryBuilder()`.
+     *
+     * It's lazy — it only matters when {@link VSRawQueryBuilder.execute} runs — so a builder can
+     * be created before a transaction and pointed at it from inside, or a
+     * {@link VSRawQueryBuilder.clone} can be pointed at another client without touching the
+     * original builder.
+     *
+     * @example
+     * ```typescript
+     * const qb = orderRepository.createRawQueryBuilder().select("*").from("order");
+     *
+     * await orderRepository.transaction(async tx => {
+     *     qb.setDb(tx);
+     *     return qb.execute();
+     * });
+     * ```
+     */
+    setDb(db: OrmTypes["dbClient"] | OrmTypes["dbTransaction"]): void;
+    /**
+     * Returns an independent builder with the same clauses and `db`. Changes made to either one
+     * afterwards don't affect the other (the underlying `VSSql`/`VSRawQueryBuilder` values
+     * themselves are immutable, so a shallow copy of every clause array is enough).
+     */
+    clone(): VSRawQueryBuilder<OrmTypes>;
+    private compileCteClause;
+    /**
+     * Compiles every configured clause into a single {@link VSSql} fragment, in the order
+     * `WITH` (CTEs) -> `SELECT` -> `FROM` -> `JOIN`s -> `WHERE` -> `GROUP BY` -> `HAVING` -> `ORDER BY`
+     * -> `LIMIT` -> `OFFSET`. Nothing runs by itself — splice the result into another `VSSql`
+     * fragment as a subquery, or pass it to `VSRepository.query()`.
+     */
+    toVSSql(): VSSql;
+    private compileForAdapter;
+    /**
+     * Compiles the builder down to a plain SQL string, rendered with the adapter's own
+     * placeholder syntax (e.g. `$1`, `$2`, ...). Values themselves are **not** interpolated into
+     * the string — use {@link VSRawQueryBuilder.toVSSql} (`.compile()`) or
+     * {@link VSRawQueryBuilder.execute} if you also need the parameter values/to run the query.
+     */
+    toSql(): string;
+    /**
+     * Compiles and runs the query against the underlying database, through the same adapter as
+     * every other `VSRepository` method.
+     *
+     * @template T Shape of the returned rows. Defaults to `any`.
+     */
+    execute<T = any>(): Promise<T>;
+}