kysely 0.11.2 → 0.12.1

package/dist/esm/query-builder/select-query-builder.js

@@ -0,0 +1,566 @@
+import { AliasNode } from '../operation-node/alias-node.js';
+import { parseJoin, } from '../parser/join-parser.js';
+import { parseSelectExpressionOrList, parseSelectAll, } from '../parser/select-parser.js';
+import { parseExistFilter, parseReferenceFilter, parseWhereFilter, parseHavingFilter, parseNotExistFilter, } from '../parser/filter-parser.js';
+import { SelectQueryNode } from '../operation-node/select-query-node.js';
+import { QueryNode } from '../operation-node/query-node.js';
+import { parseOrderBy, } from '../parser/order-by-parser.js';
+import { preventAwait } from '../util/prevent-await.js';
+import { LimitNode } from '../operation-node/limit-node.js';
+import { OffsetNode } from '../operation-node/offset-node.js';
+import { freeze } from '../util/object-utils.js';
+import { parseGroupBy } from '../parser/group-by-parser.js';
+import { parseUnion } from '../parser/union-parser.js';
+import { NoResultError } from './no-result-error.js';
+export class SelectQueryBuilder {
+    #props;
+    constructor(props) {
+        this.#props = freeze(props);
+    }
+    where(...args) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseWhereFilter(this.#props.parseContext, args)),
+        });
+    }
+    whereRef(lhs, op, rhs) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseReferenceFilter(this.#props.parseContext, lhs, op, rhs)),
+        });
+    }
+    orWhere(...args) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseWhereFilter(this.#props.parseContext, args)),
+        });
+    }
+    orWhereRef(lhs, op, rhs) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseReferenceFilter(this.#props.parseContext, lhs, op, rhs)),
+        });
+    }
+    whereExists(arg) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    whereNotExists(arg) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseNotExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    orWhereExists(arg) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    orWhereNotExists(arg) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseNotExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    having(...args) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseHavingFilter(this.#props.parseContext, args)),
+        });
+    }
+    havingRef(lhs, op, rhs) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseReferenceFilter(this.#props.parseContext, lhs, op, rhs)),
+        });
+    }
+    orHaving(...args) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseHavingFilter(this.#props.parseContext, args)),
+        });
+    }
+    orHavingRef(lhs, op, rhs) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseReferenceFilter(this.#props.parseContext, lhs, op, rhs)),
+        });
+    }
+    havingExists(arg) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    havingNotExist(arg) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseNotExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    orHavingExists(arg) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    orHavingNotExists(arg) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseNotExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    select(selection) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithSelections(this.#props.queryNode, parseSelectExpressionOrList(this.#props.parseContext, selection)),
+        });
+    }
+    distinctOn(selection) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithDistinctOnSelections(this.#props.queryNode, parseSelectExpressionOrList(this.#props.parseContext, selection)),
+        });
+    }
+    /**
+     * Makes the selection distinct.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.selectFrom('person')
+     *   .select('first_name')
+     *   .distinct()
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select distinct "first_name" from "person"
+     * ```
+     */
+    distinct() {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithDistinct(this.#props.queryNode),
+        });
+    }
+    /**
+     * Adds the `for update` option to a select query on supported databases.
+     */
+    forUpdate() {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithModifier(this.#props.queryNode, 'ForUpdate'),
+        });
+    }
+    /**
+     * Adds the `for share` option to a select query on supported databases.
+     */
+    forShare() {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithModifier(this.#props.queryNode, 'ForShare'),
+        });
+    }
+    /**
+     * Adds the `for key share` option to a select query on supported databases.
+     */
+    forKeyShare() {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithModifier(this.#props.queryNode, 'ForKeyShare'),
+        });
+    }
+    /**
+     * Adds the `for no key update` option to a select query on supported databases.
+     */
+    forNoKeyUpdate() {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithModifier(this.#props.queryNode, 'ForNoKeyUpdate'),
+        });
+    }
+    /**
+     * Adds the `skip locked` option to a select query on supported databases.
+     */
+    skipLocked() {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithModifier(this.#props.queryNode, 'SkipLocked'),
+        });
+    }
+    /**
+     * Adds the `nowait` option to a select query on supported databases.
+     */
+    noWait() {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithModifier(this.#props.queryNode, 'NoWait'),
+        });
+    }
+    selectAll(table) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithSelections(this.#props.queryNode, parseSelectAll(table)),
+        });
+    }
+    innerJoin(...args) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin(this.#props.parseContext, 'InnerJoin', args)),
+        });
+    }
+    leftJoin(...args) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin(this.#props.parseContext, 'LeftJoin', args)),
+        });
+    }
+    rightJoin(...args) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin(this.#props.parseContext, 'RightJoin', args)),
+        });
+    }
+    fullJoin(...args) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin(this.#props.parseContext, 'FullJoin', args)),
+        });
+    }
+    /**
+     * Adds an `order by` clause to the query.
+     *
+     * `orderBy` calls are additive. To order by multiple columns, call `orderBy`
+     * multiple times.
+     *
+     * The first argument is the expression to order by and the second is the
+     * order (`asc` or `desc`).
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db
+     *   .selectFrom('person')
+     *   .select('person.first_name as fn')
+     *   .orderBy('id')
+     *   .orderBy('fn', 'desc')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."first_name" as "fn"
+     * from "person"
+     * order by "id" asc, "fn" desc
+     * ```
+     *
+     * The order by expression can also be a `raw` expression or a subquery
+     * in addition to column references:
+     *
+     * ```ts
+     * await db
+     *   .selectFrom('person')
+     *   .selectAll()
+     *   .orderBy((qb) => qb.selectFrom('pet')
+     *     .select('pet.name')
+     *     .whereRef('pet.owner_id', '=', 'person.id')
+     *     .limit(1)
+     *   )
+     *   .orderBy(
+     *     db.raw('concat(first_name, last_name)')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select *
+     * from "person"
+     * order by
+     *   ( select "pet"."name"
+     *     from "pet"
+     *     where "pet"."owner_id" = "person"."id"
+     *     limit 1
+     *   ) asc,
+     *   concat(first_name, last_name) asc
+     * ```
+     *
+     * `dynamic.ref` can be used to refer to columns not known at
+     * compile time:
+     *
+     * ```ts
+     * async function someQuery(orderBy: string) {
+     *   const { ref } = db.dynamic
+     *
+     *   return await db
+     *     .selectFrom('person')
+     *     .select('person.first_name as fn')
+     *     .orderBy(ref(orderBy))
+     *     .execute()
+     * }
+     *
+     * someQuery('fn')
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."first_name" as "fn"
+     * from "person"
+     * order by "fn" asc
+     * ```
+     */
+    orderBy(orderBy, direction) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithOrderByItem(this.#props.queryNode, parseOrderBy(this.#props.parseContext, orderBy, direction)),
+        });
+    }
+    groupBy(groupBy) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithGroupByItems(this.#props.queryNode, parseGroupBy(this.#props.parseContext, groupBy)),
+        });
+    }
+    /**
+     * Adds a limit clause to the query.
+     *
+     * ### Examples
+     *
+     * Select the first 10 rows of the result:
+     *
+     * ```ts
+     * return await db
+     *   .selectFrom('person')
+     *   .select('first_name')
+     *   .limit(10)
+     * ```
+     *
+     * Select rows from index 10 to index 19 of the result:
+     *
+     * ```ts
+     * return await db
+     *   .selectFrom('person')
+     *   .select('first_name')
+     *   .offset(10)
+     *   .limit(10)
+     * ```
+     */
+    limit(limit) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithLimit(this.#props.queryNode, LimitNode.create(limit)),
+        });
+    }
+    /**
+     * Adds an offset clause to the query.
+     *
+     * ### Examples
+     *
+     * Select rows from index 10 to index 19 of the result:
+     *
+     * ```ts
+     * return await db
+     *   .selectFrom('person')
+     *   .select('first_name')
+     *   .offset(10)
+     *   .limit(10)
+     * ```
+     */
+    offset(offset) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithOffset(this.#props.queryNode, OffsetNode.create(offset)),
+        });
+    }
+    /**
+     * Combines another select query or raw expression to this query using `union`.
+     *
+     * The output row type of the combined query must match `this` query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(['id', 'first_name as name'])
+     *   .union(db.selectFrom('pet').select(['id', 'name']))
+     *   .orderBy('name')
+     * ```
+     */
+    union(expression) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithUnion(this.#props.queryNode, parseUnion(expression, false)),
+        });
+    }
+    /**
+     * Combines another select query or raw expression to this query using `union all`.
+     *
+     * The output row type of the combined query must match `this` query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(['id', 'first_name as name'])
+     *   .unionAll(db.selectFrom('pet').select(['id', 'name']))
+     *   .orderBy('name')
+     * ```
+     */
+    unionAll(expression) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithUnion(this.#props.queryNode, parseUnion(expression, true)),
+        });
+    }
+    /**
+     * Simply calls the given function passing `this` as the only argument.
+     *
+     * This method can be useful when adding optional method calls:
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .selectAll()
+     *   .call((qb) => {
+     *     if (something) {
+     *       return qb.where('something', '=', something)
+     *     } else {
+     *       return qb.where('somethingElse', '=', somethingElse)
+     *     }
+     *   })
+     *   .execute()
+     * ```
+     *
+     * The next example uses a helper funtion `log` to log a query:
+     *
+     * ```ts
+     * function log<T extends AnyQueryBuilder>(qb: T): T {
+     *   console.log(qb.compile())
+     *   return qb
+     * }
+     *
+     * db.selectFrom('person')
+     *   .selectAll()
+     *   .call(log)
+     *   .execute()
+     * ```
+     */
+    call(func) {
+        return func(this);
+    }
+    /**
+     * Gives an alias for the query. This method is only useful for sub queries.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.selectFrom('pet')
+     *   .selectAll('pet')
+     *   .select(
+     *     (qb) => qb.selectFrom('person')
+     *       .select('first_name')
+     *       .whereRef('pet.owner_id', '=', 'person.id')
+     *       .as('owner_first_name')
+     *   )
+     *   .execute()
+     * ```
+     */
+    as(alias) {
+        return new AliasedQueryBuilder(this, alias);
+    }
+    /**
+     * Change the output type of the query.
+     *
+     * You should only use this method as the last resort if the types
+     * don't support your use case.
+     */
+    castTo() {
+        return new SelectQueryBuilder(this.#props);
+    }
+    withPlugin(plugin) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            executor: this.#props.executor.withPlugin(plugin),
+        });
+    }
+    toOperationNode() {
+        return this.#props.executor.transformQuery(this.#props.queryNode, this.#props.queryId);
+    }
+    compile() {
+        return this.#props.executor.compileQuery(this.toOperationNode(), this.#props.queryId);
+    }
+    /**
+     * Executes the query and returns an array of rows.
+     *
+     * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
+     */
+    async execute() {
+        const compildQuery = this.compile();
+        const query = compildQuery.query;
+        const result = await this.#props.executor.executeQuery(compildQuery, this.#props.queryId);
+        return result.rows;
+    }
+    /**
+     * Executes the query and returns the first result or undefined if
+     * the query returned no result.
+     */
+    async executeTakeFirst() {
+        const [result] = await this.execute();
+        return result;
+    }
+    /**
+     * Executes the query and returns the first result or throws if
+     * the query returned no result.
+     *
+     * By default an instance of {@link NoResultError} is thrown, but you can
+     * provide a custom error class as the only argument to throw a different
+     * error.
+     */
+    async executeTakeFirstOrThrow(errorConstructor = NoResultError) {
+        const result = await this.executeTakeFirst();
+        if (result === undefined) {
+            throw new errorConstructor(this.toOperationNode());
+        }
+        return result;
+    }
+}
+preventAwait(SelectQueryBuilder, "don't await SelectQueryBuilder instances directly. To execute the query you need to call `execute` or `executeTakeFirst`.");
+/**
+ * {@link SelectQueryBuilder} with an alias. The result of calling {@link SelectQueryBuilder.as}.
+ */
+export class AliasedQueryBuilder {
+    #queryBuilder;
+    #alias;
+    constructor(queryBuilder, alias) {
+        this.#queryBuilder = queryBuilder;
+        this.#alias = alias;
+    }
+    /**
+     * @private
+     *
+     * This needs to be here just so that the typings work. Without this
+     * the generated .d.ts file contains no reference to the type param A
+     * which causes this type to be equal to AliasedQueryBuilder with any A
+     * as long as D, TB and O are the same.
+     */
+    get alias() {
+        return this.#alias;
+    }
+    toOperationNode() {
+        const node = this.#queryBuilder.toOperationNode();
+        if (SelectQueryNode.is(node)) {
+            return AliasNode.create(node, this.#alias);
+        }
+        throw new Error('only select queries can be aliased');
+    }
+}