kysely 0.26.3 → 0.27.1

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

@@ -5,7 +5,7 @@ import { InsertObjectOrList, InsertObjectOrListFactory } from '../parser/insert-
 import { InsertQueryNode } from '../operation-node/insert-query-node.js';
 import { QueryNode } from '../operation-node/query-node.js';
 import { NarrowPartial, SimplifyResult, SimplifySingleResult } from '../util/type-utils.js';
-import { UpdateExpression } from '../parser/update-set-parser.js';
+import { UpdateObjectExpression } from '../parser/update-set-parser.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
@@ -60,13 +60,18 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   })
      *   .executeTakeFirst()
      *
+     * // `insertId` is only available on dialects that
+     * // automatically return the id of the inserted row
+     * // such as MySQL and SQLite. On PostgreSQL, for example,
+     * // you need to add a `returning` clause to the query to
+     * // get anything out. See the "returning data" example.
      * console.log(result.insertId)
      * ```
      *
-     * The generated SQL (PostgreSQL):
+     * The generated SQL (MySQL):
      *
      * ```sql
-     * insert into "person" ("first_name", "last_name", "age") values ($1, $2, $3)
+     * insert into `person` (`first_name`, `last_name`, `age`) values (?, ?, ?)
      * ```
      *
      * <!-- siteExample("insert", "Multiple rows", 20) -->
@@ -131,11 +136,14 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * ```ts
      * import { sql } from 'kysely'
      *
