kysely 0.24.2 → 0.26.0

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

@@ -15,8 +15,7 @@ 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 { parseSetOperation } from '../parser/set-operation-parser.js';
-import { parseHaving, parseReferentialComparison, parseWhere, } from '../parser/binary-operation-parser.js';
-import { parseExists, parseNotExists, } from '../parser/unary-operation-parser.js';
+import { parseFilter, parseReferentialComparison, } from '../parser/binary-operation-parser.js';
 export class SelectQueryBuilder {
     #props;
     constructor(props) {
@@ -29,7 +28,7 @@ export class SelectQueryBuilder {
     where(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseWhere(args)),
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseFilter(args)),
         });
     }
     whereRef(lhs, op, rhs) {
@@ -38,46 +37,10 @@ export class SelectQueryBuilder {
             queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseReferentialComparison(lhs, op, rhs)),
         });
     }
-    orWhere(...args) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseWhere(args)),
-        });
-    }
-    orWhereRef(lhs, op, rhs) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseReferentialComparison(lhs, op, rhs)),
-        });
-    }
-    whereExists(arg) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseExists(arg)),
-        });
-    }
-    whereNotExists(arg) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseNotExists(arg)),
-        });
-    }
-    orWhereExists(arg) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseExists(arg)),
-        });
-    }
-    orWhereNotExists(arg) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseNotExists(arg)),
-        });
-    }
     having(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseHaving(args)),
+            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseFilter(args)),
         });
     }
     havingRef(lhs, op, rhs) {
@@ -86,51 +49,6 @@ export class SelectQueryBuilder {
             queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseReferentialComparison(lhs, op, rhs)),
         });
     }
