kysely 0.24.2 → 0.26.0

package/dist/esm/query-builder/function-module.d.ts

@@ -1,8 +1,8 @@
 import { DynamicReferenceBuilder } from '../dynamic/dynamic-reference-builder.js';
 import { ExpressionWrapper } from '../expression/expression-wrapper.js';
 import { CoalesceReferenceExpressionList } from '../parser/coalesce-parser.js';
-import { ExtractTypeFromReferenceExpression, SimpleReferenceExpression, ReferenceExpression, StringReference } from '../parser/reference-parser.js';
-import { Equals, IsNever } from '../util/type-utils.js';
+import { ExtractTypeFromReferenceExpression, ReferenceExpression, StringReference } from '../parser/reference-parser.js';
+import { Equals, IsAny } from '../util/type-utils.js';
 import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
 /**
  * Helpers for type safe SQL function calls.
@@ -12,24 +12,36 @@ import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
  *
  * ### Examples
  *
- * ```ts
- * const { count } = db.fn
+ * <!-- siteExample("select", "Function calls", 60) -->
+ *
+ * This example uses the `fn` module to select some aggregates:
  *
- * await db.selectFrom('person')
+ * ```ts
+ * const result = await db.selectFrom('person')
  *   .innerJoin('pet', 'pet.owner_id', 'person.id')
- *   .select([
+ *   .select(({ fn }) => [
  *     'person.id',
- *     count('pet.id').as('pet_count')
+ *
+ *     // The `fn` module contains the most common
+ *     // functions.
+ *     fn.count<number>('pet.id').as('pet_count'),
+ *
+ *     // You can call any function using the
+ *     // `agg` method
+ *     fn.agg<string[]>('array_agg', ['pet.name']).as('pet_names')
  *   ])
  *   .groupBy('person.id')
- *   .having(count('pet.id'), '>', 10)
+ *   .having((eb) => eb.fn.count('pet.id'), '>', 10)
  *   .execute()
  * ```
  *
  * The generated SQL (PostgreSQL):
  *
  * ```sql
- * select "person"."id", count("pet"."id") as "pet_count"
+ * select
+ *   "person"."id",
+ *   count("pet"."id") as "pet_count",
+ *   array_agg("pet"."name") as "pet_names"
  * from "person"
  * inner join "pet" on "pet"."owner_id" = "person"."id"
  * group by "person"."id"
@@ -40,6 +52,8 @@ export interface FunctionModule<DB, TB extends keyof DB> {
     /**
      * Creates a function call.
      *
+     * To create an aggregate function call, use {@link FunctionModule.agg}.
+     *
      * ### Examples
      *
      * ```ts
@@ -64,7 +78,36 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      *   .where(sql`upper(first_name)`, '=', 'JENNIFER')
      * ```
      */
-    <T>(name: string, args: ReadonlyArray<ReferenceExpression<DB, TB>>): ExpressionWrapper<T>;
+    <T>(name: string, args: ReadonlyArray<ReferenceExpression<DB, TB>>): ExpressionWrapper<DB, TB, T>;
+    /**
+     * Creates an aggregate function call.
+     *
+     * This is a specialized version of the `fn` method, that returns an {@link AggregateFunctionBuilder}
+     * instance. A builder that allows you to chain additional methods such as `distinct`,
+     * `filterWhere` and `over`.
+     *
+     * See {@link avg}, {@link count}, {@link countAll}, {@link max}, {@link min}, {@link sum}
+     * shortcuts of common aggregate functions.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(({ fn }) => [
+     *     fn.agg<number>('rank').over().as('rank'),
+     *     fn.agg<string>('group_concat', ['first_name']).distinct().as('first_names')
+     *   ])
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * select rank() over() as "rank",
+     *   group_concat(distinct "first_name") as "first_names"
+     * from "person"
+     * ```
+     */
+    agg<O>(name: string, args?: ReadonlyArray<ReferenceExpression<DB, TB>>): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Calls the `avg` function for the column given as the argument.
      *
@@ -77,10 +120,8 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * const { avg } = db.fn
-     *
      * db.selectFrom('toy')
-     *   .select(avg('price').as('avg_price'))
+     *   .select((eb) => eb.fn.avg('price').as('avg_price'))
      *   .execute()
      * ```
      *
@@ -109,10 +150,8 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * the first type argument:
      *
      * ```ts
