kysely 0.16.9 → 0.17.1

package/dist/cjs/query-creator.js

@@ -10,7 +10,6 @@ const insert_query_node_js_1 = require("./operation-node/insert-query-node.js");
 const select_query_node_js_1 = require("./operation-node/select-query-node.js");
 const update_query_node_js_1 = require("./operation-node/update-query-node.js");
 const table_parser_js_1 = require("./parser/table-parser.js");
-const raw_builder_js_1 = require("./raw-builder/raw-builder.js");
 const with_parser_js_1 = require("./parser/with-parser.js");
 const with_node_js_1 = require("./operation-node/with-node.js");
 const query_id_js_1 = require("./util/query-id.js");
@@ -25,8 +24,7 @@ class QueryCreator {
         return new select_query_builder_js_1.SelectQueryBuilder({
             queryId: (0, query_id_js_1.createQueryId)(),
             executor: this.#props.executor,
-            parseContext: this.#props.parseContext,
-            queryNode: select_query_node_js_1.SelectQueryNode.create((0, table_parser_js_1.parseTableExpressionOrList)(this.#props.parseContext, from), this.#props.withNode),
+            queryNode: select_query_node_js_1.SelectQueryNode.create((0, table_parser_js_1.parseTableExpressionOrList)(from), this.#props.withNode),
         });
     }
     /**
@@ -71,7 +69,6 @@ class QueryCreator {
         return new insert_query_builder_js_1.InsertQueryBuilder({
             queryId: (0, query_id_js_1.createQueryId)(),
             executor: this.#props.executor,
-            parseContext: this.#props.parseContext,
             queryNode: insert_query_node_js_1.InsertQueryNode.create((0, table_parser_js_1.parseTable)(table), this.#props.withNode),
         });
     }
@@ -98,8 +95,7 @@ class QueryCreator {
         return new delete_query_builder_js_1.DeleteQueryBuilder({
             queryId: (0, query_id_js_1.createQueryId)(),
             executor: this.#props.executor,
-            parseContext: this.#props.parseContext,
-            queryNode: delete_query_node_js_1.DeleteQueryNode.create((0, table_parser_js_1.parseTableExpression)(this.#props.parseContext, table), this.#props.withNode),
+            queryNode: delete_query_node_js_1.DeleteQueryNode.create((0, table_parser_js_1.parseTableExpression)(table), this.#props.withNode),
         });
     }
     /**
@@ -129,8 +125,7 @@ class QueryCreator {
         return new update_query_builder_js_1.UpdateQueryBuilder({
             queryId: (0, query_id_js_1.createQueryId)(),
             executor: this.#props.executor,
-            parseContext: this.#props.parseContext,
-            queryNode: update_query_node_js_1.UpdateQueryNode.create((0, table_parser_js_1.parseTableExpression)(this.#props.parseContext, table), this.#props.withNode),
+            queryNode: update_query_node_js_1.UpdateQueryNode.create((0, table_parser_js_1.parseTableExpression)(table), this.#props.withNode),
         });
     }
     /**
@@ -175,7 +170,7 @@ class QueryCreator {
      * ```
      */
     with(name, expression) {
-        const cte = (0, with_parser_js_1.parseCommonTableExpression)(this.#props.parseContext, name, expression);
+        const cte = (0, with_parser_js_1.parseCommonTableExpression)(name, expression);
         return new QueryCreator({
             ...this.#props,
             withNode: this.#props.withNode
@@ -189,7 +184,7 @@ class QueryCreator {
      * See the {@link with} method for examples and more documentation.
      */
     withRecursive(name, expression) {
-        const cte = (0, with_parser_js_1.parseCommonTableExpression)(this.#props.parseContext, name, expression);
+        const cte = (0, with_parser_js_1.parseCommonTableExpression)(name, expression);
         return new QueryCreator({
             ...this.#props,
             withNode: this.#props.withNode
@@ -204,14 +199,18 @@ class QueryCreator {
      * This only affects the query created through the builder returned from
      * this method and doesn't modify the `db` instance.
      *
+     * See [this recipe](https://github.com/koskimas/kysely/tree/master/recipes/schemas.md)
+     * for a more detailed explanation.
+     *
      * ### Examples
      *
      * ```
-     * await db.withSchema('mammals')
-     *  .selectFrom('pet')
-     *  .selectAll()
-     *  .innerJoin('public.person', 'public.person.id', 'pet.owner_id')
-     *  .execute()
+     * await db
+     *   .withSchema('mammals')
+     *   .selectFrom('pet')
+     *   .selectAll()
+     *   .innerJoin('public.person', 'public.person.id', 'pet.owner_id')
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -227,10 +226,11 @@ class QueryCreator {
      * doesn't belong to:
      *
      * ```
-     * await db.withSchema('mammals')
-     *  .selectFrom('pet as p')
-     *  .select('p.name')
-     *  .execute()
+     * await db
+     *   .withSchema('mammals')
+     *   .selectFrom('pet as p')
+     *   .select('p.name')
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -245,131 +245,5 @@ class QueryCreator {
             executor: this.#props.executor.withPluginAtFront(new with_schema_plugin_js_1.WithSchemaPlugin(schema)),
         });
     }
-    /**
-     * Provides a way to pass arbitrary SQL into your query and executing completely
-     * raw queries.
-     *
-     * You can use the strings `?` and `??` in the `sql` to bind parameters such as
-     * user input to the SQL. You should never EVER concatenate untrusted user
-     * input to the SQL string to avoid injection vulnerabilities. Instead use `?`
-     * in place of a value and pass the actual value in the `parameters` list. See
-     * the examples below.
-     *
-     * You should only use `raw` when there is no other way to get the job done. This is
-     * because Kysely is not able to use type inference when you use raw SQL. For example
-     * Kysely won't be able to automatically provide you with the correct query result
-     * type. However, there are ways to manually provide types when you use `raw` in most
-     * cases. See the examples below.
-     *
-     * Raw builder instances can be passed to pretty much anywhere: `select`, `where`,
-     * `*Join`, `groupBy`, `orderBy` etc. Just try it. If the method accepts it, it works.
-     *
-     * ### Examples
-     *
-     * Example of using `raw` in a select statement:
-     *
-     * ```ts
-     * const [person] = await db.selectFrom('person')
-     *   .select(db.raw<string>('concat(first_name, ' ', last_name)').as('name'))
-     *   .where('id', '=', 1)
-     *   .execute()
-     *
-     * console.log(person.name)
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select concat(first_name, ' ', last_name) as "name"
-     * from "person" where "id" = 1
-     * ```
-     *
-     * The above example selects computed column `name` by concatenating the first name
-     * and last name together.
-     *
-     * There are couple of things worth noticing:
-     *
-     *   1. You need to provide the output type of your SQL segment for the `raw` method
-     *     so that Kysely knows what type to give for the `name` column. In this case it's
-     *     a `string` since that's the output type of the `concat` function in SQL.
-     *
-     *   2. You need to give an alias for the selection using the `as` method so that
-     *     Kysely is able to add a column to the output type. The alias needs to be
-     *     known at compile time! If you pass a string variable whose value is not known
-     *     at compile time, there is no way for Kysely or typescript to add a column to
-     *     the output type. In this case you need to use the `castTo` method on the query
-     *     to specify a return type for the query.
-     *
-     * We could've also used a `??` placeholder to provide `first_name` and `last_name` like
-     * this:
-     *
-     * ```ts
-     * db.raw<string>('concat(??, ' ', ??)', ['first_name', 'last_name'])
-     * ```
-     *
-     * or this:
-     *
-     * ```ts
-     * db.raw<string>('concat(??, ' ', ??)', ['person.first_name', 'person.last_name'])
-     * ```
-     *
-     * But it's often cleaner to just write the column names in the SQL. Again remember to
-     * never concatenate column names or any other untrusted user input to the SQL string or you
-     * are going to create an injection vulnerability. All user input should go to the parameters
-     * array, never to the SQL string directly. But if the column names or values are trusted
-     * and known at compile time, there is no reason to use parameters.
-     *
-     * Example of using `raw` in `where`:
-     *
-     * ```ts
-     * function getPersonsOlderThan(ageLimit: number) {
-     *   return await db.selectFrom('person')
-     *     .selectAll()
-     *     .where(
-     *       db.raw('now() - birth_date'),
-     *       '>',
-     *       db.raw('interval ? year', [ageLimit.toString()])
-     *     )
-     *     .execute()
-     * }
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select * from "person" where now() - birth_date > interval $1 year
-     * ```
-     *
-     * The function in the above example returns people that are older than the given number of
-     * years. The number of years in this example is an untrusted user input, and therefore we use
-     * a `?` placeholder for it.
-     *
-     * Example of creating a completely raw query from scratch:
-     *
-     * ```ts
-     * 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
-     * this case we know the resulting items will be of type `Person` se specify that.
-     * The result of `execute()` method is always an array. In this case the type of
-     * the `persons` variable is `Person[]`.
-     *
-     * @param sql - The raw SQL. Special strings `?` and `??` can be used as parameter
-     *    placeholders. `?` for values and `??` for identifiers such as column names
-     *    or `column.table` references.
-     *
-     * @param params - The parameters that will be bound to the `?` and `??` placeholders in
-     *    the sql string.
-     */
-    raw(sql, parameters) {
-        return new raw_builder_js_1.RawBuilder({
-            queryId: (0, query_id_js_1.createQueryId)(),
-            executor: this.#props.executor,
-            sql,
-            parameters,
-        });
-    }
 }
 exports.QueryCreator = QueryCreator;

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

@@ -1,19 +1,30 @@
 import { ConnectionProvider } from '../driver/connection-provider.js';
-import { QueryResult } from '../driver/database-connection.js';
+import { DatabaseConnection } from '../driver/database-connection.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { RootOperationNode, QueryCompiler } from '../query-compiler/query-compiler.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
 import { QueryExecutor } from './query-executor.js';
+import { DialectAdapter } from '../index-nodeless.js';
 export declare class DefaultQueryExecutor extends QueryExecutor {
     #private;
-    constructor(compiler: QueryCompiler, connectionProvider: ConnectionProvider, plugins?: KyselyPlugin[]);
+    constructor(compiler: QueryCompiler, adapter: DialectAdapter, connectionProvider: ConnectionProvider, plugins?: KyselyPlugin[]);
+    get adapter(): DialectAdapter;
     /**
      * 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(node: RootOperationNode): CompiledQuery;
-    protected executeQueryImpl<R>(compiledQuery: CompiledQuery): Promise<QueryResult<R>>;
+    /**
+     * Provides a connection for the callback and takes care of disposing
+     * the connection after the callback has been run.
+     */
+    provideConnection<T>(consumer: (connection: DatabaseConnection) => Promise<T>): Promise<T>;
+    /**
+     * Returns a copy of this executor with a list of plugins added
+     * as the last plugins.
+     */
+    withPlugins(plugins: ReadonlyArray<KyselyPlugin>): DefaultQueryExecutor;
     /**
      * Returns a copy of this executor with a plugin added as the
      * last plugin.

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

@@ -4,39 +4,37 @@ exports.DefaultQueryExecutor = void 0;
 const query_executor_js_1 = require("./query-executor.js");
 class DefaultQueryExecutor extends query_executor_js_1.QueryExecutor {
     #compiler;
+    #adapter;
     #connectionProvider;
-    constructor(compiler, connectionProvider, plugins = []) {
+    constructor(compiler, adapter, connectionProvider, plugins = []) {
         super(plugins);
         this.#compiler = compiler;
+        this.#adapter = adapter;
         this.#connectionProvider = connectionProvider;
     }
+    get adapter() {
+        return this.#adapter;
+    }
     compileQuery(node) {
         return this.#compiler.compileQuery(node);
     }
-    async executeQueryImpl(compiledQuery) {
-        return this.#connectionProvider.withConnection((connection) => {
-            return connection.executeQuery(compiledQuery);
-        });
+    provideConnection(consumer) {
+        return this.#connectionProvider.provideConnection(consumer);
+    }
+    withPlugins(plugins) {
+        return new DefaultQueryExecutor(this.#compiler, this.#adapter, this.#connectionProvider, [...this.plugins, ...plugins]);
     }
     withPlugin(plugin) {
-        return new DefaultQueryExecutor(this.#compiler, this.#connectionProvider, [
-            ...this.plugins,
-            plugin,
-        ]);
+        return new DefaultQueryExecutor(this.#compiler, this.#adapter, this.#connectionProvider, [...this.plugins, plugin]);
     }
     withPluginAtFront(plugin) {
-        return new DefaultQueryExecutor(this.#compiler, this.#connectionProvider, [
-            plugin,
-            ...this.plugins,
-        ]);
+        return new DefaultQueryExecutor(this.#compiler, this.#adapter, this.#connectionProvider, [plugin, ...this.plugins]);
     }
     withConnectionProvider(connectionProvider) {
-        return new DefaultQueryExecutor(this.#compiler, connectionProvider, [
-            ...this.plugins,
-        ]);
+        return new DefaultQueryExecutor(this.#compiler, this.#adapter, connectionProvider, [...this.plugins]);
     }
     withoutPlugins() {
-        return new DefaultQueryExecutor(this.#compiler, this.#connectionProvider, []);
+        return new DefaultQueryExecutor(this.#compiler, this.#adapter, this.#connectionProvider, []);
     }
 }
 exports.DefaultQueryExecutor = DefaultQueryExecutor;

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

@@ -1,20 +1,25 @@
-import { QueryResult } from '../driver/database-connection.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { QueryExecutor } from './query-executor.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
+import { DialectAdapter } from '../dialect/dialect-adapter.js';
 /**
  * A {@link QueryExecutor} subclass that can be used when you don't
  * have a {@link QueryCompiler}, {@link ConnectionProvider} or any
  * other needed things to actually execute queries.
  */
 export declare class NoopQueryExecutor extends QueryExecutor {
+    get adapter(): DialectAdapter;
     /**
      * 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(): CompiledQuery;
-    protected executeQueryImpl<R>(): Promise<QueryResult<R>>;
+    /**
+     * Provides a connection for the callback and takes care of disposing
+     * the connection after the callback has been run.
+     */
+    provideConnection<T>(): Promise<T>;
     /**
      * Returns a copy of this executor with a new connection provider.
      */
@@ -24,6 +29,11 @@ export declare class NoopQueryExecutor extends QueryExecutor {
      * last plugin.
      */
     withPlugin(plugin: KyselyPlugin): NoopQueryExecutor;
+    /**
+     * Returns a copy of this executor with a list of plugins added
+     * as the last plugins.
+     */
+    withPlugins(plugins: ReadonlyArray<KyselyPlugin>): NoopQueryExecutor;
     /**
      * Returns a copy of this executor with a plugin added as the
      * first plugin.
@@ -34,3 +44,4 @@ export declare class NoopQueryExecutor extends QueryExecutor {
      */
     withoutPlugins(): QueryExecutor;
 }
+export declare const NOOP_QUERY_EXECUTOR: NoopQueryExecutor;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NoopQueryExecutor = void 0;
+exports.NOOP_QUERY_EXECUTOR = exports.NoopQueryExecutor = void 0;
 const query_executor_js_1 = require("./query-executor.js");
 /**
  * A {@link QueryExecutor} subclass that can be used when you don't
@@ -8,10 +8,13 @@ const query_executor_js_1 = require("./query-executor.js");
  * other needed things to actually execute queries.
  */
 class NoopQueryExecutor extends query_executor_js_1.QueryExecutor {
+    get adapter() {
+        throw new Error('this query cannot be compiled to SQL');
+    }
     compileQuery() {
         throw new Error('this query cannot be compiled to SQL');
     }
-    async executeQueryImpl() {
+    provideConnection() {
         throw new Error('this query cannot be executed');
     }
     withConnectionProvider() {
@@ -20,6 +23,9 @@ class NoopQueryExecutor extends query_executor_js_1.QueryExecutor {
     withPlugin(plugin) {
         return new NoopQueryExecutor([...this.plugins, plugin]);
     }
+    withPlugins(plugins) {
+        return new NoopQueryExecutor([...this.plugins, ...plugins]);
+    }
     withPluginAtFront(plugin) {
         return new NoopQueryExecutor([plugin, ...this.plugins]);
     }
@@ -28,3 +34,4 @@ class NoopQueryExecutor extends query_executor_js_1.QueryExecutor {
     }
 }
 exports.NoopQueryExecutor = NoopQueryExecutor;
+exports.NOOP_QUERY_EXECUTOR = new NoopQueryExecutor();

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

@@ -0,0 +1,8 @@
+import { QueryExecutor } from './query-executor.js';
+/**
+ * @internal
+ * @private
+ */
+export interface QueryExecutorProvider {
+    getExecutor(): QueryExecutor;
+}

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -1,18 +1,20 @@
 import { ConnectionProvider } from '../driver/connection-provider.js';
-import { QueryResult } from '../driver/database-connection.js';
+import { DatabaseConnection, QueryResult } from '../driver/database-connection.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { RootOperationNode } from '../query-compiler/query-compiler.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
 import { QueryId } from '../util/query-id.js';
+import { DialectAdapter } from '../dialect/dialect-adapter.js';
 /**
  * This class 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 declare abstract class QueryExecutor {
+export declare abstract class QueryExecutor implements ConnectionProvider {
     #private;
     constructor(plugins?: KyselyPlugin[]);
+    abstract get adapter(): DialectAdapter;
     get plugins(): ReadonlyArray<KyselyPlugin>;
     /**
      * Given the query the user has built (expressed as an operation node tree)
@@ -26,15 +28,16 @@ export declare abstract class QueryExecutor {
      * 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>): Promise<T>;
     /**
      * Executes a compiled query and runs the result through all plugins'
      * `transformResult` method.
      */
     executeQuery<R>(compiledQuery: CompiledQuery, queryId: QueryId): Promise<QueryResult<R>>;
-    /**
-     * Executes a compiled query.
-     */
-    protected abstract executeQueryImpl<R>(compiledQuery: CompiledQuery, queryId: QueryId): Promise<QueryResult<R>>;
     /**
      * Returns a copy of this executor with a new connection provider.
      */
@@ -44,6 +47,11 @@ export declare abstract class QueryExecutor {
      * last plugin.
      */
     abstract withPlugin(plugin: KyselyPlugin): QueryExecutor;
+    /**
+     * Returns a copy of this executor with a list of plugins added
+     * as the last plugins.
+     */
+    abstract withPlugins(plugin: ReadonlyArray<KyselyPlugin>): QueryExecutor;
     /**
      * Returns a copy of this executor with a plugin added as the
      * first plugin.

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

@@ -46,8 +46,10 @@ class QueryExecutor {
      * `transformResult` method.
      */
     async executeQuery(compiledQuery, queryId) {
-        const result = await this.executeQueryImpl(compiledQuery, queryId);
-        return this.#transformResult(result, queryId);
+        return await this.provideConnection(async (connection) => {
+            const result = await connection.executeQuery(compiledQuery);
+            return this.#transformResult(result, queryId);
+        });
     }
     async #transformResult(result, queryId) {
         for (const plugin of this.#plugins) {

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

@@ -2,25 +2,57 @@ import { QueryResult } from '../driver/database-connection.js';
 import { AliasNode } from '../operation-node/alias-node.js';
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
 import { RawNode } from '../operation-node/raw-node.js';
-import { CompiledQuery } from '../query-compiler/compiled-query.js';
-import { QueryExecutor } from '../query-executor/query-executor.js';
-import { QueryId } from '../util/query-id.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
+import { QueryExecutorProvider } from '../query-executor/query-executor-provider.js';
+import { QueryId } from '../util/query-id.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 declare class RawBuilder<O = unknown> implements OperationNodeSource {
     #private;
     constructor(props: RawBuilderProps);
+    /**
+     * 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
+     * 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):
+     *
+     * ```ts
+     * select concat(first_name, ' ', last_name) as "full_name"
+     * from "person"
+     * ```
+     */
     as<A extends string>(alias: A): AliasedRawBuilder<O, A>;
     /**
      * Change the output type of the raw expression.
      *
-     * This doesn't produce any SQL. This methods simply returns a copy
-     * of this `RawBuilder` with a new output type.
+     * 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<T>(): RawBuilder<T>;
+    /**
+     * Adds a plugin for this SQL snippet.
+     */
     withPlugin(plugin: KyselyPlugin): RawBuilder<O>;
     toOperationNode(): RawNode;
-    compile(): CompiledQuery;
-    execute(): Promise<QueryResult<O>>;
+    execute(executorProvider: QueryExecutorProvider): Promise<QueryResult<O>>;
 }
 /**
  * {@link RawBuilder} with an alias. The result of calling {@link RawBuilder.as}.
@@ -40,8 +72,7 @@ export declare class AliasedRawBuilder<O = unknown, A extends string = never> im
     constructor(rawBuilder: RawBuilder<O>, alias: A);
 }
 export interface RawBuilderProps {
-    readonly queryId?: QueryId;
-    readonly executor?: QueryExecutor;
-    readonly sql: string;
-    readonly parameters?: ReadonlyArray<unknown>;
+    readonly queryId: QueryId;
+    readonly rawNode: RawNode;
+    readonly plugins?: ReadonlyArray<KyselyPlugin>;
 }