kysely 0.11.1 → 0.12.0

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

@@ -1,4 +1,4 @@
-import { CreateTableNode } from '../operation-node/create-table-node.js';
+import { CreateTableNode, OnCommitAction } from '../operation-node/create-table-node.js';
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { Compilable } from '../util/compilable.js';
@@ -13,6 +13,19 @@ import { DataTypeExpression } from '../parser/data-type-parser.js';
 export declare class CreateTableBuilder<TB extends string, C extends string = never> implements OperationNodeSource, Compilable {
     #private;
     constructor(props: CreateTableBuilderProps);
+    /**
+     * Adds the "temporary" modifier.
+     *
+     * Use this to create a temporary table.
+     */
+    temporary(): CreateTableBuilder<TB, C>;
+    /**
+     * Adds an "on commit" statement.
+     *
+     * This can be used in conjunction with temporary tables on supported databases
+     * like PostgreSQL.
+     */
+    onCommit(onCommit: OnCommitAction): CreateTableBuilder<TB, C>;
     /**
      * Adds the "if not exists" modifier.
      *
@@ -22,7 +35,8 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
     /**
      * Adds a column to the table.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .createTable('person')
@@ -42,7 +56,6 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * foreign key constraints need to be defined in at the level of the `create table`
      * query. See the next example:
      *
-     * @example
      * ```ts
      *   .addColumn('parent_id', 'integer')
      *   .addForeignKeyConstraint(
@@ -55,7 +68,6 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * keyword and you need to define an autoincrementing column for example using
      * `serial`:
      *
-     * @example
      * ```ts
      * await db.schema
      *   .createTable('person')
@@ -69,7 +81,8 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * The constraint name can be anything you want, but it must be unique
      * across the whole database.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * addPrimaryKeyConstraint('primary_key', ['first_name', 'last_name'])
      * ```
@@ -81,7 +94,8 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * The constraint name can be anything you want, but it must be unique
      * across the whole database.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * addUniqueConstraint('first_name_last_name_unique', ['first_name', 'last_name'])
      * ```
@@ -93,7 +107,8 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * The constraint name can be anything you want, but it must be unique
      * across the whole database.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * addCheckConstraint('check_legs', 'number_of_legs < 5')
      * ```
@@ -105,7 +120,8 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * The constraint name can be anything you want, but it must be unique
      * across the whole database.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * addForeignKeyConstraint(
      *   'owner_id_foreign',
@@ -115,7 +131,8 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * )
      * ```
      *
-     * @example
+     * Add constraintfor multiple columns:
+     *
      * ```ts
      * addForeignKeyConstraint(
      *   'owner_id_foreign',

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

@@ -1,5 +1,5 @@
 import { ColumnDefinitionNode } from '../operation-node/column-definition-node.js';
-import { CreateTableNode } from '../operation-node/create-table-node.js';
+import { CreateTableNode, } from '../operation-node/create-table-node.js';
 import { preventAwait } from '../util/prevent-await.js';
 import { ColumnDefinitionBuilder } from './column-definition-builder.js';
 import { freeze, noop } from '../util/object-utils.js';
@@ -19,6 +19,33 @@ export class CreateTableBuilder {
     constructor(props) {
         this.#props = freeze(props);
     }
+    /**
+     * Adds the "temporary" modifier.
+     *
+     * Use this to create a temporary table.
+     */
+    temporary() {
+        return new CreateTableBuilder({
+            ...this.#props,
+            createTableNode: CreateTableNode.cloneWith(this.#props.createTableNode, {
+                temporary: true,
+            }),
+        });
+    }
+    /**
+     * Adds an "on commit" statement.
+     *
+     * This can be used in conjunction with temporary tables on supported databases
+     * like PostgreSQL.
+     */
+    onCommit(onCommit) {
+        return new CreateTableBuilder({
+            ...this.#props,
+            createTableNode: CreateTableNode.cloneWith(this.#props.createTableNode, {
+                onCommit,
+            }),
+        });
+    }
     /**
      * Adds the "if not exists" modifier.
      *
@@ -27,13 +54,16 @@ export class CreateTableBuilder {
     ifNotExists() {
         return new CreateTableBuilder({
             ...this.#props,
-            createTableNode: CreateTableNode.cloneWithIfNotExists(this.#props.createTableNode, true),
+            createTableNode: CreateTableNode.cloneWith(this.#props.createTableNode, {
+                ifNotExists: true,
+            }),
         });
     }
     /**
      * Adds a column to the table.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .createTable('person')
@@ -53,7 +83,6 @@ export class CreateTableBuilder {
      * foreign key constraints need to be defined in at the level of the `create table`
      * query. See the next example:
      *
-     * @example
      * ```ts
      *   .addColumn('parent_id', 'integer')
      *   .addForeignKeyConstraint(
@@ -66,7 +95,6 @@ export class CreateTableBuilder {
      * keyword and you need to define an autoincrementing column for example using
      * `serial`:
      *
-     * @example
      * ```ts
      * await db.schema
      *   .createTable('person')
@@ -86,7 +114,8 @@ export class CreateTableBuilder {
      * The constraint name can be anything you want, but it must be unique
      * across the whole database.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * addPrimaryKeyConstraint('primary_key', ['first_name', 'last_name'])
      * ```
@@ -103,7 +132,8 @@ export class CreateTableBuilder {
      * The constraint name can be anything you want, but it must be unique
      * across the whole database.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * addUniqueConstraint('first_name_last_name_unique', ['first_name', 'last_name'])
      * ```
@@ -120,7 +150,8 @@ export class CreateTableBuilder {
      * The constraint name can be anything you want, but it must be unique
      * across the whole database.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * addCheckConstraint('check_legs', 'number_of_legs < 5')
      * ```
@@ -137,7 +168,8 @@ export class CreateTableBuilder {
      * The constraint name can be anything you want, but it must be unique
      * across the whole database.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * addForeignKeyConstraint(
      *   'owner_id_foreign',
@@ -147,7 +179,8 @@ export class CreateTableBuilder {
      * )
      * ```
      *
-     * @example
+     * Add constraintfor multiple columns:
+     *
      * ```ts
      * addForeignKeyConstraint(
      *   'owner_id_foreign',

package/dist/esm/schema/create-view-builder.d.ts

@@ -4,11 +4,16 @@ import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
 import { CreateViewNode } from '../operation-node/create-view-node.js';
-import { AnyQueryBuilder } from '../index.js';
-import { AnyRawBuilder } from '../util/type-utils.js';
+import { AnyRawBuilder, AnySelectQueryBuilder } from '../util/type-utils.js';
 export declare class CreateViewBuilder implements OperationNodeSource, Compilable {
     #private;
     constructor(props: CreateViewBuilderProps);
+    /**
+     * Adds the "temporary" modifier.
+     *
+     * Use this to create a temporary view.
+     */
+    temporary(): CreateViewBuilder;
     materialized(): CreateViewBuilder;
     /**
      * Only implemented on some dialects like SQLite. On most dialects, use {@link orReplace}.
@@ -16,7 +21,16 @@ export declare class CreateViewBuilder implements OperationNodeSource, Compilabl
     ifNotExists(): CreateViewBuilder;
     orReplace(): CreateViewBuilder;
     columns(columns: string[]): CreateViewBuilder;
-    as(query: AnyQueryBuilder | AnyRawBuilder): CreateViewBuilder;
+    /**
+     * Sets the select query or a `values` statement that creates the view.
+     *
+     * WARNING!
+     * Some dialects don't support parameterized queries in DDL statements and therefore
+     * the query or `raw` expression passed here is interpolated into a single string
+     * opening an SQL injection vulnerability. DO NOT pass unchecked user input into
+     * the query or `raw` expression passed to this method!
+     */
+    as(query: AnySelectQueryBuilder | AnyRawBuilder): CreateViewBuilder;
     toOperationNode(): CreateViewNode;
     compile(): CompiledQuery;
     execute(): Promise<void>;

