kysely 0.27.3 → 0.27.5

package/dist/esm/index.d.ts

@@ -5,6 +5,7 @@ export { ExpressionBuilder, expressionBuilder, } from './expression/expression-b
 export * from './expression/expression-wrapper.js';
 export * from './query-builder/where-interface.js';
 export * from './query-builder/returning-interface.js';
+export * from './query-builder/output-interface.js';
 export * from './query-builder/having-interface.js';
 export * from './query-builder/select-query-builder.js';
 export * from './query-builder/insert-query-builder.js';
@@ -91,17 +92,21 @@ export * from './plugin/with-schema/with-schema-plugin.js';
 export * from './plugin/parse-json-results/parse-json-results-plugin.js';
 export * from './operation-node/add-column-node.js';
 export * from './operation-node/add-constraint-node.js';
+export * from './operation-node/add-index-node.js';
+export * from './operation-node/aggregate-function-node.js';
 export * from './operation-node/alias-node.js';
 export * from './operation-node/alter-column-node.js';
 export * from './operation-node/alter-table-node.js';
 export * from './operation-node/and-node.js';
+export * from './operation-node/binary-operation-node.js';
 export * from './operation-node/case-node.js';
+export * from './operation-node/cast-node.js';
 export * from './operation-node/check-constraint-node.js';
 export * from './operation-node/column-definition-node.js';
 export * from './operation-node/column-node.js';
 export * from './operation-node/column-update-node.js';
-export * from './operation-node/common-table-expression-node.js';
 export * from './operation-node/common-table-expression-name-node.js';
+export * from './operation-node/common-table-expression-node.js';
 export * from './operation-node/constraint-node.js';
 export * from './operation-node/create-index-node.js';
 export * from './operation-node/create-schema-node.js';
@@ -109,6 +114,7 @@ export * from './operation-node/create-table-node.js';
 export * from './operation-node/create-type-node.js';
 export * from './operation-node/create-view-node.js';
 export * from './operation-node/data-type-node.js';
+export * from './operation-node/default-insert-value-node.js';
 export * from './operation-node/default-value-node.js';
 export * from './operation-node/delete-query-node.js';
 export * from './operation-node/drop-column-node.js';
@@ -118,8 +124,11 @@ export * from './operation-node/drop-schema-node.js';
 export * from './operation-node/drop-table-node.js';
 export * from './operation-node/drop-type-node.js';
 export * from './operation-node/drop-view-node.js';
+export * from './operation-node/explain-node.js';
+export * from './operation-node/fetch-node.js';
 export * from './operation-node/foreign-key-constraint-node.js';
 export * from './operation-node/from-node.js';
+export * from './operation-node/function-node.js';
 export * from './operation-node/generated-node.js';
 export * from './operation-node/group-by-item-node.js';
 export * from './operation-node/group-by-node.js';
@@ -127,8 +136,14 @@ export * from './operation-node/having-node.js';
 export * from './operation-node/identifier-node.js';
 export * from './operation-node/insert-query-node.js';
 export * from './operation-node/join-node.js';
+export * from './operation-node/json-operator-chain-node.js';
+export * from './operation-node/json-path-leg-node.js';
+export * from './operation-node/json-path-node.js';
+export * from './operation-node/json-reference-node.js';
 export * from './operation-node/limit-node.js';
 export * from './operation-node/list-node.js';
+export * from './operation-node/matched-node.js';
+export * from './operation-node/merge-query-node.js';
 export * from './operation-node/modify-column-node.js';
 export * from './operation-node/offset-node.js';
 export * from './operation-node/on-conflict-node.js';
@@ -142,7 +157,11 @@ export * from './operation-node/operator-node.js';
 export * from './operation-node/or-node.js';
 export * from './operation-node/order-by-item-node.js';
 export * from './operation-node/order-by-node.js';
+export * from './operation-node/output-node.js';
+export * from './operation-node/over-node.js';
 export * from './operation-node/parens-node.js';
