kysely 0.28.17 → 0.29.0

package/dist/util/abort.js

@@ -0,0 +1,76 @@
+/// <reference types="./abort.d.ts" />
+import { Deferred } from './deferred.js';
+import { getMessage } from './object-utils.js';
+export function getInflightQueryAbortHandler(abortStrategy = 'ignore query', connection, beforeThrow) {
+    if (abortStrategy === 'ignore query') {
+        return;
+    }
+    if (abortStrategy === 'cancel query') {
+        const handler = connection.cancelQuery;
+        if (!handler) {
+            throwUnsupportedInflightQueryAbortStrategyError(abortStrategy, connection.killSession ? 'kill session' : undefined);
+        }
+        return handler.bind(connection);
+    }
+    if (abortStrategy === 'kill session') {
+        const handler = connection.killSession;
+        if (!handler) {
+            throwUnsupportedInflightQueryAbortStrategyError(abortStrategy, connection.cancelQuery ? 'cancel query' : undefined);
+        }
+        return handler.bind(connection);
+    }
+    beforeThrow();
+    throw new Error(`Unexpected \`inflightQueryAbortStrategy\`: "${abortStrategy}"`);
+}
+function throwUnsupportedInflightQueryAbortStrategyError(abortStrategy, alt) {
+    throw new Error(`This dialect doesn't support \`inflightQueryAbortStrategy\` "${abortStrategy}". Use "${'ignore query'}"${alt ? ` or "${alt}"` : ''} instead.`);
+}
+export function assertNotAborted(signal, timing, beforeThrow) {
+    if (signal?.aborted) {
+        beforeThrow?.();
+        throwReasonWithTiming(signal.reason, timing);
+    }
+}
+export function throwReasonWithTiming(reason, timing) {
+    decorateWithTiming(reason, timing);
+    throw reason;
+}
+export const ABORTED = {};
+export async function waitOrAbort(promise, signal, name, onAbort) {
+    if (!signal) {
+        return promise;
+    }
+    assertNotAborted(signal, `before ${name}`, onAbort);
+    const { promise: abortPromise, resolve } = new Deferred();
+    const abortListener = () => resolve(ABORTED);
+    signal.addEventListener('abort', abortListener);
+    try {
+        assertNotAborted(signal, `before ${name}`, onAbort);
+        const result = await Promise.race([promise, abortPromise]);
+        if (result !== ABORTED) {
+            return result;
+        }
+        onAbort?.();
+        throwReasonWithTiming(signal.reason, `during ${name}`);
+    }
+    finally {
+        signal.removeEventListener('abort', abortListener);
+        resolve(ABORTED);
+    }
+}
+export function printBackgroundFail(name) {
+    return (reason) => console.error(`\`${name}\` failed in the background after abortion: ${getMessage(reason)}`);
+}
+function decorateWithTiming(reason, timing) {
+    if (reason !== null &&
+        typeof reason === 'object' &&
+        !Object.isFrozen(reason)) {
+        // we use this in tests, but it can also be used to debug in userland.
+        Object.defineProperty(reason, '__kysely_timing__', {
+            configurable: true,
+            enumerable: false,
+            value: timing,
+            writable: false,
+        });
+    }
+}

package/dist/util/column-type.d.ts