package/dist/esm/schema/create-view-builder.js

@@ -2,22 +2,23 @@ import { preventAwait } from '../util/prevent-await.js';
 import { freeze } from '../util/object-utils.js';
 import { CreateViewNode } from '../operation-node/create-view-node.js';
 import { parseColumnName } from '../parser/reference-parser.js';
-import { QueryNode } from '../index.js';
 import { ImmediateValuePlugin } from '../plugin/immediate-value.ts/immediate-value-plugin.js';
 export class CreateViewBuilder {
     #props;
     constructor(props) {
-        this.#props = freeze({
-            ...props,
-            // The select statement (defined using the `as` method) can't have parameters on some
-            // dialects. We add the `ImmediateValuePlugin` to make all parameters "immediate"
-            // meaning they are interpolated into the SQL instead of added as parameters.
-            //
-            // The values are therefore not escaped at all, which leads to SQL injection
-            // vulnerabilities if user input is passed into the query. However, the use
-            // case where user input is passed into a `create view` statement is a weird
-            // one, and we can pretty safely just ignore it.
-            executor: props.executor.withPlugin(new ImmediateValuePlugin()),
+        this.#props = freeze(props);
+    }
+    /**
+     * Adds the "temporary" modifier.
+     *
+     * Use this to create a temporary view.
+     */
+    temporary() {
+        return new CreateViewBuilder({
+            ...this.#props,
+            createViewNode: CreateViewNode.cloneWith(this.#props.createViewNode, {
+                temporary: true,
+            }),
         });
     }
     materialized() {
@@ -55,11 +56,19 @@ export class CreateViewBuilder {
             }),
         });
     }
