kysely 0.26.1 → 0.26.3

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

@@ -2,11 +2,11 @@ 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, From, FromTables } from '../parser/table-parser.js';
-import { SelectExpression, SelectArg } from '../parser/select-parser.js';
-import { ReturningRow } from '../parser/returning-parser.js';
+import { SelectExpression, SelectCallback } from '../parser/select-parser.js';
+import { ReturningCallbackRow, ReturningRow } from '../parser/returning-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
 import { QueryNode } from '../operation-node/query-node.js';
-import { DrainOuterGeneric, NarrowPartial, Nullable, ShallowRecord, SimplifyResult, SimplifySingleResult } from '../util/type-utils.js';
+import { DrainOuterGeneric, NarrowPartial, Nullable, ShallowRecord, SimplifyResult, SimplifySingleResult, SqlBool } from '../util/type-utils.js';
 import { UpdateQueryNode } from '../operation-node/update-query-node.js';
 import { UpdateObject, UpdateObjectFactory } from '../parser/update-set-parser.js';
 import { Compilable } from '../util/compilable.js';
@@ -14,7 +14,7 @@ import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
 import { UpdateResult } from './update-result.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
-import { WhereExpressionFactory, WhereInterface } from './where-interface.js';
+import { WhereInterface } from './where-interface.js';
 import { ReturningInterface } from './returning-interface.js';
 import { NoResultErrorConstructor } from './no-result-error.js';
 import { Selectable } from '../util/column-type.js';
@@ -23,6 +23,7 @@ import { AliasedExpression, Expression } from '../expression/expression.js';
 import { ComparisonOperatorExpression, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
 import { KyselyTypeError } from '../util/type-error.js';
 import { Streamable } from '../util/streamable.js';
+import { ExpressionOrFactory } from '../parser/expression-parser.js';
 export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable<O>, Explainable, Streamable<O> {
     #private;
     constructor(props: UpdateQueryBuilderProps);
@@ -79,7 +80,34 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
-     * <!-- siteExample("where", "OR where", 30) -->
+     * <!-- siteExample("where", "Object filter", 30) -->
+     *
+     * You can use the `and` function to create a simple equality
+     * filter using an object
+     *
+     * ```ts
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .selectAll()
+     *   .where((eb) => eb.and({
+     *     first_name: 'Jennifer',
+     *     last_name: eb.ref('first_name')
+     *   }))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select *
+     * from "person"
+     * where (
+     *   "first_name" = $1
+     *   and "last_name" = "first_name"
+     * )
+     * ```
+     *
+     * <!-- siteExample("where", "OR where", 40) -->
      *
      * To combine conditions using `OR`, you can use the expression builder.
      * There are two ways to create `OR` expressions. Both are shown in this
@@ -114,7 +142,7 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * )
      * ```
      *
-     * <!-- siteExample("where", "Conditional where calls", 40) -->
+     * <!-- siteExample("where", "Conditional where calls", 50) -->
      *
      * You can add expressions conditionally like this:
      *
@@ -209,7 +237,7 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
-     * <!-- siteExample("where", "Complex where clause", 50) -->
+     * <!-- siteExample("where", "Complex where clause", 60) -->
      *
      * For complex `where` expressions you can pass in a single callback and
      * use the `ExpressionBuilder` to build your expression:
@@ -299,8 +327,7 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * ```
      */
     where<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): UpdateQueryBuilder<DB, UT, TB, O>;
-    where(factory: WhereExpressionFactory<DB, TB>): UpdateQueryBuilder<DB, UT, TB, O>;
-    where(expression: Expression<any>): UpdateQueryBuilder<DB, UT, TB, O>;
+    where(expression: ExpressionOrFactory<DB, TB, SqlBool>): UpdateQueryBuilder<DB, UT, TB, O>;
     /**
      * Adds a `where` clause where both sides of the operator are references
      * to columns.
@@ -714,7 +741,9 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      *   .executeTakeFirst()
      * ```
      */
