kysely 0.19.10 → 0.20.0

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AliasedQueryBuilder = exports.SelectQueryBuilder = void 0;
 const alias_node_js_1 = require("../operation-node/alias-node.js");
+const select_modifier_node_js_1 = require("../operation-node/select-modifier-node.js");
 const join_parser_js_1 = require("../parser/join-parser.js");
 const select_parser_js_1 = require("../parser/select-parser.js");
 const filter_parser_js_1 = require("../parser/filter-parser.js");
@@ -16,7 +17,7 @@ const group_by_parser_js_1 = require("../parser/group-by-parser.js");
 const union_parser_js_1 = require("../parser/union-parser.js");
 const no_result_error_js_1 = require("./no-result-error.js");
 const identifier_node_js_1 = require("../operation-node/identifier-node.js");
-const select_modifier_node_js_1 = require("../operation-node/select-modifier-node.js");
+const explain_node_js_1 = require("../operation-node/explain-node.js");
 class SelectQueryBuilder {
     #props;
     constructor(props) {
@@ -629,9 +630,8 @@ class SelectQueryBuilder {
      * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
      */
     async execute() {
-        const compildQuery = this.compile();
-        const query = compildQuery.query;
-        const result = await this.#props.executor.executeQuery(compildQuery, this.#props.queryId);
+        const compiledQuery = this.compile();
+        const result = await this.#props.executor.executeQuery(compiledQuery, this.#props.queryId);
         return result.rows;
     }
     /**
@@ -657,6 +657,81 @@ class SelectQueryBuilder {
         }
         return result;
     }
+    /**
+     * 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
+     *   }
+     * }
+     * ```
+     */
+    async *stream(chunkSize = 100) {
+        const compildQuery = this.compile();
+        const stream = this.#props.executor.stream(compildQuery, chunkSize, this.#props.queryId);
+        for await (const item of stream) {
+            yield* item.rows;
+        }
+    }
+    /**
+     * Executes query with `explain` statement before `select` keyword.
+     *
+     * ```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
+     * ```
+     */
+    async explain(format, options) {
+        const builder = new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithExplain(this.#props.queryNode, explain_node_js_1.ExplainNode.create(format, options)),
+        });
+        return await builder.execute();
+    }
 }
 exports.SelectQueryBuilder = SelectQueryBuilder;
 (0, prevent_await_js_1.preventAwait)(SelectQueryBuilder, "don't await SelectQueryBuilder instances directly. To execute the query you need to call `execute` or `executeTakeFirst`.");

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

@@ -20,7 +20,8 @@ import { NoResultErrorConstructor } from './no-result-error.js';
 import { Selectable } from '../util/column-type.js';
 import { AliasedQueryBuilder } from './select-query-builder.js';
 import { AliasedRawBuilder } from '../raw-builder/raw-builder.js';
-export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable {
+import { Explainable, ExplainFormat } from '../util/explainable.js';
+export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable, Explainable {
     #private;
     constructor(props: UpdateQueryBuilderProps);
     /**
@@ -809,6 +810,24 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * error.
      */
     executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<O>;
+    /**
+     * Executes query with `explain` statement before `update` keyword.
+     *
+     * ```ts
+     * const explained = await db
+     *  .updateTable('person')
+     *  .set(updates)
+     *  .where('id', '=', 123)
+     *  .explain('json')
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * explain format=json update `person` set `first_name` = ?, `last_name` = ? where `id` = ?
+     * ```
+     */
+    explain<ER extends Record<string, any> = Record<string, any>>(format?: ExplainFormat, options?: AnyRawBuilder): Promise<ER[]>;
 }
 export interface UpdateQueryBuilderProps {
     readonly queryId: QueryId;

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

@@ -12,6 +12,7 @@ const prevent_await_js_1 = require("../util/prevent-await.js");
 const object_utils_js_1 = require("../util/object-utils.js");
 const update_result_js_1 = require("./update-result.js");
 const no_result_error_js_1 = require("./no-result-error.js");
+const explain_node_js_1 = require("../operation-node/explain-node.js");
 class UpdateQueryBuilder {
     #props;
     constructor(props) {
@@ -332,6 +333,30 @@ class UpdateQueryBuilder {
         }
         return result;
     }
+    /**
+     * Executes query with `explain` statement before `update` keyword.
+     *
+     * ```ts
+     * const explained = await db
+     *  .updateTable('person')
+     *  .set(updates)
+     *  .where('id', '=', 123)
+     *  .explain('json')
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * explain format=json update `person` set `first_name` = ?, `last_name` = ? where `id` = ?
+     * ```
+     */
+    async explain(format, options) {
+        const builder = new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: update_query_node_js_1.UpdateQueryNode.cloneWithExplain(this.#props.queryNode, explain_node_js_1.ExplainNode.create(format, options)),
+        });
+        return await builder.execute();
+    }
 }
 exports.UpdateQueryBuilder = UpdateQueryBuilder;
 (0, prevent_await_js_1.preventAwait)(UpdateQueryBuilder, "don't await UpdateQueryBuilder instances directly. To execute the query you need to call `execute` or `executeTakeFirst`.");

package/dist/cjs/query-compiler/default-query-compiler.d.ts

@@ -71,6 +71,7 @@ import { CommonTableExpressionNameNode } from '../operation-node/common-table-ex
 import { SelectModifierNode } from '../operation-node/select-modifier-node.js';
 import { CreateTypeNode } from '../operation-node/create-type-node.js';
 import { DropTypeNode } from '../operation-node/drop-type-node.js';
+import { ExplainNode } from '../operation-node/explain-node.js';
 export declare class DefaultQueryCompiler extends OperationNodeVisitor implements QueryCompiler {
     #private;
     protected get numParameters(): number;
@@ -149,11 +150,17 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected visitSelectModifier(node: SelectModifierNode): void;
     protected visitCreateType(node: CreateTypeNode): void;
     protected visitDropType(node: DropTypeNode): void;
+    protected visitExplain(node: ExplainNode): void;
     protected append(str: string): void;
     protected appendValue(parameter: unknown): void;
     protected getLeftIdentifierWrapper(): string;
     protected getRightIdentifierWrapper(): string;
     protected getCurrentParameterPlaceholder(): string;
+    protected getLeftExplainOptionsWrapper(): string;
+    protected getExplainOptionAssignment(): string;
+    protected getExplainOptionsDelimiter(): string;
+    protected getRightExplainOptionsWrapper(): string;
+    protected sanitizeIdentifier(identifier: string): string;
     protected addParameter(parameter: unknown): void;
     protected appendImmediateValue(value: unknown): void;
 }

package/dist/cjs/query-compiler/default-query-compiler.js

@@ -32,6 +32,10 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
             !insert_query_node_js_1.InsertQueryNode.is(this.parentNode) &&
             !create_view_node_js_1.CreateViewNode.is(this.parentNode) &&
             !union_node_js_1.UnionNode.is(this.parentNode);
+        if (this.parentNode === undefined && node.explain) {
+            this.visitNode(node.explain);
+            this.append(' ');
+        }
         if (wrapInParens) {
             this.append('(');
         }
@@ -127,6 +131,10 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
     }
     visitInsertQuery(node) {
         const isSubQuery = this.nodeStack.find(query_node_js_1.QueryNode.is) !== node;
+        if (!isSubQuery && node.explain) {
+            this.visitNode(node.explain);
+            this.append(' ');
+        }
         if (isSubQuery) {
             this.append('(');
         }
@@ -134,7 +142,7 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
             this.visitNode(node.with);
             this.append(' ');
         }
-        this.append('insert');
+        this.append(node.replace ? 'replace' : 'insert');
         if (node.ignore) {
             this.append(' ignore');
         }
@@ -171,6 +179,10 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
     }
     visitDeleteQuery(node) {
         const isSubQuery = this.nodeStack.find(query_node_js_1.QueryNode.is) !== node;
+        if (!isSubQuery && node.explain) {
+            this.visitNode(node.explain);
+            this.append(' ');
+        }
         if (isSubQuery) {
             this.append('(');
         }
@@ -227,7 +239,10 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
         this.append(this.getRightIdentifierWrapper());
     }
     compileUnwrappedIdentifier(node) {
-        this.append(node.identifier);
+        if (!(0, object_utils_js_1.isString)(node.identifier)) {
+            throw new Error('a non-string identifier was passed to compileUnwrappedIdentifier.');
+        }
+        this.append(this.sanitizeIdentifier(node.identifier));
     }
     visitFilter(node) {
         if (node.left) {
@@ -311,6 +326,10 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
     }
     visitCreateTable(node) {
         this.append('create ');
+        if (node.frontModifiers) {
+            this.compileList(node.frontModifiers, ' ');
+            this.append(' ');
+        }
         if (node.temporary) {
             this.append('temporary ');
         }
@@ -326,6 +345,10 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
             this.append(' on commit ');
             this.append(node.onCommit);
         }
+        if (node.endModifiers) {
+            this.append(' ');
+            this.compileList(node.endModifiers, ' ');
+        }
     }
     visitColumnDefinition(node) {
         this.visitNode(node.column);
@@ -412,6 +435,10 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
     }
     visitUpdateQuery(node) {
         const isSubQuery = this.nodeStack.find(query_node_js_1.QueryNode.is) !== node;
+        if (!isSubQuery && node.explain) {
+            this.visitNode(node.explain);
+            this.append(' ');
+        }
         if (isSubQuery) {
             this.append('(');
         }
@@ -806,6 +833,25 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
         }
         this.visitNode(node.name);
     }
