kysely 0.11.4 → 0.13.0

package/dist/cjs/dynamic/dynamic.js

@@ -23,7 +23,8 @@ class DynamicModule {
      * `ref` to other methods as well. If the types allow you to pass a `ref`
      * value to some place, it should work.
      *
-     * @example
+     * ### Examples
+     *
      * Filter by a column not know at compile time:
      *
      * ```ts
@@ -41,7 +42,6 @@ class DynamicModule {
      * someQuery('person.last_name', 'Aniston')
      * ```
      *
-     * @example
      * Order by a column not know at compile time:
      *
      * ```ts
@@ -58,7 +58,6 @@ class DynamicModule {
      * someQuery('fn')
      * ```
      *
-     * @example
      * In this example we add selections dynamically:
      *
      * ```ts
@@ -69,7 +68,7 @@ class DynamicModule {
      *
      * // A type that lists all possible values `columnFromUserInput` can have.
      * // You can use `keyof Person` if any column of an interface is allowed.
-     * type PossibleColumns = 'last_name' | 'first_name' | 'birth_date'
+     * type PossibleColumns = 'last_name' | 'first_name' | 'birth_date'
      *
      * const [person] = await db.selectFrom('person')
      *   .select([
@@ -81,9 +80,9 @@ class DynamicModule {
      * // The resulting type contains all `PossibleColumns` as optional fields
      * // because we cannot know which field was actually selected before
      * // running the code.
-     * const lastName: string | undefined = person.last_name
-     * const firstName: string | undefined = person.first_name
-     * const birthDate: string | undefined = person.birth_date
+     * const lastName: string | undefined = person.last_name
+     * const firstName: string | undefined = person.first_name
+     * const birthDate: string | undefined = person.birth_date
      *
      * // The result type also contains the compile time selection `id`.
      * person.id

package/dist/cjs/index.d.ts

@@ -1,8 +1,17 @@
 export * from './kysely.js';
 export * from './query-creator.js';
-export * from './query-builder/query-builder.js';
+export * from './query-builder/where-interface.js';
+export * from './query-builder/join-interface.js';
+export * from './query-builder/returning-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';
+export * from './query-builder/update-query-builder.js';
+export * from './query-builder/delete-query-builder.js';
+export * from './query-builder/no-result-error.js';
 export * from './query-builder/join-builder.js';
 export * from './query-builder/expression-builder.js';
+export * from './query-builder/function-builder.js';
 export * from './query-builder/insert-result.js';
 export * from './query-builder/delete-result.js';
 export * from './query-builder/update-result.js';
@@ -64,6 +73,7 @@ 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/constraint-node.js';
 export * from './operation-node/create-index-node.js';
 export * from './operation-node/create-schema-node.js';
@@ -123,16 +133,17 @@ export * from './operation-node/unique-constraint-node.js';
 export * from './operation-node/update-query-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/where-node.js';
 export * from './operation-node/with-node.js';
 export * from './introspection/database-introspector.js';
 export * from './util/compilable.js';
 export * from './util/log.js';
-export { AnyColumn, UnknownRow, AnyQueryBuilder } from './util/type-utils.js';
-export { SelectExpression, SelectExpressionOrList, } from './parser/select-parser.js';
+export { AnyColumn, UnknownRow, AnySelectQueryBuilder, } from './util/type-utils.js';
+export { SelectExpression, SelectExpressionOrList, Selection, } from './parser/select-parser.js';
 export { ReferenceExpression, ReferenceExpressionOrList, } from './parser/reference-parser.js';
 export { ValueExpression, ValueExpressionOrList, } from './parser/value-parser.js';
-export { ExistsExpression, FilterOperator } from './parser/filter-parser.js';
+export { FilterValueExpression, FilterValueExpressionOrList, ExistsExpression, FilterOperator, } from './parser/filter-parser.js';
 export { TableExpression, TableExpressionOrList, } from './parser/table-parser.js';
 export { JoinReferenceExpression, JoinCallbackExpression, } from './parser/join-parser.js';
 export { InsertObject } from './parser/insert-values-parser.js';

package/dist/cjs/index.js

@@ -12,9 +12,18 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./kysely.js"), exports);
 __exportStar(require("./query-creator.js"), exports);
-__exportStar(require("./query-builder/query-builder.js"), exports);
+__exportStar(require("./query-builder/where-interface.js"), exports);
+__exportStar(require("./query-builder/join-interface.js"), exports);
+__exportStar(require("./query-builder/returning-interface.js"), exports);
+__exportStar(require("./query-builder/having-interface.js"), exports);
+__exportStar(require("./query-builder/select-query-builder.js"), exports);
+__exportStar(require("./query-builder/insert-query-builder.js"), exports);
+__exportStar(require("./query-builder/update-query-builder.js"), exports);
+__exportStar(require("./query-builder/delete-query-builder.js"), exports);
+__exportStar(require("./query-builder/no-result-error.js"), exports);
 __exportStar(require("./query-builder/join-builder.js"), exports);
 __exportStar(require("./query-builder/expression-builder.js"), exports);
+__exportStar(require("./query-builder/function-builder.js"), exports);
 __exportStar(require("./query-builder/insert-result.js"), exports);
 __exportStar(require("./query-builder/delete-result.js"), exports);
 __exportStar(require("./query-builder/update-result.js"), exports);
@@ -76,6 +85,7 @@ __exportStar(require("./operation-node/column-definition-node.js"), exports);
 __exportStar(require("./operation-node/column-node.js"), exports);
 __exportStar(require("./operation-node/column-update-node.js"), exports);
 __exportStar(require("./operation-node/common-table-expression-node.js"), exports);
+__exportStar(require("./operation-node/common-table-expression-name-node.js"), exports);
 __exportStar(require("./operation-node/constraint-node.js"), exports);
 __exportStar(require("./operation-node/create-index-node.js"), exports);
 __exportStar(require("./operation-node/create-schema-node.js"), exports);
@@ -135,6 +145,7 @@ __exportStar(require("./operation-node/unique-constraint-node.js"), exports);
 __exportStar(require("./operation-node/update-query-node.js"), exports);
 __exportStar(require("./operation-node/value-list-node.js"), exports);
 __exportStar(require("./operation-node/value-node.js"), exports);
+__exportStar(require("./operation-node/values-node.js"), exports);
 __exportStar(require("./operation-node/where-node.js"), exports);
 __exportStar(require("./operation-node/with-node.js"), exports);
 __exportStar(require("./introspection/database-introspector.js"), exports);

package/dist/cjs/kysely.d.ts

@@ -17,7 +17,8 @@ import { LogConfig } from './util/log.js';
  * You should create one instance of `Kysely` per database using the {@link Kysely}
  * constructor. Each `Kysely` instance maintains it's own connection pool.
  *
- * @example
+ * ### Examples
+ *
  * This example assumes your database has tables `person` and `pet`:
  *
  * ```ts
@@ -31,7 +32,7 @@ import { LogConfig } from './util/log.js';
  *   id: number
  *   owner_id: number
  *   name: string
- *   species 'cat' | 'dog'
+ *   species 'cat' | 'dog'
  * }
  *
  * interface Database {
@@ -78,10 +79,11 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
      * A value to be used in place of columns that are generated in the database
      * when inserting rows.
      *
-     * @example
+     * ### Examples
+     *
      * In this example the `Person` table has non-null properties `id` and `created_at`
      * which are both automatically genereted by the database. Since their types are
-     * `number` and `string` respectively instead of `number | null` and `string | null`
+     * `number` and `string` respectively instead of `number | null` and `string | null`
      * the `values` method requires you to give a value for them. the `generated`
      * placeholder can be used in these cases.
      *
@@ -136,12 +138,13 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
      * transaction. If the function throws, the transaction is rolled back. Otherwise
      * the transaction is committed.
      *
-     * The callback function passed to the {@link TransactionBuilder.execute | execute}
+     * The callback function passed to the {@link TransactionBuilder.execute | execute}
      * method gets the transaction object as its only argument. The transaction is
      * of type {@link Transaction} which inherits {@link Kysely}. Any query
      * started through the transaction object is executed inside the transaction.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * const catto = await db.transaction().execute(async (trx) => {
      *   const jennifer = await trx.insertInto('person')
@@ -167,8 +170,7 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
      * })
      * ```
      *
-     * @example
-     * Setting the isolation level.
+     * Setting the isolation level:
      *
      * ```ts
      * await db
@@ -183,7 +185,8 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
     /**
      * Provides a kysely instance bound to a single database connection.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db
      *   .connection()
@@ -204,6 +207,38 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
      * Returns a copy of this Kysely instance without any plugins.
      */
     withoutPlugins(): Kysely<DB>;
+    /**
+     * Returns a copy of this Kysely instance with tables added to its
+     * database type.
+     *
+     * This method only modifies the types and doesn't affect any of the
+     * executed queries in any way.
+     *
+     * ### Examples
+     *
+     * The following example adds and uses a temporary table:
+     *
+     * @example
+     * ```ts
+     * await db.schema
+     *   .createTable('temp_table')
+     *   .temporary()
+     *   .addColumn('some_column', 'integer')
+     *   .execute()
+     *
+     * const tempDb = db.withTables<{
+     *   temp_table: {
+     *     some_column: number
+     *   }
+     * }>()
+     *
+     * await tempDb
+     *   .insertInto('temp_table')
+     *   .values({ some_column: 100 })
+     *   .execute()
+     * ```
+     */
+    withTables<T extends Record<string, Record<string, any>>>(): Kysely<DB & T>;
     /**
      * Releases all resources and disconnects from the database.
      *
@@ -218,10 +253,134 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
     get isTransaction(): boolean;
 }
 export declare class Transaction<DB> extends Kysely<DB> {
+    #private;
+    constructor(props: KyselyProps);
+    /**
+     * Returns true if this `Kysely` instance is a transaction.
+     *
+     * You can also use `db instanceof Transaction`.
+     */
     get isTransaction(): true;
+    /**
+     * Returns the {@link MigrationModule} module for managing and running migrations.
+     */
     get migration(): MigrationModule;
+    /**
+     * Creates a {@link TransactionBuilder} that can be used to run queries inside a transaction.
+     *
+     * 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.
+     *
+     * The callback function passed to the {@link TransactionBuilder.execute | execute}
+     * method gets the transaction object as its only argument. The transaction is
+     * of type {@link Transaction} which inherits {@link Kysely}. Any query
+     * started through the transaction object is executed inside the transaction.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const catto = await db.transaction().execute(async (trx) => {
+     *   const jennifer = await trx.insertInto('person')
+     *     .values({
+     *       id: db.generated,
+     *       first_name: 'Jennifer',
+     *       last_name: 'Aniston',
+     *     })
+     *     .returning('id')
+     *     .executeTakeFirstOrThrow()
+     *
+     *   await someFunction(trx, jennifer)
+     *
+     *   return await trx.insertInto('pet')
+     *     .values({
+     *       id: db.generated,
+     *       user_id: jennifer.id,
+     *       name: 'Catto',
+     *       species: 'cat'
+     *     })
+     *     .returning('*')
+     *     .executeTakeFirst()
+     * })
+     * ```
+     *
+     * Setting the isolation level:
+     *
+     * ```ts
+     * await db
+     *   .transaction()
+     *   .setIsolationLevel('serializable')
+     *   .execute(async (trx) => {
+     *     await doStuff(trx)
+     *   })
+     * ```
+     */
     transaction(): TransactionBuilder<DB>;
+    /**
+     * Provides a kysely instance bound to a single database connection.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db
+     *   .connection()
+     *   .execute(async (db) => {
+     *     // `db` is an instance of `Kysely` that's bound to a single
+     *     // database connection. All queries executed through `db` use
+     *     // the same connection.
+     *     await doStuff(db)
+     *   })
+     * ```
+     */
+    connection(): ConnectionBuilder<DB>;
+    /**
+     * Releases all resources and disconnects from the database.
+     *
+     * You need to call this when you are done using the `Kysely` instance.
+     */
     destroy(): Promise<void>;
+    /**
+     * Returns a copy of this Kysely instance with the given plugin installed.
+     */
+    withPlugin(plugin: KyselyPlugin): Transaction<DB>;
+    /**
+     * Returns a copy of this Kysely instance without any plugins.
+     */
+    withoutPlugins(): Transaction<DB>;
+    /**
+     * Returns a copy of this Kysely instance with tables added to its
+     * database type.
+     *
+     * This method only modifies the types and doesn't affect any of the
+     * executed queries in any way.
+     *
+     * ### Examples
+     *
+     * The following example adds and uses a temporary table:
+     *
+     * @example
+     * ```ts
+     * await db.schema
+     *   .createTable('temp_table')
+     *   .temporary()
+     *   .addColumn('some_column', 'integer')
+     *   .execute()
+     *
+     * const tempDb = db.withTables<{
+     *   temp_table: {
+     *     some_column: number
+     *   }
+     * }>()
+     *
+     * await tempDb
+     *   .insertInto('temp_table')
+     *   .values({ some_column: 100 })
+     *   .execute()
+     * ```
+     */
+    withTables<T extends Record<string, Record<string, any>>>(): Transaction<DB & T>;
 }
 export interface KyselyProps {
     readonly config: KyselyConfig;
@@ -240,7 +399,8 @@ export interface KyselyConfig {
      * Currently there's only two levels: `query` and `error`.
      * This will be expanded based on user feedback later.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * const db = new Kysely<Database>({
      *   dialect: new PostgresDialect(postgresConfig),
@@ -248,7 +408,6 @@ export interface KyselyConfig {
      * })
      * ```
      *
-     * @example
      * ```ts
      * const db = new Kysely<Database>({
      *   dialect: new PostgresDialect(postgresConfig),

package/dist/cjs/kysely.js

@@ -22,7 +22,8 @@ const log_js_1 = require("./util/log.js");
  * You should create one instance of `Kysely` per database using the {@link Kysely}
  * constructor. Each `Kysely` instance maintains it's own connection pool.
  *
- * @example
+ * ### Examples
+ *
  * This example assumes your database has tables `person` and `pet`:
  *
  * ```ts
@@ -36,7 +37,7 @@ const log_js_1 = require("./util/log.js");
  *   id: number
  *   owner_id: number
  *   name: string
- *   species 'cat' | 'dog'
+ *   species 'cat' | 'dog'
  * }
  *
  * interface Database {
@@ -114,10 +115,11 @@ class Kysely extends query_creator_js_1.QueryCreator {
      * A value to be used in place of columns that are generated in the database
      * when inserting rows.
      *
-     * @example
+     * ### Examples
+     *
      * In this example the `Person` table has non-null properties `id` and `created_at`
      * which are both automatically genereted by the database. Since their types are
-     * `number` and `string` respectively instead of `number | null` and `string | null`
+     * `number` and `string` respectively instead of `number | null` and `string | null`
      * the `values` method requires you to give a value for them. the `generated`
      * placeholder can be used in these cases.
      *
@@ -176,12 +178,13 @@ class Kysely extends query_creator_js_1.QueryCreator {
      * transaction. If the function throws, the transaction is rolled back. Otherwise
      * the transaction is committed.
      *
-     * The callback function passed to the {@link TransactionBuilder.execute | execute}
+     * The callback function passed to the {@link TransactionBuilder.execute | execute}
      * method gets the transaction object as its only argument. The transaction is
      * of type {@link Transaction} which inherits {@link Kysely}. Any query
      * started through the transaction object is executed inside the transaction.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * const catto = await db.transaction().execute(async (trx) => {
      *   const jennifer = await trx.insertInto('person')
@@ -207,8 +210,7 @@ class Kysely extends query_creator_js_1.QueryCreator {
      * })
      * ```
      *
-     * @example
-     * Setting the isolation level.
+     * Setting the isolation level:
      *
      * ```ts
      * await db
@@ -225,7 +227,8 @@ class Kysely extends query_creator_js_1.QueryCreator {
     /**
      * Provides a kysely instance bound to a single database connection.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db
      *   .connection()
@@ -258,6 +261,40 @@ class Kysely extends query_creator_js_1.QueryCreator {
             executor: this.#props.executor.withoutPlugins(),
         });
     }
+    /**
+     * Returns a copy of this Kysely instance with tables added to its
+     * database type.
+     *
+     * This method only modifies the types and doesn't affect any of the
+     * executed queries in any way.
+     *
+     * ### Examples
+     *
+     * The following example adds and uses a temporary table:
+     *
+     * @example
+     * ```ts
+     * await db.schema
+     *   .createTable('temp_table')
+     *   .temporary()
+     *   .addColumn('some_column', 'integer')
+     *   .execute()
+     *
+     * const tempDb = db.withTables<{
+     *   temp_table: {
+     *     some_column: number
+     *   }
+     * }>()
+     *
+     * await tempDb
+     *   .insertInto('temp_table')
+     *   .values({ some_column: 100 })
+     *   .execute()
+     * ```
+     */
+    withTables() {
+        return new Kysely({ ...this.#props });
+    }
     /**
      * Releases all resources and disconnects from the database.
      *
@@ -277,6 +314,11 @@ class Kysely extends query_creator_js_1.QueryCreator {
 }
 exports.Kysely = Kysely;
 class Transaction extends Kysely {
+    #props;
+    constructor(props) {
+        super(props);
+        this.#props = props;
+    }
     // The return type is `true` instead of `boolean` to make Kysely<DB>
     // unassignable to Transaction<DB> while allowing assignment the
     // other way around.
@@ -289,9 +331,27 @@ class Transaction extends Kysely {
     transaction() {
         throw new Error('calling the transaction method for a Transaction is not supported');
     }
+    connection() {
+        throw new Error('calling the connection method for a Transaction is not supported');
+    }
     async destroy() {
         throw new Error('calling the destroy method for a Transaction is not supported');
     }
+    withPlugin(plugin) {
+        return new Transaction({
+            ...this.#props,
+            executor: this.#props.executor.withPlugin(plugin),
+        });
+    }
+    withoutPlugins() {
+        return new Transaction({
+            ...this.#props,
+            executor: this.#props.executor.withoutPlugins(),
+        });
+    }
+    withTables() {
+        return new Transaction({ ...this.#props });
+    }
 }
 exports.Transaction = Transaction;
 function isKyselyProps(obj) {