-    returning<SE extends SelectExpression<DB, TB>>(selection: SelectArg<DB, TB, SE>): UpdateQueryBuilder<DB, UT, TB, ReturningRow<DB, TB, O, SE>>;
+    returning<SE extends SelectExpression<DB, TB>>(selections: ReadonlyArray<SE>): UpdateQueryBuilder<DB, UT, TB, ReturningRow<DB, TB, O, SE>>;
+    returning<CB extends SelectCallback<DB, TB>>(callback: CB): UpdateQueryBuilder<DB, UT, TB, ReturningCallbackRow<DB, TB, O, CB>>;
+    returning<SE extends SelectExpression<DB, TB>>(selection: SE): UpdateQueryBuilder<DB, UT, TB, ReturningRow<DB, TB, O, SE>>;
     /**
      * Adds a `returning *` to an insert/update/delete query on databases
      * that support `returning` such as PostgreSQL.

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

@@ -9,7 +9,7 @@ import { preventAwait } from '../util/prevent-await.js';
 import { freeze } from '../util/object-utils.js';
 import { UpdateResult } from './update-result.js';
 import { isNoResultErrorConstructor, NoResultError, } from './no-result-error.js';
-import { parseReferentialComparison, parseFilter, } from '../parser/binary-operation-parser.js';
+import { parseReferentialBinaryOperation, parseValueBinaryOperationOrExpression, } from '../parser/binary-operation-parser.js';
 export class UpdateQueryBuilder {
     #props;
     constructor(props) {
@@ -18,13 +18,13 @@ export class UpdateQueryBuilder {
     where(...args) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseFilter(args)),
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseValueBinaryOperationOrExpression(args)),
         });
     }
     whereRef(lhs, op, rhs) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseReferentialComparison(lhs, op, rhs)),
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseReferentialBinaryOperation(lhs, op, rhs)),
         });
     }
     clearWhere() {

package/dist/esm/query-builder/where-interface.d.ts

@@ -1,8 +1,7 @@
-import { Expression } from '../expression/expression.js';
 import { ComparisonOperatorExpression, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
 import { SqlBool } from '../util/type-utils.js';
-import { ExpressionBuilder } from '../expression/expression-builder.js';
+import { ExpressionOrFactory } from '../parser/expression-parser.js';
 export interface WhereInterface<DB, TB extends keyof DB> {
     /**
      * Adds a `where` expression to the query.
@@ -57,7 +56,34 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
-     * <!-- siteExample("where", "OR where", 30) -->
+     * <!-- siteExample("where", "Object filter", 30) -->
+     *
+     * You can use the `and` function to create a simple equality
+     * filter using an object
+     *
+     * ```ts
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .selectAll()
+     *   .where((eb) => eb.and({
+     *     first_name: 'Jennifer',
+     *     last_name: eb.ref('first_name')
+     *   }))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select *
+     * from "person"
+     * where (
+     *   "first_name" = $1
+     *   and "last_name" = "first_name"
+     * )
+     * ```
+     *
+     * <!-- siteExample("where", "OR where", 40) -->
      *
      * To combine conditions using `OR`, you can use the expression builder.
      * There are two ways to create `OR` expressions. Both are shown in this
@@ -92,7 +118,7 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * )
      * ```
      *
-     * <!-- siteExample("where", "Conditional where calls", 40) -->
+     * <!-- siteExample("where", "Conditional where calls", 50) -->
      *
      * You can add expressions conditionally like this:
      *
@@ -187,7 +213,7 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
-     * <!-- siteExample("where", "Complex where clause", 50) -->
+     * <!-- siteExample("where", "Complex where clause", 60) -->
      *
      * For complex `where` expressions you can pass in a single callback and
      * use the `ExpressionBuilder` to build your expression:
@@ -277,8 +303,7 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * ```
      */
     where<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): WhereInterface<DB, TB>;
-    where(factory: WhereExpressionFactory<DB, TB>): WhereInterface<DB, TB>;
-    where(expression: Expression<any>): WhereInterface<DB, TB>;
+    where(expression: ExpressionOrFactory<DB, TB, SqlBool>): WhereInterface<DB, TB>;
     /**
      * Adds a `where` clause where both sides of the operator are references
      * to columns.
@@ -351,4 +376,3 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      */
     clearWhere(): WhereInterface<DB, TB>;
 }
-export type WhereExpressionFactory<DB, TB extends keyof DB> = (eb: ExpressionBuilder<DB, TB>) => Expression<SqlBool>;

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

@@ -87,6 +87,7 @@ import { JSONReferenceNode } from '../operation-node/json-reference-node.js';
 import { JSONPathNode } from '../operation-node/json-path-node.js';
 import { JSONPathLegNode } from '../operation-node/json-path-leg-node.js';
 import { JSONOperatorChainNode } from '../operation-node/json-operator-chain-node.js';
