kysely 0.11.2 → 0.12.1

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

@@ -1,32 +1,30 @@
-import { AliasedQueryBuilder, QueryBuilder } from '../query-builder/query-builder.js';
+import { AliasedQueryBuilder } from '../query-builder/select-query-builder.js';
 import { TableNode } from '../operation-node/table-node.js';
-import { AliasedQueryBuilderFactory, AnyAliasedQueryBuilder, AnyAliasedRawBuilder, Nullable } from '../util/type-utils.js';
+import { AnyAliasedRawBuilder, Nullable } from '../util/type-utils.js';
 import { AliasedRawBuilder } from '../raw-builder/raw-builder.js';
 import { TableExpressionNode } from '../operation-node/operation-node-utils.js';
 import { ParseContext } from './parse-context.js';
-export declare type TableExpression<DB, TB extends keyof DB> = TableReference<DB> | AnyAliasedQueryBuilder | AliasedQueryBuilderFactory<DB, TB>;
+import { AliasedComplexExpression } from './complex-expression-parser.js';
+export declare type TableExpression<DB, TB extends keyof DB> = TableReference<DB> | AliasedComplexExpression<DB, TB>;
 export declare type TableExpressionOrList<DB, TB extends keyof DB> = TableExpression<DB, TB> | ReadonlyArray<TableExpression<DB, TB>>;
-export declare type TableReference<DB> = AnyAliasedTable<DB, any, any> | AnyTable<DB> | AnyAliasedRawBuilder;
-export declare type QueryBuilderWithTable<DB, TB extends keyof DB, O, TE> = QueryBuilder<TableExpressionDatabase<DB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
+export declare type TableReference<DB> = AnyAliasedTable<DB> | AnyTable<DB> | AnyAliasedRawBuilder;
 export declare type TableExpressionDatabase<DB, TE, A extends keyof any = ExtractAliasFromTableExpression<DB, TE>> = {
     [C in keyof DB | A]: C extends A ? ExtractRowTypeFromTableExpression<DB, TE, C> : C extends keyof DB ? DB[C] : never;
 };
-export declare type QueryBuilderWithLeftJoin<DB, TB extends keyof DB, O, TE> = QueryBuilder<LeftJoinTableExpressionDatabase<DB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
 export declare type LeftJoinTableExpressionDatabase<DB, TE, A extends keyof any = ExtractAliasFromTableExpression<DB, TE>> = {
     [C in keyof DB | A]: C extends A ? Nullable<ExtractRowTypeFromTableExpression<DB, TE, C>> : C extends keyof DB ? DB[C] : never;
 };
-export declare type QueryBuilderWithRightJoin<DB, TB extends keyof DB, O, TE> = QueryBuilder<RightJoinTableExpressionDatabase<DB, TB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
 export declare type RightJoinTableExpressionDatabase<DB, TB extends keyof DB, TE, A extends keyof any = ExtractAliasFromTableExpression<DB, TE>> = {
     [C in keyof DB | A]: C extends A ? ExtractRowTypeFromTableExpression<DB, TE, C> : C extends keyof DB ? C extends TB ? Nullable<DB[C]> : DB[C] : never;
 };
-export declare type QueryBuilderWithFullJoin<DB, TB extends keyof DB, O, TE> = QueryBuilder<FullJoinTableExpressionDatabase<DB, TB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
 export declare type FullJoinTableExpressionDatabase<DB, TB extends keyof DB, TE, A extends keyof any = ExtractAliasFromTableExpression<DB, TE>> = {
     [C in keyof DB | A]: C extends A ? Nullable<ExtractRowTypeFromTableExpression<DB, TE, C>> : C extends keyof DB ? C extends TB ? Nullable<DB[C]> : DB[C] : never;
 };
 export declare type ExtractAliasFromTableExpression<DB, TE> = TE extends `${string} as ${infer TA}` ? TA : TE extends keyof DB ? TE : TE extends AliasedQueryBuilder<any, any, any, infer QA> ? QA : TE extends (qb: any) => AliasedQueryBuilder<any, any, any, infer QA> ? QA : TE extends AliasedRawBuilder<any, infer RA> ? RA : TE extends (qb: any) => AliasedRawBuilder<any, infer RA> ? RA : never;
-declare 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 AliasedQueryBuilder<any, any, infer O, infer QA> ? QA extends A ? O : never : TE extends (qb: any) => AliasedQueryBuilder<any, any, infer O, infer QA> ? QA extends A ? O : never : TE extends AliasedRawBuilder<infer O, infer RA> ? RA extends A ? O : never : never;
-declare type AnyAliasedTable<DB, TB extends keyof DB, A extends string> = TB extends string ? `${TB} as ${A}` : never;
-declare type AnyTable<DB> = keyof DB;
+export declare type TableExpressionTables<DB, TB extends keyof DB, TE> = TB | ExtractAliasFromTableExpression<DB, TE>;
+declare 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 AliasedQueryBuilder<any, any, infer O, infer QA> ? QA extends A ? O : never : TE extends (qb: any) => AliasedQueryBuilder<any, any, infer O, infer QA> ? QA extends A ? O : never : TE extends AliasedRawBuilder<infer O, infer RA> ? RA extends A ? O : never : TE extends (qb: any) => AliasedRawBuilder<infer O, infer RA> ? RA extends A ? O : never : never;
+declare type AnyAliasedTable<DB> = `${AnyTable<DB>} as ${string}`;
+declare type AnyTable<DB> = keyof DB & string;
 export declare function parseTableExpressionOrList(ctx: ParseContext, table: TableExpressionOrList<any, any>): TableExpressionNode[];
 export declare function parseTableExpression(ctx: ParseContext, table: TableExpression<any, any>): TableExpressionNode;
 export declare function parseAliasedTable(from: string): TableExpressionNode;

package/dist/cjs/parser/table-parser.js

@@ -4,7 +4,7 @@ exports.parseTable = exports.parseAliasedTable = exports.parseTableExpression =
 const object_utils_js_1 = require("../util/object-utils.js");
 const alias_node_js_1 = require("../operation-node/alias-node.js");
 const table_node_js_1 = require("../operation-node/table-node.js");
-const operation_node_source_js_1 = require("../operation-node/operation-node-source.js");
+const complex_expression_parser_js_1 = require("./complex-expression-parser.js");
 function parseTableExpressionOrList(ctx, table) {
     if ((0, object_utils_js_1.isReadonlyArray)(table)) {
         return table.map((it) => parseTableExpression(ctx, it));
@@ -18,14 +18,8 @@ function parseTableExpression(ctx, table) {
     if ((0, object_utils_js_1.isString)(table)) {
         return parseAliasedTable(table);
     }
-    else if ((0, operation_node_source_js_1.isOperationNodeSource)(table)) {
-        return table.toOperationNode();
-    }
-    else if ((0, object_utils_js_1.isFunction)(table)) {
-        return table(ctx.createExpressionBuilder()).toOperationNode();
-    }
     else {
-        throw new Error(`invalid table expression ${JSON.stringify(table)}`);
+        return (0, complex_expression_parser_js_1.parseAliasedComplexExpression)(ctx, table);
     }
 }
 exports.parseTableExpression = parseTableExpression;

package/dist/cjs/parser/union-parser.d.ts

@@ -1,5 +1,5 @@
 import { UnionNode } from '../operation-node/union-node.js';
-import { QueryBuilder } from '../query-builder/query-builder.js';
+import { SelectQueryBuilder } from '../query-builder/select-query-builder.js';
 import { RawBuilder } from '../raw-builder/raw-builder.js';
-export declare type UnionExpression<DB, O> = QueryBuilder<DB, any, O> | RawBuilder<O>;
+export declare type UnionExpression<DB, O> = SelectQueryBuilder<DB, any, O> | RawBuilder<O>;
 export declare function parseUnion(union: UnionExpression<any, any>, all: boolean): UnionNode;

package/dist/cjs/parser/union-parser.js

@@ -1,13 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseUnion = void 0;
-const query_node_js_1 = require("../operation-node/query-node.js");
 const union_node_js_1 = require("../operation-node/union-node.js");
 function parseUnion(union, all) {
-    const node = union.toOperationNode();
-    if (query_node_js_1.QueryNode.isMutating(node)) {
-        throw new Error("can't combine insert, update or delete queries using union");
-    }
-    return union_node_js_1.UnionNode.create(node, all);
+    return union_node_js_1.UnionNode.create(union.toOperationNode(), all);
 }
 exports.parseUnion = parseUnion;

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

@@ -1,13 +1,7 @@
 import { ColumnUpdateNode } from '../operation-node/column-update-node.js';
-import { RawNode } from '../operation-node/raw-node.js';
-import { SelectQueryNode } from '../operation-node/select-query-node.js';
-import { ValueNode } from '../operation-node/value-node.js';
-import { AnyQueryBuilder, AnyRawBuilder, QueryBuilderFactory, RawBuilderFactory } from '../util/type-utils.js';
-import { PrimitiveValue } from '../util/object-utils.js';
 import { ParseContext } from './parse-context.js';
+import { ValueExpression } from './value-parser.js';
 export declare type MutationObject<DB, TB extends keyof DB> = {
-    [C in keyof DB[TB]]?: MutationValueExpression<DB, TB, DB[TB][C]>;
+    [C in keyof DB[TB]]?: ValueExpression<DB, TB, DB[TB][C]>;
 };
-export declare type MutationValueExpression<DB, TB extends keyof DB, T> = T | AnyQueryBuilder | QueryBuilderFactory<DB, TB> | AnyRawBuilder | RawBuilderFactory<DB, TB>;
 export declare function parseUpdateObject(ctx: ParseContext, row: MutationObject<any, any>): ReadonlyArray<ColumnUpdateNode>;
-export declare function parseMutationValueExpression(ctx: ParseContext, value: MutationValueExpression<any, any, PrimitiveValue>): ValueNode | RawNode | SelectQueryNode;

package/dist/cjs/parser/update-set-parser.js

@@ -1,34 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseMutationValueExpression = exports.parseUpdateObject = void 0;
+exports.parseUpdateObject = void 0;
 const column_node_js_1 = require("../operation-node/column-node.js");
 const column_update_node_js_1 = require("../operation-node/column-update-node.js");
-const operation_node_source_js_1 = require("../operation-node/operation-node-source.js");
-const query_node_js_1 = require("../operation-node/query-node.js");
-const value_node_js_1 = require("../operation-node/value-node.js");
-const object_utils_js_1 = require("../util/object-utils.js");
+const value_parser_js_1 = require("./value-parser.js");
 function parseUpdateObject(ctx, row) {
-    return Object.entries(row).map(([key, value]) => {
-        return column_update_node_js_1.ColumnUpdateNode.create(column_node_js_1.ColumnNode.create(key), parseMutationValueExpression(ctx, value));
+    return Object.entries(row)
+        .filter(([_, value]) => value !== undefined)
+        .map(([key, value]) => {
+        return column_update_node_js_1.ColumnUpdateNode.create(column_node_js_1.ColumnNode.create(key), (0, value_parser_js_1.parseValueExpression)(ctx, value));
     });
 }
 exports.parseUpdateObject = parseUpdateObject;
-function parseMutationValueExpression(ctx, value) {
-    if ((0, object_utils_js_1.isPrimitive)(value)) {
-        return value_node_js_1.ValueNode.create(value);
-    }
-    else if ((0, operation_node_source_js_1.isOperationNodeSource)(value)) {
-        const node = value.toOperationNode();
-        if (!query_node_js_1.QueryNode.isMutating(node)) {
-            return node;
-        }
-    }
-    else if ((0, object_utils_js_1.isFunction)(value)) {
-        const node = value(ctx.createExpressionBuilder()).toOperationNode();
-        if (!query_node_js_1.QueryNode.isMutating(node)) {
-            return node;
-        }
-    }
-    throw new Error(`unsupported value for mutation object ${JSON.stringify(value)}`);
-}
-exports.parseMutationValueExpression = parseMutationValueExpression;

package/dist/cjs/parser/value-parser.d.ts

@@ -1,8 +1,11 @@
 import { ValueExpressionNode } from '../operation-node/operation-node-utils.js';
-import { AnyQueryBuilder, AnyRawBuilder, QueryBuilderFactory, RawBuilderFactory } from '../util/type-utils.js';
-import { ExtractTypeFromReferenceExpression } from './reference-parser.js';
+import { ValueNode } from '../operation-node/value-node.js';
+import { PrimitiveValue } from '../util/object-utils.js';
 import { ParseContext } from './parse-context.js';
-export declare type ValueExpression<DB, TB extends keyof DB, RE> = ExtractTypeFromReferenceExpression<DB, TB, RE> | AnyQueryBuilder | QueryBuilderFactory<DB, TB> | AnyRawBuilder | RawBuilderFactory<DB, TB>;
-export declare type ValueExpressionOrList<DB, TB extends keyof DB, RE> = ValueExpression<DB, TB, RE> | ReadonlyArray<ValueExpression<DB, TB, RE>>;
-export declare function parseValueExpressionOrList(ctx: ParseContext, arg: ValueExpressionOrList<any, any, any>): ValueExpressionNode;
-export declare function parseValueExpression(ctx: ParseContext, arg: ValueExpression<any, any, any>): ValueExpressionNode;
+import { SelectQueryNode } from '../operation-node/select-query-node.js';
+import { RawNode } from '../operation-node/raw-node.js';
+import { ComplexExpression } from './complex-expression-parser.js';
+export declare type ValueExpression<DB, TB extends keyof DB, V> = V | ComplexExpression<DB, TB>;
+export declare type ValueExpressionOrList<DB, TB extends keyof DB, V> = ValueExpression<DB, TB, V> | ReadonlyArray<ValueExpression<DB, TB, V>>;
+export declare function parseValueExpressionOrList(ctx: ParseContext, arg: ValueExpressionOrList<any, any, PrimitiveValue>): ValueExpressionNode;
+export declare function parseValueExpression(ctx: ParseContext, exp: ValueExpression<any, any, PrimitiveValue>): ValueNode | SelectQueryNode | RawNode;

package/dist/cjs/parser/value-parser.js

@@ -1,15 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseValueExpression = exports.parseValueExpressionOrList = void 0;
-const column_node_js_1 = require("../operation-node/column-node.js");
-const operation_node_source_js_1 = require("../operation-node/operation-node-source.js");
 const primitive_value_list_node_js_1 = require("../operation-node/primitive-value-list-node.js");
 const value_list_node_js_1 = require("../operation-node/value-list-node.js");
 const value_node_js_1 = require("../operation-node/value-node.js");
 const object_utils_js_1 = require("../util/object-utils.js");
-const query_node_js_1 = require("../operation-node/query-node.js");
+const complex_expression_parser_js_1 = require("./complex-expression-parser.js");
 function parseValueExpressionOrList(ctx, arg) {
-    if (Array.isArray(arg)) {
+    if ((0, object_utils_js_1.isReadonlyArray)(arg)) {
         return parseValueExpressionList(ctx, arg);
     }
     else {
@@ -17,23 +15,11 @@ function parseValueExpressionOrList(ctx, arg) {
     }
 }
 exports.parseValueExpressionOrList = parseValueExpressionOrList;
-function parseValueExpression(ctx, arg) {
-    if ((0, object_utils_js_1.isPrimitive)(arg)) {
-        return value_node_js_1.ValueNode.create(arg);
+function parseValueExpression(ctx, exp) {
+    if ((0, object_utils_js_1.isPrimitive)(exp)) {
+        return value_node_js_1.ValueNode.create(exp);
     }
-    else if ((0, operation_node_source_js_1.isOperationNodeSource)(arg)) {
-        const node = arg.toOperationNode();
-        if (!query_node_js_1.QueryNode.isMutating(node)) {
-            return node;
-        }
-    }
-    else if ((0, object_utils_js_1.isFunction)(arg)) {
-        const node = arg(ctx.createExpressionBuilder()).toOperationNode();
-        if (!query_node_js_1.QueryNode.isMutating(node)) {
-            return node;
-        }
-    }
-    throw new Error(`invalid value expression ${JSON.stringify(arg)}`);
+    return (0, complex_expression_parser_js_1.parseComplexExpression)(ctx, exp);
 }
 exports.parseValueExpression = parseValueExpression;
 function parseValueExpressionList(ctx, arg) {
@@ -41,14 +27,5 @@ function parseValueExpressionList(ctx, arg) {
         // Optimization for large lists of primitive values.
         return primitive_value_list_node_js_1.PrimitiveValueListNode.create(arg);
     }
-    return value_list_node_js_1.ValueListNode.create(arg.map((it) => {
-        const node = parseValueExpression(ctx, it);
-        if (column_node_js_1.ColumnNode.is(node)) {
-            throw new Error('value lists cannot have column references');
-        }
-        if (value_list_node_js_1.ValueListNode.is(node) || primitive_value_list_node_js_1.PrimitiveValueListNode.is(node)) {
-            throw new Error('value lists cannot have nested lists');
-        }
-        return node;
-    }));
+    return value_list_node_js_1.ValueListNode.create(arg.map((it) => parseValueExpression(ctx, it)));
 }

package/dist/cjs/parser/with-parser.d.ts

@@ -1,11 +1,14 @@
+import { SelectQueryBuilder } from '../query-builder/select-query-builder.js';
+import { UpdateQueryBuilder } from '../query-builder/update-query-builder.js';
+import { DeleteQueryBuilder } from '../query-builder/delete-query-builder.js';
+import { InsertQueryBuilder } from '../query-builder/insert-query-builder.js';
 import { CommonTableExpressionNode } from '../operation-node/common-table-expression-node.js';
-import { QueryBuilder } from '../query-builder/query-builder.js';
 import { QueryCreator } from '../query-creator.js';
 import { RawBuilder } from '../raw-builder/raw-builder.js';
 import { AnyRawBuilder } from '../util/type-utils.js';
 import { ParseContext } from './parse-context.js';
-export declare type CommonTableExpression<DB> = (creator: QueryCreator<DB>) => QueryBuilder<DB, any> | AnyRawBuilder;
+export declare type CommonTableExpression<DB> = (creator: QueryCreator<DB>) => SelectQueryBuilder<DB, any, any> | InsertQueryBuilder<DB, any, any> | UpdateQueryBuilder<DB, any, any> | DeleteQueryBuilder<DB, any, any> | AnyRawBuilder;
 export declare type QueryCreatorWithCommonTableExpression<DB, N extends string, E extends CommonTableExpression<DB>> = QueryCreator<DB & Record<N, ExtractRowTypeFromCommonTableExpression<E>>>;
-declare type ExtractRowTypeFromCommonTableExpression<E> = E extends (creator: QueryCreator<any>) => infer Q ? Q extends QueryBuilder<any, any, infer QO> ? QO : Q extends RawBuilder<infer RO> ? RO : never : never;
+declare type ExtractRowTypeFromCommonTableExpression<E> = E extends (creator: QueryCreator<any>) => infer Q ? Q extends SelectQueryBuilder<any, any, infer QO> ? QO : Q extends InsertQueryBuilder<any, any, infer QO> ? QO : Q extends UpdateQueryBuilder<any, any, infer QO> ? QO : Q extends DeleteQueryBuilder<any, any, infer QO> ? QO : Q extends RawBuilder<infer RO> ? RO : never : never;
 export declare function parseCommonTableExpression(ctx: ParseContext, name: string, expression: CommonTableExpression<any>): CommonTableExpressionNode;
 export {};

package/dist/cjs/plugin/camel-case/camel-case-plugin.d.ts

@@ -94,7 +94,41 @@ export interface CamelCasePluginOptions {
 export declare class CamelCasePlugin implements KyselyPlugin {
     #private;
     constructor(opt?: CamelCasePluginOptions);
+    /**
+     * 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
+     * const plugin = {
+     *   data: new WeakMap<QueryId, SomeData>(),
+     *
+     *   transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
+     *     this.data.set(args.queryId, something)
+     *     return args.node
+     *   },
+     *
+     *   transformResult(args: PluginTransformResultArgs): QueryResult<UnknownRow> {
+     *     const data = this.data.get(args.queryId)
+     *     return args.result
+     *   }
+     * }
+     * ```
+     *
+     * 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>>;
     protected mapRow(row: UnknownRow): UnknownRow;
     protected snakeCase(str: string): string;

package/dist/cjs/plugin/immediate-value.ts/immediate-value-plugin.d.ts

@@ -12,6 +12,40 @@ import { KyselyPlugin, PluginTransformQueryArgs, PluginTransformResultArgs } fro
  */
 export declare class ImmediateValuePlugin implements KyselyPlugin {
     #private;
+    /**
+     * 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
+     * const plugin = {
+     *   data: new WeakMap<QueryId, SomeData>(),
+     *
+     *   transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
+     *     this.data.set(args.queryId, something)
+     *     return args.node
+     *   },
+     *
+     *   transformResult(args: PluginTransformResultArgs): QueryResult<UnknownRow> {
+     *     const data = this.data.get(args.queryId)
+     *     return args.result
+     *   }
+     * }
+     * ```
+     *
+     * 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/cjs/plugin/immediate-value.ts/immediate-value-plugin.js

@@ -15,8 +15,8 @@ class ImmediateValuePlugin {
     transformQuery(args) {
         return this.#transformer.transformNode(args.node);
     }
-    async transformResult(args) {
-        return args.result;
+    transformResult(args) {
+        return Promise.resolve(args.result);
     }
 }
 exports.ImmediateValuePlugin = ImmediateValuePlugin;

package/dist/cjs/plugin/with-schema/with-schema-plugin.d.ts

@@ -5,6 +5,40 @@ import { UnknownRow } from '../../util/type-utils.js';
 export declare class WithSchemaPlugin implements KyselyPlugin {
     #private;
     constructor(schema: string);
+    /**
+     * 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
+     * const plugin = {
+     *   data: new WeakMap<QueryId, SomeData>(),
+     *
+     *   transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
+     *     this.data.set(args.queryId, something)
+     *     return args.node
+     *   },
+     *
+     *   transformResult(args: PluginTransformResultArgs): QueryResult<UnknownRow> {
+     *     const data = this.data.get(args.queryId)
+     *     return args.result
+     *   }
+     * }
+     * ```
+     *
+     * 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>>;
 }