kysely 0.10.1 → 0.11.0

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

@@ -18,6 +18,9 @@ import { DeleteQueryNode } from '../operation-node/delete-query-node.js';
 import { OnDuplicateKeyNode } from '../operation-node/on-duplicate-key-node.js';
 import { parseGroupBy } from '../parser/group-by-parser.js';
 import { parseUnion } from '../parser/union-parser.js';
+import { InsertResult } from './insert-result.js';
+import { UpdateResult } from './update-result.js';
+import { DeleteResult } from './delete-result.js';
 /**
  * The main query builder class.
  *
@@ -62,7 +65,7 @@ export class QueryBuilder {
      *   .whereRef('person.first_name', '=', 'pet.name')
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person", "pet" where "person"."first_name" = "pet"."name"
@@ -85,7 +88,7 @@ export class QueryBuilder {
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "person".*, (
@@ -144,7 +147,7 @@ export class QueryBuilder {
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person"
@@ -170,7 +173,7 @@ export class QueryBuilder {
      *   )
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person"
@@ -324,7 +327,7 @@ export class QueryBuilder {
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select distinct "first_name" from "person"
@@ -523,15 +526,15 @@ export class QueryBuilder {
      * values to update. In addition to the column's type, the values can be `raw`
      * instances or select queries.
      *
-     * The return value is the number of affected rows. You can use the
-     * {@link QueryBuilder.returning | returning} method on supported databases
-     * to get out the updated rows.
+     * The return value of an update query is an instance of {@link UpdateResult}.
+     * You can use the {@link QueryBuilder.returning | returning} method on
+     * supported databases to get out the updated rows.
      *
      * @example
      * Update a row in `person` table:
      *
      * ```ts
-     * const numAffectedRows = await db
+     * const result = await db
      *   .updateTable('person')
      *   .set({
      *     first_name: 'Jennifer',
@@ -539,9 +542,11 @@ export class QueryBuilder {
      *   })
      *   .where('id', '=', 1)
      *   .executeTakeFirst()
+     *
+     * console.log(result.numUpdatedRows)
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * update "person" set "first_name" = $1, "last_name" = $2 where "id" = $3
@@ -566,7 +571,7 @@ export class QueryBuilder {
      * row.id
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * update "person" set "first_name" = $1, "last_name" = $2 where "id" = $3 returning "id"
@@ -577,7 +582,7 @@ export class QueryBuilder {
      * select queries:
      *
      * ```ts
-     * const numAffectedRows = await db
+     * const result = await db
      *   .updateTable('person')
      *   .set({
      *     first_name: 'Jennifer',
@@ -586,9 +591,11 @@ export class QueryBuilder {
      *   })
      *   .where('id', '=', 1)
      *   .executeTakeFirst()
+     *
+     * console.log(result.numUpdatedRows)
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * update "person" set
@@ -614,7 +621,7 @@ export class QueryBuilder {
     }
     /**
      * Adds a `returning *` to an insert/update/delete query on databases
-     * that support `returning` such as postgres.
+     * that support `returning` such as PostgreSQL.
      */
     returningAll() {
         assertCanHaveReturningClause(this.#props.queryNode);
@@ -642,7 +649,7 @@ export class QueryBuilder {
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "person"."first_name" as "fn"
@@ -669,7 +676,7 @@ export class QueryBuilder {
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select *
@@ -701,7 +708,7 @@ export class QueryBuilder {
      * someQuery('fn')
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "person"."first_name" as "fn"
@@ -892,32 +899,22 @@ export class QueryBuilder {
      * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
      */
     async execute() {
-        const node = this.#props.executor.transformQuery(this.#props.queryNode, this.#props.queryId);
-        const compildQuery = this.#props.executor.compileQuery(node, this.#props.queryId);
+        const compildQuery = this.compile();
+        const query = compildQuery.query;
         const result = await this.#props.executor.executeQuery(compildQuery, this.#props.queryId);
-        if (InsertQueryNode.is(node)) {
-            if (this.#props.parseContext.adapter.supportsReturning &&
-                node.returning) {
-                return result.rows;
-            }
-            else if (result.insertedPrimaryKey != null) {
-                return [result.insertedPrimaryKey];
-            }
-            else {
-                return [];
-            }
+        if (this.#props.parseContext.adapter.supportsReturning &&
+            QueryNode.isMutating(query) &&
+            query.returning) {
+            return result.rows;
+        }
+        else if (InsertQueryNode.is(query)) {
+            return [new InsertResult(result.insertId)];
+        }
+        else if (UpdateQueryNode.is(query)) {
+            return [new UpdateResult(result.numUpdatedOrDeletedRows)];
         }
-        else if (UpdateQueryNode.is(node) || DeleteQueryNode.is(node)) {
-            if (this.#props.parseContext.adapter.supportsReturning &&
-                node.returning) {
-                return result.rows;
-            }
-            else if (result.numUpdatedOrDeletedRows != null) {
-                return [result.numUpdatedOrDeletedRows];
-            }
-            else {
-                return [];
-            }
+        else if (DeleteQueryNode.is(query)) {
+            return [new DeleteResult(result.numUpdatedOrDeletedRows)];
         }
         else {
             return result.rows;

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

@@ -0,0 +1,5 @@
+export declare class UpdateResult {
+    #private;
+    constructor(numUpdatedRows: bigint);
+    get numUpdatedRows(): bigint;
+}

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

@@ -0,0 +1,9 @@
+export class UpdateResult {
+    #numUpdatedRows;
+    constructor(numUpdatedRows) {
+        this.#numUpdatedRows = numUpdatedRows;
+    }
+    get numUpdatedRows() {
+        return this.#numUpdatedRows;
+    }
+}

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

@@ -1,4 +1,9 @@
+import { RootOperationNode } from './query-compiler.js';
 export interface CompiledQuery {
+    readonly query: RootOperationNode;
     readonly sql: string;
     readonly parameters: ReadonlyArray<unknown>;
 }
+export declare const CompiledQuery: Readonly<{
+    raw(sql: string): CompiledQuery;
+}>;

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

@@ -1 +1,11 @@
-export {};
+import { RawNode } from '../operation-node/raw-node.js';
+import { freeze } from '../util/object-utils.js';
+export const CompiledQuery = freeze({
+    raw(sql) {
+        return freeze({
+            sql,
+            query: RawNode.createWithSql(sql),
+            parameters: freeze([]),
+        });
+    },
+});

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

@@ -66,6 +66,7 @@ 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 { DefaultValueNode } from '../operation-node/default-value-node.js';
+import { OnNode } from '../operation-node/on-node.js';
 export declare class DefaultQueryCompiler extends OperationNodeVisitor implements QueryCompiler {
     #private;
     protected get numParameters(): number;
@@ -95,6 +96,7 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected visitPrimitiveValueList(node: PrimitiveValueListNode): void;
     protected visitParens(node: ParensNode): void;
     protected visitJoin(node: JoinNode): void;
+    protected visitOn(node: OnNode): void;
     protected visitRaw(node: RawNode): void;
     protected visitOperator(node: OperatorNode): void;
     protected visitTable(node: TableNode): void;

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

@@ -2,6 +2,8 @@ import { OperationNodeVisitor } from '../operation-node/operation-node-visitor.j
 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';
 export class DefaultQueryCompiler extends OperationNodeVisitor {
     #sql = '';
     #parameters = [];
@@ -13,6 +15,7 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         this.#parameters = [];
         this.visitNode(node);
         return freeze({
+            query: node,
             sql: this.getSql(),
             parameters: [...this.#parameters],
         });
@@ -21,9 +24,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         return this.#sql;
     }
     visitSelectQuery(node) {
-        // This is a sub query if this is not the root node.
-        const isSubQuery = this.nodeStack.length !== 1;
-        if (isSubQuery) {
+        const wrapInParens = this.nodeStack.length !== 1 &&
+            !CreateViewNode.is(this.parentNode) &&
+            !UnionNode.is(this.parentNode);
+        if (wrapInParens) {
             this.append('(');
         }
         if (node.with) {
@@ -82,7 +86,7 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
                 this.append(SELECT_MODIFIER_SQL[modifier]);
             });
         }
-        if (isSubQuery) {
+        if (wrapInParens) {
             this.append(')');
         }
     }
@@ -262,11 +266,15 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         this.append(JOIN_TYPE_SQL[node.joinType]);
         this.append(' ');
         this.visitNode(node.table);
-        this.append(' on ');
         if (node.on) {
+            this.append(' ');
             this.visitNode(node.on);
         }
     }
+    visitOn(node) {
+        this.append('on ');
+        this.visitNode(node.on);
+    }
     visitRaw(node) {
         node.sqlFragments.forEach((sql, i) => {
             this.append(sql);
@@ -310,16 +318,16 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         if (!node.nullable) {
             this.append(' not null');
         }
-        if (node.autoIncrement) {
-            this.append(' ');
-            this.append(this.getAutoIncrement());
-        }
         if (node.unique) {
             this.append(' unique');
         }
         if (node.primaryKey) {
             this.append(' primary key');
         }
+        if (node.autoIncrement) {
+            this.append(' ');
+            this.append(this.getAutoIncrement());
+        }
         if (node.references) {
             this.append(' ');
             this.visitNode(node.references);
@@ -657,6 +665,9 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append('materialized ');
         }
         this.append('view ');
+        if (node.ifNotExists) {
+            this.append('if not exists ');
+        }
         this.visitNode(node.name);
         this.append(' ');
         if (node.columns) {
@@ -732,17 +743,17 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         }
     }
 }
-const SELECT_MODIFIER_SQL = {
+const SELECT_MODIFIER_SQL = freeze({
     ForKeyShare: 'for key share',
     ForNoKeyUpdate: 'for no key update',
     ForUpdate: 'for update',
     ForShare: 'for share',
     NoWait: 'nowait',
     SkipLocked: 'skip locked',
-};
-const JOIN_TYPE_SQL = {
+});
+const JOIN_TYPE_SQL = freeze({
     InnerJoin: 'inner join',
     LeftJoin: 'left join',
     RightJoin: 'right join',
     FullJoin: 'full join',
-};
+});

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

@@ -1,11 +1,13 @@
 import { QueryBuilder } from './query-builder/query-builder.js';
 import { QueryBuilderWithTable, TableExpression, TableReference } from './parser/table-parser.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';
 import { WithNode } from './operation-node/with-node.js';
 import { ParseContext } from './parser/parse-context.js';
+import { InsertResult } from './query-builder/insert-result.js';
+import { DeleteResult } from './query-builder/delete-result.js';
+import { UpdateResult } from './query-builder/update-result.js';
 export declare class QueryCreator<DB> {
     #private;
     constructor(props: QueryCreatorProps);
@@ -21,7 +23,7 @@ export declare class QueryCreator<DB> {
      * db.selectFrom('person').selectAll()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person"
@@ -38,7 +40,7 @@ export declare class QueryCreator<DB> {
      * console.log(persons[0].id)
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "p"."id", "p"."first_name" from "person" as "p"
@@ -57,7 +59,7 @@ export declare class QueryCreator<DB> {
      * console.log(persons[0].identifier)
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "p"."identifier",
@@ -79,7 +81,7 @@ export declare class QueryCreator<DB> {
      * console.log(items[0].one)
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "q"."one",
@@ -106,7 +108,7 @@ export declare class QueryCreator<DB> {
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "p".id, "a"."species", "q"."one"
@@ -121,20 +123,17 @@ export declare class QueryCreator<DB> {
     /**
      * Creates an insert query.
      *
-     * The return value of this query is `number | undefined` because of the differences
-     * between database engines. Most engines (like Mysql) return the auto incrementing
-     * primary key (if it exists), but some (like postgres) return nothing by default.
-     * If you are running a database engine like `Mysql` that always returns the primary
-     * key, you can safely use `!` or the {@link QueryBuilder.castTo | castTo} method
-     * to cast away the `undefined` from the type.
+     * The return value of this query is an instance of {@link InsertResult}. {@link InsertResult}
+     * has the {@link InsertResult.insertId | insertId} field that holds the auto incremented id of
+     * the inserted row if the db returned one.
      *
      * See the {@link QueryBuilder.values | values} method for more info and examples. Also see
      * the {@link QueryBuilder.returning | returning} method for a way to return columns
-     * on supported databases like postgres.
+     * on supported databases like PostgreSQL.
      *
      * @example
      * ```ts
-     * const maybePrimaryKey: number | undefined = await db
+     * const result = await db
      *   .insertInto('person')
      *   .values({
      *     id: db.generated,
@@ -142,10 +141,12 @@ export declare class QueryCreator<DB> {
      *     last_name: 'Aniston'
      *   })
      *   .executeTakeFirst()
+     *
+     * console.log(result.insertId)
      * ```
      *
      * @example
-     * Some databases like postgres support the `returning` method:
+     * Some databases like PostgreSQL support the `returning` method:
      *
      * ```ts
      * const { id } = await db
@@ -159,22 +160,26 @@ export declare class QueryCreator<DB> {
      *   .executeTakeFirst()
      * ```
      */
-    insertInto<T extends keyof DB & string>(table: T): QueryBuilder<DB, T, InsertResultTypeTag>;
+    insertInto<T extends keyof DB & string>(table: T): QueryBuilder<DB, T, InsertResult>;
     /**
      * Creates a delete query.
      *
      * See the {@link QueryBuilder.where} method for examples on how to specify
-     * a where clause for the delete operation .
+     * a where clause for the delete operation.
+     *
+     * The return value of the query is an instance of {@link DeleteResult}.
      *
      * @example
      * ```ts
-     * const numAffectedRows = await db
+     * const result = await db
      *   .deleteFrom('person')
      *   .where('person.id', '=', 1)
      *   .executeTakeFirst()
+     *
+     * console.log(result.numDeletedRows)
      * ```
      */
-    deleteFrom<TR extends TableReference<DB>>(table: TR): QueryBuilderWithTable<DB, never, DeleteResultTypeTag, TR>;
+    deleteFrom<TR extends TableReference<DB>>(table: TR): QueryBuilderWithTable<DB, never, DeleteResult, TR>;
     /**
      * Creates an update query.
      *
@@ -184,16 +189,20 @@ export declare class QueryCreator<DB> {
      * See the {@link QueryBuilder.set} method for examples on how to
      * specify the updates.
      *
+     * The return value of the query is an {@link UpdateResult}.
+     *
      * @example
      * ```ts
-     * const numAffectedRows = await db
+     * const result = await db
      *   .updateTable('person')
      *   .set({ first_name: 'Jennifer' })
      *   .where('person.id', '=', 1)
      *   .executeTakeFirst()
+     *
+     * console.log(result.numUpdatedRows)
      * ```
      */
-    updateTable<TR extends TableReference<DB>>(table: TR): QueryBuilderWithTable<DB, never, UpdateResultTypeTag, TR>;
+    updateTable<TR extends TableReference<DB>>(table: TR): QueryBuilderWithTable<DB, never, UpdateResult, TR>;
     /**
      * Creates a `with` query (common table expressions).
      *
@@ -233,7 +242,7 @@ export declare class QueryCreator<DB> {
      *  .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "mammals"."pet"
@@ -253,7 +262,7 @@ export declare class QueryCreator<DB> {
      *  .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "p"."name" from "mammals"."pet" as "p"
@@ -298,7 +307,7 @@ export declare class QueryCreator<DB> {
      * console.log(person.name)
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select concat(first_name, ' ', last_name) as "name"
@@ -356,7 +365,7 @@ export declare class QueryCreator<DB> {
      * }
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person" where now() - birth_date > interval $1 year
@@ -370,7 +379,8 @@ export declare class QueryCreator<DB> {
      * Example of creating a completely raw query from scratch:
      *
      * ```ts
-     * const persons = await db.raw<Person>('select p.* from person p').execute()
+     * const result = await db.raw<Person>('select p.* from person p').execute()
+     * const persons = result.rows
      * ```
      *
      * For a raw query, you need to specify the type of the returned __row__. In

package/dist/esm/query-creator.js

@@ -26,20 +26,17 @@ export class QueryCreator {
     /**
      * Creates an insert query.
      *
-     * The return value of this query is `number | undefined` because of the differences
-     * between database engines. Most engines (like Mysql) return the auto incrementing
-     * primary key (if it exists), but some (like postgres) return nothing by default.
-     * If you are running a database engine like `Mysql` that always returns the primary
-     * key, you can safely use `!` or the {@link QueryBuilder.castTo | castTo} method
-     * to cast away the `undefined` from the type.
+     * The return value of this query is an instance of {@link InsertResult}. {@link InsertResult}
+     * has the {@link InsertResult.insertId | insertId} field that holds the auto incremented id of
+     * the inserted row if the db returned one.
      *
      * See the {@link QueryBuilder.values | values} method for more info and examples. Also see
      * the {@link QueryBuilder.returning | returning} method for a way to return columns
-     * on supported databases like postgres.
+     * on supported databases like PostgreSQL.
      *
      * @example
      * ```ts
-     * const maybePrimaryKey: number | undefined = await db
+     * const result = await db
      *   .insertInto('person')
      *   .values({
      *     id: db.generated,
@@ -47,10 +44,12 @@ export class QueryCreator {
      *     last_name: 'Aniston'
      *   })
      *   .executeTakeFirst()
+     *
+     * console.log(result.insertId)
      * ```
      *
      * @example
-     * Some databases like postgres support the `returning` method:
+     * Some databases like PostgreSQL support the `returning` method:
      *
      * ```ts
      * const { id } = await db
@@ -76,14 +75,18 @@ export class QueryCreator {
      * Creates a delete query.
      *
      * See the {@link QueryBuilder.where} method for examples on how to specify
-     * a where clause for the delete operation .
+     * a where clause for the delete operation.
+     *
+     * The return value of the query is an instance of {@link DeleteResult}.
      *
      * @example
      * ```ts
-     * const numAffectedRows = await db
+     * const result = await db
      *   .deleteFrom('person')
      *   .where('person.id', '=', 1)
      *   .executeTakeFirst()
+     *
+     * console.log(result.numDeletedRows)
      * ```
      */
     deleteFrom(table) {
@@ -103,13 +106,17 @@ export class QueryCreator {
      * See the {@link QueryBuilder.set} method for examples on how to
      * specify the updates.
      *
+     * The return value of the query is an {@link UpdateResult}.
+     *
      * @example
      * ```ts
-     * const numAffectedRows = await db
+     * const result = await db
      *   .updateTable('person')
      *   .set({ first_name: 'Jennifer' })
      *   .where('person.id', '=', 1)
      *   .executeTakeFirst()
+     *
+     * console.log(result.numUpdatedRows)
      * ```
      */
     updateTable(table) {
@@ -167,7 +174,7 @@ export class QueryCreator {
      *  .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "mammals"."pet"
@@ -187,7 +194,7 @@ export class QueryCreator {
      *  .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "p"."name" from "mammals"."pet" as "p"
@@ -237,7 +244,7 @@ export class QueryCreator {
      * console.log(person.name)
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select concat(first_name, ' ', last_name) as "name"
@@ -295,7 +302,7 @@ export class QueryCreator {
      * }
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person" where now() - birth_date > interval $1 year
@@ -309,7 +316,8 @@ export class QueryCreator {
      * Example of creating a completely raw query from scratch:
      *
      * ```ts
-     * const persons = await db.raw<Person>('select p.* from person p').execute()
+     * const result = await db.raw<Person>('select p.* from person p').execute()
+     * const persons = result.rows
      * ```
      *
      * For a raw query, you need to specify the type of the returned __row__. In