+import { TupleNode } from '../operation-node/tuple-node.js';
 export declare class DefaultQueryCompiler extends OperationNodeVisitor implements QueryCompiler {
     #private;
     protected get numParameters(): number;
@@ -113,6 +114,7 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected visitOr(node: OrNode): void;
     protected visitValue(node: ValueNode): void;
     protected visitValueList(node: ValueListNode): void;
+    protected visitTuple(node: TupleNode): void;
     protected visitPrimitiveValueList(node: PrimitiveValueListNode): void;
     protected visitParens(node: ParensNode): void;
     protected visitJoin(node: JoinNode): void;
@@ -194,4 +196,5 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected sanitizeIdentifier(identifier: string): string;
     protected addParameter(parameter: unknown): void;
     protected appendImmediateValue(value: unknown): void;
+    protected sortSelectModifiers(arr: SelectModifierNode[]): ReadonlyArray<SelectModifierNode>;
 }

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

@@ -2,6 +2,7 @@
 import { InsertQueryNode } from '../operation-node/insert-query-node.js';
 import { OperationNodeVisitor } from '../operation-node/operation-node-visitor.js';
 import { OperatorNode } from '../operation-node/operator-node.js';
+import { ParensNode } from '../operation-node/parens-node.js';
 import { QueryNode } from '../operation-node/query-node.js';
 import { freeze, isString, isNumber, isBoolean, isNull, isDate, isBigInt, } from '../util/object-utils.js';
 import { CreateViewNode } from '../operation-node/create-view-node.js';
@@ -27,6 +28,7 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
     }
     visitSelectQuery(node) {
         const wrapInParens = this.parentNode !== undefined &&
+            !ParensNode.is(this.parentNode) &&
             !InsertQueryNode.is(this.parentNode) &&
             !CreateViewNode.is(this.parentNode) &&
             !SetOperationNode.is(this.parentNode);
@@ -41,20 +43,23 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.visitNode(node.with);
             this.append(' ');
         }
-        this.append('select ');
+        this.append('select');
         if (node.distinctOn) {
-            this.compileDistinctOn(node.distinctOn);
             this.append(' ');
+            this.compileDistinctOn(node.distinctOn);
         }
