kysely 0.28.17 → 0.29.0

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

@@ -0,0 +1,143 @@
+/// <reference types="./parse-json-results-plugin.d.ts" />
+import { freeze, isPlainObject, isString } from '../../util/object-utils.js';
+/**
+ * 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
+ * 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 {
+    options;
+    #options;
+    constructor(options = {}) {
+        this.options = options;
+        const { shouldParse } = options;
+        this.#options = freeze({
+            objectStrategy: options.objectStrategy || 'in-place',
+            reviver: options.reviver || ((_, value) => value),
+            shouldParse: shouldParse
+                ? (value, jsonPath) => maybeJson(value) && shouldParse(value, jsonPath)
+                : maybeJson,
+        });
+    }
+    // noop
+    transformQuery(args) {
+        return args.node;
+    }
+    async transformResult(args) {
+        return {
+            ...args.result,
+            rows: parseArray(args.result.rows, '$', this.#options),
+        };
+    }
+}
+function parseArray(arr, jsonPath, options) {
+    const target = options.objectStrategy === 'create' ? new Array(arr.length) : arr;
+    for (let i = 0; i < arr.length; ++i) {
+        target[i] = parse(arr[i], `${jsonPath}[${i}]`, options);
+    }
+    return target;
+}
+function parse(value, jsonPath, options) {
+    if (isString(value)) {
+        return parseString(value, jsonPath, options);
+    }
+    if (Array.isArray(value)) {
+        return parseArray(value, jsonPath, options);
+    }
+    if (isPlainObject(value)) {
+        return parseObject(value, jsonPath, options);
+    }
+    return value;
+}
+function parseString(str, jsonPath, options) {
+    const { shouldParse } = options;
+    if (!shouldParse(str, jsonPath)) {
+        return str;
+    }
+    try {
+        return parse(JSON.parse(str, (key, value, ...otherArgs) => {
+            // prevent prototype pollution
+            if (key === '__proto__') {
+                return;
+            }
+            // prevent prototype pollution
+            if (key === 'constructor' &&
+                isPlainObject(value) &&
+                Object.hasOwn(value, 'prototype')) {
+                delete value.prototype;
+            }
+            return options.reviver(key, value, ...otherArgs);
+        }), jsonPath, { ...options, objectStrategy: 'in-place' });
+    }
+    catch (error) {
+        // custom JSON detection should expose parsing errors.
+        if (shouldParse !== maybeJson) {
+            throw error;
+        }
+        // built-in naive heuristic should keep going despite errors given there might be false positives in detection.
+        console.error(error);
+        return str;
+    }
+}
+function maybeJson(value) {
+    return ((value.startsWith('{') && value.endsWith('}')) ||
+        (value.startsWith('[') && value.endsWith(']')));
+}
+function parseObject(obj, jsonPath, options) {
+    const { objectStrategy } = options;
+    const target = objectStrategy === 'create' ? {} : obj;
+    for (const key of Object.keys(obj)) {
+        // prevent prototype pollution
+        if (key === '__proto__') {
+            continue;
+        }
+        const parsed = parse(obj[key], `${jsonPath}."${key}"`, options);
+        // prevent prototype pollution
+        if (key === 'constructor' &&
+            isPlainObject(parsed) &&
+            Object.hasOwn(parsed, 'prototype')) {
+            delete parsed.prototype;
+        }
+        target[key] = parsed;
+    }
+    return target;
+}

package/dist/plugin/safe-null-comparison/safe-null-comparison-plugin.d.ts

@@ -0,0 +1,81 @@
+import type { QueryResult } from '../../driver/database-connection.js';
+import type { RootOperationNode } from '../../operation-node/root-operation-node.js';
+import type { UnknownRow } from '../../util/type-utils.js';
+import type { KyselyPlugin, PluginTransformQueryArgs, PluginTransformResultArgs } from '../kysely-plugin.js';
+/**
+ * Plugin that handles NULL comparisons to prevent common SQL mistakes.
+ *
+ * In SQL, comparing values with NULL using standard comparison operators (=, !=, <>)
+ * always yields NULL, which is usually not what developers expect. The correct way
+ * to compare with NULL is using IS NULL and IS NOT NULL.
+ *
+ * When working with nullable variables (e.g. string | null), you need to be careful to
+ * manually handle these cases with conditional WHERE clauses. This plugins automatically
+ * applies the correct operator based on the value, allowing you to simply write `query.where('name', '=', name)`.
+ *
+ * The plugin transforms the following operators when comparing with NULL:
+ * - `=` becomes `IS`
+ * - `!=` becomes `IS NOT`
+ * - `<>` becomes `IS NOT`
+ */
+export declare class SafeNullComparisonPlugin implements KyselyPlugin {
+    #private;
+    /**
+     * 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}
+     * and returning the transformed tree. You'd usually want to use an {@link OperationNodeTransformer}
+     * for this.
+     *
+     * If you need to pass some query-related data between this method and `transformResult` you
+     * can use a `WeakMap` with {@link PluginTransformQueryArgs.queryId | args.queryId} as the key:
+     *
+     * ```ts
+     * import type {
+     *   KyselyPlugin,
+     *   QueryResult,
+     *   RootOperationNode,
+     *   UnknownRow
+     * } from 'kysely'
+     *
+     * interface MyData {
+     *   // ...
+     * }
+     * const data = new WeakMap<any, MyData>()
+     *
+     * const plugin = {
+     *   transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
+     *     const something: MyData = {}
+     *
+     *     // ...
+     *
+     *     data.set(args.queryId, something)
+     *
+     *     // ...
+     *
+     *     return args.node
+     *   },
+     *
+     *   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`
+     * is not always matched by a call to `transformResult` which would leave orphaned items in the map
+     * and cause a memory leak.
+     */
+    transformQuery(args: PluginTransformQueryArgs): RootOperationNode;
+    /**
+     * This method is called for each query after it has been executed. The result
+     * of the query can be accessed through {@link PluginTransformResultArgs.result | args.result}.
+     * You can modify the result and return the modifier result.
+     */
+    transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>>;
+}

