kysely 0.7.7 → 0.8.1

package/dist/cjs/query-builder/expression-builder.d.ts

@@ -1,9 +1,42 @@
 import { TableExpression, QueryBuilderWithTable } from '../parser/table-parser.js';
 import { NoopQueryExecutor } from '../query-executor/noop-query-executor.js';
 import { ParseContext } from '../parser/parse-context.js';
+import { FunctionBuilder } from './function-builder.js';
 export declare class ExpressionBuilder<DB, TB extends keyof DB> {
     #private;
     constructor(props: ExpressionBuilderProps);
+    /**
+     * Returns a {@link FunctionBuilder} that can be used to write type safe function
+     * calls.
+     *
+     * The difference between this and {@link Kysely.fn} is that this one is more
+     * type safe. You can only refer to columns visible to the part of the query
+     * you are building. {@link Kysely.fn} allows you to refer to columns in any
+     * table of the database even if it doesn't produce valid SQL.
+     *
+     * ```ts
+     * await db.selectFrom('person')
+     *   .innerJoin('pet', 'pet.owner_id', 'person.id')
+     *   .select([
+     *     'person.id',
+     *     (qb) => qb.fn.count('pet.id').as('pet_count')
+     *   ])
+     *   .groupBy('person.id')
+     *   .having(count('pet.id'), '>', 10)
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (postgresql):
+     *
+     * ```sql
+     * select "person"."id", count("pet"."id") as "pet_count"
+     * from "person"
+     * inner join "pet" on "pet"."owner_id" = "person"."id"
+     * group by "person"."id"
+     * having count("pet"."id") > $1
+     * ```
+     */
+    get fn(): FunctionBuilder<DB, TB>;
     /**
      * Creates a subquery.
      *

package/dist/cjs/query-builder/expression-builder.js

@@ -7,11 +7,46 @@ const table_parser_js_1 = require("../parser/table-parser.js");
 const with_schema_plugin_js_1 = require("../plugin/with-schema/with-schema-plugin.js");
 const query_id_js_1 = require("../util/query-id.js");
 const object_utils_js_1 = require("../util/object-utils.js");
+const function_builder_js_1 = require("./function-builder.js");
 class ExpressionBuilder {
     #props;
     constructor(props) {
         this.#props = (0, object_utils_js_1.freeze)(props);
     }
+    /**
+     * Returns a {@link FunctionBuilder} that can be used to write type safe function
+     * calls.
+     *
+     * The difference between this and {@link Kysely.fn} is that this one is more
+     * type safe. You can only refer to columns visible to the part of the query
+     * you are building. {@link Kysely.fn} allows you to refer to columns in any
+     * table of the database even if it doesn't produce valid SQL.
+     *
+     * ```ts
+     * await db.selectFrom('person')
+     *   .innerJoin('pet', 'pet.owner_id', 'person.id')
+     *   .select([
+     *     'person.id',
+     *     (qb) => qb.fn.count('pet.id').as('pet_count')
+     *   ])
+     *   .groupBy('person.id')
+     *   .having(count('pet.id'), '>', 10)
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (postgresql):
+     *
+     * ```sql
+     * select "person"."id", count("pet"."id") as "pet_count"
+     * from "person"
+     * inner join "pet" on "pet"."owner_id" = "person"."id"
+     * group by "person"."id"
+     * having count("pet"."id") > $1
+     * ```
+     */
+    get fn() {
+        return new function_builder_js_1.FunctionBuilder({ executor: this.#props.executor });
+    }
     subQuery(table) {
         return new query_builder_js_1.QueryBuilder({
             queryId: (0, query_id_js_1.createQueryId)(),

package/dist/cjs/query-builder/function-builder.d.ts

@@ -0,0 +1,112 @@
+import { StringReference, ExtractTypeFromReferenceExpression } from '../parser/reference-parser.js';
+import { QueryExecutor } from '../query-executor/query-executor.js';
+import { RawBuilder } from '../raw-builder/raw-builder.js';
+/**
+ * Helpers for type safe SQL function calls.
+ *
+ * @example
+ * ```ts
+ * const { count } = db.fn
+ *
+ * await db.selectFrom('person')
+ *   .innerJoin('pet', 'pet.owner_id', 'person.id')
+ *   .select([
+ *     'person.id',
+ *     count('pet.id').as('pet_count')
+ *   ])
+ *   .groupBy('person.id')
+ *   .having(count('pet.id'), '>', 10)
+ *   .execute()
+ * ```
+ *
+ * The generated SQL (postgresql):
+ *
+ * ```sql
+ * select "person"."id", count("pet"."id") as "pet_count"
+ * from "person"
+ * inner join "pet" on "pet"."owner_id" = "person"."id"
+ * group by "person"."id"
+ * having count("pet"."id") > $1
+ * ```
+ */
+export declare class FunctionBuilder<DB, TB extends keyof DB> {
+    #private;
+    constructor(props: FunctionBuilderProps);
+    /**
+     * Calls the `max` function for the column given as the argument.
+     */
+    min<C extends StringReference<DB, TB>>(column: C): RawBuilder<ExtractTypeFromReferenceExpression<DB, TB, C>>;
+    /**
+     * Calls the `min` function for the column given as the argument.
+     */
+    max<C extends StringReference<DB, TB>>(column: C): RawBuilder<ExtractTypeFromReferenceExpression<DB, TB, C>>;
+    /**
+     * Calls the `avg` 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` 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
+     * know if you've done so.
+     *
+     * You can specify the output type of the expression by providing
+     * the type as the first type argument:
+     *
+     * ```ts
+     * const { avg } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(avg<number>('price'))
+     *   .execute()
+     * ```
+     */
+    avg<O extends number | string, C extends StringReference<DB, TB> = any>(column: C): RawBuilder<O>;
+    /**
+     * 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` 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
+     * know if you've done so.
+     *
+     * You can specify the output type of the expression by providing
+     * the type as the first type argument:
+     *
+     * ```ts
+     * const { sum } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(sum<number>('price'))
+     *   .execute()
+     * ```
+     */
+    sum<O extends number | string | BigInt, C extends StringReference<DB, TB> = any>(column: C): RawBuilder<O>;
+    /**
+     * 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` 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
+     * know if you've done so.
+     *
+     * You can specify the output type of the expression by providing
+     * the type as the first type argument:
+     *
+     * ```ts
+     * const { count } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(count<number>('price'))
+     *   .execute()
+     * ```
+     */
+    count<O extends number | string | BigInt, C extends StringReference<DB, TB> = any>(column: C): RawBuilder<O>;
+}
+export interface FunctionBuilderProps {
+    readonly executor: QueryExecutor;
+}

package/dist/cjs/query-builder/function-builder.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FunctionBuilder = void 0;
+const raw_builder_js_1 = require("../raw-builder/raw-builder.js");
+const object_utils_js_1 = require("../util/object-utils.js");
+const query_id_js_1 = require("../util/query-id.js");
+/**
+ * Helpers for type safe SQL function calls.
+ *
+ * @example
+ * ```ts
+ * const { count } = db.fn
+ *
+ * await db.selectFrom('person')
+ *   .innerJoin('pet', 'pet.owner_id', 'person.id')
+ *   .select([
+ *     'person.id',
+ *     count('pet.id').as('pet_count')
+ *   ])
+ *   .groupBy('person.id')
+ *   .having(count('pet.id'), '>', 10)
+ *   .execute()
+ * ```
+ *
+ * The generated SQL (postgresql):
+ *
+ * ```sql
+ * select "person"."id", count("pet"."id") as "pet_count"
+ * from "person"
+ * inner join "pet" on "pet"."owner_id" = "person"."id"
+ * group by "person"."id"
+ * having count("pet"."id") > $1
+ * ```
+ */
+class FunctionBuilder {
+    #props;
+    constructor(props) {
+        this.#props = (0, object_utils_js_1.freeze)(props);
+        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.
+     */
+    min(column) {
+        return this.#oneArgFunction('min', column);
+    }
+    /**
+     * Calls the `min` function for the column given as the argument.
+     */
+    max(column) {
+        return this.#oneArgFunction('max', column);
+    }
+    /**
+     * Calls the `avg` 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` 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
+     * know if you've done so.
+     *
+     * You can specify the output type of the expression by providing
+     * the type as the first type argument:
+     *
+     * ```ts
+     * const { avg } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(avg<number>('price'))
+     *   .execute()
+     * ```
+     */
+    avg(column) {
+        return this.#oneArgFunction('avg', 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` 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
+     * know if you've done so.
+     *
+     * You can specify the output type of the expression by providing
+     * the type as the first type argument:
+     *
+     * ```ts
+     * const { sum } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(sum<number>('price'))
+     *   .execute()
+     * ```
+     */
+    sum(column) {
+        return this.#oneArgFunction('sum', column);
+    }
+    /**
+     * 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` 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
+     * know if you've done so.
+     *
+     * You can specify the output type of the expression by providing
+     * the type as the first type argument:
+     *
+     * ```ts
+     * const { count } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(count<number>('price'))
+     *   .execute()
+     * ```
+     */
+    count(column) {
+        return this.#oneArgFunction('count', column);
+    }
+    #oneArgFunction(fn, column) {
+        return new raw_builder_js_1.RawBuilder({
+            queryId: (0, query_id_js_1.createQueryId)(),
+            executor: this.#props.executor,
+            sql: `${fn}(??)`,
+            parameters: [column],
+        });
+    }
+}
+exports.FunctionBuilder = FunctionBuilder;

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

@@ -2,7 +2,7 @@ import { AliasNode } from '../operation-node/alias-node.js';
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { JoinCallbackExpression, JoinReferenceExpression } from '../parser/join-parser.js';
-import { TableExpression, QueryBuilderWithTable } from '../parser/table-parser.js';
+import { TableExpression, QueryBuilderWithTable, QueryBuilderWithLeftJoin, QueryBuilderWithRightJoin, QueryBuilderWithFullJoin } from '../parser/table-parser.js';
 import { SelectExpression, QueryBuilderWithSelection, SelectAllQueryBuilder } from '../parser/select-parser.js';
 import { ExistsExpression, FilterOperator } from '../parser/filter-parser.js';
 import { InsertObject } from '../parser/insert-values-parser.js';
@@ -10,7 +10,7 @@ import { QueryBuilderWithReturning } from '../parser/returning-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
 import { ValueExpressionOrList } from '../parser/value-parser.js';
 import { QueryNode } from '../operation-node/query-node.js';
-import { AnyColumn, ManyResultRowType, NonEmptySingleResultRowType, SingleResultRowType } from './type-utils.js';
+import { AnyColumn, ManyResultRowType, NonEmptySingleResultRowType, SingleResultRowType } from '../util/type-utils.js';
 import { OrderByDirectionExpression, OrderByExpression } from '../parser/order-by-parser.js';
 import { MutationObject } from '../parser/update-set-parser.js';
 import { Compilable } from '../util/compilable.js';
@@ -869,20 +869,20 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * Just like {@link QueryBuilder.innerJoin | innerJoin} but adds a left join
      * instead of an inner join.
      */
-    leftJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithTable<DB, TB, O, TE>;
-    leftJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithTable<DB, TB, O, TE>;
+    leftJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithLeftJoin<DB, TB, O, TE>;
+    leftJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithLeftJoin<DB, TB, O, TE>;
     /**
      * Just like {@link QueryBuilder.innerJoin | innerJoin} but adds a right join
      * instead of an inner join.
      */
-    rightJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithTable<DB, TB, O, TE>;
-    rightJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithTable<DB, TB, O, TE>;
+    rightJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithRightJoin<DB, TB, O, TE>;
+    rightJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithRightJoin<DB, TB, O, TE>;
     /**
      * Just like {@link QueryBuilder.innerJoin | innerJoin} but adds a full join
      * instead of an inner join.
      */
-    fullJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithTable<DB, TB, O, TE>;
-    fullJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithTable<DB, TB, O, TE>;
+    fullJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithFullJoin<DB, TB, O, TE>;
+    fullJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithFullJoin<DB, TB, O, TE>;
     /**
      * Sets the values to insert for an {@link Kysely.insertInto | insert} query.
      *

package/dist/cjs/query-compiler/compiled-query.d.ts

@@ -1,4 +1,4 @@
 export interface CompiledQuery {
     readonly sql: string;
-    readonly bindings: ReadonlyArray<any>;
+    readonly parameters: ReadonlyArray<any>;
 }

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

@@ -62,7 +62,7 @@ import { ModifyColumnNode } from '../operation-node/modify-column-node.js';
 import { OnDuplicateKeyNode } from '../operation-node/on-duplicate-key-node.js';
 export declare class DefaultQueryCompiler extends OperationNodeVisitor implements QueryCompiler {
     #private;
-    protected get numBindings(): number;
+    protected get numParameters(): number;
     compileQuery(node: RootOperationNode): CompiledQuery;
     protected getSql(): string;
     protected visitSelectQuery(node: SelectQueryNode): void;
@@ -129,6 +129,6 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected getLeftIdentifierWrapper(): string;
     protected getRightIdentifierWrapper(): string;
     protected getCurrentParameterPlaceholder(): string;
-    protected addBinding(binding: any): void;
+    protected addParameter(parameter: any): void;
     protected appendImmediateValue(value: PrimitiveValue): void;
 }

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

@@ -8,17 +8,17 @@ const raw_node_js_1 = require("../operation-node/raw-node.js");
 const object_utils_js_1 = require("../util/object-utils.js");
 class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisitor {
     #sqlFragments = [];
-    #bindings = [];
-    get numBindings() {
-        return this.#bindings.length;
+    #parameters = [];
+    get numParameters() {
+        return this.#parameters.length;
     }
     compileQuery(node) {
         this.#sqlFragments = [];
-        this.#bindings = [];
+        this.#parameters = [];
         this.visitNode(node);
         return (0, object_utils_js_1.freeze)({
             sql: this.getSql(),
-            bindings: this.#bindings,
+            parameters: this.#parameters,
         });
     }
     getSql() {
@@ -640,7 +640,7 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
         this.#sqlFragments.push(str);
     }
     appendValue(value) {
-        this.addBinding(value);
+        this.addParameter(value);
         this.append(this.getCurrentParameterPlaceholder());
     }
     getLeftIdentifierWrapper() {
@@ -650,10 +650,10 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
         return '"';
     }
     getCurrentParameterPlaceholder() {
-        return '$' + this.numBindings;
+        return '$' + this.numParameters;
     }
-    addBinding(binding) {
-        this.#bindings.push(binding);
+    addParameter(parameter) {
+        this.#parameters.push(parameter);
     }
     appendImmediateValue(value) {
         if ((0, object_utils_js_1.isString)(value)) {

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

@@ -9,6 +9,9 @@ import { QueryNode } from '../operation-node/query-node.js';
 import { RawNode } from '../operation-node/raw-node.js';
 import { CompiledQuery } from './compiled-query.js';
 export declare type RootOperationNode = QueryNode | CreateTableNode | CreateIndexNode | AlterTableNode | DropTableNode | DropIndexNode | CreateSchemaNode | DropSchemaNode | RawNode;
+/**
+ * a `QueryCompiler` compiles a query expressed as a tree of `OperationNodes` into SQL.
+ */
 export interface QueryCompiler {
     compileQuery(node: RootOperationNode): CompiledQuery;
 }

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

@@ -1,6 +1,6 @@
 import { QueryBuilder } from './query-builder/query-builder.js';
 import { QueryBuilderWithTable, TableExpression, TableReference } from './parser/table-parser.js';
-import { InsertResultTypeTag, DeleteResultTypeTag, UpdateResultTypeTag } from './query-builder/type-utils.js';
+import { InsertResultTypeTag, DeleteResultTypeTag, UpdateResultTypeTag } from './util/type-utils.js';
 import { QueryExecutor } from './query-executor/query-executor.js';
 import { RawBuilder } from './raw-builder/raw-builder.js';
 import { CommonTableExpression, QueryCreatorWithCommonTableExpression } from './parser/with-parser.js';
@@ -276,11 +276,11 @@ export declare class QueryCreator<DB> {
      * 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.
      *
-     * @param sql - The raw SQL. Special strings `?` and `??` can be used to provide
-     *    parameter bindings. `?` for values and `??` for identifiers such as column names
+     * @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 `??` bindings in
+     * @param params - The parameters that will be bound to the `?` and `??` placeholders in
      *    the sql string.
      *
      * @example
@@ -318,7 +318,7 @@ export declare class QueryCreator<DB> {
      *     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 `??` bindings to provide `first_name` and `last_name` like
+     * We could've also used a `??` placeholder to provide `first_name` and `last_name` like
      * this:
      *
      * ```ts
@@ -333,9 +333,9 @@ export declare class QueryCreator<DB> {
      *
      * 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 bindings
+     * 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 bindings.
+     * and known at compile time, there is no reason to use parameters.
      *
      * @example
      * Example of using `raw` in `where`:
@@ -361,7 +361,7 @@ export declare class QueryCreator<DB> {
      *
      * 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 `?` binding for it.
+     * a `?` placeholder for it.
      *
      * @example
      * Example of creating a completely raw query from scratch:
@@ -375,7 +375,7 @@ export declare class QueryCreator<DB> {
      * The result of `execute()` method is always an array. In this case the type of
      * the `persons` variable is `Person[]`.
      */
-    raw<T = unknown>(sql: string, params?: any[]): RawBuilder<T>;
+    raw<T = unknown>(sql: string, parameters?: any[]): RawBuilder<T>;
 }
 export interface QueryCreatorProps {
     readonly executor: QueryExecutor;

package/dist/cjs/query-creator.js

@@ -218,11 +218,11 @@ class QueryCreator {
      * 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.
      *
-     * @param sql - The raw SQL. Special strings `?` and `??` can be used to provide
-     *    parameter bindings. `?` for values and `??` for identifiers such as column names
+     * @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 `??` bindings in
+     * @param params - The parameters that will be bound to the `?` and `??` placeholders in
      *    the sql string.
      *
      * @example
@@ -260,7 +260,7 @@ class QueryCreator {
      *     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 `??` bindings to provide `first_name` and `last_name` like
+     * We could've also used a `??` placeholder to provide `first_name` and `last_name` like
      * this:
      *
      * ```ts
@@ -275,9 +275,9 @@ class QueryCreator {
      *
      * 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 bindings
+     * 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 bindings.
+     * and known at compile time, there is no reason to use parameters.
      *
      * @example
      * Example of using `raw` in `where`:
@@ -303,7 +303,7 @@ class QueryCreator {
      *
      * 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 `?` binding for it.
+     * a `?` placeholder for it.
      *
      * @example
      * Example of creating a completely raw query from scratch:
@@ -317,11 +317,12 @@ class QueryCreator {
      * The result of `execute()` method is always an array. In this case the type of
      * the `persons` variable is `Person[]`.
      */
-    raw(sql, params) {
+    raw(sql, parameters) {
         return new raw_builder_js_1.RawBuilder({
-            sql,
-            params,
+            queryId: (0, query_id_js_1.createQueryId)(),
             executor: this.#props.executor,
+            sql,
+            parameters,
         });
     }
 }

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

@@ -4,10 +4,18 @@ 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';
 export declare class RawBuilder<O = unknown> implements OperationNodeSource {
     #private;
-    constructor(args: RawBuilderConstructorArgs);
+    constructor(props: RawBuilderProps);
     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.
+     */
+    castTo<T>(): RawBuilder<T>;
     toOperationNode(): RawNode;
     compile(): CompiledQuery;
     execute(): Promise<QueryResult<O>>;
@@ -29,8 +37,9 @@ export declare class AliasedRawBuilder<O = unknown, A extends string = never> im
     toOperationNode(): AliasNode;
     constructor(rawBuilder: RawBuilder<O>, alias: A);
 }
-export interface RawBuilderConstructorArgs {
-    sql: string;
-    params?: any;
-    executor: QueryExecutor;
+export interface RawBuilderProps {
+    readonly queryId: QueryId;
+    readonly executor: QueryExecutor;
+    readonly sql: string;
+    readonly parameters?: any;
 }