kysely 0.8.0 → 0.9.2

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

@@ -2,12 +2,18 @@ import { ColumnDefinitionNode } from '../operation-node/column-definition-node.j
 import { CreateTableNode } from '../operation-node/create-table-node.js';
 import { preventAwait } from '../util/prevent-await.js';
 import { ColumnDefinitionBuilder } from './column-definition-builder.js';
-import { freeze } from '../util/object-utils.js';
+import { freeze, noop } from '../util/object-utils.js';
 import { ForeignKeyConstraintNode } from '../operation-node/foreign-key-constraint-node.js';
 import { ColumnNode } from '../operation-node/column-node.js';
 import { TableNode } from '../operation-node/table-node.js';
 import { ForeignKeyConstraintBuilder } from './foreign-key-constraint-builder.js';
 import { parseDataTypeExpression, } from '../parser/data-type-parser.js';
+import { PrimaryConstraintNode } from '../operation-node/primary-constraint-node.js';
+import { UniqueConstraintNode } from '../operation-node/unique-constraint-node.js';
+import { CheckConstraintNode } from '../operation-node/check-constraint-node.js';
+/**
+ * This builder can be used to create a `create table` query.
+ */
 export class CreateTableBuilder {
     #props;
     constructor(props) {
@@ -31,18 +37,45 @@ export class CreateTableBuilder {
      * ```ts
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('int', 'id', (col) => col.increments().primary()),
+     *   .addColumn('id', 'integer', (col) => col.increments().primaryKey()),
      *   .addColumn('first_name', 'varchar(50), (col) => col.notNull())
-     *   .addColumn('varchar', 'last_name')
-     *   .addColumn('numeric(8, 2)', 'bank_balance')
+     *   .addColumn('last_name', 'varchar')
+     *   .addColumn('bank_balance', 'numeric(8, 2)')
      *   .addColumn('data', db.raw('customtype'))
+     *   .addColumn('parent_id', 'integer', (col) =>
+     *     col.references('person.id').onDelete('cascade'))
+     *   )
+     * ```
+     *
+     * With this method, it's once again good to remember that Kysely just builds the query
+     * that's as close to the structure of your builder method calls as possible, and doesn't
+     * provide the same API for all databses. For example, some databases like older MySQL
+     * don't support `references` statement in the column definition. Instead foreign key
+     * constraints need to be defined in at the level of the `create table` query. See
+     * the next example:
+     *
+     * @example
+     * ```ts
+     *   .addColumn('parent_id', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'person_parent_id_fk', ['parent_id'], 'person', ['id'],
+     *     (cb) => cb.onDelete('cascade')
+     *   )
+     * ```
+     *
+     * Another good example is that PostgreSQL doesn't support the `auto_increment`
+     * keyword and you need to define an autoincrementing column for example using
+     * `serial`:
+     *
+     * @example
+     * ```ts
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'serial', (col) => col.primaryKey()),
      * ```
      */
-    addColumn(columnName, dataType, build) {
-        let columnBuilder = new ColumnDefinitionBuilder(ColumnDefinitionNode.create(columnName, parseDataTypeExpression(dataType)));
-        if (build) {
-            columnBuilder = build(columnBuilder);
-        }
+    addColumn(columnName, dataType, build = noop) {
+        const columnBuilder = build(new ColumnDefinitionBuilder(ColumnDefinitionNode.create(columnName, parseDataTypeExpression(dataType))));
         return new CreateTableBuilder({
             ...this.#props,
             createTableNode: CreateTableNode.cloneWithColumn(this.#props.createTableNode, columnBuilder.toOperationNode()),
@@ -51,6 +84,9 @@ export class CreateTableBuilder {
     /**
      * Adds a primary key constraint for one or more columns.
      *
+     * The constraint name can be anything you want, but it must be unique
+     * across the whole database.
+     *
      * @example
      * ```ts
      * addPrimaryKeyConstraint('primary_key', ['first_name', 'last_name'])
@@ -59,12 +95,15 @@ export class CreateTableBuilder {
     addPrimaryKeyConstraint(constraintName, columns) {
         return new CreateTableBuilder({
             ...this.#props,
-            createTableNode: CreateTableNode.cloneWithPrimaryKeyConstraint(this.#props.createTableNode, constraintName, columns),
+            createTableNode: CreateTableNode.cloneWithConstraint(this.#props.createTableNode, PrimaryConstraintNode.create(columns, constraintName)),
         });
     }
     /**
      * Adds a unique constraint for one or more columns.
      *
+     * The constraint name can be anything you want, but it must be unique
+     * across the whole database.
+     *
      * @example
      * ```ts
      * addUniqueConstraint('first_name_last_name_unique', ['first_name', 'last_name'])
@@ -73,12 +112,15 @@ export class CreateTableBuilder {
     addUniqueConstraint(constraintName, columns) {
         return new CreateTableBuilder({
             ...this.#props,
-            createTableNode: CreateTableNode.cloneWithUniqueConstraint(this.#props.createTableNode, constraintName, columns),
+            createTableNode: CreateTableNode.cloneWithConstraint(this.#props.createTableNode, UniqueConstraintNode.create(columns, constraintName)),
         });
     }
     /**
      * Adds a check constraint.
      *
+     * The constraint name can be anything you want, but it must be unique
+     * across the whole database.
+     *
      * @example
      * ```ts
      * addCheckConstraint('check_legs', 'number_of_legs < 5')
@@ -87,12 +129,15 @@ export class CreateTableBuilder {
     addCheckConstraint(constraintName, checkExpression) {
         return new CreateTableBuilder({
             ...this.#props,
-            createTableNode: CreateTableNode.cloneWithCheckConstraint(this.#props.createTableNode, constraintName, checkExpression),
+            createTableNode: CreateTableNode.cloneWithConstraint(this.#props.createTableNode, CheckConstraintNode.create(checkExpression, constraintName)),
         });
     }
     /**
      * Adds a foreign key constraint.
      *
+     * The constraint name can be anything you want, but it must be unique
+     * across the whole database.
+     *
      * @example
      * ```ts
      * addForeignKeyConstraint(
@@ -114,14 +159,11 @@ export class CreateTableBuilder {
      * )
      * ```
      */
-    addForeignKeyConstraint(constraintName, columns, targetTable, targetColumns, build) {
-        let builder = new ForeignKeyConstraintBuilder(ForeignKeyConstraintNode.create(columns.map(ColumnNode.create), TableNode.create(targetTable), targetColumns.map(ColumnNode.create), constraintName));
-        if (build) {
-            builder = build(builder);
-        }
+    addForeignKeyConstraint(constraintName, columns, targetTable, targetColumns, build = noop) {
+        const builder = build(new ForeignKeyConstraintBuilder(ForeignKeyConstraintNode.create(columns.map(ColumnNode.create), TableNode.create(targetTable), targetColumns.map(ColumnNode.create), constraintName)));
         return new CreateTableBuilder({
             ...this.#props,
-            createTableNode: CreateTableNode.cloneWithForeignKeyConstraint(this.#props.createTableNode, builder.toOperationNode()),
+            createTableNode: CreateTableNode.cloneWithConstraint(this.#props.createTableNode, builder.toOperationNode()),
         });
     }
     toOperationNode() {

package/dist/esm/schema/schema.d.ts

@@ -22,14 +22,49 @@ export declare class SchemaModule {
      * ```ts
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('id', 'int', col => col.primaryKey().increments())
+     *   .addColumn('id', 'integer', col => col.primaryKey().increments())
      *   .addColumn('first_name', 'varchar', col => col.notNull())
      *   .addColumn('last_name', 'varchar', col => col.notNull())
      *   .addColumn('gender', 'varchar')
      *   .execute()
      * ```
+     *
+     * @example
+     * This example creates a table with a foreign key. Not all database
+     * engines support column-level foreign key constraint definitions.
+     * For example if you are using MySQL 5.X see the next example after
+     * this one.
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('id', 'integer', col => col.primaryKey().increments())
+     *   .addColumn('owner_id', 'integer', col => col
+     *     .references('person.id')
+     *     .onDelete('cascade')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * @example
+     * This example adds a foreign key constraint for a columns just
+     * like the previous example, but using a table-level statement.
+     * On MySQL 5.X you need to define foreign key constraints like
+     * this:
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('id', 'integer', col => col.primaryKey().increments())
+     *   .addColumn('owner_id', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'pet_owner_id_foreign', ['owner_id'], 'person', ['id'],
+     *     (constraint) => constraint.onDelete('cascade')
+     *   )
+     *   .execute()
+     * ```
      */
-    createTable(table: string): CreateTableBuilder;
+    createTable<TB extends string>(table: TB): CreateTableBuilder<TB, never>;
     /**
      * Drop a table.
      *

package/dist/esm/schema/schema.js

@@ -33,12 +33,47 @@ export class SchemaModule {
      * ```ts
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('id', 'int', col => col.primaryKey().increments())
+     *   .addColumn('id', 'integer', col => col.primaryKey().increments())
      *   .addColumn('first_name', 'varchar', col => col.notNull())
      *   .addColumn('last_name', 'varchar', col => col.notNull())
      *   .addColumn('gender', 'varchar')
      *   .execute()
      * ```
+     *
+     * @example
+     * This example creates a table with a foreign key. Not all database
+     * engines support column-level foreign key constraint definitions.
+     * For example if you are using MySQL 5.X see the next example after
+     * this one.
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('id', 'integer', col => col.primaryKey().increments())
+     *   .addColumn('owner_id', 'integer', col => col
+     *     .references('person.id')
+     *     .onDelete('cascade')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * @example
+     * This example adds a foreign key constraint for a columns just
+     * like the previous example, but using a table-level statement.
+     * On MySQL 5.X you need to define foreign key constraints like
+     * this:
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('id', 'integer', col => col.primaryKey().increments())
+     *   .addColumn('owner_id', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'pet_owner_id_foreign', ['owner_id'], 'person', ['id'],
+     *     (constraint) => constraint.onDelete('cascade')
+     *   )
+     *   .execute()
+     * ```
      */
     createTable(table) {
         return new CreateTableBuilder({

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

@@ -1,18 +1,19 @@
 /// <reference types="node" />
 export declare type PrimitiveValue = string | number | boolean | null | Date | Buffer | BigInt;
-export declare function isEmpty(obj: ArrayLike<any> | string | object | Buffer): boolean;
-export declare function isString(obj: any): obj is string;
-export declare function isNumber(obj: any): obj is number;
-export declare function isBoolean(obj: any): obj is boolean;
-export declare function isNull(obj: any): obj is null;
-export declare function isDate(obj: any): obj is Date;
-export declare function isBuffer(obj: any): obj is Buffer;
-export declare function isBigInt(obj: any): obj is BigInt;
-export declare function isPrimitive(obj: any): obj is PrimitiveValue;
-export declare function isFunction(obj: any): obj is Function;
-export declare function isObject(obj: any): obj is Record<string, any>;
+export declare function isEmpty(obj: ArrayLike<unknown> | string | object | Buffer): boolean;
+export declare function isString(obj: unknown): obj is string;
+export declare function isNumber(obj: unknown): obj is number;
+export declare function isBoolean(obj: unknown): obj is boolean;
+export declare function isNull(obj: unknown): obj is null;
+export declare function isDate(obj: unknown): obj is Date;
+export declare function isBuffer(obj: unknown): obj is Buffer;
+export declare function isBigInt(obj: unknown): obj is BigInt;
+export declare function isPrimitive(obj: unknown): obj is PrimitiveValue;
+export declare function isFunction(obj: unknown): obj is Function;
+export declare function isObject(obj: unknown): obj is Record<string, unknown>;
 export declare function getLast<T>(arr: ArrayLike<T>): T | undefined;
 export declare function freeze<T>(obj: T): Readonly<T>;
 export declare function asArray<T>(arg: T | T[]): T[];
 export declare function asReadonlyArray<T>(arg: T | ReadonlyArray<T>): ReadonlyArray<T>;
 export declare function isReadonlyArray(arg: unknown): arg is ReadonlyArray<unknown>;
+export declare function noop<T>(obj: T): T;

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

@@ -41,7 +41,7 @@ export function isFunction(obj) {
     return typeof obj === 'function';
 }
 export function isObject(obj) {
-    return obj && typeof obj === 'object';
+    return typeof obj === 'object' && obj !== null;
 }
 export function getLast(arr) {
     return arr[arr.length - 1];
@@ -68,3 +68,6 @@ export function asReadonlyArray(arg) {
 export function isReadonlyArray(arg) {
     return Array.isArray(arg);
 }
+export function noop(obj) {
+    return obj;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely",
-  "version": "0.8.0",
+  "version": "0.9.2",
   "description": "Type safe SQL query builder",
   "repository": {
     "type": "git",