package/dist/plugin/safe-null-comparison/safe-null-comparison-plugin.js

@@ -0,0 +1,27 @@
+/// <reference types="./safe-null-comparison-plugin.d.ts" />
+import { SafeNullComparisonTransformer } from './safe-null-comparison-transformer.js';
+/**
+ * Plugin that handles NULL comparisons to prevent common SQL mistakes.
+ *
+ * In SQL, comparing values with NULL using standard comparison operators (=, !=, <>)
+ * always yields NULL, which is usually not what developers expect. The correct way
+ * to compare with NULL is using IS NULL and IS NOT NULL.
+ *
+ * When working with nullable variables (e.g. string | null), you need to be careful to
+ * manually handle these cases with conditional WHERE clauses. This plugins automatically
+ * applies the correct operator based on the value, allowing you to simply write `query.where('name', '=', name)`.
+ *
+ * The plugin transforms the following operators when comparing with NULL:
+ * - `=` becomes `IS`
+ * - `!=` becomes `IS NOT`
+ * - `<>` becomes `IS NOT`
+ */
+export class SafeNullComparisonPlugin {
+    #transformer = new SafeNullComparisonTransformer();
+    transformQuery(args) {
+        return this.#transformer.transformNode(args.node);
+    }
+    transformResult(args) {
+        return Promise.resolve(args.result);
+    }
+}

package/dist/plugin/safe-null-comparison/safe-null-comparison-transformer.d.ts

@@ -0,0 +1,5 @@
+import { BinaryOperationNode } from '../../operation-node/binary-operation-node.js';
+import { OperationNodeTransformer } from '../../operation-node/operation-node-transformer.js';
+export declare class SafeNullComparisonTransformer extends OperationNodeTransformer {
+    protected transformBinaryOperation(node: BinaryOperationNode): BinaryOperationNode;
+}

package/dist/plugin/safe-null-comparison/safe-null-comparison-transformer.js

@@ -0,0 +1,20 @@
+/// <reference types="./safe-null-comparison-transformer.d.ts" />
+import { BinaryOperationNode } from '../../operation-node/binary-operation-node.js';
+import { OperationNodeTransformer } from '../../operation-node/operation-node-transformer.js';
+import { OperatorNode } from '../../operation-node/operator-node.js';
+import { ValueNode } from '../../operation-node/value-node.js';
+export class SafeNullComparisonTransformer extends OperationNodeTransformer {
+    transformBinaryOperation(node) {
+        const { operator, leftOperand, rightOperand } = super.transformBinaryOperation(node);
+        if (!ValueNode.is(rightOperand) ||
+            rightOperand.value !== null ||
+            !OperatorNode.is(operator)) {
+            return node;
+        }
+        const op = operator.operator;
+        if (op !== '=' && op !== '!=' && op !== '<>') {
+            return node;
+        }
+        return BinaryOperationNode.create(leftOperand, OperatorNode.create(op === '=' ? 'is' : 'is not'), rightOperand);
+    }
+}

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

