kysely 0.16.11 → 0.17.2

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

@@ -12,7 +12,6 @@ import { OrderByDirectionExpression, OrderByExpression } from '../parser/order-b
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
-import { ParseContext } from '../parser/parse-context.js';
 import { UnionExpression } from '../parser/union-parser.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
 import { WhereInterface } from './where-interface.js';
@@ -46,7 +45,13 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```
      *
      * Operator can be any supported operator or if the typings don't support it
-     * you can always use `db.raw('your operator')`.
+     * you can always use
+     *
+     * ```ts
+     * sql`your operator`
+     * ```
+     *
+     * The next example uses the `>` operator:
      *
      * ```ts
      * const persons = await db
@@ -62,8 +67,8 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * select * from "person" where "id" > $1
      * ```
      *
-     * The `where` methods don't change the type of the query. You can add
-     * conditional `where`s easily by doing something like this:
+     * `where` methods don't change the type of the query. You can add
+     * conditional statements easily by doing something like this:
      *
      * ```ts
      * let query = db
@@ -71,6 +76,8 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   .selectAll()
      *
      * if (firstName) {
+     *   // The query builder is immutable. Remember to reassign
+     *   // the result back to the query variable.
      *   query = query.where('first_name', '=', firstName)
      * }
      *
@@ -78,8 +85,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```
      *
      * This is true for basically all methods execpt the `select` and
-     * `returning` methods, which DO change the return type of the
-     * query.
+     * `returning`, that __do__ change the return type of the query.
      *
      * Both the first and third argument can also be subqueries.
      * A subquery is defined by passing a function and calling
@@ -116,7 +122,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *
      * A `where in` query can be built by using the `in` operator and an array
      * of values. The values in the array can also be subqueries or raw
-     * instances.
+     * {@link sql} expressions.
      *
      * ```ts
      * const persons = await db
@@ -132,15 +138,17 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
-     * If everything else fails, you can always pass {@link Kysely.raw | raw}
+     * If everything else fails, you can always use the {@link sql} tag
      * as any of the arguments, including the operator:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(
-     *     db.raw('coalesce(first_name, last_name)'),
+     *     sql`coalesce(first_name, last_name)`,
      *     'like',
      *     '%' + name + '%',
      *   )
@@ -175,24 +183,25 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```
      *
      * In all examples above the columns were known at compile time
-     * (except for the `raw` expressions). By default kysely only allows
-     * you to refer to columns that exist in the database **and** can be
-     * referred to in the current query and context.
+     * (except for the raw {@link sql} expressions). By default kysely only
+     * allows you to refer to columns that exist in the database **and**
+     * can be referred to in the current query and context.
      *
      * Sometimes you may want to refer to columns that come from the user
      * input and thus are not available at compile time.
      *
-     * You have two options, `db.raw` or `db.dynamic`. The example below
+     * You have two options, the {@link sql} tag or `db.dynamic`. The example below
      * uses both:
      *
      * ```ts
+     * import { sql } from 'kysely'
      * const { ref } = db.dynamic
      *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(ref(columnFromUserInput), '=', 1)
-     *   .orWhere(db.raw('??', [columnFromUserInput]), '=', 2)
+     *   .orWhere(sql.id(columnFromUserInput), '=', 2)
      *   .execute()
      * ```
      */
@@ -326,13 +335,14 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
     /**
      * Adds a `where exists` clause to the query.
      *
-     * You can either use a subquery or a raw instance.
+     * You can either use a subquery or a raw {@link sql} snippet.
      *
      * ### Examples
      *
      * The query below selets all persons that own a pet named Catto:
      *
      * ```ts
+     * const petName = 'Catto'
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
@@ -340,7 +350,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *     .selectFrom('pet')
      *     .select('pet.id')
      *     .whereRef('person.id', '=', 'pet.owner_id')
-     *     .where('pet.name', '=', 'Catto')
+     *     .where('pet.name', '=', petName)
      *   )
      *   .execute()
      * ```
@@ -357,16 +367,16 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * )
      * ```
      *