@@ -0,0 +1,229 @@
+import type { DrainOuterGeneric, IsNever, IsNullable } from './type-utils.js';
+/**
+ * This type can be used to specify a different type for
+ * select, insert and update operations.
+ *
+ * Also see the {@link Generated} type.
+ *
+ * ### Examples
+ *
+ * The next example defines a number column that is optional
+ * in inserts and updates. All columns are always optional
+ * in updates so therefore we don't need to specify `undefined`
+ * for the update type. The type below is useful for all kinds of
+ * database generated columns like identifiers. The `Generated`
+ * type is actually just a shortcut for the type in this example:
+ *
+ * ```ts
+ * type GeneratedNumber = ColumnType<number, number | undefined, number>
+ * ```
+ *
+ * The above example makes the column optional in inserts
+ * and updates, but you can still choose to provide the
+ * column. If you want to prevent insertion/update you
+ * can se the type as `never`:
+ *
+ * ```ts
+ * type ReadonlyNumber = ColumnType<number, never, never>
+ * ```
+ *
+ * Here's one more example where the type is different
+ * for each different operation:
+ *
+ * ```ts
+ * type UnupdateableDate = ColumnType<Date, string, never>
+ * ```
+ */
+export type ColumnType<SelectType, InsertType = SelectType, UpdateType = SelectType> = {
+    readonly __select__: SelectType;
+    readonly __insert__: InsertType;
+    readonly __update__: UpdateType;
+};
+/**
+ * A shortcut for defining database-generated columns. The type
+ * is the same for all selects, inserts and updates but the
+ * column is optional for inserts and updates.
+ *
+ * The update type is `S` instead of `S | undefined` because updates are always
+ * optional --> no need to specify optionality.
+ * ```
+ */
+export type Generated<S> = ColumnType<S, S | undefined, S>;
+/**
+ * A shortcut for defining columns that are only database-generated
+ * (like postgres GENERATED ALWAYS AS IDENTITY). No insert/update
+ * is allowed.
+ */
+export type GeneratedAlways<S> = ColumnType<S, never, never>;
+/**
+ * A shortcut for defining JSON columns, which are by default inserted/updated
+ * as stringified JSON strings.
+ */
+export type JSONColumnType<SelectType extends object | null, InsertType = string, UpdateType = string> = ColumnType<SelectType, InsertType, UpdateType>;
+/**
+ * Evaluates to `K` if `T` can be `null` or `undefined`.
+ */
+type IfNullable<T, K> = IsNullable<T> extends true ? K : never;
+/**
+ * Evaluates to `K` if `T` can't be `null` or `undefined`.
+ */
+type IfNotNullable<T, K> = IsNullable<T> extends true ? never : IfNotNever<T, K>;
+/**
+ * Evaluates to `K` if `T` isn't `never`.
+ */
+type IfNotNever<T, K> = IsNever<T> extends true ? never : K;
+export type SelectType<T> = T extends ColumnType<infer S, any, any> ? S : T;
+export type InsertType<T> = T extends ColumnType<any, infer I, any> ? I : T;
+export type UpdateType<T> = T extends ColumnType<any, any, infer U> ? U : T;
+/**
+ * Keys of `R` whose `InsertType` values can be `null` or `undefined`.
+ */
+export type NullableInsertKeys<R> = {
+    [K in keyof R]: IfNullable<InsertType<R[K]>, K>;
+}[keyof R];
+/**
+ * Keys of `R` whose `InsertType` values can't be `null` or `undefined`.
+ */
+export type NonNullableInsertKeys<R> = {
+    [K in keyof R]: IfNotNullable<InsertType<R[K]>, K>;
+}[keyof R];
+/**
+ * Keys of `R` whose `SelectType` values are not `never`
+ */
+type NonNeverSelectKeys<R> = {
+    [K in keyof R]: IfNotNever<SelectType<R[K]>, K>;
+}[keyof R];
+/**
+ * Keys of `R` whose `UpdateType` values are not `never`
+ */
+export type UpdateKeys<R> = {
+    [K in keyof R]: IfNotNever<UpdateType<R[K]>, K>;
+}[keyof R];
+/**
+ * Given a table interface, extracts the select type from all
+ * {@link ColumnType} types.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * interface PersonTable {
+ *   id: Generated<number>
+ *   first_name: string
+ *   modified_at: ColumnType<Date, string, never>
+ * }
+ *
+ * type Person = Selectable<PersonTable>
+ * // {
+ * //   id: number,
+ * //   first_name: string
+ * //   modified_at: Date
+ * // }
+ * ```
+ */
+export type Selectable<R> = DrainOuterGeneric<{
+    [K in NonNeverSelectKeys<R>]: SelectType<R[K]>;
+}>;
+/**
+ * Given a table interface, extracts the insert type from all
+ * {@link ColumnType} types.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * interface PersonTable {
+ *   id: Generated<number>
+ *   first_name: string
+ *   modified_at: ColumnType<Date, string, never>
+ * }
+ *
+ * type InsertablePerson = Insertable<PersonTable>
+ * // {
+ * //   id?: number,
+ * //   first_name: string
+ * //   modified_at: string
+ * // }
+ * ```
+ */
+export type Insertable<R> = DrainOuterGeneric<object & {
+    [K in NonNullableInsertKeys<R>]: InsertType<R[K]>;
+} & {
+    [K in NullableInsertKeys<R>]?: InsertType<R[K]>;
+}>;
+/**
+ * Given a table interface, extracts the update type from all
+ * {@link ColumnType} types.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * interface PersonTable {
+ *   id: Generated<number>
+ *   first_name: string
+ *   modified_at: ColumnType<Date, string, never>
+ * }
+ *
+ * type UpdateablePerson = Updateable<PersonTable>
+ * // {
+ * //   id?: number,
+ * //   first_name?: string
+ * // }
+ * ```
+ */
+export type Updateable<R> = DrainOuterGeneric<{
+    [K in UpdateKeys<R>]?: UpdateType<R[K]> | undefined;
+}>;
+/**
+ * Wrap your column type to opt-out from dehydration by {@link ShallowDehydrateValue},
+ * when used by JSON functions, such as the ones used by the relational helpers.
+ *
+ * Why need this?
+ *
+ * An edge case surfaced in issues where a numeric string column type was actually
+ * not a numeric data type column, but text - and thus shouldn't be dehydrated
+ * to `number`.
+ *
+ * Another use case would be, when someone finds a way to keep nested columns hydrated
+ * at runtime, e.g. via a plugin, and wants to prevent dehydration of such columns
+ * at the type level.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * import type { NonDehydrateable } from 'kysely'
+ * import { jsonArrayFrom } from 'kysely/helpers/postgres'
+ *
+ * const result = await db
+ *   .withTables<{
+ *     my_table: {
+ *       a_column: '1' | '2' | '3',
+ *       another_column: NonDehydrateable<'1' | '2' | '3'>,
+ *       column_too: NonDehydrateable<ColumnType<'1' | '2' | '3'>>
+ *     }
+ *   }>()
+ *   .selectFrom('person')
+ *   .select((eb) => [
+ *     'id',
+ *     jsonArrayFrom(
+ *       eb.selectFrom('my_table')
+ *         .select(['a_column', 'another_column', 'column_too'])
+ *     ).as('related')
+ *   ])
+ *   .execute()
+ * ```
+ *
+ * In the example above, "a_column" will be dehydrated to `number`
+ * given it is a numeric string - which is normally a numeric data type column
+ * that gets output as a string by underlying database drivers to avoid
+ * precision loss or overflow.
+ *
+ * "another_column" and "column_too" will remain as `'1' | '2' | '3'`, given they're
+ * wrapped in `NonDehydrateable`, which prevents their dehydration.
+ */
+export type NonDehydrateable<T> = [T] extends [
+    ColumnType<infer S, infer I, infer U>
+] ? ColumnType<S & {
+    __kysely_dehydrate__?: false;
+}, I, U> : T & {
+    __kysely_dehydrate__?: false;
+};
+export {};

