kysely 0.27.3 → 0.27.5

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

@@ -2,20 +2,68 @@ import { QueryResult } from '../../driver/database-connection.js';
 import { RootOperationNode } from '../../query-compiler/query-compiler.js';
 import { UnknownRow } from '../../util/type-utils.js';
 import { KyselyPlugin, PluginTransformQueryArgs, PluginTransformResultArgs } from '../kysely-plugin.js';
+export interface ParseJSONResultsPluginOptions {
+    /**
+     * When `'in-place'`, arrays' and objects' values are parsed in-place. This is
+     * the most time and space efficient option.
+     *
+     * This can result in runtime errors if some objects/arrays are readonly.
+     *
+     * When `'create'`, new arrays and objects are created to avoid such errors.
+     *
+     * Defaults to `'in-place'`.
+     */
+    objectStrategy?: ObjectStrategy;
+}
+type ObjectStrategy = 'in-place' | 'create';
 /**
  * Parses JSON strings in query results into JSON objects.
  *
  * 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;
+    readonly opt: ParseJSONResultsPluginOptions;
+    constructor(opt?: ParseJSONResultsPluginOptions);
     /**
      * This is called for each query before it is executed. You can modify the query by
      * transforming its {@link OperationNode} tree provided in {@link PluginTransformQueryArgs.node | args.node}
@@ -26,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`
@@ -53,3 +123,4 @@ export declare class ParseJSONResultsPlugin implements KyselyPlugin {
      */
     transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>>;
 }
+export {};

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

@@ -8,14 +8,51 @@ const object_utils_js_1 = require("../../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()
+ * ```
  */
 class ParseJSONResultsPlugin {
+    opt;
+    #objectStrategy;
+    constructor(opt = {}) {
+        this.opt = opt;
+        this.#objectStrategy = opt.objectStrategy || 'in-place';
+    }
     // noop
     transformQuery(args) {
         return args.node;
@@ -23,33 +60,34 @@ class ParseJSONResultsPlugin {
     async transformResult(args) {
         return {
             ...args.result,
-            rows: parseArray(args.result.rows),
+            rows: parseArray(args.result.rows, this.#objectStrategy),
         };
     }
 }
 exports.ParseJSONResultsPlugin = ParseJSONResultsPlugin;
-function parseArray(arr) {
+function parseArray(arr, objectStrategy) {
+    const target = objectStrategy === 'create' ? new Array(arr.length) : arr;
     for (let i = 0; i < arr.length; ++i) {
-        arr[i] = parse(arr[i]);
+        target[i] = parse(arr[i], objectStrategy);
     }
-    return arr;
+    return target;
 }
-function parse(obj) {
+function parse(obj, objectStrategy) {
     if ((0, object_utils_js_1.isString)(obj)) {
         return parseString(obj);
     }
     if (Array.isArray(obj)) {
-        return parseArray(obj);
+        return parseArray(obj, objectStrategy);
     }
     if ((0, object_utils_js_1.isPlainObject)(obj)) {
-        return parseObject(obj);
+        return parseObject(obj, objectStrategy);
     }
     return obj;
 }
 function parseString(str) {
     if (maybeJson(str)) {
         try {
-            return parse(JSON.parse(str));
+            return parse(JSON.parse(str), 'in-place');
         }
         catch (err) {
             // this catch block is intentionally empty.
@@ -60,9 +98,10 @@ function parseString(str) {
 function maybeJson(value) {
     return value.match(/^[\[\{]/) != null;
 }
-function parseObject(obj) {
+function parseObject(obj, objectStrategy) {
+    const target = objectStrategy === 'create' ? {} : obj;
     for (const key in obj) {
-        obj[key] = parse(obj[key]);
+        target[key] = parse(obj[key], objectStrategy);
     }
-    return obj;
+    return target;
 }

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

@@ -8,6 +8,7 @@ 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 order_by_parser_js_1 = require("../parser/order-by-parser.js");
 class AggregateFunctionBuilder {
     #props;
     constructor(props) {
@@ -72,6 +73,35 @@ class AggregateFunctionBuilder {
             aggregateFunctionNode: aggregate_function_node_js_1.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: aggregate_function_node_js_1.AggregateFunctionNode.cloneWithOrderBy(this.#props.aggregateFunctionNode, (0, order_by_parser_js_1.parseOrderBy)([orderBy, direction])),
+        });
+    }
     filterWhere(...args) {
         return new AggregateFunctionBuilder({
             ...this.#props,