kysely 0.18.0 → 0.19.1

package/dist/cjs/migration/migrator.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Migrator = exports.NO_MIGRATIONS = exports.MIGRATION_LOCK_ID = exports.MIGRATION_LOCK_TABLE = exports.MIGRATION_TABLE = void 0;
+exports.Migrator = exports.NO_MIGRATIONS = exports.MIGRATION_LOCK_ID = exports.DEFAULT_MIGRATION_LOCK_TABLE = exports.DEFAULT_MIGRATION_TABLE = void 0;
+const noop_plugin_js_1 = require("../plugin/noop-plugin.js");
+const with_schema_plugin_js_1 = require("../plugin/with-schema/with-schema-plugin.js");
 const object_utils_js_1 = require("../util/object-utils.js");
-exports.MIGRATION_TABLE = 'kysely_migration';
-exports.MIGRATION_LOCK_TABLE = 'kysely_migration_lock';
+exports.DEFAULT_MIGRATION_TABLE = 'kysely_migration';
+exports.DEFAULT_MIGRATION_LOCK_TABLE = 'kysely_migration_lock';
 exports.MIGRATION_LOCK_ID = 'migration_lock';
 exports.NO_MIGRATIONS = (0, object_utils_js_1.freeze)({ __noMigrations__: true });
 /**
@@ -37,9 +39,10 @@ class Migrator {
      * The returned array is sorted by migration name.
      */
     async getMigrations() {
-        const executedMigrations = (await this.#doesTableExists(exports.MIGRATION_TABLE))
+        const executedMigrations = (await this.#doesTableExists(this.#migrationTable))
             ? await this.#props.db
-                .selectFrom(exports.MIGRATION_TABLE)
+                .withPlugin(this.#schemaPlugin)
+                .selectFrom(this.#migrationTable)
                 .select(['name', 'timestamp'])
                 .execute()
             : [];
@@ -184,16 +187,61 @@ class Migrator {
             return { error };
         }
     }
+    get #migrationTableSchema() {
+        return this.#props.migrationTableSchema;
+    }
+    get #migrationTable() {
+        return this.#props.migrationTableName ?? exports.DEFAULT_MIGRATION_TABLE;
+    }
+    get #migrationLockTable() {
+        return this.#props.migrationLockTableName ?? exports.DEFAULT_MIGRATION_LOCK_TABLE;
+    }
+    get #schemaPlugin() {
+        if (this.#migrationTableSchema) {
+            return new with_schema_plugin_js_1.WithSchemaPlugin(this.#migrationTableSchema);
+        }
+        return new noop_plugin_js_1.NoopPlugin();
+    }
     async #ensureMigrationTablesExists() {
+        await this.#ensureMigrationTableSchemaExists();
         await this.#ensureMigrationTableExists();
         await this.#ensureMigrationLockTableExists();
         await this.#ensureLockRowExists();
     }
