kysely 0.27.5 → 0.28.0

package/dist/esm/parser/order-by-parser.js

@@ -1,9 +1,12 @@
 /// <reference types="./order-by-parser.d.ts" />
-import { isDynamicReferenceBuilder } from '../dynamic/dynamic-reference-builder.js';
+import { isDynamicReferenceBuilder, } from '../dynamic/dynamic-reference-builder.js';
+import { isExpression } from '../expression/expression.js';
 import { OrderByItemNode } from '../operation-node/order-by-item-node.js';
 import { RawNode } from '../operation-node/raw-node.js';
-import { isExpressionOrFactory, parseExpression } from './expression-parser.js';
-import { parseStringReference } from './reference-parser.js';
+import { OrderByItemBuilder } from '../query-builder/order-by-item-builder.js';
+import { logOnce } from '../util/log-once.js';
+import { isExpressionOrFactory, parseExpression, } from './expression-parser.js';
+import { parseStringReference, } from './reference-parser.js';
 export function isOrderByDirection(thing) {
     return thing === 'asc' || thing === 'desc';
 }
@@ -14,21 +17,22 @@ export function parseOrderBy(args) {
     if (args.length === 1) {
         const [orderBy] = args;
         if (Array.isArray(orderBy)) {
+            logOnce('orderBy(array) is deprecated, use multiple orderBy calls instead.');
             return orderBy.map((item) => parseOrderByItem(item));
         }
         return [parseOrderByItem(orderBy)];
     }
     throw new Error(`Invalid number of arguments at order by! expected 1-2, received ${args.length}`);
 }