+     * const ani = "Ani"
+     * const ston = "ston"
+     *
      * const result = await db
      *   .insertInto('person')
      *   .values(({ ref, selectFrom, fn }) => ({
      *     first_name: 'Jennifer',
-     *     last_name: sql`${'Ani'} || ${'ston'}`,
+     *     last_name: sql`concat(${ani}, ${ston})`,
      *     middle_name: ref('first_name'),
      *     age: selectFrom('person')
      *       .select(fn.avg<number>('age')
@@ -147,8 +155,18 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * insert into "person" ("first_name", "last_name", "age")
-     * values ($1, $2 || $3, (select avg("age") as "avg_age" from "person"))
+     * insert into "person" (
+     *   "first_name",
+     *   "last_name",
+     *   "middle_name",
+     *   "age"
+     * )
+     * values (
+     *   $1,
+     *   concat($2, $3),
+     *   "first_name",
+     *   (select avg("age") as "avg_age" from "person")
+     * )
      * ```
      *
      * You can also use the callback version of subqueries or raw expressions:
@@ -208,7 +226,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *     .select((eb) => [
      *       'pet.name',
      *       eb.val('Petson').as('last_name'),
-     *       eb.val(7).as('age'),
+     *       eb.lit(7).as('age'),
      *     ])
      *   )
      *   .execute()
@@ -218,10 +236,14 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *
      * ```sql
      * insert into "person" ("first_name", "last_name", "age")
-     * select "pet"."name", $1 as "first_name", $2 as "last_name" from "pet"
+     * select "pet"."name", $1 as "last_name", 7 as "age from "pet"
      * ```
      */
     expression(expression: ExpressionOrFactory<DB, TB, any>): InsertQueryBuilder<DB, TB, O>;
+    /**
+     * Creates an `insert into "person" default values` query.
+     */
+    defaultValues(): InsertQueryBuilder<DB, TB, O>;
     /**
      * Changes an `insert into` query to an `insert ignore into` query.
      *
@@ -414,7 +436,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   .onDuplicateKeyUpdate({ species: 'hamster' })
      * ```
      */
-    onDuplicateKeyUpdate(update: UpdateExpression<DB, TB, TB>): InsertQueryBuilder<DB, TB, O>;
+    onDuplicateKeyUpdate(update: UpdateObjectExpression<DB, TB, TB>): InsertQueryBuilder<DB, TB, O>;
     /**
      * Allows you to return data from modified rows.
      *
@@ -545,10 +567,10 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
     /**
      * Change the output type of the query.
      *
-     * You should only use this method as the last resort if the types
-     * don't support your use case.
+     * This method call doesn't change the SQL in any way. This methods simply
+     * returns a copy of this `InsertQueryBuilder` with a new output type.
      */
-    $castTo<T>(): InsertQueryBuilder<DB, TB, T>;
+    $castTo<C>(): InsertQueryBuilder<DB, TB, C>;
     /**
      * Narrows (parts of) the output type of the query.
      *

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

@@ -3,7 +3,7 @@ import { parseSelectArg, parseSelectAll, } from '../parser/select-parser.js';
 import { parseInsertExpression, } from '../parser/insert-values-parser.js';
 import { InsertQueryNode } from '../operation-node/insert-query-node.js';
 import { QueryNode } from '../operation-node/query-node.js';
-import { parseUpdateExpression, } from '../parser/update-set-parser.js';
+import { parseUpdateObjectExpression, } from '../parser/update-set-parser.js';
 import { preventAwait } from '../util/prevent-await.js';
 import { freeze } from '../util/object-utils.js';
 import { OnDuplicateKeyNode } from '../operation-node/on-duplicate-key-node.js';
@@ -75,7 +75,7 @@ export class InsertQueryBuilder {
      *     .select((eb) => [
      *       'pet.name',
      *       eb.val('Petson').as('last_name'),
-     *       eb.val(7).as('age'),
+     *       eb.lit(7).as('age'),
      *     ])
      *   )
      *   .execute()
@@ -85,7 +85,7 @@ export class InsertQueryBuilder {
      *
      * ```sql
      * insert into "person" ("first_name", "last_name", "age")
-     * select "pet"."name", $1 as "first_name", $2 as "last_name" from "pet"
+     * select "pet"."name", $1 as "last_name", 7 as "age from "pet"
      * ```
      */
     expression(expression) {
@@ -96,6 +96,17 @@ export class InsertQueryBuilder {
             }),
         });
     }
+    /**
+     * Creates an `insert into "person" default values` query.
+     */
+    defaultValues() {
+        return new InsertQueryBuilder({
+            ...this.#props,
+            queryNode: InsertQueryNode.cloneWith(this.#props.queryNode, {
+                defaultValues: true,
+            }),
+        });
+    }
     /**
      * Changes an `insert into` query to an `insert ignore into` query.
      *
@@ -308,7 +319,7 @@ export class InsertQueryBuilder {
         return new InsertQueryBuilder({
             ...this.#props,
             queryNode: InsertQueryNode.cloneWith(this.#props.queryNode, {
-                onDuplicateKey: OnDuplicateKeyNode.create(parseUpdateExpression(update)),
+                onDuplicateKey: OnDuplicateKeyNode.create(parseUpdateObjectExpression(update)),
             }),
         });
     }
@@ -396,8 +407,8 @@ export class InsertQueryBuilder {
     /**
      * Change the output type of the query.
      *
-     * You should only use this method as the last resort if the types
-     * don't support your use case.
+     * This method call doesn't change the SQL in any way. This methods simply
+     * returns a copy of this `InsertQueryBuilder` with a new output type.
      */
     $castTo() {
         return new InsertQueryBuilder(this.#props);

package/dist/esm/query-builder/insert-result.d.ts

@@ -23,7 +23,14 @@
  */
 export declare class InsertResult {
     /**
-     * The auto incrementing primary key
+     * The auto incrementing primary key of the inserted row.
+     *
+     * This property can be undefined when the query contains an `on conflict`
+     * clause that makes the query succeed even when nothing gets inserted.
+     *
+     * This property is always undefined on dialects like PostgreSQL that
+     * don't return the inserted id by default. On those dialects you need
+     * to use the {@link ReturningInterface.returning | returning} method.
      */
     readonly insertId: bigint | undefined;
     /**

package/dist/esm/query-builder/insert-result.js

@@ -24,7 +24,14 @@
  */
 export class InsertResult {
     /**
-     * The auto incrementing primary key
+     * The auto incrementing primary key of the inserted row.
+     *
+     * This property can be undefined when the query contains an `on conflict`
+     * clause that makes the query succeed even when nothing gets inserted.
+     *
+     * This property is always undefined on dialects like PostgreSQL that
+     * don't return the inserted id by default. On those dialects you need
+     * to use the {@link ReturningInterface.returning | returning} method.
      */
     insertId;
     /**

package/dist/esm/query-builder/json-path-builder.d.ts

@@ -1,10 +1,11 @@
 import { AliasableExpression, AliasedExpression, Expression } from '../expression/expression.js';
 import { AliasNode } from '../operation-node/alias-node.js';
+import { JSONPathNode } from '../operation-node/json-path-node.js';
 import { JSONReferenceNode } from '../operation-node/json-reference-node.js';
 import { OperationNode } from '../operation-node/operation-node.js';
 export declare class JSONPathBuilder<S, O = S> {
     #private;
-    constructor(node: JSONReferenceNode);
+    constructor(node: JSONReferenceNode | JSONPathNode);
     /**
      * Access an element of a JSON array in a specific location.
      *
@@ -123,7 +124,7 @@ export declare class JSONPathBuilder<S, O = S> {
 }
 export declare class TraversedJSONPathBuilder<S, O> extends JSONPathBuilder<S, O> implements AliasableExpression<O> {
     #private;
-    constructor(node: JSONReferenceNode);
+    constructor(node: JSONReferenceNode | JSONPathNode);
     /** @private */
     /**
      * All expressions need to have this getter for complicated type-related reasons.
@@ -231,7 +232,8 @@ export declare class TraversedJSONPathBuilder<S, O> extends JSONPathBuilder<S, O
      * This method call doesn't change the SQL in any way. This methods simply
      * returns a copy of this `JSONPathBuilder` with a new output type.
      */
-    $castTo<T>(): JSONPathBuilder<T>;
+    $castTo<C>(): JSONPathBuilder<C>;
+    $notNull(): JSONPathBuilder<Exclude<O, null>>;
     /**
      * Creates the OperationNode that describes how to compile this expression into SQL.
      *

package/dist/esm/query-builder/json-path-builder.js

@@ -132,9 +132,12 @@ export class JSONPathBuilder {
         return this.#createBuilderWithPathLeg('Member', key);
     }
     #createBuilderWithPathLeg(legType, value) {
-        return new TraversedJSONPathBuilder(JSONReferenceNode.cloneWithTraversal(this.#node, JSONPathNode.is(this.#node.traversal)
-            ? JSONPathNode.cloneWithLeg(this.#node.traversal, JSONPathLegNode.create(legType, value))
-            : JSONOperatorChainNode.cloneWithValue(this.#node.traversal, ValueNode.createImmediate(value))));
+        if (JSONReferenceNode.is(this.#node)) {
+            return new TraversedJSONPathBuilder(JSONReferenceNode.cloneWithTraversal(this.#node, JSONPathNode.is(this.#node.traversal)
+                ? JSONPathNode.cloneWithLeg(this.#node.traversal, JSONPathLegNode.create(legType, value))
+                : JSONOperatorChainNode.cloneWithValue(this.#node.traversal, ValueNode.createImmediate(value))));
+        }
+        return new TraversedJSONPathBuilder(JSONPathNode.cloneWithLeg(this.#node, JSONPathLegNode.create(legType, value)));
     }
 }
 export class TraversedJSONPathBuilder extends JSONPathBuilder {
@@ -159,6 +162,9 @@ export class TraversedJSONPathBuilder extends JSONPathBuilder {
     $castTo() {
         return new JSONPathBuilder(this.#node);
     }
+    $notNull() {
+        return new JSONPathBuilder(this.#node);
+    }
     toOperationNode() {
         return this.#node;
     }

package/dist/esm/query-builder/on-conflict-builder.d.ts

@@ -4,7 +4,8 @@ import { OperationNodeSource } from '../operation-node/operation-node-source.js'
 import { ComparisonOperatorExpression, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
 import { ExpressionOrFactory } from '../parser/expression-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
-import { UpdateExpression } from '../parser/update-set-parser.js';
+import { UpdateObjectExpression } from '../parser/update-set-parser.js';
+import { Updateable } from '../util/column-type.js';
 import { AnyColumn, SqlBool } from '../util/type-utils.js';
 import { WhereInterface } from './where-interface.js';
 export declare class OnConflictBuilder<DB, TB extends keyof DB> implements WhereInterface<DB, TB> {
@@ -40,12 +41,6 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      * methods for alternative ways to specify the conflict target.
      */
     expression(expression: Expression<any>): OnConflictBuilder<DB, TB>;
-    /**
-     * Specify an index predicate for the index target.
-     *
-     * See {@link WhereInterface.where} for more info.
-     */
-    where<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): OnConflictBuilder<DB, TB>;
     /**
      * Adds a `where` expression to the query.
      *
@@ -345,13 +340,60 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      *   .execute()
      * ```
      */
-    where(expression: ExpressionOrFactory<DB, TB, SqlBool>): OnConflictBuilder<DB, TB>;
+    where<RE extends ReferenceExpression<DB, TB>, VE extends OperandValueExpressionOrList<DB, TB, RE>>(lhs: RE, op: ComparisonOperatorExpression, rhs: VE): OnConflictBuilder<DB, TB>;
+    where<E extends ExpressionOrFactory<DB, TB, SqlBool>>(expression: E): OnConflictBuilder<DB, TB>;
     /**
-     * Specify an index predicate for the index target.
+     * Adds a `where` clause where both sides of the operator are references
+     * to columns.
      *
-     * See {@link WhereInterface.whereRef} for more info.
+     * The normal `where` method treats the right hand side argument as a
+     * value by default. `whereRef` treats it as a column reference. This method is
+     * expecially useful with joins and correlated subqueries.
+     *
+     * ### Examples
+     *
+     * Usage with a join:
+     *
+     * ```ts
+     * db.selectFrom(['person', 'pet'])
+     *   .selectAll()
+     *   .whereRef('person.first_name', '=', 'pet.name')
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select * from "person", "pet" where "person"."first_name" = "pet"."name"
+     * ```
+     *
+     * Usage in a subquery:
+     *
+     * ```ts
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .selectAll('person')
+     *   .select((eb) => eb
+     *     .selectFrom('pet')
+     *     .select('name')
+     *     .whereRef('pet.owner_id', '=', 'person.id')
+     *     .limit(1)
+     *     .as('pet_name')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person".*, (
+     *   select "name"
+     *   from "pet"
+     *   where "pet"."owner_id" = "person"."id"
+     *   limit $1
+     * ) as "pet_name"
+     * from "person"
      */
-    whereRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): OnConflictBuilder<DB, TB>;
+    whereRef<LRE extends ReferenceExpression<DB, TB>, RRE extends ReferenceExpression<DB, TB>>(lhs: LRE, op: ComparisonOperatorExpression, rhs: RRE): OnConflictBuilder<DB, TB>;
     /**
      * Clears all where expressions from the query.
      *
@@ -435,7 +477,7 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      *   )
      * ```
      */
-    doUpdateSet(update: UpdateExpression<OnConflictDatabase<DB, TB>, OnConflictTables<TB>, OnConflictTables<TB>>): OnConflictUpdateBuilder<OnConflictDatabase<DB, TB>, OnConflictTables<TB>>;
+    doUpdateSet(update: UpdateObjectExpression<OnConflictDatabase<DB, TB>, OnConflictTables<TB>, OnConflictTables<TB>>): OnConflictUpdateBuilder<OnConflictDatabase<DB, TB>, OnConflictTables<TB>>;
     /**
      * Simply calls the provided function passing `this` as the only argument. `$call` returns
      * what the provided function returns.
@@ -446,7 +488,7 @@ export interface OnConflictBuilderProps {
     readonly onConflictNode: OnConflictNode;
 }
 export type OnConflictDatabase<DB, TB extends keyof DB> = {
-    [K in keyof DB | 'excluded']: K extends keyof DB ? DB[K] : DB[TB];
+    [K in keyof DB | 'excluded']: Updateable<K extends keyof DB ? DB[K] : DB[TB]>;
 };
 export type OnConflictTables<TB> = TB | 'excluded';
 export declare class OnConflictDoNothingBuilder<DB, TB extends keyof DB> implements OperationNodeSource {
@@ -462,7 +504,7 @@ export declare class OnConflictUpdateBuilder<DB, TB extends keyof DB> implements
      *
      * See {@link WhereInterface.where} for more info.
      */
-    where<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): OnConflictUpdateBuilder<DB, TB>;
+    where<RE extends ReferenceExpression<DB, TB>, VE extends OperandValueExpressionOrList<DB, TB, RE>>(lhs: RE, op: ComparisonOperatorExpression, rhs: VE): OnConflictUpdateBuilder<DB, TB>;
     /**
      * Adds a `where` expression to the query.
      *
@@ -762,13 +804,13 @@ export declare class OnConflictUpdateBuilder<DB, TB extends keyof DB> implements
      *   .execute()
      * ```
      */
-    where(expression: ExpressionOrFactory<DB, TB, SqlBool>): OnConflictUpdateBuilder<DB, TB>;
+    where<E extends ExpressionOrFactory<DB, TB, SqlBool>>(expression: E): OnConflictUpdateBuilder<DB, TB>;
     /**
      * Specify a where condition for the update operation.
      *
      * See {@link WhereInterface.whereRef} for more info.
      */
-    whereRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): OnConflictUpdateBuilder<DB, TB>;
+    whereRef<LRE extends ReferenceExpression<DB, TB>, RRE extends ReferenceExpression<DB, TB>>(lhs: LRE, op: ComparisonOperatorExpression, rhs: RRE): OnConflictUpdateBuilder<DB, TB>;
     /**
      * Clears all where expressions from the query.
      *

package/dist/esm/query-builder/on-conflict-builder.js

@@ -3,7 +3,7 @@ import { ColumnNode } from '../operation-node/column-node.js';
 import { IdentifierNode } from '../operation-node/identifier-node.js';
 import { OnConflictNode } from '../operation-node/on-conflict-node.js';
 import { parseValueBinaryOperationOrExpression, parseReferentialBinaryOperation, } from '../parser/binary-operation-parser.js';
-import { parseUpdateExpression, } from '../parser/update-set-parser.js';
+import { parseUpdateObjectExpression, } from '../parser/update-set-parser.js';
 import { freeze } from '../util/object-utils.js';
 import { preventAwait } from '../util/prevent-await.js';
 export class OnConflictBuilder {
@@ -81,11 +81,6 @@ export class OnConflictBuilder {
             onConflictNode: OnConflictNode.cloneWithIndexWhere(this.#props.onConflictNode, parseValueBinaryOperationOrExpression(args)),
         });
     }
-    /**
-     * Specify an index predicate for the index target.
-     *
-     * See {@link WhereInterface.whereRef} for more info.
-     */
     whereRef(lhs, op, rhs) {
         return new OnConflictBuilder({
             ...this.#props,
@@ -173,7 +168,7 @@ export class OnConflictBuilder {
         return new OnConflictUpdateBuilder({
             ...this.#props,
             onConflictNode: OnConflictNode.cloneWith(this.#props.onConflictNode, {
-                updates: parseUpdateExpression(update),
+                updates: parseUpdateObjectExpression(update),
             }),
         });
     }

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

@@ -28,7 +28,7 @@ export declare class OverBuilder<DB, TB extends keyof DB> implements OperationNo
      * from "person"
      * ```
      */
-    orderBy(orderBy: StringReference<DB, TB> | DynamicReferenceBuilder<any>, direction?: OrderByDirectionExpression): OverBuilder<DB, TB>;
+    orderBy<OE extends StringReference<DB, TB> | DynamicReferenceBuilder<any>>(orderBy: OE, direction?: OrderByDirectionExpression): OverBuilder<DB, TB>;
     /**
      * Adds partition by clause item/s inside the over function.
      *
@@ -51,7 +51,7 @@ export declare class OverBuilder<DB, TB extends keyof DB> implements OperationNo
      * ```
      */
     partitionBy(partitionBy: ReadonlyArray<PartitionByExpression<DB, TB>>): OverBuilder<DB, TB>;
-    partitionBy(partitionBy: PartitionByExpression<DB, TB>): OverBuilder<DB, TB>;
+    partitionBy<PE extends PartitionByExpression<DB, TB>>(partitionBy: PE): OverBuilder<DB, TB>;
     /**
      * Simply calls the provided function passing `this` as the only argument. `$call` returns
      * what the provided function returns.