kysely 0.17.1 → 0.17.2

package/dist/cjs/query-executor/query-executor.d.ts

@@ -1,20 +1,24 @@
 import { ConnectionProvider } from '../driver/connection-provider.js';
-import { DatabaseConnection, QueryResult } from '../driver/database-connection.js';
+import { QueryResult } from '../driver/database-connection.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { RootOperationNode } from '../query-compiler/query-compiler.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
 import { QueryId } from '../util/query-id.js';
 import { DialectAdapter } from '../dialect/dialect-adapter.js';
 /**
- * This class abstracts away the details of how to compile a query into SQL
+ * This interface abstracts away the details of how to compile a query into SQL
  * and execute it. Instead of passing around all those details, {@link SelectQueryBuilder}
  * and other classes that execute queries can just pass around and instance of
  * `QueryExecutor`.
  */
-export declare abstract class QueryExecutor implements ConnectionProvider {
-    #private;
-    constructor(plugins?: KyselyPlugin[]);
-    abstract get adapter(): DialectAdapter;
+export interface QueryExecutor extends ConnectionProvider {
+    /**
+     * Returns the adapter for the current dialect.
+     */
+    get adapter(): DialectAdapter;
+    /**
+     * Returns all installed plugins.
+     */
     get plugins(): ReadonlyArray<KyselyPlugin>;
     /**
      * Given the query the user has built (expressed as an operation node tree)
@@ -27,12 +31,7 @@ export declare abstract class QueryExecutor implements ConnectionProvider {
      * the output of {@link transformQuery} into this method but you can
      * compile any query using this method.
      */
-    abstract compileQuery(node: RootOperationNode, queryId: QueryId): CompiledQuery;
-    /**
-     * Provides a connection for the callback and takes care of disposing
-     * the connection after the callback has been run.
-     */
-    abstract provideConnection<T>(consumer: (connection: DatabaseConnection) => Promise<T>): Promise<T>;
+    compileQuery(node: RootOperationNode, queryId: QueryId): CompiledQuery;
     /**
      * Executes a compiled query and runs the result through all plugins'
      * `transformResult` method.
@@ -41,24 +40,24 @@ export declare abstract class QueryExecutor implements ConnectionProvider {
     /**
      * Returns a copy of this executor with a new connection provider.
      */
-    abstract withConnectionProvider(connectionProvider: ConnectionProvider): QueryExecutor;
+    withConnectionProvider(connectionProvider: ConnectionProvider): QueryExecutor;
     /**
      * Returns a copy of this executor with a plugin added as the
      * last plugin.
      */
-    abstract withPlugin(plugin: KyselyPlugin): QueryExecutor;
+    withPlugin(plugin: KyselyPlugin): QueryExecutor;
     /**
      * Returns a copy of this executor with a list of plugins added
      * as the last plugins.
      */
-    abstract withPlugins(plugin: ReadonlyArray<KyselyPlugin>): QueryExecutor;
+    withPlugins(plugin: ReadonlyArray<KyselyPlugin>): QueryExecutor;
     /**
      * Returns a copy of this executor with a plugin added as the
      * first plugin.
      */
-    abstract withPluginAtFront(plugin: KyselyPlugin): QueryExecutor;
+    withPluginAtFront(plugin: KyselyPlugin): QueryExecutor;
     /**
      * Returns a copy of this executor without any plugins.
      */
-    abstract withoutPlugins(): QueryExecutor;
+    withoutPlugins(): QueryExecutor;
 }

package/dist/cjs/query-executor/query-executor.js

@@ -1,61 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QueryExecutor = void 0;
-const object_utils_js_1 = require("../util/object-utils.js");
-const NO_PLUGINS = (0, object_utils_js_1.freeze)([]);
-/**
- * This class abstracts away the details of how to compile a query into SQL
- * and execute it. Instead of passing around all those details, {@link SelectQueryBuilder}
- * and other classes that execute queries can just pass around and instance of
- * `QueryExecutor`.
- */
-class QueryExecutor {
-    #plugins;
-    constructor(plugins) {
-        this.#plugins = plugins ?? NO_PLUGINS;
-    }
-    get plugins() {
-        return this.#plugins;
-    }
-    /**
-     * Given the query the user has built (expressed as an operation node tree)
-     * this method runs it through all plugins' `transformQuery` methods and
-     * returns the result.
-     */
-    transformQuery(node, queryId) {
-        for (const plugin of this.#plugins) {
-            const transformedNode = plugin.transformQuery({ node, queryId });
-            // We need to do a runtime check here. There is no good way
-            // to write types that enforce this constraint.
-            if (transformedNode.kind === node.kind) {
-                node = transformedNode;
-            }
-            else {
-                throw new Error([
-                    `KyselyPlugin.transformQuery must return a node`,
-                    `of the same kind that was given to it.`,
-                    `The plugin was given a ${node.kind}`,
-                    `but it returned a ${transformedNode.kind}`,
-                ].join(' '));
-            }
-        }
-        return node;
-    }
-    /**
-     * Executes a compiled query and runs the result through all plugins'
-     * `transformResult` method.
-     */
-    async executeQuery(compiledQuery, queryId) {
-        return await this.provideConnection(async (connection) => {
-            const result = await connection.executeQuery(compiledQuery);
-            return this.#transformResult(result, queryId);
-        });
-    }
-    async #transformResult(result, queryId) {
-        for (const plugin of this.#plugins) {
-            result = await plugin.transformResult({ result, queryId });
-        }
-        return result;
-    }
-}
-exports.QueryExecutor = QueryExecutor;