-export function parseOrderByItem(ref, direction) {
-    const parsedRef = parseOrderByExpression(ref);
+export function parseOrderByItem(expr, modifiers) {
+    const parsedRef = parseOrderByExpression(expr);
     if (OrderByItemNode.is(parsedRef)) {
-        if (direction) {
+        if (modifiers) {
             throw new Error('Cannot specify direction twice!');
         }
         return parsedRef;
     }
-    return OrderByItemNode.create(parsedRef, parseOrderByDirectionExpression(direction));
+    return parseOrderByWithModifiers(parsedRef, modifiers);
 }
 function parseOrderByExpression(expr) {
     if (isExpressionOrFactory(expr)) {
@@ -39,19 +43,25 @@ function parseOrderByExpression(expr) {
     }
     const [ref, direction] = expr.split(' ');
     if (direction) {
-        if (!isOrderByDirection(direction)) {
-            throw new Error(`Invalid order by direction: ${direction}`);
-        }
-        return OrderByItemNode.create(parseStringReference(ref), parseOrderByDirectionExpression(direction));
+        logOnce("`orderBy('column asc')` is deprecated. Use `orderBy('column', 'asc')` instead.");
+        return parseOrderByWithModifiers(parseStringReference(ref), direction);
     }
     return parseStringReference(expr);
 }
-function parseOrderByDirectionExpression(expr) {
-    if (!expr) {
-        return undefined;
+function parseOrderByWithModifiers(expr, modifiers) {
+    if (typeof modifiers === 'string') {
+        if (!isOrderByDirection(modifiers)) {
+            throw new Error(`Invalid order by direction: ${modifiers}`);
+        }
+        return OrderByItemNode.create(expr, RawNode.createWithSql(modifiers));
+    }
+    if (isExpression(modifiers)) {
+        logOnce("`orderBy(..., expr)` is deprecated. Use `orderBy(..., 'asc')` or `orderBy(..., (ob) => ...)` instead.");
+        return OrderByItemNode.create(expr, modifiers.toOperationNode());
     }
-    if (expr === 'asc' || expr === 'desc') {
-        return RawNode.createWithSql(expr);
+    const node = OrderByItemNode.create(expr);
+    if (!modifiers) {
+        return node;
     }
-    return expr.toOperationNode();
+    return modifiers(new OrderByItemBuilder({ node })).toOperationNode();
 }

package/dist/esm/parser/savepoint-parser.d.ts

@@ -0,0 +1,4 @@
+import { RawNode } from '../operation-node/raw-node.js';
+export type RollbackToSavepoint<S extends string[], SN extends S[number]> = S extends [...infer L, infer R] ? R extends SN ? S : RollbackToSavepoint<L extends string[] ? L : never, SN> : never;
+export type ReleaseSavepoint<S extends string[], SN extends S[number]> = S extends [...infer L, infer R] ? R extends SN ? L : ReleaseSavepoint<L extends string[] ? L : never, SN> : never;
+export declare function parseSavepointCommand(command: string, savepointName: string): RawNode;

package/dist/esm/parser/savepoint-parser.js

@@ -0,0 +1,9 @@
+/// <reference types="./savepoint-parser.d.ts" />
+import { IdentifierNode } from '../operation-node/identifier-node.js';
+import { RawNode } from '../operation-node/raw-node.js';
+export function parseSavepointCommand(command, savepointName) {
+    return RawNode.createWithChildren([
+        RawNode.createWithSql(`${command} `),
+        IdentifierNode.create(savepointName), // ensures savepointName gets sanitized
+    ]);
+}

package/dist/esm/parser/select-from-parser.d.ts

@@ -0,0 +1,4 @@
+import type { SelectQueryBuilder } from '../query-builder/select-query-builder.js';
+import type { ShallowRecord } from '../util/type-utils.js';
+import type { ExtractTableAlias, From, FromTables, TableExpressionOrList } from './table-parser.js';
+export type SelectFrom<DB, TB extends keyof DB, TE extends TableExpressionOrList<DB, TB>> = TE extends keyof DB & string ? SelectQueryBuilder<DB, TB | ExtractTableAlias<DB, TE>, {}> : TE extends `${infer T} as ${infer A}` ? T extends keyof DB ? SelectQueryBuilder<DB & ShallowRecord<A, DB[T]>, TB | A, {}> : never : TE extends ReadonlyArray<infer T> ? SelectQueryBuilder<From<DB, T>, FromTables<DB, TB, T>, {}> : SelectQueryBuilder<From<DB, TE>, FromTables<DB, TB, TE>, {}>;

package/dist/esm/parser/select-from-parser.js

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

package/dist/esm/parser/table-parser.d.ts

@@ -3,22 +3,19 @@ import { TableNode } from '../operation-node/table-node.js';
 import { AliasedExpressionOrFactory } from './expression-parser.js';
 import { OperationNode } from '../operation-node/operation-node.js';
 import { AliasedExpression } from '../expression/expression.js';
-import { DrainOuterGeneric, ShallowRecord } from '../util/type-utils.js';
+import { DrainOuterGeneric } from '../util/type-utils.js';
 export type TableExpression<DB, TB extends keyof DB> = AnyAliasedTable<DB> | AnyTable<DB> | AliasedExpressionOrFactory<DB, TB>;
 export type TableExpressionOrList<DB, TB extends keyof DB> = TableExpression<DB, TB> | ReadonlyArray<TableExpression<DB, TB>>;
-export type TableReference<DB> = SimpleTableReference<DB> | AliasedExpression<any, any>;
 export type SimpleTableReference<DB> = AnyAliasedTable<DB> | AnyTable<DB>;
 export type AnyAliasedTable<DB> = `${AnyTable<DB>} as ${string}`;
-export type TableReferenceOrList<DB> = TableReference<DB> | ReadonlyArray<TableReference<DB>>;
+export type AnyTable<DB> = keyof DB & string;
 export type From<DB, TE> = DrainOuterGeneric<{
     [C in keyof DB | ExtractAliasFromTableExpression<DB, TE>]: C extends ExtractAliasFromTableExpression<DB, TE> ? ExtractRowTypeFromTableExpression<DB, TE, C> : C extends keyof DB ? DB[C] : never;
 }>;
 export type FromTables<DB, TB extends keyof DB, TE> = DrainOuterGeneric<TB | ExtractAliasFromTableExpression<DB, TE>>;
 export type ExtractTableAlias<DB, TE> = TE extends `${string} as ${infer TA}` ? TA extends keyof DB ? TA : never : TE extends keyof DB ? TE : never;
-export type PickTableWithAlias<DB, T extends AnyAliasedTable<DB>> = T extends `${infer TB} as ${infer A}` ? TB extends keyof DB ? ShallowRecord<A, DB[TB]> : never : never;
 type ExtractAliasFromTableExpression<DB, TE> = TE extends string ? TE extends `${string} as ${infer TA}` ? TA : TE extends keyof DB ? TE : never : TE extends AliasedExpression<any, infer QA> ? QA : TE extends (qb: any) => AliasedExpression<any, infer QA> ? QA : never;
 type ExtractRowTypeFromTableExpression<DB, TE, A extends keyof any> = TE extends `${infer T} as ${infer TA}` ? TA extends A ? T extends keyof DB ? DB[T] : never : never : TE extends A ? TE extends keyof DB ? DB[TE] : never : TE extends AliasedExpression<infer O, infer QA> ? QA extends A ? O : never : TE extends (qb: any) => AliasedExpression<infer O, infer QA> ? QA extends A ? O : never : never;
-type AnyTable<DB> = keyof DB & string;
 export declare function parseTableExpressionOrList(table: TableExpressionOrList<any, any>): OperationNode[];
 export declare function parseTableExpression(table: TableExpression<any, any>): OperationNode;
 export declare function parseAliasedTable(from: string): TableNode | AliasNode;

package/dist/esm/parser/update-parser.d.ts

@@ -0,0 +1,5 @@
+import type { UpdateQueryBuilder } from '../query-builder/update-query-builder.js';
+import type { UpdateResult } from '../query-builder/update-result.js';
+import type { ShallowRecord } from '../util/type-utils.js';
+import type { ExtractTableAlias, From, FromTables, TableExpressionOrList } from './table-parser.js';
+export type UpdateTable<DB, TE extends TableExpressionOrList<DB, never>> = TE extends ReadonlyArray<infer T> ? UpdateQueryBuilder<From<DB, T>, FromTables<DB, never, T>, FromTables<DB, never, T>, UpdateResult> : TE extends keyof DB & string ? UpdateQueryBuilder<DB, ExtractTableAlias<DB, TE>, ExtractTableAlias<DB, TE>, UpdateResult> : TE extends `${infer T} as ${infer A}` ? T extends keyof DB ? UpdateQueryBuilder<DB & ShallowRecord<A, DB[T]>, A, A, UpdateResult> : never : UpdateQueryBuilder<From<DB, TE>, FromTables<DB, never, TE>, FromTables<DB, never, TE>, UpdateResult>;

package/dist/esm/parser/update-parser.js

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

package/dist/esm/parser/update-set-parser.d.ts

@@ -1,11 +1,14 @@
 import { ColumnUpdateNode } from '../operation-node/column-update-node.js';
 import { ExpressionBuilder } from '../expression/expression-builder.js';
-import { UpdateKeys, UpdateType } from '../util/column-type.js';
+import { UpdateType } from '../util/column-type.js';
 import { ValueExpression } from './value-parser.js';
 import { ExtractRawTypeFromReferenceExpression, ReferenceExpression } from './reference-parser.js';
-export type UpdateObject<DB, TB extends keyof DB, UT extends keyof DB = TB> = {
-    [C in UpdateKeys<DB[UT]>]?: ValueExpression<DB, TB, UpdateType<DB[UT][C]>> | undefined;
-};
+import { AnyColumn, DrainOuterGeneric } from '../util/type-utils.js';
+export type UpdateObject<DB, TB extends keyof DB, UT extends keyof DB = TB> = DrainOuterGeneric<{
+    [C in AnyColumn<DB, UT>]?: {
+        [T in UT]: C extends keyof DB[T] ? ValueExpression<DB, TB, UpdateType<DB[T][C]>> | undefined : never;
+    }[UT];
+}>;
 export type UpdateObjectFactory<DB, TB extends keyof DB, UT extends keyof DB> = (eb: ExpressionBuilder<DB, TB>) => UpdateObject<DB, TB, UT>;
 export type UpdateObjectExpression<DB, TB extends keyof DB, UT extends keyof DB = TB> = UpdateObject<DB, TB, UT> | UpdateObjectFactory<DB, TB, UT>;
 export type ExtractUpdateTypeFromReferenceExpression<DB, TB extends keyof DB, RE, DV = unknown> = UpdateType<ExtractRawTypeFromReferenceExpression<DB, TB, RE, DV>>;

package/dist/esm/plugin/camel-case/camel-case-plugin.js

@@ -83,7 +83,7 @@ export class CamelCasePlugin {
         this.#snakeCaseTransformer = new SnakeCaseTransformer(this.snakeCase.bind(this));
     }
     transformQuery(args) {
-        return this.#snakeCaseTransformer.transformNode(args.node);
+        return this.#snakeCaseTransformer.transformNode(args.node, args.queryId);
     }
     async transformResult(args) {
         if (args.result.rows && Array.isArray(args.result.rows)) {

package/dist/esm/plugin/camel-case/camel-case-transformer.d.ts

@@ -1,8 +1,9 @@
 import { IdentifierNode } from '../../operation-node/identifier-node.js';
 import { OperationNodeTransformer } from '../../operation-node/operation-node-transformer.js';
+import { QueryId } from '../../util/query-id.js';
 import { StringMapper } from './camel-case.js';
 export declare class SnakeCaseTransformer extends OperationNodeTransformer {
     #private;
     constructor(snakeCase: StringMapper);
-    protected transformIdentifier(node: IdentifierNode): IdentifierNode;
+    protected transformIdentifier(node: IdentifierNode, queryId: QueryId): IdentifierNode;
 }

package/dist/esm/plugin/camel-case/camel-case-transformer.js

@@ -6,8 +6,8 @@ export class SnakeCaseTransformer extends OperationNodeTransformer {
         super();
         this.#snakeCase = snakeCase;
     }
-    transformIdentifier(node) {
-        node = super.transformIdentifier(node);
+    transformIdentifier(node, queryId) {
+        node = super.transformIdentifier(node, queryId);
         return {
             ...node,
             name: this.#snakeCase(node.name),

package/dist/esm/plugin/camel-case/camel-case.js

@@ -20,7 +20,10 @@ export function createSnakeCaseMapper({ upperCase = false, underscoreBeforeDigit
             // If underScoreBeforeDigits is true then, well, insert an underscore
             // before digits :). Only the first digit gets an underscore if
             // there are multiple.
-            if (underscoreBeforeDigits && isDigit(char) && !isDigit(prevChar)) {
+            if (underscoreBeforeDigits &&
+                isDigit(char) &&
+                !isDigit(prevChar) &&
+                !out.endsWith('_')) {
                 out += '_' + char;
                 continue;
             }

package/dist/esm/plugin/deduplicate-joins/deduplicate-joins-plugin.js

@@ -8,7 +8,7 @@ import { DeduplicateJoinsTransformer } from './deduplicate-joins-transformer.js'
 export class DeduplicateJoinsPlugin {
     #transformer = new DeduplicateJoinsTransformer();
     transformQuery(args) {
-        return this.#transformer.transformNode(args.node);
+        return this.#transformer.transformNode(args.node, args.queryId);
     }
     transformResult(args) {
         return Promise.resolve(args.result);

package/dist/esm/plugin/deduplicate-joins/deduplicate-joins-transformer.d.ts

@@ -2,9 +2,10 @@ import { DeleteQueryNode } from '../../operation-node/delete-query-node.js';
 import { OperationNodeTransformer } from '../../operation-node/operation-node-transformer.js';
 import { SelectQueryNode } from '../../operation-node/select-query-node.js';
 import { UpdateQueryNode } from '../../operation-node/update-query-node.js';
+import { QueryId } from '../../util/query-id.js';
 export declare class DeduplicateJoinsTransformer extends OperationNodeTransformer {
     #private;
-    protected transformSelectQuery(node: SelectQueryNode): SelectQueryNode;
-    protected transformUpdateQuery(node: UpdateQueryNode): UpdateQueryNode;
-    protected transformDeleteQuery(node: DeleteQueryNode): DeleteQueryNode;
+    protected transformSelectQuery(node: SelectQueryNode, queryId: QueryId): SelectQueryNode;
+    protected transformUpdateQuery(node: UpdateQueryNode, queryId: QueryId): UpdateQueryNode;
+    protected transformDeleteQuery(node: DeleteQueryNode, queryId: QueryId): DeleteQueryNode;
 }

package/dist/esm/plugin/deduplicate-joins/deduplicate-joins-transformer.js

@@ -2,14 +2,14 @@
 import { OperationNodeTransformer } from '../../operation-node/operation-node-transformer.js';
 import { compare, freeze } from '../../util/object-utils.js';
 export class DeduplicateJoinsTransformer extends OperationNodeTransformer {
-    transformSelectQuery(node) {
-        return this.#transformQuery(super.transformSelectQuery(node));
+    transformSelectQuery(node, queryId) {
+        return this.#transformQuery(super.transformSelectQuery(node, queryId));
     }
-    transformUpdateQuery(node) {
-        return this.#transformQuery(super.transformUpdateQuery(node));
+    transformUpdateQuery(node, queryId) {
+        return this.#transformQuery(super.transformUpdateQuery(node, queryId));
     }
-    transformDeleteQuery(node) {
-        return this.#transformQuery(super.transformDeleteQuery(node));
+    transformDeleteQuery(node, queryId) {
+        return this.#transformQuery(super.transformDeleteQuery(node, queryId));
     }
     #transformQuery(node) {
         if (!node.joins || node.joins.length === 0) {

package/dist/esm/plugin/handle-empty-in-lists/handle-empty-in-lists-plugin.d.ts

@@ -0,0 +1,211 @@
+import { QueryResult } from '../../driver/database-connection.js';
+import { RootOperationNode } from '../../query-compiler/query-compiler.js';
+import { KyselyPlugin, PluginTransformQueryArgs, PluginTransformResultArgs } from '../kysely-plugin.js';
+import { UnknownRow } from '../../util/type-utils.js';
+import { HandleEmptyInListsOptions } from './handle-empty-in-lists.js';
+/**
+ * A plugin that allows handling `in ()` and `not in ()` expressions.
+ *
+ * These expressions are invalid SQL syntax for many databases, and result in runtime
+ * database errors.
+ *
+ * The workarounds used by other libraries always involve modifying the query under
+ * the hood, which is not aligned with Kysely's philosophy of WYSIWYG. We recommend manually checking
+ * for empty arrays before passing them as arguments to `in` and `not in` expressions
+ * instead, but understand that this can be cumbersome. Hence we're going with an
+ * opt-in approach where you can choose if and how to handle these cases. We do
+ * not want to make this the default behavior, as it can lead to unexpected behavior.
+ * Use it at your own risk. Test it. Make sure it works as expected for you.
+ *
+ * Using this plugin also allows you to throw an error (thus avoiding unnecessary
+ * requests to the database) or print a warning in these cases.
+ *
+ * ### Examples
+ *
+ * The following strategy replaces the `in`/`not in` expression with a noncontingent
+ * expression. A contradiction (falsy) `1 = 0` for `in`, and a tautology (truthy) `1 = 1` for `not in`),
+ * similarily to how {@link https://github.com/knex/knex/blob/176151d8048b2a7feeb89a3d649a5580786d4f4e/docs/src/guide/query-builder.md#L1763 | Knex.js},
+ * {@link https://github.com/prisma/prisma-engines/blob/99168c54187178484dae45d9478aa40cfd1866d2/quaint/src/visitor.rs#L804-L823 | PrismaORM},
+ * {@link https://github.com/laravel/framework/blob/8.x/src/Illuminate/Database/Query/Grammars/Grammar.php#L284-L291 | Laravel},
+ * {@link https://docs.sqlalchemy.org/en/13/core/engines.html#sqlalchemy.create_engine.params.empty_in_strategy | SQLAlchemy}
+ * handle this.
+ *
+ * ```ts
+ * import Sqlite from 'better-sqlite3'
+ * import {
+ *   HandleEmptyInListsPlugin,
+ *   Kysely,
+ *   replaceWithNoncontingentExpression,
+ *   SqliteDialect,
+ * } from 'kysely'
+ * import type { Database } from 'type-editor' // imaginary module
+ *
+ * const db = new Kysely<Database>({
+ *   dialect: new SqliteDialect({
+ *     database: new Sqlite(':memory:'),
+ *   }),
+ *   plugins: [
+ *     new HandleEmptyInListsPlugin({
+ *       strategy: replaceWithNoncontingentExpression
+ *     })
+ *   ],
+ * })
+ *
+ * const results = await db
+ *   .selectFrom('person')
+ *   .where('id', 'in', [])
+ *   .where('first_name', 'not in', [])
+ *   .selectAll()
+ *   .execute()
+ * ```
+ *
+ * The generated SQL (SQLite):
+ *
+ * ```sql
+ * select * from "person" where 1 = 0 and 1 = 1
+ * ```
+ *
+ * The following strategy does the following:
+ *
+ * When `in`, pushes a `null` value into the empty list resulting in `in (null)`,
+ * similiarly to how {@link https://github.com/typeorm/typeorm/blob/0280cdc451c35ef73c830eb1191c95d34f6ce06e/src/query-builder/QueryBuilder.ts#L919-L922 | TypeORM}
+ * and {@link https://github.com/sequelize/sequelize/blob/0f2891c6897e12bf9bf56df344aae5b698f58c7d/packages/core/src/abstract-dialect/where-sql-builder.ts#L368-L379 | Sequelize}
+ * handle `in ()`. `in (null)` is logically the equivalent of `= null`, which returns
+ * `null`, which is a falsy expression in most SQL databases. We recommend NOT
+ * using this strategy if you plan to use `in` in `select`, `returning`, or `output`
+ * clauses, as the return type differs from the `SqlBool` default type for comparisons.
+ *
+ * When `not in`, casts the left operand as `char` and pushes a unique value into
+ * the empty list resulting in `cast({{lhs}} as char) not in ({{VALUE}})`. Casting
+ * is required to avoid database errors with non-string values.
+ *
+ * ```ts
+ * import Sqlite from 'better-sqlite3'
+ * import {
+ *   HandleEmptyInListsPlugin,
+ *   Kysely,
+ *   pushValueIntoList,
+ *   SqliteDialect
+ * } from 'kysely'
+ * import type { Database } from 'type-editor' // imaginary module
+ *
+ * const db = new Kysely<Database>({
+ *   dialect: new SqliteDialect({
+ *     database: new Sqlite(':memory:'),
+ *   }),
+ *   plugins: [
+ *     new HandleEmptyInListsPlugin({
+ *       strategy: pushValueIntoList('__kysely_no_values_were_provided__') // choose a unique value for not in. has to be something with zero chance being in the data.
+ *     })
+ *   ],
+ * })
+ *
+ * const results = await db
+ *   .selectFrom('person')
+ *   .where('id', 'in', [])
+ *   .where('first_name', 'not in', [])
+ *   .selectAll()
+ *   .execute()
+ * ```
+ *
+ * The generated SQL (SQLite):
+ *
+ * ```sql
+ * select * from "person" where "id" in (null) and cast("first_name" as char) not in ('__kysely_no_values_were_provided__')
+ * ```
+ *
+ * The following custom strategy throws an error when an empty list is encountered
+ * to avoid unnecessary requests to the database:
+ *
+ * ```ts
+ * import Sqlite from 'better-sqlite3'
+ * import {
+ *   HandleEmptyInListsPlugin,
+ *   Kysely,
+ *   SqliteDialect
+ * } from 'kysely'
+ * import type { Database } from 'type-editor' // imaginary module
+ *
+ * const db = new Kysely<Database>({
+ *   dialect: new SqliteDialect({
+ *     database: new Sqlite(':memory:'),
+ *   }),
+ *   plugins: [
+ *     new HandleEmptyInListsPlugin({
+ *       strategy: () => {
+ *         throw new Error('Empty in/not-in is not allowed')
+ *       }
+ *     })
+ *   ],
+ * })
+ *
+ * const results = await db
+ *   .selectFrom('person')
+ *   .where('id', 'in', [])
+ *   .selectAll()
+ *   .execute() // throws an error with 'Empty in/not-in is not allowed' message!
+ * ```
+ */
+export declare class HandleEmptyInListsPlugin implements KyselyPlugin {
+    #private;
+    readonly opt: HandleEmptyInListsOptions;
+    constructor(opt: HandleEmptyInListsOptions);
+    /**
+     * This is called for each query before it is executed. You can modify the query by
+     * transforming its {@link OperationNode} tree provided in {@link PluginTransformQueryArgs.node | args.node}
+     * and returning the transformed tree. You'd usually want to use an {@link OperationNodeTransformer}
+     * for this.
+     *
+     * If you need to pass some query-related data between this method and `transformResult` you
+     * can use a `WeakMap` with {@link PluginTransformQueryArgs.queryId | args.queryId} as the key:
+     *
+     * ```ts
+     * import type {
+     *   KyselyPlugin,
+     *   QueryResult,
+     *   RootOperationNode,
+     *   UnknownRow
+     * } from 'kysely'
+     *
+     * interface MyData {
+     *   // ...
+     * }
+     * const data = new WeakMap<any, MyData>()
+     *
+     * const plugin = {
+     *   transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
+     *     const something: MyData = {}
+     *
+     *     // ...
+     *
+     *     data.set(args.queryId, something)
+     *
+     *     // ...
+     *
+     *     return args.node
+     *   },
+     *
+     *   async transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {
+     *     // ...
+     *
+     *     const something = data.get(args.queryId)
+     *
+     *     // ...
+     *
+     *     return args.result
+     *   }
+     * } satisfies KyselyPlugin
+     * ```
+     *
+     * You should use a `WeakMap` instead of a `Map` or some other strong references because `transformQuery`
+     * is not always matched by a call to `transformResult` which would leave orphaned items in the map
+     * and cause a memory leak.
+     */
+    transformQuery(args: PluginTransformQueryArgs): RootOperationNode;
+    /**
+     * This method is called for each query after it has been executed. The result
+     * of the query can be accessed through {@link PluginTransformResultArgs.result | args.result}.
+     * You can modify the result and return the modifier result.
+     */
+    transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>>;
+}

package/dist/esm/plugin/handle-empty-in-lists/handle-empty-in-lists-plugin.js

@@ -0,0 +1,159 @@
+/// <reference types="./handle-empty-in-lists-plugin.d.ts" />
+import { HandleEmptyInListsTransformer } from './handle-empty-in-lists-transformer.js';
+/**
+ * A plugin that allows handling `in ()` and `not in ()` expressions.
+ *
+ * These expressions are invalid SQL syntax for many databases, and result in runtime
+ * database errors.
+ *
+ * The workarounds used by other libraries always involve modifying the query under
+ * the hood, which is not aligned with Kysely's philosophy of WYSIWYG. We recommend manually checking
+ * for empty arrays before passing them as arguments to `in` and `not in` expressions
+ * instead, but understand that this can be cumbersome. Hence we're going with an
+ * opt-in approach where you can choose if and how to handle these cases. We do
+ * not want to make this the default behavior, as it can lead to unexpected behavior.
+ * Use it at your own risk. Test it. Make sure it works as expected for you.
+ *
+ * Using this plugin also allows you to throw an error (thus avoiding unnecessary
+ * requests to the database) or print a warning in these cases.
+ *
+ * ### Examples
+ *
+ * The following strategy replaces the `in`/`not in` expression with a noncontingent
+ * expression. A contradiction (falsy) `1 = 0` for `in`, and a tautology (truthy) `1 = 1` for `not in`),
+ * similarily to how {@link https://github.com/knex/knex/blob/176151d8048b2a7feeb89a3d649a5580786d4f4e/docs/src/guide/query-builder.md#L1763 | Knex.js},
+ * {@link https://github.com/prisma/prisma-engines/blob/99168c54187178484dae45d9478aa40cfd1866d2/quaint/src/visitor.rs#L804-L823 | PrismaORM},
+ * {@link https://github.com/laravel/framework/blob/8.x/src/Illuminate/Database/Query/Grammars/Grammar.php#L284-L291 | Laravel},
+ * {@link https://docs.sqlalchemy.org/en/13/core/engines.html#sqlalchemy.create_engine.params.empty_in_strategy | SQLAlchemy}
+ * handle this.
+ *
+ * ```ts
+ * import Sqlite from 'better-sqlite3'
+ * import {
+ *   HandleEmptyInListsPlugin,
+ *   Kysely,
+ *   replaceWithNoncontingentExpression,
+ *   SqliteDialect,
+ * } from 'kysely'
+ * import type { Database } from 'type-editor' // imaginary module
+ *
+ * const db = new Kysely<Database>({
+ *   dialect: new SqliteDialect({
+ *     database: new Sqlite(':memory:'),
+ *   }),
+ *   plugins: [
+ *     new HandleEmptyInListsPlugin({
+ *       strategy: replaceWithNoncontingentExpression
+ *     })
+ *   ],
+ * })
+ *
+ * const results = await db
+ *   .selectFrom('person')
+ *   .where('id', 'in', [])
+ *   .where('first_name', 'not in', [])
+ *   .selectAll()
+ *   .execute()
+ * ```
+ *
+ * The generated SQL (SQLite):
+ *
+ * ```sql
+ * select * from "person" where 1 = 0 and 1 = 1
+ * ```
+ *
+ * The following strategy does the following:
+ *
+ * When `in`, pushes a `null` value into the empty list resulting in `in (null)`,
+ * similiarly to how {@link https://github.com/typeorm/typeorm/blob/0280cdc451c35ef73c830eb1191c95d34f6ce06e/src/query-builder/QueryBuilder.ts#L919-L922 | TypeORM}
+ * and {@link https://github.com/sequelize/sequelize/blob/0f2891c6897e12bf9bf56df344aae5b698f58c7d/packages/core/src/abstract-dialect/where-sql-builder.ts#L368-L379 | Sequelize}
+ * handle `in ()`. `in (null)` is logically the equivalent of `= null`, which returns
+ * `null`, which is a falsy expression in most SQL databases. We recommend NOT
+ * using this strategy if you plan to use `in` in `select`, `returning`, or `output`
+ * clauses, as the return type differs from the `SqlBool` default type for comparisons.
+ *
+ * When `not in`, casts the left operand as `char` and pushes a unique value into
+ * the empty list resulting in `cast({{lhs}} as char) not in ({{VALUE}})`. Casting
+ * is required to avoid database errors with non-string values.
+ *
+ * ```ts
+ * import Sqlite from 'better-sqlite3'
+ * import {
+ *   HandleEmptyInListsPlugin,
+ *   Kysely,
+ *   pushValueIntoList,
+ *   SqliteDialect
+ * } from 'kysely'
+ * import type { Database } from 'type-editor' // imaginary module
+ *
+ * const db = new Kysely<Database>({
+ *   dialect: new SqliteDialect({
+ *     database: new Sqlite(':memory:'),
+ *   }),
+ *   plugins: [
+ *     new HandleEmptyInListsPlugin({
+ *       strategy: pushValueIntoList('__kysely_no_values_were_provided__') // choose a unique value for not in. has to be something with zero chance being in the data.
+ *     })
+ *   ],
+ * })
+ *
+ * const results = await db
+ *   .selectFrom('person')
+ *   .where('id', 'in', [])
+ *   .where('first_name', 'not in', [])
+ *   .selectAll()
+ *   .execute()
+ * ```
+ *
+ * The generated SQL (SQLite):
+ *
+ * ```sql
+ * select * from "person" where "id" in (null) and cast("first_name" as char) not in ('__kysely_no_values_were_provided__')
+ * ```
+ *
+ * The following custom strategy throws an error when an empty list is encountered
+ * to avoid unnecessary requests to the database:
+ *
+ * ```ts
+ * import Sqlite from 'better-sqlite3'
+ * import {
+ *   HandleEmptyInListsPlugin,
+ *   Kysely,
+ *   SqliteDialect
+ * } from 'kysely'
+ * import type { Database } from 'type-editor' // imaginary module
+ *
+ * const db = new Kysely<Database>({
+ *   dialect: new SqliteDialect({
+ *     database: new Sqlite(':memory:'),
+ *   }),
+ *   plugins: [
+ *     new HandleEmptyInListsPlugin({
+ *       strategy: () => {
+ *         throw new Error('Empty in/not-in is not allowed')
+ *       }
+ *     })
+ *   ],
+ * })
+ *
+ * const results = await db
+ *   .selectFrom('person')
+ *   .where('id', 'in', [])
+ *   .selectAll()
+ *   .execute() // throws an error with 'Empty in/not-in is not allowed' message!
+ * ```
+ */
+export class HandleEmptyInListsPlugin {
+    opt;
+    #transformer;
+    constructor(opt) {
+        this.opt = opt;
+        this.#transformer = new HandleEmptyInListsTransformer(opt.strategy);
+    }
+    transformQuery(args) {
+        return this.#transformer.transformNode(args.node, args.queryId);
+    }
+    async transformResult(args) {
+        return args.result;
+    }
+}

package/dist/esm/plugin/handle-empty-in-lists/handle-empty-in-lists-transformer.d.ts

@@ -0,0 +1,8 @@
+import { BinaryOperationNode } from '../../operation-node/binary-operation-node.js';
+import { OperationNodeTransformer } from '../../operation-node/operation-node-transformer.js';
+import { EmptyInListsStrategy } from './handle-empty-in-lists.js';
+export declare class HandleEmptyInListsTransformer extends OperationNodeTransformer {
+    #private;
+    constructor(strategy: EmptyInListsStrategy);
+    protected transformBinaryOperation(node: BinaryOperationNode): BinaryOperationNode;
+}