package/dist/util/deferred.js

@@ -0,0 +1,23 @@
+/// <reference types="./deferred.d.ts" />
+export class Deferred {
+    #promise;
+    #resolve;
+    #reject;
+    constructor() {
+        this.#promise = new Promise((resolve, reject) => {
+            this.#reject = reject;
+            this.#resolve = resolve;
+        });
+    }
+    get promise() {
+        return this.#promise;
+    }
+    resolve = (value) => {
+        this.#resolve?.(value);
+        this.#resolve = this.#reject = undefined;
+    };
+    reject = (reason) => {
+        this.#reject?.(reason);
+        this.#reject = this.#resolve = undefined;
+    };
+}

package/dist/util/executable.d.ts

@@ -0,0 +1,35 @@
+import type { QueryNode } from '../operation-node/query-node.js';
+import type { NoResultErrorConstructor } from '../query-builder/no-result-error.js';
+import type { AbortableQueryOptions } from './abort.js';
+import type { SimplifyResult, SimplifySingleResult } from './type-utils.js';
+export interface Executable<O> {
+    /**
+     * Executes the query and returns an array of rows.
+     *
+     * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
+     */
+    execute(options?: AbortableQueryOptions): Promise<SimplifyResult<O>[]>;
+    /**
+     * Executes the query and returns the first result or undefined if
+     * the query returned no result.
+     */
+    executeTakeFirst(options?: AbortableQueryOptions): Promise<SimplifySingleResult<O>>;
+    /**
+     * Executes the query and returns the first result or throws if
+     * the query returned no result.
+     *
+     * By default an instance of {@link NoResultError} is thrown, but you can
+     * provide a custom error class, or callback to throw a different
+     * error.
+     */
+    executeTakeFirstOrThrow(options?: ExecuteTakeFirstOrThrowOptions | ExecuteTakeFirstOrThrowOptions['errorConstructor']): Promise<SimplifyResult<O>>;
+}
+export interface ExecuteTakeFirstOrThrowOptions extends AbortableQueryOptions {
+    /**
+     * An optional error constructor that is used to create an error
+     * when the query returns no results.
+     *
+     * By default, an instance of {@link NoResultError} is thrown.
+     */
+    errorConstructor?: NoResultErrorConstructor | ((node: QueryNode) => Error);
+}

