kysely 0.12.0 → 0.12.1

package/dist/esm/dialect/sqlite/sqlite-adapter.d.ts

@@ -1,7 +1,43 @@
 import { DialectAdapter } from '../dialect-adapter.js';
 export declare class SqliteAdapter implements DialectAdapter {
+    /**
+     * Whether or not this dialect supports transactional DDL.
+     *
+     * If this is true, migrations are executed inside a transaction.
+     */
     get supportsTransactionalDdl(): boolean;
+    /**
+     * Whether or not this dialect supports the `returning` in inserts
+     * updates and deletes.
+     */
     get supportsReturning(): boolean;
+    /**
+     * This method is used to acquire a lock for the migrations so that
+     * it's not possible for two migration processes to run in parallel.
+     *
+     * Most dialects have explicit locks that can be used, like advisory locks
+     * in PostgreSQL and the get_lock function in MySQL.
+     *
+     * If the dialect doesn't have explicit locks the {@link MIGRATION_LOCK_TABLE}
+     * created by Kysely can be used instead. {@link MIGRATION_LOCK_TABLE}
+     * has two columns `id` and `is_locked` and there's only one row in the
+     * table whose id is {@link MIGRATION_LOCK_ID}. `is_locked` is an integer.
+     * Kysely takes care of creating the lock table and inserting the one single
+     * row to it before this method is executed.
+     *
+     * If `supportsTransactionalDdl` is `true` then the `db` passed to this method
+     * is a transaction inside which the migrations will be executed. Otherwise
+     * `db` is a single connection (session) that will be used to execute the
+     * migrations.
+     */
     acquireMigrationLock(): Promise<void>;
+    /**
+     * Releases the migration lock. See {@link acquireMigrationLock}.
+     *
+     * If `supportsTransactionalDdl` is `true` then the `db` passed to this method
+     * is a transaction inside which the migrations were executed. Otherwise `db`
+     * is a single connection (session) that was used to execute the migrations
+     * and the `acquireMigrationLock` call.
+     */
     releaseMigrationLock(): Promise<void>;
 }

package/dist/esm/dialect/sqlite/sqlite-dialect.d.ts

@@ -15,9 +15,25 @@ import { DatabaseConnection } from '../../driver/database-connection.js';
 export declare class SqliteDialect implements Dialect {
     #private;
     constructor(config: SqliteDialectConfig);
+    /**
+     * Creates a driver for the dialect.
+     */
     createDriver(): Driver;
+    /**
+     * Creates a query compiler for the dialect.
+     */
     createQueryCompiler(): QueryCompiler;
+    /**
+     * Creates an adapter for the dialect.
+     */
     createAdapter(): DialectAdapter;
+    /**
+     * Creates a database introspector that can be used to get the database metadata
+     * such as the tables and columns that exist in the database.
+     *
+     * `db` never has any plugins installed. It's created using
+     * {@link Kysely.withoutPlugins}.
+     */
     createIntrospector(db: Kysely<any>): DatabaseIntrospector;
 }
 /**

package/dist/esm/dialect/sqlite/sqlite-driver.d.ts

@@ -4,11 +4,40 @@ import { SqliteDialectConfig } from './sqlite-dialect.js';
 export declare class SqliteDriver implements Driver {
     #private;
     constructor(config: SqliteDialectConfig);
+    /**
+     * Initializes the driver.
+     *
+     * After calling this method the driver should be usable and `acquireConnection` etc.
+     * methods should be callable.
+     *
+     * IMPORTANT: The underlying database engine driver (like [pg](https://node-postgres.com/))
+     * should be imported inside this function, not at the top of the driver file! This is
+     * important so that Kysely is usable without installing all database driver libraries
+     * it supports.
+     */
     init(): Promise<void>;
+    /**
+     * Acquires a new connection from the pool.
+     */
     acquireConnection(): Promise<DatabaseConnection>;
