kysely 0.10.0 → 0.11.2

package/dist/esm/query-creator.js

@@ -26,20 +26,17 @@ export class QueryCreator {
     /**
      * Creates an insert query.
      *
-     * The return value of this query is `number | undefined` because of the differences
-     * between database engines. Most engines (like Mysql) return the auto incrementing
-     * primary key (if it exists), but some (like postgres) return nothing by default.
-     * If you are running a database engine like `Mysql` that always returns the primary
-     * key, you can safely use `!` or the {@link QueryBuilder.castTo | castTo} method
-     * to cast away the `undefined` from the type.
+     * The return value of this query is an instance of {@link InsertResult}. {@link InsertResult}
+     * has the {@link InsertResult.insertId | insertId} field that holds the auto incremented id of
+     * the inserted row if the db returned one.
      *
      * See the {@link QueryBuilder.values | values} method for more info and examples. Also see
      * the {@link QueryBuilder.returning | returning} method for a way to return columns
-     * on supported databases like postgres.
+     * on supported databases like PostgreSQL.
      *
      * @example
      * ```ts
-     * const maybePrimaryKey: number | undefined = await db
+     * const result = await db
      *   .insertInto('person')
      *   .values({
      *     id: db.generated,
@@ -47,10 +44,12 @@ export class QueryCreator {
      *     last_name: 'Aniston'
      *   })
      *   .executeTakeFirst()
+     *
+     * console.log(result.insertId)
      * ```
      *
      * @example
-     * Some databases like postgres support the `returning` method:
+     * Some databases like PostgreSQL support the `returning` method:
      *
      * ```ts
      * const { id } = await db
@@ -76,14 +75,18 @@ export class QueryCreator {
      * Creates a delete query.
      *
      * See the {@link QueryBuilder.where} method for examples on how to specify
-     * a where clause for the delete operation .
+     * a where clause for the delete operation.
+     *
+     * The return value of the query is an instance of {@link DeleteResult}.
      *
      * @example
      * ```ts
-     * const numAffectedRows = await db
+     * const result = await db
      *   .deleteFrom('person')
      *   .where('person.id', '=', 1)
      *   .executeTakeFirst()
+     *
+     * console.log(result.numDeletedRows)
      * ```
      */
     deleteFrom(table) {
@@ -103,13 +106,17 @@ export class QueryCreator {
      * See the {@link QueryBuilder.set} method for examples on how to
      * specify the updates.
      *
+     * The return value of the query is an {@link UpdateResult}.
+     *
      * @example
      * ```ts
-     * const numAffectedRows = await db
+     * const result = await db
      *   .updateTable('person')
      *   .set({ first_name: 'Jennifer' })
      *   .where('person.id', '=', 1)
      *   .executeTakeFirst()
+     *
+     * console.log(result.numUpdatedRows)
      * ```
      */
     updateTable(table) {
@@ -167,7 +174,7 @@ export class QueryCreator {
      *  .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "mammals"."pet"
@@ -187,7 +194,7 @@ export class QueryCreator {
      *  .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "p"."name" from "mammals"."pet" as "p"
@@ -237,7 +244,7 @@ export class QueryCreator {
      * console.log(person.name)
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select concat(first_name, ' ', last_name) as "name"
@@ -295,7 +302,7 @@ export class QueryCreator {
      * }
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person" where now() - birth_date > interval $1 year
@@ -309,7 +316,8 @@ export class QueryCreator {
      * Example of creating a completely raw query from scratch:
      *
      * ```ts
-     * const persons = await db.raw<Person>('select p.* from person p').execute()
+     * const result = await db.raw<Person>('select p.* from person p').execute()
+     * const persons = result.rows
      * ```
      *
      * For a raw query, you need to specify the type of the returned __row__. In

package/dist/esm/raw-builder/raw-builder.d.ts

@@ -41,5 +41,5 @@ export interface RawBuilderProps {
     readonly queryId: QueryId;
     readonly executor: QueryExecutor;
     readonly sql: string;
-    readonly parameters?: any;
+    readonly parameters?: ReadonlyArray<unknown>;
 }

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

@@ -72,6 +72,8 @@ export declare class AlterTableAddColumnBuilder implements ColumnDefinitionBuild
     notNull(): AlterTableAddColumnBuilder;
     defaultTo(value: PrimitiveValue | AnyRawBuilder): AlterTableAddColumnBuilder;
     check(sql: string): AlterTableAddColumnBuilder;
+    generatedAlwaysAs(sql: string): AlterTableAddColumnBuilder;
+    stored(): AlterTableAddColumnBuilder;
     toOperationNode(): AlterTableNode;
     compile(): CompiledQuery;
     execute(): Promise<void>;
@@ -91,6 +93,8 @@ export declare class AlterTableModifyColumnBuilder implements ColumnDefinitionBu
     notNull(): AlterTableModifyColumnBuilder;
     defaultTo(value: PrimitiveValue | AnyRawBuilder): AlterTableModifyColumnBuilder;
     check(sql: string): AlterTableModifyColumnBuilder;
+    generatedAlwaysAs(sql: string): AlterTableModifyColumnBuilder;
+    stored(): AlterTableModifyColumnBuilder;
     toOperationNode(): AlterTableNode;
     compile(): CompiledQuery;
     execute(): Promise<void>;

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

@@ -238,6 +238,18 @@ export class AlterTableAddColumnBuilder {
             columnBuilder: this.#props.columnBuilder.check(sql),
         });
     }
+    generatedAlwaysAs(sql) {
+        return new AlterTableAddColumnBuilder({
+            ...this.#props,
+            columnBuilder: this.#props.columnBuilder.generatedAlwaysAs(sql),
+        });
+    }
+    stored() {
+        return new AlterTableAddColumnBuilder({
+            ...this.#props,
+            columnBuilder: this.#props.columnBuilder.stored(),
+        });
+    }
     toOperationNode() {
         return this.#props.executor.transformQuery(AlterTableNode.cloneWith(this.#props.alterTableNode, {
             addColumn: AddColumnNode.create(this.#props.columnBuilder.toOperationNode()),
@@ -309,6 +321,18 @@ export class AlterTableModifyColumnBuilder {
             columnBuilder: this.#props.columnBuilder.check(sql),
         });
     }
+    generatedAlwaysAs(sql) {
+        return new AlterTableModifyColumnBuilder({
+            ...this.#props,
+            columnBuilder: this.#props.columnBuilder.generatedAlwaysAs(sql),
+        });
+    }
+    stored() {
+        return new AlterTableModifyColumnBuilder({
+            ...this.#props,
+            columnBuilder: this.#props.columnBuilder.stored(),
+        });
+    }
     toOperationNode() {
         return this.#props.executor.transformQuery(AlterTableNode.cloneWith(this.#props.alterTableNode, {
             modifyColumn: ModifyColumnNode.create(this.#props.columnBuilder.toOperationNode()),

package/dist/esm/schema/column-definition-builder.d.ts

@@ -40,10 +40,19 @@ export interface ColumnDefinitionBuilderInterface<R> {
      * column definition (like MySQL 5) you need to call the table level
      * {@link TableBuilder.addForeignKeyConstraint} method instead.
      *
+     * @example
+     * ```ts
+     * col.references('person.id').onDelete('cascade')
+     * ```
      */
     onDelete(onDelete: OnModifyForeignAction): R;
     /**
      * Adds an `on update` constraint for the foreign key column.
+     *
+     * @example
+     * ```ts
+     * col.references('person.id').onUpdate('cascade')
+     * ```
      */
     onUpdate(onUpdate: OnModifyForeignAction): R;
     /**
@@ -78,6 +87,36 @@ export interface ColumnDefinitionBuilderInterface<R> {
      * ```
      */
     check(sql: string): R;
+    /**
+     * Makes the column a generated column using a `generated always as` statement.
+     *
+     * @example
+     * ```ts
+     * db.schema
+     *   .createTable('person')
+     *   .addColumn('full_name', 'varchar(255)',
+     *     (col) => col.generatedAlwaysAs("concat(first_name, ' ', last_name)")
+     *   )
+     *   .execute()
+     * ```
+     */
+    generatedAlwaysAs(sql: string): R;
+    /**
+     * Makes a generated column stored instead of virtual. This method can only
+     * be used with {@link generatedAlwaysAs}
+     *
+     * @example
+     * ```ts
+     * db.schema
+     *   .createTable('person')
+     *   .addColumn('full_name', 'varchar(255)', (col) => col
+     *     .generatedAlwaysAs("concat(first_name, ' ', last_name)")
+     *     .stored()
+     *   )
+     *   .execute()
+     * ```
+     */
+    stored(): R;
 }
 export declare class ColumnDefinitionBuilder implements ColumnDefinitionBuilderInterface<ColumnDefinitionBuilder>, OperationNodeSource {
     #private;
@@ -91,5 +130,7 @@ export declare class ColumnDefinitionBuilder implements ColumnDefinitionBuilderI
     notNull(): ColumnDefinitionBuilder;
     defaultTo(value: DefaultValueExpression): ColumnDefinitionBuilder;
     check(sql: string): ColumnDefinitionBuilder;
+    generatedAlwaysAs(sql: string): ColumnDefinitionBuilder;
+    stored(): ColumnDefinitionBuilder;
     toOperationNode(): ColumnDefinitionNode;
 }

package/dist/esm/schema/column-definition-builder.js

@@ -6,6 +6,8 @@ import { parseStringReference } from '../parser/reference-parser.js';
 import { preventAwait } from '../util/prevent-await.js';
 import { ColumnDefinitionNode } from '../operation-node/column-definition-node.js';
 import { parseDefaultValueExpression, } from '../parser/default-value-parser.js';
+import { GeneratedAlwaysAsNode } from '../operation-node/generated-always-as-node.js';
+import { DefaultValueNode } from '../operation-node/default-value-node.js';
 export class ColumnDefinitionBuilder {
     #node;
     constructor(node) {
@@ -52,7 +54,7 @@ export class ColumnDefinitionBuilder {
     }
     defaultTo(value) {
         return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, {
-            defaultTo: parseDefaultValueExpression(value),
+            defaultTo: DefaultValueNode.create(parseDefaultValueExpression(value)),
         }));
     }
     check(sql) {
@@ -60,6 +62,21 @@ export class ColumnDefinitionBuilder {
             check: CheckConstraintNode.create(sql),
         }));
     }
+    generatedAlwaysAs(sql) {
+        return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, {
+            generatedAlwaysAs: GeneratedAlwaysAsNode.create(sql),
+        }));
+    }
+    stored() {
+        if (!this.#node.generatedAlwaysAs) {
+            throw new Error('stored() can only be called after generatedAlwaysAs');
+        }
+        return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, {
+            generatedAlwaysAs: GeneratedAlwaysAsNode.cloneWith(this.#node.generatedAlwaysAs, {
+                stored: true,
+            }),
+        }));
+    }
     toOperationNode() {
         return this.#node;
     }

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

@@ -27,8 +27,8 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * await db.schema
      *   .createTable('person')
      *   .addColumn('id', 'integer', (col) => col.autoIncrement().primaryKey()),
-     *   .addColumn('first_name', 'varchar(50), (col) => col.notNull())
-     *   .addColumn('last_name', 'varchar')
+     *   .addColumn('first_name', 'varchar(50)', (col) => col.notNull())
+     *   .addColumn('last_name', 'varchar(255)')
      *   .addColumn('bank_balance', 'numeric(8, 2)')
      *   .addColumn('data', db.raw('customtype'))
      *   .addColumn('parent_id', 'integer', (col) =>
@@ -37,11 +37,10 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ```
      *
      * 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:
+     * 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

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

@@ -38,8 +38,8 @@ export class CreateTableBuilder {
      * await db.schema
      *   .createTable('person')
      *   .addColumn('id', 'integer', (col) => col.autoIncrement().primaryKey()),
-     *   .addColumn('first_name', 'varchar(50), (col) => col.notNull())
-     *   .addColumn('last_name', 'varchar')
+     *   .addColumn('first_name', 'varchar(50)', (col) => col.notNull())
+     *   .addColumn('last_name', 'varchar(255)')
      *   .addColumn('bank_balance', 'numeric(8, 2)')
      *   .addColumn('data', db.raw('customtype'))
      *   .addColumn('parent_id', 'integer', (col) =>
@@ -48,11 +48,10 @@ export class CreateTableBuilder {
      * ```
      *
      * 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:
+     * 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

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

@@ -10,6 +10,10 @@ export declare class CreateViewBuilder implements OperationNodeSource, Compilabl
     #private;
     constructor(props: CreateViewBuilderProps);
     materialized(): CreateViewBuilder;
+    /**
+     * Only implemented on some dialects like SQLite. On most dialects, use {@link orReplace}.
+     */
+    ifNotExists(): CreateViewBuilder;
     orReplace(): CreateViewBuilder;
     columns(columns: string[]): CreateViewBuilder;
     as(query: AnyQueryBuilder | AnyRawBuilder): CreateViewBuilder;

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

@@ -28,6 +28,17 @@ export class CreateViewBuilder {
             }),
         });
     }