+export * from './operation-node/partition-by-item-node.js';
+export * from './operation-node/partition-by-node.js';
 export * from './operation-node/primary-constraint-node.js';
 export * from './operation-node/primitive-value-list-node.js';
 export * from './operation-node/query-node.js';
@@ -151,38 +170,26 @@ export * from './operation-node/reference-node.js';
 export * from './operation-node/references-node.js';
 export * from './operation-node/rename-column-node.js';
 export * from './operation-node/returning-node.js';
+export * from './operation-node/schemable-identifier-node.js';
 export * from './operation-node/select-all-node.js';
-export * from './operation-node/select-query-node.js';
+export * from './operation-node/select-modifier-node.js';
 export * from './operation-node/select-query-node.js';
 export * from './operation-node/selection-node.js';
+export * from './operation-node/set-operation-node.js';
+export * from './operation-node/simple-reference-expression-node.js';
 export * from './operation-node/table-node.js';
+export * from './operation-node/top-node.js';
+export * from './operation-node/tuple-node.js';
+export * from './operation-node/unary-operation-node.js';
 export * from './operation-node/unique-constraint-node.js';
 export * from './operation-node/update-query-node.js';
+export * from './operation-node/using-node.js';
 export * from './operation-node/value-list-node.js';
 export * from './operation-node/value-node.js';
 export * from './operation-node/values-node.js';
 export * from './operation-node/when-node.js';
 export * from './operation-node/where-node.js';
 export * from './operation-node/with-node.js';
-export * from './operation-node/explain-node.js';
-export * from './operation-node/default-insert-value-node.js';
-export * from './operation-node/aggregate-function-node.js';
-export * from './operation-node/over-node.js';
-export * from './operation-node/partition-by-node.js';
-export * from './operation-node/partition-by-item-node.js';
-export * from './operation-node/set-operation-node.js';
-export * from './operation-node/binary-operation-node.js';
-export * from './operation-node/unary-operation-node.js';
-export * from './operation-node/using-node.js';
-export * from './operation-node/json-reference-node.js';
-export * from './operation-node/json-path-leg-node.js';
-export * from './operation-node/json-path-node.js';
-export * from './operation-node/json-operator-chain-node.js';
-export * from './operation-node/tuple-node.js';
-export * from './operation-node/merge-query-node.js';
-export * from './operation-node/matched-node.js';
-export * from './operation-node/fetch-node.js';
-export * from './operation-node/top-node.js';
 export * from './util/column-type.js';
 export * from './util/compilable.js';
 export * from './util/explainable.js';

package/dist/esm/index.js

@@ -6,6 +6,7 @@ export { expressionBuilder, } from './expression/expression-builder.js';
 export * from './expression/expression-wrapper.js';
 export * from './query-builder/where-interface.js';
 export * from './query-builder/returning-interface.js';
+export * from './query-builder/output-interface.js';
 export * from './query-builder/having-interface.js';
 export * from './query-builder/select-query-builder.js';
 export * from './query-builder/insert-query-builder.js';
@@ -92,17 +93,21 @@ export * from './plugin/with-schema/with-schema-plugin.js';
 export * from './plugin/parse-json-results/parse-json-results-plugin.js';
 export * from './operation-node/add-column-node.js';
 export * from './operation-node/add-constraint-node.js';
+export * from './operation-node/add-index-node.js';
+export * from './operation-node/aggregate-function-node.js';
 export * from './operation-node/alias-node.js';
 export * from './operation-node/alter-column-node.js';
 export * from './operation-node/alter-table-node.js';
 export * from './operation-node/and-node.js';
+export * from './operation-node/binary-operation-node.js';
 export * from './operation-node/case-node.js';
+export * from './operation-node/cast-node.js';
 export * from './operation-node/check-constraint-node.js';
 export * from './operation-node/column-definition-node.js';
 export * from './operation-node/column-node.js';
 export * from './operation-node/column-update-node.js';
