kysely 0.27.4 → 0.27.5

package/dist/esm/plugin/deduplicate-joins/deduplicate-joins-transformer.js

@@ -24,8 +24,8 @@ export class DeduplicateJoinsTransformer extends OperationNodeTransformer {
         const out = [];
         for (let i = 0; i < joins.length; ++i) {
             let foundDuplicate = false;
-            for (let j = i + 1; j < joins.length; ++j) {
-                if (compare(joins[i], joins[j])) {
+            for (let j = 0; j < out.length; ++j) {
+                if (compare(joins[i], out[j])) {
                     foundDuplicate = true;
                     break;
                 }

package/dist/esm/plugin/immediate-value/immediate-value-plugin.d.ts

@@ -22,19 +22,41 @@ export declare class ImmediateValuePlugin implements KyselyPlugin {
      * can use a `WeakMap` with {@link PluginTransformQueryArgs.queryId | args.queryId} as the key:
      *
      * ```ts
-     * const plugin = {
-     *   data: new WeakMap<QueryId, SomeData>(),
+     * import type {
+     *   KyselyPlugin,
+     *   QueryResult,
+     *   RootOperationNode,
+     *   UnknownRow
+     * } from 'kysely'
+     *
+     * interface MyData {
+     *   // ...
+     * }
+     * const data = new WeakMap<any, MyData>()
      *
+     * const plugin = {
      *   transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
-     *     this.data.set(args.queryId, something)
+     *     const something: MyData = {}
+     *
+     *     // ...
+     *
+     *     data.set(args.queryId, something)
+     *
+     *     // ...
+     *
      *     return args.node
      *   },
      *
-     *   transformResult(args: PluginTransformResultArgs): QueryResult<UnknownRow> {
-     *     const data = this.data.get(args.queryId)
+     *   async transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {
+     *     // ...
+     *
+     *     const something = data.get(args.queryId)
+     *
+     *     // ...
+     *
      *     return args.result
      *   }
-     * }
+     * } satisfies KyselyPlugin
      * ```
      *
      * You should use a `WeakMap` instead of a `Map` or some other strong references because `transformQuery`

package/dist/esm/plugin/kysely-plugin.d.ts

@@ -13,19 +13,41 @@ export interface KyselyPlugin {
      * can use a `WeakMap` with {@link PluginTransformQueryArgs.queryId | args.queryId} as the key:
      *
      * ```ts
-     * const plugin = {
-     *   data: new WeakMap<QueryId, SomeData>(),
+     * import type {
+     *   KyselyPlugin,
+     *   QueryResult,
+     *   RootOperationNode,
+     *   UnknownRow
+     * } from 'kysely'
+     *
+     * interface MyData {
+     *   // ...
+     * }
+     * const data = new WeakMap<any, MyData>()
      *
+     * const plugin = {
      *   transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
-     *     this.data.set(args.queryId, something)
+     *     const something: MyData = {}
+     *
+     *     // ...
+     *
+     *     data.set(args.queryId, something)
+     *
+     *     // ...
+     *
      *     return args.node
      *   },
      *
-     *   transformResult(args: PluginTransformResultArgs): QueryResult<UnknownRow> {
-     *     const data = this.data.get(args.queryId)
+     *   async transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {
+     *     // ...
+     *
+     *     const something = data.get(args.queryId)
+     *
+     *     // ...
+     *
      *     return args.result
      *   }
-     * }
+     * } satisfies KyselyPlugin
      * ```
      *
      * You should use a `WeakMap` instead of a `Map` or some other strong references because `transformQuery`

package/dist/esm/plugin/noop-plugin.d.ts

@@ -13,19 +13,41 @@ export declare class NoopPlugin implements KyselyPlugin {
      * can use a `WeakMap` with {@link PluginTransformQueryArgs.queryId | args.queryId} as the key:
      *
      * ```ts
-     * const plugin = {
-     *   data: new WeakMap<QueryId, SomeData>(),
+     * import type {
+     *   KyselyPlugin,
+     *   QueryResult,
+     *   RootOperationNode,
+     *   UnknownRow
+     * } from 'kysely'
+     *
+     * interface MyData {
+     *   // ...
+     * }
+     * const data = new WeakMap<any, MyData>()
      *
+     * const plugin = {
      *   transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
-     *     this.data.set(args.queryId, something)
+     *     const something: MyData = {}
+     *
+     *     // ...
+     *
+     *     data.set(args.queryId, something)
+     *
+     *     // ...
+     *
      *     return args.node
      *   },
      *
-     *   transformResult(args: PluginTransformResultArgs): QueryResult<UnknownRow> {
-     *     const data = this.data.get(args.queryId)
+     *   async transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {
+     *     // ...
+     *
+     *     const something = data.get(args.queryId)
+     *
+     *     // ...
+     *
      *     return args.result
      *   }
-     * }
+     * } satisfies KyselyPlugin
      * ```
      *
      * You should use a `WeakMap` instead of a `Map` or some other strong references because `transformQuery`

package/dist/esm/plugin/parse-json-results/parse-json-results-plugin.d.ts

@@ -22,12 +22,43 @@ type ObjectStrategy = 'in-place' | 'create';
  * This plugin can be useful with dialects that don't automatically parse
  * JSON into objects and arrays but return JSON strings instead.
  *
+ * To apply this plugin globally, pass an instance of it to the `plugins` option
+ * when creating a new `Kysely` instance:
+ *
  * ```ts
- * const db = new Kysely<DB>({
- *   ...
- *   plugins: [new ParseJSONResultsPlugin()]
+ * import * as Sqlite from 'better-sqlite3'
+ * import { Kysely, ParseJSONResultsPlugin, SqliteDialect } from 'kysely'
+ * import type { Database } from 'type-editor' // imaginary module
+ *
+ * const db = new Kysely<Database>({
+ *   dialect: new SqliteDialect({
+ *     database: new Sqlite(':memory:'),
+ *   }),
+ *   plugins: [new ParseJSONResultsPlugin()],
  * })
  * ```
+ *
+ * To apply this plugin to a single query:
+ *
+ * ```ts
+ * import { ParseJSONResultsPlugin } from 'kysely'
+ * import { jsonArrayFrom } from 'kysely/helpers/sqlite'
+ *
+ * const result = await db
+ *   .selectFrom('person')
+ *   .select((eb) => [
+ *     'id',
+ *     'first_name',
+ *     'last_name',
+ *     jsonArrayFrom(
+ *       eb.selectFrom('pet')
+ *         .whereRef('owner_id', '=', 'person.id')
+ *         .select(['name', 'species'])
+ *     ).as('pets')
+ *   ])
+ *   .withPlugin(new ParseJSONResultsPlugin())
+ *   .execute()
+ * ```
  */
 export declare class ParseJSONResultsPlugin implements KyselyPlugin {
     #private;
@@ -43,19 +74,41 @@ export declare class ParseJSONResultsPlugin implements KyselyPlugin {
      * can use a `WeakMap` with {@link PluginTransformQueryArgs.queryId | args.queryId} as the key:
      *
      * ```ts
-     * const plugin = {
-     *   data: new WeakMap<QueryId, SomeData>(),
+     * import type {
+     *   KyselyPlugin,
+     *   QueryResult,
+     *   RootOperationNode,
+     *   UnknownRow
+     * } from 'kysely'
+     *
+     * interface MyData {
+     *   // ...
+     * }
+     * const data = new WeakMap<any, MyData>()
      *
+     * const plugin = {
      *   transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
-     *     this.data.set(args.queryId, something)
+     *     const something: MyData = {}
+     *
+     *     // ...
+     *
+     *     data.set(args.queryId, something)
+     *
+     *     // ...
+     *
      *     return args.node
      *   },
      *
-     *   transformResult(args: PluginTransformResultArgs): QueryResult<UnknownRow> {
-     *     const data = this.data.get(args.queryId)
+     *   async transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {
+     *     // ...
+     *
+     *     const something = data.get(args.queryId)
+     *
+     *     // ...
+     *
      *     return args.result
      *   }
-     * }
+     * } satisfies KyselyPlugin
      * ```
      *
      * You should use a `WeakMap` instead of a `Map` or some other strong references because `transformQuery`

package/dist/esm/plugin/parse-json-results/parse-json-results-plugin.js

@@ -6,12 +6,43 @@ import { isPlainObject, isString } from '../../util/object-utils.js';
  * This plugin can be useful with dialects that don't automatically parse
  * JSON into objects and arrays but return JSON strings instead.
  *
+ * To apply this plugin globally, pass an instance of it to the `plugins` option
+ * when creating a new `Kysely` instance:
+ *
  * ```ts
- * const db = new Kysely<DB>({
- *   ...
- *   plugins: [new ParseJSONResultsPlugin()]
+ * import * as Sqlite from 'better-sqlite3'
+ * import { Kysely, ParseJSONResultsPlugin, SqliteDialect } from 'kysely'
+ * import type { Database } from 'type-editor' // imaginary module
+ *
+ * const db = new Kysely<Database>({
+ *   dialect: new SqliteDialect({
+ *     database: new Sqlite(':memory:'),
+ *   }),
+ *   plugins: [new ParseJSONResultsPlugin()],
  * })
  * ```
+ *
+ * To apply this plugin to a single query:
+ *
+ * ```ts
+ * import { ParseJSONResultsPlugin } from 'kysely'
+ * import { jsonArrayFrom } from 'kysely/helpers/sqlite'
+ *
+ * const result = await db
+ *   .selectFrom('person')
+ *   .select((eb) => [
+ *     'id',
+ *     'first_name',
+ *     'last_name',
+ *     jsonArrayFrom(
+ *       eb.selectFrom('pet')
+ *         .whereRef('owner_id', '=', 'person.id')
+ *         .select(['name', 'species'])
+ *     ).as('pets')
+ *   ])
+ *   .withPlugin(new ParseJSONResultsPlugin())
+ *   .execute()
+ * ```
  */
 export class ParseJSONResultsPlugin {
     opt;

package/dist/esm/plugin/with-schema/with-schema-plugin.d.ts

@@ -15,19 +15,41 @@ export declare class WithSchemaPlugin implements KyselyPlugin {
      * can use a `WeakMap` with {@link PluginTransformQueryArgs.queryId | args.queryId} as the key:
      *
      * ```ts
-     * const plugin = {
-     *   data: new WeakMap<QueryId, SomeData>(),
+     * import type {
+     *   KyselyPlugin,
+     *   QueryResult,
+     *   RootOperationNode,
+     *   UnknownRow
+     * } from 'kysely'
+     *
+     * interface MyData {
+     *   // ...
+     * }
+     * const data = new WeakMap<any, MyData>()
      *
+     * const plugin = {
      *   transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
-     *     this.data.set(args.queryId, something)
+     *     const something: MyData = {}
+     *
+     *     // ...
+     *
+     *     data.set(args.queryId, something)
+     *
+     *     // ...
+     *
      *     return args.node
      *   },
      *
-     *   transformResult(args: PluginTransformResultArgs): QueryResult<UnknownRow> {
-     *     const data = this.data.get(args.queryId)
+     *   async transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {
+     *     // ...
+     *
+     *     const something = data.get(args.queryId)
+     *
+     *     // ...
+     *
      *     return args.result
      *   }
-     * }
+     * } satisfies KyselyPlugin
      * ```
      *
      * You should use a `WeakMap` instead of a `Map` or some other strong references because `transformQuery`

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

@@ -2,10 +2,12 @@ import { AggregateFunctionNode } from '../operation-node/aggregate-function-node
 import { AliasNode } from '../operation-node/alias-node.js';
 import { OverBuilder } from './over-builder.js';
 import { AliasableExpression, AliasedExpression, Expression } from '../expression/expression.js';
-import { ReferenceExpression } from '../parser/reference-parser.js';
+import { ReferenceExpression, StringReference } from '../parser/reference-parser.js';
 import { ComparisonOperatorExpression, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
 import { SqlBool } from '../util/type-utils.js';
 import { ExpressionOrFactory } from '../parser/expression-parser.js';
+import { DynamicReferenceBuilder } from '../dynamic/dynamic-reference-builder.js';
+import { OrderByDirectionExpression } from '../parser/order-by-parser.js';
 export declare class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unknown> implements AliasableExpression<O> {
     #private;
     constructor(props: AggregateFunctionBuilderProps);
@@ -14,11 +16,19 @@ export declare class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unkno
      * 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:
      *
+     * ### Examples
+     *
      * ```ts
+     * import { type Expression, type OperationNode, sql } from 'kysely'
+     *
      * class SomeExpression<T> implements Expression<T> {
      *   get expressionType(): T | undefined {
      *     return undefined
      *   }
+     *
+     *   toOperationNode(): OperationNode {
+     *     return sql`some sql here`.toOperationNode()
+     *   }
      * }
      * ```
      *
@@ -75,6 +85,30 @@ export declare class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unkno
      * ```
      */
     distinct(): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * Adds an `order by` clause inside the aggregate function.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .innerJoin('pet', 'pet.owner_id', 'person.id')
+     *   .select((eb) =>
+     *     eb.fn.jsonAgg('pet').orderBy('pet.name').as('person_pets')
+     *   )
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select json_agg("pet" order by "pet"."name") as "person_pets"
+     * from "person"
+     * inner join "pet" ON "pet"."owner_id" = "person"."id"
+     * ```
+     */
+    orderBy<OE extends StringReference<DB, TB> | DynamicReferenceBuilder<any>>(orderBy: OE, direction?: OrderByDirectionExpression): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Adds a `filter` clause with a nested `where` clause after the function.
      *
@@ -219,11 +253,19 @@ export declare class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unkno
     /**
      * Creates the OperationNode that describes how to compile this expression into SQL.
      *
+     * ### Examples
+     *
      * If you are creating a custom expression, it's often easiest to use the {@link sql}
      * template tag to build the node:
      *
      * ```ts
+     * import { type Expression, type OperationNode, sql } from 'kysely'
+     *
      * class SomeExpression<T> implements Expression<T> {
+     *   get expressionType(): T | undefined {
+     *     return undefined
+     *   }
+     *
      *   toOperationNode(): OperationNode {
      *     return sql`some sql here`.toOperationNode()
      *   }

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

@@ -6,6 +6,7 @@ import { IdentifierNode } from '../operation-node/identifier-node.js';
 import { preventAwait } from '../util/prevent-await.js';
 import { createOverBuilder } from '../parser/parse-utils.js';
 import { parseReferentialBinaryOperation, parseValueBinaryOperationOrExpression, } from '../parser/binary-operation-parser.js';
+import { parseOrderBy, } from '../parser/order-by-parser.js';
 export class AggregateFunctionBuilder {
     #props;
     constructor(props) {
@@ -70,6 +71,35 @@ export class AggregateFunctionBuilder {
             aggregateFunctionNode: AggregateFunctionNode.cloneWithDistinct(this.#props.aggregateFunctionNode),
         });
     }
+    /**
+     * Adds an `order by` clause inside the aggregate function.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .innerJoin('pet', 'pet.owner_id', 'person.id')
+     *   .select((eb) =>
+     *     eb.fn.jsonAgg('pet').orderBy('pet.name').as('person_pets')
+     *   )
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select json_agg("pet" order by "pet"."name") as "person_pets"
+     * from "person"
+     * inner join "pet" ON "pet"."owner_id" = "person"."id"
+     * ```
+     */
+    orderBy(orderBy, direction) {
+        return new AggregateFunctionBuilder({
+            ...this.#props,
+            aggregateFunctionNode: AggregateFunctionNode.cloneWithOrderBy(this.#props.aggregateFunctionNode, parseOrderBy([orderBy, direction])),
+        });
+    }
     filterWhere(...args) {
         return new AggregateFunctionBuilder({
             ...this.#props,