kysely 0.27.3 → 0.27.5

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

@@ -8,6 +8,7 @@ const update_query_node_js_1 = require("../operation-node/update-query-node.js")
 const insert_values_parser_js_1 = require("../parser/insert-values-parser.js");
 const join_parser_js_1 = require("../parser/join-parser.js");
 const merge_parser_js_1 = require("../parser/merge-parser.js");
+const select_parser_js_1 = require("../parser/select-parser.js");
 const top_parser_js_1 = require("../parser/top-parser.js");
 const noop_query_executor_js_1 = require("../query-executor/noop-query-executor.js");
 const object_utils_js_1 = require("../util/object-utils.js");
@@ -20,6 +21,35 @@ class MergeQueryBuilder {
     constructor(props) {
         this.#props = (0, object_utils_js_1.freeze)(props);
     }
+    /**
+     * This can be used to add any additional SQL to the end of the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * await db
+     *   .mergeInto('person')
+     *   .using('pet', 'pet.owner_id', 'person.id')
+     *   .whenMatched()
+     *   .thenDelete()
+     *   .modifyEnd(sql.raw('-- this is a comment'))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * merge into "person" using "pet" on "pet"."owner_id" = "person"."id" when matched then delete -- this is a comment
+     * ```
+     */
+    modifyEnd(modifier) {
+        return new MergeQueryBuilder({
+            ...this.#props,
+            queryNode: query_node_js_1.QueryNode.cloneWithEndModifier(this.#props.queryNode, modifier.toOperationNode()),
+        });
+    }
     /**
      * Changes a `merge into` query to an `merge top into` query.
      *
@@ -79,6 +109,18 @@ class MergeQueryBuilder {
             queryNode: merge_query_node_js_1.MergeQueryNode.cloneWithUsing(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('Using', args)),
         });
     }
+    output(args) {
+        return new MergeQueryBuilder({
+            ...this.#props,
+            queryNode: query_node_js_1.QueryNode.cloneWithOutput(this.#props.queryNode, (0, select_parser_js_1.parseSelectArg)(args)),
+        });
+    }
+    outputAll(table) {
+        return new MergeQueryBuilder({
+            ...this.#props,
+            queryNode: query_node_js_1.QueryNode.cloneWithOutput(this.#props.queryNode, (0, select_parser_js_1.parseSelectAll)(table)),
+        });
+    }
 }
 exports.MergeQueryBuilder = MergeQueryBuilder;
 (0, prevent_await_js_1.preventAwait)(MergeQueryBuilder, "don't await MergeQueryBuilder instances directly. To execute the query you need to call `execute` when available.");
@@ -87,6 +129,35 @@ class WheneableMergeQueryBuilder {
     constructor(props) {
         this.#props = (0, object_utils_js_1.freeze)(props);
     }
+    /**
+     * This can be used to add any additional SQL to the end of the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * await db
+     *   .mergeInto('person')
+     *   .using('pet', 'pet.owner_id', 'person.id')
+     *   .whenMatched()
+     *   .thenDelete()
+     *   .modifyEnd(sql.raw('-- this is a comment'))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * merge into "person" using "pet" on "pet"."owner_id" = "person"."id" when matched then delete -- this is a comment
+     * ```
+     */
+    modifyEnd(modifier) {
+        return new WheneableMergeQueryBuilder({
+            ...this.#props,
+            queryNode: query_node_js_1.QueryNode.cloneWithEndModifier(this.#props.queryNode, modifier.toOperationNode()),
+        });
+    }
     /**
      * See {@link MergeQueryBuilder.top}.
      */
@@ -217,6 +288,18 @@ class WheneableMergeQueryBuilder {
     whenNotMatchedBySourceAndRef(lhs, op, rhs) {
         return this.#whenNotMatched([lhs, op, rhs], true, true);
     }
+    output(args) {
+        return new WheneableMergeQueryBuilder({
+            ...this.#props,
+            queryNode: query_node_js_1.QueryNode.cloneWithOutput(this.#props.queryNode, (0, select_parser_js_1.parseSelectArg)(args)),
+        });
+    }
+    outputAll(table) {
+        return new WheneableMergeQueryBuilder({
+            ...this.#props,
+            queryNode: query_node_js_1.QueryNode.cloneWithOutput(this.#props.queryNode, (0, select_parser_js_1.parseSelectAll)(table)),
+        });
+    }
     #whenNotMatched(args, refRight = false, bySource = false) {
         const props = {
             ...this.#props,
@@ -239,13 +322,15 @@ class WheneableMergeQueryBuilder {
      * The next example uses a helper function `log` to log a query:
      *
      * ```ts
+     * import type { Compilable } from 'kysely'
+     *
      * function log<T extends Compilable>(qb: T): T {
      *   console.log(qb.compile())
      *   return qb
      * }
      *
-     * db.updateTable('person')
-     *   .set(values)
+     * await db.updateTable('person')
+     *   .set({ first_name: 'John' })
      *   .$call(log)
      *   .execute()
      * ```
@@ -266,7 +351,9 @@ class WheneableMergeQueryBuilder {
      * ### Examples
      *
      * ```ts
-     * async function updatePerson(id: number, updates: UpdateablePerson, returnLastName: boolean) {
+     * import type { PersonUpdate } from 'type-editor' // imaginary module
+     *
+     * async function updatePerson(id: number, updates: PersonUpdate, returnLastName: boolean) {
      *   return await db
      *     .updateTable('person')
      *     .set(updates)
@@ -282,11 +369,11 @@ class WheneableMergeQueryBuilder {
      * the code. In the example above the return type of the `updatePerson` function is:
      *
      * ```ts
-     * {
+     * Promise<{
      *   id: number
      *   first_name: string
      *   last_name?: string
-     * }
+     * }>
      * ```
      */
     $if(condition, func) {
@@ -301,7 +388,7 @@ class WheneableMergeQueryBuilder {
         return this.#props.executor.transformQuery(this.#props.queryNode, this.#props.queryId);
     }
     compile() {
-        return this.#props.executor.compileQuery(this.#props.queryNode, this.#props.queryId);
+        return this.#props.executor.compileQuery(this.toOperationNode(), this.#props.queryId);
     }
     /**
      * Executes the query and returns an array of rows.
@@ -311,6 +398,10 @@ class WheneableMergeQueryBuilder {
     async execute() {
         const compiledQuery = this.compile();
         const result = await this.#props.executor.executeQuery(compiledQuery, this.#props.queryId);
+        if (compiledQuery.query.output &&
+            this.#props.executor.adapter.supportsOutput) {
+            return result.rows;
+        }
         return [new merge_result_js_1.MergeResult(result.numAffectedRows)];
     }
     /**
@@ -434,7 +525,7 @@ class MatchedThenableMergeQueryBuilder {
      *   .thenUpdate((ub) => ub
      *     .set(sql`metadata['has_pets']`, 'Y')
      *     .set({
-     *       updated_at: Date.now(),
+     *       updated_at: new Date().toISOString(),
      *     })
      *   )
      *   .execute()

package/dist/cjs/query-builder/no-result-error.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isNoResultErrorConstructor = exports.NoResultError = void 0;
+exports.NoResultError = void 0;
+exports.isNoResultErrorConstructor = isNoResultErrorConstructor;
 class NoResultError extends Error {
     /**
      * The operation node tree of the query that was executed.
@@ -15,4 +16,3 @@ exports.NoResultError = NoResultError;
 function isNoResultErrorConstructor(fn) {
     return Object.prototype.hasOwnProperty.call(fn, 'prototype');
 }
-exports.isNoResultErrorConstructor = isNoResultErrorConstructor;

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

@@ -73,6 +73,8 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      * you can always use:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * sql`your operator`
      * ```
      *
@@ -84,7 +86,7 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
-     *   .where('id', 'in', ['1', '2', '3'])
+     *   .where('id', 'in', [1, 2, 3])
      *   .execute()
      * ```
      *
@@ -303,7 +305,7 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(
-     *     sql`coalesce(first_name, last_name)`,
+     *     sql<string>`coalesce(first_name, last_name)`,
      *     'like',
      *     '%' + name + '%',
      *   )
@@ -332,6 +334,8 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      * import { sql } from 'kysely'
      * const { ref } = db.dynamic
      *
+     * const columnFromUserInput: string = 'id'
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
@@ -419,21 +423,25 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      * ### Examples
      *
      * ```ts
+     * const id = 1
+     * const first_name = 'John'
+     *
      * await db
      *   .insertInto('person')
-     *   .values({ first_name, pic })
+     *   .values({ first_name, id })
      *   .onConflict((oc) => oc
-     *     .column('pic')
+     *     .column('id')
      *     .doNothing()
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * insert into "person" ("first_name", "pic")
+     * insert into "person" ("first_name", "id")
      * values ($1, $2)
-     * on conflict ("pic") do nothing
+     * on conflict ("id") do nothing
      * ```
      */
     doNothing(): OnConflictDoNothingBuilder<DB, TB>;
@@ -443,21 +451,25 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      * ### Examples
      *
      * ```ts
+     * const id = 1
+     * const first_name = 'John'
+     *
      * await db
      *   .insertInto('person')
-     *   .values({ first_name, pic })
+     *   .values({ first_name, id })
      *   .onConflict((oc) => oc
-     *     .column('pic')
+     *     .column('id')
      *     .doUpdateSet({ first_name })
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * insert into "person" ("first_name", "pic")
+     * insert into "person" ("first_name", "id")
      * values ($1, $2)
-     * on conflict ("pic")
+     * on conflict ("id")
      * do update set "first_name" = $3
      * ```
      *
@@ -466,15 +478,32 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      * to create an upsert operation:
      *
      * ```ts
-     * db.insertInto('person')
-     *   .values(person)
-     *   .onConflict((oc) => oc
-     *     .column('id')
-     *     .doUpdateSet((eb) => ({
-     *       first_name: eb.ref('excluded.first_name'),
-     *       last_name: eb.ref('excluded.last_name')
-     *     }))
+     * import type { NewPerson } from 'type-editor' // imaginary module
+     *
+     * async function upsertPerson(person: NewPerson): Promise<void> {
+     *   await db.insertInto('person')
+     *     .values(person)
+     *     .onConflict((oc) => oc
+     *       .column('id')
+     *       .doUpdateSet((eb) => ({
+     *         first_name: eb.ref('excluded.first_name'),
+     *         last_name: eb.ref('excluded.last_name')
+     *       })
+     *     )
      *   )
+     *   .execute()
+     * }
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name")
+     * values ($1, $2)
+     * on conflict ("id")
+     * do update set
+     *  "first_name" = excluded."first_name",
+     *  "last_name" = excluded."last_name"
      * ```
      */
     doUpdateSet(update: UpdateObjectExpression<OnConflictDatabase<DB, TB>, OnConflictTables<TB>, OnConflictTables<TB>>): OnConflictUpdateBuilder<OnConflictDatabase<DB, TB>, OnConflictTables<TB>>;
@@ -537,6 +566,8 @@ export declare class OnConflictUpdateBuilder<DB, TB extends keyof DB> implements
      * you can always use:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * sql`your operator`
      * ```
      *
@@ -548,7 +579,7 @@ export declare class OnConflictUpdateBuilder<DB, TB extends keyof DB> implements
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
-     *   .where('id', 'in', ['1', '2', '3'])
+     *   .where('id', 'in', [1, 2, 3])
      *   .execute()
      * ```
      *
@@ -767,7 +798,7 @@ export declare class OnConflictUpdateBuilder<DB, TB extends keyof DB> implements
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(
-     *     sql`coalesce(first_name, last_name)`,
+     *     sql<string>`coalesce(first_name, last_name)`,
      *     'like',
      *     '%' + name + '%',
      *   )
@@ -796,6 +827,8 @@ export declare class OnConflictUpdateBuilder<DB, TB extends keyof DB> implements
      * import { sql } from 'kysely'
      * const { ref } = db.dynamic
      *
+     * const columnFromUserInput: string = 'id'
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()

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

@@ -101,21 +101,25 @@ class OnConflictBuilder {
      * ### Examples
      *
      * ```ts
+     * const id = 1
+     * const first_name = 'John'
+     *
      * await db
      *   .insertInto('person')
-     *   .values({ first_name, pic })
+     *   .values({ first_name, id })
      *   .onConflict((oc) => oc
-     *     .column('pic')
+     *     .column('id')
      *     .doNothing()
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * insert into "person" ("first_name", "pic")
+     * insert into "person" ("first_name", "id")
      * values ($1, $2)
-     * on conflict ("pic") do nothing
+     * on conflict ("id") do nothing
      * ```
      */
     doNothing() {
@@ -132,21 +136,25 @@ class OnConflictBuilder {
      * ### Examples
      *
      * ```ts
+     * const id = 1
+     * const first_name = 'John'
+     *
      * await db
      *   .insertInto('person')
-     *   .values({ first_name, pic })
+     *   .values({ first_name, id })
      *   .onConflict((oc) => oc
-     *     .column('pic')
+     *     .column('id')
      *     .doUpdateSet({ first_name })
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * insert into "person" ("first_name", "pic")
+     * insert into "person" ("first_name", "id")
      * values ($1, $2)
-     * on conflict ("pic")
+     * on conflict ("id")
      * do update set "first_name" = $3
      * ```
      *
@@ -155,15 +163,32 @@ class OnConflictBuilder {
      * to create an upsert operation:
      *
      * ```ts
-     * db.insertInto('person')
-     *   .values(person)
-     *   .onConflict((oc) => oc
-     *     .column('id')
-     *     .doUpdateSet((eb) => ({
-     *       first_name: eb.ref('excluded.first_name'),
-     *       last_name: eb.ref('excluded.last_name')
-     *     }))
+     * import type { NewPerson } from 'type-editor' // imaginary module
+     *
+     * async function upsertPerson(person: NewPerson): Promise<void> {
+     *   await db.insertInto('person')
+     *     .values(person)
+     *     .onConflict((oc) => oc
+     *       .column('id')
+     *       .doUpdateSet((eb) => ({
+     *         first_name: eb.ref('excluded.first_name'),
+     *         last_name: eb.ref('excluded.last_name')
+     *       })
+     *     )
      *   )
+     *   .execute()
+     * }
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name")
+     * values ($1, $2)
+     * on conflict ("id")
+     * do update set
+     *  "first_name" = excluded."first_name",
+     *  "last_name" = excluded."last_name"
      * ```
      */
     doUpdateSet(update) {

package/dist/cjs/query-builder/output-interface.d.ts

@@ -0,0 +1,138 @@
+import { ExpressionBuilder } from '../expression/expression-builder.js';
+import { AliasedExpressionOrFactory } from '../parser/expression-parser.js';
+import { ReturningAllRow, ReturningRow } from '../parser/returning-parser.js';
+import { AnyAliasedColumnWithTable, AnyColumnWithTable } from '../util/type-utils.js';
+export interface OutputInterface<DB, TB extends keyof DB, O, OP extends OutputPrefix = OutputPrefix> {
+    /**
+     * Allows you to return data from modified rows.
+     *
+     * On supported databases like MS SQL Server (MSSQL), this method can be chained
+     * to `insert`, `update`, `delete` and `merge` queries to return data.
+     *
+     * Also see the {@link outputAll} method.
+     *
+     * ### Examples
+     *
+     * Return one column:
+     *
+     * ```ts
+     * const { id } = await db
+     *   .insertInto('person')
+     *   .output('inserted.id')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston',
+     *     gender: 'female',
+     *   })
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name", "gender")
+     * output "inserted"."id"
+     * values (@1, @2, @3)
+     * ```
+     *
+     * Return multiple columns:
+     *
+     * ```ts
+     * const { old_first_name, old_last_name, new_first_name, new_last_name } = await db
+     *   .updateTable('person')
+     *   .set({ first_name: 'John', last_name: 'Doe' })
+     *   .output([
+     *     'deleted.first_name as old_first_name',
+     *     'deleted.last_name as old_last_name',
+     *     'inserted.first_name as new_first_name',
+     *     'inserted.last_name as new_last_name',
+     *   ])
+     *   .where('created_at', '<', new Date())
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * update "person"
+     * set "first_name" = @1, "last_name" = @2
+     * output "deleted"."first_name" as "old_first_name",
+     *   "deleted"."last_name" as "old_last_name",
+     *   "inserted"."first_name" as "new_first_name",
+     *   "inserted"."last_name" as "new_last_name"
+     * where "created_at" < @3
+     * ```
+     *
+     * Return arbitrary expressions:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const { full_name } = await db
+     *   .deleteFrom('person')
+     *   .output((eb) => sql<string>`concat(${eb.ref('deleted.first_name')}, ' ', ${eb.ref('deleted.last_name')})`.as('full_name'))
+     *   .where('created_at', '<', new Date())
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * delete from "person"
+     * output concat("deleted"."first_name", ' ', "deleted"."last_name") as "full_name"
+     * where "created_at" < @1
+     * ```
+     *
+     * Return the action performed on the row:
+     *
+     * ```ts
+     * await db
+     *   .mergeInto('person')
+     *   .using('pet', 'pet.owner_id', 'person.id')
+     *   .whenMatched()
+     *   .thenDelete()
+     *   .whenNotMatched()
+     *   .thenInsertValues({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'male'
+     *   })
+     *   .output([
+     *     'inserted.id as inserted_id',
+     *     'deleted.id as deleted_id',
+     *   ])
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * merge into "person"
+     * using "pet" on "pet"."owner_id" = "person"."id"
+     * when matched then delete
+     * when not matched then
+     * insert ("first_name", "last_name", "gender")
+     * values (@1, @2, @3)
+     * output "inserted"."id" as "inserted_id", "deleted"."id" as "deleted_id"
+     * ```
+     *
+     */
+    output<OE extends OutputExpression<DB, TB, OP>>(selections: ReadonlyArray<OE>): OutputInterface<DB, TB, ReturningRow<DB, TB, O, SelectExpressionFromOutputExpression<OE>>, OP>;
+    output<CB extends OutputCallback<DB, TB, OP>>(callback: CB): OutputInterface<DB, TB, ReturningRow<DB, TB, O, SelectExpressionFromOutputCallback<CB>>, OP>;
+    output<OE extends OutputExpression<DB, TB, OP>>(selection: OE): OutputInterface<DB, TB, ReturningRow<DB, TB, O, SelectExpressionFromOutputExpression<OE>>, OP>;
+    /**
+     * Adds an `output {prefix}.*` to an `insert`/`update`/`delete`/`merge` query on databases
+     * that support `output` such as MS SQL Server (MSSQL).
+     *
+     * Also see the {@link output} method.
+     */
+    outputAll(table: OP): OutputInterface<DB, TB, ReturningAllRow<DB, TB, O>, OP>;
+}
+export type OutputPrefix = 'deleted' | 'inserted';
+export type OutputDatabase<DB, TB extends keyof DB, OP extends OutputPrefix = OutputPrefix> = {
+    [K in OP]: DB[TB];
+};
+export type OutputExpression<DB, TB extends keyof DB, OP extends OutputPrefix = OutputPrefix, ODB = OutputDatabase<DB, TB, OP>, OTB extends keyof ODB = keyof ODB> = AnyAliasedColumnWithTable<ODB, OTB> | AnyColumnWithTable<ODB, OTB> | AliasedExpressionOrFactory<ODB, OTB>;
+export type OutputCallback<DB, TB extends keyof DB, OP extends OutputPrefix = OutputPrefix> = (eb: ExpressionBuilder<OutputDatabase<DB, TB, OP>, OP>) => ReadonlyArray<OutputExpression<DB, TB, OP>>;
+export type SelectExpressionFromOutputExpression<OE> = OE extends `${OutputPrefix}.${infer C}` ? C : OE;
+export type SelectExpressionFromOutputCallback<CB> = CB extends (eb: ExpressionBuilder<any, any>) => ReadonlyArray<infer OE> ? SelectExpressionFromOutputExpression<OE> : never;

package/dist/cjs/query-builder/output-interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/query-builder/returning-interface.d.ts

@@ -26,20 +26,20 @@ export interface ReturningInterface<DB, TB extends keyof DB, O> {
      *     last_name: 'Aniston'
      *   })
      *   .returning('id')
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      * ```
      *
      * Return multiple columns:
      *
      * ```ts
-     * const { id, first_name } = await db
+     * const { id, last_name } = await db
      *   .insertInto('person')
      *   .values({
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   })
      *   .returning(['id', 'last_name'])
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      * ```
      *
      * Return arbitrary expressions:
@@ -56,9 +56,9 @@ export interface ReturningInterface<DB, TB extends keyof DB, O> {
      *   .returning((eb) => [
      *     'id as id',
      *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name'),
-     *     eb.selectFrom('pets').select('pet.id').limit(1).as('first_pet_id')
+     *     eb.selectFrom('pet').select('pet.id').limit(1).as('first_pet_id')
      *   ])
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      * ```
      */
     returning<SE extends SelectExpression<DB, TB>>(selections: ReadonlyArray<SE>): ReturningInterface<DB, TB, ReturningRow<DB, TB, O, SE>>;
@@ -67,6 +67,8 @@ export interface ReturningInterface<DB, TB extends keyof DB, O> {
     /**
      * Adds a `returning *` to an insert/update/delete query on databases
      * that support `returning` such as PostgreSQL.
+     *
+     * Also see the {@link returning} method.
      */
     returningAll(): ReturningInterface<DB, TB, Selectable<DB[TB]>>;
 }

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

@@ -5,11 +5,19 @@ export interface SelectQueryBuilderExpression<O> extends AliasableExpression<O>
     /**
      * Creates the OperationNode that describes how to compile this expression into SQL.
      *
+     * ### Examples
+     *
      * If you are creating a custom expression, it's often easiest to use the {@link sql}
      * template tag to build the node:
      *
      * ```ts
+     * import { type Expression, type OperationNode, sql } from 'kysely'
+     *
      * class SomeExpression<T> implements Expression<T> {
+     *   get expressionType(): T | undefined {
+     *     return undefined
+     *   }
+     *
      *   toOperationNode(): OperationNode {
      *     return sql`some sql here`.toOperationNode()
      *   }