kysely 0.21.5 → 0.22.0

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

@@ -0,0 +1,146 @@
+"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");
+class AggregateFunctionBuilder {
+    #props;
+    constructor(props) {
+        this.#props = (0, object_utils_js_1.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: aggregate_function_node_js_1.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 = (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
+     *
+     * 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 alias_node_js_1.AliasNode.create(this.#aggregateFunctionBuilder.toOperationNode(), identifier_node_js_1.IdentifierNode.create(this.#alias));
+    }
+}
+exports.AliasedAggregateFunctionBuilder = AliasedAggregateFunctionBuilder;

package/dist/cjs/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/cjs/query-builder/expression-builder.js

@@ -6,7 +6,7 @@ const select_query_node_js_1 = require("../operation-node/select-query-node.js")
 const table_parser_js_1 = require("../parser/table-parser.js");
 const with_schema_plugin_js_1 = require("../plugin/with-schema/with-schema-plugin.js");
 const query_id_js_1 = require("../util/query-id.js");
-const function_builder_js_1 = require("./function-builder.js");
+const function_module_js_1 = require("./function-module.js");
 const reference_parser_js_1 = require("../parser/reference-parser.js");
 const raw_builder_js_1 = require("../raw-builder/raw-builder.js");
 const object_utils_js_1 = require("../util/object-utils.js");
@@ -17,7 +17,7 @@ class ExpressionBuilder {
         this.#props = (0, object_utils_js_1.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
@@ -48,7 +48,7 @@ class ExpressionBuilder {
      * ```
      */
     get fn() {
-        return new function_builder_js_1.FunctionBuilder();
+        return new function_module_js_1.FunctionModule();
     }
     selectFrom(table) {
         return new select_query_builder_js_1.SelectQueryBuilder({

package/dist/cjs/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/cjs/query-builder/{function-builder.js → function-module.js}

@@ -1,10 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FunctionBuilder = void 0;
-const raw_node_js_1 = require("../operation-node/raw-node.js");
+exports.FunctionModule = void 0;
+const aggregate_function_node_js_1 = require("../operation-node/aggregate-function-node.js");
 const reference_parser_js_1 = require("../parser/reference-parser.js");
-const raw_builder_js_1 = require("../raw-builder/raw-builder.js");
-const query_id_js_1 = require("../util/query-id.js");
+const aggregate_function_builder_js_1 = require("./aggregate-function-builder.js");
 /**
  * Helpers for type safe SQL function calls.
  *
@@ -37,46 +36,13 @@ const query_id_js_1 = require("../util/query-id.js");
  * having count("pet"."id") > $1
  * ```
  */
-class FunctionBuilder {
+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.
@@ -100,10 +66,12 @@ class FunctionBuilder {
      * ```
      */
     avg(column) {
-        return this.#oneArgFunction('avg', column);
+        return new aggregate_function_builder_js_1.AggregateFunctionBuilder({
+            aggregateFunctionNode: aggregate_function_node_js_1.AggregateFunctionNode.create('avg', (0, reference_parser_js_1.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
@@ -116,21 +84,68 @@ 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 aggregate_function_builder_js_1.AggregateFunctionBuilder({
+            aggregateFunctionNode: aggregate_function_node_js_1.AggregateFunctionNode.create('count', (0, reference_parser_js_1.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 aggregate_function_builder_js_1.AggregateFunctionBuilder({
+            aggregateFunctionNode: aggregate_function_node_js_1.AggregateFunctionNode.create('max', (0, reference_parser_js_1.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 aggregate_function_builder_js_1.AggregateFunctionBuilder({
+            aggregateFunctionNode: aggregate_function_node_js_1.AggregateFunctionNode.create('min', (0, reference_parser_js_1.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
@@ -140,21 +155,17 @@ 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 raw_builder_js_1.RawBuilder({
-            queryId: (0, query_id_js_1.createQueryId)(),
-            rawNode: raw_node_js_1.RawNode.create([`${fn}(`, ')'], [(0, reference_parser_js_1.parseStringReference)(column)]),
+    sum(column) {
+        return new aggregate_function_builder_js_1.AggregateFunctionBuilder({
+            aggregateFunctionNode: aggregate_function_node_js_1.AggregateFunctionNode.create('sum', (0, reference_parser_js_1.parseStringReference)(column)),
         });
     }
 }
-exports.FunctionBuilder = FunctionBuilder;
+exports.FunctionModule = FunctionModule;

package/dist/cjs/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/cjs/query-builder/over-builder.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OverBuilder = void 0;
+const over_node_js_1 = require("../operation-node/over-node.js");
+const order_by_parser_js_1 = require("../parser/order-by-parser.js");
+const partition_by_parser_js_1 = require("../parser/partition-by-parser.js");
+const object_utils_js_1 = require("../util/object-utils.js");
+const prevent_await_js_1 = require("../util/prevent-await.js");
+class OverBuilder {
+    #props;
+    constructor(props) {
+        this.#props = (0, object_utils_js_1.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: over_node_js_1.OverNode.cloneWithOrderByItem(this.#props.overNode, (0, order_by_parser_js_1.parseOrderBy)(orderBy, direction)),
+        });
+    }
+    partitionBy(partitionBy) {
+        return new OverBuilder({
+            overNode: over_node_js_1.OverNode.cloneWithPartitionByItems(this.#props.overNode, (0, partition_by_parser_js_1.parsePartitionBy)(partitionBy)),
+        });
+    }
+    toOperationNode() {
+        return this.#props.overNode;
+    }
+}
+exports.OverBuilder = OverBuilder;
+(0, prevent_await_js_1.preventAwait)(OverBuilder, "don't await OverBuilder instances. They are never executed directly and are always just a part of a query.");