kysely 0.23.4 → 0.24.0

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

@@ -2,7 +2,7 @@
 import { AliasNode } from '../operation-node/alias-node.js';
 import { SelectModifierNode } from '../operation-node/select-modifier-node.js';
 import { parseJoin, } from '../parser/join-parser.js';
-import { parseSelectExpressionOrList, parseSelectAll, } from '../parser/select-parser.js';
+import { parseSelectArg, parseSelectAll, } from '../parser/select-parser.js';
 import { parseReferenceExpressionOrList, } from '../parser/reference-parser.js';
 import { SelectQueryNode } from '../operation-node/select-query-node.js';
 import { QueryNode } from '../operation-node/query-node.js';
@@ -11,12 +11,11 @@ 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 { NoResultError } from './no-result-error.js';
+import { parseGroupBy } from '../parser/group-by-parser.js';
+import { isNoResultErrorConstructor, NoResultError, } from './no-result-error.js';
 import { IdentifierNode } from '../operation-node/identifier-node.js';
-import { ExplainNode } from '../operation-node/explain-node.js';
 import { parseSetOperation } from '../parser/set-operation-parser.js';
-import { parseHaving, parseReferentialFilter, parseWhere, } from '../parser/binary-operation-parser.js';
+import { parseHaving, parseReferentialComparison, parseWhere, } from '../parser/binary-operation-parser.js';
 import { parseExists, parseNotExists, } from '../parser/unary-operation-parser.js';
 export class SelectQueryBuilder {
     #props;
@@ -36,7 +35,7 @@ export class SelectQueryBuilder {
     whereRef(lhs, op, rhs) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseReferentialFilter(lhs, op, rhs)),
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseReferentialComparison(lhs, op, rhs)),
         });
     }
     orWhere(...args) {
@@ -48,7 +47,7 @@ export class SelectQueryBuilder {
     orWhereRef(lhs, op, rhs) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseReferentialFilter(lhs, op, rhs)),
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseReferentialComparison(lhs, op, rhs)),
         });
     }
     whereExists(arg) {
@@ -84,7 +83,7 @@ export class SelectQueryBuilder {
     havingRef(lhs, op, rhs) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseReferentialFilter(lhs, op, rhs)),
+            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseReferentialComparison(lhs, op, rhs)),
         });
     }
     orHaving(...args) {
@@ -96,7 +95,7 @@ export class SelectQueryBuilder {
     orHavingRef(lhs, op, rhs) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseReferentialFilter(lhs, op, rhs)),
+            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseReferentialComparison(lhs, op, rhs)),
         });
     }
     havingExists(arg) {
@@ -105,12 +104,21 @@ export class SelectQueryBuilder {
             queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseExists(arg)),
         });
     }
+    /**
+     * @deprecated Use {@link havingNotExists} instead.
+     */
     havingNotExist(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
             queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseNotExists(arg)),
         });
     }
+    havingNotExists(arg) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseNotExists(arg)),
+        });
+    }
     orHavingExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
@@ -123,10 +131,199 @@ export class SelectQueryBuilder {
             queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseNotExists(arg)),
         });
     }
