kysely 0.21.6 → 0.23.0

package/dist/cjs/query-builder/aggregate-function-builder.d.ts

@@ -0,0 +1,348 @@
+import { AggregateFunctionNode } from '../operation-node/aggregate-function-node.js';
+import { AliasNode } from '../operation-node/alias-node.js';
+import { OverBuilder } from './over-builder.js';
+import { AliasedExpression, Expression } from '../expression/expression.js';
+import { ReferenceExpression } from '../parser/reference-parser.js';
+import { ComparisonOperatorExpression, OperandValueExpressionOrList, WhereGrouper } from '../parser/binary-operation-parser.js';
+import { ExistsExpression } from '../parser/unary-operation-parser.js';
+export declare class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unknown> implements Expression<O> {
+    #private;
+    constructor(props: AggregateFunctionBuilderProps);
+    /** @private */
+    /**
+     * All expressions need to have this getter for complicated type-related reasons.
+     * Simply add this getter for your expression and always return `undefined` from it:
+     *
+     * ```ts
+     * class SomeExpression<T> implements Expression<T> {
+     *   get expressionType(): T | undefined {
+     *     return undefined
+     *   }
+     * }
+     * ```
+     *
+     * The getter is needed to make the expression assignable to another expression only
+     * if the types `T` are assignable. Without this property (or some other property
+     * that references `T`), you could assing `Expression<string>` to `Expression<number>`.
+     */
+    get expressionType(): O | undefined;
+    /**
+     * Returns an aliased version of the function.
+     *
+     * In addition to slapping `as "the_alias"` to the end of the SQL,
+     * this method also provides strict typing:
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select(
+     *     eb => eb.fn.count<number>('id').as('person_count')
+     *   )
+     *   .executeTakeFirstOrThrow()
+     *
+     * // `person_count: number` field exists in the result type.
+     * console.log(result.person_count)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select count("id") as "person_count"
+     * from "person"
+     * ```
+     */
+    as<A extends string>(alias: A): AliasedAggregateFunctionBuilder<DB, TB, O, A>;
+    /**
+     * 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')
+     *   )
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select count(distinct "first_name") as "first_name_count"
+     * from "person"
+     * ```
+     */
+    distinct(): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * 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, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): AggregateFunctionBuilder<DB, TB, O>;
+    filterWhere(grouper: WhereGrouper<DB, TB>): AggregateFunctionBuilder<DB, TB, O>;
+    filterWhere(expression: Expression<any>): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * 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>): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * Just like {@link filterWhereExists} but creates a `not exists` clause inside
+     * the `filter` clause.
+     */
+    filterWhereNotExists(arg: ExistsExpression<DB, TB>): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * 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>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * 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, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): AggregateFunctionBuilder<DB, TB, O>;
+    orFilterWhere(grouper: WhereGrouper<DB, TB>): AggregateFunctionBuilder<DB, TB, O>;
+    orFilterWhere(expression: Expression<any>): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * 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>): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * 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>): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * 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>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * Adds an `over` clause (window functions) after the function.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select(
+     *     eb => eb.fn.avg<number>('age').over().as('average_age')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select avg("age") over() as "average_age"
+     * from "person"
+     * ```
+     *
+     * Also supports passing a callback that returns an over builder,
+     * allowing to add partition by and sort by clauses inside over.
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select(
+     *     eb => eb.fn.avg<number>('age').over(
+     *       ob => ob.partitionBy('last_name').orderBy('first_name', 'asc')
+     *     ).as('average_age')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select avg("age") over(partition by "last_name" order by "first_name" asc) as "average_age"
+     * from "person"
+     * ```
+     */
+    over(over?: OverBuilderCallback<DB, TB>): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * Creates the OperationNode that describes how to compile this expression into SQL.
+     *
+     * If you are creating a custom expression, it's often easiest to use the {@link sql}
+     * template tag to build the node:
+     *
+     * ```ts
+     * class SomeExpression<T> implements Expression<T> {
+     *   toOperationNode(): OperationNode {
+     *     return sql`some sql here`.toOperationNode()
+     *   }
+     * }
+     * ```
+     */
+    toOperationNode(): AggregateFunctionNode;
+}
+/**
+ * {@link AggregateFunctionBuilder} with an alias. The result of calling {@link AggregateFunctionBuilder.as}.
+ */
+export declare class AliasedAggregateFunctionBuilder<DB, TB extends keyof DB, O = unknown, A extends string = never> implements AliasedExpression<O, A> {
+    #private;
+    constructor(aggregateFunctionBuilder: AggregateFunctionBuilder<DB, TB, O>, alias: A);
+    /** @private */
+    /**
+     * Returns the aliased expression.
+     */
+    get expression(): Expression<O>;
+    /** @private */
+    /**
+     * Returns the alias.
+     */
+    get alias(): A;
+    /**
+     * Creates the OperationNode that describes how to compile this expression into SQL.
+     */
+    toOperationNode(): AliasNode;
+}
+export interface AggregateFunctionBuilderProps {
+    aggregateFunctionNode: AggregateFunctionNode;
+}
+export declare type OverBuilderCallback<DB, TB extends keyof DB> = (builder: OverBuilder<DB, TB>) => OverBuilder<DB, TB>;

