kysely 0.23.4 → 0.24.0

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

@@ -1,211 +1,47 @@
 /// <reference types="./function-module.d.ts" />
+import { ExpressionWrapper } from '../expression/expression-wrapper.js';
 import { AggregateFunctionNode } from '../operation-node/aggregate-function-node.js';
-import { parseCoalesce, } from '../parser/coalesce-parser.js';
-import { parseSimpleReferenceExpression, } from '../parser/reference-parser.js';
-import { RawBuilder } from '../raw-builder/raw-builder.js';
-import { createQueryId } from '../util/query-id.js';
+import { FunctionNode } from '../operation-node/function-node.js';
+import { parseSimpleReferenceExpression, parseReferenceExpressionOrList, } from '../parser/reference-parser.js';
+import { parseSelectAll } from '../parser/select-parser.js';
 import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
-/**
- * Helpers for type safe SQL function calls.
- *
- * You can always use the {@link sql} tag to call functions and build arbitrary
- * expressions. This module simply has shortcuts for most common function calls.
- *
- * ### Examples
- *
- * ```ts
- * const { count } = db.fn
- *
- * await db.selectFrom('person')
- *   .innerJoin('pet', 'pet.owner_id', 'person.id')
- *   .select([
- *     'person.id',
- *     count('pet.id').as('pet_count')
- *   ])
- *   .groupBy('person.id')
- *   .having(count('pet.id'), '>', 10)
- *   .execute()
- * ```
- *
- * The generated SQL (PostgreSQL):
- *
- * ```sql
- * select "person"."id", count("pet"."id") as "pet_count"
- * from "person"
- * inner join "pet" on "pet"."owner_id" = "person"."id"
- * group by "person"."id"
- * having count("pet"."id") > $1
- * ```
- */
-export class FunctionModule {
-    constructor() {
-        this.avg = this.avg.bind(this);
-        this.coalesce = this.coalesce.bind(this);
-        this.count = this.count.bind(this);
-        this.max = this.max.bind(this);
-        this.min = this.min.bind(this);
-        this.sum = this.sum.bind(this);
-    }
-    /**
-     * Calls the `avg` function for the column given as the argument.
-     *
-     * If this is used in a `select` statement the type of the selected expression
-     * will be `number | string` by default. This is because Kysely can't know the
-     * type the db driver outputs. Sometimes the output can be larger than the largest
-     * javascript number and a string is returned instead. Most drivers allow you
-     * to configure the output type of large numbers and Kysely can't know if you've
-     * done so.
-     *
-     * You can specify the output type of the expression by providing the type as
-     * the first type argument:
-     *
-     * ```ts
-     * const { avg } = db.fn
-     *
-     * db.selectFrom('toy')
-     *   .select(avg<number>('price').as('avg_price'))
-     *   .execute()
-     * ```
-     *
-     * Sometimes a null is returned, e.g. when row count is 0, and no `group by`
-     * was used. It is highly recommended to include null in the output type union
-     * and handle null values in post-execute code, or wrap the function with a `coalesce`
-     * function.
-     *
-     * ```ts
-     * const { avg } = db.fn
-     *
-     * db.selectFrom('toy')
-     *   .select(avg<number | null>('price').as('avg_price'))
-     *   .execute()
-     * ```
-     */
-    avg(column) {
-        return new AggregateFunctionBuilder({
-            aggregateFunctionNode: AggregateFunctionNode.create('avg', parseSimpleReferenceExpression(column)),
-        });
-    }
-    /**
-     * Calls the `coalesce` function for given arguments.
-     *
-     * This function returns the first non-null value from left to right, commonly
-     * used to provide a default scalar for nullable columns or functions.
-     *
-     * ```ts
-     * const { coalesce, max } = db.fn
-     *
-     * db.selectFrom('person')
-     *   .select(coalesce(max('age'), sql<number>`0`).as('max_age'))
-     *   .where('first_name', '=', 'Jennifer')
-     *   .execute()
-     * ```
-     *
-     * The generated SQL (postgres):
-     *
-     * ```sql
-     * select coalesce(max("age"), 0) as "max_age" from "person" where "first_name" = $1
-     * ```
-     *
-     * If this is used in a `select` statement the type of the selected expression
-     * is inferred in the same manner that the function computes. A union of arguments'
-     * types - if a non-nullable argument exists, it stops there (ignoring any further
-     * arguments' types) and exludes null from the final union type.
-     *
-     * Examples:
-     *
-     * `(string | null, number | null)` is inferred as `string | number | null`.
-     *
-     * `(string | null, number, Date | null)` is inferred as `string | number`.
-     *
-     * `(number, string | null)` is inferred as `number`.
-     */
-    coalesce(value, ...otherValues) {
-        return new RawBuilder({
-            queryId: createQueryId(),
-            rawNode: parseCoalesce([value, ...otherValues]),
-        });
-    }
-    /**
-     * Calls the `count` function for the column given as the argument.
-     *
-     * If this is used in a `select` statement the type of the selected expression
-     * will be `number | string | bigint` by default. This is because Kysely
-     * can't know the type the db driver outputs. Sometimes the output can be larger
-     * than the largest javascript number and a string is returned instead. Most
-     * drivers allow you to configure the output type of large numbers and Kysely
-     * can't know if you've done so.
-     *
-     * You can specify the output type of the expression by providing
-     * the type as the first type argument:
-     *
-     * ```ts
-     * const { count } = db.fn
-     *
-     * db.selectFrom('toy')
-     *   .select(count<number>('id').as('num_toys'))
-     *   .execute()
-     * ```
-     *
-     * You can limit column range:
-     *
-     * ```ts
-     * db.selectFrom('toy')
-     *   .select(qb => qb.fn.count<number>('id').as('num_toys'))
-     *   .execute()
-     * ```
-     */
-    count(column) {
-        return new AggregateFunctionBuilder({
-            aggregateFunctionNode: AggregateFunctionNode.create('count', parseSimpleReferenceExpression(column)),
-        });
-    }
-    max(column) {
-        return new AggregateFunctionBuilder({
-            aggregateFunctionNode: AggregateFunctionNode.create('max', parseSimpleReferenceExpression(column)),
-        });
-    }
-    min(column) {
-        return new AggregateFunctionBuilder({
-            aggregateFunctionNode: AggregateFunctionNode.create('min', parseSimpleReferenceExpression(column)),
-        });
-    }
-    /**
-     * Calls the `sum` function for the column given as the argument.
-     *
-     * If this is used in a `select` statement the type of the selected expression
-     * will be `number | string | bigint` by default. This is because Kysely
-     * can't know the type the db driver outputs. Sometimes the output can be larger
-     * than the largest javascript number and a string is returned instead. Most
-     * drivers allow you to configure the output type of large numbers and Kysely
-     * can't know if you've done so.
-     *
-     * You can specify the output type of the expression by providing
-     * the type as the first type argument:
-     *
-     * ```ts
-     * const { sum } = db.fn
-     *
-     * db.selectFrom('toy')
-     *   .select(sum<number>('price').as('total_price'))
-     *   .execute()
-     * ```
-     *
-     * Sometimes a null is returned, e.g. when row count is 0, and no `group by`
-     * was used. It is highly recommended to include null in the output type union
-     * and handle null values in post-execute code, or wrap the function with a `coalesce`
-     * function.
-     *
-     * ```ts
-     * const { sum } = db.fn
-     *
-     * db.selectFrom('toy')
-     *   .select(sum<number | null>('price').as('total_price'))
-     *   .execute()
-     * ```
-     */
-    sum(column) {
-        return new AggregateFunctionBuilder({
-            aggregateFunctionNode: AggregateFunctionNode.create('sum', parseSimpleReferenceExpression(column)),
-        });
-    }
+export function createFunctionModule() {
+    const fn = (name, args) => {
+        return new ExpressionWrapper(FunctionNode.create(name, parseReferenceExpressionOrList(args)));
+    };
+    return Object.assign(fn, {
+        avg(column) {
+            return new AggregateFunctionBuilder({
+                aggregateFunctionNode: AggregateFunctionNode.create('avg', parseSimpleReferenceExpression(column)),
+            });
+        },
+        coalesce(value, ...otherValues) {
+            return fn('coalesce', [value, ...otherValues]);
+        },
+        count(column) {
+            return new AggregateFunctionBuilder({
+                aggregateFunctionNode: AggregateFunctionNode.create('count', parseSimpleReferenceExpression(column)),
+            });
+        },
+        countAll(table) {
+            return new AggregateFunctionBuilder({
+                aggregateFunctionNode: AggregateFunctionNode.create('count', parseSelectAll(table)[0]),
+            });
+        },
+        max(column) {
+            return new AggregateFunctionBuilder({
+                aggregateFunctionNode: AggregateFunctionNode.create('max', parseSimpleReferenceExpression(column)),
+            });
+        },
+        min(column) {
+            return new AggregateFunctionBuilder({
+                aggregateFunctionNode: AggregateFunctionNode.create('min', parseSimpleReferenceExpression(column)),
+            });
+        },
+        sum(column) {
+            return new AggregateFunctionBuilder({
+                aggregateFunctionNode: AggregateFunctionNode.create('sum', parseSimpleReferenceExpression(column)),
+            });
+        },
+    });
 }

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

@@ -1,14 +1,16 @@
 import { Expression } from '../expression/expression.js';
-import { ComparisonOperatorExpression, HavingGrouper, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
+import { ComparisonOperatorExpression, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
 import { ExistsExpression } from '../parser/unary-operation-parser.js';
+import { SqlBool } from '../util/type-utils.js';
+import { HavingExpressionBuilder } from './deprecated-having-expression-builder.js';
 export interface HavingInterface<DB, TB extends keyof DB> {
     /**
      * Just like {@link WhereInterface.where | where} but adds a `having` statement
      * instead of a `where` statement.
      */
     having<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): HavingInterface<DB, TB>;
-    having(grouper: HavingGrouper<DB, TB>): HavingInterface<DB, TB>;
+    having(factory: HavingExpressionFactory<DB, TB>): HavingInterface<DB, TB>;
     having(expression: Expression<any>): HavingInterface<DB, TB>;
     /**
      * Just like {@link WhereInterface.whereRef | whereRef} but adds a `having` statement
@@ -16,35 +18,36 @@ export interface HavingInterface<DB, TB extends keyof DB> {
      */
     havingRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): HavingInterface<DB, TB>;
     /**
-     * Just like {@link WhereInterface.orWhere | orWhere} but adds a `having` statement
-     * instead of a `where` statement.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     orHaving<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): HavingInterface<DB, TB>;
-    orHaving(grouper: HavingGrouper<DB, TB>): HavingInterface<DB, TB>;
+    /**
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
+     */
+    orHaving(factory: HavingExpressionFactory<DB, TB>): HavingInterface<DB, TB>;
+    /**
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
+     */
     orHaving(expression: Expression<any>): HavingInterface<DB, TB>;
     /**
-     * Just like {@link WhereInterface.orWhereRef | orWhereRef} but adds a `having` statement
-     * instead of a `where` statement.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     orHavingRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): HavingInterface<DB, TB>;
     /**
-     * Just like {@link WhereInterface.whereExists | whereExists} but adds a `having` statement
-     * instead of a `where` statement.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     havingExists(arg: ExistsExpression<DB, TB>): HavingInterface<DB, TB>;
     /**
-     * Just like {@link WhereInterface.whereNotExists | whereNotExists} but adds a `having` statement
-     * instead of a `where` statement.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
-    havingNotExist(arg: ExistsExpression<DB, TB>): HavingInterface<DB, TB>;
+    havingNotExists(arg: ExistsExpression<DB, TB>): HavingInterface<DB, TB>;
     /**
-     * Just like {@link WhereInterface.orWhereExists | orWhereExists} but adds a `having` statement
-     * instead of a `where` statement.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     orHavingExists(arg: ExistsExpression<DB, TB>): HavingInterface<DB, TB>;
     /**
-     * Just like {@link WhereInterface.orWhereNotExists | orWhereNotExists} but adds a `having` statement
-     * instead of a `where` statement.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     orHavingNotExists(arg: ExistsExpression<DB, TB>): HavingInterface<DB, TB>;
 }
+export declare type HavingExpressionFactory<DB, TB extends keyof DB> = (eb: HavingExpressionBuilder<DB, TB>) => Expression<SqlBool> | HavingExpressionBuilder<DB, TB>;

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

@@ -1,10 +1,11 @@
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
-import { SelectExpression } from '../parser/select-parser.js';
-import { InsertObject } from '../parser/insert-values-parser.js';
+import { SelectExpression, SelectArg } from '../parser/select-parser.js';
+import { InsertObjectOrList, InsertObjectOrListFactory } from '../parser/insert-values-parser.js';
 import { InsertQueryNode } from '../operation-node/insert-query-node.js';
-import { MergePartial, SingleResultType } from '../util/type-utils.js';
-import { UpdateObject } from '../parser/update-set-parser.js';
+import { QueryNode } from '../operation-node/query-node.js';
+import { MergePartial, SimplifyResult, SimplifySingleResult } from '../util/type-utils.js';
+import { UpdateExpression } from '../parser/update-set-parser.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
@@ -19,7 +20,8 @@ import { Selectable } from '../util/column-type.js';
 import { Explainable, ExplainFormat } from '../util/explainable.js';
 import { Expression } from '../expression/expression.js';
 import { KyselyTypeError } from '../util/type-error.js';
-export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable<O>, Explainable {
+import { Streamable } from '../util/streamable.js';
+export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable<O>, Explainable, Streamable<O> {
     #private;
     constructor(props: InsertQueryBuilderProps);
     /**
@@ -116,11 +118,12 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *
      * const result = await db
      *   .insertInto('person')
-     *   .values({
+     *   .values((eb) => ({
      *     first_name: 'Jennifer',
      *     last_name: sql`${'Ani'} || ${'ston'}`,
-     *     age: db.selectFrom('person').select(sql`avg(age)`),
-     *   })
+     *     middle_name: eb.ref('first_name'),
+     *     age: eb.selectFrom('person').select(sql`avg(age)`),
+     *   }))
      *   .executeTakeFirst()
      *
      * console.log(result.insertId)
@@ -141,15 +144,15 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   .where('first_name', '=', 'Jennifer')
      *   .select(['id', 'first_name', 'gender'])
      *   .limit(1)
-     * ).insertInto('pet').values({
-     *   owner_id: (eb) => eb.selectFrom('jennifer').select('id'),
-     *   name: (eb) => eb.selectFrom('jennifer').select('first_name'),
+     * ).insertInto('pet').values((eb) => ({
+     *   owner_id: eb.selectFrom('jennifer').select('id'),
+     *   name: eb.selectFrom('jennifer').select('first_name'),
      *   species: 'cat',
-     * })
+     * }))
      * ```
      */
-    values(row: InsertObject<DB, TB>): InsertQueryBuilder<DB, TB, O>;
-    values(row: ReadonlyArray<InsertObject<DB, TB>>): InsertQueryBuilder<DB, TB, O>;
+    values(insert: InsertObjectOrList<DB, TB>): InsertQueryBuilder<DB, TB, O>;
+    values(insert: InsertObjectOrListFactory<DB, TB>): InsertQueryBuilder<DB, TB, O>;
     /**
      * Sets the columns to insert.
      *
@@ -259,7 +262,6 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *     .doUpdateSet({ species: 'hamster' })
      *   )
      *   .execute()
-     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -385,7 +387,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   .onDuplicateKeyUpdate({ species: 'hamster' })
      * ```
      */
-    onDuplicateKeyUpdate(updates: UpdateObject<DB, TB, TB>): InsertQueryBuilder<DB, TB, O>;
+    onDuplicateKeyUpdate(update: UpdateExpression<DB, TB, TB>): InsertQueryBuilder<DB, TB, O>;
     /**
      * Allows you to return data from modified rows.
      *
@@ -437,23 +439,23 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   })
-     *   .returning([
+     *   .returning(eb => [
      *     'id as id',
      *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name'),
-     *     (qb) => qb.selectFrom('pets').select('pet.id').limit(1).as('first_pet_id')
+     *     eb.selectFrom('pets').select('pet.id').limit(1).as('first_pet_id')
      *   ])
      *   .executeTakeFirst()
      * ```
      */
-    returning<SE extends SelectExpression<DB, TB>>(selections: ReadonlyArray<SE>): InsertQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SE>>;
-    returning<SE extends SelectExpression<DB, TB>>(selection: SE): InsertQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SE>>;
+    returning<SE extends SelectExpression<DB, TB>>(selection: SelectArg<DB, TB, SE>): InsertQueryBuilder<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(): InsertQueryBuilder<DB, TB, Selectable<DB[TB]>>;
     /**
-     * Simply calls the given function passing `this` as the only argument.
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
      *
      * If you want to conditionally call a method on `this`, see
      * the {@link $if} method.
@@ -562,7 +564,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   )
      *   .with('new_pet', (qb) => qb
      *     .insertInto('pet')
-     *     .values({ owner_id: (eb) => eb.selectFrom('new_person').select('id'), ...pet })
+     *     .values((eb) => ({ owner_id: eb.selectFrom('new_person').select('id'), ...pet }))
      *     .returning(['name as pet_name', 'species'])
      *     .$assertType<{ pet_name: string, species: Species }>()
      *   )
@@ -587,35 +589,81 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *
      * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
      */
-    execute(): Promise<O[]>;
+    execute(): Promise<SimplifyResult<O>[]>;
     /**
      * Executes the query and returns the first result or undefined if
      * the query returned no result.
      */
-    executeTakeFirst(): Promise<SingleResultType<O>>;
+    executeTakeFirst(): Promise<SimplifySingleResult<O>>;
     /**
      * Executes the query and returns the first result or throws if
      * the query returned no result.
      *
      * By default an instance of {@link NoResultError} is thrown, but you can
-     * provide a custom error class as the only argument to throw a different
+     * provide a custom error class, or callback as the only argument to throw a different
      * error.
      */
-    executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<O>;
+    executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor | ((node: QueryNode) => Error)): Promise<SimplifyResult<O>>;
+    /**
+     * Executes the query and streams the rows.
+     *
+     * The optional argument `chunkSize` defines how many rows to fetch from the database
+     * at a time. It only affects some dialects like PostgreSQL that support it.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const stream = db.
+     *   .selectFrom('person')
+     *   .select(['first_name', 'last_name'])
+     *   .where('gender', '=', 'other')
+     *   .stream()
+     *
+     * for await (const person of stream) {
+     *   console.log(person.first_name)
+     *
+     *   if (person.last_name === 'Something') {
+     *     // Breaking or returning before the stream has ended will release
+     *     // the database connection and invalidate the stream.
+     *     break
+     *   }
+     * }
+     * ```
+     */
+    stream(chunkSize?: number): AsyncIterableIterator<O>;
     /**
-     * Executes query with `explain` statement before `insert` keyword.
+     * Executes query with `explain` statement before the main query.
      *
      * ```ts
      * const explained = await db
-     *  .insertInto('person')
-     *  .values(values)
+     *  .selectFrom('person')
+     *  .where('gender', '=', 'female')
+     *  .selectAll()
      *  .explain('json')
      * ```
      *
      * The generated SQL (MySQL):
      *
      * ```sql
-     * explain format=json insert into `person` (`id`, `first_name`, `last_name`) values (?, ?, ?) (?, ?, ?)
+     * explain format=json select * from `person` where `gender` = ?
+     * ```
+     *
+     * You can also execute `explain analyze` statements.
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const explained = await db
+     *  .selectFrom('person')
+     *  .where('gender', '=', 'female')
+     *  .selectAll()
+     *  .explain('json', sql`analyze`)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * explain (analyze, format json) select * from "person" where "gender" = $1
      * ```
      */
     explain<ER extends Record<string, any> = Record<string, any>>(format?: ExplainFormat, options?: Expression<any>): Promise<ER[]>;