+    /**
+     * Adds a select statement to the query.
+     *
+     * When a column (or any expression) is selected, Kysely adds its type to the return
+     * type of the query. Kysely is smart enough to parse the selection names and types
+     * from aliased columns, subqueries, raw expressions etc.
+     *
+     * Kysely only allows you to select columns and expressions that exist and would
+     * produce valid SQL. However, Kysely is not perfect and there may be cases where
+     * the type inference doesn't work and you need to override it. You can always
+     * use the {@link Kysely.dynamic | dynamic} module and the {@link sql} tag
+     * to override the types.
+     *
+     * Select calls are additive. Calling `select('id').select('first_name')` is the
+     * same as calling `select(['id', 'first_name'])`.
+     *
+     * To select all columns of the query or specific tables see the
+     * {@link selectAll} method.
+     *
+     * See the {@link $if} method if you are looking for a way to add selections
+     * based on a runtime condition.
+     *
+     * ### Examples
+     *
+     * Select a single column:
+     *
+     * ```ts
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .select('id')
+     *   .where('first_name', '=', 'Arnold')
+     *   .execute()
+     *
+     * persons[0].id
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "id" from "person" where "first_name" = $1
+     * ```
+     *
+     * Select a single column and specify a table:
+     *
+     * ```ts
+     * const persons = await db
+     *   .selectFrom(['person', 'pet'])
+     *   .select('person.id')
+     *   .execute()
+     *
+     * persons[0].id
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."id" from "person", "pet"
+     * ```
+     *
+     * Select multiple columns:
+     *
+     * ```ts
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .select(['person.id', 'first_name'])
+     *   .execute()
+     *
+     * persons[0].id
+     * persons[0].first_name
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."id", "first_name" from "person"
+     * ```
+     *
+     * Aliased selections:
+     *
+     * ```ts
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .select([
+     *     'person.first_name as fn',
+     *     'person.last_name as ln'
+     *   ])
+     *   .execute()
+     *
+     * persons[0].fn
+     * persons[0].ln
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select
+     *   "person"."first_name" as "fn",
+     *   "person"."last_name" as "ln"
+     * from "person"
+     * ```
+     *
+     * You can also select arbitrary expression including subqueries and raw sql snippets.
+     * When you do that, you need to give a name for the selections using the {@link as} method:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const persons = await db.selectFrom('person')
+     *   .select(({ selectFrom, or, cmpr }) => [
+     *     // Select a correlated subquery
+     *     selectFrom('pet')
+     *       .whereRef('person.id', '=', 'pet.owner_id')
+     *       .select('pet.name')
+     *       .orderBy('pet.name')
+     *       .limit(1)
+     *       .as('first_pet_name'),
+     *
+     *     // Build and select an expression using the expression builder
+     *     or([
+     *       cmpr('first_name', '=', 'Jennifer'),
+     *       cmpr('first_name', '=', 'Arnold')
+     *     ]).as('is_jennifer_or_arnold'),
+     *
+     *     // Select a raw sql expression
+     *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name')
+     *   ])
+     *   .execute()
+     *
+     * persons[0].first_pet_name
+     * persons[0].is_jennifer_or_arnold
+     * persons[0].full_name
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select
+     *   (
+     *     select "pet"."name"
+     *     from "pet"
+     *     where "person"."id" = "pet"."owner_id"
+     *     order by "pet"."name"
+     *     limit $1
+     *   ) as "pet_name",
+     *   ("first_name" = $2 or "first_name" = $3) as "jennifer_or_arnold",
+     *   concat(first_name, ' ', last_name) as "full_name"
+     * from "person"
+     * ```
+     *
+     * In case you use the {@link sql} tag you need to specify the type of the expression
+     * (in this example `string`).
+     *
+     * All the examples above assume you know the column names at compile time.
+     * While it's better to build your code like that (that way you also know
+     * the types) sometimes it's not possible or you just prefer to write more
+     * dynamic code.
+     * <br><br>
+     * In this example, we use the `dynamic` module's methods to add selections
+     * dynamically:
+     *
+     * ```ts
+     * const { ref } = db.dynamic
+     *
+     * // Some column name provided by the user. Value not known at compile time.
+     * const columnFromUserInput = req.query.select;
+     *
+     * // A type that lists all possible values `columnFromUserInput` can have.
+     * // You can use `keyof Person` if any column of an interface is allowed.
+     * type PossibleColumns = 'last_name' | 'first_name' | 'birth_date'
+     *
+     * const spersons = await db
+     *   .selectFrom('person')
+     *   .select([
+     *     ref<PossibleColumns>(columnFromUserInput)
+     *     'id'
+     *   ])
+     *   .execute()
+     *
+     * // The resulting type contains all `PossibleColumns` as optional fields
+     * // because we cannot know which field was actually selected before
+     * // running the code.
+     * const lastName: string | undefined = persons[0].last_name
+     * const firstName: string | undefined = persons[0].first_name
+     * const birthDate: string | undefined = persons[0].birth_date
+     *
+     * // The result type also contains the compile time selection `id`.
+     * persons[0].id
+     * ```
+     */
     select(selection) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithSelections(this.#props.queryNode, parseSelectExpressionOrList(selection)),
+            queryNode: SelectQueryNode.cloneWithSelections(this.#props.queryNode, parseSelectArg(selection)),
         });
     }
     distinctOn(selection) {
@@ -346,7 +543,7 @@ export class SelectQueryBuilder {
      * await db
      *   .selectFrom('person')
      *   .selectAll()
-     *   .orderBy((qb) => qb.selectFrom('pet')
+     *   .orderBy((eb) => eb.selectFrom('pet')
      *     .select('pet.name')
      *     .whereRef('pet.owner_id', '=', 'person.id')
      *     .limit(1)
@@ -402,6 +599,104 @@ export class SelectQueryBuilder {
             queryNode: SelectQueryNode.cloneWithOrderByItem(this.#props.queryNode, parseOrderBy(orderBy, direction)),
         });
     }
+    /**
+     * Adds a `group by` clause to the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * await db
+     *   .selectFrom('person')
+     *   .select([
+     *     'first_name',
+     *     sql`max(id)`.as('max_id')
+     *   ])
+     *   .groupBy('first_name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "first_name", max(id)
+     * from "person"
+     * group by "first_name"
+     * ```
+     *
+     * `groupBy` also accepts an array:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * await db
+     *   .selectFrom('person')
+     *   .select([
+     *     'first_name',
+     *     'last_name',
+     *     sql`max(id)`.as('max_id')
+     *   ])
+     *   .groupBy([
+     *     'first_name',
+     *     'last_name'
+     *   ])
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "first_name", "last_name", max(id)
+     * from "person"
+     * group by "first_name", "last_name"
+     * ```
+     *
+     * The group by expressions can also be subqueries or
+     * raw sql expressions:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * await db
+     *   .selectFrom('person')
+     *   .select([
+     *     'first_name',
+     *     'last_name',
+     *     sql`max(id)`.as('max_id')
+     *   ])
+     *   .groupBy([
+     *     sql`concat(first_name, last_name)`,
+     *     (qb) => qb.selectFrom('pet').select('id').limit(1)
+     *   ])
+     *   .execute()
+     * ```
+     *
+     * `dynamic.ref` can be used to refer to columns not known at
+     * compile time:
+     *
+     * ```ts
+     * async function someQuery(groupBy: string) {
+     *   const { ref } = db.dynamic
+     *
+     *   return await db
+     *     .selectFrom('person')
+     *     .select('first_name')
+     *     .groupBy(ref(groupBy))
+     *     .execute()
+     * }
+     *
+     * someQuery('first_name')
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "first_name"
+     * from "person"
+     * group by "first_name"
+     * ```
+     */
     groupBy(groupBy) {
         return new SelectQueryBuilder({
             ...this.#props,
@@ -610,7 +905,7 @@ export class SelectQueryBuilder {
      * db.selectFrom('person')
      *   .select(['id', 'first_name'])
      *   .clearSelect()
-     *   .select(['id','gender'])
+     *   .select(['id', 'gender'])
      * ```
      *
      * The generated SQL(PostgreSQL):
@@ -705,7 +1000,8 @@ export class SelectQueryBuilder {
         });
     }
     /**
-     * Simply calls the given function passing `this` as the only argument.
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
      *
      * If you want to conditionally call a method on `this`, see
      * the {@link $if} method.
@@ -738,12 +1034,29 @@ export class SelectQueryBuilder {
     /**
      * Call `func(this)` if `condition` is true.
      *
-     * This method is especially handy with optional selects. Any `select` or `selectAll`
-     * method calls add columns as optional fields to the output type when called inside
-     * the `func` callback. This is because we can't know if those selections were actually
-     * made before running the code.
+     * NOTE: This method has an impact on typescript performance and it should only be used
+     * when necessary. Remember that you can call most methods like `where` conditionally
+     * like this:
+     *
+     * ```ts
+     * let query = db.selectFrom('person').selectAll()
+     *
+     * if (firstName) {
+     *   query = query.where('first_name', '=', firstName)
+     * }
+     *
+     * if (lastName) {
+     *   query = query.where('last_name', '=', lastName)
+     * }
+     *
+     * const result = await query.execute()
+     * ```
+     *
+     * This method is mainly useful with optional selects. Any `select` or `selectAll`
+     * method called inside the callback add optional fields to the result type. This is
+     * because we can't know if those selections were actually made before running the code.
      *
-     * Also see [this recipe](https://github.com/koskimas/kysely/tree/master/recipes/conditional-selects.md)
+     * Also see [this recipe](https://github.com/koskimas/kysely/tree/master/site/docs/recipes/conditional-selects.md)
      *
      * ### Examples
      *
@@ -900,42 +1213,19 @@ export class SelectQueryBuilder {
      * 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
+     * provide a custom error class, or callback to throw a different
      * error.
      */
     async executeTakeFirstOrThrow(errorConstructor = NoResultError) {
         const result = await this.executeTakeFirst();
         if (result === undefined) {
-            throw new errorConstructor(this.toOperationNode());
+            const error = isNoResultErrorConstructor(errorConstructor)
+                ? new errorConstructor(this.toOperationNode())
+                : errorConstructor(this.toOperationNode());
+            throw error;
         }
         return result;
     }
-    /**
-     * Executes the query and streams the rows.
-     *
-     * The optional argument `chunkSize` defines how many rows to fetch from the database
-     * at a time. It only affects some dialects like PostgreSQL that support it.
-     *
-     * ### Examples
-     *
-     * ```ts
-     * const stream = db.
-     *   .selectFrom('person')
-     *   .select(['first_name', 'last_name'])
-     *   .where('gender', '=', 'other')
-     *   .stream()
-     *
-     * for await (const person of stream) {
-     *   console.log(person.first_name)
-     *
-     *   if (person.last_name === 'Something') {
-     *     // Breaking or returning before the stream has ended will release
-     *     // the database connection and invalidate the stream.
-     *     break
-     *   }
-     * }
-     * ```
-     */
     async *stream(chunkSize = 100) {
         const compiledQuery = this.compile();
         const stream = this.#props.executor.stream(compiledQuery, chunkSize, this.#props.queryId);
@@ -943,45 +1233,10 @@ export class SelectQueryBuilder {
             yield* item.rows;
         }
     }
-    /**
-     * Executes query with `explain` statement before `select` keyword.
-     *
-     * ```ts
-     * const explained = await db
-     *  .selectFrom('person')
-     *  .where('gender', '=', 'female')
-     *  .selectAll()
-     *  .explain('json')
-     * ```
-     *
-     * The generated SQL (MySQL):
-     *
-     * ```sql
-     * explain format=json select * from `person` where `gender` = ?
-     * ```
-     *
-     * You can also execute `explain analyze` statements.
-     *
-     * ```ts
-     * import { sql } from 'kysely'
-     *
-     * const explained = await db
-     *  .selectFrom('person')
-     *  .where('gender', '=', 'female')
-     *  .selectAll()
-     *  .explain('json', sql`analyze`)
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * explain (analyze, format json) select * from "person" where "gender" = $1
-     * ```
-     */
     async explain(format, options) {
         const builder = new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithExplain(this.#props.queryNode, ExplainNode.create(format, options?.toOperationNode())),
+            queryNode: QueryNode.cloneWithExplain(this.#props.queryNode, format, options),
         });
         return await builder.execute();
     }