kysely 0.23.5 → 0.24.0

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

@@ -77,6 +77,13 @@ export class CreateViewBuilder {
             }),
         });
     }
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call(func) {
+        return func(this);
+    }
     toOperationNode() {
         return this.#props.executor.transformQuery(this.#props.node, this.#props.queryId);
     }

package/dist/esm/schema/drop-index-builder.d.ts

@@ -14,6 +14,11 @@ export declare class DropIndexBuilder implements OperationNodeSource, Compilable
     on(table: string): DropIndexBuilder;
     ifExists(): DropIndexBuilder;
     cascade(): DropIndexBuilder;
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call<T>(func: (qb: this) => T): T;
     toOperationNode(): DropIndexNode;
     compile(): CompiledQuery;
     execute(): Promise<void>;

package/dist/esm/schema/drop-index-builder.js

@@ -36,6 +36,13 @@ export class DropIndexBuilder {
             }),
         });
     }
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call(func) {
+        return func(this);
+    }
     toOperationNode() {
         return this.#props.executor.transformQuery(this.#props.node, this.#props.queryId);
     }

package/dist/esm/schema/drop-schema-builder.d.ts

@@ -9,6 +9,11 @@ export declare class DropSchemaBuilder implements OperationNodeSource, Compilabl
     constructor(props: DropSchemaBuilderProps);
     ifExists(): DropSchemaBuilder;
     cascade(): DropSchemaBuilder;
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call<T>(func: (qb: this) => T): T;
     toOperationNode(): DropSchemaNode;
     compile(): CompiledQuery;
     execute(): Promise<void>;

package/dist/esm/schema/drop-schema-builder.js

@@ -23,6 +23,13 @@ export class DropSchemaBuilder {
             }),
         });
     }
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call(func) {
+        return func(this);
+    }
     toOperationNode() {
         return this.#props.executor.transformQuery(this.#props.node, this.#props.queryId);
     }

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

@@ -9,6 +9,11 @@ export declare class DropTableBuilder implements OperationNodeSource, Compilable
     constructor(props: DropTableBuilderProps);
     ifExists(): DropTableBuilder;
     cascade(): DropTableBuilder;
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call<T>(func: (qb: this) => T): T;
     toOperationNode(): DropTableNode;
     compile(): CompiledQuery;
     execute(): Promise<void>;

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

@@ -23,6 +23,13 @@ export class DropTableBuilder {
             }),
         });
     }
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call(func) {
+        return func(this);
+    }
     toOperationNode() {
         return this.#props.executor.transformQuery(this.#props.node, this.#props.queryId);
     }

package/dist/esm/schema/drop-type-builder.d.ts

@@ -8,6 +8,11 @@ export declare class DropTypeBuilder implements OperationNodeSource, Compilable
     #private;
     constructor(props: DropTypeBuilderProps);
     ifExists(): DropTypeBuilder;
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call<T>(func: (qb: this) => T): T;
     toOperationNode(): DropTypeNode;
     compile(): CompiledQuery;
     execute(): Promise<void>;

package/dist/esm/schema/drop-type-builder.js

@@ -15,6 +15,13 @@ export class DropTypeBuilder {
             }),
         });
     }
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call(func) {
+        return func(this);
+    }
     toOperationNode() {
         return this.#props.executor.transformQuery(this.#props.node, this.#props.queryId);
     }

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

@@ -10,6 +10,11 @@ export declare class DropViewBuilder implements OperationNodeSource, Compilable
     materialized(): DropViewBuilder;
     ifExists(): DropViewBuilder;
     cascade(): DropViewBuilder;
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call<T>(func: (qb: this) => T): T;
     toOperationNode(): DropViewNode;
     compile(): CompiledQuery;
     execute(): Promise<void>;

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

@@ -31,6 +31,13 @@ export class DropViewBuilder {
             }),
         });
     }
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call(func) {
+        return func(this);
+    }
     toOperationNode() {
         return this.#props.executor.transformQuery(this.#props.node, this.#props.queryId);
     }

package/dist/esm/schema/foreign-key-constraint-builder.d.ts

@@ -10,5 +10,10 @@ export declare class ForeignKeyConstraintBuilder implements ForeignKeyConstraint
     constructor(node: ForeignKeyConstraintNode);
     onDelete(onDelete: OnModifyForeignAction): ForeignKeyConstraintBuilder;
     onUpdate(onUpdate: OnModifyForeignAction): ForeignKeyConstraintBuilder;
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call<T>(func: (qb: this) => T): T;
     toOperationNode(): ForeignKeyConstraintNode;
 }