-        if (node.frontModifiers && node.frontModifiers.length > 0) {
-            this.compileList(node.frontModifiers, ' ');
+        if (node.frontModifiers?.length) {
             this.append(' ');
+            this.compileList(node.frontModifiers, ' ');
         }
         if (node.selections) {
+            this.append(' ');
             this.compileList(node.selections);
+        }
+        if (node.from) {
             this.append(' ');
+            this.visitNode(node.from);
         }
-        this.visitNode(node.from);
         if (node.joins) {
             this.append(' ');
             this.compileList(node.joins, ' ');
@@ -87,9 +92,9 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append(' ');
             this.visitNode(node.offset);
         }
-        if (node.endModifiers && node.endModifiers.length > 0) {
+        if (node.endModifiers?.length) {
             this.append(' ');
-            this.compileList(node.endModifiers, ' ');
+            this.compileList(this.sortSelectModifiers([...node.endModifiers]), ' ');
         }
         if (wrapInParens) {
             this.append(')');
@@ -271,6 +276,11 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         this.compileList(node.values);
         this.append(')');
     }
+    visitTuple(node) {
+        this.append('(');
+        this.compileList(node.values);
+        this.append(')');
+    }
     visitPrimitiveValueList(node) {
         this.append('(');
         const { values } = node;
@@ -651,6 +661,12 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
     visitCommonTableExpression(node) {
         this.visitNode(node.name);
         this.append(' as ');
+        if (isBoolean(node.materialized)) {
+            if (!node.materialized) {
+                this.append('not ');
+            }
+            this.append('materialized ');
+        }
         this.visitNode(node.expression);
     }
     visitCommonTableExpressionName(node) {
@@ -1054,6 +1070,13 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             throw new Error(`invalid immediate value ${value}`);
         }
     }
+    sortSelectModifiers(arr) {
+        arr.sort((left, right) => left.modifier && right.modifier
+            ? SELECT_MODIFIER_PRIORITY[left.modifier] -
+                SELECT_MODIFIER_PRIORITY[right.modifier]
+            : 1);
+        return freeze(arr);
+    }
 }
 const SELECT_MODIFIER_SQL = freeze({
     ForKeyShare: 'for key share',
@@ -1064,6 +1087,15 @@ const SELECT_MODIFIER_SQL = freeze({
     SkipLocked: 'skip locked',
     Distinct: 'distinct',
 });
+const SELECT_MODIFIER_PRIORITY = freeze({
+    ForKeyShare: 1,
+    ForNoKeyUpdate: 1,
+    ForUpdate: 1,
+    ForShare: 1,
+    NoWait: 2,
+    SkipLocked: 2,
+    Distinct: 0,
+});
 const JOIN_TYPE_SQL = freeze({
     InnerJoin: 'inner join',
     LeftJoin: 'left join',

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

@@ -10,6 +10,8 @@ import { InsertResult } from './query-builder/insert-result.js';
 import { DeleteResult } from './query-builder/delete-result.js';
 import { UpdateResult } from './query-builder/update-result.js';
 import { KyselyPlugin } from './plugin/kysely-plugin.js';
+import { CTEBuilderCallback } from './query-builder/cte-builder.js';
+import { CallbackSelection, SelectCallback, SelectExpression, Selection } from './parser/select-parser.js';
 export declare class QueryCreator<DB> {
     #private;
     constructor(props: QueryCreatorProps);
@@ -125,6 +127,56 @@ export declare class QueryCreator<DB> {
     selectFrom<TE extends keyof DB & string>(from: TE): SelectQueryBuilder<DB, ExtractTableAlias<DB, TE>, {}>;
     selectFrom<TE extends AnyAliasedTable<DB>>(from: TE): SelectQueryBuilder<DB & PickTableWithAlias<DB, TE>, ExtractTableAlias<DB, TE>, {}>;
     selectFrom<TE extends TableExpression<DB, keyof DB>>(from: TE): SelectQueryBuilder<From<DB, TE>, FromTables<DB, never, TE>, {}>;
+    /**
+     * Creates a `select` query builder without a `from` clause.
+     *
+     * If you want to create a `select from` query, use the `selectFrom` method instead.
+     * This one can be used to create a plain `select` statement without a `from` clause.
+     *
+     * This method accepts the same inputs as {@link SelectQueryBuilder.select}. See its
+     * documentation for more examples.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const result = db.selectNoFrom((eb) => [
+     *   eb.selectFrom('person')
+     *     .select('id')
+     *     .where('first_name', '=', 'Jennifer')
+     *     .limit(1)
+     *     .as('jennifer_id'),
+     *
+     *   eb.selectFrom('pet')
+     *     .select('id')
+     *     .where('name', '=', 'Doggo')
+     *     .limit(1)
+     *     .as('doggo_id')
+     *   ])
+     *   .executeTakeFirstOrThrow()
+     *
+     * console.log(result.jennifer_id)
+     * console.log(result.doggo_id)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select (
+     *   select "id"
+     *   from "person"
+     *   where "first_name" = $1
+     *   limit $2
+     * ) as "jennifer_id", (
+     *   select "id"
+     *   from "pet"
+     *   where "name" = $3
+     *   limit $4
+     * ) as "doggo_id"
+     * ```
+     */
+    selectNoFrom<SE extends SelectExpression<DB, never>>(selections: ReadonlyArray<SE>): SelectQueryBuilder<DB, never, Selection<DB, never, SE>>;
+    selectNoFrom<CB extends SelectCallback<DB, never>>(callback: CB): SelectQueryBuilder<DB, never, CallbackSelection<DB, never, CB>>;
+    selectNoFrom<SE extends SelectExpression<DB, never>>(selection: SE): SelectQueryBuilder<DB, never, Selection<DB, never, SE>>;
     /**
      * Creates an insert query.
      *
@@ -310,14 +362,36 @@ export declare class QueryCreator<DB> {
      *   .selectAll()
      *   .execute()
      * ```
+     *
+     * The first argument can also be a callback. The callback is passed
+     * a `CTEBuilder` instance that can be used to configure the CTE:
+     *
+     * ```ts
+     * await db
+     *   .with(
+     *     (cte) => cte('jennifers').materialized(),
+     *     (db) => db
+     *       .selectFrom('person')
+     *       .where('first_name', '=', 'Jennifer')
+     *       .select(['id', 'age'])
+     *   )
+     *   .selectFrom('jennifers')
+     *   .selectAll()
+     *   .execute()
+     * ```
      */
-    with<N extends string, E extends CommonTableExpression<DB, N>>(name: N, expression: E): QueryCreatorWithCommonTableExpression<DB, N, E>;
+    with<N extends string, E extends CommonTableExpression<DB, N>>(nameOrBuilder: N | CTEBuilderCallback<N>, expression: E): QueryCreatorWithCommonTableExpression<DB, N, E>;
     /**
      * Creates a recursive `with` query (Common Table Expression).
      *
+     * Note that recursiveness is a property of the whole `with` statement.
+     * You cannot have recursive and non-recursive CTEs in a same `with` statement.
+     * Therefore the recursiveness is determined by the **first** `with` or
+     * `withRecusive` call you make.
+     *
      * See the {@link with} method for examples and more documentation.
      */
-    withRecursive<N extends string, E extends RecursiveCommonTableExpression<DB, N>>(name: N, expression: E): QueryCreatorWithCommonTableExpression<DB, N, E>;
+    withRecursive<N extends string, E extends RecursiveCommonTableExpression<DB, N>>(nameOrBuilder: N | CTEBuilderCallback<N>, expression: E): QueryCreatorWithCommonTableExpression<DB, N, E>;
     /**
      * Returns a copy of this query creator instance with the given plugin installed.
      */

package/dist/esm/query-creator.js

@@ -1,5 +1,5 @@
 /// <reference types="./query-creator.d.ts" />
-import { SelectQueryBuilder } from './query-builder/select-query-builder.js';
+import { createSelectQueryBuilder, } from './query-builder/select-query-builder.js';
 import { InsertQueryBuilder } from './query-builder/insert-query-builder.js';
 import { DeleteQueryBuilder } from './query-builder/delete-query-builder.js';
 import { UpdateQueryBuilder } from './query-builder/update-query-builder.js';
@@ -13,16 +13,24 @@ import { WithNode } from './operation-node/with-node.js';
 import { createQueryId } from './util/query-id.js';
 import { WithSchemaPlugin } from './plugin/with-schema/with-schema-plugin.js';
 import { freeze } from './util/object-utils.js';
+import { parseSelectArg, } from './parser/select-parser.js';
 export class QueryCreator {
     #props;
     constructor(props) {
         this.#props = freeze(props);
     }
     selectFrom(from) {
-        return new SelectQueryBuilder({
+        return createSelectQueryBuilder({
             queryId: createQueryId(),
             executor: this.#props.executor,
-            queryNode: SelectQueryNode.create(parseTableExpressionOrList(from), this.#props.withNode),
+            queryNode: SelectQueryNode.createFrom(parseTableExpressionOrList(from), this.#props.withNode),
+        });
+    }
+    selectNoFrom(selection) {
+        return createSelectQueryBuilder({
+            queryId: createQueryId(),
+            executor: this.#props.executor,
+            queryNode: SelectQueryNode.cloneWithSelections(SelectQueryNode.create(this.#props.withNode), parseSelectArg(selection)),
         });
     }
     /**
@@ -157,9 +165,26 @@ export class QueryCreator {
      *   .selectAll()
      *   .execute()
      * ```
+     *
+     * The first argument can also be a callback. The callback is passed
+     * a `CTEBuilder` instance that can be used to configure the CTE:
+     *
+     * ```ts
+     * await db
+     *   .with(
+     *     (cte) => cte('jennifers').materialized(),
+     *     (db) => db
+     *       .selectFrom('person')
+     *       .where('first_name', '=', 'Jennifer')
+     *       .select(['id', 'age'])
+     *   )
+     *   .selectFrom('jennifers')
+     *   .selectAll()
+     *   .execute()
+     * ```
      */
-    with(name, expression) {
-        const cte = parseCommonTableExpression(name, expression);
+    with(nameOrBuilder, expression) {
+        const cte = parseCommonTableExpression(nameOrBuilder, expression);
         return new QueryCreator({
             ...this.#props,
             withNode: this.#props.withNode
@@ -170,10 +195,15 @@ export class QueryCreator {
     /**
      * Creates a recursive `with` query (Common Table Expression).
      *
+     * Note that recursiveness is a property of the whole `with` statement.
+     * You cannot have recursive and non-recursive CTEs in a same `with` statement.
+     * Therefore the recursiveness is determined by the **first** `with` or
+     * `withRecusive` call you make.
+     *
      * See the {@link with} method for examples and more documentation.
      */
-    withRecursive(name, expression) {
-        const cte = parseCommonTableExpression(name, expression);
+    withRecursive(nameOrBuilder, expression) {
+        const cte = parseCommonTableExpression(nameOrBuilder, expression);
         return new QueryCreator({
             ...this.#props,
             withNode: this.#props.withNode