-export * from './operation-node/common-table-expression-node.js';
 export * from './operation-node/common-table-expression-name-node.js';
+export * from './operation-node/common-table-expression-node.js';
 export * from './operation-node/constraint-node.js';
 export * from './operation-node/create-index-node.js';
 export * from './operation-node/create-schema-node.js';
@@ -110,6 +115,7 @@ export * from './operation-node/create-table-node.js';
 export * from './operation-node/create-type-node.js';
 export * from './operation-node/create-view-node.js';
 export * from './operation-node/data-type-node.js';
+export * from './operation-node/default-insert-value-node.js';
 export * from './operation-node/default-value-node.js';
 export * from './operation-node/delete-query-node.js';
 export * from './operation-node/drop-column-node.js';
@@ -119,8 +125,11 @@ export * from './operation-node/drop-schema-node.js';
 export * from './operation-node/drop-table-node.js';
 export * from './operation-node/drop-type-node.js';
 export * from './operation-node/drop-view-node.js';
+export * from './operation-node/explain-node.js';
+export * from './operation-node/fetch-node.js';
 export * from './operation-node/foreign-key-constraint-node.js';
 export * from './operation-node/from-node.js';
+export * from './operation-node/function-node.js';
 export * from './operation-node/generated-node.js';
 export * from './operation-node/group-by-item-node.js';
 export * from './operation-node/group-by-node.js';
@@ -128,8 +137,14 @@ export * from './operation-node/having-node.js';
 export * from './operation-node/identifier-node.js';
 export * from './operation-node/insert-query-node.js';
 export * from './operation-node/join-node.js';
+export * from './operation-node/json-operator-chain-node.js';
+export * from './operation-node/json-path-leg-node.js';
+export * from './operation-node/json-path-node.js';
+export * from './operation-node/json-reference-node.js';
 export * from './operation-node/limit-node.js';
 export * from './operation-node/list-node.js';
+export * from './operation-node/matched-node.js';
+export * from './operation-node/merge-query-node.js';
 export * from './operation-node/modify-column-node.js';
 export * from './operation-node/offset-node.js';
 export * from './operation-node/on-conflict-node.js';
@@ -143,7 +158,11 @@ export * from './operation-node/operator-node.js';
 export * from './operation-node/or-node.js';
 export * from './operation-node/order-by-item-node.js';
 export * from './operation-node/order-by-node.js';
+export * from './operation-node/output-node.js';
+export * from './operation-node/over-node.js';
 export * from './operation-node/parens-node.js';
+export * from './operation-node/partition-by-item-node.js';
+export * from './operation-node/partition-by-node.js';
 export * from './operation-node/primary-constraint-node.js';
 export * from './operation-node/primitive-value-list-node.js';
 export * from './operation-node/query-node.js';
@@ -152,38 +171,26 @@ export * from './operation-node/reference-node.js';
 export * from './operation-node/references-node.js';
 export * from './operation-node/rename-column-node.js';
 export * from './operation-node/returning-node.js';
+export * from './operation-node/schemable-identifier-node.js';
 export * from './operation-node/select-all-node.js';
-export * from './operation-node/select-query-node.js';
+export * from './operation-node/select-modifier-node.js';
 export * from './operation-node/select-query-node.js';
 export * from './operation-node/selection-node.js';
+export * from './operation-node/set-operation-node.js';
+export * from './operation-node/simple-reference-expression-node.js';
 export * from './operation-node/table-node.js';
+export * from './operation-node/top-node.js';
+export * from './operation-node/tuple-node.js';
+export * from './operation-node/unary-operation-node.js';
 export * from './operation-node/unique-constraint-node.js';
 export * from './operation-node/update-query-node.js';
+export * from './operation-node/using-node.js';
 export * from './operation-node/value-list-node.js';
 export * from './operation-node/value-node.js';
 export * from './operation-node/values-node.js';
 export * from './operation-node/when-node.js';
 export * from './operation-node/where-node.js';
 export * from './operation-node/with-node.js';