+    visitExplain(node) {
+        this.append('explain');
+        if (node.options || node.format) {
+            this.append(' ');
+            this.append(this.getLeftExplainOptionsWrapper());
+            if (node.options) {
+                this.visitNode(node.options);
+                if (node.format) {
+                    this.append(this.getExplainOptionsDelimiter());
+                }
+            }
+            if (node.format) {
+                this.append('format');
+                this.append(this.getExplainOptionAssignment());
+                this.append(node.format);
+            }
+            this.append(this.getRightExplainOptionsWrapper());
+        }
+    }
     append(str) {
         this.#sql += str;
     }
@@ -822,6 +868,33 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
     getCurrentParameterPlaceholder() {
         return '$' + this.numParameters;
     }
+    getLeftExplainOptionsWrapper() {
+        return '(';
+    }
+    getExplainOptionAssignment() {
+        return ' ';
+    }
+    getExplainOptionsDelimiter() {
+        return ', ';
+    }
+    getRightExplainOptionsWrapper() {
+        return ')';
+    }
+    sanitizeIdentifier(identifier) {
+        const leftWrap = this.getLeftIdentifierWrapper();
+        const rightWrap = this.getRightIdentifierWrapper();
+        let sanitized = '';
+        for (const c of identifier) {
+            sanitized += c;
+            if (c === leftWrap) {
+                sanitized += leftWrap;
+            }
+            else if (c === rightWrap) {
+                sanitized += rightWrap;
+            }
+        }
+        return sanitized;
+    }
     addParameter(parameter) {
         this.#parameters.push(parameter);
     }

