add ts docs to filterWhere methods @ AggregateFunctionBuilder.

src/query-builder/aggregate-function-builder.ts

@@ -66,13 +66,15 @@ export class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unknown>
   }
 
   /**
-   * Adds a distinct clause inside the function.
+   * Adds a `distinct` clause inside the function.
+   *
+   * ### Examples
    *
    * ```ts
    * const result = await db
    *   .selectFrom('person')
-   *   .select(
-   *     eb => eb.fn.count<number>('first_name').distinct().as('first_name_count')
+   *   .select((eb) =>
+   *     eb.fn.count<number>('first_name').distinct().as('first_name_count')
    *   )
    *   .executeTakeFirstOrThrow()
    * ```
@@ -94,7 +96,48 @@ export class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unknown>
   }
 
   /**
-   * // TODO: ...
+   * Adds a `filter` clause with a nested `where` clause after the function.
+   *
+   * Similar to {@link WhereInterface}'s `where` method.
+   *
+   * Also see {@link orFilterWhere}, {@link filterWhereExists} and {@link filterWhereRef}.
+   *
+   * ### Examples
+   *
+   * Count by gender:
+   *
+   * ```ts
+   * const result = await db
+   *   .selectFrom('person')
+   *   .select([
+   *     (eb) =>
+   *       eb.fn
+   *         .count<number>('id')
+   *         .filterWhere('gender', '=', 'female')
+   *         .as('female_count'),
+   *     (eb) =>
+   *       eb.fn
+   *         .count<number>('id')
+   *         .filterWhere('gender', '=', 'male')
+   *         .as('male_count'),
+   *     (eb) =>
+   *       eb.fn
+   *         .count<number>('id')
+   *         .filterWhere('gender', '=', 'other')
+   *         .as('other_count'),
+   *   ])
+   *   .executeTakeFirstOrThrow()
+   * ```
+   *
+   * The generated SQL (PostgreSQL):
+   *
+   * ```sql
+   * select
+   *   count("id") filter(where "gender" = $1) as "female_count",
+   *   count("id") filter(where "gender" = $2) as "male_count",
+   *   count("id") filter(where "gender" = $3) as "other_count"
+   * from "person"
+   * ```
    */
   filterWhere<RE extends ReferenceExpression<DB, TB>>(
     lhs: RE,
@@ -119,7 +162,44 @@ export class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unknown>
   }
 
   /**
-   * TODO: ...
+   * Adds a `filter` clause with a nested `where exists` clause after the function.
+   *
+   * Similar to {@link WhereInterface}'s `whereExists` method.
+   *
+   * ### Examples
+   *
+   * Count pet owners versus general public:
+   *
+   * ```ts
+   * const result = await db
+   *   .selectFrom('person')
+   *   .select([
+   *     (eb) =>
+   *       eb.fn
+   *         .count<number>('person.id')
+   *         .filterWhereExists((qb) =>
+   *           qb
+   *             .selectFrom('pet')
+   *             .select('pet.id')
+   *             .whereRef('pet.owner_id', '=', 'person.id')
+   *         )
+   *         .as('pet_owner_count'),
+   *     (eb) => eb.fn.count<number>('person.id').as('total_count'),
+   *   ])
+   *   .executeTakeFirstOrThrow()
+   * ```
+   *
+   * The generated SQL (PostgreSQL):
+   *
+   * ```sql
+   * select count("person"."id") filter(where exists (
+   *   select "pet"."id"
+   *   from "pet"
+   *   where "pet"."owner_id" = "person"."id"
+   * )) as "pet_ower_count",
+   *   count("person"."id") as "total_count"
+   * from "person"
+   * ```
    */
   filterWhereExists(
     arg: ExistsExpression<DB, TB>
@@ -134,7 +214,8 @@ export class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unknown>
   }
 
   /**
-   * TODO: ...
+   * Just like {@link filterWhereExists} but creates a `not exists` clause inside
+   * the `filter` clause.
    */
   filterWhereNotExists(
     arg: ExistsExpression<DB, TB>
@@ -149,7 +230,37 @@ export class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unknown>
   }
 
   /**
-   * TODO: ...
+   * Adds a `filter` clause with a nested `where` clause after the function, where
+   * both sides of the operator are references to columns.
+   *
+   * Similar to {@link WhereInterface}'s `whereRef` method.
+   *
+   * ### Examples
+   *
+   * Count people with same first and last names versus general public:
+   *
+   * ```ts
+   * const result = await db
+   *   .selectFrom('person')
+   *   .select([
+   *     (eb) =>
+   *       eb.fn
+   *         .count<number>('id')
+   *         .filterWhereRef('first_name', '=', 'last_name')
+   *         .as('repeat_name_count'),
+   *     (eb) => eb.fn.count<number>('id').as('total_count'),
+   *   ])
+   *   .executeTakeFirstOrThrow()
+   * ```
+   *
+   * The generated SQL (PostgreSQL):
+   *
+   * ```sql
+   * select
+   *   count("id") filter(where "first_name" = "last_name") as "repeat_name_count",
+   *   count("id") as "total_count"
+   * from "person"
+   * ```
    */
   filterWhereRef(
     lhs: ReferenceExpression<DB, TB>,
@@ -166,7 +277,39 @@ export class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unknown>
   }
 
   /**
-   * TODO: ...
+   * Adds a `filter` clause with a nested `or where` clause after the function.
+   * Otherwise works just like {@link filterWhere}.
+   *
+   * Similar to {@link WhereInterface}'s `orWhere` method.
+   *
+   * ### Examples
+   *
+   * For some reason you're tasked with counting adults (18+) or people called
+   * "Bob" versus general public:
+   *
+   * ```ts
+   * const result = await db
+   *   .selectFrom('person')
+   *   .select([
+   *     (eb) =>
+   *       eb.fn
+   *         .count<number>('id')
+   *         .filterWhere('age', '>=', '18')
+   *         .orFilterWhere('first_name', '=', 'Bob')
+   *         .as('adult_or_bob_count'),
+   *     (eb) => eb.fn.count<number>('id').as('total_count'),
+   *   ])
+   *   .executeTakeFirstOrThrow()
+   * ```
+   *
+   * The generated SQL (PostgreSQL):
+   *
+   * ```sql
+   * select
+   *   count("id") filter(where "age" >= $1 or "first_name" = $2) as "adult_or_bob_count",
+   *   count("id") as "total_count"
+   * from "person"
+   * ```
    */
   orFilterWhere<RE extends ReferenceExpression<DB, TB>>(
     lhs: RE,
@@ -193,7 +336,10 @@ export class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unknown>
   }
 
   /**
-   * TODO: ...
+   * Just like {@link filterWhereExists} but creates an `or exists` clause inside
+   * the `filter` clause.
+   *
+   * Similar to {@link WhereInterface}'s `orWhereExists` method.
    */
   orFilterWhereExists(
     arg: ExistsExpression<DB, TB>
@@ -208,7 +354,10 @@ export class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unknown>
   }
 
   /**
-   * TODO: ...
+   * Just like {@link filterWhereExists} but creates an `or not exists` clause inside
+   * the `filter` clause.
+   *
+   * Similar to {@link WhereInterface}'s `orWhereNotExists` method.
    */
   orFilterWhereNotExists(
     arg: ExistsExpression<DB, TB>
@@ -223,7 +372,12 @@ export class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unknown>
   }
 
   /**
-   * TODO: ...
+   * Adds an `or where` clause inside the `filter` clause. Otherwise works just
+   * like {@link filterWhereRef}.
+   *
+   * Also see {@link orFilterWhere} and {@link filterWhere}.
+   *
+   * Similar to {@link WhereInterface}'s `orWhereRef` method.
    */
   orFilterWhereRef(
     lhs: ReferenceExpression<DB, TB>,
@@ -240,7 +394,9 @@ export class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unknown>
   }
 
   /**
-   * Adds an over clause (window functions) after the function.
+   * Adds an `over` clause (window functions) after the function.
+   *
+   * ### Examples
    *
    * ```ts
    * const result = await db

src/query-builder/where-interface.ts

@@ -208,7 +208,7 @@ export interface WhereInterface<DB, TB extends keyof DB> {
    *
    * The normal `where` method treats the right hand side argument as a
    * value by default. `whereRef` treats it as a column reference. This method is
-   * expecially useful with joins and correclated subqueries.
+   * expecially useful with joins and correlated subqueries.
    *
    * ### Examples
    *
@@ -411,12 +411,12 @@ export interface WhereInterface<DB, TB extends keyof DB> {
   whereNotExists(arg: ExistsExpression<DB, TB>): WhereInterface<DB, TB>
 
   /**
-   * Just like {@link whereExists} but creates a `or exists` clause.
+   * Just like {@link whereExists} but creates an `or exists` clause.
    */
   orWhereExists(arg: ExistsExpression<DB, TB>): WhereInterface<DB, TB>
 
   /**
-   * Just like {@link whereExists} but creates a `or not exists` clause.
+   * Just like {@link whereExists} but creates an `or not exists` clause.
    */
   orWhereNotExists(arg: ExistsExpression<DB, TB>): WhereInterface<DB, TB>
 }