kysely 0.21.6 → 0.22.0

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

@@ -0,0 +1,142 @@
+/// <reference types="./aggregate-function-builder.d.ts" />
+import { freeze } from '../util/object-utils.js';
+import { AggregateFunctionNode } from '../operation-node/aggregate-function-node.js';
+import { AliasNode } from '../operation-node/alias-node.js';
+import { IdentifierNode } from '../operation-node/identifier-node.js';
+import { preventAwait } from '../util/prevent-await.js';
+import { createOverBuilder } from '../parser/parse-utils.js';
+export class AggregateFunctionBuilder {
+    #props;
+    constructor(props) {
+        this.#props = freeze(props);
+    }
+    /**
+     * 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.
+     *
+     * ```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: AggregateFunctionNode.cloneWithDistinct(this.#props.aggregateFunctionNode),
+        });
+    }
+    /**
+     * Adds an over clause (window functions) after the function.
+     *
+     * ```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 = createOverBuilder();
+        return new AggregateFunctionBuilder({
+            ...this.#props,
+            aggregateFunctionNode: AggregateFunctionNode.cloneWithOver(this.#props.aggregateFunctionNode, (over ? over(builder) : builder).toOperationNode()),
+        });
+    }
+    toOperationNode() {
+        return this.#props.aggregateFunctionNode;
+    }
+}
+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}.
+ */
+export class AliasedAggregateFunctionBuilder {
+    #aggregateFunctionBuilder;
+    #alias;
+    constructor(aggregateFunctionBuilder, alias) {
+        this.#aggregateFunctionBuilder = aggregateFunctionBuilder;
+        this.#alias = alias;
+    }
+    /**
+     * @private
+     *
+     * This needs to be here just so that the typings work. Without this
+     * the generated .d.ts file contains no reference to the type param A
+     * which causes this type to be equal to AliasedAggregateFunctionBuilder with any A
+     * as long as O is the same.
+     */
+    get alias() {
+        return this.#alias;
+    }
+    toOperationNode() {
+        return AliasNode.create(this.#aggregateFunctionBuilder.toOperationNode(), IdentifierNode.create(this.#alias));
+    }
+}

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

@@ -1,6 +1,6 @@
 import { SelectQueryBuilder } from './select-query-builder.js';
 import { TableExpression, From, FromTables } from '../parser/table-parser.js';
-import { FunctionBuilder } from './function-builder.js';
+import { FunctionModule } from './function-module.js';
 import { ExtractTypeFromReferenceExpression, StringReference } from '../parser/reference-parser.js';
 import { RawBuilder } from '../raw-builder/raw-builder.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
@@ -8,7 +8,7 @@ export declare class ExpressionBuilder<DB, TB extends keyof DB> {
     #private;
     constructor(props: ExpressionBuilderProps);
     /**
-     * Returns a {@link FunctionBuilder} that can be used to write type safe function
+     * Returns a {@link FunctionModule} that can be used to write type safe function
      * calls.
      *
      * The difference between this and {@link Kysely.fn} is that this one is more
@@ -38,7 +38,7 @@ export declare class ExpressionBuilder<DB, TB extends keyof DB> {
      * having count("pet"."id") > $1
      * ```
      */
-    get fn(): FunctionBuilder<DB, TB>;
+    get fn(): FunctionModule<DB, TB>;
     /**
      * Creates a subquery.
      *

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

@@ -4,7 +4,7 @@ import { SelectQueryNode } from '../operation-node/select-query-node.js';
 import { parseTableExpressionOrList, } from '../parser/table-parser.js';
 import { WithSchemaPlugin } from '../plugin/with-schema/with-schema-plugin.js';
 import { createQueryId } from '../util/query-id.js';
-import { FunctionBuilder } from './function-builder.js';
+import { FunctionModule } from './function-module.js';
 import { parseStringReference, } from '../parser/reference-parser.js';
 import { RawBuilder } from '../raw-builder/raw-builder.js';
 import { freeze } from '../util/object-utils.js';
@@ -15,7 +15,7 @@ export class ExpressionBuilder {
         this.#props = freeze(props);
     }
     /**
-     * Returns a {@link FunctionBuilder} that can be used to write type safe function
+     * Returns a {@link FunctionModule} that can be used to write type safe function
      * calls.
      *
      * The difference between this and {@link Kysely.fn} is that this one is more
@@ -46,7 +46,7 @@ export class ExpressionBuilder {
      * ```
      */
     get fn() {
-        return new FunctionBuilder();
+        return new FunctionModule();
     }
     selectFrom(table) {
         return new SelectQueryBuilder({

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

@@ -1,5 +1,5 @@
 import { StringReference, ExtractTypeFromReferenceExpression } from '../parser/reference-parser.js';
-import { RawBuilder } from '../raw-builder/raw-builder.js';
+import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
 /**
  * Helpers for type safe SQL function calls.
  *
@@ -32,38 +32,8 @@ import { RawBuilder } from '../raw-builder/raw-builder.js';
  * having count("pet"."id") > $1
  * ```
  */
-export declare class FunctionBuilder<DB, TB extends keyof DB> {
-    #private;
+export declare class FunctionModule<DB, TB extends keyof DB> {
     constructor();
-    /**
-     * Calls the `max` function for the column given as the argument.
-     *
-     * ### Examples
-     *
-     * ```ts
-     * const { max } = db.fn
-     *
-     * db.selectFrom('toy')
-     *   .select(max('price').as('max_price'))
-     *   .execute()
-     * ```
-     */
-    max<C extends StringReference<DB, TB>>(column: C): RawBuilder<ExtractTypeFromReferenceExpression<DB, TB, C>>;
-    /**
-     * Calls the `min` function for the column given as the argument.
-     *
-     * ### Examples
-     *
-     * ```ts
-     * const { min } = db.fn
-     *
-     * db.selectFrom('toy')
-     *   .select(min('price').as('min_price'))
-     *   .execute()
-     * ```
-     *
-     */
-    min<C extends StringReference<DB, TB>>(column: C): RawBuilder<ExtractTypeFromReferenceExpression<DB, TB, C>>;
     /**
      * Calls the `avg` function for the column given as the argument.
      *
@@ -85,9 +55,9 @@ export declare class FunctionBuilder<DB, TB extends keyof DB> {
      *   .execute()
      * ```
      */
-    avg<O extends number | string, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: C): RawBuilder<O>;
+    avg<O extends number | string, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
     /**
-     * Calls the `sum` function for the column given as the argument.
+     * 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
@@ -100,19 +70,56 @@ export declare class FunctionBuilder<DB, TB extends keyof DB> {
      * the type as the first type argument:
      *
      * ```ts
-     * const { sum } = db.fn
+     * const { count } = db.fn
      *
      * db.selectFrom('toy')
-     *   .select(sum<number>('price').as('total_price'))
+     *   .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()
      * ```
      */
-    sum<O extends number | string | bigint, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: C): RawBuilder<O>;
+    count<O extends number | string | bigint, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
     /**
-     * Calls the `count` function for the column given as the argument.
+     * Calls the `max` function for the column given as the argument.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const { max } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(max('price').as('max_price'))
+     *   .execute()
+     * ```
+     */
+    max<C extends StringReference<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, ExtractTypeFromReferenceExpression<DB, TB, C>>;
+    /**
+     * Calls the `min` function for the column given as the argument.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const { min } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(min('price').as('min_price'))
+     *   .execute()
+     * ```
+     *
+     */
+    min<C extends StringReference<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, ExtractTypeFromReferenceExpression<DB, TB, C>>;
+    /**
+     * 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
+     * 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
@@ -122,12 +129,12 @@ export declare class FunctionBuilder<DB, TB extends keyof DB> {
      * the type as the first type argument:
      *
      * ```ts
-     * const { count } = db.fn
+     * const { sum } = db.fn
      *
      * db.selectFrom('toy')
-     *   .select(count<number>('id').as('num_toys'))
+     *   .select(sum<number>('price').as('total_price'))
      *   .execute()
      * ```
      */
-    count<O extends number | string | bigint, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: C): RawBuilder<O>;
+    sum<O extends number | string | bigint, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
 }

package/dist/esm/query-builder/{function-builder.js → function-module.js}

@@ -1,8 +1,7 @@
-/// <reference types="./function-builder.d.ts" />
-import { RawNode } from '../operation-node/raw-node.js';
+/// <reference types="./function-module.d.ts" />
+import { AggregateFunctionNode } from '../operation-node/aggregate-function-node.js';
 import { parseStringReference, } from '../parser/reference-parser.js';
-import { RawBuilder } from '../raw-builder/raw-builder.js';
-import { createQueryId } from '../util/query-id.js';
+import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
 /**
  * Helpers for type safe SQL function calls.
  *
@@ -35,46 +34,13 @@ import { createQueryId } from '../util/query-id.js';
  * having count("pet"."id") > $1
  * ```
  */
-export class FunctionBuilder {
+export class FunctionModule {
     constructor() {
-        this.min = this.min.bind(this);
-        this.max = this.max.bind(this);
         this.avg = this.avg.bind(this);
-        this.sum = this.sum.bind(this);
         this.count = this.count.bind(this);
-    }
-    /**
-     * Calls the `max` function for the column given as the argument.
-     *
-     * ### Examples
-     *
-     * ```ts
-     * const { max } = db.fn
-     *
-     * db.selectFrom('toy')
-     *   .select(max('price').as('max_price'))
-     *   .execute()
-     * ```
-     */
-    max(column) {
-        return this.#oneArgFunction('max', column);
-    }
-    /**
-     * Calls the `min` function for the column given as the argument.
-     *
-     * ### Examples
-     *
-     * ```ts
-     * const { min } = db.fn
-     *
-     * db.selectFrom('toy')
-     *   .select(min('price').as('min_price'))
-     *   .execute()
-     * ```
-     *
-     */
-    min(column) {
-        return this.#oneArgFunction('min', column);
+        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.
@@ -98,10 +64,12 @@ export class FunctionBuilder {
      * ```
      */
     avg(column) {
-        return this.#oneArgFunction('avg', column);
+        return new AggregateFunctionBuilder({
+            aggregateFunctionNode: AggregateFunctionNode.create('avg', parseStringReference(column)),
+        });
     }
     /**
-     * Calls the `sum` function for the column given as the argument.
+     * 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
@@ -114,21 +82,68 @@ export class FunctionBuilder {
      * the type as the first type argument:
      *
      * ```ts
-     * const { sum } = db.fn
+     * const { count } = db.fn
      *
      * db.selectFrom('toy')
-     *   .select(sum<number>('price').as('total_price'))
+     *   .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()
      * ```
      */
-    sum(column) {
-        return this.#oneArgFunction('sum', column);
+    count(column) {
+        return new AggregateFunctionBuilder({
+            aggregateFunctionNode: AggregateFunctionNode.create('count', parseStringReference(column)),
+        });
     }
     /**
-     * Calls the `count` function for the column given as the argument.
+     * Calls the `max` function for the column given as the argument.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const { max } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(max('price').as('max_price'))
+     *   .execute()
+     * ```
+     */
+    max(column) {
+        return new AggregateFunctionBuilder({
+            aggregateFunctionNode: AggregateFunctionNode.create('max', parseStringReference(column)),
+        });
+    }
+    /**
+     * Calls the `min` function for the column given as the argument.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const { min } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(min('price').as('min_price'))
+     *   .execute()
+     * ```
+     *
+     */
+    min(column) {
+        return new AggregateFunctionBuilder({
+            aggregateFunctionNode: AggregateFunctionNode.create('min', parseStringReference(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
+     * 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
@@ -138,20 +153,16 @@ export class FunctionBuilder {
      * the type as the first type argument:
      *
      * ```ts
-     * const { count } = db.fn
+     * const { sum } = db.fn
      *
      * db.selectFrom('toy')
-     *   .select(count<number>('id').as('num_toys'))
+     *   .select(sum<number>('price').as('total_price'))
      *   .execute()
      * ```
      */
-    count(column) {
-        return this.#oneArgFunction('count', column);
-    }
-    #oneArgFunction(fn, column) {
-        return new RawBuilder({
-            queryId: createQueryId(),
-            rawNode: RawNode.create([`${fn}(`, ')'], [parseStringReference(column)]),
+    sum(column) {
+        return new AggregateFunctionBuilder({
+            aggregateFunctionNode: AggregateFunctionNode.create('sum', parseStringReference(column)),
         });
     }
 }

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

@@ -0,0 +1,59 @@
+import { DynamicReferenceBuilder } from '../dynamic/dynamic-reference-builder.js';
+import { OperationNodeSource } from '../operation-node/operation-node-source.js';
+import { OverNode } from '../operation-node/over-node.js';
+import { OrderByDirectionExpression } from '../parser/order-by-parser.js';
+import { PartitionByExpression } from '../parser/partition-by-parser.js';
+import { StringReference } from '../parser/reference-parser.js';
+export declare class OverBuilder<DB, TB extends keyof DB> implements OperationNodeSource {
+    #private;
+    constructor(props: OverBuilderProps);
+    /**
+     * Adds an order by clause item inside the over function.
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select(
+     *     eb => eb.fn.avg<number>('age').over(
+     *       ob => ob.orderBy('first_name', 'asc').orderBy('last_name', 'asc')
+     *     ).as('average_age')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select avg("age") over(order by "first_name" asc, "last_name" asc) as "average_age"
+     * from "person"
+     * ```
+     */
+    orderBy(orderBy: StringReference<DB, TB> | DynamicReferenceBuilder<any>, direction?: OrderByDirectionExpression): OverBuilder<DB, TB>;
+    /**
+     * Adds partition by clause item/s inside the over function.
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select(
+     *     eb => eb.fn.avg<number>('age').over(
+     *       ob => ob.partitionBy(['last_name', 'first_name'])
+     *     ).as('average_age')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select avg("age") over(partition by "last_name", "first_name") as "average_age"
+     * from "person"
+     * ```
+     */
+    partitionBy(partitionBy: ReadonlyArray<PartitionByExpression<DB, TB>>): OverBuilder<DB, TB>;
+    partitionBy(partitionBy: PartitionByExpression<DB, TB>): OverBuilder<DB, TB>;
+    toOperationNode(): OverNode;
+}
+export interface OverBuilderProps {
+    readonly overNode: OverNode;
+}

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

@@ -0,0 +1,47 @@
+/// <reference types="./over-builder.d.ts" />
+import { OverNode } from '../operation-node/over-node.js';
+import { parseOrderBy, } from '../parser/order-by-parser.js';
+import { parsePartitionBy, } from '../parser/partition-by-parser.js';
+import { freeze } from '../util/object-utils.js';
+import { preventAwait } from '../util/prevent-await.js';
+export class OverBuilder {
+    #props;
+    constructor(props) {
+        this.#props = freeze(props);
+    }
+    /**
+     * Adds an order by clause item inside the over function.
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select(
+     *     eb => eb.fn.avg<number>('age').over(
+     *       ob => ob.orderBy('first_name', 'asc').orderBy('last_name', 'asc')
+     *     ).as('average_age')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select avg("age") over(order by "first_name" asc, "last_name" asc) as "average_age"
+     * from "person"
+     * ```
+     */
+    orderBy(orderBy, direction) {
+        return new OverBuilder({
+            overNode: OverNode.cloneWithOrderByItem(this.#props.overNode, parseOrderBy(orderBy, direction)),
+        });
+    }
+    partitionBy(partitionBy) {
+        return new OverBuilder({
+            overNode: OverNode.cloneWithPartitionByItems(this.#props.overNode, parsePartitionBy(partitionBy)),
+        });
+    }
+    toOperationNode() {
+        return this.#props.overNode;
+    }
+}
+preventAwait(OverBuilder, "don't await OverBuilder instances. They are never executed directly and are always just a part of a query.");