package/dist/esm/schema/foreign-key-constraint-builder.js

@@ -17,6 +17,13 @@ export class ForeignKeyConstraintBuilder {
             onUpdate: parseOnModifyForeignAction(onUpdate),
         }));
     }
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call(func) {
+        return func(this);
+    }
     toOperationNode() {
         return this.#node;
     }

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

@@ -2,3 +2,4 @@ import { CompiledQuery } from '../query-compiler/compiled-query.js';
 export interface Compilable<O = unknown> {
     compile(): CompiledQuery<O>;
 }
+export declare function isCompilable(value: unknown): value is Compilable;

package/dist/esm/util/compilable.js

@@ -1,2 +1,5 @@
 /// <reference types="./compilable.d.ts" />
-export {};
+import { isFunction, isObject } from './object-utils.js';
+export function isCompilable(value) {
+    return isObject(value) && isFunction(value.compile);
+}

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

@@ -1,5 +1,40 @@
 import { Expression } from '../expression/expression.js';
 export declare type ExplainFormat = 'text' | 'xml' | 'json' | 'yaml' | 'traditional' | 'tree';
 export interface Explainable {
+    /**
+     * Executes query with `explain` statement before the main query.
+     *
+     * ```ts
+     * const explained = await db
+     *  .selectFrom('person')
+     *  .where('gender', '=', 'female')
+     *  .selectAll()
+     *  .explain('json')
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * explain format=json select * from `person` where `gender` = ?
+     * ```
+     *
+     * You can also execute `explain analyze` statements.
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const explained = await db
+     *  .selectFrom('person')
+     *  .where('gender', '=', 'female')
+     *  .selectAll()
+     *  .explain('json', sql`analyze`)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * explain (analyze, format json) select * from "person" where "gender" = $1
+     * ```
+     */
     explain<O extends Record<string, any> = Record<string, any>>(format?: ExplainFormat, options?: Expression<any>): Promise<O[]>;
 }

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

