kysely 0.27.3 → 0.27.5

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

@@ -44,7 +44,7 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      *
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('id', 'integer', (col) => col.autoIncrement().primaryKey()),
+     *   .addColumn('id', 'integer', (col) => col.autoIncrement().primaryKey())
      *   .addColumn('first_name', 'varchar(50)', (col) => col.notNull())
      *   .addColumn('last_name', 'varchar(255)')
      *   .addColumn('bank_balance', 'numeric(8, 2)')
@@ -52,7 +52,7 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      *   // don't include it.
      *   .addColumn('data', sql`any_type_here`)
      *   .addColumn('parent_id', 'integer', (col) =>
-     *     col.references('person.id').onDelete('cascade'))
+     *     col.references('person.id').onDelete('cascade')
      *   )
      * ```
      *
@@ -63,11 +63,18 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * `create table` query. See the next example:
      *
      * ```ts
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'integer', (col) => col.primaryKey())
      *   .addColumn('parent_id', 'integer')
      *   .addForeignKeyConstraint(
-     *     'person_parent_id_fk', ['parent_id'], 'person', ['id'],
+     *     'person_parent_id_fk',
+     *     ['parent_id'],
+     *     'person',
+     *     ['id'],
      *     (cb) => cb.onDelete('cascade')
      *   )
+     *   .execute()
      * ```
      *
      * Another good example is that PostgreSQL doesn't support the `auto_increment`
@@ -77,7 +84,8 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ```ts
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('id', 'serial', (col) => col.primaryKey()),
+     *   .addColumn('id', 'serial', (col) => col.primaryKey())
+     *   .execute()
      * ```
      */
     addColumn<CN extends string>(columnName: CN, dataType: DataTypeExpression, build?: ColumnBuilderCallback): CreateTableBuilder<TB, C | CN>;
@@ -90,7 +98,12 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ### Examples
      *
      * ```ts
-     * addPrimaryKeyConstraint('primary_key', ['first_name', 'last_name'])
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('first_name', 'varchar(64)')
+     *   .addColumn('last_name', 'varchar(64)')
+     *   .addPrimaryKeyConstraint('primary_key', ['first_name', 'last_name'])
+     *   .execute()
      * ```
      */
     addPrimaryKeyConstraint(constraintName: string, columns: C[]): CreateTableBuilder<TB, C>;
@@ -103,12 +116,30 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ### Examples
      *
      * ```ts
-     * addUniqueConstraint('first_name_last_name_unique', ['first_name', 'last_name'])
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('first_name', 'varchar(64)')
+     *   .addColumn('last_name', 'varchar(64)')
+     *   .addUniqueConstraint(
+     *     'first_name_last_name_unique',
+     *     ['first_name', 'last_name']
+     *   )
+     *   .execute()
      * ```
      *
      * In dialects such as PostgreSQL you can specify `nulls not distinct` as follows:
+     *
      * ```ts
-     * addUniqueConstraint('first_name_last_name_unique', ['first_name', 'last_name'], (builder) => builder.nullsNotDistinct())
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('first_name', 'varchar(64)')
+     *   .addColumn('last_name', 'varchar(64)')
+     *   .addUniqueConstraint(
+     *     'first_name_last_name_unique',
+     *     ['first_name', 'last_name'],
+     *     (cb) => cb.nullsNotDistinct()
+     *   )
+     *   .execute()
      * ```
      */
     addUniqueConstraint(constraintName: string, columns: C[], build?: UniqueConstraintNodeBuilderCallback): CreateTableBuilder<TB, C>;
@@ -123,7 +154,11 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ```ts
      * import { sql } from 'kysely'
      *
-     * addCheckConstraint('check_legs', sql`number_of_legs < 5`)
+     * await db.schema
+     *   .createTable('animal')
+     *   .addColumn('number_of_legs', 'integer')
+     *   .addCheckConstraint('check_legs', sql`number_of_legs < 5`)
+     *   .execute()
      * ```
      */
     addCheckConstraint(constraintName: string, checkExpression: Expression<any>): CreateTableBuilder<TB, C>;
@@ -136,24 +171,33 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ### Examples
      *
      * ```ts
-     * addForeignKeyConstraint(
-     *   'owner_id_foreign',
-     *   ['owner_id'],
-     *   'person',
-     *   ['id'],
-     * )
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('owner_id', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'owner_id_foreign',
+     *     ['owner_id'],
+     *     'person',
+     *     ['id'],
+     *   )
+     *   .execute()
      * ```
      *
      * Add constraint for multiple columns:
      *
      * ```ts