-     * const { avg } = db.fn
-     *
      * db.selectFrom('toy')
-     *   .select(avg<number>('price').as('avg_price'))
+     *   .select((eb) => eb.fn.avg<number>('price').as('avg_price'))
      *   .execute()
      * ```
      *
@@ -122,14 +161,12 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * function.
      *
      * ```ts
-     * const { avg } = db.fn
-     *
      * db.selectFrom('toy')
-     *   .select(avg<number | null>('price').as('avg_price'))
+     *   .select((eb) => eb.fn.avg<number | null>('price').as('avg_price'))
      *   .execute()
      * ```
      */
-    avg<O extends number | string | null = number | string, C extends SimpleReferenceExpression<DB, TB> = SimpleReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
+    avg<O extends number | string | null = number | string, C extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Calls the `coalesce` function for given arguments.
      *
@@ -151,10 +188,8 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * const { coalesce } = db.fn
-     *
      * db.selectFrom('participant')
-     *   .select(coalesce('nickname', sql<string>`'<anonymous>'`).as('nickname'))
+     *   .select((eb) => eb.fn.coalesce('nickname', sql<string>`'<anonymous>'`).as('nickname'))
      *   .where('room_id', '=', roomId)
      *   .execute()
      * ```
@@ -180,10 +215,8 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * You can combine this function with other helpers in this module:
      *
      * ```ts
-     * const { avg, coalesce } = db.fn
-     *
      * db.selectFrom('person')
-     *   .select(coalesce(avg<number | null>('age'), sql<number>`0`).as('avg_age'))
+     *   .select((eb) => eb.fn.coalesce(eb.fn.avg<number | null>('age'), sql<number>`0`).as('avg_age'))
      *   .where('first_name', '=', 'Jennifer')
      *   .execute()
      * ```
@@ -194,7 +227,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * select coalesce(avg("age"), 0) as "avg_age" from "person" where "first_name" = $1
      * ```
      */
-    coalesce<V extends ReferenceExpression<DB, TB>, OV extends ReferenceExpression<DB, TB>[]>(value: V, ...otherValues: OV): ExpressionWrapper<CoalesceReferenceExpressionList<DB, TB, [V, ...OV]>>;
+    coalesce<V extends ReferenceExpression<DB, TB>, OV extends ReferenceExpression<DB, TB>[]>(value: V, ...otherValues: OV): ExpressionWrapper<DB, TB, CoalesceReferenceExpressionList<DB, TB, [V, ...OV]>>;
     /**
      * Calls the `count` function for the column given as the argument.
      *
@@ -210,10 +243,8 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * const { count } = db.fn
-     *
      * db.selectFrom('toy')
-     *   .select(count('id').as('num_toys'))
+     *   .select((eb) => eb.fn.count('id').as('num_toys'))
      *   .execute()
      * ```
      *
@@ -234,10 +265,8 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * the type as the first type argument:
      *
      * ```ts
-     * const { count } = db.fn
-     *
      * db.selectFrom('toy')
-     *   .select(count<number>('id').as('num_toys'))
+     *   .select((eb) => eb.fn.count<number>('id').as('num_toys'))
      *   .execute()
      * ```
      *
@@ -249,7 +278,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      *   .execute()
      * ```
      */
-    count<O extends number | string | bigint, C extends SimpleReferenceExpression<DB, TB> = SimpleReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
+    count<O extends number | string | bigint, C extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Calls the `count` function with `*` or `table.*` as argument.
      *
@@ -266,10 +295,8 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * const { countAll } = db.fn
-     *
      * db.selectFrom('toy')
-     *   .select(countAll().as('num_toys'))
+     *   .select((eb) => eb.fn.countAll().as('num_toys'))
      *   .execute()
      * ```
      *
@@ -290,10 +317,8 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * the type as the first type argument:
      *
      * ```ts
-     * const { countAll } = db.fn
-     *
      * db.selectFrom('toy')
-     *   .select(countAll<number>().as('num_toys'))
+     *   .select((eb) => eb.fn.countAll<number>().as('num_toys'))
      *   .execute()
      * ```
      *
