kysely 0.26.1 → 0.26.3

package/dist/esm/query-builder/select-query-builder.d.ts

@@ -1,48 +1,31 @@
-import { AliasNode } from '../operation-node/alias-node.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { JoinCallbackExpression, JoinReferenceExpression } from '../parser/join-parser.js';
 import { TableExpression } from '../parser/table-parser.js';
-import { SelectExpression, Selection, SelectArg, AllSelection } from '../parser/select-parser.js';
+import { SelectExpression, Selection, AllSelection, SelectCallback, CallbackSelection } from '../parser/select-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
 import { SelectQueryNode } from '../operation-node/select-query-node.js';
 import { QueryNode } from '../operation-node/query-node.js';
-import { DrainOuterGeneric, NarrowPartial, Nullable, ShallowRecord, Simplify, SimplifySingleResult } from '../util/type-utils.js';
-import { OrderByDirectionExpression, OrderByExpression } from '../parser/order-by-parser.js';
+import { DrainOuterGeneric, NarrowPartial, Nullable, ShallowRecord, Simplify, SimplifySingleResult, SqlBool } from '../util/type-utils.js';
+import { OrderByDirectionExpression, OrderByExpression, DirectedOrderByStringReference, UndirectedOrderByExpression } from '../parser/order-by-parser.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
 import { GroupByArg } from '../parser/group-by-parser.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
-import { WhereExpressionFactory, WhereInterface } from './where-interface.js';
+import { WhereInterface } from './where-interface.js';
 import { NoResultErrorConstructor } from './no-result-error.js';
-import { HavingExpressionFactory, HavingInterface } from './having-interface.js';
+import { HavingInterface } from './having-interface.js';
 import { Explainable, ExplainFormat } from '../util/explainable.js';
