kysely 0.23.4 → 0.24.0

package/dist/esm/expression/expression-builder.d.ts

@@ -0,0 +1,386 @@
+import { SelectQueryBuilder } from '../query-builder/select-query-builder.js';
+import { TableExpression, From, FromTables, ExtractTableAlias, AnyAliasedTable, PickTableWithAlias } from '../parser/table-parser.js';
+import { FunctionModule } from '../query-builder/function-module.js';
+import { ExtractTypeFromReferenceExpression, ReferenceExpression, StringReference } from '../parser/reference-parser.js';
+import { QueryExecutor } from '../query-executor/query-executor.js';
+import { BinaryOperatorExpression, ComparisonOperatorExpression, OperandValueExpression, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
+import { Expression } from './expression.js';
+import { ExpressionWrapper } from './expression-wrapper.js';
+import { ComparisonOperator, UnaryOperator } from '../operation-node/operator-node.js';
+import { SqlBool } from '../util/type-utils.js';
+import { ExtractTypeFromValueExpressionOrList } from '../parser/value-parser.js';
+export interface ExpressionBuilder<DB, TB extends keyof DB> {
+    /**
+     * Returns a {@link FunctionModule} that can be used to write type safe function
+     * calls.
+     *
+     * The difference between this and {@link Kysely.fn} is that this one is more
+     * type safe. You can only refer to columns visible to the part of the query
+     * you are building. {@link Kysely.fn} allows you to refer to columns in any
+     * table of the database even if it doesn't produce valid SQL.
+     *
+     * ```ts
+     * await db.selectFrom('person')
+     *   .innerJoin('pet', 'pet.owner_id', 'person.id')
+     *   .select((eb) => [
+     *     'person.id',
+     *     eb.fn.count('pet.id').as('pet_count')
+     *   ])
+     *   .groupBy('person.id')
+     *   .having(count('pet.id'), '>', 10)
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."id", count("pet"."id") as "pet_count"
+     * from "person"
+     * inner join "pet" on "pet"."owner_id" = "person"."id"
+     * group by "person"."id"
+     * having count("pet"."id") > $1
+     * ```
+     */
+    get fn(): FunctionModule<DB, TB>;
+    /**
+     * Creates a subquery.
+     *
+     * The query builder returned by this method is typed in a way that you can refer to
+     * all tables of the parent query in addition to the subquery's tables.
+     *
+     * This method accepts all the same inputs as {@link QueryCreator.selectFrom}.
+     *
+     * ### Examples
+     *
+     * This example shows that you can refer to both `pet.owner_id` and `person.id`
+     * columns from the subquery. This is needed to be able to create correlated
+     * subqueries:
+     *
+     * ```ts
+     * const result = await db.selectFrom('pet')
+     *   .select((eb) => [
+     *     'pet.name',
+     *     eb.selectFrom('person')
+     *       .whereRef('person.id', '=', 'pet.owner_id')
+     *       .select('person.first_name')
+     *       .as('owner_name')
+     *   ])
+     *   .execute()
+     *
+     * console.log(result[0].owner_name)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select
+     *   "pet"."name",
+     *   ( select "person"."first_name"
+     *     from "person"
+     *     where "person"."id" = "pet"."owner_id"
+     *   ) as "owner_name"
+     * from "pet"
+     * ```
+     *
+     * You can use a normal query in place of `(qb) => qb.selectFrom(...)` but in
+     * that case Kysely typings wouldn't allow you to reference `pet.owner_id`
+     * because `pet` is not joined to that query.
+     */
+    selectFrom<TE extends keyof DB & string>(from: TE[]): SelectQueryBuilder<DB, TB | ExtractTableAlias<DB, TE>, {}>;
+    selectFrom<TE extends TableExpression<DB, TB>>(from: TE[]): SelectQueryBuilder<From<DB, TE>, FromTables<DB, TB, TE>, {}>;
+    selectFrom<TE extends keyof DB & string>(from: TE): SelectQueryBuilder<DB, TB | ExtractTableAlias<DB, TE>, {}>;
+    selectFrom<TE extends AnyAliasedTable<DB>>(from: TE): SelectQueryBuilder<DB & PickTableWithAlias<DB, TE>, TB | ExtractTableAlias<DB, TE>, {}>;
+    selectFrom<TE extends TableExpression<DB, TB>>(from: TE): SelectQueryBuilder<From<DB, TE>, FromTables<DB, TB, TE>, {}>;
+    /**
+     * This can be used to reference columns.
+     *
+     * ### Examples
+     *
+     * By default the third argument of {@link bxp} and {@link cmpr} is a value.
+     * This function can be used to pass in a column reference instead:
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .selectAll('person')
+     *   .where(({ or, cmpr, ref }) => or([
+     *     cmpr('first_name', '=', ref('last_name')),
+     *     cmpr('first_name', '=', ref('middle_name'))
+     *   ]))
+     * ```
+     *
+     * In the next example we use the `ref` method to reference
+     * columns of the virtual table `excluded` in a type-safe way
+     * to create an upsert operation:
+     *
+     * ```ts
+     * db.insertInto('person')
+     *   .values(person)
+     *   .onConflict((oc) => oc
+     *     .column('id')
+     *     .doUpdateSet(({ ref }) => ({
+     *       first_name: ref('excluded.first_name'),
+     *       last_name: ref('excluded.last_name')
+     *     }))
+     *   )
+     * ```
+     *
+     * In the next example we use `ref` in a raw sql expression. Unless you
+     * want to be as type-safe as possible, this is probably overkill:
+     *
+     * ```ts
+     * db.update('pet').set((eb) => ({
+     *   name: sql`concat(${eb.ref('pet.name')}, ${suffix})`
+     * }))
+     * ```
+     */
+    ref<RE extends StringReference<DB, TB>>(reference: RE): ExpressionWrapper<ExtractTypeFromReferenceExpression<DB, TB, RE>>;
+    /**
+     * Returns a value expression.
+     *
+     * This can be used to pass in a value where a reference is taken by default.
+     *
+     * This function returns an {@link Expression} and can be used pretty much anywhere.
+     *
+     * ### Examples
+     *
+     * The {@link cmpr} function takes a reference by default as the first argument. `val` could
+     * be used to pass in a value instead:
+     *
+     * ```ts
+     * cmpr(val(38), '=', ref('age'))
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * $1 = "age"
+     * ```
+     */
+    val<VE>(value: VE): ExpressionWrapper<ExtractTypeFromValueExpressionOrList<VE>>;
+    /**
+     * Creates a binary comparison expression.
+     *
+     * This function returns an {@link Expression} and can be used pretty much anywhere.
+     * See the examples for a couple of possible use cases.
+     *
+     * @see {@link bxp}
+     *
+     * ### Examples
+     *
+     * In this example we use `cmpr` and {@link or} to create a `WHERE expr1 OR expr2 OR expr3`
+     * statement:
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .selectAll('person')
+     *   .where(({ or, cmpr }) => or([
+     *     cmpr('first_name', '=', 'Jennifer'),
+     *     cmpr('fist_name', '=', 'Arnold'),
+     *     cmpr('fist_name', '=', 'Sylvester')
+     *   ]))
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person".*
+     * from "person"
+     * where "first_name" = $1
+     * or "first_name" = $2
+     * or "first_name" = $3
+     * ```
+     *
+     * By default the third argument is a value. {@link ref} can be used to
+     * pass in a column reference instead:
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .selectAll('person')
+     *   .where(({ or, cmpr, ref }) => or([
+     *     cmpr('first_name', '=', ref('last_name')),
+     *     cmpr('first_name', '=', ref('middle_name'))
+     *   ]))
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person".*
+     * from "person"
+     * where "first_name" = "last_name"
+     * or "first_name" = "middle_name"
+     * ```
+     */
+    cmpr<O extends SqlBool = SqlBool, RE extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): ExpressionWrapper<O>;
+    /**
+     * Creates a binary expression.
+     *
+     * See {@link cmpr} for creating binary comparison operations.
+     *
+     * This function returns an {@link Expression} and can be used pretty much anywhere.
+     * See the examples for a couple of possible use cases.
+     *
+     * ### Examples
+     *
+     * In the following example `bxp` is used to increment an integer column:
+     *
+     * ```ts
+     * db.updateTable('person')
+     *   .set((eb) => ({
+     *     age: eb.bxp('age', '+', 1)
+     *   }))
+     *   .where('id', '=', id)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * update "person"
+     * set "age" = "age" + $1
+     * where "id" = $2
+     * ```
+     *
+     * By default the third argument is a value. {@link ref} can be used to
+     * pass in a column reference instead:
+     *
+     * ```ts
+     * db.updateTable('person')
+     *   .set((eb) => ({
+     *     age: eb.bxp('age', '+', eb.ref('age'))
+     *   }))
+     *   .where('id', '=', id)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * update "person"
+     * set "age" = "age" + "age"
+     * where "id" = $1
+     * ```
+     */
+    bxp<RE extends ReferenceExpression<DB, TB>, OP extends BinaryOperatorExpression>(lhs: RE, op: OP, rhs: OperandValueExpression<DB, TB, RE>): ExpressionWrapper<OP extends ComparisonOperator ? SqlBool : ExtractTypeFromReferenceExpression<DB, TB, RE>>;
+    /**
+     * Creates an unary expression.
+     *
+     * This function returns an {@link Expression} and can be used pretty much anywhere.
+     * See the examples for a couple of possible use cases.
+     *
+     * @see {@link not}, {@link exists} and {@link neg}.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select((eb) => [
+     *     'first_name',
+     *     eb.unary('-', 'age').as('negative_age')
+     *   ])
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "first_name", -"age"
+     * from "person"
+     * ```
+     */
+    unary<RE extends ReferenceExpression<DB, TB>>(op: UnaryOperator, expr: RE): ExpressionWrapper<ExtractTypeFromReferenceExpression<DB, TB, RE>>;
+    /**
+     * Creates a `not` operation.
+     *
+     * A shortcut for `unary('not', expr)`.
+     *
+     * @see {@link unary}
+     */
+    not<RE extends ReferenceExpression<DB, TB>>(expr: RE): ExpressionWrapper<ExtractTypeFromReferenceExpression<DB, TB, RE>>;
+    /**
+     * Creates an `exists` operation.
+     *
+     * A shortcut for `unary('exists', expr)`.
+     *
+     * @see {@link unary}
+     */
+    exists<RE extends ReferenceExpression<DB, TB>>(expr: RE): ExpressionWrapper<SqlBool>;
+    /**
+     * Creates a negation operation.
+     *
+     * A shortcut for `unary('-', expr)`.
+     *
+     * @see {@link unary}
+     */
+    neg<RE extends ReferenceExpression<DB, TB>>(expr: RE): ExpressionWrapper<ExtractTypeFromReferenceExpression<DB, TB, RE>>;
+    /**
+     * Combines two or more expressions using the logical `and` operator.
+     *
+     * This function returns an {@link Expression} and can be used pretty much anywhere.
+     * See the examples for a couple of possible use cases.
+     *
+     * ### Examples
+     *
+     * In this example we use `and` with {@link cmpr} to create a `WHERE expr1 AND expr2 AND expr3`
+     * statement:
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .selectAll('person')
+     *   .where(({ and, cmpr }) => and([
+     *     cmpr('first_name', '=', 'Jennifer'),
+     *     cmpr('fist_name', '=', 'Arnold'),
+     *     cmpr('fist_name', '=', 'Sylvester')
+     *   ]))
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person".*
+     * from "person"
+     * where "first_name" = $1
+     * and "first_name" = $2
+     * and "first_name" = $3
+     * ```
+     */
+    and(expres: ReadonlyArray<Expression<SqlBool>>): ExpressionWrapper<SqlBool>;
+    /**
+     * Combines two or more expressions using the logical `or` operator.
+     *
+     * This function returns an {@link Expression} and can be used pretty much anywhere.
+     * See the examples for a couple of possible use cases.
+     *
+     * ### Examples
+     *
+     * In this example we use `or` with {@link cmpr} to create a `WHERE expr1 OR expr2 OR expr3`
+     * statement:
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .selectAll('person')
+     *   .where(({ or, cmpr }) => or([
+     *     cmpr('first_name', '=', 'Jennifer'),
+     *     cmpr('fist_name', '=', 'Arnold'),
+     *     cmpr('fist_name', '=', 'Sylvester')
+     *   ]))
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person".*
+     * from "person"
+     * where "first_name" = $1
+     * or "first_name" = $2
+     * or "first_name" = $3
+     * ```
+     */
+    or(expres: ReadonlyArray<Expression<SqlBool>>): ExpressionWrapper<SqlBool>;
+    /**
+     * See {@link QueryCreator.withSchema}
+     *
+     * @deprecated Will be removed in kysely 0.25.0.
+     */
+    withSchema(schema: string): ExpressionBuilder<DB, TB>;
+}
+export declare function createExpressionBuilder<DB, TB extends keyof DB>(executor?: QueryExecutor): ExpressionBuilder<DB, TB>;
+export declare function expressionBuilder<DB, TB extends keyof DB>(_: SelectQueryBuilder<DB, TB, any>): ExpressionBuilder<DB, TB>;
+export declare function expressionBuilder<DB, TB extends keyof DB>(): ExpressionBuilder<DB, TB>;