@@ -301,11 +326,9 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * table:
      *
      * ```ts
-     * const { countAll } = db.fn
-     *
      * db.selectFrom('toy')
      *   .innerJoin('pet', 'pet.id', 'toy.pet_id')
-     *   .select(countAll('toy').as('num_toys'))
+     *   .select((eb) => eb.fn.countAll('toy').as('num_toys'))
      *   .execute()
      * ```
      *
@@ -343,10 +366,8 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * const { max } = db.fn
-     *
      * db.selectFrom('toy')
-     *   .select(max('price').as('max_price'))
+     *   .select((eb) => eb.fn.max('price').as('max_price'))
      *   .execute()
      * ```
      *
@@ -370,14 +391,12 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * function.
      *
      * ```ts
-     * const { max } = db.fn
-     *
      * db.selectFrom('toy')
-     *   .select(max<number | null, 'price'>('price').as('max_price'))
+     *   .select((eb) => eb.fn.max<number | null, 'price'>('price').as('max_price'))
      *   .execute()
      * ```
      */
-    max<O extends number | string | bigint | null = never, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: OutputBoundStringReference<DB, TB, C, O>): StringReferenceBoundAggregateFunctionBuilder<DB, TB, C, O>;
+    max<O extends number | string | bigint | null = any, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: OutputBoundStringReference<DB, TB, C, O>): StringReferenceBoundAggregateFunctionBuilder<DB, TB, C, O>;
     max<O extends number | string | bigint | null = number | string | bigint>(column: DynamicReferenceBuilder): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Calls the `min` function for the column given as the argument.
@@ -395,10 +414,8 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * const { min } = db.fn
-     *
      * db.selectFrom('toy')
-     *   .select(min('price').as('min_price'))
+     *   .select((eb) => eb.fn.min('price').as('min_price'))
      *   .execute()
      * ```
      *
@@ -422,14 +439,12 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * function.
      *
      * ```ts
-     * const { min } = db.fn
-     *
      * db.selectFrom('toy')
-     *   .select(min<number | null, 'price'>('price').as('min_price'))
+     *   .select((eb) => eb.fn.min<number | null, 'price'>('price').as('min_price'))
      *   .execute()
      * ```
      */
-    min<O extends number | string | bigint | null = never, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: OutputBoundStringReference<DB, TB, C, O>): StringReferenceBoundAggregateFunctionBuilder<DB, TB, C, O>;
+    min<O extends number | string | bigint | null = any, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: OutputBoundStringReference<DB, TB, C, O>): StringReferenceBoundAggregateFunctionBuilder<DB, TB, C, O>;
     min<O extends number | string | bigint | null = number | string | bigint>(column: DynamicReferenceBuilder): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Calls the `sum` function for the column given as the argument.
@@ -443,10 +458,8 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * const { sum } = db.fn
-     *
      * db.selectFrom('toy')
-     *   .select(sum('price').as('total_price'))
+     *   .select((eb) => eb.fn.sum('price').as('total_price'))
      *   .execute()
      * ```
      *
@@ -475,10 +488,8 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * the first type argument:
      *
      * ```ts
-     * const { sum } = db.fn
-     *
      * db.selectFrom('toy')
-     *   .select(sum<number>('price').as('total_price'))
+     *   .select((eb) => eb.fn.sum<number>('price').as('total_price'))
      *   .execute()
      * ```
      *
@@ -488,16 +499,14 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * function.
      *
      * ```ts
-     * const { sum } = db.fn
-     *
      * db.selectFrom('toy')