-export * from './operation-node/explain-node.js';
-export * from './operation-node/default-insert-value-node.js';
-export * from './operation-node/aggregate-function-node.js';
-export * from './operation-node/over-node.js';
-export * from './operation-node/partition-by-node.js';
-export * from './operation-node/partition-by-item-node.js';
-export * from './operation-node/set-operation-node.js';
-export * from './operation-node/binary-operation-node.js';
-export * from './operation-node/unary-operation-node.js';
-export * from './operation-node/using-node.js';
-export * from './operation-node/json-reference-node.js';
-export * from './operation-node/json-path-leg-node.js';
-export * from './operation-node/json-path-node.js';
-export * from './operation-node/json-operator-chain-node.js';
-export * from './operation-node/tuple-node.js';
-export * from './operation-node/merge-query-node.js';
-export * from './operation-node/matched-node.js';
-export * from './operation-node/fetch-node.js';
-export * from './operation-node/top-node.js';
 export * from './util/column-type.js';
 export * from './util/compilable.js';
 export * from './util/explainable.js';

package/dist/esm/kysely.d.ts

@@ -20,37 +20,27 @@ import { DrainOuterGeneric } from './util/type-utils.js';
  * The main Kysely class.
  *
  * You should create one instance of `Kysely` per database using the {@link Kysely}
- * constructor. Each `Kysely` instance maintains it's own connection pool.
+ * constructor. Each `Kysely` instance maintains its own connection pool.
  *
  * ### Examples
  *
- * This example assumes your database has tables `person` and `pet`:
+ * This example assumes your database has a "person" table:
  *
  * ```ts
- * import { Kysely, Generated, PostgresDialect } from 'kysely'
- *
- * interface PersonTable {
- *   id: Generated<number>
- *   first_name: string
- *   last_name: string
- * }
- *
- * interface PetTable {
- *   id: Generated<number>
- *   owner_id: number
- *   name: string
- *   species: 'cat' | 'dog'
- * }
+ * import * as Sqlite from 'better-sqlite3'
+ * import { type Generated, Kysely, SqliteDialect } from 'kysely'
  *
  * interface Database {
- *   person: PersonTable,
- *   pet: PetTable
+ *   person: {
+ *     id: Generated<number>
+ *     first_name: string
+ *     last_name: string | null
+ *   }
  * }
  *
  * const db = new Kysely<Database>({
- *   dialect: new PostgresDialect({
- *     host: 'localhost',
- *     database: 'kysely_test',
+ *   dialect: new SqliteDialect({
+ *     database: new Sqlite(':memory:'),
  *   })
  * })
  * ```