-     * The same query as in the previous example but with using raw:
+     * The same query as in the previous example but with using raw {@link sql}:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const petName = 'Catto'
      * db.selectFrom('person')
      *   .selectAll()
      *   .whereExists(
-     *     db.raw(
-     *       '(select pet.id from pet where person.id = pet.owner_id and pet.name = ?)',
-     *       ['Catto']
-     *     )
+     *     sql`(select pet.id from pet where person.id = pet.owner_id and pet.name = ${petName})`
      *   )
      * ```
      *
@@ -449,7 +459,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * 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 {@link Kysely.raw | raw}
+     * 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
@@ -536,11 +546,13 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * from "person"
      * ```
      *
-     * You can also select subqueries and raw expressions. Note that you
+     * You can also select subqueries and raw sql expressions. Note that you
      * always need to give a name for the selections using the `as`
      * method:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const persons = await db.selectFrom('person')
      *   .select([
      *     (qb) => qb
@@ -549,7 +561,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *       .select('pet.name')
      *       .limit(1)
      *       .as('pet_name')
-     *     db.raw<string>("concat(first_name, ' ', last_name)").as('full_name')
+     *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name')
      *   ])
      *   .execute()
      *
@@ -571,7 +583,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * from "person"
      * ```
      *
-     * In case you use `raw` you need to specify the type of the expression
+     * 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.
@@ -889,10 +901,12 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * order by "id" asc, "fn" desc
      * ```
      *
-     * The order by expression can also be a `raw` expression or a subquery
+     * The order by expression can also be a raw sql expression or a subquery
      * in addition to column references:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * await db
      *   .selectFrom('person')
      *   .selectAll()
@@ -902,7 +916,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *     .limit(1)
      *   )
      *   .orderBy(
-     *     db.raw('concat(first_name, last_name)')
+     *     sql`concat(first_name, last_name)`
      *   )
      *   .execute()
      * ```
@@ -953,11 +967,13 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ### Examples
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * await db
      *   .selectFrom('person')
      *   .select([
      *     'first_name',
-     *     db.raw('max(id)').as('max_id')
+     *     sql`max(id)`.as('max_id')
      *   ])
      *   .groupBy('first_name')
      *   .execute()
@@ -974,12 +990,14 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * `groupBy` also accepts an array:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * await db
      *   .selectFrom('person')
      *   .select([
      *     'first_name',
      *     'last_name',
-     *     db.raw('max(id)').as('max_id')
+     *     sql`max(id)`.as('max_id')
      *   ])
      *   .groupBy([
      *     'first_name',
@@ -997,18 +1015,20 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```
      *
      * The group by expressions can also be subqueries or
-     * raw expressions:
+     * raw sql expressions:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * await db
      *   .selectFrom('person')
      *   .select([
      *     'first_name',
      *     'last_name',
-     *     db.raw('max(id)').as('max_id')
+     *     sql`max(id)`.as('max_id')
      *   ])
      *   .groupBy([
-     *     db.raw('concat(first_name, last_name)'),
+     *     sql`concat(first_name, last_name)`,
      *     (qb) => qb.selectFrom('pet').select('id').limit(1)
      *   ])
      *   .execute()
