kysely 0.18.0 → 0.18.1

package/dist/esm/migration/migrator.js

@@ -1,7 +1,9 @@
 /// <reference types="./migrator.d.ts" />
+import { NoopPlugin } from '../plugin/noop-plugin.js';
+import { WithSchemaPlugin } from '../plugin/with-schema/with-schema-plugin.js';
 import { freeze, getLast } from '../util/object-utils.js';
-export const MIGRATION_TABLE = 'kysely_migration';
-export const MIGRATION_LOCK_TABLE = 'kysely_migration_lock';
+export const DEFAULT_MIGRATION_TABLE = 'kysely_migration';
+export const DEFAULT_MIGRATION_LOCK_TABLE = 'kysely_migration_lock';
 export const MIGRATION_LOCK_ID = 'migration_lock';
 export const NO_MIGRATIONS = freeze({ __noMigrations__: true });
 /**
@@ -35,9 +37,10 @@ export class Migrator {
      * The returned array is sorted by migration name.
      */
     async getMigrations() {
-        const executedMigrations = (await this.#doesTableExists(MIGRATION_TABLE))
+        const executedMigrations = (await this.#doesTableExists(this.#migrationTable))
             ? await this.#props.db
-                .selectFrom(MIGRATION_TABLE)
+                .withPlugin(this.#schemaPlugin)
+                .selectFrom(this.#migrationTable)
                 .select(['name', 'timestamp'])
                 .execute()
             : [];
@@ -182,16 +185,61 @@ export class Migrator {
             return { error };
         }
     }
+    get #migrationTableSchema() {
+        return this.#props.migrationTableSchema;
+    }
+    get #migrationTable() {
+        return this.#props.migrationTableName ?? DEFAULT_MIGRATION_TABLE;
+    }
+    get #migrationLockTable() {
+        return this.#props.migrationLockTableName ?? DEFAULT_MIGRATION_LOCK_TABLE;
+    }
+    get #schemaPlugin() {
+        if (this.#migrationTableSchema) {
+            return new WithSchemaPlugin(this.#migrationTableSchema);
+        }
+        return new 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(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(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
@@ -203,17 +251,18 @@ export 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(MIGRATION_TABLE))) {
+                if (!(await this.#doesTableExists(this.#migrationTable))) {
                     throw error;
                 }
             }
         }
     }
     async #ensureMigrationLockTableExists() {
-        if (!(await this.#doesTableExists(MIGRATION_LOCK_TABLE))) {
+        if (!(await this.#doesTableExists(this.#migrationLockTable))) {
             try {
                 await this.#props.db.schema
-                    .createTable(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))
@@ -223,7 +272,7 @@ export 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(MIGRATION_LOCK_TABLE))) {
+                if (!(await this.#doesTableExists(this.#migrationLockTable))) {
                     throw error;
                 }
             }
@@ -233,7 +282,8 @@ export class Migrator {
         if (!(await this.#doesLockRowExists())) {
             try {
                 await this.#props.db
-                    .insertInto(MIGRATION_LOCK_TABLE)
+                    .withPlugin(this.#schemaPlugin)
+                    .insertInto(this.#migrationLockTable)
                     .values({ id: MIGRATION_LOCK_ID, is_locked: 0 })
                     .execute();
             }
@@ -244,15 +294,21 @@ export 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(MIGRATION_LOCK_TABLE)
+            .withPlugin(this.#schemaPlugin)
+            .selectFrom(this.#migrationLockTable)
             .where('id', '=', MIGRATION_LOCK_ID)
             .select('id')
             .executeTakeFirst();
@@ -310,7 +366,8 @@ export class Migrator {
     }
     async #getExecutedMigrations(db) {
         const executedMigrations = await db
-            .selectFrom(MIGRATION_TABLE)
+            .withPlugin(this.#schemaPlugin)
+            .selectFrom(this.#migrationTable)
             .select('name')
             .orderBy('name')
             .execute();
@@ -346,7 +403,8 @@ export class Migrator {
                 if (migration.down) {
                     await migration.down(db);
                     await db
-                        .deleteFrom(MIGRATION_TABLE)
+                        .withPlugin(this.#schemaPlugin)
+                        .deleteFrom(this.#migrationTable)
                         .where('name', '=', migration.name)
                         .execute();
                     results[i] = {
@@ -384,7 +442,8 @@ export class Migrator {
             try {
                 await migration.up(db);
                 await db
-                    .insertInto(MIGRATION_TABLE)
+                    .withPlugin(this.#schemaPlugin)
+                    .insertInto(this.#migrationTable)
                     .values({
                     name: migration.name,
                     timestamp: new Date().toISOString(),

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

@@ -0,0 +1,42 @@
+import { QueryResult } from '../driver/database-connection.js';
+import { UnknownRow } from '../index-nodeless.js';
+import { RootOperationNode } from '../query-compiler/query-compiler.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/esm/plugin/noop-plugin.js

@@ -0,0 +1,9 @@
+/// <reference types="./noop-plugin.d.ts" />
+export class NoopPlugin {
+    transformQuery(args) {
+        return args.node;
+    }
+    async transformResult(args) {
+        return args.result;
+    }
+}

package/dist/esm/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/esm/query-creator.js

@@ -190,6 +190,24 @@ export class QueryCreator {
                 : 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/esm/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/esm/schema/schema.js

@@ -237,6 +237,18 @@ export class SchemaModule {
             dropViewNode: 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/esm/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/esm/util/stack-trace-utils.d.ts

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

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

@@ -0,0 +1,14 @@
+/// <reference types="./stack-trace-utils.d.ts" />
+import { isObject, isString } from './object-utils.js';
+export 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;
+}
+function isStackHolder(obj) {
+    return isObject(obj) && isString(obj.stack);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "Type safe SQL query builder",
   "repository": {
     "type": "git",
@@ -48,21 +48,21 @@
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.5.0",
-    "@types/chai": "^4.3.0",
+    "@types/chai": "^4.3.1",
     "@types/chai-subset": "^1.3.3",
     "@types/mocha": "^9.1.0",
     "@types/pg": "^8.6.5",
-    "better-sqlite3": "^7.5.0",
+    "better-sqlite3": "^7.5.1",
     "chai": "^4.3.6",
     "chai-subset": "^1.6.0",
-    "esbuild": "^0.14.27",
+    "esbuild": "^0.14.36",
     "mocha": "^9.2.2",
     "mysql2": "^2.3.3",
     "pg": "^8.7.3",
-    "playwright": "^1.20.0",
-    "prettier": "^2.6.0",
-    "tsd": "^0.19.1",
-    "typedoc": "^0.22.13",
-    "typescript": "4.6.2"
+    "playwright": "^1.21.0",
+    "prettier": "^2.6.2",
+    "tsd": "^0.20.0",
+    "typedoc": "^0.22.15",
+    "typescript": "4.6.3"
   }
 }