package/dist/esm/expression/expression-builder.js

@@ -0,0 +1,88 @@
+/// <reference types="./expression-builder.d.ts" />
+import { SelectQueryBuilder } from '../query-builder/select-query-builder.js';
+import { SelectQueryNode } from '../operation-node/select-query-node.js';
+import { parseTableExpressionOrList, } from '../parser/table-parser.js';
+import { WithSchemaPlugin } from '../plugin/with-schema/with-schema-plugin.js';
+import { createQueryId } from '../util/query-id.js';
+import { createFunctionModule, } from '../query-builder/function-module.js';
+import { parseStringReference, } from '../parser/reference-parser.js';
+import { parseValueBinaryOperation, } from '../parser/binary-operation-parser.js';
+import { AndNode } from '../operation-node/and-node.js';
+import { OrNode } from '../operation-node/or-node.js';
+import { ParensNode } from '../operation-node/parens-node.js';
+import { ExpressionWrapper } from './expression-wrapper.js';
+import { parseUnaryOperation } from '../parser/unary-operation-parser.js';
+import { parseValueExpressionOrList, } from '../parser/value-parser.js';
+import { NOOP_QUERY_EXECUTOR } from '../query-executor/noop-query-executor.js';
+import { ValueNode } from '../operation-node/value-node.js';
+export function createExpressionBuilder(executor = NOOP_QUERY_EXECUTOR) {
+    function unary(op, expr) {
+        return new ExpressionWrapper(parseUnaryOperation(op, expr));
+    }
+    return {
+        get fn() {
+            return createFunctionModule();
+        },
+        selectFrom(table) {
+            return new SelectQueryBuilder({
+                queryId: createQueryId(),
+                executor: executor,
+                queryNode: SelectQueryNode.create(parseTableExpressionOrList(table)),
+            });
+        },
+        ref(reference) {
+            return new ExpressionWrapper(parseStringReference(reference));
+        },
+        val(value) {
+            return new ExpressionWrapper(parseValueExpressionOrList(value));
+        },
+        cmpr(lhs, op, rhs) {
+            return new ExpressionWrapper(parseValueBinaryOperation(lhs, op, rhs));
+        },
+        bxp(lhs, op, rhs) {
+            return new ExpressionWrapper(parseValueBinaryOperation(lhs, op, rhs));
+        },
+        unary,
+        not(expr) {
+            return unary('not', expr);
+        },
+        exists(expr) {
+            return unary('exists', expr);
+        },
+        neg(expr) {
+            return unary('-', expr);
+        },
+        and(exprs) {
+            if (exprs.length === 0) {
+                return new ExpressionWrapper(ValueNode.createImmediate(true));
+            }
+            else if (exprs.length === 1) {
+                return new ExpressionWrapper(exprs[0].toOperationNode());
+            }
+            let node = AndNode.create(exprs[0].toOperationNode(), exprs[1].toOperationNode());
+            for (let i = 2; i < exprs.length; ++i) {
+                node = AndNode.create(node, exprs[i].toOperationNode());
+            }
+            return new ExpressionWrapper(ParensNode.create(node));
+        },
+        or(exprs) {
+            if (exprs.length === 0) {
+                return new ExpressionWrapper(ValueNode.createImmediate(false));
+            }
+            else if (exprs.length === 1) {
+                return new ExpressionWrapper(exprs[0].toOperationNode());
+            }
+            let node = OrNode.create(exprs[0].toOperationNode(), exprs[1].toOperationNode());
+            for (let i = 2; i < exprs.length; ++i) {
+                node = OrNode.create(node, exprs[i].toOperationNode());
+            }
+            return new ExpressionWrapper(ParensNode.create(node));
+        },
+        withSchema(schema) {
+            return createExpressionBuilder(executor.withPluginAtFront(new WithSchemaPlugin(schema)));
+        },
+    };
+}
+export function expressionBuilder(_) {
+    return createExpressionBuilder();
+}