package/dist/cjs/query-creator.d.ts

@@ -161,6 +161,33 @@ export declare class QueryCreator<DB> {
      * ```
      */
     insertInto<T extends keyof DB & string>(table: T): InsertQueryBuilder<DB, T, InsertResult>;
+    /**
+     * Creates a replace query.
+     *
+     * A MySQL-only statement similar to {@link InsertQueryBuilder.onDuplicateKeyUpdate}
+     * that deletes and inserts values on collision instead of updating existing rows.
+     *
+     * 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 InsertQueryBuilder.values | values} method for more info and examples.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const result = await db
+     *   .replaceInto('person')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .executeTakeFirst()
+     *
+     * console.log(result.insertId)
+     * ```
+     */
+    replaceInto<T extends keyof DB & string>(table: T): InsertQueryBuilder<DB, T, InsertResult>;
     /**
      * Creates a delete query.
      *

package/dist/cjs/query-creator.js

@@ -72,6 +72,39 @@ class QueryCreator {
             queryNode: insert_query_node_js_1.InsertQueryNode.create((0, table_parser_js_1.parseTable)(table), this.#props.withNode),
         });
     }
+    /**
+     * Creates a replace query.
+     *
+     * A MySQL-only statement similar to {@link InsertQueryBuilder.onDuplicateKeyUpdate}
+     * that deletes and inserts values on collision instead of updating existing rows.
+     *
+     * 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 InsertQueryBuilder.values | values} method for more info and examples.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const result = await db
+     *   .replaceInto('person')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .executeTakeFirst()
+     *
+     * console.log(result.insertId)
+     * ```
+     */
+    replaceInto(table) {
+        return new insert_query_builder_js_1.InsertQueryBuilder({
+            queryId: (0, query_id_js_1.createQueryId)(),
+            executor: this.#props.executor,
+            queryNode: insert_query_node_js_1.InsertQueryNode.create((0, table_parser_js_1.parseTable)(table), this.#props.withNode, true),
+        });
+    }
     /**
      * Creates a delete query.
      *

package/dist/cjs/query-executor/query-executor-base.d.ts

@@ -36,6 +36,12 @@ export declare abstract class QueryExecutorBase implements QueryExecutor {
      * `transformResult` method.
      */
     executeQuery<R>(compiledQuery: CompiledQuery, queryId: QueryId): Promise<QueryResult<R>>;
+    /**
+     * Executes a compiled query and runs the result through all plugins'
+     * `transformResult` method. Results are streamead instead of loaded
+     * at once.
+     */
+    stream<R>(compiledQuery: CompiledQuery, chunkSize: number, queryId: QueryId): AsyncIterableIterator<QueryResult<R>>;
     /**
      * Returns a copy of this executor with a new connection provider.
      */

package/dist/cjs/query-executor/query-executor-base.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueryExecutorBase = void 0;
 const object_utils_js_1 = require("../util/object-utils.js");
+const deferred_js_1 = require("../util/deferred.js");
 const NO_PLUGINS = (0, object_utils_js_1.freeze)([]);
 class QueryExecutorBase {
     #plugins;
@@ -36,6 +37,24 @@ class QueryExecutorBase {
             return this.#transformResult(result, queryId);
         });
     }
+    async *stream(compiledQuery, chunkSize, queryId) {
+        const connectionDefer = new deferred_js_1.Deferred();
+        const connectionReleaseDefer = new deferred_js_1.Deferred();
+        this.provideConnection(async (connection) => {
+            connectionDefer.resolve(connection);
+            // Lets wait until we don't need connection before returning here (returning releases connection)
+            return await connectionReleaseDefer.promise;
+        }).catch((ex) => connectionDefer.reject(ex));
+        const connection = await connectionDefer.promise;
+        try {
+            for await (const result of connection.streamQuery(compiledQuery, chunkSize)) {
+                yield await this.#transformResult(result, queryId);
+            }
+        }
+        finally {
+            connectionReleaseDefer.resolve();
+        }
+    }
     async #transformResult(result, queryId) {
         for (const plugin of this.#plugins) {
             result = await plugin.transformResult({ result, queryId });

package/dist/cjs/query-executor/query-executor.d.ts

@@ -37,6 +37,17 @@ export interface QueryExecutor extends ConnectionProvider {
      * `transformResult` method.
      */
     executeQuery<R>(compiledQuery: CompiledQuery, queryId: QueryId): Promise<QueryResult<R>>;
+    /**
+     * Executes a compiled query and runs the result through all plugins'
+     * `transformResult` method. Results are streamead instead of loaded
+     * at once.
+     */
+    stream<R>(compiledQuery: CompiledQuery, 
+    /**
+     * How many rows should be pulled from the database at once. Supported
+     * only by the postgres driver.
+     */
+    chunkSize: number, queryId: QueryId): AsyncIterableIterator<QueryResult<R>>;
     /**
      * Returns a copy of this executor with a new connection provider.
      */