-     * addForeignKeyConstraint(
-     *   'owner_id_foreign',
-     *   ['owner_id1', 'owner_id2'],
-     *   'person',
-     *   ['id1', 'id2'],
-     *   (cb) => cb.onDelete('cascade')
-     * )
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('owner_id1', 'integer')
+     *   .addColumn('owner_id2', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'owner_id_foreign',
+     *     ['owner_id1', 'owner_id2'],
+     *     'person',
+     *     ['id1', 'id2'],
+     *     (cb) => cb.onDelete('cascade')
+     *   )
+     *   .execute()
      * ```
      */
     addForeignKeyConstraint(constraintName: string, columns: C[], targetTable: string, targetColumns: string[], build?: ForeignKeyConstraintBuilderCallback): CreateTableBuilder<TB, C>;
@@ -165,11 +209,14 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ### Examples
      *
      * ```ts
-     * db.schema.createTable('person')
+     * import { sql } from 'kysely'
+     *
+     * await db.schema
+     *   .createTable('person')
      *   .modifyFront(sql`global temporary`)
      *   .addColumn('id', 'integer', col => col.primaryKey())
      *   .addColumn('first_name', 'varchar(64)', col => col.notNull())
-     *   .addColumn('last_name', 'varchar(64), col => col.notNull())
+     *   .addColumn('last_name', 'varchar(64)', col => col.notNull())
      *   .execute()
      * ```
      *
@@ -192,10 +239,13 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ### Examples
      *
      * ```ts
-     * db.schema.createTable('person')
-     *   .addColumn('id', 'integer', col => col => primaryKey())
+     * import { sql } from 'kysely'
+     *
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'integer', col => col.primaryKey())
      *   .addColumn('first_name', 'varchar(64)', col => col.notNull())