+import { SetOperandExpression } from '../parser/set-operation-parser.js';
 import { AliasedExpression, Expression } from '../expression/expression.js';
 import { ComparisonOperatorExpression, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
 import { KyselyTypeError } from '../util/type-error.js';
 import { Selectable } from '../util/column-type.js';
 import { Streamable } from '../util/streamable.js';
-export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, HavingInterface<DB, TB>, Expression<O>, Compilable<O>, Explainable, Streamable<O> {
-    #private;
-    constructor(props: SelectQueryBuilderProps);
-    /** @private */
-    /**
-     * All expressions need to have this getter for complicated type-related reasons.
-     * Simply add this getter for your expression and always return `undefined` from it:
-     *
-     * ```ts
-     * class SomeExpression<T> implements Expression<T> {
-     *   get expressionType(): T | undefined {
-     *     return undefined
-     *   }
-     * }
-     * ```
-     *
-     * The getter is needed to make the expression assignable to another expression only
-     * if the types `T` are assignable. Without this property (or some other property
-     * that references `T`), you could assing `Expression<string>` to `Expression<number>`.
-     */
-    get expressionType(): O | undefined;
+import { ExpressionOrFactory } from '../parser/expression-parser.js';
+import { ExpressionWrapper } from '../expression/expression-wrapper.js';
+import { SelectQueryBuilderExpression } from './select-query-builder-expression.js';
+export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInterface<DB, TB>, HavingInterface<DB, TB>, SelectQueryBuilderExpression<O>, Compilable<O>, Explainable, Streamable<O> {
     /**
      * Adds a `where` expression to the query.
      *
@@ -96,7 +79,34 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
-     * <!-- siteExample("where", "OR where", 30) -->
+     * <!-- siteExample("where", "Object filter", 30) -->
+     *
+     * You can use the `and` function to create a simple equality
+     * filter using an object
+     *
+     * ```ts
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .selectAll()
+     *   .where((eb) => eb.and({
+     *     first_name: 'Jennifer',
+     *     last_name: eb.ref('first_name')
+     *   }))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select *
+     * from "person"
+     * where (
+     *   "first_name" = $1
+     *   and "last_name" = "first_name"
+     * )
+     * ```
+     *
+     * <!-- siteExample("where", "OR where", 40) -->
      *
      * To combine conditions using `OR`, you can use the expression builder.
      * There are two ways to create `OR` expressions. Both are shown in this
@@ -131,7 +141,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * )
      * ```
      *
-     * <!-- siteExample("where", "Conditional where calls", 40) -->
+     * <!-- siteExample("where", "Conditional where calls", 50) -->
      *
      * You can add expressions conditionally like this:
      *
@@ -226,7 +236,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
-     * <!-- siteExample("where", "Complex where clause", 50) -->
+     * <!-- siteExample("where", "Complex where clause", 60) -->
      *
      * For complex `where` expressions you can pass in a single callback and
      * use the `ExpressionBuilder` to build your expression:
@@ -316,8 +326,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```
      */
     where<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): SelectQueryBuilder<DB, TB, O>;
-    where(factory: WhereExpressionFactory<DB, TB>): SelectQueryBuilder<DB, TB, O>;
-    where(expression: Expression<any>): SelectQueryBuilder<DB, TB, O>;
+    where(expression: ExpressionOrFactory<DB, TB, SqlBool>): SelectQueryBuilder<DB, TB, O>;
     /**
      * Adds a `where` clause where both sides of the operator are references
      * to columns.
@@ -375,8 +384,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * instead of a `where` statement.
      */
     having<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): SelectQueryBuilder<DB, TB, O>;
-    having(factory: HavingExpressionFactory<DB, TB>): SelectQueryBuilder<DB, TB, O>;
-    having(expression: Expression<any>): SelectQueryBuilder<DB, TB, O>;
+    having(expression: ExpressionOrFactory<DB, TB, SqlBool>): SelectQueryBuilder<DB, TB, O>;
     /**
      * Just like {@link WhereInterface.whereRef | whereRef} but adds a `having` statement
      * instead of a `where` statement.
@@ -568,7 +576,9 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * persons[0].id
      * ```
      */
-    select<SE extends SelectExpression<DB, TB>>(selection: SelectArg<DB, TB, SE>): SelectQueryBuilder<DB, TB, O & Selection<DB, TB, SE>>;
+    select<SE extends SelectExpression<DB, TB>>(selections: ReadonlyArray<SE>): SelectQueryBuilder<DB, TB, O & Selection<DB, TB, SE>>;
+    select<CB extends SelectCallback<DB, TB>>(callback: CB): SelectQueryBuilder<DB, TB, O & CallbackSelection<DB, TB, CB>>;
+    select<SE extends SelectExpression<DB, TB>>(selection: SE): SelectQueryBuilder<DB, TB, O & Selection<DB, TB, SE>>;
     /**
      * Adds `distinct on` expressions to the select clause.
      *
@@ -917,14 +927,28 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
     /**
      * Adds an `order by` clause to the query.
      *
-     * `orderBy` calls are additive. To order by multiple columns, call `orderBy`
-     * multiple times.
+     * `orderBy` calls are additive. Meaning, additional `orderBy` calls append to
+     * the existing order by clause.
+     *
+     * In a single call you can add a single column/expression or multiple columns/expressions.
      *
-     * The first argument is the expression to order by and the second is the
-     * order (`asc` or `desc`).
+     * Single column/expression calls can have 1-2 arguments. The first argument is
+     * the expression to order by (optionally including the direction) while the second
+     * optional argument is the direction (`asc` or `desc`).
      *
      * ### Examples
      *
+     * Single column/expression per call:
+     *
+     * ```ts
+     * await db
+     *   .selectFrom('person')
+     *   .select('person.first_name as fn')
+     *   .orderBy('id')
+     *   .orderBy('fn desc')
+     *   .execute()
+     * ```
+     *
      * ```ts
      * await db
      *   .selectFrom('person')
@@ -942,6 +966,16 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * order by "id" asc, "fn" desc
      * ```
      *
+     * Multiple columns/expressions per call:
+     *
+     * ```ts
+     * await db
+     *   .selectFrom('person')
+     *   .select('person.first_name as fn')
+     *   .orderBy(['id', 'fn desc'])
+     *   .execute()
+     * ```
+     *
      * The order by expression can also be a raw sql expression or a subquery
      * in addition to column references:
      *
@@ -1001,7 +1035,9 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * order by "fn" asc
      * ```
      */
-    orderBy(orderBy: OrderByExpression<DB, TB, O>, direction?: OrderByDirectionExpression): SelectQueryBuilder<DB, TB, O>;
+    orderBy(orderBy: UndirectedOrderByExpression<DB, TB, O>, direction?: OrderByDirectionExpression): SelectQueryBuilder<DB, TB, O>;
+    orderBy(ref: DirectedOrderByStringReference<DB, TB, O>): SelectQueryBuilder<DB, TB, O>;
+    orderBy(refs: ReadonlyArray<OrderByExpression<DB, TB, O>>): SelectQueryBuilder<DB, TB, O>;
     /**
      * Adds a `group by` clause to the query.
      *
@@ -1155,8 +1191,20 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   .union(db.selectFrom('pet').select(['id', 'name']))
      *   .orderBy('name')
      * ```
+     *
+     * You can provide a callback to get an expression builder.
+     * In the following example, this allows us to wrap the query in parentheses:
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(['id', 'first_name as name'])
+     *   .union((eb) => eb.parens(
+     *     eb.selectFrom('pet').select(['id', 'name'])
+     *   ))
+     *   .orderBy('name')
+     * ```
      */
-    union(expression: Expression<O>): SelectQueryBuilder<DB, TB, O>;
+    union(expression: SetOperandExpression<DB, O>): SelectQueryBuilder<DB, TB, O>;
     /**
      * Combines another select query or raw expression to this query using `union all`.
      *
@@ -1170,8 +1218,20 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   .unionAll(db.selectFrom('pet').select(['id', 'name']))
      *   .orderBy('name')
      * ```
+     *
+     * You can provide a callback to get an expression builder.
+     * In the following example, this allows us to wrap the query in parentheses:
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(['id', 'first_name as name'])
+     *   .unionAll((eb) => eb.parens(
+     *     eb.selectFrom('pet').select(['id', 'name'])
+     *   ))
+     *   .orderBy('name')
+     * ```
      */
-    unionAll(expression: Expression<O>): SelectQueryBuilder<DB, TB, O>;
+    unionAll(expression: SetOperandExpression<DB, O>): SelectQueryBuilder<DB, TB, O>;
     /**
      * Combines another select query or raw expression to this query using `intersect`.
      *
@@ -1185,8 +1245,20 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   .intersect(db.selectFrom('pet').select(['id', 'name']))
      *   .orderBy('name')
      * ```
+     *
+     * You can provide a callback to get an expression builder.
+     * In the following example, this allows us to wrap the query in parentheses:
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(['id', 'first_name as name'])
+     *   .intersect((eb) => eb.parens(
+     *     eb.selectFrom('pet').select(['id', 'name'])
+     *   ))
+     *   .orderBy('name')
+     * ```
      */
-    intersect(expression: Expression<O>): SelectQueryBuilder<DB, TB, O>;
+    intersect(expression: SetOperandExpression<DB, O>): SelectQueryBuilder<DB, TB, O>;
     /**
      * Combines another select query or raw expression to this query using `intersect all`.
      *
@@ -1200,8 +1272,20 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   .intersectAll(db.selectFrom('pet').select(['id', 'name']))
      *   .orderBy('name')
      * ```
+     *
+     * You can provide a callback to get an expression builder.
+     * In the following example, this allows us to wrap the query in parentheses:
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(['id', 'first_name as name'])
+     *   .intersectAll((eb) => eb.parens(
+     *     eb.selectFrom('pet').select(['id', 'name'])
+     *   ))
+     *   .orderBy('name')
+     * ```
      */
-    intersectAll(expression: Expression<O>): SelectQueryBuilder<DB, TB, O>;
+    intersectAll(expression: SetOperandExpression<DB, O>): SelectQueryBuilder<DB, TB, O>;
     /**
      * Combines another select query or raw expression to this query using `except`.
      *
@@ -1215,8 +1299,20 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   .except(db.selectFrom('pet').select(['id', 'name']))
      *   .orderBy('name')
      * ```
+     *
+     * You can provide a callback to get an expression builder.
+     * In the following example, this allows us to wrap the query in parentheses:
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(['id', 'first_name as name'])
+     *   .except((eb) => eb.parens(
+     *     eb.selectFrom('pet').select(['id', 'name'])
+     *   ))
+     *   .orderBy('name')
+     * ```
      */
-    except(expression: Expression<O>): SelectQueryBuilder<DB, TB, O>;
+    except(expression: SetOperandExpression<DB, O>): SelectQueryBuilder<DB, TB, O>;
     /**
      * Combines another select query or raw expression to this query using `except all`.
      *
@@ -1230,8 +1326,20 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   .exceptAll(db.selectFrom('pet').select(['id', 'name']))
      *   .orderBy('name')
      * ```
+     *
+     * You can provide a callback to get an expression builder.
+     * In the following example, this allows us to wrap the query in parentheses:
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(['id', 'first_name as name'])
+     *   .exceptAll((eb) => eb.parens(
+     *     eb.selectFrom('pet').select(['id', 'name'])
+     *   ))
+     *   .orderBy('name')
+     * ```
      */
-    exceptAll(expression: Expression<O>): SelectQueryBuilder<DB, TB, O>;
+    exceptAll(expression: SetOperandExpression<DB, O>): SelectQueryBuilder<DB, TB, O>;
     /**
      * Gives an alias for the query. This method is only useful for sub queries.
      *
@@ -1251,7 +1359,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * pets[0].owner_first_name
      * ```
      */
-    as<A extends string>(alias: A): AliasedSelectQueryBuilder<DB, TB, O, A>;
+    as<A extends string>(alias: A): AliasedSelectQueryBuilder<O, A>;
     /**
      * Clears all select clauses from the query.
      *
@@ -1445,6 +1553,54 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * don't support your use case.
      */
     $castTo<T>(): SelectQueryBuilder<DB, TB, T>;
+    /**
+     * Changes the output type from an object to a tuple.
+     *
+     * This doesn't affect the generated SQL in any way. This function is
+     * just a necessary evil when you need to convert a query's output
+     * record type to a tuple type. Typescript doesn't currently offer
+     * tools to do this automatically (without insane hackery).
+     *
+     * The returned object can no longer be executed. It can only be used
+     * as a subquery.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .selectAll('person')
+     *   .where(({ eb, refTuple, selectFrom }) => eb(
+     *     refTuple('first_name', 'last_name'),
+     *     'in',
+     *     selectFrom('pet')
+     *       .select(['name', 'species'])
+     *       .where('pet.species', '!=', 'cat')
+     *       .$asTuple('name', 'species')
+     *   ))
+     * ```
+     *
+     * The generated SQL(PostgreSQL):
+     *
+     * ```sql
+     * select
+     *   "person".*
+     * from
+     *   "person"
+     * where
+     *   ("first_name", "last_name")
+     *   in
+     *   (
+     *     select "name", "species"
+     *     from "pet"
+     *     where "pet"."species" != $1
+     *   )
+     * ```
+     */
+    $asTuple<K1 extends keyof O, K2 extends Exclude<keyof O, K1>>(key1: K1, key2: K2): keyof O extends K1 | K2 ? ExpressionWrapper<DB, TB, [O[K1], O[K2]]> : KyselyTypeError<'$asTuple() call failed: All selected columns must be provided as arguments'>;
+    $asTuple<K1 extends keyof O, K2 extends Exclude<keyof O, K1>, K3 extends Exclude<keyof O, K1 | K2>>(key1: K1, key2: K2, key3: K3): keyof O extends K1 | K2 | K3 ? ExpressionWrapper<DB, TB, [O[K1], O[K2], O[K3]]> : KyselyTypeError<'$asTuple() call failed: All selected columns must be provided as arguments'>;
+    $asTuple<K1 extends keyof O, K2 extends Exclude<keyof O, K1>, K3 extends Exclude<keyof O, K1 | K2>, K4 extends Exclude<keyof O, K1 | K2 | K3>>(key1: K1, key2: K2, key3: K3, key4: K4): keyof O extends K1 | K2 | K3 | K4 ? ExpressionWrapper<DB, TB, [O[K1], O[K2], O[K3], O[K4]]> : KyselyTypeError<'$asTuple() call failed: All selected columns must be provided as arguments'>;
+    $asTuple<K1 extends keyof O, K2 extends Exclude<keyof O, K1>, K3 extends Exclude<keyof O, K1 | K2>, K4 extends Exclude<keyof O, K1 | K2 | K3>, K5 extends Exclude<keyof O, K1 | K2 | K3 | K4>>(key1: K1, key2: K2, key3: K3, key4: K4, key5: K5): keyof O extends K1 | K2 | K3 | K4 | K5 ? ExpressionWrapper<DB, TB, [O[K1], O[K2], O[K3], O[K4], O[K5]]> : KyselyTypeError<'$asTuple() call failed: All selected columns must be provided as arguments'>;
     /**
      * Narrows (parts of) the output type of the query.
      *
@@ -1630,31 +1786,14 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      */
     explain<ER extends Record<string, any> = Record<string, any>>(format?: ExplainFormat, options?: Expression<any>): Promise<ER[]>;
 }
+export declare function createSelectQueryBuilder<DB, TB extends keyof DB, O>(props: SelectQueryBuilderProps): SelectQueryBuilder<DB, TB, O>;
 export interface SelectQueryBuilderProps {
     readonly queryId: QueryId;
     readonly queryNode: SelectQueryNode;
     readonly executor: QueryExecutor;
 }
-/**
- * {@link SelectQueryBuilder} with an alias. The result of calling {@link SelectQueryBuilder.as}.
- */
-export declare class AliasedSelectQueryBuilder<DB, TB extends keyof DB, O = undefined, A extends string = never> implements AliasedExpression<O, A> {
-    #private;
-    constructor(queryBuilder: SelectQueryBuilder<DB, TB, O>, alias: A);
-    /** @private */
-    /**
-     * Returns the aliased expression.
-     */
-    get expression(): Expression<O>;
-    /** @private */
-    /**
-     * Returns the alias.
-     */
-    get alias(): A;
-    /**
-     * Creates the OperationNode that describes how to compile this expression into SQL.
-     */
-    toOperationNode(): AliasNode;
+export interface AliasedSelectQueryBuilder<O = undefined, A extends string = never> extends AliasedExpression<O, A> {
+    get isAliasedSelectQueryBuilder(): true;
 }
 export type SelectQueryBuilderWithInnerJoin<DB, TB extends keyof DB, O, TE extends TableExpression<DB, TB>> = TE extends `${infer T} as ${infer A}` ? T extends keyof DB ? InnerJoinedBuilder<DB, TB, O, A, DB[T]> : never : TE extends keyof DB ? SelectQueryBuilder<DB, TB | TE, O> : TE extends AliasedExpression<infer QO, infer QA> ? InnerJoinedBuilder<DB, TB, O, QA, QO> : TE extends (qb: any) => AliasedExpression<infer QO, infer QA> ? InnerJoinedBuilder<DB, TB, O, QA, QO> : never;
 type InnerJoinedBuilder<DB, TB extends keyof DB, O, A extends string, R> = A extends keyof DB ? SelectQueryBuilder<InnerJoinedDB<DB, A, R>, TB | A, O> : SelectQueryBuilder<DB & ShallowRecord<A, R>, TB | A, O>;