package/dist/cjs/query-builder/aggregate-function-builder.js

@@ -0,0 +1,298 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AliasedAggregateFunctionBuilder = exports.AggregateFunctionBuilder = void 0;
+const object_utils_js_1 = require("../util/object-utils.js");
+const aggregate_function_node_js_1 = require("../operation-node/aggregate-function-node.js");
+const alias_node_js_1 = require("../operation-node/alias-node.js");
+const identifier_node_js_1 = require("../operation-node/identifier-node.js");
+const prevent_await_js_1 = require("../util/prevent-await.js");
+const parse_utils_js_1 = require("../parser/parse-utils.js");
+const binary_operation_parser_js_1 = require("../parser/binary-operation-parser.js");
+const unary_operation_parser_js_1 = require("../parser/unary-operation-parser.js");
+class AggregateFunctionBuilder {
+    #props;
+    constructor(props) {
+        this.#props = (0, object_utils_js_1.freeze)(props);
+    }
+    /** @private */
+    get expressionType() {
+        return undefined;
+    }
+    /**
+     * Returns an aliased version of the function.
+     *
+     * In addition to slapping `as "the_alias"` to the end of the SQL,
+     * this method also provides strict typing:
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select(
+     *     eb => eb.fn.count<number>('id').as('person_count')
+     *   )
+     *   .executeTakeFirstOrThrow()
+     *
+     * // `person_count: number` field exists in the result type.
+     * console.log(result.person_count)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select count("id") as "person_count"
+     * from "person"
+     * ```
+     */
+    as(alias) {
+        return new AliasedAggregateFunctionBuilder(this, alias);
+    }
+    /**
+     * 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')
+     *   )
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select count(distinct "first_name") as "first_name_count"
+     * from "person"
+     * ```
+     */
+    distinct() {
+        return new AggregateFunctionBuilder({
+            ...this.#props,
+            aggregateFunctionNode: aggregate_function_node_js_1.AggregateFunctionNode.cloneWithDistinct(this.#props.aggregateFunctionNode),
+        });
+    }
+    filterWhere(...args) {
+        return new AggregateFunctionBuilder({
+            ...this.#props,
+            aggregateFunctionNode: aggregate_function_node_js_1.AggregateFunctionNode.cloneWithFilter(this.#props.aggregateFunctionNode, (0, binary_operation_parser_js_1.parseWhere)(args)),
+        });
+    }
+    /**
+     * 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) {
+        return new AggregateFunctionBuilder({
+            ...this.#props,
+            aggregateFunctionNode: aggregate_function_node_js_1.AggregateFunctionNode.cloneWithFilter(this.#props.aggregateFunctionNode, (0, unary_operation_parser_js_1.parseExists)(arg)),
+        });
+    }
+    /**
+     * Just like {@link filterWhereExists} but creates a `not exists` clause inside
+     * the `filter` clause.
+     */
+    filterWhereNotExists(arg) {
+        return new AggregateFunctionBuilder({
+            ...this.#props,
+            aggregateFunctionNode: aggregate_function_node_js_1.AggregateFunctionNode.cloneWithFilter(this.#props.aggregateFunctionNode, (0, unary_operation_parser_js_1.parseNotExists)(arg)),
+        });
+    }
+    /**
+     * 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, op, rhs) {
+        return new AggregateFunctionBuilder({
+            ...this.#props,
+            aggregateFunctionNode: aggregate_function_node_js_1.AggregateFunctionNode.cloneWithFilter(this.#props.aggregateFunctionNode, (0, binary_operation_parser_js_1.parseReferentialFilter)(lhs, op, rhs)),
+        });
+    }
+    orFilterWhere(...args) {
+        return new AggregateFunctionBuilder({
+            ...this.#props,
+            aggregateFunctionNode: aggregate_function_node_js_1.AggregateFunctionNode.cloneWithOrFilter(this.#props.aggregateFunctionNode, (0, binary_operation_parser_js_1.parseWhere)(args)),
+        });
+    }
+    /**
+     * Just like {@link filterWhereExists} but creates an `or exists` clause inside
+     * the `filter` clause.
+     *
+     * Similar to {@link WhereInterface}'s `orWhereExists` method.
+     */
+    orFilterWhereExists(arg) {
+        return new AggregateFunctionBuilder({
+            ...this.#props,
+            aggregateFunctionNode: aggregate_function_node_js_1.AggregateFunctionNode.cloneWithOrFilter(this.#props.aggregateFunctionNode, (0, unary_operation_parser_js_1.parseExists)(arg)),
+        });
+    }
+    /**
+     * Just like {@link filterWhereExists} but creates an `or not exists` clause inside
+     * the `filter` clause.
+     *
+     * Similar to {@link WhereInterface}'s `orWhereNotExists` method.
+     */
+    orFilterWhereNotExists(arg) {
+        return new AggregateFunctionBuilder({
+            ...this.#props,
+            aggregateFunctionNode: aggregate_function_node_js_1.AggregateFunctionNode.cloneWithOrFilter(this.#props.aggregateFunctionNode, (0, unary_operation_parser_js_1.parseNotExists)(arg)),
+        });
+    }
+    /**
+     * 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, op, rhs) {
+        return new AggregateFunctionBuilder({
+            ...this.#props,
+            aggregateFunctionNode: aggregate_function_node_js_1.AggregateFunctionNode.cloneWithOrFilter(this.#props.aggregateFunctionNode, (0, binary_operation_parser_js_1.parseReferentialFilter)(lhs, op, rhs)),
+        });
+    }
+    /**
+     * Adds an `over` clause (window functions) after the function.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select(
+     *     eb => eb.fn.avg<number>('age').over().as('average_age')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select avg("age") over() as "average_age"
+     * from "person"
+     * ```
+     *
+     * Also supports passing a callback that returns an over builder,
+     * allowing to add partition by and sort by clauses inside over.
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select(
+     *     eb => eb.fn.avg<number>('age').over(
+     *       ob => ob.partitionBy('last_name').orderBy('first_name', 'asc')
+     *     ).as('average_age')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select avg("age") over(partition by "last_name" order by "first_name" asc) as "average_age"
+     * from "person"
+     * ```
+     */
+    over(over) {
+        const builder = (0, parse_utils_js_1.createOverBuilder)();
+        return new AggregateFunctionBuilder({
+            ...this.#props,
+            aggregateFunctionNode: aggregate_function_node_js_1.AggregateFunctionNode.cloneWithOver(this.#props.aggregateFunctionNode, (over ? over(builder) : builder).toOperationNode()),
+        });
+    }
+    toOperationNode() {
+        return this.#props.aggregateFunctionNode;
+    }
+}
+exports.AggregateFunctionBuilder = AggregateFunctionBuilder;
+(0, prevent_await_js_1.preventAwait)(AggregateFunctionBuilder, "don't await AggregateFunctionBuilder instances. They are never executed directly and are always just a part of a query.");
+/**
+ * {@link AggregateFunctionBuilder} with an alias. The result of calling {@link AggregateFunctionBuilder.as}.
+ */
+class AliasedAggregateFunctionBuilder {
+    #aggregateFunctionBuilder;
+    #alias;
+    constructor(aggregateFunctionBuilder, alias) {
+        this.#aggregateFunctionBuilder = aggregateFunctionBuilder;
+        this.#alias = alias;
+    }
+    /** @private */
+    get expression() {
+        return this.#aggregateFunctionBuilder;
+    }
+    /** @private */
+    get alias() {
+        return this.#alias;
+    }
+    toOperationNode() {
+        return alias_node_js_1.AliasNode.create(this.#aggregateFunctionBuilder.toOperationNode(), identifier_node_js_1.IdentifierNode.create(this.#alias));
+    }
+}
+exports.AliasedAggregateFunctionBuilder = AliasedAggregateFunctionBuilder;