kysely 0.24.2 → 0.26.0

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

@@ -18,7 +18,6 @@ const no_result_error_js_1 = require("./no-result-error.js");
 const identifier_node_js_1 = require("../operation-node/identifier-node.js");
 const set_operation_parser_js_1 = require("../parser/set-operation-parser.js");
 const binary_operation_parser_js_1 = require("../parser/binary-operation-parser.js");
-const unary_operation_parser_js_1 = require("../parser/unary-operation-parser.js");
 class SelectQueryBuilder {
     #props;
     constructor(props) {
@@ -31,7 +30,7 @@ class SelectQueryBuilder {
     where(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, binary_operation_parser_js_1.parseWhere)(args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, binary_operation_parser_js_1.parseFilter)(args)),
         });
     }
     whereRef(lhs, op, rhs) {
@@ -40,46 +39,10 @@ class SelectQueryBuilder {
             queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, binary_operation_parser_js_1.parseReferentialComparison)(lhs, op, rhs)),
         });
     }
-    orWhere(...args) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, binary_operation_parser_js_1.parseWhere)(args)),
-        });
-    }
-    orWhereRef(lhs, op, rhs) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, binary_operation_parser_js_1.parseReferentialComparison)(lhs, op, rhs)),
-        });
-    }
-    whereExists(arg) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, unary_operation_parser_js_1.parseExists)(arg)),
-        });
-    }
-    whereNotExists(arg) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, unary_operation_parser_js_1.parseNotExists)(arg)),
-        });
-    }
-    orWhereExists(arg) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, unary_operation_parser_js_1.parseExists)(arg)),
-        });
-    }
-    orWhereNotExists(arg) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, unary_operation_parser_js_1.parseNotExists)(arg)),
-        });
-    }
     having(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, binary_operation_parser_js_1.parseHaving)(args)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, binary_operation_parser_js_1.parseFilter)(args)),
         });
     }
     havingRef(lhs, op, rhs) {
@@ -88,51 +51,6 @@ class SelectQueryBuilder {
             queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, binary_operation_parser_js_1.parseReferentialComparison)(lhs, op, rhs)),
         });
     }
-    orHaving(...args) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, binary_operation_parser_js_1.parseHaving)(args)),
-        });
-    }
-    orHavingRef(lhs, op, rhs) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, binary_operation_parser_js_1.parseReferentialComparison)(lhs, op, rhs)),
-        });
-    }
-    havingExists(arg) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, unary_operation_parser_js_1.parseExists)(arg)),
-        });
-    }
-    /**
-     * @deprecated Use {@link havingNotExists} instead.
-     */
-    havingNotExist(arg) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, unary_operation_parser_js_1.parseNotExists)(arg)),
-        });
-    }
-    havingNotExists(arg) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, unary_operation_parser_js_1.parseNotExists)(arg)),
-        });
-    }
-    orHavingExists(arg) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, unary_operation_parser_js_1.parseExists)(arg)),
-        });
-    }
-    orHavingNotExists(arg) {
-        return new SelectQueryBuilder({
-            ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, unary_operation_parser_js_1.parseNotExists)(arg)),
-        });
-    }
     /**
      * Adds a select statement to the query.
      *
@@ -157,6 +75,8 @@ class SelectQueryBuilder {
      *
      * ### Examples
      *
+     * <!-- siteExample("select", "A single column", 10) -->
+     *
      * Select a single column:
      *
      * ```ts
@@ -165,8 +85,6 @@ class SelectQueryBuilder {
      *   .select('id')
      *   .where('first_name', '=', 'Arnold')
      *   .execute()
-     *
-     * persons[0].id
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -175,6 +93,8 @@ 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
@@ -182,8 +102,6 @@ class SelectQueryBuilder {
      *   .selectFrom(['person', 'pet'])
      *   .select('person.id')
      *   .execute()
-     *
-     * persons[0].id
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -192,6 +110,8 @@ class SelectQueryBuilder {
      * select "person"."id" from "person", "pet"
      * ```
      *
+     * <!-- siteExample("select", "Multiple columns", 30) -->
+     *
      * Select multiple columns:
      *
      * ```ts
@@ -199,9 +119,6 @@ class SelectQueryBuilder {
      *   .selectFrom('person')
      *   .select(['person.id', 'first_name'])
      *   .execute()
-     *
-     * persons[0].id
-     * persons[0].first_name
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -210,35 +127,36 @@ 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 }) => [
@@ -250,7 +168,8 @@ 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')
@@ -260,10 +179,6 @@ 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):
@@ -391,10 +306,12 @@ 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()
@@ -1027,12 +944,6 @@ class SelectQueryBuilder {
     $call(func) {
         return func(this);
     }
-    /**
-     * @deprecated Use `$call` instead
-     */
-    call(func) {
-        return this.$call(func);
-    }
     /**
      * Call `func(this)` if `condition` is true.
      *
@@ -1088,14 +999,12 @@ 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')
      *   )
      * ```
@@ -1108,12 +1017,6 @@ class SelectQueryBuilder {
             ...this.#props,
         });
     }
-    /**
-     * @deprecated Use `$if` instead
-     */
-    if(condition, func) {
-        return this.$if(condition, func);
-    }
     /**
      * Change the output type of the query.
      *
@@ -1124,10 +1027,47 @@ 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`.
@@ -1171,12 +1111,6 @@ 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.
      */