package/dist/cjs/raw-builder/sql.d.ts

@@ -221,7 +221,7 @@ export interface Sql {
      *   sql.id('first_name')
      * ]
      *
-     * sql`BEFORE ${sql.array(things, sql`::varchar, `)} AFTER`
+     * sql`BEFORE ${sql.join(things, sql`::varchar, `)} AFTER`
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -281,7 +281,7 @@ export interface Sql {
  * from "person"
  * where birthdate between $1 and $2
  * and "nicknames" @> ARRAY[$3, $4, $5, $6, $7, $8, $9, $10]
- * order by concate(first_name, ' ', last_name)
+ * order by concat(first_name, ' ', last_name)
  * ```
  *
  * SQL snippets can be executed by calling the `execute` method and passing a `Kysely`
@@ -313,7 +313,15 @@ export interface Sql {
  *   .select([
  *     'first_name',
  *     'last_name',
- *     (eb) => sql<string>`concat(${eb.ref('first_name')}, ' ', ${eb.ref('last_name')})`.as('full_name')
+ *     (eb) => {
+ *       // The `eb.ref` method is type-safe and only accepts
+ *       // column references that are possible.
+ *       const firstName = eb.ref('first_name')
+ *       const lastName = eb.ref('last_name')
+ *
+ *       const fullName = sql<string>`concat(${firstName}, ' ', ${lastName})`
+ *       return fullName.as('full_name')
+ *     }
  *   ])
  * ```
  *

package/dist/cjs/raw-builder/sql.js

@@ -58,7 +58,7 @@ const raw_builder_js_1 = require("./raw-builder.js");
  * from "person"
  * where birthdate between $1 and $2
  * and "nicknames" @> ARRAY[$3, $4, $5, $6, $7, $8, $9, $10]
- * order by concate(first_name, ' ', last_name)
+ * order by concat(first_name, ' ', last_name)
  * ```
  *
  * SQL snippets can be executed by calling the `execute` method and passing a `Kysely`
@@ -90,7 +90,15 @@ const raw_builder_js_1 = require("./raw-builder.js");
  *   .select([
  *     'first_name',
  *     'last_name',
- *     (eb) => sql<string>`concat(${eb.ref('first_name')}, ' ', ${eb.ref('last_name')})`.as('full_name')
+ *     (eb) => {
+ *       // The `eb.ref` method is type-safe and only accepts
+ *       // column references that are possible.
+ *       const firstName = eb.ref('first_name')
+ *       const lastName = eb.ref('last_name')
+ *
+ *       const fullName = sql<string>`concat(${firstName}, ' ', ${lastName})`
+ *       return fullName.as('full_name')
+ *     }
  *   ])
  * ```
  *

package/dist/cjs/schema/alter-table-builder.d.ts

@@ -23,6 +23,13 @@ export declare class AlterTableBuilder {
     alterColumn(column: string): AlterColumnBuilder;
     dropColumn(column: string): AlterTableExecutor;
     renameColumn(column: string, newColumn: string): AlterTableExecutor;
+    /**
+     * See {@link CreateTableBuilder.addColumn}
+     *
+     * Unlike {@link CreateTableBuilder.addColumn} this method returns the column builder
+     * and doesn't take a callback as the last argument. This is because you can only
+     * add one column per `ALTER TABLE` query.
+     */
     addColumn(columnName: string, dataType: DataTypeExpression): AlterTableAddColumnBuilder;
     /**
      * Creates an `alter table modify column` query. The `modify column` statement
@@ -30,8 +37,21 @@ export declare class AlterTableBuilder {
      * should use the `alterColumn` method.
      */
     modifyColumn(columnName: string, dataType: DataTypeExpression): AlterTableModifyColumnBuilder;
+    /**
+     * See {@link CreateTableBuilder.addUniqueConstraint}
+     */
     addUniqueConstraint(constraintName: string, columns: string[]): AlterTableExecutor;
+    /**
+     * See {@link CreateTableBuilder.addCheckConstraint}
+     */
     addCheckConstraint(constraintName: string, checkExpression: AnyRawBuilder): AlterTableExecutor;
+    /**
+     * See {@link CreateTableBuilder.addForeignKeyConstraint}
+     *
+     * Unlike {@link CreateTableBuilder.addForeignKeyConstraint} this method returns
+     * the constraint builder and doesn't take a callback as the last argument. This
+     * is because you can only add one column per `ALTER TABLE` query.
+     */
     addForeignKeyConstraint(constraintName: string, columns: string[], targetTable: string, targetColumns: string[]): AlterTableAddForeignKeyConstraintBuilder;
 }
 export interface AlterTableBuilderProps {
@@ -142,7 +162,8 @@ export declare class AlterTableAddColumnBuilder implements ColumnDefinitionBuild
      *   .execute()
      * ```
      *
-     * Raw {@link sql} expressions are also supported:
+     * Values passed to `defaultTo` are interpreted as value literals by default. You can define
+     * an arbitrary SQL expression using the {@link sql} template tag:
      *
      * ```ts
      * import { sql } from 'kysely'
@@ -306,7 +327,8 @@ export declare class AlterTableModifyColumnBuilder implements ColumnDefinitionBu
      *   .execute()
      * ```
      *
-     * Raw {@link sql} expressions are also supported:
+     * Values passed to `defaultTo` are interpreted as value literals by default. You can define
+     * an arbitrary SQL expression using the {@link sql} template tag:
      *
      * ```ts
      * import { sql } from 'kysely'

package/dist/cjs/schema/alter-table-builder.js

@@ -68,6 +68,13 @@ class AlterTableBuilder {
             }),
         });
     }