package/dist/util/executable.js

@@ -0,0 +1,2 @@
+/// <reference types="./executable.d.ts" />
+export {};

package/dist/util/object-utils.d.ts

@@ -0,0 +1,24 @@
+import type { ShallowRecord } from './type-utils.js';
+export declare function isEmpty(obj: ArrayLike<unknown> | string | object): boolean;
+export declare function isUndefined(obj: unknown): obj is undefined;
+export declare function isString(obj: unknown): obj is string;
+export declare function isNumber(obj: unknown): obj is number;
+export declare function isBoolean(obj: unknown): obj is boolean;
+export declare function isNull(obj: unknown): obj is null;
+export declare function isDate(obj: unknown): obj is Date;
+export declare function isBigInt(obj: unknown): obj is bigint;
+export declare function isBuffer(obj: unknown): obj is {
+    length: number;
+};
+export declare function isFunction(obj: unknown): obj is Function;
+export declare function isObject(obj: unknown): obj is ShallowRecord<string, unknown>;
+export declare function isArrayBufferOrView(obj: unknown): obj is ArrayBuffer | ArrayBufferView;
+export declare function isPlainObject(obj: unknown): obj is Record<string, unknown>;
+export declare function getLast<T>(arr: ArrayLike<T>): T | undefined;
+export declare function freeze<T>(obj: T): Readonly<T>;
+export declare function asArray<T>(arg: T | ReadonlyArray<T>): ReadonlyArray<T>;
+export declare function asReadonlyArray<T>(arg: T | ReadonlyArray<T>): ReadonlyArray<T>;
+export declare function isReadonlyArray(arg: unknown): arg is ReadonlyArray<unknown>;
+export declare function noop<T>(obj: T): T;
+export declare function compare(obj1: unknown, obj2: unknown): boolean;
+export declare function getMessage(error: unknown): string;

package/dist/util/object-utils.js

@@ -0,0 +1,144 @@
+/// <reference types="./object-utils.d.ts" />
+export function isEmpty(obj) {
+    if (Array.isArray(obj) || isString(obj) || isBuffer(obj)) {
+        return obj.length === 0;
+    }
+    else if (obj) {
+        return Object.keys(obj).length === 0;
+    }
+    return false;
+}
+export function isUndefined(obj) {
+    return typeof obj === 'undefined' || obj === undefined;
+}
+export function isString(obj) {
+    return typeof obj === 'string';
+}
+export function isNumber(obj) {
+    return typeof obj === 'number';
+}
+export function isBoolean(obj) {
+    return typeof obj === 'boolean';
+}
+export function isNull(obj) {
+    return obj === null;
+}
+export function isDate(obj) {
+    return obj instanceof Date;
+}
+export function isBigInt(obj) {
+    return typeof obj === 'bigint';
+}
+// Don't change the returnd type to `obj is Buffer` to not create a
+// hard dependency to node.
+export function isBuffer(obj) {
+    return typeof Buffer !== 'undefined' && Buffer.isBuffer(obj);
+}
+export function isFunction(obj) {
+    return typeof obj === 'function';
+}
+export function isObject(obj) {
+    return typeof obj === 'object' && obj !== null;
+}
+export function isArrayBufferOrView(obj) {
+    return obj instanceof ArrayBuffer || ArrayBuffer.isView(obj);
+}
+export function isPlainObject(obj) {
+    if (!isObject(obj) || getTag(obj) !== '[object Object]') {
+        return false;
+    }
+    if (Object.getPrototypeOf(obj) === null) {
+        return true;
+    }
+    let proto = obj;
+    while (Object.getPrototypeOf(proto) !== null) {
+        proto = Object.getPrototypeOf(proto);
+    }
+    return Object.getPrototypeOf(obj) === proto;
+}
+export function getLast(arr) {
+    return arr[arr.length - 1];
+}
+export function freeze(obj) {
+    return Object.freeze(obj);
+}
+export function asArray(arg) {
+    if (isReadonlyArray(arg)) {
+        return arg;
+    }
+    else {
+        return [arg];
+    }
+}
+export function asReadonlyArray(arg) {
+    if (isReadonlyArray(arg)) {
+        return arg;
+    }
+    else {
+        return freeze([arg]);
+    }
+}
+export function isReadonlyArray(arg) {
+    return Array.isArray(arg);
+}
+export function noop(obj) {
+    return obj;
+}
+export function compare(obj1, obj2) {
+    if (isReadonlyArray(obj1) && isReadonlyArray(obj2)) {
+        return compareArrays(obj1, obj2);
+    }
+    else if (isObject(obj1) && isObject(obj2)) {
+        return compareObjects(obj1, obj2);
+    }
+    return obj1 === obj2;
+}
+export function getMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function compareArrays(arr1, arr2) {
+    if (arr1.length !== arr2.length) {
+        return false;
+    }
+    for (let i = 0; i < arr1.length; ++i) {
+        if (!compare(arr1[i], arr2[i])) {
+            return false;
+        }
+    }
+    return true;
+}
+function compareObjects(obj1, obj2) {
+    if (isBuffer(obj1) && isBuffer(obj2)) {
+        return compareBuffers(obj1, obj2);
+    }
+    else if (isDate(obj1) && isDate(obj2)) {
+        return compareDates(obj1, obj2);
+    }
+    return compareGenericObjects(obj1, obj2);
+}
+function compareBuffers(buf1, buf2) {
+    return Buffer.compare(buf1, buf2) === 0;
+}
+function compareDates(date1, date2) {
+    return date1.getTime() === date2.getTime();
+}
+function compareGenericObjects(obj1, obj2) {
+    const keys1 = Object.keys(obj1);
+    const keys2 = Object.keys(obj2);
+    if (keys1.length !== keys2.length) {
+        return false;
+    }
+    for (const key of keys1) {
+        if (!compare(obj1[key], obj2[key])) {
+            return false;
+        }
+    }
+    return true;
+}
+const toString = Object.prototype.toString;
+function getTag(value) {
+    if (value == null) {
+        return value === undefined ? '[object Undefined]' : '[object Null]';
+    }
+    return toString.call(value);
+}