package/dist/esm/expression/expression-wrapper.d.ts

@@ -0,0 +1,92 @@
+import { AliasNode } from '../operation-node/alias-node.js';
+import { OperationNode } from '../operation-node/operation-node.js';
+import { AliasedExpression, Expression } from './expression.js';
+export declare class ExpressionWrapper<T> implements Expression<T> {
+    #private;
+    constructor(node: OperationNode);
+    /** @private */
+    /**
+     * 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:
+     *
+     * ```ts
+     * class SomeExpression<T> implements Expression<T> {
+     *   get expressionType(): T | undefined {
+     *     return undefined
+     *   }
+     * }
+     * ```
+     *
+     * The getter is needed to make the expression assignable to another expression only
+     * if the types `T` are assignable. Without this property (or some other property
+     * that references `T`), you could assing `Expression<string>` to `Expression<number>`.
+     */
+    get expressionType(): T | undefined;
+    /**
+     * Returns an aliased version of the expression.
+     *
+     * In addition to slapping `as "the_alias"` to the end of the SQL,
+     * this method also provides strict typing:
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select(eb =>
+     *     eb.cmpr('first_name', '=', 'Jennifer').as('is_jennifer')
+     *   )
+     *   .executeTakeFirstOrThrow()
+     *
+     * // `is_jennifer: SqlBool` field exists in the result type.
+     * console.log(result.is_jennifer)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```ts
+     * select "first_name" = $1 as "is_jennifer"
+     * from "person"
+     * ```
+     */
+    as<A extends string>(alias: A): AliasedExpression<T, A>;
+    as<A extends string>(alias: Expression<unknown>): AliasedExpression<T, A>;
+    /**
+     * Change the output type of the raw expression.
+     *
+     * This method call doesn't change the SQL in any way. This methods simply
+     * returns a copy of this `ExpressionWrapper` with a new output type.
+     */
+    $castTo<T>(): ExpressionWrapper<T>;
+    /**
+     * Creates the OperationNode that describes how to compile this expression into SQL.
+     *
+     * If you are creating a custom expression, it's often easiest to use the {@link sql}
+     * template tag to build the node:
+     *
+     * ```ts
+     * class SomeExpression<T> implements Expression<T> {
+     *   toOperationNode(): OperationNode {
+     *     return sql`some sql here`.toOperationNode()
+     *   }
+     * }
+     * ```
+     */
+    toOperationNode(): OperationNode;
+}
+export declare class AliasedExpressionWrapper<T, A extends string> implements AliasedExpression<T, A> {
+    #private;
+    constructor(expr: Expression<T>, alias: A | Expression<unknown>);
+    /** @private */
+    /**
+     * Returns the aliased expression.
+     */
+    get expression(): Expression<T>;
+    /** @private */
+    /**
+     * Returns the alias.
+     */
+    get alias(): A | Expression<unknown>;
+    /**
+     * Creates the OperationNode that describes how to compile this expression into SQL.
+     */
+    toOperationNode(): AliasNode;
+}