-     *   .addColumn('last_name', 'varchar(64), col => col.notNull())
+     *   .addColumn('last_name', 'varchar(64)', col => col.notNull())
      *   .modifyEnd(sql`collate utf8_unicode_ci`)
      *   .execute()
      * ```
@@ -217,7 +267,8 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ### Examples
      *
      * ```ts
-     * db.schema.createTable('copy')
+     * await db.schema
+     *   .createTable('copy')
      *   .temporary()
      *   .as(db.selectFrom('person').select(['first_name', 'last_name']))
      *   .execute()
@@ -237,17 +288,19 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ### Examples
      *
      * ```ts
-     * db.schema
+     * await db.schema
      *   .createTable('test')
      *   .$call((builder) => builder.addColumn('id', 'integer'))
      *   .execute()
      * ```
      *
+     * This is useful for creating reusable functions that can be called with a builder.
+     *
      * ```ts
-     * const addDefaultColumns = <T extends string, C extends string = never>(
-     *   builder: CreateTableBuilder<T, C>
-     * ) => {
-     *   return builder
+     * import { type CreateTableBuilder, sql } from 'kysely'
+     *
+     * const addDefaultColumns = (ctb: CreateTableBuilder<any, any>) => {
+     *   return ctb
      *     .addColumn('id', 'integer', (col) => col.notNull())
      *     .addColumn('created_at', 'date', (col) =>
      *       col.notNull().defaultTo(sql`now()`)
@@ -257,7 +310,7 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      *     )
      * }
      *
-     * db.schema
+     * await db.schema
      *   .createTable('test')
      *   .$call(addDefaultColumns)
      *   .execute()

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

@@ -73,7 +73,7 @@ export class CreateTableBuilder {
      *
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('id', 'integer', (col) => col.autoIncrement().primaryKey()),
+     *   .addColumn('id', 'integer', (col) => col.autoIncrement().primaryKey())
      *   .addColumn('first_name', 'varchar(50)', (col) => col.notNull())
      *   .addColumn('last_name', 'varchar(255)')
      *   .addColumn('bank_balance', 'numeric(8, 2)')
@@ -81,7 +81,7 @@ export class CreateTableBuilder {
      *   // don't include it.
      *   .addColumn('data', sql`any_type_here`)
      *   .addColumn('parent_id', 'integer', (col) =>
-     *     col.references('person.id').onDelete('cascade'))
+     *     col.references('person.id').onDelete('cascade')
      *   )
      * ```
      *
@@ -92,11 +92,18 @@ export class CreateTableBuilder {
      * `create table` query. See the next example:
      *
      * ```ts
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'integer', (col) => col.primaryKey())
      *   .addColumn('parent_id', 'integer')
      *   .addForeignKeyConstraint(
-     *     'person_parent_id_fk', ['parent_id'], 'person', ['id'],
+     *     'person_parent_id_fk',
+     *     ['parent_id'],
+     *     'person',
+     *     ['id'],
      *     (cb) => cb.onDelete('cascade')
      *   )
+     *   .execute()
      * ```
      *
      * Another good example is that PostgreSQL doesn't support the `auto_increment`
@@ -106,7 +113,8 @@ export class CreateTableBuilder {
      * ```ts
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('id', 'serial', (col) => col.primaryKey()),
+     *   .addColumn('id', 'serial', (col) => col.primaryKey())
+     *   .execute()
      * ```
      */
     addColumn(columnName, dataType, build = noop) {
@@ -125,7 +133,12 @@ export class CreateTableBuilder {
      * ### Examples
      *
      * ```ts
-     * addPrimaryKeyConstraint('primary_key', ['first_name', 'last_name'])
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('first_name', 'varchar(64)')
+     *   .addColumn('last_name', 'varchar(64)')
+     *   .addPrimaryKeyConstraint('primary_key', ['first_name', 'last_name'])
+     *   .execute()
      * ```
      */
     addPrimaryKeyConstraint(constraintName, columns) {
@@ -143,12 +156,30 @@ export class CreateTableBuilder {
      * ### Examples
      *
      * ```ts
-     * addUniqueConstraint('first_name_last_name_unique', ['first_name', 'last_name'])
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('first_name', 'varchar(64)')
+     *   .addColumn('last_name', 'varchar(64)')
+     *   .addUniqueConstraint(
+     *     'first_name_last_name_unique',
+     *     ['first_name', 'last_name']
+     *   )
+     *   .execute()
      * ```
      *
      * In dialects such as PostgreSQL you can specify `nulls not distinct` as follows:
+     *
      * ```ts
-     * addUniqueConstraint('first_name_last_name_unique', ['first_name', 'last_name'], (builder) => builder.nullsNotDistinct())
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('first_name', 'varchar(64)')
+     *   .addColumn('last_name', 'varchar(64)')
+     *   .addUniqueConstraint(
+     *     'first_name_last_name_unique',
+     *     ['first_name', 'last_name'],
+     *     (cb) => cb.nullsNotDistinct()
+     *   )
+     *   .execute()
      * ```
      */
     addUniqueConstraint(constraintName, columns, build = noop) {
@@ -169,7 +200,11 @@ export class CreateTableBuilder {
      * ```ts
      * import { sql } from 'kysely'
      *
-     * addCheckConstraint('check_legs', sql`number_of_legs < 5`)
+     * await db.schema
+     *   .createTable('animal')
+     *   .addColumn('number_of_legs', 'integer')
+     *   .addCheckConstraint('check_legs', sql`number_of_legs < 5`)
+     *   .execute()
      * ```
      */
     addCheckConstraint(constraintName, checkExpression) {
@@ -187,24 +222,33 @@ export class CreateTableBuilder {
      * ### Examples
      *
      * ```ts
-     * addForeignKeyConstraint(
-     *   'owner_id_foreign',
-     *   ['owner_id'],
-     *   'person',
-     *   ['id'],
-     * )
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('owner_id', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'owner_id_foreign',
+     *     ['owner_id'],
+     *     'person',
+     *     ['id'],
+     *   )
+     *   .execute()
      * ```
      *
      * Add constraint for multiple columns:
      *
      * ```ts
-     * addForeignKeyConstraint(
-     *   'owner_id_foreign',
-     *   ['owner_id1', 'owner_id2'],
-     *   'person',
-     *   ['id1', 'id2'],
-     *   (cb) => cb.onDelete('cascade')
-     * )
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('owner_id1', 'integer')
+     *   .addColumn('owner_id2', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'owner_id_foreign',
+     *     ['owner_id1', 'owner_id2'],
+     *     'person',
+     *     ['id1', 'id2'],
+     *     (cb) => cb.onDelete('cascade')
+     *   )
+     *   .execute()
      * ```
      */
     addForeignKeyConstraint(constraintName, columns, targetTable, targetColumns, build = noop) {
@@ -222,11 +266,14 @@ export class CreateTableBuilder {
      * ### Examples
      *
      * ```ts
-     * db.schema.createTable('person')
+     * import { sql } from 'kysely'
+     *
+     * await db.schema
+     *   .createTable('person')
      *   .modifyFront(sql`global temporary`)
      *   .addColumn('id', 'integer', col => col.primaryKey())
      *   .addColumn('first_name', 'varchar(64)', col => col.notNull())
-     *   .addColumn('last_name', 'varchar(64), col => col.notNull())
+     *   .addColumn('last_name', 'varchar(64)', col => col.notNull())
      *   .execute()
      * ```
      *
@@ -254,10 +301,13 @@ export class CreateTableBuilder {
      * ### Examples
      *
      * ```ts
-     * db.schema.createTable('person')
-     *   .addColumn('id', 'integer', col => col => primaryKey())
+     * import { sql } from 'kysely'
+     *
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'integer', col => col.primaryKey())
      *   .addColumn('first_name', 'varchar(64)', col => col.notNull())
-     *   .addColumn('last_name', 'varchar(64), col => col.notNull())
+     *   .addColumn('last_name', 'varchar(64)', col => col.notNull())
      *   .modifyEnd(sql`collate utf8_unicode_ci`)
      *   .execute()
      * ```
@@ -284,7 +334,8 @@ export class CreateTableBuilder {
      * ### Examples
      *
      * ```ts
-     * db.schema.createTable('copy')
+     * await db.schema
+     *   .createTable('copy')
      *   .temporary()
      *   .as(db.selectFrom('person').select(['first_name', 'last_name']))
      *   .execute()
@@ -311,17 +362,19 @@ export class CreateTableBuilder {
      * ### Examples
      *
      * ```ts
-     * db.schema
+     * await db.schema
      *   .createTable('test')
      *   .$call((builder) => builder.addColumn('id', 'integer'))
      *   .execute()
      * ```
      *
+     * This is useful for creating reusable functions that can be called with a builder.
+     *
      * ```ts
-     * const addDefaultColumns = <T extends string, C extends string = never>(
-     *   builder: CreateTableBuilder<T, C>
-     * ) => {
-     *   return builder
+     * import { type CreateTableBuilder, sql } from 'kysely'
+     *
+     * const addDefaultColumns = (ctb: CreateTableBuilder<any, any>) => {
+     *   return ctb
      *     .addColumn('id', 'integer', (col) => col.notNull())
      *     .addColumn('created_at', 'date', (col) =>
      *       col.notNull().defaultTo(sql`now()`)
@@ -331,7 +384,7 @@ export class CreateTableBuilder {
      *     )
      * }
      *
-     * db.schema
+     * await db.schema
      *   .createTable('test')
      *   .$call(addDefaultColumns)
      *   .execute()

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

@@ -15,7 +15,7 @@ import { DrainOuterGeneric } from './type-utils.js';
  * type is actually just a shortcut for the type in this example:
  *
  * ```ts
- * ColumnType<number, number | undefined, number>
+ * type GeneratedNumber = ColumnType<number, number | undefined, number>
  * ```
  *
  * The above example makes the column optional in inserts
@@ -24,14 +24,14 @@ import { DrainOuterGeneric } from './type-utils.js';
  * can se the type as `never`:
  *
  * ```ts
- * ColumnType<number, never, never>
+ * type ReadonlyNumber = ColumnType<number, never, never>
  * ```
  *
  * Here's one more example where the type is different
  * for each different operation:
  *
  * ```ts
- * ColumnType<Date, string, never>
+ * type UnupdateableDate = ColumnType<Date, string, never>
  * ```
  */
 export type ColumnType<SelectType, InsertType = SelectType, UpdateType = SelectType> = {
@@ -44,12 +44,8 @@ export type ColumnType<SelectType, InsertType = SelectType, UpdateType = SelectT
  * is the same for all selects, inserts and updates but the
  * column is optional for inserts and updates.
  *
- * 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>
+ * The update type is `S` instead of `S | undefined` because updates are always
+ * optional --> no need to specify optionality.
  * ```
  */
 export type Generated<S> = ColumnType<S, S | undefined, S>;

package/dist/esm/util/object-utils.js

@@ -44,11 +44,17 @@ export function isArrayBufferOrView(obj) {
     return obj instanceof ArrayBuffer || ArrayBuffer.isView(obj);
 }
 export function isPlainObject(obj) {
-    return (isObject(obj) &&
-        !Array.isArray(obj) &&
-        !isDate(obj) &&
-        !isBuffer(obj) &&
-        !isArrayBufferOrView(obj));
+    if (!isObject(obj) || getTag(obj) !== '[object Object]') {
+        return false;
+    }
+    if (Object.getPrototypeOf(obj) === null) {
+        return true;
+    }
+    let proto = obj;
+    while (Object.getPrototypeOf(proto) !== null) {
+        proto = Object.getPrototypeOf(proto);
+    }
+    return Object.getPrototypeOf(obj) === proto;
 }
 export function getLast(arr) {
     return arr[arr.length - 1];
@@ -126,3 +132,10 @@ function compareGenericObjects(obj1, obj2) {
     }
     return true;
 }
+const toString = Object.prototype.toString;
+function getTag(value) {
+    if (value == null) {
+        return value === undefined ? '[object Undefined]' : '[object Null]';
+    }
+    return toString.call(value);
+}

package/dist/esm/util/require-all-props.d.ts

@@ -26,14 +26,16 @@ type AllProps<T> = T & {
  * 1. Omit checked type - all checked properties will be expect as of type never
  *
  * ```ts
- * const z: SomeType = requireAllProps({ propC: "no type will work" });
+ * type SomeType = { propA: string; propB?: number; }
+ * // const z: SomeType = requireAllProps({ propC: "no type will work" }); // Property 'propA' is missing in type '{ propC: string; }' but required in type 'SomeType'.
  * ```
  *
  * 2. Apply to spreaded object - there is no way how to check in compile time if spreaded object contains all properties
  *
  * ```ts
+ * type SomeType = { propA: string; propB?: number; }
  * const y: SomeType = { propA: "" }; // valid object according to SomeType declaration
- * const x = requireAllProps<SomeType>( { ... y } );
+ * // const x = requireAllProps<SomeType>({ ...y }); // Argument of type '{ propA: string; propB?: number; }' is not assignable to parameter of type 'AllProps<SomeType>'.
  * ```
  *
  * @param obj object to check if all properties has been used

package/dist/esm/util/require-all-props.js

@@ -19,14 +19,16 @@
  * 1. Omit checked type - all checked properties will be expect as of type never
  *
  * ```ts
- * const z: SomeType = requireAllProps({ propC: "no type will work" });
+ * type SomeType = { propA: string; propB?: number; }
+ * // const z: SomeType = requireAllProps({ propC: "no type will work" }); // Property 'propA' is missing in type '{ propC: string; }' but required in type 'SomeType'.
  * ```
  *
  * 2. Apply to spreaded object - there is no way how to check in compile time if spreaded object contains all properties
  *
  * ```ts
+ * type SomeType = { propA: string; propB?: number; }
  * const y: SomeType = { propA: "" }; // valid object according to SomeType declaration
- * const x = requireAllProps<SomeType>( { ... y } );
+ * // const x = requireAllProps<SomeType>({ ...y }); // Argument of type '{ propA: string; propB?: number; }' is not assignable to parameter of type 'AllProps<SomeType>'.
  * ```
  *
  * @param obj object to check if all properties has been used

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

@@ -8,7 +8,7 @@ export interface Streamable<O> {
      * ### Examples
      *
      * ```ts
-     * const stream = db.
+     * const stream = db
      *   .selectFrom('person')
      *   .select(['first_name', 'last_name'])
      *   .where('gender', '=', 'other')

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

@@ -125,7 +125,9 @@ export type NarrowPartial<O, T> = DrainOuterGeneric<T extends object ? {
  * Example:
  *
  * ```ts
- * const person = await db.selectFrom('person')
+ * import type { NotNull } from 'kysely'
+ *
+ * await db.selectFrom('person')
  *   .where('nullable_column', 'is not', null)
  *   .selectAll()
  *   .$narrowType<{ nullable_column: NotNull }>()
@@ -148,7 +150,7 @@ export type SqlBool = boolean | 0 | 1;
  *   A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<T>>>>>>>>>>>>>>>>>>>>>>>>
  * >
  *
- * type Error = Test<number> // Type instantiation is excessively deep and possibly infinite.ts (2589)
+ * // type Error = Test<number> // Type instantiation is excessively deep and possibly infinite.ts (2589)
  * ```
  *
  * To fix this, we can use `DrainOuterGeneric`: