kysely 0.21.5 → 0.22.0

package/dist/esm/query-builder/{function-builder.js → function-module.js}

@@ -1,8 +1,7 @@
-/// <reference types="./function-builder.d.ts" />
-import { RawNode } from '../operation-node/raw-node.js';
+/// <reference types="./function-module.d.ts" />
+import { AggregateFunctionNode } from '../operation-node/aggregate-function-node.js';
 import { parseStringReference, } from '../parser/reference-parser.js';
-import { RawBuilder } from '../raw-builder/raw-builder.js';
-import { createQueryId } from '../util/query-id.js';
+import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
 /**
  * Helpers for type safe SQL function calls.
  *
@@ -35,46 +34,13 @@ import { createQueryId } from '../util/query-id.js';
  * having count("pet"."id") > $1
  * ```
  */
-export class FunctionBuilder {
+export class FunctionModule {
     constructor() {
-        this.min = this.min.bind(this);
-        this.max = this.max.bind(this);
         this.avg = this.avg.bind(this);
-        this.sum = this.sum.bind(this);
         this.count = this.count.bind(this);
-    }
-    /**
-     * Calls the `max` function for the column given as the argument.
-     *
-     * ### Examples
-     *
-     * ```ts
-     * const { max } = db.fn
-     *
-     * db.selectFrom('toy')
-     *   .select(max('price').as('max_price'))
-     *   .execute()
-     * ```
-     */
-    max(column) {
-        return this.#oneArgFunction('max', column);
-    }
-    /**
-     * Calls the `min` function for the column given as the argument.
-     *
-     * ### Examples
-     *
-     * ```ts
-     * const { min } = db.fn
-     *
-     * db.selectFrom('toy')
-     *   .select(min('price').as('min_price'))
-     *   .execute()
-     * ```
-     *
-     */
-    min(column) {
-        return this.#oneArgFunction('min', column);
+        this.max = this.max.bind(this);
+        this.min = this.min.bind(this);
+        this.sum = this.sum.bind(this);
     }
     /**
      * Calls the `avg` function for the column given as the argument.
@@ -98,10 +64,12 @@ export class FunctionBuilder {
      * ```
      */
     avg(column) {
-        return this.#oneArgFunction('avg', column);
+        return new AggregateFunctionBuilder({
+            aggregateFunctionNode: AggregateFunctionNode.create('avg', parseStringReference(column)),
+        });
     }
     /**
-     * Calls the `sum` function for the column given as the argument.
+     * Calls the `count` function for the column given as the argument.
      *
      * If this is used in a `select` statement the type of the selected expression
      * will be `number | string | bigint` by default. This is because Kysely can't
@@ -114,21 +82,68 @@ export class FunctionBuilder {
      * the type as the first type argument:
      *
      * ```ts
-     * const { sum } = db.fn
+     * const { count } = db.fn
      *
      * db.selectFrom('toy')
-     *   .select(sum<number>('price').as('total_price'))
+     *   .select(count<number>('id').as('num_toys'))
+     *   .execute()
+     * ```
+     *
+     * You can limit column range:
+     *
+     * ```ts
+     * db.selectFrom('toy')
+     *   .select(qb => qb.fn.count<number>('id').as('num_toys'))
      *   .execute()
      * ```
      */
-    sum(column) {
-        return this.#oneArgFunction('sum', column);
+    count(column) {
+        return new AggregateFunctionBuilder({
+            aggregateFunctionNode: AggregateFunctionNode.create('count', parseStringReference(column)),
+        });
     }
     /**
-     * Calls the `count` function for the column given as the argument.
+     * Calls the `max` function for the column given as the argument.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const { max } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(max('price').as('max_price'))
+     *   .execute()
+     * ```
+     */
+    max(column) {
+        return new AggregateFunctionBuilder({
+            aggregateFunctionNode: AggregateFunctionNode.create('max', parseStringReference(column)),
+        });
+    }
+    /**
+     * Calls the `min` function for the column given as the argument.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const { min } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(min('price').as('min_price'))
+     *   .execute()
+     * ```
+     *
+     */
+    min(column) {
+        return new AggregateFunctionBuilder({
+            aggregateFunctionNode: AggregateFunctionNode.create('min', parseStringReference(column)),
+        });
+    }
+    /**
+     * Calls the `sum` function for the column given as the argument.
      *
      * If this is used in a `select` statement the type of the selected expression
-     * will be `number | string |bigint` by default. This is because Kysely can't
+     * will be `number | string | bigint` by default. This is because Kysely can't
      * know the type the db driver outputs. Sometimes the output can be larger than
      * the largest javascript number and a string is returned instead. Most drivers
      * allow you to configure the output type of large numbers and Kysely can't
@@ -138,20 +153,16 @@ export class FunctionBuilder {
      * the type as the first type argument:
      *
      * ```ts
-     * const { count } = db.fn
+     * const { sum } = db.fn
      *
      * db.selectFrom('toy')
-     *   .select(count<number>('id').as('num_toys'))
+     *   .select(sum<number>('price').as('total_price'))
      *   .execute()
      * ```
      */
-    count(column) {
-        return this.#oneArgFunction('count', column);
-    }
-    #oneArgFunction(fn, column) {
-        return new RawBuilder({
-            queryId: createQueryId(),
-            rawNode: RawNode.create([`${fn}(`, ')'], [parseStringReference(column)]),
+    sum(column) {
+        return new AggregateFunctionBuilder({
+            aggregateFunctionNode: AggregateFunctionNode.create('sum', parseStringReference(column)),
         });
     }
 }

package/dist/esm/query-builder/over-builder.d.ts

@@ -0,0 +1,59 @@
+import { DynamicReferenceBuilder } from '../dynamic/dynamic-reference-builder.js';
+import { OperationNodeSource } from '../operation-node/operation-node-source.js';
+import { OverNode } from '../operation-node/over-node.js';
+import { OrderByDirectionExpression } from '../parser/order-by-parser.js';
+import { PartitionByExpression } from '../parser/partition-by-parser.js';
+import { StringReference } from '../parser/reference-parser.js';
+export declare class OverBuilder<DB, TB extends keyof DB> implements OperationNodeSource {
+    #private;
+    constructor(props: OverBuilderProps);
+    /**
+     * Adds an order by clause item inside the over function.
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select(
+     *     eb => eb.fn.avg<number>('age').over(
+     *       ob => ob.orderBy('first_name', 'asc').orderBy('last_name', 'asc')
+     *     ).as('average_age')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select avg("age") over(order by "first_name" asc, "last_name" asc) as "average_age"
+     * from "person"
+     * ```
+     */
+    orderBy(orderBy: StringReference<DB, TB> | DynamicReferenceBuilder<any>, direction?: OrderByDirectionExpression): OverBuilder<DB, TB>;
+    /**
+     * Adds partition by clause item/s inside the over function.
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select(
+     *     eb => eb.fn.avg<number>('age').over(
+     *       ob => ob.partitionBy(['last_name', 'first_name'])
+     *     ).as('average_age')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select avg("age") over(partition by "last_name", "first_name") as "average_age"
+     * from "person"
+     * ```
+     */
+    partitionBy(partitionBy: ReadonlyArray<PartitionByExpression<DB, TB>>): OverBuilder<DB, TB>;
+    partitionBy(partitionBy: PartitionByExpression<DB, TB>): OverBuilder<DB, TB>;
+    toOperationNode(): OverNode;
+}
+export interface OverBuilderProps {
+    readonly overNode: OverNode;
+}

package/dist/esm/query-builder/over-builder.js

@@ -0,0 +1,47 @@
+/// <reference types="./over-builder.d.ts" />
+import { OverNode } from '../operation-node/over-node.js';
+import { parseOrderBy, } from '../parser/order-by-parser.js';
+import { parsePartitionBy, } from '../parser/partition-by-parser.js';
+import { freeze } from '../util/object-utils.js';
+import { preventAwait } from '../util/prevent-await.js';
+export class OverBuilder {
+    #props;
+    constructor(props) {
+        this.#props = freeze(props);
+    }
+    /**
+     * Adds an order by clause item inside the over function.
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select(
+     *     eb => eb.fn.avg<number>('age').over(
+     *       ob => ob.orderBy('first_name', 'asc').orderBy('last_name', 'asc')
+     *     ).as('average_age')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select avg("age") over(order by "first_name" asc, "last_name" asc) as "average_age"
+     * from "person"
+     * ```
+     */
+    orderBy(orderBy, direction) {
+        return new OverBuilder({
+            overNode: OverNode.cloneWithOrderByItem(this.#props.overNode, parseOrderBy(orderBy, direction)),
+        });
+    }
+    partitionBy(partitionBy) {
+        return new OverBuilder({
+            overNode: OverNode.cloneWithPartitionByItems(this.#props.overNode, parsePartitionBy(partitionBy)),
+        });
+    }
+    toOperationNode() {
+        return this.#props.overNode;
+    }
+}
+preventAwait(OverBuilder, "don't await OverBuilder instances. They are never executed directly and are always just a part of a query.");

package/dist/esm/query-builder/select-query-builder.d.ts

@@ -13,13 +13,13 @@ import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
 import { GroupByExpression } from '../parser/group-by-parser.js';
-import { UnionExpression } from '../parser/union-parser.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
 import { WhereInterface } from './where-interface.js';
 import { NoResultErrorConstructor } from './no-result-error.js';
 import { HavingInterface } from './having-interface.js';
 import { AliasedRawBuilder } from '../raw-builder/raw-builder.js';
 import { Explainable, ExplainFormat } from '../util/explainable.js';
+import { SetOperationExpression } from '../parser/set-operation-parser.js';
 export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, HavingInterface<DB, TB>, OperationNodeSource, Compilable, Explainable {
     #private;
     constructor(props: SelectQueryBuilderProps);
@@ -1202,7 +1202,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   .orderBy('name')
      * ```
      */
-    union(expression: UnionExpression<DB, O>): SelectQueryBuilder<DB, TB, O>;
+    union(expression: SetOperationExpression<DB, O>): SelectQueryBuilder<DB, TB, O>;
     /**
      * Combines another select query or raw expression to this query using `union all`.
      *
@@ -1217,7 +1217,67 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   .orderBy('name')
      * ```
      */
-    unionAll(expression: UnionExpression<DB, O>): SelectQueryBuilder<DB, TB, O>;
+    unionAll(expression: SetOperationExpression<DB, O>): SelectQueryBuilder<DB, TB, O>;
+    /**
+     * Combines another select query or raw expression to this query using `intersect`.
+     *
+     * The output row type of the combined query must match `this` query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(['id', 'first_name as name'])
+     *   .intersect(db.selectFrom('pet').select(['id', 'name']))
+     *   .orderBy('name')
+     * ```
+     */
+    intersect(expression: SetOperationExpression<DB, O>): SelectQueryBuilder<DB, TB, O>;
+    /**
+     * Combines another select query or raw expression to this query using `intersect all`.
+     *
+     * The output row type of the combined query must match `this` query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(['id', 'first_name as name'])
+     *   .intersectAll(db.selectFrom('pet').select(['id', 'name']))
+     *   .orderBy('name')
+     * ```
+     */
+    intersectAll(expression: SetOperationExpression<DB, O>): SelectQueryBuilder<DB, TB, O>;
+    /**
+     * Combines another select query or raw expression to this query using `except`.
+     *
+     * The output row type of the combined query must match `this` query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(['id', 'first_name as name'])
+     *   .except(db.selectFrom('pet').select(['id', 'name']))
+     *   .orderBy('name')
+     * ```
+     */
+    except(expression: SetOperationExpression<DB, O>): SelectQueryBuilder<DB, TB, O>;
+    /**
+     * Combines another select query or raw expression to this query using `except all`.
+     *
+     * The output row type of the combined query must match `this` query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(['id', 'first_name as name'])
+     *   .exceptAll(db.selectFrom('pet').select(['id', 'name']))
+     *   .orderBy('name')
+     * ```
+     */
+    exceptAll(expression: SetOperationExpression<DB, O>): SelectQueryBuilder<DB, TB, O>;
     /**
      * Simply calls the given function passing `this` as the only argument.
      *

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

@@ -12,10 +12,10 @@ import { LimitNode } from '../operation-node/limit-node.js';
 import { OffsetNode } from '../operation-node/offset-node.js';
 import { freeze } from '../util/object-utils.js';
 import { parseGroupBy, } from '../parser/group-by-parser.js';
-import { parseUnion } from '../parser/union-parser.js';
 import { NoResultError } from './no-result-error.js';
 import { IdentifierNode } from '../operation-node/identifier-node.js';
 import { ExplainNode } from '../operation-node/explain-node.js';
+import { parseSetOperation, } from '../parser/set-operation-parser.js';
 export class SelectQueryBuilder {
     #props;
     constructor(props) {
@@ -470,7 +470,7 @@ export class SelectQueryBuilder {
     union(expression) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithUnion(this.#props.queryNode, parseUnion(expression, false)),
+            queryNode: SelectQueryNode.cloneWithSetOperation(this.#props.queryNode, parseSetOperation('union', expression, false)),
         });
     }
     /**
@@ -490,7 +490,87 @@ export class SelectQueryBuilder {
     unionAll(expression) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithUnion(this.#props.queryNode, parseUnion(expression, true)),
+            queryNode: SelectQueryNode.cloneWithSetOperation(this.#props.queryNode, parseSetOperation('union', expression, true)),
+        });
+    }
+    /**
+     * Combines another select query or raw expression to this query using `intersect`.
+     *
+     * The output row type of the combined query must match `this` query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(['id', 'first_name as name'])
+     *   .intersect(db.selectFrom('pet').select(['id', 'name']))
+     *   .orderBy('name')
+     * ```
+     */
+    intersect(expression) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithSetOperation(this.#props.queryNode, parseSetOperation('intersect', expression, false)),
+        });
+    }
+    /**
+     * Combines another select query or raw expression to this query using `intersect all`.
+     *
+     * The output row type of the combined query must match `this` query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(['id', 'first_name as name'])
+     *   .intersectAll(db.selectFrom('pet').select(['id', 'name']))
+     *   .orderBy('name')
+     * ```
+     */
+    intersectAll(expression) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithSetOperation(this.#props.queryNode, parseSetOperation('intersect', expression, true)),
+        });
+    }
+    /**
+     * Combines another select query or raw expression to this query using `except`.
+     *
+     * The output row type of the combined query must match `this` query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(['id', 'first_name as name'])
+     *   .except(db.selectFrom('pet').select(['id', 'name']))
+     *   .orderBy('name')
+     * ```
+     */
+    except(expression) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithSetOperation(this.#props.queryNode, parseSetOperation('except', expression, false)),
+        });
+    }
+    /**
+     * Combines another select query or raw expression to this query using `except all`.
+     *
+     * The output row type of the combined query must match `this` query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(['id', 'first_name as name'])
+     *   .exceptAll(db.selectFrom('pet').select(['id', 'name']))
+     *   .orderBy('name')
+     * ```
+     */
+    exceptAll(expression) {
+        return new SelectQueryBuilder({
+            ...this.#props,
+            queryNode: SelectQueryNode.cloneWithSetOperation(this.#props.queryNode, parseSetOperation('except', expression, true)),
         });
     }
     /**

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

@@ -60,7 +60,6 @@ import { ColumnDefinitionNode } from '../operation-node/column-definition-node.j
 import { ModifyColumnNode } from '../operation-node/modify-column-node.js';
 import { OnDuplicateKeyNode } from '../operation-node/on-duplicate-key-node.js';
 import { ColumnNode } from '../operation-node/column-node.js';
-import { UnionNode } from '../operation-node/union-node.js';
 import { CreateViewNode } from '../operation-node/create-view-node.js';
 import { DropViewNode } from '../operation-node/drop-view-node.js';
 import { GeneratedNode } from '../operation-node/generated-node.js';
@@ -73,6 +72,12 @@ import { CreateTypeNode } from '../operation-node/create-type-node.js';
 import { DropTypeNode } from '../operation-node/drop-type-node.js';
 import { ExplainNode } from '../operation-node/explain-node.js';
 import { SchemableIdentifierNode } from '../operation-node/schemable-identifier-node.js';
+import { DefaultInsertValueNode } from '../operation-node/default-insert-value-node.js';
+import { AggregateFunctionNode } from '../operation-node/aggregate-function-node.js';
+import { OverNode } from '../operation-node/over-node.js';
+import { PartitionByNode } from '../operation-node/partition-by-node.js';
+import { PartitionByItemNode } from '../operation-node/partition-by-item-node.js';
+import { SetOperationNode } from '../operation-node/set-operation-node.js';
 export declare class DefaultQueryCompiler extends OperationNodeVisitor implements QueryCompiler {
     #private;
     protected get numParameters(): number;
@@ -144,7 +149,7 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected visitModifyColumn(node: ModifyColumnNode): void;
     protected visitAddConstraint(node: AddConstraintNode): void;
     protected visitDropConstraint(node: DropConstraintNode): void;
-    protected visitUnion(node: UnionNode): void;
+    protected visitSetOperation(node: SetOperationNode): void;
     protected visitCreateView(node: CreateViewNode): void;
     protected visitDropView(node: DropViewNode): void;
     protected visitGenerated(node: GeneratedNode): void;
@@ -153,6 +158,11 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected visitCreateType(node: CreateTypeNode): void;
     protected visitDropType(node: DropTypeNode): void;
     protected visitExplain(node: ExplainNode): void;
+    protected visitDefaultInsertValue(_: DefaultInsertValueNode): void;
+    protected visitAggregateFunction(node: AggregateFunctionNode): void;
+    protected visitOver(node: OverNode): void;
+    protected visitPartitionBy(node: PartitionByNode): void;
+    protected visitPartitionByItem(node: PartitionByItemNode): void;
     protected append(str: string): void;
     protected appendValue(parameter: unknown): void;
     protected getLeftIdentifierWrapper(): string;

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

@@ -2,10 +2,9 @@
 import { InsertQueryNode } from '../operation-node/insert-query-node.js';
 import { OperationNodeVisitor } from '../operation-node/operation-node-visitor.js';
 import { QueryNode } from '../operation-node/query-node.js';
-import { RawNode } from '../operation-node/raw-node.js';
 import { getLast, freeze, isString, isNumber, isBoolean, isNull, isDate, isBigInt, } from '../util/object-utils.js';
-import { UnionNode } from '../operation-node/union-node.js';
 import { CreateViewNode } from '../operation-node/create-view-node.js';
+import { SetOperationNode } from '../operation-node/set-operation-node.js';
 export class DefaultQueryCompiler extends OperationNodeVisitor {
     #sql = '';
     #parameters = [];
@@ -29,7 +28,7 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         const wrapInParens = this.parentNode !== undefined &&
             !InsertQueryNode.is(this.parentNode) &&
             !CreateViewNode.is(this.parentNode) &&
-            !UnionNode.is(this.parentNode);
+            !SetOperationNode.is(this.parentNode);
         if (this.parentNode === undefined && node.explain) {
             this.visitNode(node.explain);
             this.append(' ');
@@ -71,9 +70,9 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append(' ');
             this.visitNode(node.having);
         }
-        if (node.union) {
+        if (node.setOperations) {
             this.append(' ');
-            this.compileList(node.union, ' ');
+            this.compileList(node.setOperations, ' ');
         }
         if (node.orderBy) {
             this.append(' ');
@@ -542,13 +541,7 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         }
         if (node.expression) {
             this.append(' (');
-            if (RawNode.is(node.expression)) {
-                this.append('(');
-            }
             this.visitNode(node.expression);
-            if (RawNode.is(node.expression)) {
-                this.append(')');
-            }
             this.append(')');
         }
     }
@@ -750,12 +743,13 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append(' restrict');
         }
     }
-    visitUnion(node) {
-        this.append('union ');
+    visitSetOperation(node) {
+        this.append(node.operator);
+        this.append(' ');
         if (node.all) {
             this.append('all ');
         }
-        this.visitNode(node.union);
+        this.visitNode(node.expression);
     }
     visitCreateView(node) {
         this.append('create ');
@@ -865,6 +859,42 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append(this.getRightExplainOptionsWrapper());
         }
     }
+    visitDefaultInsertValue(_) {
+        this.append('default');
+    }
+    visitAggregateFunction(node) {
+        this.append(node.func);
+        this.append('(');
+        if (node.distinct) {
+            this.append('distinct ');
+        }
+        this.visitNode(node.column);
+        this.append(')');
+        if (node.over) {
+            this.append(' ');
+            this.visitNode(node.over);
+        }
+    }
+    visitOver(node) {
+        this.append('over(');
+        if (node.partitionBy) {
+            this.visitNode(node.partitionBy);
+            if (node.orderBy) {
+                this.append(' ');
+            }
+        }
+        if (node.orderBy) {
+            this.visitNode(node.orderBy);
+        }
+        this.append(')');
+    }
+    visitPartitionBy(node) {
+        this.append('partition by ');
+        this.compileList(node.items);
+    }
+    visitPartitionByItem(node) {
+        this.visitNode(node.partitionBy);
+    }
     append(str) {
         this.#sql += str;
     }

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

@@ -7,13 +7,14 @@ export interface Sql {
      * import { sql } from 'kysely'
      *
      * const id = 123
-     *
      * const snippet = sql<Person[]>`select * from person where id = ${id}`
      * ```
      *
      * Substitutions (the things inside `${}`) are automatically passed to the database
-     * as parameters and are NOT interpolated to the SQL string. There's no need to worry
-     * about SQL injection vulnerabilities.
+     * as parameters and are never interpolated to the SQL string. There's no need to worry
+     * about SQL injection vulnerabilities. Substitutions can be values, other `sql`
+     * expressions, queries and almost anything else Kysely can produce and they get
+     * handled correctly. See the examples below.
      *
      * If you need your substitutions to be interpreted as identifiers, value literals or
      * lists of things, see the {@link Sql.ref}, {@link Sql.table}, {@link Sql.id},
@@ -29,8 +30,7 @@ export interface Sql {
      *   .selectFrom('person')
      *   .select(
      *     // If you use `sql` in a select statement, remember to call the `as`
-     *     // method to give it an alias. Otherwise Kysely is not able to add
-     *     // the column to the result type.
+     *     // method to give it an alias.
      *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name')
      *   )
      *   .where(sql`birthdate between ${date1} and ${date2}`)
@@ -97,6 +97,14 @@ export interface Sql {
      * type-safety though... But it's possible.
      */
     <T = unknown>(sqlFragments: TemplateStringsArray, ...parameters: unknown[]): RawBuilder<T>;
+    /**
+     * `sql.value(value)` is a shortcut for:
+     *
+     * ```ts
+     * sql`${value}`
+     * ```
+     */
+    value(value: unknown): RawBuilder<unknown>;
     /**
      * This can be used to add runtime column references to SQL snippets.
      *