+    /**
+     * Sets the select query or a `values` statement that creates the view.
+     *
+     * WARNING!
+     * Some dialects don't support parameterized queries in DDL statements and therefore
+     * the query or `raw` expression passed here is interpolated into a single string
+     * opening an SQL injection vulnerability. DO NOT pass unchecked user input into
+     * the query or `raw` expression passed to this method!
+     */
     as(query) {
-        const queryNode = query.toOperationNode();
-        if (QueryNode.isMutating(queryNode)) {
-            throw new Error('only select statements are allowd in views');
-        }
+        const queryNode = query
+            .withPlugin(new ImmediateValuePlugin())
+            .toOperationNode();
         return new CreateViewBuilder({
             ...this.#props,
             createViewNode: CreateViewNode.cloneWith(this.#props.createViewNode, {

package/dist/esm/schema/schema.d.ts

@@ -17,7 +17,8 @@ export declare class SchemaModule {
     /**
      * Create a new table.
      *
-     * @example
+     * ### Examples
+     *
      * This example creates a new table with columns `id`, `first_name`,
      * `last_name` and `gender`:
      *
@@ -31,7 +32,6 @@ export declare class SchemaModule {
      *   .execute()
      * ```
      *
-     * @example
      * This example creates a table with a foreign key. Not all database
      * engines support column-level foreign key constraint definitions.
      * For example if you are using MySQL 5.X see the next example after
@@ -48,7 +48,6 @@ export declare class SchemaModule {
      *   .execute()
      * ```
      *
-     * @example
      * This example adds a foreign key constraint for a columns just
      * like the previous example, but using a table-level statement.
      * On MySQL 5.X you need to define foreign key constraints like
@@ -70,7 +69,8 @@ export declare class SchemaModule {
     /**
      * Drop a table.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .dropTable('person')
@@ -81,7 +81,8 @@ export declare class SchemaModule {
     /**
      * Create a new index.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .createIndex('person_full_name_unique_index')
@@ -94,7 +95,8 @@ export declare class SchemaModule {
     /**
      * Drop an index.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .dropIndex('person_full_name_unique_index')
@@ -105,7 +107,8 @@ export declare class SchemaModule {
     /**
      * Create a new schema.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .createSchema('some_schema')
@@ -116,7 +119,8 @@ export declare class SchemaModule {
     /**
      * Drop a schema.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .dropSchema('some_schema')
@@ -127,7 +131,8 @@ export declare class SchemaModule {
     /**
      * Alter a table.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .alterTable('person')
@@ -140,7 +145,8 @@ export declare class SchemaModule {
     /**
      * Create a new view.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .createView('dogs')
@@ -153,7 +159,8 @@ export declare class SchemaModule {
     /**
      * Drop a view.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .dropView('dogs')

package/dist/esm/schema/schema.js

@@ -30,7 +30,8 @@ export class SchemaModule {
     /**
      * Create a new table.
      *
-     * @example
+     * ### Examples
+     *
      * This example creates a new table with columns `id`, `first_name`,
      * `last_name` and `gender`:
      *
@@ -44,7 +45,6 @@ export class SchemaModule {
      *   .execute()
      * ```
      *
-     * @example
      * This example creates a table with a foreign key. Not all database
      * engines support column-level foreign key constraint definitions.
      * For example if you are using MySQL 5.X see the next example after
@@ -61,7 +61,6 @@ export class SchemaModule {
      *   .execute()
      * ```
      *
-     * @example
      * This example adds a foreign key constraint for a columns just
      * like the previous example, but using a table-level statement.
      * On MySQL 5.X you need to define foreign key constraints like
@@ -89,7 +88,8 @@ export class SchemaModule {
     /**
      * Drop a table.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .dropTable('person')
@@ -106,7 +106,8 @@ export class SchemaModule {
     /**
      * Create a new index.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .createIndex('person_full_name_unique_index')
@@ -125,7 +126,8 @@ export class SchemaModule {
     /**
      * Drop an index.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .dropIndex('person_full_name_unique_index')
@@ -142,7 +144,8 @@ export class SchemaModule {
     /**
      * Create a new schema.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .createSchema('some_schema')
@@ -159,7 +162,8 @@ export class SchemaModule {
     /**
      * Drop a schema.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .dropSchema('some_schema')
@@ -176,7 +180,8 @@ export class SchemaModule {
     /**
      * Alter a table.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .alterTable('person')
@@ -195,7 +200,8 @@ export class SchemaModule {
     /**
      * Create a new view.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .createView('dogs')
@@ -214,7 +220,8 @@ export class SchemaModule {
     /**
      * Drop a view.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db.schema
      *   .dropView('dogs')

package/dist/esm/util/dynamic-import.js

@@ -1,7 +1,7 @@
 import { isFunction, isObject } from './object-utils.js';
 export async function importFunction(modulePath) {
     const module = await import(modulePath);
-    const errorMessage = `module "${modulePath}" doesn export a function`;
+    const errorMessage = `module "${modulePath}" doesn't export a function`;
     if (isFunction(module)) {
         return module;
     }

package/dist/esm/util/log.d.ts

@@ -1,19 +1,22 @@
+import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { ArrayItemType } from './type-utils.js';
 export declare const LOG_LEVELS: readonly ["query", "error"];
 export declare type LogLevel = ArrayItemType<typeof LOG_LEVELS>;
-export declare class Log {
-    #private;
-    constructor(levels: ReadonlyArray<LogLevel>);
-    query(getEvent: () => QueryLogEvent): void;
-    error(getEvent: () => ErrorLogEvent): void;
-}
-export declare type LogEvent = QueryLogEvent | ErrorLogEvent;
 export interface QueryLogEvent {
     readonly level: 'query';
-    readonly sql: string;
+    readonly query: CompiledQuery;
     readonly queryDurationMillis: number;
 }
 export interface ErrorLogEvent {
     readonly level: 'error';
     readonly error: unknown;
 }
+export declare type LogEvent = QueryLogEvent | ErrorLogEvent;
+export declare type Logger = (event: LogEvent) => void;
+export declare type LogConfig = ReadonlyArray<LogLevel> | Logger;
+export declare class Log {
+    #private;
+    constructor(config: LogConfig);
+    query(getEvent: () => QueryLogEvent): void;
+    error(getEvent: () => ErrorLogEvent): void;
+}

package/dist/esm/util/log.js

@@ -1,28 +1,41 @@
-import { freeze } from './object-utils.js';
-export const LOG_LEVELS = ['query', 'error'];
+import { freeze, isFunction } from './object-utils.js';
+export const LOG_LEVELS = freeze(['query', 'error']);
 export class Log {
     #levels;
-    constructor(levels) {
-        this.#levels = freeze({
-            query: levels.includes('query'),
-            error: levels.includes('error'),
-        });
+    #logger;
+    constructor(config) {
+        if (isFunction(config)) {
+            this.#logger = config;
+            this.#levels = freeze({
+                query: true,
+                error: true,
+            });
+        }
+        else {
+            this.#logger = defaultLogger;
+            this.#levels = freeze({
+                query: config.includes('query'),
+                error: config.includes('error'),
+            });
+        }
     }
     query(getEvent) {
         if (this.#levels.query) {
-            this.#defaultQuery(getEvent());
+            this.#logger(getEvent());
         }
     }
     error(getEvent) {
         if (this.#levels.error) {
-            this.#defaultError(getEvent());
+            this.#logger(getEvent());
         }
     }
-    #defaultQuery(event) {
-        console.log(`kysely:query: ${event.sql}`);
+}
+function defaultLogger(event) {
+    if (event.level === 'query') {
+        console.log(`kysely:query: ${event.query.sql}`);
         console.log(`kysely:query: duration: ${event.queryDurationMillis.toFixed(1)}ms`);
     }
-    #defaultError(event) {
+    else if (event.level === 'error') {
         if (event.error instanceof Error) {
             console.error(`kysely:error: ${event.error.stack ?? event.error.message}`);
         }

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

@@ -1,5 +1,5 @@
 import { AliasedRawBuilder, RawBuilder } from '../raw-builder/raw-builder.js';
-import { AliasedQueryBuilder, QueryBuilder } from '../query-builder/query-builder.js';
+import { AliasedQueryBuilder, SelectQueryBuilder } from '../query-builder/select-query-builder.js';
 import { ExpressionBuilder } from '../query-builder/expression-builder.js';
 import { InsertResult } from '../query-builder/insert-result.js';
 import { DeleteResult } from '../query-builder/delete-result.js';
@@ -41,7 +41,7 @@ export declare type ValueType<T> = T[keyof T];
  */
 export declare type RowType<DB, TB extends keyof DB> = UnionToIntersection<DB[TB]>;
 /**
- * Evil typescript magic to convert a union type `A | B | C` into an
+ * Evil typescript magic to convert a union type `A | B | C` into an
  * intersection type `A & B & C`.
  */
 declare type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
@@ -73,12 +73,12 @@ declare type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) e
  *
  * type Columns = AnyColumn<Database, 'person' | 'pet'>
  *
- * // Columns == 'id' | 'name' | 'species'
+ * // Columns == 'id' | 'name' | 'species'
  * ```
  */
 export declare type AnyColumn<DB, TB extends keyof DB> = {
     [T in TB]: keyof DB[T];
-}[TB];
+}[TB] & string;
 /**
  * Given a database type and a union of table names in that db, returns
  * a union type with all possible `table`.`column` combinations.
@@ -107,7 +107,7 @@ export declare type AnyColumn<DB, TB extends keyof DB> = {
  *
  * type Columns = AnyColumn<Database, 'person' | 'pet'>
  *
- * // Columns == 'person.id' | 'pet.name' | 'pet.species'
+ * // Columns == 'person.id' | 'pet.name' | 'pet.species'
  * ```
  */
 export declare type AnyColumnWithTable<DB, TB extends keyof DB> = {
@@ -129,11 +129,11 @@ export declare type AnyAliasedColumnWithTable<DB, TB extends keyof DB> = {
  * Extracts the item type of an array.
  */
 export declare type ArrayItemType<T> = T extends ReadonlyArray<infer I> ? I : never;
-export declare type AnyQueryBuilder = QueryBuilder<any, any, any>;
+export declare type AnySelectQueryBuilder = SelectQueryBuilder<any, any, any>;
 export declare type AnyAliasedQueryBuilder = AliasedQueryBuilder<any, any, any, any>;
 export declare type AnyRawBuilder = RawBuilder<any>;
 export declare type AnyAliasedRawBuilder = AliasedRawBuilder<any, any>;
-export declare type QueryBuilderFactory<DB, TB extends keyof DB> = (qb: ExpressionBuilder<DB, TB>) => QueryBuilder<any, any, any>;
+export declare type SelectQueryBuilderFactory<DB, TB extends keyof DB> = (qb: ExpressionBuilder<DB, TB>) => AnySelectQueryBuilder;
 export declare type AliasedQueryBuilderFactory<DB, TB extends keyof DB> = (qb: ExpressionBuilder<DB, TB>) => AnyAliasedQueryBuilder;
 export declare type RawBuilderFactory<DB, TB extends keyof DB> = (qb: ExpressionBuilder<DB, TB>) => AnyRawBuilder;
 export declare type AliasedRawBuilderFactory<DB, TB extends keyof DB> = (qb: ExpressionBuilder<DB, TB>) => AnyAliasedRawBuilder;