-    orHaving(...args) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseHaving(args)),
-        });
-    }
-    orHavingRef(lhs, op, rhs) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseReferentialComparison(lhs, op, rhs)),
-        });
-    }
-    havingExists(arg) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            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,
-            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseExists(arg)),
-        });
-    }
-    orHavingNotExists(arg) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseNotExists(arg)),
-        });
-    }
     /**
      * Adds a select statement to the query.
      *
@@ -155,6 +73,8 @@ export class SelectQueryBuilder {
      *
      * ### Examples
      *
+     * <!-- siteExample("select", "A single column", 10) -->
+     *
      * Select a single column:
      *
      * ```ts
@@ -163,8 +83,6 @@ export class SelectQueryBuilder {
      *   .select('id')
      *   .where('first_name', '=', 'Arnold')
      *   .execute()
-     *
-     * persons[0].id
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -173,6 +91,8 @@ export class SelectQueryBuilder {
      * select "id" from "person" where "first_name" = $1
      * ```
      *
+     * <!-- siteExample("select", "Column with a table", 20) -->
+     *
      * Select a single column and specify a table:
      *
      * ```ts
@@ -180,8 +100,6 @@ export class SelectQueryBuilder {
      *   .selectFrom(['person', 'pet'])
      *   .select('person.id')
      *   .execute()
-     *
-     * persons[0].id
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -190,6 +108,8 @@ export class SelectQueryBuilder {
      * select "person"."id" from "person", "pet"
      * ```
      *
+     * <!-- siteExample("select", "Multiple columns", 30) -->
+     *
      * Select multiple columns:
      *
      * ```ts
@@ -197,9 +117,6 @@ export class SelectQueryBuilder {
      *   .selectFrom('person')
      *   .select(['person.id', 'first_name'])
      *   .execute()
-     *
-     * persons[0].id
-     * persons[0].first_name
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -208,35 +125,36 @@ export class SelectQueryBuilder {
      * select "person"."id", "first_name" from "person"
      * ```
      *
-     * Aliased selections:
+     * <!-- siteExample("select", "Aliases", 40) -->
+     *
+     * You can provide an alias for the selections by appending `as the_alias` to the selection.
      *
      * ```ts
      * const persons = await db
      *   .selectFrom('person')
      *   .select([
-     *     'person.first_name as fn',
+     *     '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",
+     *   "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:
+     * <!-- siteExample("select", "Complex selections", 50) -->
+     *
+     * You can select arbitrary expression including subqueries and raw sql snippets.
+     * When you do that, you need to give a name for the selections using the `as` method:
      *
      * ```ts
-     * import { sql } from 'kysely'
+     * import { sql } from 'kysely'
      *
      * const persons = await db.selectFrom('person')
      *   .select(({ selectFrom, or, cmpr }) => [
@@ -248,7 +166,8 @@ export class SelectQueryBuilder {
      *       .limit(1)
      *       .as('first_pet_name'),
      *
-     *     // Build and select an expression using the expression builder
+     *     // Build and select an expression using
+     *     // the expression builder
      *     or([
      *       cmpr('first_name', '=', 'Jennifer'),
      *       cmpr('first_name', '=', 'Arnold')
@@ -258,10 +177,6 @@ export class SelectQueryBuilder {
      *     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):
@@ -389,10 +304,12 @@ export class SelectQueryBuilder {
     /**
      * Makes the selection distinct.
      *
+     * <!-- siteExample("select", "Distinct", 70) -->
+     *
      * ### Examples
      *
      * ```ts
-     * await db.selectFrom('person')
+     * const persons = await db.selectFrom('person')
      *   .select('first_name')
      *   .distinct()
      *   .execute()
@@ -1025,12 +942,6 @@ export class SelectQueryBuilder {
     $call(func) {
         return func(this);
     }
-    /**
-     * @deprecated Use `$call` instead
-     */
-    call(func) {
-        return this.$call(func);
-    }
     /**
      * Call `func(this)` if `condition` is true.
      *
@@ -1086,14 +997,12 @@ export class SelectQueryBuilder {
      * You can also call any other methods inside the callback:
      *
      * ```ts
-     * const { count } = db.fn
-     *
      * db.selectFrom('person')
      *   .select('person.id')
      *   .$if(filterByFirstName, (qb) => qb.where('first_name', '=', firstName))
      *   .$if(filterByPetCount, (qb) => qb
      *     .innerJoin('pet', 'pet.owner_id', 'person.id')
-     *     .having(count('pet.id'), '>', petCountLimit)
+     *     .having((eb) => eb.fn.count('pet.id'), '>', petCountLimit)
      *     .groupBy('person.id')
      *   )
      * ```
@@ -1106,12 +1015,6 @@ export class SelectQueryBuilder {
             ...this.#props,
         });
     }
-    /**
-     * @deprecated Use `$if` instead
-     */
-    if(condition, func) {
-        return this.$if(condition, func);
-    }
     /**
      * Change the output type of the query.
      *
@@ -1122,10 +1025,47 @@ export class SelectQueryBuilder {
         return new SelectQueryBuilder(this.#props);
     }
     /**
-     * @deprecated Use `$castTo` instead.
+     * Narrows (parts of) the output type of the query.
+     *
+     * Kysely tries to be as type-safe as possible, but in some cases we have to make
+     * compromises for better maintainability and compilation performance. At present,
+     * Kysely doesn't narrow the output type of the query when using {@link where}, {@link having}
+     * or {@link JoinQueryBuilder.on}.
+     *
+     * This utility method is very useful for these situations, as it removes unncessary
+     * runtime assertion/guard code. Its input type is limited to the output type
+     * of the query, so you can't add a column that doesn't exist, or change a column's
+     * type to something that doesn't exist in its union type.
+     *
+     * ### Examples
+     *
+     * Turn this code:
+     *
+     * ```ts
+     * const person = await db.selectFrom('person')
+     *   .where('nullable_column', 'is not', null)
+     *   .selectAll()
+     *   .executeTakeFirstOrThrow()
+     *
+     * if (person.nullable_column) {
+     *   functionThatExpectsPersonWithNonNullValue(person)
+     * }
+     * ```
+     *
+     * Into this:
+     *
+     * ```ts
+     * const person = await db.selectFrom('person')
+     *   .where('nullable_column', 'is not', null)
+     *   .selectAll()
+     *   .$narrowType<{ nullable_column: string }>()
+     *   .executeTakeFirstOrThrow()
+     *
+     * functionThatExpectsPersonWithNonNullValue(person)
+     * ```
      */
-    castTo() {
-        return this.$castTo();
+    $narrowType() {
+        return new SelectQueryBuilder(this.#props);
     }
     /**
      * Asserts that query's output row type equals the given type `T`.
@@ -1169,12 +1109,6 @@ export class SelectQueryBuilder {
     $assertType() {
         return new SelectQueryBuilder(this.#props);
     }
-    /**
-     * @deprecated Use `$assertType` instead.
-     */
-    assertType() {
-        return new SelectQueryBuilder(this.#props);
-    }
     /**
      * Returns a copy of this SelectQueryBuilder instance with the given plugin installed.
      */