+    async #ensureMigrationTableSchemaExists() {
+        if (!this.#migrationTableSchema) {
+            // Use default schema. Nothing to do.
+            return;
+        }
+        if (!(await this.#doesSchemaExists())) {
+            try {
+                await this.#props.db.schema
+                    .createSchema(this.#migrationTableSchema)
+                    .ifNotExists()
+                    .execute();
+            }
+            catch (error) {
+                // At least on PostgreSQL, `if not exists` doesn't guarantee the `create schema`
+                // query doesn't throw if the schema already exits. That's why we check if
+                // the schema exist here and ignore the error if it does.
+                if (!(await this.#doesSchemaExists())) {
+                    throw error;
+                }
+            }
+        }
+    }
     async #ensureMigrationTableExists() {
-        if (!(await this.#doesTableExists(exports.MIGRATION_TABLE))) {
+        if (!(await this.#doesTableExists(this.#migrationTable))) {
             try {
+                if (this.#migrationTableSchema) {
+                    await this.#props.db.schema
+                        .createSchema(this.#migrationTableSchema)
+                        .ifNotExists()
+                        .execute();
+                }
                 await this.#props.db.schema
-                    .createTable(exports.MIGRATION_TABLE)
+                    .withPlugin(this.#schemaPlugin)
+                    .createTable(this.#migrationTable)
                     .ifNotExists()
                     .addColumn('name', 'varchar(255)', (col) => col.notNull().primaryKey())
                     // The migration run time as ISO string. This is not a real date type as we
@@ -205,17 +253,18 @@ class Migrator {
                 // At least on PostgreSQL, `if not exists` doesn't guarantee the `create table`
                 // query doesn't throw if the table already exits. That's why we check if
                 // the table exist here and ignore the error if it does.
-                if (!(await this.#doesTableExists(exports.MIGRATION_TABLE))) {
+                if (!(await this.#doesTableExists(this.#migrationTable))) {
                     throw error;
                 }
             }
         }
     }
     async #ensureMigrationLockTableExists() {
-        if (!(await this.#doesTableExists(exports.MIGRATION_LOCK_TABLE))) {
+        if (!(await this.#doesTableExists(this.#migrationLockTable))) {
             try {
                 await this.#props.db.schema
-                    .createTable(exports.MIGRATION_LOCK_TABLE)
+                    .withPlugin(this.#schemaPlugin)
+                    .createTable(this.#migrationLockTable)
                     .ifNotExists()
                     .addColumn('id', 'varchar(255)', (col) => col.notNull().primaryKey())
                     .addColumn('is_locked', 'integer', (col) => col.notNull().defaultTo(0))
@@ -225,7 +274,7 @@ class Migrator {
                 // At least on PostgreSQL, `if not exists` doesn't guarantee the `create table`
                 // query doesn't throw if the table already exits. That's why we check if
                 // the table exist here and ignore the error if it does.
-                if (!(await this.#doesTableExists(exports.MIGRATION_LOCK_TABLE))) {
+                if (!(await this.#doesTableExists(this.#migrationLockTable))) {
                     throw error;
                 }
             }
@@ -235,7 +284,8 @@ class Migrator {
         if (!(await this.#doesLockRowExists())) {
             try {
                 await this.#props.db
-                    .insertInto(exports.MIGRATION_LOCK_TABLE)
+                    .withPlugin(this.#schemaPlugin)
+                    .insertInto(this.#migrationLockTable)
                     .values({ id: exports.MIGRATION_LOCK_ID, is_locked: 0 })
                     .execute();
             }
@@ -246,15 +296,21 @@ class Migrator {
             }
         }
     }
+    async #doesSchemaExists() {
+        const schemas = await this.#props.db.introspection.getSchemas();
+        return schemas.some((it) => it.name === this.#migrationTableSchema);
+    }
     async #doesTableExists(tableName) {
-        const metadata = await this.#props.db.introspection.getMetadata({
+        const schema = this.#migrationTableSchema;
+        const tables = await this.#props.db.introspection.getTables({
             withInternalKyselyTables: true,
         });
-        return !!metadata.tables.find((it) => it.name === tableName);
+        return tables.some((it) => it.name === tableName && (!schema || it.schema === schema));
     }
     async #doesLockRowExists() {
         const lockRow = await this.#props.db
-            .selectFrom(exports.MIGRATION_LOCK_TABLE)
+            .withPlugin(this.#schemaPlugin)
+            .selectFrom(this.#migrationLockTable)
             .where('id', '=', exports.MIGRATION_LOCK_ID)
             .select('id')
             .executeTakeFirst();
@@ -312,7 +368,8 @@ class Migrator {
     }
     async #getExecutedMigrations(db) {
         const executedMigrations = await db
-            .selectFrom(exports.MIGRATION_TABLE)
+            .withPlugin(this.#schemaPlugin)
+            .selectFrom(this.#migrationTable)
             .select('name')
             .orderBy('name')
             .execute();
@@ -348,7 +405,8 @@ class Migrator {
                 if (migration.down) {
                     await migration.down(db);
                     await db
-                        .deleteFrom(exports.MIGRATION_TABLE)
+                        .withPlugin(this.#schemaPlugin)
+                        .deleteFrom(this.#migrationTable)
                         .where('name', '=', migration.name)
                         .execute();
                     results[i] = {
@@ -386,7 +444,8 @@ class Migrator {
             try {
                 await migration.up(db);
                 await db
-                    .insertInto(exports.MIGRATION_TABLE)
+                    .withPlugin(this.#schemaPlugin)
+                    .insertInto(this.#migrationTable)
                     .values({
                     name: migration.name,
                     timestamp: new Date().toISOString(),

package/dist/cjs/plugin/noop-plugin.d.ts

@@ -0,0 +1,42 @@
+import { QueryResult } from '../driver/database-connection.js';
+import { RootOperationNode } from '../query-compiler/query-compiler.js';
+import { UnknownRow } from '../util/type-utils.js';
+import { KyselyPlugin, PluginTransformQueryArgs, PluginTransformResultArgs } from './kysely-plugin.js';
+export declare class NoopPlugin implements KyselyPlugin {
+    /**
+     * This is called for each query before it is executed. You can modify the query by
+     * transforming its {@link OperationNode} tree provided in {@link PluginTransformQueryArgs.node | args.node}
+     * and returning the transformed tree. You'd usually want to use an {@link OperationNodeTransformer}
+     * for this.
+     *
+     * If you need to pass some query-related data between this method and `transformResult` you
+     * can use a `WeakMap` with {@link PluginTransformQueryArgs.queryId | args.queryId} as the key:
+     *
+     * ```ts
+     * const plugin = {
+     *   data: new WeakMap<QueryId, SomeData>(),
+     *
+     *   transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
+     *     this.data.set(args.queryId, something)
+     *     return args.node
+     *   },
+     *
+     *   transformResult(args: PluginTransformResultArgs): QueryResult<UnknownRow> {
+     *     const data = this.data.get(args.queryId)
+     *     return args.result
+     *   }
+     * }
+     * ```
+     *
+     * You should use a `WeakMap` instead of a `Map` or some other strong references because `transformQuery`
+     * is not always matched by a call to `transformResult` which would leave orphaned items in the map
+     * and cause a memory leak.
+     */
+    transformQuery(args: PluginTransformQueryArgs): RootOperationNode;
+    /**
+     * This method is called for each query after it has been executed. The result
+     * of the query can be accessed through {@link PluginTransformResultArgs.result | args.result}.
+     * You can modify the result and return the modifier result.
+     */
+    transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>>;
+}

package/dist/cjs/plugin/noop-plugin.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoopPlugin = void 0;
+class NoopPlugin {
+    transformQuery(args) {
+        return args.node;
+    }
+    async transformResult(args) {
+        return args.result;
+    }
+}
+exports.NoopPlugin = NoopPlugin;

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

@@ -9,6 +9,7 @@ import { WithNode } from './operation-node/with-node.js';
 import { InsertResult } from './query-builder/insert-result.js';
 import { DeleteResult } from './query-builder/delete-result.js';
 import { UpdateResult } from './query-builder/update-result.js';
+import { KyselyPlugin } from './plugin/kysely-plugin.js';
 export declare class QueryCreator<DB> {
     #private;
     constructor(props: QueryCreatorProps);
@@ -252,6 +253,14 @@ export declare class QueryCreator<DB> {
      * See the {@link with} method for examples and more documentation.
      */
     withRecursive<N extends string, E extends RecursiveCommonTableExpression<DB, N>>(name: N, expression: E): QueryCreatorWithCommonTableExpression<DB, N, E>;
+    /**
+     * Returns a copy of this query creator instance with the given plugin installed.
+     */
+    withPlugin(plugin: KyselyPlugin): QueryCreator<DB>;
+    /**
+     * Returns a copy of this query creator instance without any plugins.
+     */
+    withoutPlugins(): QueryCreator<DB>;
     /**
      * Sets the schema to be used for all table references that don't explicitly
      * specify a schema.

package/dist/cjs/query-creator.js

@@ -192,6 +192,24 @@ class QueryCreator {
                 : with_node_js_1.WithNode.create(cte, { recursive: true }),
         });
     }
+    /**
+     * Returns a copy of this query creator instance with the given plugin installed.
+     */
+    withPlugin(plugin) {
+        return new QueryCreator({
+            ...this.#props,
+            executor: this.#props.executor.withPlugin(plugin),
+        });
+    }
+    /**
+     * Returns a copy of this query creator instance without any plugins.
+     */
+    withoutPlugins() {
+        return new QueryCreator({
+            ...this.#props,
+            executor: this.#props.executor.withoutPlugins(),
+        });
+    }
     /**
      * Sets the schema to be used for all table references that don't explicitly
      * specify a schema.

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

@@ -25,12 +25,8 @@ export declare class AlterTableBuilder {
     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;
+    addColumn(columnName: string, dataType: DataTypeExpression, build?: AlterTableAddColumnBuilderCallback): AlterTableAddColumnBuilder;
     /**
      * Creates an `alter table modify column` query. The `modify column` statement
      * is only implemeted by MySQL and oracle AFAIK. On other databases you
@@ -245,6 +241,7 @@ export declare class AlterTableAddColumnBuilder implements ColumnDefinitionBuild
 export interface AlterTableAddColumnBuilderProps extends AlterTableBuilderProps {
     readonly columnBuilder: ColumnDefinitionBuilder;
 }
+export declare type AlterTableAddColumnBuilderCallback = (builder: AlterTableAddColumnBuilder) => AlterTableAddColumnBuilder;
 export declare class AlterTableModifyColumnBuilder implements ColumnDefinitionBuilderInterface, OperationNodeSource, Compilable {
     #private;
     constructor(props: AlterTableModifyColumnBuilderProps);

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

@@ -70,16 +70,12 @@ 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({
+    addColumn(columnName, dataType, build = object_utils_js_1.noop) {
+        return build(new AlterTableAddColumnBuilder({
             ...this.#props,
             columnBuilder: new column_definition_builder_js_1.ColumnDefinitionBuilder(column_definition_node_js_1.ColumnDefinitionNode.create(columnName, (0, data_type_parser_js_1.parseDataTypeExpression)(dataType))),
-        });
+        }));
     }
     /**
      * Creates an `alter table modify column` query. The `modify column` statement

package/dist/cjs/schema/schema.d.ts

@@ -8,6 +8,7 @@ import { DropSchemaBuilder } from './drop-schema-builder.js';
 import { DropTableBuilder } from './drop-table-builder.js';
 import { CreateViewBuilder } from './create-view-builder.js';
 import { DropViewBuilder } from './drop-view-builder.js';
+import { KyselyPlugin } from '../plugin/kysely-plugin.js';
 /**
  * Provides methods for building database schema.
  */
@@ -169,6 +170,14 @@ export declare class SchemaModule {
      * ```
      */
     dropView(viewName: string): DropViewBuilder;
+    /**
+     * Returns a copy of this schema module with the given plugin installed.
+     */
+    withPlugin(plugin: KyselyPlugin): SchemaModule;
+    /**
+     * Returns a copy of this schema module  without any plugins.
+     */
+    withoutPlugins(): SchemaModule;
     /**
      * See {@link QueryCreator.withSchema}
      */

package/dist/cjs/schema/schema.js

@@ -239,6 +239,18 @@ class SchemaModule {
             dropViewNode: drop_view_node_js_1.DropViewNode.create(viewName),
         });
     }
+    /**
+     * Returns a copy of this schema module with the given plugin installed.
+     */
+    withPlugin(plugin) {
+        return new SchemaModule(this.#executor.withPlugin(plugin));
+    }
+    /**
+     * Returns a copy of this schema module  without any plugins.
+     */
+    withoutPlugins() {
+        return new SchemaModule(this.#executor.withoutPlugins());
+    }
     /**
      * See {@link QueryCreator.withSchema}
      */

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

@@ -43,13 +43,21 @@ export declare type ColumnType<SelectType, InsertType = SelectType, UpdateType =
  * is the same for all selects, inserts and updates but the
  * column is optional for inserts and updates.
  *
- * This is implemented using {@link ColumnType} like this:
+ * The implementation:
  *
  * ```ts
+ * // The update type is `S` instead of `S | undefined` because
+ * // updates are always optional --> no need to specify optionality.
  * type Generated<S> = ColumnType<S, S | undefined, S>
  * ```
  */
 export declare type Generated<S> = ColumnType<S, S | undefined, S>;
+/**
+ * A shortcut for defining columns that are only database-generated
+ * (like postgres GENERATED ALWAYS AS IDENTITY). No insert/update
+ * is allowed.
+ */
+export declare type GeneratedAlways<S> = ColumnType<S, never, never>;
 /**
  * Evaluates to `K` if `T` can be `null` or `undefined`.
  */

package/dist/cjs/util/stack-trace-utils.d.ts

@@ -0,0 +1 @@
+export declare function extendStackTrace(err: unknown, stackError: Error): unknown;

package/dist/cjs/util/stack-trace-utils.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extendStackTrace = void 0;
+const object_utils_js_1 = require("./object-utils.js");
+function extendStackTrace(err, stackError) {
+    if (isStackHolder(err) && stackError.stack) {
+        // Remove the first line that just says `Error`.
+        const stackExtension = stackError.stack.split('\n').slice(1).join('\n');
+        err.stack += `\n${stackExtension}`;
+        return err;
+    }
+    return err;
+}
+exports.extendStackTrace = extendStackTrace;
+function isStackHolder(obj) {
+    return (0, object_utils_js_1.isObject)(obj) && (0, object_utils_js_1.isString)(obj.stack);
+}

package/dist/esm/dialect/database-introspector.d.ts

@@ -3,8 +3,18 @@ import { ColumnDataType } from '../operation-node/data-type-node.js';
  * An interface for getting the database metadata (names of the tables and columns etc.)
  */
 export interface DatabaseIntrospector {
+    /**
+     * Get schema metadata.
+     */
+    getSchemas(): Promise<SchemaMetadata[]>;
+    /**
+     * Get table metadata.
+     */
+    getTables(options?: DatabaseMetadataOptions): Promise<TableMetadata[]>;
     /**
      * Get the database metadata such as table and column names.
+     *
+     * @deprecated Use getTables() instead.
      */
     getMetadata(options?: DatabaseMetadataOptions): Promise<DatabaseMetadata>;
 }
@@ -15,6 +25,9 @@ export interface DatabaseMetadataOptions {
      */
     withInternalKyselyTables: boolean;
 }
+export interface SchemaMetadata {
+    readonly name: string;
+}
 export interface DatabaseMetadata {
     /**
      * The tables found in the database.