+    /**
+     * Only implemented on some dialects like SQLite. On most dialects, use {@link orReplace}.
+     */
+    ifNotExists() {
+        return new CreateViewBuilder({
+            ...this.#props,
+            createViewNode: CreateViewNode.cloneWith(this.#props.createViewNode, {
+                ifNotExists: true,
+            }),
+        });
+    }
     orReplace() {
         return new CreateViewBuilder({
             ...this.#props,

package/dist/esm/util/dynamic-import.d.ts

@@ -0,0 +1,2 @@
+export declare function importFunction<T extends Function>(modulePath: string): Promise<T>;
+export declare function importNamedFunction<T extends Function>(modulePath: string, exportName: string): Promise<T>;

package/dist/esm/util/dynamic-import.js

@@ -0,0 +1,27 @@
+import { isFunction, isObject } from './object-utils.js';
+export async function importFunction(modulePath) {
+    const module = await import(modulePath);
+    const errorMessage = `module "${modulePath}" doesn't export a function`;
+    if (isFunction(module)) {
+        return module;
+    }
+    else if (isObject(module) && isFunction(module.default)) {
+        return module.default;
+    }
+    throw new Error(errorMessage);
+}
+export async function importNamedFunction(modulePath, exportName) {
+    const module = await import(modulePath);
+    const errorMessage = `no function export named "${exportName}" found in module "${modulePath}"`;
+    if (!isObject(module)) {
+        throw new Error(errorMessage);
+    }
+    if (isFunction(module[exportName])) {
+        return module[exportName];
+    }
+    else if (isObject(module.default) &&
+        isFunction(module.default[exportName])) {
+        return module.default[exportName];
+    }
+    throw new Error(errorMessage);
+}

package/dist/esm/util/performance-now.d.ts

@@ -0,0 +1 @@
+export declare function performanceNow(): number;

package/dist/esm/util/performance-now.js

@@ -0,0 +1,9 @@
+import { isFunction } from './object-utils.js';
+export function performanceNow() {
+    if (typeof performance !== 'undefined' && isFunction(performance.now)) {
+        return performance.now();
+    }
+    else {
+        return Date.now();
+    }
+}

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

@@ -1,6 +1,9 @@
 import { AliasedRawBuilder, RawBuilder } from '../raw-builder/raw-builder.js';
 import { AliasedQueryBuilder, QueryBuilder } from '../query-builder/query-builder.js';
 import { ExpressionBuilder } from '../query-builder/expression-builder.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';
 /**
  * Given an object type, extracts the union of all value types.
  */
@@ -134,25 +137,11 @@ export declare type QueryBuilderFactory<DB, TB extends keyof DB> = (qb: Expressi
 export declare type AliasedQueryBuilderFactory<DB, TB extends keyof DB> = (qb: ExpressionBuilder<DB, TB>) => AnyAliasedQueryBuilder;
 export declare type RawBuilderFactory<DB, TB extends keyof DB> = (qb: ExpressionBuilder<DB, TB>) => AnyRawBuilder;
 export declare type AliasedRawBuilderFactory<DB, TB extends keyof DB> = (qb: ExpressionBuilder<DB, TB>) => AnyAliasedRawBuilder;
-export interface InsertResultTypeTag {
-    /** @internal */
-    readonly __isInsertResultTypeTag__: true;
-}
-export interface DeleteResultTypeTag {
-    /** @internal */
-    readonly __isDeleteResultTypeTag__: true;
-}
-export interface UpdateResultTypeTag {
-    /** @internal */
-    readonly __isUpdateResultTypeTag__: true;
-}
 export interface GeneratedPlaceholder {
     /** @internal */
     readonly __isGeneratedPlaceholder__: true;
 }
-export declare type ManyResultRowType<O> = O extends InsertResultTypeTag ? number | undefined : O extends DeleteResultTypeTag ? number : O extends UpdateResultTypeTag ? number : O;
-export declare type SingleResultRowType<O> = O extends InsertResultTypeTag ? number | undefined : O extends DeleteResultTypeTag ? number : O extends UpdateResultTypeTag ? number : O | undefined;
-export declare type NonEmptySingleResultRowType<O> = O extends InsertResultTypeTag ? number : O extends DeleteResultTypeTag ? number : O extends UpdateResultTypeTag ? number : O;
+export declare type SingleResultType<O> = O extends InsertResult ? O : O extends DeleteResult ? O : O extends UpdateResult ? O : O | undefined;
 export declare type UnknownRow = Record<string, unknown>;
 export declare type Nullable<T> = {
     [P in keyof T]: T[P] | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely",
-  "version": "0.10.0",
+  "version": "0.11.2",
   "description": "Type safe SQL query builder",
   "repository": {
     "type": "git",
@@ -38,18 +38,20 @@
     "@types/node": "^16.11.9"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.4.1",
     "@types/chai": "^4.2.22",
     "@types/chai-subset": "^1.3.3",
     "@types/mocha": "^9.0.0",
     "@types/pg": "^8.6.1",
+    "better-sqlite3": "^7.4.5",
     "chai": "^4.3.4",
     "chai-subset": "^1.6.0",
     "mocha": "^9.1.3",
     "mysql2": "^2.3.3",
     "pg": "^8.7.1",
-    "prettier": "^2.4.1",
+    "prettier": "^2.5.1",
     "tsd": "^0.19.0",
-    "typedoc": "^0.22.9",
+    "typedoc": "^0.22.10",
     "typescript": "4.5.2"
   }
 }