kysely 0.11.1 → 0.12.0

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

@@ -4,10 +4,11 @@
  * If the table has an auto incrementing primary key {@link insertId} will hold
  * the generated id on dialects that support it. For example PostgreSQL doesn't
  * return the id by default and {@link insertId} is undefined. On PostgreSQL you
- * need to use {@link QueryBuilder.returning} or {@link QueryBuilder.returningAll}
+ * need to use {@link ReturningInterface.returning} or {@link ReturningInterface.returningAll}
  * to get out the inserted id.
  *
- * @example
+ * ### Examples
+ *
  * ```ts
  * const result = await db
  *   .insertInto('person')

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

@@ -1,68 +1,70 @@
 import { JoinNode } from '../operation-node/join-node.js';
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
-import { ExistsExpression, FilterOperator } from '../parser/filter-parser.js';
+import { ExistsExpression, FilterOperator, FilterValueExpressionOrList } from '../parser/filter-parser.js';
 import { ParseContext } from '../parser/parse-context.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
-import { ValueExpressionOrList } from '../parser/value-parser.js';
+import { AnyRawBuilder } from '../util/type-utils.js';
 export declare class JoinBuilder<DB, TB extends keyof DB> implements OperationNodeSource {
     #private;
     constructor(props: JoinBuilderProps);
     /**
-     * Just like {@link QueryBuilder.where} but adds an item to the join's
+     * Just like {@link WhereInterface.where} but adds an item to the join's
      * `on` clause instead.
      *
-     * See {@link QueryBuilder.where} for documentation and examples.
+     * See {@link WhereInterface.where} for documentation and examples.
      */
-    on<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: FilterOperator, rhs: ValueExpressionOrList<DB, TB, RE>): JoinBuilder<DB, TB>;
+    on<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: FilterOperator, rhs: FilterValueExpressionOrList<DB, TB, RE>): JoinBuilder<DB, TB>;
     on(grouper: (qb: JoinBuilder<DB, TB>) => JoinBuilder<DB, TB>): JoinBuilder<DB, TB>;
+    on(raw: AnyRawBuilder): JoinBuilder<DB, TB>;
     /**
-     * Just like {@link QueryBuilder.orWhere} but adds an item to the join's
+     * Just like {@link WhereInterface.orWhere} but adds an item to the join's
      * `on` clause instead.
      *
-     * See {@link QueryBuilder.orWhere} for documentation and examples.
+     * See {@link WhereInterface.orWhere} for documentation and examples.
      */
-    orOn<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: FilterOperator, rhs: ValueExpressionOrList<DB, TB, RE>): JoinBuilder<DB, TB>;
+    orOn<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: FilterOperator, rhs: FilterValueExpressionOrList<DB, TB, RE>): JoinBuilder<DB, TB>;
     orOn(grouper: (qb: JoinBuilder<DB, TB>) => JoinBuilder<DB, TB>): JoinBuilder<DB, TB>;
+    orOn(raw: AnyRawBuilder): JoinBuilder<DB, TB>;
     /**
-     * Just like {@link QueryBuilder.whereRef} but adds an item to the join's
+     * Just like {@link WhereInterface.whereRef} but adds an item to the join's
      * `on` clause instead.
      *
-     * See {@link QueryBuilder.whereRef} for documentation and examples.
+     * See {@link WhereInterface.whereRef} for documentation and examples.
      */
     onRef(lhs: ReferenceExpression<DB, TB>, op: FilterOperator, rhs: ReferenceExpression<DB, TB>): JoinBuilder<DB, TB>;
     /**
-     * Just like {@link QueryBuilder.orWhereRef} but adds an item to the join's
+     * Just like {@link WhereInterface.orWhereRef} but adds an item to the join's
      * `on` clause instead.
      *
-     * See {@link QueryBuilder.orWhereRef} for documentation and examples.
+     * See {@link WhereInterface.orWhereRef} for documentation and examples.
      */
     orOnRef(lhs: ReferenceExpression<DB, TB>, op: FilterOperator, rhs: ReferenceExpression<DB, TB>): JoinBuilder<DB, TB>;
     /**
-     * Just like {@link QueryBuilder.whereExists} but adds an item to the join's
+     * Just like {@link WhereInterface.whereExists} but adds an item to the join's
      * `on` clause instead.
      *
-     * See {@link QueryBuilder.whereExists} for documentation and examples.
+     * See {@link WhereInterface.whereExists} for documentation and examples.
      */
     onExists(arg: ExistsExpression<DB, TB>): JoinBuilder<DB, TB>;
     /**
-     * Just like {@link QueryBuilder.whereNotExists} but adds an item to the join's
+     * Just like {@link WhereInterface.whereNotExists} but adds an item to the join's
      * `on` clause instead.
      *
-     * See {@link QueryBuilder.whereNotExists} for documentation and examples.
+     * See {@link WhereInterface.whereNotExists} for documentation and examples.
      */
     onNotExists(arg: ExistsExpression<DB, TB>): JoinBuilder<DB, TB>;
     /**
-     * Just like {@link QueryBuilder.orWhereExists} but adds an item to the join's
+     * Just like {@link WhereInterface.orWhereExists} but adds an item to the join's
      * `on` clause instead.
      *
-     * See {@link QueryBuilder.orWhereExists} for documentation and examples.
+     * See {@link WhereInterface.orWhereExists} for documentation and examples.
      */
     orOnExists(arg: ExistsExpression<DB, TB>): JoinBuilder<DB, TB>;
     /**
-     * Just like {@link QueryBuilder.orWhereNotExists} but adds an item to the join's
+     * Just like {@link WhereInterface.orWhereNotExists} but adds an item to the join's
      * `on` clause instead.
      *
-     * See {@link QueryBuilder.orWhereNotExists} for documentation and examples.
+     * See {@link WhereInterface.orWhereNotExists} for documentation and examples.
      */
     orOnNotExists(arg: ExistsExpression<DB, TB>): JoinBuilder<DB, TB>;
     toOperationNode(): JoinNode;

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

@@ -20,10 +20,10 @@ export class JoinBuilder {
         });
     }
     /**
-     * Just like {@link QueryBuilder.whereRef} but adds an item to the join's
+     * Just like {@link WhereInterface.whereRef} but adds an item to the join's
      * `on` clause instead.
      *
-     * See {@link QueryBuilder.whereRef} for documentation and examples.
+     * See {@link WhereInterface.whereRef} for documentation and examples.
      */
     onRef(lhs, op, rhs) {
         return new JoinBuilder({
@@ -32,10 +32,10 @@ export class JoinBuilder {
         });
     }
     /**
-     * Just like {@link QueryBuilder.orWhereRef} but adds an item to the join's
+     * Just like {@link WhereInterface.orWhereRef} but adds an item to the join's
      * `on` clause instead.
      *
-     * See {@link QueryBuilder.orWhereRef} for documentation and examples.
+     * See {@link WhereInterface.orWhereRef} for documentation and examples.
      */
     orOnRef(lhs, op, rhs) {
         return new JoinBuilder({
@@ -44,10 +44,10 @@ export class JoinBuilder {
         });
     }
     /**
-     * Just like {@link QueryBuilder.whereExists} but adds an item to the join's
+     * Just like {@link WhereInterface.whereExists} but adds an item to the join's
      * `on` clause instead.
      *
-     * See {@link QueryBuilder.whereExists} for documentation and examples.
+     * See {@link WhereInterface.whereExists} for documentation and examples.
      */
     onExists(arg) {
         return new JoinBuilder({
@@ -56,10 +56,10 @@ export class JoinBuilder {
         });
     }
     /**
-     * Just like {@link QueryBuilder.whereNotExists} but adds an item to the join's
+     * Just like {@link WhereInterface.whereNotExists} but adds an item to the join's
      * `on` clause instead.
      *
-     * See {@link QueryBuilder.whereNotExists} for documentation and examples.
+     * See {@link WhereInterface.whereNotExists} for documentation and examples.
      */
     onNotExists(arg) {
         return new JoinBuilder({
@@ -68,10 +68,10 @@ export class JoinBuilder {
         });
     }
     /**
-     * Just like {@link QueryBuilder.orWhereExists} but adds an item to the join's
+     * Just like {@link WhereInterface.orWhereExists} but adds an item to the join's
      * `on` clause instead.
      *
-     * See {@link QueryBuilder.orWhereExists} for documentation and examples.
+     * See {@link WhereInterface.orWhereExists} for documentation and examples.
      */
     orOnExists(arg) {
         return new JoinBuilder({
@@ -80,10 +80,10 @@ export class JoinBuilder {
         });
     }
     /**
-     * Just like {@link QueryBuilder.orWhereNotExists} but adds an item to the join's
+     * Just like {@link WhereInterface.orWhereNotExists} but adds an item to the join's
      * `on` clause instead.
      *
-     * See {@link QueryBuilder.orWhereNotExists} for documentation and examples.
+     * See {@link WhereInterface.orWhereNotExists} for documentation and examples.
      */
     orOnNotExists(arg) {
         return new JoinBuilder({

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

@@ -0,0 +1,133 @@
+import { JoinCallbackExpression, JoinReferenceExpression } from '../parser/join-parser.js';
+import { FullJoinTableExpressionDatabase, LeftJoinTableExpressionDatabase, RightJoinTableExpressionDatabase, TableExpression, TableExpressionDatabase, TableExpressionTables } from '../parser/table-parser.js';
+export interface JoinInterface<DB, TB extends keyof DB> {
+    /**
+     * Joins another table to the query using an inner join.
+     *
+     * ### Examples
+     *
+     * Simple usage by providing a table name and two columns to join:
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .innerJoin('pet', 'pet.owner_id', 'person.id')
+     *   // `select` needs to come after the call to `innerJoin` so
+     *   // that you can select from the joined table.
+     *   .select('person.id', 'pet.name')
+     *   .execute()
+     *
+     * result[0].id
+     * result[0].name
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."id", "pet"."name"
+     * from "person"
+     * inner join "pet"
+     * on "pet"."owner_id" = "person"."id"
+     * ```
+     *
+     * You can give an alias for the joined table like this:
+     *
+     * ```ts
+     * await db.selectFrom('person')
+     *   .innerJoin('pet as p', 'p.owner_id', 'person.id')
+     *   .where('p.name', '=', 'Doggo')
+     *   .selectAll()
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select *
+     * from "person"
+     * inner join "pet" as "p"
+     * on "p"."owner_id" = "person"."id"
+     * where "p".name" = $1
+     * ```
+     *
+     * You can provide a function as the second argument to get a join
+     * builder for creating more complex joins. The join builder has a
+     * bunch of `on*` methods for building the `on` clause of the join.
+     * There's basically an equivalent for every `where` method
+     * (`on`, `onRef`, `onExists` etc.). You can do all the same things
+     * with the `on` method that you can with the corresponding `where`
+     * method. See the `where` method documentation for more examples.
+     *
+     * ```ts
+     * await db.selectFrom('person')
+     *   .innerJoin(
+     *     'pet',
+     *     (join) => join
+     *       .onRef('pet.owner_id', '=', 'person.id')
+     *       .on('pet.name', '=', 'Doggo')
+     *   )
+     *   .selectAll()
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select *
+     * from "person"
+     * inner join "pet"
+     * on "pet"."owner_id" = "person"."id"
+     * and "pet"."name" = $1
+     * ```
+     *
+     * You can join a subquery by providing a function as the first
+     * argument:
+     *
+     * ```ts
+     * await db.selectFrom('person')
+     *   .innerJoin(
+     *     (qb) => qb.selectFrom('pet')
+     *       .select(['owner_id', 'name'])
+     *       .where('name', '=', 'Doggo')
+     *       .as('doggos'),
+     *     'doggos.owner_id',
+     *     'person.id',
+     *   )
+     *   .selectAll()
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select *
+     * from "person"
+     * inner join (
+     *   select "owner_id", "name"
+     *   from "pet"
+     *   where "name" = $1
+     * ) as "doggos"
+     * on "doggos"."owner_id" = "person"."id"
+     * ```
+     */
+    innerJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): JoinInterface<TableExpressionDatabase<DB, TE>, TableExpressionTables<DB, TB, TE>>;
+    innerJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): JoinInterface<TableExpressionDatabase<DB, TE>, TableExpressionTables<DB, TB, TE>>;
+    /**
+     * Just like {@link JoinInterface.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): JoinInterface<LeftJoinTableExpressionDatabase<DB, TE>, TableExpressionTables<DB, TB, TE>>;
+    leftJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): JoinInterface<LeftJoinTableExpressionDatabase<DB, TE>, TableExpressionTables<DB, TB, TE>>;
+    /**
+     * Just like {@link JoinInterface.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): JoinInterface<RightJoinTableExpressionDatabase<DB, TB, TE>, TableExpressionTables<DB, TB, TE>>;
+    rightJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): JoinInterface<RightJoinTableExpressionDatabase<DB, TB, TE>, TableExpressionTables<DB, TB, TE>>;
+    /**
+     * Just like {@link JoinInterface.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): JoinInterface<FullJoinTableExpressionDatabase<DB, TB, TE>, TableExpressionTables<DB, TB, TE>>;
+    fullJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): JoinInterface<FullJoinTableExpressionDatabase<DB, TB, TE>, TableExpressionTables<DB, TB, TE>>;
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/esm/query-builder/no-result-error.d.ts

@@ -0,0 +1,9 @@
+import { QueryNode } from '../operation-node/query-node.js';
+export declare type NoResultErrorConstructor = new (node: QueryNode) => Error;
+export declare class NoResultError extends Error {
+    /**
+     * The operation node tree of the query that was executed.
+     */
+    readonly node: QueryNode;
+    constructor(node: QueryNode);
+}