package/dist/util/provide-controlled-connection.d.ts

@@ -0,0 +1,8 @@
+import type { ConnectionProvider } from '../driver/connection-provider.js';
+import type { DatabaseConnection } from '../driver/database-connection.js';
+import type { AbortableOperationOptions } from './abort.js';
+export interface ControlledConnection {
+    readonly connection: DatabaseConnection;
+    readonly release: () => void;
+}
+export declare function provideControlledConnection(connectionProvider: ConnectionProvider, options?: AbortableOperationOptions): Promise<ControlledConnection>;

package/dist/util/provide-controlled-connection.js

@@ -0,0 +1,22 @@
+/// <reference types="./provide-controlled-connection.d.ts" />
+import { Deferred } from './deferred.js';
+import { freeze } from './object-utils.js';
+export async function provideControlledConnection(connectionProvider, options) {
+    const connectionDefer = new Deferred();
+    const connectionReleaseDefer = new Deferred();
+    void connectionProvider
+        .provideConnection(async (connection) => {
+        connectionDefer.resolve(connection);
+        return await connectionReleaseDefer.promise;
+    }, options)
+        .catch((ex) => connectionDefer.reject(ex));
+    // Create composite of the connection and the release method instead of
+    // modifying the connection or creating a new nesting `DatabaseConnection`.
+    // This way we don't accidentally override any methods of 3rd party
+    // connections and don't return wrapped connections to drivers that
+    // expect a certain specific connection class.
+    return freeze({
+        connection: await connectionDefer.promise,
+        release: connectionReleaseDefer.resolve,
+    });
+}

package/dist/util/streamable.d.ts

@@ -0,0 +1,38 @@
+import type { AbortableOperationOptions } from './abort.js';
+export interface Streamable<O> {
+    /**
+     * Executes the query and streams the rows.
+     *
+     * The optional argument `chunkSize` defines how many rows to fetch from the database
+     * at a time. It only affects some dialects like PostgreSQL that support it.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const stream = db
+     *   .selectFrom('person')
+     *   .select(['first_name', 'last_name'])
+     *   .where('gender', '=', 'other')
+     *   .stream()
+     *
+     * for await (const person of stream) {
+     *   console.log(person.first_name)
+     *
+     *   if (person.last_name === 'Something') {
+     *     // Breaking or returning before the stream has ended will release
+     *     // the database connection and invalidate the stream.
+     *     break
+     *   }
+     * }
+     * ```
+     */
+    stream(chunkSizeOrOptions?: StreamOptions | StreamOptions['chunkSize']): AsyncIterableIterator<O>;
+}
+export interface StreamOptions extends AbortableOperationOptions {
+    /**
+     * How many rows should be pulled from the database at once.
+     *
+     * Supported only by some dialects like PostgreSQL.
+     */
+    chunkSize?: number;
+}