kysely 0.27.3 → 0.27.5

package/dist/esm/plugin/camel-case/camel-case-plugin.js

@@ -4,47 +4,48 @@ import { SnakeCaseTransformer } from './camel-case-transformer.js';
 import { createCamelCaseMapper, createSnakeCaseMapper, } from './camel-case.js';
 /**
  * A plugin that converts snake_case identifiers in the database into
- * camelCase in the javascript side.
+ * camelCase in the JavaScript side.
  *
  * For example let's assume we have a table called `person_table`
  * with columns `first_name` and `last_name` in the database. When
  * using `CamelCasePlugin` we would setup Kysely like this:
  *
  * ```ts
- * interface Person {
- *   firstName: string
- *   lastName: string
- * }
+ * import * as Sqlite from 'better-sqlite3'
+ * import { CamelCasePlugin, Kysely, SqliteDialect } from 'kysely'
  *
- * interface Database {
- *   personTable: Person
+ * interface CamelCasedDatabase {
+ *   userMetadata: {
+ *     firstName: string
+ *     lastName: string
+ *   }
  * }
  *
- * const db = new Kysely<Database>({
- *   dialect: new PostgresDialect({
- *     database: 'kysely_test',
- *     host: 'localhost',
+ * const db = new Kysely<CamelCasedDatabase>({
+ *   dialect: new SqliteDialect({
+ *     database: new Sqlite(':memory:'),
  *   }),
- *   plugins: [
- *     new CamelCasePlugin()
- *   ]
+ *   plugins: [new CamelCasePlugin()],
  * })
  *
- * const person = await db.selectFrom('personTable')
+ * const person = await db.selectFrom('userMetadata')
  *   .where('firstName', '=', 'Arnold')
  *   .select(['firstName', 'lastName'])
  *   .executeTakeFirst()
  *
- * // generated sql:
- * // select first_name, last_name from person_table where first_name = $1
- *
  * if (person) {
  *   console.log(person.firstName)
  * }
  * ```
  *
+ * The generated SQL (SQLite):
+ *
+ * ```sql
+ * select "first_name", "last_name" from "user_metadata" where "first_name" = ?
+ * ```
+ *
  * As you can see from the example, __everything__ needs to be defined
- * in camelCase in the typescript code: table names, columns, schemas,
+ * in camelCase in the TypeScript code: table names, columns, schemas,
  * __everything__. When using the `CamelCasePlugin` Kysely works as if
  * the database was defined in camelCase.
  *
@@ -57,11 +58,15 @@ import { createCamelCaseMapper, createSnakeCaseMapper, } from './camel-case.js';
  * ```ts
  * class MyCamelCasePlugin extends CamelCasePlugin {
  *   protected override snakeCase(str: string): string {
- *     return mySnakeCase(str)
+ *     // ...
+ *
+ *     return str
  *   }
  *
  *   protected override camelCase(str: string): string {
- *     return myCamelCase(str)
+ *     // ...
+ *
+ *     return str
  *   }
  * }
  * ```

package/dist/esm/plugin/deduplicate-joins/deduplicate-joins-plugin.d.ts

@@ -5,7 +5,7 @@ import { KyselyPlugin, PluginTransformQueryArgs, PluginTransformResultArgs } fro
 /**
  * Plugin that removes duplicate joins from queries.
  *
- * See [this recipe](https://github.com/koskimas/kysely/tree/master/site/docs/recipes/deduplicate-joins.md)
+ * See [this recipe](https://github.com/kysely-org/kysely/blob/master/site/docs/recipes/0008-deduplicate-joins.md)
  */
 export declare class DeduplicateJoinsPlugin implements KyselyPlugin {
     #private;
@@ -19,19 +19,41 @@ export declare class DeduplicateJoinsPlugin 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/deduplicate-joins/deduplicate-joins-plugin.js

@@ -3,7 +3,7 @@ import { DeduplicateJoinsTransformer } from './deduplicate-joins-transformer.js'
 /**
  * Plugin that removes duplicate joins from queries.
  *
- * See [this recipe](https://github.com/koskimas/kysely/tree/master/site/docs/recipes/deduplicate-joins.md)
+ * See [this recipe](https://github.com/kysely-org/kysely/blob/master/site/docs/recipes/0008-deduplicate-joins.md)
  */
 export class DeduplicateJoinsPlugin {
     #transformer = new DeduplicateJoinsTransformer();

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

@@ -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/esm/plugin/parse-json-results/parse-json-results-plugin.js

@@ -6,14 +6,51 @@ 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;
+    #objectStrategy;
+    constructor(opt = {}) {
+        this.opt = opt;
+        this.#objectStrategy = opt.objectStrategy || 'in-place';
+    }
     // noop
     transformQuery(args) {
         return args.node;
@@ -21,32 +58,33 @@ export class ParseJSONResultsPlugin {
     async transformResult(args) {
         return {
             ...args.result,
-            rows: parseArray(args.result.rows),
+            rows: parseArray(args.result.rows, this.#objectStrategy),
         };
     }
 }
-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 (isString(obj)) {
         return parseString(obj);
     }
     if (Array.isArray(obj)) {
-        return parseArray(obj);
+        return parseArray(obj, objectStrategy);
     }
     if (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.
@@ -57,9 +95,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/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()
      *   }