package/dist/esm/query-builder/no-result-error.js

@@ -0,0 +1,10 @@
+export class NoResultError extends Error {
+    /**
+     * The operation node tree of the query that was executed.
+     */
+    node;
+    constructor(node) {
+        super('no result');
+        this.node = node;
+    }
+}

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

@@ -0,0 +1,73 @@
+import { ReturningRow } from '../parser/returning-parser.js';
+import { SelectExpression } from '../parser/select-parser.js';
+export interface ReturningInterface<DB, TB extends keyof DB, O> {
+    /**
+     * Allows you to return data from modified rows.
+     *
+     * On supported databases like PostgreSQL, this method can be chained to
+     * `insert`, `update` and `delete` queries to return data.
+     *
+     * Note that on SQLite you need to give aliases for the expressions to avoid
+     * [this bug](https://sqlite.org/forum/forumpost/033daf0b32) in SQLite.
+     * For example `.returning('id as id')`.
+     *
+     * Also see the {@link ReturningInterface.returningAll | returningAll} method.
+     *
+     * ### Examples
+     *
+     * Return one column:
+     *
+     * ```ts
+     * const { id } = await db
+     *   .insertInto('person')
+     *   .values({
+     *     id: db.generated,
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .returning('id')
+     *   .executeTakeFirst()
+     * ```
+     *
+     * Return multiple columns:
+     *
+     * ```ts
+     * const { id, first_name } = await db
+     *   .insertInto('person')
+     *   .values({
+     *     id: db.generated,
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .returning(['id', 'last_name'])
+     *   .executeTakeFirst()
+     * ```
+     *
+     * Return arbitrary expressions:
+     *
+     * ```ts
+     * const { raw } = db
+     *
+     * const { id, full_name, first_pet_id } = await db
+     *   .insertInto('person')
+     *   .values({
+     *     id: db.generated,
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .returning([
+     *     'id as id',
+     *     raw<string>(`concat(first_name, ' ', last_name)`).as('full_name'),
+     *     (qb) => qb.selectFrom('pets').select('pet.id').limit(1).as('first_pet_id')
+     *   ])
+     *   .executeTakeFirst()
+     * ```
+     */
+    returning<SE extends SelectExpression<DB, TB>>(selections: ReadonlyArray<SE>): ReturningInterface<DB, TB, ReturningRow<DB, TB, O, SE>>;
+    returning<SE extends SelectExpression<DB, TB>>(selection: SE): ReturningInterface<DB, TB, ReturningRow<DB, TB, O, SE>>;
+    /**
+     * Adds a `returning *` to an insert/update/delete query on databases
+     * that support `returning` such as PostgreSQL.
+     */
+    returningAll(): ReturningInterface<DB, TB, DB[TB]>;
+}

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

@@ -0,0 +1 @@
+export {};