@@ -0,0 +1,66 @@
+import type { QueryResult } from '../../driver/database-connection.js';
+import type { KyselyPlugin, PluginTransformQueryArgs, PluginTransformResultArgs } from '../kysely-plugin.js';
+import type { UnknownRow } from '../../util/type-utils.js';
+import type { RootOperationNode } from '../../operation-node/root-operation-node.js';
+export declare class WithSchemaPlugin implements KyselyPlugin {
+    #private;
+    constructor(schema: string);
+    /**
+     * 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}
+     * and returning the transformed tree. You'd usually want to use an {@link OperationNodeTransformer}
+     * for this.
+     *
+     * If you need to pass some query-related data between this method and `transformResult` you
+     * can use a `WeakMap` with {@link PluginTransformQueryArgs.queryId | args.queryId} as the key:
+     *
+     * ```ts
+     * import type {
+     *   KyselyPlugin,
+     *   QueryResult,
+     *   RootOperationNode,
+     *   UnknownRow
+     * } from 'kysely'
+     *
+     * interface MyData {
+     *   // ...
+     * }
+     * const data = new WeakMap<any, MyData>()
+     *
+     * const plugin = {
+     *   transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
+     *     const something: MyData = {}
+     *
+     *     // ...
+     *
+     *     data.set(args.queryId, something)
+     *
+     *     // ...
+     *
+     *     return args.node
+     *   },
+     *
+     *   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`
+     * is not always matched by a call to `transformResult` which would leave orphaned items in the map
+     * and cause a memory leak.
+     */
+    transformQuery(args: PluginTransformQueryArgs): RootOperationNode;
+    /**
+     * This method is called for each query after it has been executed. The result
+     * of the query can be accessed through {@link PluginTransformResultArgs.result | args.result}.
+     * You can modify the result and return the modifier result.
+     */
+    transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>>;
+}

package/dist/plugin/with-schema/with-schema-transformer.js