package/dist/esm/expression/expression-wrapper.js

@@ -0,0 +1,50 @@
+/// <reference types="./expression-wrapper.d.ts" />
+import { AliasNode } from '../operation-node/alias-node.js';
+import { IdentifierNode } from '../operation-node/identifier-node.js';
+import { isOperationNodeSource } from '../operation-node/operation-node-source.js';
+export class ExpressionWrapper {
+    #node;
+    constructor(node) {
+        this.#node = node;
+    }
+    /** @private */
+    get expressionType() {
+        return undefined;
+    }
+    as(alias) {
+        return new AliasedExpressionWrapper(this, alias);
+    }
+    /**
+     * Change the output type of the raw expression.
+     *
+     * This method call doesn't change the SQL in any way. This methods simply
+     * returns a copy of this `ExpressionWrapper` with a new output type.
+     */
+    $castTo() {
+        return new ExpressionWrapper(this.#node);
+    }
+    toOperationNode() {
+        return this.#node;
+    }
+}
+export class AliasedExpressionWrapper {
+    #expr;
+    #alias;
+    constructor(expr, alias) {
+        this.#expr = expr;
+        this.#alias = alias;
+    }
+    /** @private */
+    get expression() {
+        return this.#expr;
+    }
+    /** @private */
+    get alias() {
+        return this.#alias;
+    }
+    toOperationNode() {
+        return AliasNode.create(this.#expr.toOperationNode(), isOperationNodeSource(this.#alias)
+            ? this.#alias.toOperationNode()
+            : IdentifierNode.create(this.#alias));
+    }
+}

package/dist/esm/expression/expression.d.ts

@@ -90,7 +90,7 @@ export interface AliasedExpression<T, A extends string> extends OperationNodeSou
     /**
      * Returns the alias.
      */
-    get alias(): A;
+    get alias(): A | Expression<unknown>;
     /**
      * Creates the OperationNode that describes how to compile this expression into SQL.
      */