@@ -1242,7 +1262,6 @@ export interface SelectQueryBuilderProps {
     readonly queryId: QueryId;
     readonly queryNode: SelectQueryNode;
     readonly executor: QueryExecutor;
-    readonly parseContext: ParseContext;
 }
 /**
  * {@link SelectQueryBuilder} with an alias. The result of calling {@link SelectQueryBuilder.as}.

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

@@ -23,109 +23,109 @@ class SelectQueryBuilder {
     where(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseWhereFilter)(this.#props.parseContext, args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseWhereFilter)(args)),
         });
     }
     whereRef(lhs, op, rhs) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(this.#props.parseContext, lhs, op, rhs)),
+            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(lhs, op, rhs)),
         });
     }
     orWhere(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseWhereFilter)(this.#props.parseContext, args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseWhereFilter)(args)),
         });
     }
     orWhereRef(lhs, op, rhs) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(this.#props.parseContext, lhs, op, rhs)),
+            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(lhs, op, rhs)),
         });
     }
     whereExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(this.#props.parseContext, arg)),
+            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(arg)),
         });
     }
     whereNotExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(this.#props.parseContext, arg)),
+            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(arg)),
         });
     }
     orWhereExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(this.#props.parseContext, arg)),
+            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(arg)),
         });
     }
     orWhereNotExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(this.#props.parseContext, arg)),
+            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(arg)),
         });
     }
     having(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, filter_parser_js_1.parseHavingFilter)(this.#props.parseContext, args)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, filter_parser_js_1.parseHavingFilter)(args)),
         });
     }
     havingRef(lhs, op, rhs) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(this.#props.parseContext, lhs, op, rhs)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(lhs, op, rhs)),
         });
     }
     orHaving(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, filter_parser_js_1.parseHavingFilter)(this.#props.parseContext, args)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, filter_parser_js_1.parseHavingFilter)(args)),
         });
     }
     orHavingRef(lhs, op, rhs) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(this.#props.parseContext, lhs, op, rhs)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(lhs, op, rhs)),
         });
     }
     havingExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(this.#props.parseContext, arg)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(arg)),
         });
     }
     havingNotExist(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(this.#props.parseContext, arg)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithHaving(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(arg)),
         });
     }
     orHavingExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(this.#props.parseContext, arg)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(arg)),
         });
     }
     orHavingNotExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(this.#props.parseContext, arg)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(arg)),
         });
     }
     select(selection) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithSelections(this.#props.queryNode, (0, select_parser_js_1.parseSelectExpressionOrList)(this.#props.parseContext, selection)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithSelections(this.#props.queryNode, (0, select_parser_js_1.parseSelectExpressionOrList)(selection)),
         });
     }
     distinctOn(selection) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithDistinctOnSelections(this.#props.queryNode, (0, select_parser_js_1.parseSelectExpressionOrList)(this.#props.parseContext, selection)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithDistinctOnSelections(this.#props.queryNode, (0, select_parser_js_1.parseSelectExpressionOrList)(selection)),
         });
     }
     /**
@@ -215,25 +215,25 @@ class SelectQueryBuilder {
     innerJoin(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)(this.#props.parseContext, 'InnerJoin', args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('InnerJoin', args)),
         });
     }
     leftJoin(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)(this.#props.parseContext, 'LeftJoin', args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('LeftJoin', args)),
         });
     }
     rightJoin(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)(this.#props.parseContext, 'RightJoin', args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('RightJoin', args)),
         });
     }
     fullJoin(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)(this.#props.parseContext, 'FullJoin', args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('FullJoin', args)),
         });
     }
     /**
@@ -264,10 +264,12 @@ class SelectQueryBuilder {
      * order by "id" asc, "fn" desc
      * ```
      *
-     * The order by expression can also be a `raw` expression or a subquery
+     * The order by expression can also be a raw sql expression or a subquery
      * in addition to column references:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * await db
      *   .selectFrom('person')
      *   .selectAll()
@@ -277,7 +279,7 @@ class SelectQueryBuilder {
      *     .limit(1)
      *   )
      *   .orderBy(
-     *     db.raw('concat(first_name, last_name)')
+     *     sql`concat(first_name, last_name)`
      *   )
      *   .execute()
      * ```
@@ -324,13 +326,13 @@ class SelectQueryBuilder {
     orderBy(orderBy, direction) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrderByItem(this.#props.queryNode, (0, order_by_parser_js_1.parseOrderBy)(this.#props.parseContext, orderBy, direction)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithOrderByItem(this.#props.queryNode, (0, order_by_parser_js_1.parseOrderBy)(orderBy, direction)),
         });
     }
     groupBy(groupBy) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithGroupByItems(this.#props.queryNode, (0, group_by_parser_js_1.parseGroupBy)(this.#props.parseContext, groupBy)),
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithGroupByItems(this.#props.queryNode, (0, group_by_parser_js_1.parseGroupBy)(groupBy)),
         });
     }
     /**