@@ -86,30 +76,52 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
     case(): CaseBuilder<DB, keyof DB>;
     case<V>(value: Expression<V>): CaseBuilder<DB, keyof DB, V>;
     /**
-     * Returns a {@link FunctionModule} that can be used to write type safe function
+     * Returns a {@link FunctionModule} that can be used to write somewhat type-safe function
      * calls.
      *
      * ```ts
+     * const { count } = db.fn
+     *
      * await db.selectFrom('person')
      *   .innerJoin('pet', 'pet.owner_id', 'person.id')
-     *   .select((eb) => [
-     *     'person.id',
-     *     eb.fn.count('pet.id').as('pet_count')
+     *   .select([
+     *     'id',
+     *     count('pet.id').as('person_count'),
      *   ])
      *   .groupBy('person.id')
-     *   .having((eb) => eb.fn.count('pet.id'), '>', 10)
+     *   .having(count('pet.id'), '>', 10)
      *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * select "person"."id", count("pet"."id") as "pet_count"
+     * select "person"."id", count("pet"."id") as "person_count"
      * from "person"
      * inner join "pet" on "pet"."owner_id" = "person"."id"
      * group by "person"."id"
      * having count("pet"."id") > $1
      * ```
+     *
+     * Why "somewhat" type-safe? Because the function calls are not bound to the
+     * current query context. They allow you to reference columns and tables that
+     * are not in the current query. E.g. remove the `innerJoin` from the previous
+     * query and TypeScript won't even complain.
+     *
+     * If you want to make the function calls fully type-safe, you can use the
+     * {@link ExpressionBuilder.fn} getter for a query context-aware, stricter {@link FunctionModule}.
+     *
+     * ```ts
+     * await db.selectFrom('person')
+     *   .innerJoin('pet', 'pet.owner_id', 'person.id')
+     *   .select((eb) => [
+     *     'person.id',
+     *     eb.fn.count('pet.id').as('pet_count')
+     *   ])
+     *   .groupBy('person.id')
+     *   .having((eb) => eb.fn.count('pet.id'), '>', 10)
+     *   .execute()
+     * ```
      */
     get fn(): FunctionModule<DB, keyof DB>;
     /**
@@ -118,8 +130,11 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
      * The returned {@link TransactionBuilder} can be used to configure the transaction. The
      * {@link TransactionBuilder.execute} method can then be called to run the transaction.
      * {@link TransactionBuilder.execute} takes a function that is run inside the
-     * transaction. If the function throws, the transaction is rolled back. Otherwise
-     * the transaction is committed.
+     * transaction. If the function throws an exception,
+     * 1. the exception is caught,
+     * 2. the transaction is rolled back, and
+     * 3. the exception is thrown again.
+     * Otherwise the transaction is committed.
      *
      * The callback function passed to the {@link TransactionBuilder.execute | execute}
      * method gets the transaction object as its only argument. The transaction is
@@ -130,9 +145,12 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
      *
      * <!-- siteExample("transactions", "Simple transaction", 10) -->
      *
-     * This example inserts two rows in a transaction. If an error is thrown inside
-     * the callback passed to the `execute` method, the transaction is rolled back.
-     * Otherwise it's committed.
+     * This example inserts two rows in a transaction. If an exception is thrown inside
+     * the callback passed to the `execute` method,
+     * 1. the exception is caught,
+     * 2. the transaction is rolled back, and
+     * 3. the exception is thrown again.
+     * Otherwise the transaction is committed.
      *
      * ```ts
      * const catto = await db.transaction().execute(async (trx) => {
@@ -160,12 +178,18 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
      * Setting the isolation level:
      *
      * ```ts
+     * import type { Kysely } from 'kysely'
+     *
      * await db
      *   .transaction()
      *   .setIsolationLevel('serializable')
      *   .execute(async (trx) => {
      *     await doStuff(trx)
      *   })
+     *
+     * async function doStuff(kysely: typeof db) {
+     *   // ...
+     * }
      * ```
      */
     transaction(): TransactionBuilder<DB>;
@@ -183,6 +207,10 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
      *     // the same connection.
      *     await doStuff(db)
      *   })
+     *
+     * async function doStuff(kysely: typeof db) {
+     *   // ...
+     * }
      * ```
      */
     connection(): ConnectionBuilder<DB>;
@@ -209,7 +237,6 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
      *
      * The following example adds and uses a temporary table:
      *
-     * @example
      * ```ts
      * await db.schema
      *   .createTable('temp_table')
@@ -250,7 +277,7 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
     /**
      * Executes a given compiled query or query builder.
      *
-     * See {@link https://github.com/koskimas/kysely/blob/master/site/docs/recipes/splitting-build-compile-and-execute-code.md#execute-compiled-queries splitting build, compile and execute code recipe} for more information.
+     * See {@link https://github.com/kysely-org/kysely/blob/master/site/docs/recipes/0004-splitting-query-building-and-execution.md#execute-compiled-queries splitting build, compile and execute code recipe} for more information.
      */
     executeQuery<R>(query: CompiledQuery<R> | Compilable<R>, queryId?: QueryId): Promise<QueryResult<R>>;
 }