@@ -10,6 +10,8 @@ export interface QueryLogEvent {
 export interface ErrorLogEvent {
     readonly level: 'error';
     readonly error: unknown;
+    readonly query: CompiledQuery;
+    readonly queryDurationMillis: number;
 }
 export declare type LogEvent = QueryLogEvent | ErrorLogEvent;
 export declare type Logger = (event: LogEvent) => void;

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

@@ -9,7 +9,7 @@ export function isEmpty(obj) {
     return false;
 }
 export function isUndefined(obj) {
-    return obj === undefined;
+    return typeof obj === 'undefined' || obj === undefined;
 }
 export function isString(obj) {
     return typeof obj === 'string';

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

@@ -0,0 +1,29 @@
+export interface Streamable<O> {
+    /**
+     * Executes the query and streams the rows.
+     *
+     * The optional argument `chunkSize` defines how many rows to fetch from the database
+     * at a time. It only affects some dialects like PostgreSQL that support it.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const stream = db.
+     *   .selectFrom('person')
+     *   .select(['first_name', 'last_name'])
+     *   .where('gender', '=', 'other')
+     *   .stream()
+     *
+     * for await (const person of stream) {
+     *   console.log(person.first_name)
+     *
+     *   if (person.last_name === 'Something') {
+     *     // Breaking or returning before the stream has ended will release
+     *     // the database connection and invalidate the stream.
+     *     break
+     *   }
+     * }
+     * ```
+     */
+    stream(chunkSize?: number): AsyncIterableIterator<O>;
+}

package/dist/esm/util/streamable.js

@@ -0,0 +1,2 @@
+/// <reference types="./streamable.d.ts" />
+export {};

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

@@ -144,3 +144,4 @@ export declare type IsNever<T> = [T] extends [never] ? true : false;
  * Evaluates to `true` if the types `T` and `U` are equal.
  */
 export declare type Equals<T, U> = (<G>() => G extends T ? 1 : 2) extends <G>() => G extends U ? 1 : 2 ? true : false;
+export declare type SqlBool = boolean | 0 | 1;

package/helpers/postgres.d.ts

@@ -0,0 +1 @@
+export * from '../dist/cjs/helpers/postgres.js'

package/helpers/postgres.js

@@ -0,0 +1 @@
+module.exports = require('../dist/cjs/helpers/postgres.js')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely",
-  "version": "0.23.5",
+  "version": "0.24.0",
   "description": "Type safe SQL query builder",
   "repository": {
     "type": "git",
@@ -14,14 +14,24 @@
   "exports": {
     ".": {
       "import": "./dist/esm/index.js",
-      "require": "./dist/cjs/index.js"
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/cjs/index.js"
+    },
+    "./helpers/postgres": {
+      "import": "./dist/esm/helpers/postgres.js",
+      "require": "./dist/cjs/helpers/postgres.js",
+      "default": "./dist/cjs/helpers/postgres.js"
     }
   },
   "scripts": {
-    "clean": "rm -rf dist && rm -rf test/node/dist && rm -rf test/browser/bundle.js",
-    "test": "npm run clean && npm run build:cjs && npm run script:copy-interface-doc && npm run test:node:build && npm run test:node && npm run test:typings && npm run test:esmimports",
-    "test:node:build": "rm -rf test/node/dist && tsc -p test/node",
-    "test:node": "mocha --timeout 15000 test/node/dist/**/*.test.js",
+    "clean": "rm -rf dist & rm -rf test/node/dist & rm -rf test/browser/bundle.js & rm -rf helpers",
+    "test": "npm run build && npm run test:node:build && concurrently -n node,typings,esmimports \"npm run test:node\" \"npm run test:typings\" \"npm run test:esmimports\"",
+    "test:node:build": "tsc -p test/node",
+    "test:node": "concurrently -n postgres,mysql,sqlite \"npm run test:node:postgres\" \"npm run test:node:mysql\" \"npm run test:node:sqlite\"",
+    "test:node:postgres": "DIALECT=postgres npm run test:node:run",
+    "test:node:mysql": "DIALECT=mysql npm run test:node:run",
+    "test:node:sqlite": "DIALECT=sqlite npm run test:node:run",
+    "test:node:run": "mocha --timeout 15000 test/node/dist/**/*.test.js",
     "test:browser:build": "rm -rf test/browser/bundle.js && esbuild test/browser/main.ts --bundle --outfile=test/browser/bundle.js",
     "test:browser": "npm run build && npm run test:browser:build && node test/browser/test.js",
     "test:deno": "npm run build && deno run test/deno/local.test.ts && deno run test/deno/cdn.test.ts",
@@ -29,7 +39,7 @@
     "test:esmimports": "node scripts/check-esm-imports.js",
     "test:esbuild": "esbuild --bundle --platform=node --external:pg-native dist/esm/index.js --outfile=/dev/null",
     "prettier": "prettier --write 'src/**/*.ts' 'test/**/*.ts'",
-    "build": "npm run clean && npm run build:esm && npm run build:cjs && npm run script:module-fixup && npm run script:copy-interface-doc",
+    "build": "npm run clean && concurrently -n esm,cjs \"npm run build:esm\" \"npm run build:cjs\" && concurrently -n modulefix,docfix \"npm run script:module-fixup\" \"npm run script:copy-interface-doc\"",
     "build:esm": "tsc -p tsconfig.json && npm run script:add-deno-type-references",
     "build:cjs": "tsc -p tsconfig-cjs.json",
     "docs:build": "typedoc --excludePrivate --excludeInternal --customCss ./docs-theme.css src/index.ts && npm run docs:postprocess",
@@ -57,6 +67,7 @@
     "chai": "^4.3.6",
     "chai-as-promised": "^7.1.1",
     "chai-subset": "^1.6.0",
+    "concurrently": "^7.6.0",
     "esbuild": "^0.14.47",
     "mocha": "^10.0.0",
     "mysql2": "^2.3.3",
@@ -66,7 +77,7 @@
     "prettier": "^2.7.1",
     "sinon": "^14.0.0",
     "tsd": "^0.21.0",
-    "typedoc": "^0.23.6",
-    "typescript": "4.7.4"
+    "typedoc": "^0.23.28",
+    "typescript": "5.0.2"
   }
 }

package/dist/cjs/query-builder/expression-builder.d.ts

@@ -1,126 +0,0 @@
-import { SelectQueryBuilder } from './select-query-builder.js';
-import { TableExpression, From, FromTables } from '../parser/table-parser.js';
-import { FunctionModule } from './function-module.js';
-import { ExtractTypeFromReferenceExpression, StringReference } from '../parser/reference-parser.js';
-import { RawBuilder } from '../raw-builder/raw-builder.js';
-import { QueryExecutor } from '../query-executor/query-executor.js';
-export declare class ExpressionBuilder<DB, TB extends keyof DB> {
-    #private;
-    constructor(props: ExpressionBuilderProps);
-    /**
-     * Returns a {@link FunctionModule} that can be used to write type safe function
-     * calls.
-     *
-     * The difference between this and {@link Kysely.fn} is that this one is more
-     * type safe. You can only refer to columns visible to the part of the query
-     * you are building. {@link Kysely.fn} allows you to refer to columns in any
-     * table of the database even if it doesn't produce valid SQL.
-     *
-     * ```ts
-     * await db.selectFrom('person')
-     *   .innerJoin('pet', 'pet.owner_id', 'person.id')
-     *   .select([
-     *     'person.id',
-     *     (qb) => qb.fn.count('pet.id').as('pet_count')
-     *   ])
-     *   .groupBy('person.id')
-     *   .having(count('pet.id'), '>', 10)
-     *   .execute()
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select "person"."id", count("pet"."id") as "pet_count"
-     * from "person"
-     * inner join "pet" on "pet"."owner_id" = "person"."id"
-     * group by "person"."id"
-     * having count("pet"."id") > $1
-     * ```
-     */
-    get fn(): FunctionModule<DB, TB>;
-    /**
-     * Creates a subquery.
-     *
-     * The query builder returned by this method is typed in a way that you can refer to
-     * all tables of the parent query in addition to the subquery's tables.
-     *
-     * This method accepts all the same inputs as {@link QueryCreator.selectFrom}.
-     *
-     * ### Examples
-     *
-     * This example shows that you can refer to both `pet.owner_id` and `person.id`
-     * columns from the subquery. This is needed to be able to create correlated
-     * subqueries:
-     *
-     * ```ts
-     * const result = await db.selectFrom('pet')
-     *   .select([
-     *     'pet.name',
-     *     (qb) => qb.selectFrom('person')
-     *       .whereRef('person.id', '=', 'pet.owner_id')
-     *       .select('person.first_name')
-     *       .as('owner_name')
-     *   ])
-     *   .execute()
-     *
-     * console.log(result[0].owner_name)
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select
-     *   "pet"."name",
-     *   ( select "person"."first_name"
-     *     from "person"
-     *     where "person"."id" = "pet"."owner_id"
-     *   ) as "owner_name"
-     * from "pet"
-     * ```
-     *
-     * You can use a normal query in place of `(qb) => qb.selectFrom(...)` but in
-     * that case Kysely typings wouldn't allow you to reference `pet.owner_id`
-     * because `pet` is not joined to that query.
-     */
-    selectFrom<TE extends TableExpression<DB, TB>>(from: TE[]): SelectQueryBuilder<From<DB, TE>, FromTables<DB, TB, TE>, {}>;
-    selectFrom<TE extends TableExpression<DB, TB>>(from: TE): SelectQueryBuilder<From<DB, TE>, FromTables<DB, TB, TE>, {}>;
-    /**
-     * See {@link QueryCreator.withSchema}
-     */
-    withSchema(schema: string): ExpressionBuilder<DB, TB>;
-    /**
-     * This can be used to reference columns.
-     *
-     * ### Examples
-     *
-     * In the next example we use the `ref` method to reference
-     * columns of the virtual table `excluded` in a type-safe way
-     * to create an upsert operation:
-     *
-     * ```ts
-     * db.insertInto('person')
-     *   .values(person)
-     *   .onConflict(oc => oc
-     *     .column('id')
-     *     .doUpdateSet({
-     *       first_name: (eb) => eb.ref('excluded.first_name'),
-     *       last_name: (eb) => eb.ref('excluded.last_name')
-     *     })
-     *   )
-     * ```
-     *
-     * In the next example we use `ref` in a raw sql expression. Unless you
-     * want to be as type-safe as possible, this is probably overkill:
-     *
-     * ```ts
-     * db.update('pet').set({
-     *   name: (eb) => sql`concat(${eb.ref('pet.name')}, ${suffix})`
-     * })
-     * ```
-     */
-    ref<RE extends StringReference<DB, TB>>(reference: RE): RawBuilder<ExtractTypeFromReferenceExpression<DB, TB, RE>>;
-}
-export interface ExpressionBuilderProps {
-    readonly executor: QueryExecutor;
-}

package/dist/cjs/query-builder/expression-builder.js

@@ -1,107 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ExpressionBuilder = void 0;
-const select_query_builder_js_1 = require("./select-query-builder.js");
-const select_query_node_js_1 = require("../operation-node/select-query-node.js");
-const table_parser_js_1 = require("../parser/table-parser.js");
-const with_schema_plugin_js_1 = require("../plugin/with-schema/with-schema-plugin.js");
-const query_id_js_1 = require("../util/query-id.js");
-const function_module_js_1 = require("./function-module.js");
-const reference_parser_js_1 = require("../parser/reference-parser.js");
-const raw_builder_js_1 = require("../raw-builder/raw-builder.js");
-const object_utils_js_1 = require("../util/object-utils.js");
-const raw_node_js_1 = require("../operation-node/raw-node.js");
-class ExpressionBuilder {
-    #props;
-    constructor(props) {
-        this.#props = (0, object_utils_js_1.freeze)(props);
-    }
-    /**
-     * Returns a {@link FunctionModule} that can be used to write type safe function
-     * calls.
-     *
-     * The difference between this and {@link Kysely.fn} is that this one is more
-     * type safe. You can only refer to columns visible to the part of the query
-     * you are building. {@link Kysely.fn} allows you to refer to columns in any
-     * table of the database even if it doesn't produce valid SQL.
-     *
-     * ```ts
-     * await db.selectFrom('person')
-     *   .innerJoin('pet', 'pet.owner_id', 'person.id')
-     *   .select([
-     *     'person.id',
-     *     (qb) => qb.fn.count('pet.id').as('pet_count')
-     *   ])
-     *   .groupBy('person.id')
-     *   .having(count('pet.id'), '>', 10)
-     *   .execute()
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select "person"."id", count("pet"."id") as "pet_count"
-     * from "person"
-     * inner join "pet" on "pet"."owner_id" = "person"."id"
-     * group by "person"."id"
-     * having count("pet"."id") > $1
-     * ```
-     */
-    get fn() {
-        return new function_module_js_1.FunctionModule();
-    }
-    selectFrom(table) {
-        return new select_query_builder_js_1.SelectQueryBuilder({
-            queryId: (0, query_id_js_1.createQueryId)(),
-            executor: this.#props.executor,
-            queryNode: select_query_node_js_1.SelectQueryNode.create((0, table_parser_js_1.parseTableExpressionOrList)(table)),
-        });
-    }
-    /**
-     * See {@link QueryCreator.withSchema}
-     */
-    withSchema(schema) {
-        return new ExpressionBuilder({
-            ...this.#props,
-            executor: this.#props.executor.withPluginAtFront(new with_schema_plugin_js_1.WithSchemaPlugin(schema)),
-        });
-    }
-    /**
-     * This can be used to reference columns.
-     *
-     * ### Examples
-     *
-     * In the next example we use the `ref` method to reference
-     * columns of the virtual table `excluded` in a type-safe way
-     * to create an upsert operation:
-     *
-     * ```ts
-     * db.insertInto('person')
-     *   .values(person)
-     *   .onConflict(oc => oc
-     *     .column('id')
-     *     .doUpdateSet({
-     *       first_name: (eb) => eb.ref('excluded.first_name'),
-     *       last_name: (eb) => eb.ref('excluded.last_name')
-     *     })
-     *   )
-     * ```
-     *
-     * In the next example we use `ref` in a raw sql expression. Unless you
-     * want to be as type-safe as possible, this is probably overkill:
-     *
-     * ```ts
-     * db.update('pet').set({
-     *   name: (eb) => sql`concat(${eb.ref('pet.name')}, ${suffix})`
-     * })
-     * ```
-     */
-    ref(reference) {
-        return new raw_builder_js_1.RawBuilder({
-            queryId: (0, query_id_js_1.createQueryId)(),
-            plugins: this.#props.executor.plugins,
-            rawNode: raw_node_js_1.RawNode.createWithChild((0, reference_parser_js_1.parseStringReference)(reference)),
-        });
-    }
-}
-exports.ExpressionBuilder = ExpressionBuilder;