@@ -0,0 +1,170 @@
+/// <reference types="./with-schema-transformer.d.ts" />
+import { AliasNode } from '../../operation-node/alias-node.js';
+import { IdentifierNode } from '../../operation-node/identifier-node.js';
+import { JoinNode } from '../../operation-node/join-node.js';
+import { ListNode } from '../../operation-node/list-node.js';
+import { OperationNodeTransformer } from '../../operation-node/operation-node-transformer.js';
+import { isRootOperationNode, } from '../../operation-node/root-operation-node.js';
+import { SchemableIdentifierNode } from '../../operation-node/schemable-identifier-node.js';
+import { TableNode } from '../../operation-node/table-node.js';
+import { UsingNode } from '../../operation-node/using-node.js';
+import { freeze } from '../../util/object-utils.js';
+const SCHEMALESS_FUNCTIONS = freeze({
+    json_agg: true,
+    to_json: true,
+});
+export class WithSchemaTransformer extends OperationNodeTransformer {
+    #schema;
+    #schemableIds = new Set();
+    #ctes = new Set();
+    constructor(schema) {
+        super();
+        this.#schema = schema;
+    }
+    transformNodeImpl(node, queryId) {
+        if (!isRootOperationNode(node)) {
+            return super.transformNodeImpl(node, queryId);
+        }
+        const ctes = this.#collectCTEs(node);
+        for (const cte of ctes) {
+            this.#ctes.add(cte);
+        }
+        const tables = this.#collectSchemableIds(node);
+        for (const table of tables) {
+            this.#schemableIds.add(table);
+        }
+        const transformed = super.transformNodeImpl(node, queryId);
+        for (const table of tables) {
+            this.#schemableIds.delete(table);
+        }
+        for (const cte of ctes) {
+            this.#ctes.delete(cte);
+        }
+        return transformed;
+    }
+    transformSchemableIdentifier(node, queryId) {
+        const transformed = super.transformSchemableIdentifier(node, queryId);
+        if (transformed.schema || !this.#schemableIds.has(node.identifier.name)) {
+            return transformed;
+        }
+        return {
+            ...transformed,
+            schema: IdentifierNode.create(this.#schema),
+        };
+    }
+    transformReferences(node, queryId) {
+        const transformed = super.transformReferences(node, queryId);
+        if (transformed.table.table.schema) {
+            return transformed;
+        }
+        return {
+            ...transformed,
+            table: TableNode.createWithSchema(this.#schema, transformed.table.table.identifier.name),
+        };
+    }
+    transformAggregateFunction(node, queryId) {
+        return {
+            ...super.transformAggregateFunction({ ...node, aggregated: [] }, queryId),
+            aggregated: this.#transformTableArgsWithoutSchemas(node, queryId, 'aggregated'),
+        };
+    }
+    transformFunction(node, queryId) {
+        return {
+            ...super.transformFunction({ ...node, arguments: [] }, queryId),
+            arguments: this.#transformTableArgsWithoutSchemas(node, queryId, 'arguments'),
+        };
+    }
+    transformSelectModifier(node, queryId) {
+        return {
+            ...super.transformSelectModifier({ ...node, of: undefined }, queryId),
+            of: node.of?.map((item) => TableNode.is(item) && !item.table.schema
+                ? {
+                    ...item,
+                    table: this.transformIdentifier(item.table.identifier, queryId),
+                }
+                : this.transformNode(item, queryId)),
+        };
+    }
+    #transformTableArgsWithoutSchemas(node, queryId, argsKey) {
+        return SCHEMALESS_FUNCTIONS[node.func]
+            ? node[argsKey].map((arg) => !TableNode.is(arg) || arg.table.schema
+                ? this.transformNode(arg, queryId)
+                : {
+                    ...arg,
+                    table: this.transformIdentifier(arg.table.identifier, queryId),
+                })
+            : this.transformNodeList(node[argsKey], queryId);
+    }
+    #collectSchemableIds(node) {
+        const schemableIds = new Set();
+        if ('name' in node && node.name && SchemableIdentifierNode.is(node.name)) {
+            this.#collectSchemableId(node.name, schemableIds);
+        }
+        if ('from' in node && node.from) {
+            for (const from of node.from.froms) {
+                this.#collectSchemableIdsFromTableExpr(from, schemableIds);
+            }
+        }
+        if ('into' in node && node.into) {
+            this.#collectSchemableIdsFromTableExpr(node.into, schemableIds);
+        }
+        if ('table' in node && node.table) {
+            this.#collectSchemableIdsFromTableExpr(node.table, schemableIds);
+        }
+        if ('joins' in node && node.joins) {
+            for (const join of node.joins) {
+                this.#collectSchemableIdsFromTableExpr(join.table, schemableIds);
+            }
+        }
+        if ('using' in node && node.using) {
+            if (JoinNode.is(node.using)) {
+                this.#collectSchemableIdsFromTableExpr(node.using.table, schemableIds);
+            }
+            else {
+                this.#collectSchemableIdsFromTableExpr(node.using, schemableIds);
+            }
+        }
+        return schemableIds;
+    }
+    #collectCTEs(node) {
+        const ctes = new Set();
+        if ('with' in node && node.with) {
+            this.#collectCTEIds(node.with, ctes);
+        }
+        return ctes;
+    }
+    #collectSchemableIdsFromTableExpr(node, schemableIds) {
+        if (TableNode.is(node)) {
+            return this.#collectSchemableId(node.table, schemableIds);
+        }
+        if (AliasNode.is(node) && TableNode.is(node.node)) {
+            return this.#collectSchemableId(node.node.table, schemableIds);
+        }
+        if (ListNode.is(node)) {
+            for (const table of node.items) {
+                this.#collectSchemableIdsFromTableExpr(table, schemableIds);
+            }
+            return;
+        }
+        if (UsingNode.is(node)) {
+            for (const table of node.tables) {
+                this.#collectSchemableIdsFromTableExpr(table, schemableIds);
+            }
+            return;
+        }
+    }
+    #collectSchemableId(node, schemableIds) {
+        const id = node.identifier.name;
+        if (!this.#schemableIds.has(id) && !this.#ctes.has(id)) {
+            schemableIds.add(id);
+        }
+    }
+    #collectCTEIds(node, ctes) {
+        for (const expr of node.expressions) {
+            const cteId = expr.name.table.table.identifier.name;
+            if (!this.#ctes.has(cteId)) {
+                ctes.add(cteId);
+            }
+        }
+    }
+}