-     *   .select(sum<number | null>('price').as('total_price'))
+     *   .select((eb) => eb.fn.sum<number | null>('price').as('total_price'))
      *   .execute()
      * ```
      */
-    sum<O extends number | string | bigint | null = number | string | bigint, C extends SimpleReferenceExpression<DB, TB> = SimpleReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
+    sum<O extends number | string | bigint | null = number | string | bigint, C extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
 }
 export declare function createFunctionModule<DB, TB extends keyof DB>(): FunctionModule<DB, TB>;
-declare type OutputBoundStringReference<DB, TB extends keyof DB, C extends StringReference<DB, TB>, O> = IsNever<O> extends true ? C : Equals<ExtractTypeFromReferenceExpression<DB, TB, C> | null, O | null> extends true ? C : never;
-declare type StringReferenceBoundAggregateFunctionBuilder<DB, TB extends keyof DB, C extends StringReference<DB, TB>, O> = AggregateFunctionBuilder<DB, TB, ExtractTypeFromReferenceExpression<DB, TB, C> | (null extends O ? null : never)>;
+type OutputBoundStringReference<DB, TB extends keyof DB, C extends StringReference<DB, TB>, O> = IsAny<O> extends true ? C : Equals<ExtractTypeFromReferenceExpression<DB, TB, C> | null, O | null> extends true ? C : never;
+type StringReferenceBoundAggregateFunctionBuilder<DB, TB extends keyof DB, C extends StringReference<DB, TB>, O> = AggregateFunctionBuilder<DB, TB, ExtractTypeFromReferenceExpression<DB, TB, C> | (IsAny<O> extends true ? never : null extends O ? null : never)>;
 export {};

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

@@ -2,46 +2,42 @@
 import { ExpressionWrapper } from '../expression/expression-wrapper.js';
 import { AggregateFunctionNode } from '../operation-node/aggregate-function-node.js';
 import { FunctionNode } from '../operation-node/function-node.js';
-import { parseSimpleReferenceExpression, parseReferenceExpressionOrList, } from '../parser/reference-parser.js';
+import { parseReferenceExpressionOrList, } from '../parser/reference-parser.js';
 import { parseSelectAll } from '../parser/select-parser.js';
 import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
 export function createFunctionModule() {
     const fn = (name, args) => {
         return new ExpressionWrapper(FunctionNode.create(name, parseReferenceExpressionOrList(args)));
     };
+    const agg = (name, args) => {
+        return new AggregateFunctionBuilder({
+            aggregateFunctionNode: AggregateFunctionNode.create(name, args ? parseReferenceExpressionOrList(args) : undefined),
+        });
+    };
     return Object.assign(fn, {
+        agg,
         avg(column) {
-            return new AggregateFunctionBuilder({
-                aggregateFunctionNode: AggregateFunctionNode.create('avg', parseSimpleReferenceExpression(column)),
-            });
+            return agg('avg', [column]);
         },
         coalesce(value, ...otherValues) {
             return fn('coalesce', [value, ...otherValues]);
         },
         count(column) {
-            return new AggregateFunctionBuilder({
-                aggregateFunctionNode: AggregateFunctionNode.create('count', parseSimpleReferenceExpression(column)),
-            });
+            return agg('count', [column]);
         },
         countAll(table) {
             return new AggregateFunctionBuilder({
-                aggregateFunctionNode: AggregateFunctionNode.create('count', parseSelectAll(table)[0]),
+                aggregateFunctionNode: AggregateFunctionNode.create('count', parseSelectAll(table)),
             });
         },
         max(column) {
-            return new AggregateFunctionBuilder({
-                aggregateFunctionNode: AggregateFunctionNode.create('max', parseSimpleReferenceExpression(column)),
-            });
+            return agg('max', [column]);
         },
         min(column) {
-            return new AggregateFunctionBuilder({
-                aggregateFunctionNode: AggregateFunctionNode.create('min', parseSimpleReferenceExpression(column)),
-            });
+            return agg('min', [column]);
         },
         sum(column) {
-            return new AggregateFunctionBuilder({
-                aggregateFunctionNode: AggregateFunctionNode.create('sum', parseSimpleReferenceExpression(column)),
-            });
+            return agg('sum', [column]);
         },
     });
 }

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

@@ -1,9 +1,8 @@
+import { ExpressionBuilder } from '../expression/expression-builder.js';
 import { Expression } from '../expression/expression.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
@@ -17,37 +16,5 @@ export interface HavingInterface<DB, TB extends keyof DB> {
      * instead of a `where` statement.
      */
     havingRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): HavingInterface<DB, TB>;
-    /**
-     * @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>;
-    /**
-     * @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>;
-    /**
-     * @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>;
-    /**
-     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
-     */
-    havingExists(arg: ExistsExpression<DB, TB>): HavingInterface<DB, TB>;
-    /**
-     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
-     */
-    havingNotExists(arg: ExistsExpression<DB, TB>): HavingInterface<DB, TB>;
-    /**
-     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
-     */
-    orHavingExists(arg: ExistsExpression<DB, TB>): HavingInterface<DB, TB>;
-    /**
-     * @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>;
+export type HavingExpressionFactory<DB, TB extends keyof DB> = (eb: ExpressionBuilder<DB, TB>) => Expression<SqlBool>;