+    /**
+     * Begins a transaction.
+     */
     beginTransaction(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Commits a transaction.
+     */
     commitTransaction(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Rolls back a transaction.
+     */
     rollbackTransaction(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Releases a connection back to the pool.
+     */
     releaseConnection(): Promise<void>;
+    /**
+     * Destroys the driver and releases all resources.
+     */
     destroy(): Promise<void>;
 }

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

@@ -3,5 +3,8 @@ import { Kysely } from '../../kysely.js';
 export declare class SqliteIntrospector implements DatabaseIntrospector {
     #private;
     constructor(db: Kysely<any>);
+    /**
+     * Get the database metadata such as the names of the tables and columns.
+     */
     getMetadata(options?: DatabaseMetadataOptions): Promise<DatabaseMetadata>;
 }

package/dist/esm/driver/default-connection-provider.d.ts

@@ -4,5 +4,9 @@ import { Driver } from './driver.js';
 export declare class DefaultConnectionProvider implements ConnectionProvider {
     #private;
     constructor(driver: Driver);
+    /**
+     * Provides a connection for the callback and takes care of disposing
+     * the connection after the callback has been run.
+     */
     withConnection<T>(runner: (connection: DatabaseConnection) => Promise<T>): Promise<T>;
 }

package/dist/esm/driver/runtime-driver.d.ts

@@ -9,11 +9,40 @@ import { Driver, TransactionSettings } from './driver.js';
 export declare class RuntimeDriver implements Driver {
     #private;
     constructor(driver: Driver, log: Log);
+    /**
+     * Initializes the driver.
+     *
+     * After calling this method the driver should be usable and `acquireConnection` etc.
+     * methods should be callable.
+     *
+     * IMPORTANT: The underlying database engine driver (like [pg](https://node-postgres.com/))
+     * should be imported inside this function, not at the top of the driver file! This is
+     * important so that Kysely is usable without installing all database driver libraries
+     * it supports.
+     */
     init(): Promise<void>;
+    /**
+     * Acquires a new connection from the pool.
+     */
     acquireConnection(): Promise<DatabaseConnection>;
+    /**
+     * Releases a connection back to the pool.
+     */
     releaseConnection(runtimeConnection: DatabaseConnection): Promise<void>;
+    /**
+     * Begins a transaction.
+     */
     beginTransaction(connection: DatabaseConnection, settings: TransactionSettings): Promise<void>;
+    /**
+     * Commits a transaction.
+     */
     commitTransaction(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Rolls back a transaction.
+     */
     rollbackTransaction(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Destroys the driver and releases all resources.
+     */
     destroy(): Promise<void>;
 }

package/dist/esm/driver/single-connection-provider.d.ts

@@ -3,5 +3,9 @@ import { ConnectionProvider } from './connection-provider.js';
 export declare class SingleConnectionProvider implements ConnectionProvider {
     #private;
     constructor(connection: DatabaseConnection);
+    /**
+     * Provides a connection for the callback and takes care of disposing
+     * the connection after the callback has been run.
+     */
     withConnection<T>(runner: (connection: DatabaseConnection) => Promise<T>): Promise<T>;
 }

package/dist/esm/package.json

@@ -1,3 +1 @@
-{
-    "type": "module"
-}
+{"type":"module"}

package/dist/esm/parser/parse-context.d.ts

@@ -34,8 +34,22 @@ export declare class DefaultParseContext implements ParseContext {
     #private;
     constructor(adapter: DialectAdapter);
     get adapter(): DialectAdapter;
+    /**
+     * Creates a select query builder with a {@link NoopQueryExecutor}.
+     */
     createSelectQueryBuilder(): SelectQueryBuilder<any, any, any>;
+    /**
+     * Creates an expression builder for building stuff like subqueries.
+     * {@link NoopQueryExecutor} is used as the executor and the queries
+     * built using the returned builder can never be executed.
+     */
     createExpressionBuilder(): ExpressionBuilder<any, any>;
+    /**
+     * Creates a query creator with a {@link NoopQueryExecutor}.
+     */
     createQueryCreator(): QueryCreator<any>;
+    /**
+     * Creates an instance of a join builder.
+     */
     createJoinBuilder(joinType: JoinType, table: TableExpression<any, any>): JoinBuilder<any, any>;
 }

package/dist/esm/plugin/camel-case/camel-case-plugin.d.ts

@@ -94,7 +94,41 @@ export interface CamelCasePluginOptions {
 export declare class CamelCasePlugin implements KyselyPlugin {
     #private;
     constructor(opt?: CamelCasePluginOptions);
+    /**
+     * 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>>;
     protected mapRow(row: UnknownRow): UnknownRow;
     protected snakeCase(str: string): string;

package/dist/esm/plugin/immediate-value.ts/immediate-value-plugin.d.ts

@@ -12,6 +12,40 @@ import { KyselyPlugin, PluginTransformQueryArgs, PluginTransformResultArgs } fro
  */
 export declare class ImmediateValuePlugin implements KyselyPlugin {
     #private;
+    /**
+     * 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/with-schema/with-schema-plugin.d.ts

@@ -5,6 +5,40 @@ import { UnknownRow } from '../../util/type-utils.js';
 export declare class WithSchemaPlugin implements KyselyPlugin {
     #private;
     constructor(schema: string);
+    /**
+     * 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>>;
 }