kysely 0.28.17 → 0.29.0

package/dist/query-executor/default-query-executor.js

@@ -0,0 +1,37 @@
+/// <reference types="./default-query-executor.d.ts" />
+import { QueryExecutorBase } from './query-executor-base.js';
+export class DefaultQueryExecutor extends QueryExecutorBase {
+    #compiler;
+    #adapter;
+    #connectionProvider;
+    constructor(compiler, adapter, connectionProvider, plugins = []) {
+        super(plugins);
+        this.#compiler = compiler;
+        this.#adapter = adapter;
+        this.#connectionProvider = connectionProvider;
+    }
+    get adapter() {
+        return this.#adapter;
+    }
+    compileQuery(node, queryId) {
+        return this.#compiler.compileQuery(node, queryId);
+    }
+    provideConnection(consumer, options) {
+        return this.#connectionProvider.provideConnection(consumer, options);
+    }
+    withPlugins(plugins) {
+        return new DefaultQueryExecutor(this.#compiler, this.#adapter, this.#connectionProvider, [...this.plugins, ...plugins]);
+    }
+    withPlugin(plugin) {
+        return new DefaultQueryExecutor(this.#compiler, this.#adapter, this.#connectionProvider, [...this.plugins, plugin]);
+    }
+    withPluginAtFront(plugin) {
+        return new DefaultQueryExecutor(this.#compiler, this.#adapter, this.#connectionProvider, [plugin, ...this.plugins]);
+    }
+    withConnectionProvider(connectionProvider) {
+        return new DefaultQueryExecutor(this.#compiler, this.#adapter, connectionProvider, [...this.plugins]);
+    }
+    withoutPlugins() {
+        return new DefaultQueryExecutor(this.#compiler, this.#adapter, this.#connectionProvider, []);
+    }
+}

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

@@ -0,0 +1,69 @@
+import type { ConnectionProvider } from '../driver/connection-provider.js';
+import type { DatabaseConnection, QueryResult } from '../driver/database-connection.js';
+import type { CompiledQuery } from '../query-compiler/compiled-query.js';
+import type { KyselyPlugin } from '../plugin/kysely-plugin.js';
+import type { QueryId } from '../util/query-id.js';
+import type { DialectAdapter } from '../dialect/dialect-adapter.js';
+import type { QueryExecutor } from './query-executor.js';
+import { type AbortableOperationOptions, type AbortableQueryOptions } from '../util/abort.js';
+import type { RootOperationNode } from '../operation-node/root-operation-node.js';
+export declare abstract class QueryExecutorBase implements QueryExecutor {
+    #private;
+    constructor(plugins?: ReadonlyArray<KyselyPlugin>);
+    abstract get adapter(): DialectAdapter;
+    /**
+     * Returns all installed plugins.
+     */
+    get plugins(): ReadonlyArray<KyselyPlugin>;
+    /**
+     * Given the query the user has built (expressed as an operation node tree)
+     * this method runs it through all plugins' `transformQuery` methods and
+     * returns the result.
+     */
+    transformQuery<T extends RootOperationNode>(node: T, queryId: QueryId): T;
+    /**
+     * Compiles the transformed query into SQL. You usually want to pass
+     * the output of {@link transformQuery} into this method but you can
+     * compile any query using this method.
+     */
+    abstract compileQuery(node: RootOperationNode, queryId: QueryId): CompiledQuery;
+    /**
+     * Provides a connection for the callback and takes care of disposing
+     * the connection after the callback has been run.
+     */
+    abstract provideConnection<T>(consumer: (connection: DatabaseConnection) => Promise<T>, options?: AbortableOperationOptions): Promise<T>;
+    /**
+     * Executes a compiled query and runs the result through all plugins'
+     * `transformResult` method.
+     */
+    executeQuery<R>(compiledQuery: CompiledQuery, options?: AbortableQueryOptions): 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, options?: AbortableOperationOptions): AsyncIterableIterator<QueryResult<R>>;
+    /**
+     * Returns a copy of this executor with a new connection provider.
+     */
+    abstract withConnectionProvider(connectionProvider: ConnectionProvider): QueryExecutorBase;
+    /**
+     * Returns a copy of this executor with a plugin added as the
+     * last plugin.
+     */
+    abstract withPlugin(plugin: KyselyPlugin): QueryExecutorBase;
+    /**
+     * Returns a copy of this executor with a list of plugins added
+     * as the last plugins.
+     */
+    abstract withPlugins(plugin: ReadonlyArray<KyselyPlugin>): QueryExecutorBase;
+    /**
+     * Returns a copy of this executor with a plugin added as the
+     * first plugin.
+     */
+    abstract withPluginAtFront(plugin: KyselyPlugin): QueryExecutorBase;
+    /**
+     * Returns a copy of this executor without any plugins.
+     */
+    abstract withoutPlugins(): QueryExecutorBase;
+}

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

@@ -0,0 +1,173 @@
+/// <reference types="./query-executor-base.d.ts" />
+import { freeze } from '../util/object-utils.js';
+import { provideControlledConnection } from '../util/provide-controlled-connection.js';
+import { ABORTED, assertNotAborted, getInflightQueryAbortHandler, printBackgroundFail, throwReasonWithTiming, } from '../util/abort.js';
+import { Deferred } from '../util/deferred.js';
+const NO_PLUGINS = freeze([]);
+export class QueryExecutorBase {
+    #plugins;
+    constructor(plugins = NO_PLUGINS) {
+        this.#plugins = plugins;
+    }
+    get plugins() {
+        return this.#plugins;
+    }
+    transformQuery(node, queryId) {
+        for (const plugin of this.#plugins) {
+            const transformedNode = plugin.transformQuery({ node, queryId });
+            // We need to do a runtime check here. There is no good way
+            // to write types that enforce this constraint.
+            if (transformedNode.kind === node.kind) {
+                node = transformedNode;
+            }
+            else {
+                throw new Error([
+                    `KyselyPlugin.transformQuery must return a node`,
+                    `of the same kind that was given to it.`,
+                    `The plugin was given a ${node.kind}`,
+                    `but it returned a ${transformedNode.kind}`,
+                ].join(' '));
+            }
+        }
+        return node;
+    }
+    async executeQuery(compiledQuery, options) {
+        const { inflightQueryAbortStrategy = 'ignore query', signal } = options || {};
+        // intentionally isolating the simple common case from the new cancellation flow.
+        if (!signal) {
+            const result = await this.provideConnection(async (connection) => {
+                return await connection.executeQuery(compiledQuery);
+            }, options);
+            return await this.#transformResult(result, compiledQuery.queryId);
+        }
+        assertNotAborted(signal, 'before query execution');
+        options = freeze({ signal });
+        const { connection, release } = await provideControlledConnection(this, options);
+        const controlConnectionProvider = this.provideConnection.bind(this);
+        const { promise: abortPromise, resolve } = new Deferred();
+        const abortListener = () => resolve(ABORTED);
+        signal.addEventListener('abort', abortListener, { once: true });
+        try {
+            assertNotAborted(signal, 'before query execution', release);
+            const inflightQueryAbortHandler = getInflightQueryAbortHandler(inflightQueryAbortStrategy, connection, release);
+            if (inflightQueryAbortHandler && connection.collectSessionInfo) {
+                assertNotAborted(signal, 'before query execution', release);
+                const collectPromise = connection.collectSessionInfo();
+                const result = await Promise.race([abortPromise, collectPromise]).catch((error) => {
+                    release();
+                    throw error;
+                });
+                if (result === ABORTED) {
+                    void collectPromise
+                        .catch(printBackgroundFail('collectSessionInfo'))
+                        .finally(release);
+                    throwReasonWithTiming(signal.reason, 'before query execution');
+                }
+            }
+            const queryPromise = connection.executeQuery(compiledQuery, options);
+            const result = await Promise.race([abortPromise, queryPromise])
+                // only the query can error. in that case, we want to release immediately.
+                .catch((error) => {
+                release();
+                throw error;
+            });
+            if (result === ABORTED) {
+                void Promise.allSettled([
+                    queryPromise.catch(printBackgroundFail('query')),
+                    inflightQueryAbortHandler?.(controlConnectionProvider).catch(printBackgroundFail('inflightQueryAbortHandler')),
+                ])
+                    // the abort handler might use the same connection that runs the query.
+                    .finally(release);
+                throwReasonWithTiming(signal.reason, 'during query execution');
+            }
+            else {
+                release();
+            }
+            const transformPromise = this.#transformResult(result, compiledQuery.queryId, options);
+            const transformedResult = await Promise.race([
+                abortPromise,
+                transformPromise,
+            ]);
+            if (transformedResult === ABORTED) {
+                transformPromise.catch(printBackgroundFail('plugins.transformResult'));
+                throwReasonWithTiming(signal.reason, 'during result transformation');
+            }
+            return transformedResult;
+        }
+        finally {
+            resolve(ABORTED);
+            signal.removeEventListener('abort', abortListener);
+        }
+    }
+    async *stream(compiledQuery, chunkSize, options) {
+        const { signal } = options || {};
+        if (!signal) {
+            const { connection, release } = await provideControlledConnection(this);
+            try {
+                for await (const result of connection.streamQuery(compiledQuery, chunkSize)) {
+                    yield await this.#transformResult(result, compiledQuery.queryId, options);
+                }
+            }
+            finally {
+                release();
+            }
+            return;
+        }
+        options = freeze({ signal });
+        assertNotAborted(signal, 'before connection acquisition');
+        const { connection, release } = await provideControlledConnection(this, options);
+        const { promise: abortPromise, resolve } = new Deferred();
+        const abortListener = () => resolve(ABORTED);
+        signal.addEventListener('abort', abortListener, { once: true });
+        let asyncIterator;
+        let releasePrerequisite;
+        assertNotAborted(signal, 'before query streaming', release);
+        const { queryId } = compiledQuery;
+        try {
+            asyncIterator = connection.streamQuery(compiledQuery, chunkSize, options);
+            while (true) {
+                assertNotAborted(signal, 'during query streaming');
+                const nextPromise = asyncIterator.next();
+                const result = await Promise.race([abortPromise, nextPromise]);
+                if (result === ABORTED) {
+                    releasePrerequisite = nextPromise.catch(printBackgroundFail('iterator.next'));
+                    throwReasonWithTiming(signal.reason, 'during query streaming');
+                }
+                if (result.done) {
+                    break;
+                }
+                const transformPromise = this.#transformResult(result.value, queryId, options);
+                const transformedResult = await Promise.race([
+                    abortPromise,
+                    transformPromise,
+                ]);
+                if (transformedResult === ABORTED) {
+                    releasePrerequisite = transformPromise.catch(printBackgroundFail('plugins.transformResult'));
+                    throwReasonWithTiming(signal.reason, 'during result transformation');
+                }
+                yield transformedResult;
+            }
+        }
+        finally {
+            resolve(ABORTED);
+            signal.removeEventListener('abort', abortListener);
+            const cleanup = (asyncIterator?.return?.() || Promise.resolve())
+                .finally(() => releasePrerequisite)
+                .finally(release);
+            if (!releasePrerequisite) {
+                await cleanup;
+            }
+        }
+    }
+    async #transformResult(result, queryId, options) {
+        const args = freeze({
+            queryId,
+            result,
+            signal: options?.signal,
+        });
+        for (const plugin of this.#plugins) {
+            result = await plugin.transformResult(args);
+        }
+        return result;
+    }
+}

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

@@ -0,0 +1,75 @@
+import type { ConnectionProvider } from '../driver/connection-provider.js';
+import type { QueryResult } from '../driver/database-connection.js';
+import type { CompiledQuery } from '../query-compiler/compiled-query.js';
+import type { KyselyPlugin } from '../plugin/kysely-plugin.js';
+import type { QueryId } from '../util/query-id.js';
+import type { DialectAdapter } from '../dialect/dialect-adapter.js';
+import type { RootOperationNode } from '../operation-node/root-operation-node.js';
+import type { AbortableOperationOptions, AbortableQueryOptions } from '../util/abort.js';
+/**
+ * This interface abstracts away the details of how to compile a query into SQL
+ * and execute it. Instead of passing around all those details, {@link SelectQueryBuilder}
+ * and other classes that execute queries can just pass around and instance of
+ * `QueryExecutor`.
+ */
+export interface QueryExecutor extends ConnectionProvider {
+    /**
+     * Returns the adapter for the current dialect.
+     */
+    get adapter(): DialectAdapter;
+    /**
+     * Returns all installed plugins.
+     */
+    get plugins(): ReadonlyArray<KyselyPlugin>;
+    /**
+     * Given the query the user has built (expressed as an operation node tree)
+     * this method runs it through all plugins' `transformQuery` methods and
+     * returns the result.
+     */
+    transformQuery<T extends RootOperationNode>(node: T, queryId: QueryId): T;
+    /**
+     * Compiles the transformed query into SQL. You usually want to pass
+     * the output of {@link transformQuery} into this method but you can
+     * compile any query using this method.
+     */
+    compileQuery<R = unknown>(node: RootOperationNode, queryId: QueryId): CompiledQuery<R>;
+    /**
+     * Executes a compiled query and runs the result through all plugins'
+     * `transformResult` method.
+     */
+    executeQuery<R>(compiledQuery: CompiledQuery<R>, options?: AbortableQueryOptions): 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<R>, 
+    /**
+     * How many rows should be pulled from the database at once. Supported
+     * only by the postgres driver.
+     */
+    chunkSize: number, options?: AbortableOperationOptions): AsyncIterableIterator<QueryResult<R>>;
+    /**
+     * Returns a copy of this executor with a new connection provider.
+     */
+    withConnectionProvider(connectionProvider: ConnectionProvider): QueryExecutor;
+    /**
+     * Returns a copy of this executor with a plugin added as the
+     * last plugin.
+     */
+    withPlugin(plugin: KyselyPlugin): QueryExecutor;
+    /**
+     * Returns a copy of this executor with a list of plugins added
+     * as the last plugins.
+     */
+    withPlugins(plugin: ReadonlyArray<KyselyPlugin>): QueryExecutor;
+    /**
+     * Returns a copy of this executor with a plugin added as the
+     * first plugin.
+     */
+    withPluginAtFront(plugin: KyselyPlugin): QueryExecutor;
+    /**
+     * Returns a copy of this executor without any plugins.
+     */
+    withoutPlugins(): QueryExecutor;
+}

package/dist/query-finalizer.d.ts

@@ -0,0 +1,27 @@
+import type { QueryResult } from './driver/database-connection.js';
+import type { OperationNodeSource } from './operation-node/operation-node-source.js';
+import type { OperationNode } from './operation-node/operation-node.js';
+import type { RootOperationNode } from './operation-node/root-operation-node.js';
+import type { CompiledQuery } from './query-compiler/compiled-query.js';
+import type { QueryExecutor } from './query-executor/query-executor.js';
+import type { AbortableQueryOptions } from './util/abort.js';
+import type { Compilable } from './util/compilable.js';
+import type { QueryId } from './util/query-id.js';
+export declare class QueryFinalizer<N extends RootOperationNode, O = unknown> implements OperationNodeSource, Compilable {
+    #private;
+    constructor(props: QueryFinalizerProps<N>);
+    toOperationNode(): N;
+    /**
+     * Compiles the query.
+     */
+    compile(): CompiledQuery<O>;
+    /**
+     * Executes the query.
+     */
+    execute(options?: AbortableQueryOptions): Promise<QueryResult<O>>;
+}
+export interface QueryFinalizerProps<N extends OperationNode> {
+    readonly executor: QueryExecutor;
+    readonly node: N;
+    readonly queryId: QueryId;
+}

package/dist/query-finalizer.js

@@ -0,0 +1,23 @@
+/// <reference types="./query-finalizer.d.ts" />
+import { freeze } from './util/object-utils.js';
+export class QueryFinalizer {
+    #props;
+    constructor(props) {
+        this.#props = freeze(props);
+    }
+    toOperationNode() {
+        return this.#props.executor.transformQuery(this.#props.node, this.#props.queryId);
+    }
+    /**
+     * Compiles the query.
+     */
+    compile() {
+        return this.#props.executor.compileQuery(this.toOperationNode(), this.#props.queryId);
+    }
+    /**
+     * Executes the query.
+     */
+    async execute(options) {
+        return await this.#props.executor.executeQuery(this.compile(), options);
+    }
+}

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

@@ -0,0 +1,219 @@
+import type { QueryResult } from '../driver/database-connection.js';
+import type { RawNode } from '../operation-node/raw-node.js';
+import type { CompiledQuery } from '../query-compiler/compiled-query.js';
+import type { KyselyPlugin } from '../plugin/kysely-plugin.js';
+import type { QueryExecutorProvider } from '../query-executor/query-executor-provider.js';
+import type { QueryId } from '../util/query-id.js';
+import type { AliasableExpression, AliasedExpression, Expression } from '../expression/expression.js';
+import type { AbortableQueryOptions } from '../util/abort.js';
+/**
+ * An instance of this class can be used to create raw SQL snippets or queries.
+ *
+ * You shouldn't need to create `RawBuilder` instances directly. Instead you should
+ * use the {@link sql} template tag.
+ */
+export interface RawBuilder<O> extends AliasableExpression<O> {
+    get isRawBuilder(): true;
+    /**
+     * Returns an aliased version of the SQL expression.
+     *
+     * In addition to slapping `as "the_alias"` to the end of the SQL,
+     * this method also provides strict typing:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select(
+     *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name')
+     *   )
+     *   .executeTakeFirstOrThrow()
+     *
+     * // `full_name: string` field exists in the result type.
+     * console.log(result.full_name)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select concat(first_name, ' ', last_name) as "full_name"
+     * from "person"
+     * ```
+     *
+     * You can also pass in a raw SQL snippet but in that case you must
+     * provide the alias as the only type argument:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const values = sql<{ a: number, b: string }>`(values (1, 'foo'))`
+     *
+     * // The alias is `t(a, b)` which specifies the column names
+     * // in addition to the table name. We must tell kysely that
+     * // columns of the table can be referenced through `t`
+     * // by providing an explicit type argument.
+     * const aliasedValues = values.as<'t'>(sql`t(a, b)`)
+     *
+     * await db
+     *   .insertInto('person')
+     *   .columns(['first_name', 'last_name'])
+     *   .expression(
+     *     db.selectFrom(aliasedValues).select(['t.a', 't.b'])
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name")
+     * from (values (1, 'foo')) as t(a, b)
+     * select "t"."a", "t"."b"
+     * ```
+     */
+    as<A extends string>(alias: A): AliasedRawBuilder<O, A>;
+    /**
+     * Returns an aliased version of the expression.
+     *
+     * ### Examples
+     *
+     * In addition to slapping `as "the_alias"` at the end of the expression,
+     * this method also provides strict typing:
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select((eb) =>
+     *     // `eb.fn<string>` returns an AliasableExpression<string>
+     *     eb.fn<string>('concat', ['first_name', eb.val(' '), 'last_name']).as('full_name')
+     *   )
+     *   .executeTakeFirstOrThrow()
+     *
+     * // `full_name: string` field exists in the result type.
+     * console.log(result.full_name)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select
+     *   concat("first_name", $1, "last_name") as "full_name"
+     * from
+     *   "person"
+     * ```
+     *
+     * You can also pass in a raw SQL snippet (or any expression) but in that case you must
+     * provide the alias as the only type argument:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const values = sql<{ a: number, b: string }>`(values (1, 'foo'))`
+     *
+     * // The alias is `t(a, b)` which specifies the column names
+     * // in addition to the table name. We must tell kysely that
+     * // columns of the table can be referenced through `t`
+     * // by providing an explicit type argument.
+     * const aliasedValues = values.as<'t'>(sql`t(a, b)`)
+     *
+     * await db
+     *   .insertInto('person')
+     *   .columns(['first_name', 'last_name'])
+     *   .expression(
+     *     db.selectFrom(aliasedValues).select(['t.a', 't.b'])
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name")
+     * from (values (1, 'foo')) as t(a, b)
+     * select "t"."a", "t"."b"
+     * ```
+     */
+    as<A extends string>(alias: Expression<any>): AliasedRawBuilder<O, A>;
+    /**
+     * Change the output type of the raw expression.
+     *
+     * This method call doesn't change the SQL in any way. This methods simply
+     * returns a copy of this `RawBuilder` with a new output type.
+     */
+    $castTo<C>(): RawBuilder<C>;
+    /**
+     * Omit null from the expression's type.
+     *
+     * This function can be useful in cases where you know an expression can't be
+     * null, but Kysely is unable to infer it.
+     *
+     * This method call doesn't change the SQL in any way. This methods simply
+     * returns a copy of `this` with a new output type.
+     */
+    $notNull(): RawBuilder<Exclude<O, null>>;
+    /**
+     * Adds a plugin for this SQL snippet.
+     */
+    withPlugin(plugin: KyselyPlugin): RawBuilder<O>;
+    /**
+     * Compiles the builder to a `CompiledQuery`.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const compiledQuery = sql`select * from ${sql.table('person')}`.compile(db)
+     * console.log(compiledQuery.sql)
+     * ```
+     */
+    compile(executorProvider: QueryExecutorProvider): CompiledQuery<O>;
+    /**
+     * Executes the raw query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const result = await sql`select * from ${sql.table('person')}`.execute(db)
+     * ```
+     */
+    execute(executorProvider: QueryExecutorProvider, options?: AbortableQueryOptions): Promise<QueryResult<O>>;
+    /**
+     * Creates the OperationNode that describes how to compile this expression into SQL.
+     *
+     * ### Examples
+     *
+     * If you are creating a custom expression, it's often easiest to use the {@link sql}
+     * template tag to build the node:
+     *
+     * ```ts
+     * import { type Expression, type OperationNode, sql } from 'kysely'
+     *
+     * class SomeExpression<T> implements Expression<T> {
+     *   get expressionType(): T | undefined {
+     *     return undefined
+     *   }
+     *
+     *   toOperationNode(): OperationNode {
+     *     return sql`some sql here`.toOperationNode()
+     *   }
+     * }
+     * ```
+     */
+    toOperationNode(): RawNode;
+}
+export interface RawBuilderProps {
+    readonly queryId: QueryId;
+    readonly rawNode: RawNode;
+    readonly plugins?: ReadonlyArray<KyselyPlugin>;
+}
+export declare function createRawBuilder<O>(props: RawBuilderProps): RawBuilder<O>;
+/**
+ * {@link RawBuilder} with an alias. The result of calling {@link RawBuilder.as}.
+ */
+export interface AliasedRawBuilder<out O = unknown, out A extends string = never> extends AliasedExpression<O, A> {
+    get rawBuilder(): RawBuilder<O>;
+}