@@ -269,8 +296,11 @@ export declare class Transaction<DB> extends Kysely<DB> {
      * The returned {@link TransactionBuilder} can be used to configure the transaction. The
      * {@link TransactionBuilder.execute} method can then be called to run the transaction.
      * {@link TransactionBuilder.execute} takes a function that is run inside the
-     * transaction. If the function throws, the transaction is rolled back. Otherwise
-     * the transaction is committed.
+     * transaction. If the function throws an exception,
+     * 1. the exception is caught,
+     * 2. the transaction is rolled back, and
+     * 3. the exception is thrown again.
+     * Otherwise the transaction is committed.
      *
      * The callback function passed to the {@link TransactionBuilder.execute | execute}
      * method gets the transaction object as its only argument. The transaction is
@@ -281,9 +311,12 @@ export declare class Transaction<DB> extends Kysely<DB> {
      *
      * <!-- siteExample("transactions", "Simple transaction", 10) -->
      *
-     * This example inserts two rows in a transaction. If an error is thrown inside
-     * the callback passed to the `execute` method, the transaction is rolled back.
-     * Otherwise it's committed.
+     * This example inserts two rows in a transaction. If an exception is thrown inside
+     * the callback passed to the `execute` method,
+     * 1. the exception is caught,
+     * 2. the transaction is rolled back, and
+     * 3. the exception is thrown again.
+     * Otherwise the transaction is committed.
      *
      * ```ts
      * const catto = await db.transaction().execute(async (trx) => {
@@ -311,12 +344,18 @@ export declare class Transaction<DB> extends Kysely<DB> {
      * Setting the isolation level:
      *
      * ```ts
+     * import type { Kysely } from 'kysely'
+     *
      * await db
      *   .transaction()
      *   .setIsolationLevel('serializable')
      *   .execute(async (trx) => {
      *     await doStuff(trx)
      *   })
+     *
+     * async function doStuff(kysely: typeof db) {
+     *   // ...
+     * }
      * ```
      */
     transaction(): TransactionBuilder<DB>;
@@ -334,6 +373,10 @@ export declare class Transaction<DB> extends Kysely<DB> {
      *     // the same connection.
      *     await doStuff(db)
      *   })
+     *
+     * async function doStuff(kysely: typeof db) {
+     *   // ...
+     * }
      * ```
      */
     connection(): ConnectionBuilder<DB>;
@@ -366,7 +409,6 @@ export declare class Transaction<DB> extends Kysely<DB> {
      *
      * The following example adds and uses a temporary table:
      *
-     * @example
      * ```ts
      * await db.schema
      *   .createTable('temp_table')
@@ -406,16 +448,32 @@ export interface KyselyConfig {
      *
      * ### Examples
      *
+     * Setting up built-in logging for preferred log levels:
+     *
      * ```ts
+     * import * as Sqlite from 'better-sqlite3'
+     * import { Kysely, SqliteDialect } from 'kysely'
+     * import type { Database } from 'type-editor' // imaginary module
+     *
      * const db = new Kysely<Database>({
-     *   dialect: new PostgresDialect(postgresConfig),
+     *   dialect: new SqliteDialect({
+     *     database: new Sqlite(':memory:'),
+     *   }),
      *   log: ['query', 'error']
      * })
      * ```
      *
+     * Setting up custom logging:
+     *
      * ```ts
+     * import * as Sqlite from 'better-sqlite3'
+     * import { Kysely, SqliteDialect } from 'kysely'
+     * import type { Database } from 'type-editor' // imaginary module
+     *
      * const db = new Kysely<Database>({
-     *   dialect: new PostgresDialect(postgresConfig),
+     *   dialect: new SqliteDialect({
+     *     database: new Sqlite(':memory:'),
+     *   }),
      *   log(event): void {
      *     if (event.level === 'query') {
      *       console.log(event.query.sql)