vsrepo 2.6.0 → 2.7.0

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

@@ -0,0 +1,433 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VSRawQueryBuilder = void 0;
+const VSRepoError_1 = require("../../errors/VSRepoError");
+const vsrepo_error_type_enum_1 = require("../enums/vsrepo-error-type.enum");
+const vs_sql_util_1 = require("./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
+ */
+class VSRawQueryBuilder {
+    db;
+    adapter;
+    logger;
+    cteClauses = [];
+    recursiveWith = false;
+    selectColumns = [];
+    fromTarget;
+    joinClauses = [];
+    whereConditions = [];
+    groupByColumns = [];
+    havingConditions = [];
+    orderByClauses = [];
+    limitValue;
+    offsetValue;
+    /**
+     * @internal
+     */
+    constructor(db, adapter, logger) {
+        this.db = db;
+        this.adapter = adapter;
+        this.logger = logger;
+    }
+    trace(message, obj) {
+        this.logger?.logDebug(`VSRawQueryBuilder: ${message}`, obj);
+    }
+    static validateNonEmptyString(value, context) {
+        if (value.trim().length === 0) {
+            throw new VSRepoError_1.VSRepoError(`${context}: Invalid value: Expected a non-empty string but received ${value}`, vsrepo_error_type_enum_1.VSRepoErrorType.QUERY_BUILDER);
+        }
+    }
+    /** 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. */
+    static toFragment(value, context) {
+        if (typeof value !== "string") {
+            return value;
+        }
+        VSRawQueryBuilder.validateNonEmptyString(value, context);
+        return vs_sql_util_1.VSSql.raw(value);
+    }
+    newSubBuilder() {
+        return new VSRawQueryBuilder(this.db, this.adapter, this.logger);
+    }
+    resolveSubquery(value) {
+        const result = typeof value === "function" ? value(this.newSubBuilder()) : value;
+        return result instanceof VSRawQueryBuilder ? result.toVSSql() : result;
+    }
+    resolveTarget(target, context, alias) {
+        const base = target instanceof VSRawQueryBuilder || typeof target === "function"
+            ? vs_sql_util_1.VSSql.sql `(${this.resolveSubquery(target)})`
+            : VSRawQueryBuilder.toFragment(target, context);
+        if (alias === undefined) {
+            return base;
+        }
+        VSRawQueryBuilder.validateNonEmptyString(alias, "alias");
+        return vs_sql_util_1.VSSql.sql `${base} AS ${vs_sql_util_1.VSSql.raw(alias)}`;
+    }
+    resolveCteQuery(query) {
+        return query instanceof vs_sql_util_1.VSSql ? query : this.resolveSubquery(query);
+    }
+    static combine(conditions) {
+        let result = vs_sql_util_1.VSSql.sql `(${conditions[0].sql})`;
+        for (let i = 1; i < conditions.length; i++) {
+            const { connector, sql } = conditions[i];
+            result = connector === "AND" ? vs_sql_util_1.VSSql.sql `${result} AND (${sql})` : vs_sql_util_1.VSSql.sql `${result} OR (${sql})`;
+        }
+        return result;
+    }
+    static validateNonNegativeInt(value, name) {
+        if (!Number.isInteger(value) || value < 0) {
+            throw new VSRepoError_1.VSRepoError(`${name}: Invalid value: Expected >=0 but received ${value}`, vsrepo_error_type_enum_1.VSRepoErrorType.QUERY_BUILDER);
+        }
+    }
+    /**
+     * 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) {
+        this.selectColumns = columns.length
+            ? columns.map(column => VSRawQueryBuilder.toFragment(column, "select"))
+            : [vs_sql_util_1.VSSql.raw("*")];
+        return 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, alias) {
+        this.fromTarget = this.resolveTarget(target, "from", alias);
+        return this;
+    }
+    addCte(name, query, columns) {
+        VSRawQueryBuilder.validateNonEmptyString(name, "with");
+        if (columns) {
+            for (let i = 0; i < columns.length; i++) {
+                const column = columns[i];
+                VSRawQueryBuilder.validateNonEmptyString(column, `with columns[${i}]`);
+            }
+        }
+        this.cteClauses.push({ name, columns, query: this.resolveCteQuery(query) });
+        return this;
+    }
+    /**
+     * 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, query, columns) {
+        return this.addCte(name, query, columns);
+    }
+    /**
+     * 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, query, columns) {
+        this.recursiveWith = true;
+        return this.addCte(name, query, columns);
+    }
+    addJoin(type, target, alias, on) {
+        this.joinClauses.push({
+            type,
+            target: this.resolveTarget(target, "join", alias),
+            on: VSRawQueryBuilder.toFragment(on, "on"),
+        });
+        return this;
+    }
+    /**
+     * Adds an `INNER JOIN`.
+     */
+    innerJoin(target, alias, on) {
+        return this.addJoin("INNER", target, alias, on);
+    }
+    /**
+     * Adds a `LEFT JOIN`.
+     */
+    leftJoin(target, alias, on) {
+        return this.addJoin("LEFT", target, alias, on);
+    }
+    /**
+     * Adds a `RIGHT JOIN`.
+     */
+    rightJoin(target, alias, on) {
+        return this.addJoin("RIGHT", target, alias, on);
+    }
+    /**
+     * Adds a `FULL JOIN`.
+     */
+    fullJoin(target, alias, on) {
+        return this.addJoin("FULL", target, alias, on);
+    }
+    /**
+     * 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) {
+        this.whereConditions.push({ connector: "AND", sql: VSRawQueryBuilder.toFragment(condition, "where") });
+        return this;
+    }
+    /** Alias for {@link VSRawQueryBuilder.where} — `AND`-combines `condition` with the existing filter. */
+    andWhere(condition) {
+        this.whereConditions.push({ connector: "AND", sql: VSRawQueryBuilder.toFragment(condition, "andWhere") });
+        return this;
+    }
+    /** `OR`-combines `condition` with the existing `WHERE` filter. */
+    orWhere(condition) {
+        this.whereConditions.push({ connector: "OR", sql: VSRawQueryBuilder.toFragment(condition, "orWhere") });
+        return this;
+    }
+    /**
+     * Adds columns to `GROUP BY`. Each call appends; call {@link VSRawQueryBuilder.clone} from a
+     * common base if you need independent variations.
+     */
+    groupBy(...columns) {
+        this.groupByColumns.push(...columns.map(column => VSRawQueryBuilder.toFragment(column, "groupBy")));
+        return 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) {
+        this.havingConditions.push({ connector: "AND", sql: VSRawQueryBuilder.toFragment(condition, "having") });
+        return this;
+    }
+    /** Alias for {@link VSRawQueryBuilder.having} — `AND`-combines `condition` with the existing `HAVING` filter. */
+    andHaving(condition) {
+        this.havingConditions.push({ connector: "AND", sql: VSRawQueryBuilder.toFragment(condition, "andHaving") });
+        return this;
+    }
+    /** `OR`-combines `condition` with the existing `HAVING` filter. */
+    orHaving(condition) {
+        this.havingConditions.push({ connector: "OR", sql: VSRawQueryBuilder.toFragment(condition, "orHaving") });
+        return 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, direction) {
+        const base = VSRawQueryBuilder.toFragment(column, "orderBy");
+        this.orderByClauses.push(direction ? vs_sql_util_1.VSSql.sql `${base} ${vs_sql_util_1.VSSql.raw(direction.toUpperCase())}` : base);
+        return this;
+    }
+    /**
+     * Sets the maximum number of rows to return, replacing any previous `limit`.
+     */
+    limit(limit) {
+        VSRawQueryBuilder.validateNonNegativeInt(limit, "limit");
+        this.limitValue = limit;
+        return this;
+    }
+    /**
+     * Sets how many rows to skip, replacing any previous `offset`.
+     */
+    offset(offset) {
+        VSRawQueryBuilder.validateNonNegativeInt(offset, "offset");
+        this.offsetValue = offset;
+        return 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) {
+        this.db = db;
+        this.trace("db replaced");
+    }
+    /**
+     * 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() {
+        const copy = new VSRawQueryBuilder(this.db, this.adapter, this.logger);
+        copy.recursiveWith = this.recursiveWith;
+        copy.cteClauses = [...this.cteClauses];
+        copy.selectColumns = [...this.selectColumns];
+        copy.fromTarget = this.fromTarget;
+        copy.joinClauses = [...this.joinClauses];
+        copy.whereConditions = [...this.whereConditions];
+        copy.groupByColumns = [...this.groupByColumns];
+        copy.havingConditions = [...this.havingConditions];
+        copy.orderByClauses = [...this.orderByClauses];
+        copy.limitValue = this.limitValue;
+        copy.offsetValue = this.offsetValue;
+        this.trace("clone");
+        return copy;
+    }
+    compileCteClause() {
+        const ctes = this.cteClauses.map(({ name, columns, query }) => {
+            const columnList = columns?.length ? vs_sql_util_1.VSSql.sql `(${vs_sql_util_1.VSSql.raw(columns.join(", "))}) ` : vs_sql_util_1.VSSql.empty;
+            return vs_sql_util_1.VSSql.sql `${vs_sql_util_1.VSSql.raw(name)} ${columnList}AS (${query})`;
+        });
+        return vs_sql_util_1.VSSql.sql `WITH ${this.recursiveWith ? vs_sql_util_1.VSSql.raw("RECURSIVE ") : vs_sql_util_1.VSSql.empty}${vs_sql_util_1.VSSql.join(ctes, ", ")}`;
+    }
+    /**
+     * 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() {
+        if (!this.fromTarget) {
+            throw new VSRepoError_1.VSRepoError("'from' is required before calling 'toVSSql'", vsrepo_error_type_enum_1.VSRepoErrorType.QUERY_BUILDER);
+        }
+        const select = this.selectColumns.length ? vs_sql_util_1.VSSql.join(this.selectColumns, ", ") : vs_sql_util_1.VSSql.raw("*");
+        let query = vs_sql_util_1.VSSql.sql `SELECT ${select} FROM ${this.fromTarget}`;
+        for (const { type, target, on } of this.joinClauses) {
+            query = vs_sql_util_1.VSSql.sql `${query} ${vs_sql_util_1.VSSql.raw(`${type} JOIN`)} ${target} ON ${on}`;
+        }
+        if (this.whereConditions.length) {
+            query = vs_sql_util_1.VSSql.sql `${query} WHERE ${VSRawQueryBuilder.combine(this.whereConditions)}`;
+        }
+        if (this.groupByColumns.length) {
+            query = vs_sql_util_1.VSSql.sql `${query} GROUP BY ${vs_sql_util_1.VSSql.join(this.groupByColumns, ", ")}`;
+        }
+        if (this.havingConditions.length) {
+            query = vs_sql_util_1.VSSql.sql `${query} HAVING ${VSRawQueryBuilder.combine(this.havingConditions)}`;
+        }
+        if (this.orderByClauses.length) {
+            query = vs_sql_util_1.VSSql.sql `${query} ORDER BY ${vs_sql_util_1.VSSql.join(this.orderByClauses, ", ")}`;
+        }
+        if (this.limitValue !== undefined) {
+            query = vs_sql_util_1.VSSql.sql `${query} LIMIT ${this.limitValue}`;
+        }
+        if (this.offsetValue !== undefined) {
+            query = vs_sql_util_1.VSSql.sql `${query} OFFSET ${this.offsetValue}`;
+        }
+        if (this.cteClauses.length) {
+            query = vs_sql_util_1.VSSql.sql `${this.compileCteClause()} ${query}`;
+        }
+        return query;
+    }
+    compileForAdapter() {
+        if (!this.adapter.getPlaceholder) {
+            throw new VSRepoError_1.VSRepoError("Your adapter did not implement the 'getPlaceholder' method, required to compile a " +
+                "'VSRawQueryBuilder'; try updating your adapter to a newer version.", vsrepo_error_type_enum_1.VSRepoErrorType.QUERY_BUILDER);
+        }
+        return this.toVSSql().compile(index => this.adapter.getPlaceholder(index));
+    }
+    /**
+     * 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() {
+        return this.compileForAdapter().text;
+    }
+    /**
+     * 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`.
+     */
+    async execute() {
+        const { text, args } = this.compileForAdapter();
+        this.trace("execute", { query: text, args });
+        const start = this.logger?.startPerformLog("run raw query builder execute");
+        try {
+            return await this.adapter.query(text, { args, db: this.db, modifying: false });
+        }
+        finally {
+            this.logger?.endPerformLog(start);
+        }
+    }
+}
+exports.VSRawQueryBuilder = VSRawQueryBuilder;
+//# sourceMappingURL=vs-raw-query-builder.util.js.map

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

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

package/dist/internal/utils/vs-sql.util.d.ts

@@ -0,0 +1,100 @@
+/**
+ * An ORM-agnostic, composable SQL fragment that compiles down to whatever placeholder
+ * syntax your adapter declares via `VSRepoAdapter.getPlaceholder()`, instead of assuming one.
+ *
+ * A `VSSql` never touches the database by itself — build one with `VSSql.sql`
+ * (or compose it from `VSSql.raw`/`VSSql.join`/`VSSql.empty`) and pass it
+ * straight to `VSRepository.query()`, which compiles and executes it.
+ *
+ * Values interpolated with `${...}` are always sent as parameters. Nesting
+ * another `VSSql` inline splices its text and parameters into the outer
+ * fragment, so fragments compose freely:
+ *
+ * @example
+ * ```typescript
+ * import { VSSql } from "vsrepo";
+ *
+ * const filter = onlyActive ? VSSql.sql`AND active = ${true}` : VSSql.empty;
+ *
+ * const fragment = VSSql.sql`
+ *     SELECT * FROM ${VSSql.raw('"user"')}
+ *     WHERE id IN (${VSSql.join(ids)})
+ *     ${filter}
+ * `;
+ *
+ * const users = await userRepository.query<User[]>(fragment);
+ * ```
+ *
+ * @publicApi
+ */
+export declare class VSSql {
+    private readonly chunks;
+    private readonly values;
+    private constructor();
+    /**
+     * Appends `value` to the in-progress `chunks`/`values` pair: a nested
+     * `VSSql` is spliced in (its own text merged into the current trailing
+     * chunk, its own parameters appended in order), anything else becomes a
+     * single new parameter. `chunks` always has `values.length + 1` entries.
+     */
+    private static appendValue;
+    /**
+     * Compiles this fragment into a single SQL string and its positional
+     * argument array, rendering each parameter's placeholder with
+     * `getPlaceholder(index)` — `index` is the 0-based position of the
+     * parameter in the returned `args` array. Used internally by
+     * `VSRepository.query()`; only call this directly if you need the raw
+     * `{ text, args }` pair for something else (e.g. logging).
+     */
+    compile(getPlaceholder: (index: number) => string): {
+        text: string;
+        args: unknown[];
+    };
+    /**
+     * Builds a `VSSql` fragment from a tagged template literal. Every
+     * interpolated `${value}` becomes a parameter, except another `VSSql`
+     * (e.g. from `raw()`, `join()`, or a nested `sql` fragment), which is
+     * spliced in as text + its own parameters instead.
+     *
+     * @example
+     * ```typescript
+     * const fragment = VSSql.sql`SELECT * FROM "user" WHERE email = ${email}`;
+     * const users = await userRepository.query<User[]>(fragment);
+     * ```
+     */
+    static sql(strings: TemplateStringsArray, ...values: unknown[]): VSSql;
+    /**
+     * Inserts `text` into the query as-is, unparameterized — for identifiers
+     * (table/column names) or SQL keywords that can't be bound as a
+     * parameter. `text` is never escaped or validated: only pass trusted,
+     * non-user-controlled input.
+     *
+     * @example
+     * ```typescript
+     * const table = VSSql.raw('"user"');
+     * const fragment = VSSql.sql`SELECT * FROM ${table} WHERE active = ${true}`;
+     * ```
+     */
+    static raw(text: string): VSSql;
+    /**
+     * An empty fragment — contributes no text and no parameters. Useful as
+     * the "nothing" branch when conditionally composing a fragment.
+     * @example
+     * ```typescript
+     * condition ? VSSql.sql`AND active = true` : VSSql.empty
+     * ```
+     */
+    static readonly empty: VSSql;
+    /**
+     * Joins `values` into a single fragment, separated by `separator` and
+     * wrapped by `prefix`/`suffix`. Each element is either a parameter value
+     * (auto-wrapped, like a normal `${...}` interpolation) or a nested `VSSql`
+     * fragment (spliced in). Most commonly used to build an `IN (...)` list.
+     *
+     * @example
+     * ```typescript
+     * const fragment = VSSql.sql`WHERE id IN (${VSSql.join(ids)})`;
+     * ```
+     */
+    static join(values: readonly unknown[], separator?: string, prefix?: string, suffix?: string): VSSql;
+}