+    /**
+     * See {@link CreateTableBuilder.addColumn}
+     *
+     * Unlike {@link CreateTableBuilder.addColumn} this method returns the column builder
+     * and doesn't take a callback as the last argument. This is because you can only
+     * add one column per `ALTER TABLE` query.
+     */
     addColumn(columnName, dataType) {
         return new AlterTableAddColumnBuilder({
             ...this.#props,
@@ -85,6 +92,9 @@ class AlterTableBuilder {
             columnBuilder: new column_definition_builder_js_1.ColumnDefinitionBuilder(column_definition_node_js_1.ColumnDefinitionNode.create(columnName, (0, data_type_parser_js_1.parseDataTypeExpression)(dataType))),
         });
     }
+    /**
+     * See {@link CreateTableBuilder.addUniqueConstraint}
+     */
     addUniqueConstraint(constraintName, columns) {
         return new AlterTableExecutor({
             ...this.#props,
@@ -93,6 +103,9 @@ class AlterTableBuilder {
             }),
         });
     }
+    /**
+     * See {@link CreateTableBuilder.addCheckConstraint}
+     */
     addCheckConstraint(constraintName, checkExpression) {
         return new AlterTableExecutor({
             ...this.#props,
@@ -101,6 +114,13 @@ class AlterTableBuilder {
             }),
         });
     }
