kysely 0.12.1 → 0.14.1

package/dist/esm/query-builder/on-conflict-builder.js

@@ -0,0 +1,317 @@
+import { ColumnNode } from '../operation-node/column-node.js';
+import { IdentifierNode } from '../operation-node/identifier-node.js';
+import { OnConflictNode } from '../operation-node/on-conflict-node.js';
+import { parseWhereFilter, parseReferenceFilter, parseExistFilter, parseNotExistFilter, } from '../parser/filter-parser.js';
+import { parseUpdateObject, } from '../parser/update-set-parser.js';
+import { freeze } from '../util/object-utils.js';
+import { preventAwait } from '../util/prevent-await.js';
+export class OnConflictBuilder {
+    #props;
+    constructor(props) {
+        this.#props = freeze(props);
+    }
+    /**
+     * Specify a single column as the conflict target.
+     *
+     * Also see the {@link columns}, {@link constraint} and {@link expression}
+     * methods for alternative ways to specify the conflict target.
+     */
+    column(column) {
+        const columnNode = ColumnNode.create(column);
+        return new OnConflictBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWith(this.#props.onConflictNode, {
+                columns: this.#props.onConflictNode.columns
+                    ? freeze([...this.#props.onConflictNode.columns, columnNode])
+                    : freeze([columnNode]),
+            }),
+        });
+    }
+    /**
+     * Specify a list of columns as the conflict target.
+     *
+     * Also see the {@link column}, {@link constraint} and {@link expression}
+     * methods for alternative ways to specify the conflict target.
+     */
+    columns(columns) {
+        const columnNodes = columns.map(ColumnNode.create);
+        return new OnConflictBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWith(this.#props.onConflictNode, {
+                columns: this.#props.onConflictNode.columns
+                    ? freeze([...this.#props.onConflictNode.columns, ...columnNodes])
+                    : freeze(columnNodes),
+            }),
+        });
+    }
+    /**
+     * Specify a specific constraint by name as the conflict target.
+     *
+     * Also see the {@link column}, {@link columns} and {@link expression}
+     * methods for alternative ways to specify the conflict target.
+     */
+    constraint(constraintName) {
+        return new OnConflictBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWith(this.#props.onConflictNode, {
+                constraint: IdentifierNode.create(constraintName),
+            }),
+        });
+    }
+    /**
+     * Specify an expression as the conflict target.
+     *
+     * This can be used if the unique index is an expression index.
+     *
+     * Also see the {@link column}, {@link columns} and {@link constraint}
+     * methods for alternative ways to specify the conflict target.
+     */
+    expression(expression) {
+        return new OnConflictBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWith(this.#props.onConflictNode, {
+                indexExpression: expression.toOperationNode(),
+            }),
+        });
+    }
+    where(...args) {
+        return new OnConflictBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWithIndexWhere(this.#props.onConflictNode, parseWhereFilter(this.#props.parseContext, args)),
+        });
+    }
+    /**
+     * Specify an index predicate for the index target.
+     *
+     * See {@link WhereInterface.whereRef} for more info.
+     */
+    whereRef(lhs, op, rhs) {
+        return new OnConflictBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWithIndexWhere(this.#props.onConflictNode, parseReferenceFilter(this.#props.parseContext, lhs, op, rhs)),
+        });
+    }
+    orWhere(...args) {
+        return new OnConflictBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWithIndexOrWhere(this.#props.onConflictNode, parseWhereFilter(this.#props.parseContext, args)),
+        });
+    }
+    /**
+     * Specify an index predicate for the index target.
+     *
+     * See {@link WhereInterface.orWhereRef} for more info.
+     */
+    orWhereRef(lhs, op, rhs) {
+        return new OnConflictBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWithIndexOrWhere(this.#props.onConflictNode, parseReferenceFilter(this.#props.parseContext, lhs, op, rhs)),
+        });
+    }
+    /**
+     * Specify an index predicate for the index target.
+     *
+     * See {@link WhereInterface.whereExists} for more info.
+     */
+    whereExists(arg) {
+        return new OnConflictBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWithIndexWhere(this.#props.onConflictNode, parseExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    /**
+     * Specify an index predicate for the index target.
+     *
+     * See {@link WhereInterface.whereNotExists} for more info.
+     */
+    whereNotExists(arg) {
+        return new OnConflictBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWithIndexWhere(this.#props.onConflictNode, parseNotExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    /**
+     * Specify an index predicate for the index target.
+     *
+     * See {@link WhereInterface.orWhereExists} for more info.
+     */
+    orWhereExists(arg) {
+        return new OnConflictBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWithIndexOrWhere(this.#props.onConflictNode, parseExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    /**
+     * Specify an index predicate for the index target.
+     *
+     * See {@link WhereInterface.orWhereNotExists} for more info.
+     */
+    orWhereNotExists(arg) {
+        return new OnConflictBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWithIndexOrWhere(this.#props.onConflictNode, parseNotExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    /**
+     * Adds the "do nothing" conflict action.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db
+     *   .insertInto('person')
+     *   .values({ id: db.generated, first_name, pic })
+     *   .onConflict((oc) => oc
+     *     .column('pic')
+     *     .doNothing()
+     *   )
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "pic")
+     * values ($1, $2)
+     * on conflict ("pic") do nothing
+     * ```
+     */
+    doNothing() {
+        return new OnConflictDoNothingBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWith(this.#props.onConflictNode, {
+                doNothing: true,
+            }),
+        });
+    }
+    /**
+     * Adds the "do update set" conflict action.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db
+     *   .insertInto('person')
+     *   .values({ id: db.generated, first_name, pic })
+     *   .onConflict((oc) => oc
+     *     .column('pic')
+     *     .doUpdateSet({ first_name })
+     *   )
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "pic")
+     * values ($1, $2)
+     * on conflict ("pic")
+     * do update set "first_name" = $3
+     * ```
+     */
+    doUpdateSet(updates) {
+        return new OnConflictUpdateBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWith(this.#props.onConflictNode, {
+                updates: parseUpdateObject(this.#props.parseContext, updates),
+            }),
+        });
+    }
+}
+preventAwait(OnConflictBuilder, "don't await OnConflictBuilder instances.");
+export class OnConflictDoNothingBuilder {
+    #props;
+    constructor(props) {
+        this.#props = freeze(props);
+    }
+    toOperationNode() {
+        return this.#props.onConflictNode;
+    }
+}
+preventAwait(OnConflictDoNothingBuilder, "don't await OnConflictDoNothingBuilder instances.");
+export class OnConflictUpdateBuilder {
+    #props;
+    constructor(props) {
+        this.#props = freeze(props);
+    }
+    where(...args) {
+        return new OnConflictUpdateBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWithUpdateWhere(this.#props.onConflictNode, parseWhereFilter(this.#props.parseContext, args)),
+        });
+    }
+    /**
+     * Specify a where condition for the update operation.
+     *
+     * See {@link WhereInterface.whereRef} for more info.
+     */
+    whereRef(lhs, op, rhs) {
+        return new OnConflictUpdateBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWithUpdateWhere(this.#props.onConflictNode, parseReferenceFilter(this.#props.parseContext, lhs, op, rhs)),
+        });
+    }
+    orWhere(...args) {
+        return new OnConflictUpdateBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWithUpdateOrWhere(this.#props.onConflictNode, parseWhereFilter(this.#props.parseContext, args)),
+        });
+    }
+    /**
+     * Specify a where condition for the update operation.
+     *
+     * See {@link WhereInterface.orWhereRef} for more info.
+     */
+    orWhereRef(lhs, op, rhs) {
+        return new OnConflictUpdateBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWithUpdateOrWhere(this.#props.onConflictNode, parseReferenceFilter(this.#props.parseContext, lhs, op, rhs)),
+        });
+    }
+    /**
+     * Specify a where condition for the update operation.
+     *
+     * See {@link WhereInterface.whereExists} for more info.
+     */
+    whereExists(arg) {
+        return new OnConflictUpdateBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWithUpdateWhere(this.#props.onConflictNode, parseExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    /**
+     * Specify a where condition for the update operation.
+     *
+     * See {@link WhereInterface.whereNotExists} for more info.
+     */
+    whereNotExists(arg) {
+        return new OnConflictUpdateBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWithUpdateWhere(this.#props.onConflictNode, parseNotExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    /**
+     * Specify a where condition for the update operation.
+     *
+     * See {@link WhereInterface.orWhereExists} for more info.
+     */
+    orWhereExists(arg) {
+        return new OnConflictUpdateBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWithUpdateOrWhere(this.#props.onConflictNode, parseExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    /**
+     * Specify a where condition for the update operation.
+     *
+     * See {@link WhereInterface.orWhereNotExists} for more info.
+     */
+    orWhereNotExists(arg) {
+        return new OnConflictUpdateBuilder({
+            ...this.#props,
+            onConflictNode: OnConflictNode.cloneWithUpdateOrWhere(this.#props.onConflictNode, parseNotExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    toOperationNode() {
+        return this.#props.onConflictNode;
+    }
+}
+preventAwait(OnConflictUpdateBuilder, "don't await OnConflictUpdateBuilder instances.");

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

@@ -64,10 +64,11 @@ 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 { GeneratedAlwaysAsNode } from '../operation-node/generated-always-as-node.js';
+import { GeneratedNode } from '../operation-node/generated-node.js';
 import { DefaultValueNode } from '../operation-node/default-value-node.js';
 import { OnNode } from '../operation-node/on-node.js';
 import { ValuesNode } from '../operation-node/values-node.js';
+import { CommonTableExpressionNameNode } from '../operation-node/common-table-expression-name-node.js';
 export declare class DefaultQueryCompiler extends OperationNodeVisitor implements QueryCompiler {
     #private;
     protected get numParameters(): number;
@@ -129,6 +130,7 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected visitList(node: ListNode): void;
     protected visitWith(node: WithNode): void;
     protected visitCommonTableExpression(node: CommonTableExpressionNode): void;
+    protected visitCommonTableExpressionName(node: CommonTableExpressionNameNode): void;
     protected visitAlterTable(node: AlterTableNode): void;
     protected visitAddColumn(node: AddColumnNode): void;
     protected visitRenameColumn(node: RenameColumnNode): void;
@@ -140,7 +142,7 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected visitUnion(node: UnionNode): void;
     protected visitCreateView(node: CreateViewNode): void;
     protected visitDropView(node: DropViewNode): void;
-    protected visitGeneratedAlwaysAs(node: GeneratedAlwaysAsNode): void;
+    protected visitGenerated(node: GeneratedNode): void;
     protected visitDefaultValue(node: DefaultValueNode): void;
     protected append(str: string): void;
     protected appendValue(parameter: unknown): void;

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

@@ -321,15 +321,18 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         this.visitNode(node.column);
         this.append(' ');
         this.visitNode(node.dataType);
-        if (node.generatedAlwaysAs) {
+        if (node.unsigned) {
+            this.append(' unsigned');
+        }
+        if (node.generated) {
             this.append(' ');
-            this.visitNode(node.generatedAlwaysAs);
+            this.visitNode(node.generated);
         }
         if (node.defaultTo) {
             this.append(' ');
             this.visitNode(node.defaultTo);
         }
-        if (!node.nullable) {
+        if (node.notNull) {
             this.append(' not null');
         }
         if (node.unique) {
@@ -448,16 +451,29 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.compileList(node.columns);
             this.append(')');
         }
-        if (node.constraint) {
+        else if (node.constraint) {
             this.append(' on constraint ');
             this.visitNode(node.constraint);
         }
+        else if (node.indexExpression) {
+            this.append(' (');
+            this.visitNode(node.indexExpression);
+            this.append(')');
+        }
+        if (node.indexWhere) {
+            this.append(' ');
+            this.visitNode(node.indexWhere);
+        }
         if (node.doNothing === true) {
             this.append(' do nothing');
         }
         else if (node.updates) {
             this.append(' do update set ');
             this.compileList(node.updates);
+            if (node.updateWhere) {
+                this.append(' ');
+                this.visitNode(node.updateWhere);
+            }
         }
     }
     visitOnDuplicateKey(node) {
@@ -570,6 +586,9 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
     }
     visitWith(node) {
         this.append('with ');
+        if (node.recursive) {
+            this.append('recursive ');
+        }
         this.compileList(node.expressions);
     }
     visitCommonTableExpression(node) {
@@ -577,6 +596,14 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         this.append(' as ');
         this.visitNode(node.expression);
     }
+    visitCommonTableExpressionName(node) {
+        this.visitNode(node.table);
+        if (node.columns) {
+            this.append('(');
+            this.compileList(node.columns);
+            this.append(')');
+        }
+    }
     visitAlterTable(node) {
         this.append('alter table ');
         this.visitNode(node.table);
@@ -708,10 +735,23 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         }
         this.visitNode(node.name);
     }
-    visitGeneratedAlwaysAs(node) {
-        this.append('generated always as (');
-        this.visitNode(node.expression);
-        this.append(')');
+    visitGenerated(node) {
+        this.append('generated ');
+        if (node.always) {
+            this.append('always ');
+        }
+        if (node.byDefault) {
+            this.append('by default ');
+        }
+        this.append('as ');
+        if (node.identity) {
+            this.append('identity');
+        }
+        if (node.expression) {
+            this.append('(');
+            this.visitNode(node.expression);
+            this.append(')');
+        }
         if (node.stored) {
             this.append(' stored');
         }

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

@@ -5,7 +5,7 @@ import { UpdateQueryBuilder } from './query-builder/update-query-builder.js';
 import { TableExpression, TableExpressionDatabase, TableExpressionTables, TableReference } from './parser/table-parser.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';
+import { CommonTableExpression, QueryCreatorWithCommonTableExpression, RecursiveCommonTableExpression } from './parser/with-parser.js';
 import { WithNode } from './operation-node/with-node.js';
 import { ParseContext } from './parser/parse-context.js';
 import { InsertResult } from './query-builder/insert-result.js';
@@ -206,7 +206,7 @@ export declare class QueryCreator<DB> {
      */
     updateTable<TR extends TableReference<DB>>(table: TR): UpdateQueryBuilder<TableExpressionDatabase<DB, TR>, TableExpressionTables<DB, never, TR>, UpdateResult>;
     /**
-     * Creates a `with` query (common table expressions).
+     * Creates a `with` query (Common Table Expression).
      *
      * ### Examples
      *
@@ -227,8 +227,32 @@ export declare class QueryCreator<DB> {
      *   .selectAll()
      *   .execute()
      * ```
+     *
+     * The CTE name can optionally specify column names in addition to
+     * a name. In that case Kysely requires the expression to retun
+     * rows with the same columns.
+     *
+     * ```ts
+     * await db
+     *   .with('jennifers(id, age)', (db) => db
+     *     .selectFrom('person')
+     *     .where('first_name', '=', 'Jennifer')
+     *     // This is ok since we return columns with the same
+     *     // names as specified by `jennifers(id, age)`.
+     *     .select(['id', 'age'])
+     *   )
+     *   .selectFrom('jennifers')
+     *   .selectAll()
+     *   .execute()
+     * ```
+     */
+    with<N extends string, E extends CommonTableExpression<DB, N>>(name: N, expression: E): QueryCreatorWithCommonTableExpression<DB, N, E>;
+    /**
+     * Creates a recursive `with` query (Common Table Expression).
+     *
+     * See the {@link with} method for examples and more documentation.
      */
-    with<N extends string, E extends CommonTableExpression<DB>>(name: N, expression: E): QueryCreatorWithCommonTableExpression<DB, N, E>;
+    withRecursive<N extends string, E extends RecursiveCommonTableExpression<DB, N>>(name: N, expression: E): QueryCreatorWithCommonTableExpression<DB, N, E>;
     /**
      * Sets the schema to be used for all table references that don't explicitly
      * specify a schema.

package/dist/esm/query-creator.js

@@ -133,7 +133,7 @@ export class QueryCreator {
         });
     }
     /**
-     * Creates a `with` query (common table expressions).
+     * Creates a `with` query (Common Table Expression).
      *
      * ### Examples
      *
@@ -154,6 +154,24 @@ export class QueryCreator {
      *   .selectAll()
      *   .execute()
      * ```
+     *
+     * The CTE name can optionally specify column names in addition to
+     * a name. In that case Kysely requires the expression to retun
+     * rows with the same columns.
+     *
+     * ```ts
+     * await db
+     *   .with('jennifers(id, age)', (db) => db
+     *     .selectFrom('person')
+     *     .where('first_name', '=', 'Jennifer')
+     *     // This is ok since we return columns with the same
+     *     // names as specified by `jennifers(id, age)`.
+     *     .select(['id', 'age'])
+     *   )
+     *   .selectFrom('jennifers')
+     *   .selectAll()
+     *   .execute()
+     * ```
      */
     with(name, expression) {
         const cte = parseCommonTableExpression(this.#props.parseContext, name, expression);
@@ -164,6 +182,20 @@ export class QueryCreator {
                 : WithNode.create(cte),
         });
     }
+    /**
+     * Creates a recursive `with` query (Common Table Expression).
+     *
+     * See the {@link with} method for examples and more documentation.
+     */
+    withRecursive(name, expression) {
+        const cte = parseCommonTableExpression(this.#props.parseContext, name, expression);
+        return new QueryCreator({
+            ...this.#props,
+            withNode: this.#props.withNode
+                ? WithNode.cloneWithExpression(this.#props.withNode, cte)
+                : WithNode.create(cte, { recursive: true }),
+        });
+    }
     /**
      * Sets the schema to be used for all table references that don't explicitly
      * specify a schema.

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

@@ -7,10 +7,29 @@ import { QueryExecutor } from './query-executor.js';
 export declare class DefaultQueryExecutor extends QueryExecutor {
     #private;
     constructor(compiler: QueryCompiler, connectionProvider: ConnectionProvider, plugins?: KyselyPlugin[]);
+    /**
+     * Compiles the transformed query into SQL. You usually want to pass
+     * the output of {@link transformQuery} into this method but you can
+     * compile any query using this method.
+     */
     compileQuery(node: RootOperationNode): CompiledQuery;
     protected executeQueryImpl<R>(compiledQuery: CompiledQuery): Promise<QueryResult<R>>;
+    /**
+     * Returns a copy of this executor with a plugin added as the
+     * last plugin.
+     */
     withPlugin(plugin: KyselyPlugin): DefaultQueryExecutor;
+    /**
+     * Returns a copy of this executor with a plugin added as the
+     * first plugin.
+     */
     withPluginAtFront(plugin: KyselyPlugin): DefaultQueryExecutor;
+    /**
+     * Returns a copy of this executor with a new connection provider.
+     */
     withConnectionProvider(connectionProvider: ConnectionProvider): QueryExecutor;
+    /**
+     * Returns a copy of this executor without any plugins.
+     */
     withoutPlugins(): QueryExecutor;
 }

package/dist/esm/query-executor/noop-query-executor.d.ts

@@ -8,10 +8,29 @@ import { KyselyPlugin } from '../plugin/kysely-plugin.js';
  * other needed things to actually execute queries.
  */
 export declare class NoopQueryExecutor extends QueryExecutor {
+    /**
+     * Compiles the transformed query into SQL. You usually want to pass
+     * the output of {@link transformQuery} into this method but you can
+     * compile any query using this method.
+     */
     compileQuery(): CompiledQuery;
     protected executeQueryImpl<R>(): Promise<QueryResult<R>>;
+    /**
+     * Returns a copy of this executor with a new connection provider.
+     */
     withConnectionProvider(): QueryExecutor;
+    /**
+     * Returns a copy of this executor with a plugin added as the
+     * last plugin.
+     */
     withPlugin(plugin: KyselyPlugin): NoopQueryExecutor;
+    /**
+     * Returns a copy of this executor with a plugin added as the
+     * first plugin.
+     */
     withPluginAtFront(plugin: KyselyPlugin): NoopQueryExecutor;
+    /**
+     * Returns a copy of this executor without any plugins.
+     */
     withoutPlugins(): QueryExecutor;
 }

package/dist/esm/raw-builder/raw-builder.js

@@ -47,7 +47,7 @@ export class RawBuilder {
             if (match.index > 0 && sql[match.index - 1] === '\\') {
                 continue;
             }
-            sqlFragments.push(sql.slice(sqlIdx, match.index).replaceAll('\\?', '?'));
+            sqlFragments.push(sql.slice(sqlIdx, match.index).replace(/\\\?/g, '?'));
             argNodes.push(parseRawArg(str, parameters[paramIdx]));
             sqlIdx = match.index + str.length;
             ++paramIdx;