+    /**
+     * See {@link CreateTableBuilder.addForeignKeyConstraint}
+     *
+     * Unlike {@link CreateTableBuilder.addForeignKeyConstraint} this method returns
+     * the constraint builder and doesn't take a callback as the last argument. This
+     * is because you can only add one column per `ALTER TABLE` query.
+     */
     addForeignKeyConstraint(constraintName, columns, targetTable, targetColumns) {
         return new AlterTableAddForeignKeyConstraintBuilder({
             ...this.#props,

package/dist/cjs/schema/column-definition-builder.d.ts

@@ -83,7 +83,8 @@ export interface ColumnDefinitionBuilderInterface {
      *   .execute()
      * ```
      *
-     * Raw {@link sql} expressions are also supported:
+     * Values passed to `defaultTo` are interpreted as value literals by default. You can define
+     * an arbitrary SQL expression using the {@link sql} template tag:
      *
      * ```ts
      * import { sql } from 'kysely'
@@ -241,7 +242,8 @@ export declare class ColumnDefinitionBuilder implements ColumnDefinitionBuilderI
      *   .execute()
      * ```
      *
-     * Raw {@link sql} expressions are also supported:
+     * Values passed to `defaultTo` are interpreted as value literals by default. You can define
+     * an arbitrary SQL expression using the {@link sql} template tag:
      *
      * ```ts
      * import { sql } from 'kysely'

package/dist/cjs/schema/create-table-builder.d.ts

@@ -136,7 +136,7 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * )
      * ```
      *
-     * Add constraintfor multiple columns:
+     * Add constraint for multiple columns:
      *
      * ```ts
      * addForeignKeyConstraint(

package/dist/cjs/schema/create-table-builder.js

@@ -186,7 +186,7 @@ class CreateTableBuilder {
      * )
      * ```
      *
-     * Add constraintfor multiple columns:
+     * Add constraint for multiple columns:
      *
      * ```ts
      * addForeignKeyConstraint(

package/dist/cjs/util/type-utils.d.ts

@@ -74,7 +74,7 @@ export declare type ExtractColumnType<DB, TB extends keyof DB, C> = {
  *   movie: Movie
  * }
  *
- * type Columns = AnyColumn<Database, 'person' | 'pet'>
+ * type Columns = AnyColumnWithTable<Database, 'person' | 'pet'>
  *
  * // Columns == 'person.id' | 'pet.name' | 'pet.species'
  * ```

package/dist/esm/dialect/mysql/mysql-dialect-config.d.ts

@@ -202,4 +202,23 @@ export interface MysqlSslOptions {
      * You can also connect to a MySQL server without properly providing the appropriate CA to trust. You should not do this.
      */
     rejectUnauthorized?: boolean;
+    charsetNumber?: number;
+    compress?: boolean;
+    authSwitchHandler?: (data: any, callback: () => void) => any;
+    connectAttributes?: {
+        [param: string]: any;
+    };
+    decimalNumbers?: boolean;
+    isServer?: boolean;
+    maxPreparedStatements?: number;
+    namedPlaceholders?: boolean;
+    nestTables?: boolean | string;
+    passwordSha1?: string;
+    pool?: any;
+    stream?: any;
+    uri?: string;
+    Promise?: any;
+    authPlugins?: {
+        [key: string]: any;
+    };
 }

package/dist/esm/driver/default-connection-provider.d.ts

@@ -8,5 +8,5 @@ export declare class DefaultConnectionProvider implements ConnectionProvider {
      * Provides a connection for the callback and takes care of disposing
      * the connection after the callback has been run.
      */
-    provideConnection<T>(runner: (connection: DatabaseConnection) => Promise<T>): Promise<T>;
+    provideConnection<T>(consumer: (connection: DatabaseConnection) => Promise<T>): Promise<T>;
 }

package/dist/esm/driver/default-connection-provider.js

@@ -4,10 +4,10 @@ export class DefaultConnectionProvider {
     constructor(driver) {
         this.#driver = driver;
     }
-    async provideConnection(runner) {
+    async provideConnection(consumer) {
         const connection = await this.#driver.acquireConnection();
         try {
-            return await runner(connection);
+            return await consumer(connection);
         }
         finally {
             await this.#driver.releaseConnection(connection);

package/dist/esm/driver/dummy-driver.d.ts

@@ -27,6 +27,14 @@ import { Driver } from './driver.js';
  *   },
  * })
  * ```
+ *
+ * You can use it to build a query and compile it to SQL but trying to
+ * execute the query will throw an error.
+ *
+ * ```ts
+ * const { sql } = db.selectFrom('person').selectAll().compile()
+ * console.log(sql) // select * from "person"
+ * ```
  */
 export declare class DummyDriver implements Driver {
     /**

package/dist/esm/driver/dummy-driver.js

@@ -26,6 +26,14 @@
  *   },
  * })
  * ```
+ *
+ * You can use it to build a query and compile it to SQL but trying to
+ * execute the query will throw an error.
+ *
+ * ```ts
+ * const { sql } = db.selectFrom('person').selectAll().compile()
+ * console.log(sql) // select * from "person"
+ * ```
  */
 export class DummyDriver {
     async init() {

package/dist/esm/driver/single-connection-provider.d.ts

@@ -7,5 +7,5 @@ export declare class SingleConnectionProvider implements ConnectionProvider {
      * Provides a connection for the callback and takes care of disposing
      * the connection after the callback has been run.
      */
-    provideConnection<T>(runner: (connection: DatabaseConnection) => Promise<T>): Promise<T>;
+    provideConnection<T>(consumer: (connection: DatabaseConnection) => Promise<T>): Promise<T>;
 }

package/dist/esm/driver/single-connection-provider.js

@@ -5,11 +5,11 @@ export class SingleConnectionProvider {
     constructor(connection) {
         this.#connection = connection;
     }
-    async provideConnection(runner) {
+    async provideConnection(consumer) {
         while (this.#runningPromise) {
             await this.#runningPromise;
         }
-        const promise = this.#run(runner);
+        const promise = this.#run(consumer);
         this.#runningPromise = promise
             .then(() => {
             this.#runningPromise = undefined;

package/dist/esm/parser/complex-expression-parser.d.ts

@@ -1,7 +1,7 @@
-import { RawBuilder } from '../index-nodeless.js';
 import { AliasNode } from '../operation-node/alias-node.js';
 import { RawNode } from '../operation-node/raw-node.js';
 import { SelectQueryNode } from '../operation-node/select-query-node.js';
+import { RawBuilder } from '../raw-builder/raw-builder.js';
 import { AliasedQueryBuilderFactory, AliasedRawBuilderFactory, AnyAliasedQueryBuilder, AnyAliasedRawBuilder, AnySelectQueryBuilder, SelectQueryBuilderFactory, RawBuilderFactory } from '../util/type-utils.js';
 export declare type ComplexExpression<DB, TB extends keyof DB, V = any> = AnySelectQueryBuilder | SelectQueryBuilderFactory<DB, TB> | RawBuilder<V> | RawBuilderFactory<DB, TB>;
 export declare type AliasedComplexExpression<DB, TB extends keyof DB> = AnyAliasedQueryBuilder | AliasedQueryBuilderFactory<DB, TB> | AnyAliasedRawBuilder | AliasedRawBuilderFactory<DB, TB>;

package/dist/esm/plugin/deduplicate-joins/deduplicate-joins-transformer.d.ts

@@ -1,6 +1,7 @@
-import { DeleteQueryNode, UpdateQueryNode } from '../../index-nodeless.js';
+import { DeleteQueryNode } from '../../operation-node/delete-query-node.js';
 import { OperationNodeTransformer } from '../../operation-node/operation-node-transformer.js';
 import { SelectQueryNode } from '../../operation-node/select-query-node.js';
+import { UpdateQueryNode } from '../../operation-node/update-query-node.js';
 export declare class DeduplicateJoinsTransformer extends OperationNodeTransformer {
     #private;
     protected transformSelectQuery(node: SelectQueryNode): SelectQueryNode;

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

@@ -46,7 +46,13 @@ export declare class DeleteQueryBuilder<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 `sql\`your operator\``.
+     * you can always use
+     *
+     * ```ts
+     * sql`your operator`
+     * ```
+     *
+     * The next example uses the `>` operator:
      *
      * ```ts
      * const persons = await db
@@ -62,8 +68,8 @@ export declare class DeleteQueryBuilder<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 +77,8 @@ export declare class DeleteQueryBuilder<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 +86,7 @@ export declare class DeleteQueryBuilder<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

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

@@ -3,7 +3,7 @@ import { TableExpression, TableExpressionDatabase, TableExpressionTables } from
 import { FunctionBuilder } from './function-builder.js';
 import { ExtractTypeFromReferenceExpression, StringReference } from '../parser/reference-parser.js';
 import { RawBuilder } from '../raw-builder/raw-builder.js';
-import { QueryExecutor } from '../index-nodeless.js';
+import { QueryExecutor } from '../query-executor/query-executor.js';
 export declare class ExpressionBuilder<DB, TB extends keyof DB> {
     #private;
     constructor(props: ExpressionBuilderProps);

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

@@ -7,8 +7,8 @@ import { createQueryId } from '../util/query-id.js';
 import { FunctionBuilder } from './function-builder.js';
 import { parseStringReference, } from '../parser/reference-parser.js';
 import { RawBuilder } from '../raw-builder/raw-builder.js';
-import { RawNode } from '../index-nodeless.js';
 import { freeze } from '../util/object-utils.js';
+import { RawNode } from '../operation-node/raw-node.js';
 export class ExpressionBuilder {
     #props;
     constructor(props) {

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

@@ -1,5 +1,5 @@
 /// <reference types="./function-builder.d.ts" />
-import { RawNode } from '../index-nodeless.js';
+import { RawNode } from '../operation-node/raw-node.js';
 import { parseStringReference, } from '../parser/reference-parser.js';
 import { RawBuilder } from '../raw-builder/raw-builder.js';
 import { createQueryId } from '../util/query-id.js';

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

@@ -69,7 +69,13 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      * ```
      *
      * Operator can be any supported operator or if the typings don't support it
-     * you can always use `sql\`your operator\``.
+     * you can always use
+     *
+     * ```ts
+     * sql`your operator`
+     * ```
+     *
+     * The next example uses the `>` operator:
      *
      * ```ts
      * const persons = await db
@@ -85,8 +91,8 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      * 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
@@ -94,6 +100,8 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      *   .selectAll()
      *
      * if (firstName) {
+     *   // The query builder is immutable. Remember to reassign
+     *   // the result back to the query variable.
      *   query = query.where('first_name', '=', firstName)
      * }
      *
@@ -101,8 +109,7 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      * ```
      *
      * 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
@@ -426,7 +433,13 @@ export declare class OnConflictUpdateBuilder<DB, TB extends keyof DB> implements
      * ```
      *
      * Operator can be any supported operator or if the typings don't support it
-     * you can always use `sql\`your operator\``.
+     * you can always use
+     *
+     * ```ts
+     * sql`your operator`
+     * ```
+     *
+     * The next example uses the `>` operator:
      *
      * ```ts
      * const persons = await db
@@ -442,8 +455,8 @@ export declare class OnConflictUpdateBuilder<DB, TB extends keyof DB> implements
      * 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
@@ -451,6 +464,8 @@ export declare class OnConflictUpdateBuilder<DB, TB extends keyof DB> implements
      *   .selectAll()
      *
      * if (firstName) {
+     *   // The query builder is immutable. Remember to reassign
+     *   // the result back to the query variable.
      *   query = query.where('first_name', '=', firstName)
      * }
      *
@@ -458,8 +473,7 @@ export declare class OnConflictUpdateBuilder<DB, TB extends keyof DB> implements
      * ```
      *
      * 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