kysely 0.25.0 → 0.26.0

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

@@ -6,11 +6,82 @@ 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 { ComparisonOperator, JSONOperatorWith$, UnaryOperator } from '../operation-node/operator-node.js';
 import { SqlBool } from '../util/type-utils.js';
 import { ExtractTypeFromValueExpressionOrList } from '../parser/value-parser.js';
 import { CaseBuilder } from '../query-builder/case-builder.js';
+import { JSONPathBuilder } from '../query-builder/json-path-builder.js';
 export interface ExpressionBuilder<DB, TB extends keyof DB> {
+    /**
+     * Creates a binary expression.
+     *
+     * 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 `eb` is used to increment an integer column:
+     *
+     * ```ts
+     * db.updateTable('person')
+     *   .set((eb) => ({
+     *     age: eb('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('age', '+', eb.ref('age'))
+     *   }))
+     *   .where('id', '=', id)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * update "person"
+     * set "age" = "age" + "age"
+     * where "id" = $1
+     * ```
+     */
+    <RE extends ReferenceExpression<DB, TB>, OP extends BinaryOperatorExpression>(lhs: RE, op: OP, rhs: OperandValueExpressionOrList<DB, TB, RE>): ExpressionWrapper<DB, TB, OP extends ComparisonOperator ? SqlBool : ExtractTypeFromReferenceExpression<DB, TB, RE>>;
+    /**
+     * Returns a copy of `this` expression builder, for destructuring purposes.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .where(({ eb, exists, selectFrom }) =>
+     *     eb('first_name', '=', 'Jennifer').and(
+     *       exists(selectFrom('pet').whereRef('owner_id', '=', 'person.id').select('pet.id'))
+     *     )
+     *   )
+     *   .selectAll()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select * from "person" where "first_name" = $1 and exists (
+     *   select "pet.id" from "pet" where "owner_id" = "person.id"
+     * )
+     * ```
+     */
+    eb: ExpressionBuilder<DB, TB>;
     /**
      * Returns a {@link FunctionModule} that can be used to write type safe function
      * calls.
@@ -28,7 +99,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      *     eb.fn.count('pet.id').as('pet_count')
      *   ])
      *   .groupBy('person.id')
-     *   .having(count('pet.id'), '>', 10)
+     *   .having((eb) => eb.fn.count('pet.id'), '>', 10)
      *   .execute()
      * ```
      *
@@ -147,25 +218,28 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
     case<C extends SimpleReferenceExpression<DB, TB>>(column: C): CaseBuilder<DB, TB, ExtractTypeFromReferenceExpression<DB, TB, C>>;
     case<O>(expression: Expression<O>): CaseBuilder<DB, TB, O>;
     /**
-     * This can be used to reference columns.
+     * This method can be used to reference columns within the query's context. For
+     * a non-type-safe version of this method see {@link sql}'s version.
+     *
+     * Additionally, this method can be used to reference nested JSON properties or
+     * array elements. See {@link JSONPathBuilder} for more information.
      *
      * ### Examples
      *
-     * By default the third argument of {@link bxp} and {@link cmpr} is a value.
+     * By default the third argument of binary expressions 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'))
+     *   .where((eb) => eb.or([
+     *     eb('first_name', '=', eb.ref('last_name')),
+     *     eb('first_name', '=', eb.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:
+     * 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')
@@ -179,142 +253,126 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      *   )
      * ```
      *
-     * 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:
+     * 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.
+     * In the next example we use `ref` to reference a nested JSON property:
      *
-     * This function returns an {@link Expression} and can be used pretty much anywhere.
+     * ```ts
+     * db.selectFrom('person')
+     *   .where(({ cmpr, ref }) => cmpr(
+     *     ref('address', '->').key('state').key('abbr'),
+     *     '=',
+     *     'CA'
+     *   ))
+     *   .selectAll()
+     * ```
      *
-     * ### Examples
+     * The generated SQL (PostgreSQL):
      *
-     * The {@link cmpr} function takes a reference by default as the first argument. `val` could
-     * be used to pass in a value instead:
+     * ```sql
+     * select * from "person" where "address"->'state'->'abbr' = $1
+     * ```
+     *
+     * You can also compile to a JSON path expression by using the `->$`or `->>$` operator:
      *
      * ```ts
-     * cmpr(val(38), '=', ref('age'))
+     * db.selectFrom('person')
+     *   .select(({ ref }) =>
+     *     ref('experience', '->$')
+     *       .at('last')
+     *       .key('title')
+     *       .as('current_job')
+     *   )
      * ```
      *
-     * The generated SQL (PostgreSQL):
+     * The generated SQL (MySQL):
      *
      * ```sql
-     * $1 = "age"
+     * select `experience`->'$[last].title' as `current_job` from `person`
      * ```
      */
-    val<VE>(value: VE): ExpressionWrapper<ExtractTypeFromValueExpressionOrList<VE>>;
+    ref<RE extends StringReference<DB, TB>>(reference: RE): ExpressionWrapper<DB, TB, ExtractTypeFromReferenceExpression<DB, TB, RE>>;
+    ref<RE extends StringReference<DB, TB>>(reference: RE, op: JSONOperatorWith$): JSONPathBuilder<ExtractTypeFromReferenceExpression<DB, TB, RE>>;
     /**
-     * Creates a binary comparison expression.
+     * Returns a value expression.
      *
-     * This function returns an {@link Expression} and can be used pretty much anywhere.
-     * See the examples for a couple of possible use cases.
+     * This can be used to pass in a value where a reference is taken by default.
      *
-     * @see {@link bxp}
+     * This function returns an {@link Expression} and can be used pretty much anywhere.
      *
      * ### Examples
      *
-     * In this example we use `cmpr` and {@link or} to create a `WHERE expr1 OR expr2 OR expr3`
-     * statement:
+     * Binary expressions take a reference by default as the first argument. `val` could
+     * be used to pass in a value instead:
      *
      * ```ts
-     * db.selectFrom('person')
-     *   .selectAll('person')
-     *   .where(({ or, cmpr }) => or([
-     *     cmpr('first_name', '=', 'Jennifer'),
-     *     cmpr('fist_name', '=', 'Arnold'),
-     *     cmpr('fist_name', '=', 'Sylvester')
-     *   ]))
+     * eb(val(38), '=', ref('age'))
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * select "person".*
-     * from "person"
-     * where "first_name" = $1
-     * or "first_name" = $2
-     * or "first_name" = $3
+     * $1 = "age"
      * ```
+     */
+    val<VE>(value: VE): ExpressionWrapper<DB, TB, ExtractTypeFromValueExpressionOrList<VE>>;
+    /**
+     * @deprecated Use the expression builder as a function instead.
      *
-     * By default the third argument is a value. {@link ref} can be used to
-     * pass in a column reference instead:
+     * Before:
      *
      * ```ts
-     * db.selectFrom('person')
-     *   .selectAll('person')
-     *   .where(({ or, cmpr, ref }) => or([
-     *     cmpr('first_name', '=', ref('last_name')),
-     *     cmpr('first_name', '=', ref('middle_name'))
-     *   ]))
+     * where((eb) => eb.cmpr('first_name', '=', 'Jennifer'))
      * ```
      *
-     * The generated SQL (PostgreSQL):
+     * After:
      *
-     * ```sql
-     * select "person".*
-     * from "person"
-     * where "first_name" = "last_name"
-     * or "first_name" = "middle_name"
+     * ```ts
+     * where((eb) => eb('first_name', '=', 'Jennifer'))
      * ```
-     */
-    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:
+     * or
      *
      * ```ts
-     * db.updateTable('person')
-     *   .set((eb) => ({
-     *     age: eb.bxp('age', '+', 1)
-     *   }))
-     *   .where('id', '=', id)
+     * where(({ eb }) => eb('first_name', '=', 'Jennifer'))
      * ```
+     */
+    cmpr<O extends SqlBool = SqlBool, RE extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): ExpressionWrapper<DB, TB, O>;
+    /**
+     * @deprecated Use the expression builder as a function instead.
      *
-     * The generated SQL (PostgreSQL):
+     * Before:
      *
-     * ```sql
-     * update "person"
-     * set "age" = "age" + $1
-     * where "id" = $2
+     * ```ts
+     * set((eb) => ({
+     *   age: eb.bxp('age', '+', 10)
+     * }))
      * ```
      *
-     * By default the third argument is a value. {@link ref} can be used to
-     * pass in a column reference instead:
+     * After:
      *
      * ```ts
-     * db.updateTable('person')
-     *   .set((eb) => ({
-     *     age: eb.bxp('age', '+', eb.ref('age'))
-     *   }))
-     *   .where('id', '=', id)
+     * set((eb) => ({
+     *   age: eb('age', '+', 10)
+     * }))
      * ```
      *
-     * The generated SQL (PostgreSQL):
+     * or
      *
-     * ```sql
-     * update "person"
-     * set "age" = "age" + "age"
-     * where "id" = $1
+     * ```ts
+     * set(({ eb }) => ({
+     *   age: eb('age', '+', 10)
+     * }))
      * ```
      */
-    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>>;
+    bxp<RE extends ReferenceExpression<DB, TB>, OP extends BinaryOperatorExpression>(lhs: RE, op: OP, rhs: OperandValueExpression<DB, TB, RE>): ExpressionWrapper<DB, TB, OP extends ComparisonOperator ? SqlBool : ExtractTypeFromReferenceExpression<DB, TB, RE>>;
     /**
      * Creates an unary expression.
      *
@@ -340,7 +398,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * from "person"
      * ```
      */
-    unary<RE extends ReferenceExpression<DB, TB>>(op: UnaryOperator, expr: RE): ExpressionWrapper<ExtractTypeFromReferenceExpression<DB, TB, RE>>;
+    unary<RE extends ReferenceExpression<DB, TB>>(op: UnaryOperator, expr: RE): ExpressionWrapper<DB, TB, ExtractTypeFromReferenceExpression<DB, TB, RE>>;
     /**
      * Creates a `not` operation.
      *
@@ -348,7 +406,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      *
      * @see {@link unary}
      */
-    not<RE extends ReferenceExpression<DB, TB>>(expr: RE): ExpressionWrapper<ExtractTypeFromReferenceExpression<DB, TB, RE>>;
+    not<RE extends ReferenceExpression<DB, TB>>(expr: RE): ExpressionWrapper<DB, TB, ExtractTypeFromReferenceExpression<DB, TB, RE>>;
     /**
      * Creates an `exists` operation.
      *
@@ -356,7 +414,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      *
      * @see {@link unary}
      */
-    exists<RE extends ReferenceExpression<DB, TB>>(expr: RE): ExpressionWrapper<SqlBool>;
+    exists<RE extends ReferenceExpression<DB, TB>>(expr: RE): ExpressionWrapper<DB, TB, SqlBool>;
     /**
      * Creates a negation operation.
      *
@@ -364,7 +422,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      *
      * @see {@link unary}
      */
-    neg<RE extends ReferenceExpression<DB, TB>>(expr: RE): ExpressionWrapper<ExtractTypeFromReferenceExpression<DB, TB, RE>>;
+    neg<RE extends ReferenceExpression<DB, TB>>(expr: RE): ExpressionWrapper<DB, TB, ExtractTypeFromReferenceExpression<DB, TB, RE>>;
     /**
      * Combines two or more expressions using the logical `and` operator.
      *
@@ -373,16 +431,16 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      *
      * ### Examples
      *
-     * In this example we use `and` with {@link cmpr} to create a `WHERE expr1 AND expr2 AND expr3`
+     * In this example we use `and` 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')
+     *   .where((eb) => eb.and([
+     *     eb('first_name', '=', 'Jennifer'),
+     *     eb('fist_name', '=', 'Arnold'),
+     *     eb('fist_name', '=', 'Sylvester')
      *   ]))
      * ```
      *
@@ -396,7 +454,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * and "first_name" = $3
      * ```
      */
-    and(expres: ReadonlyArray<Expression<SqlBool>>): ExpressionWrapper<SqlBool>;
+    and(exprs: ReadonlyArray<Expression<SqlBool>>): ExpressionWrapper<DB, TB, SqlBool>;
     /**
      * Combines two or more expressions using the logical `or` operator.
      *
@@ -405,16 +463,16 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      *
      * ### Examples
      *
-     * In this example we use `or` with {@link cmpr} to create a `WHERE expr1 OR expr2 OR expr3`
+     * In this example we use `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')
+     *   .where((eb) => or([
+     *     eb('first_name', '=', 'Jennifer'),
+     *     eb('fist_name', '=', 'Arnold'),
+     *     eb('fist_name', '=', 'Sylvester')
      *   ]))
      * ```
      *
@@ -428,7 +486,48 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * or "first_name" = $3
      * ```
      */
-    or(expres: ReadonlyArray<Expression<SqlBool>>): ExpressionWrapper<SqlBool>;
+    or(exprs: ReadonlyArray<Expression<SqlBool>>): ExpressionWrapper<DB, TB, SqlBool>;
+    /**
+     * Wraps the expression in parentheses.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .selectAll('person')
+     *   .where((eb) => eb(eb.parens('age', '+', 1), '/', 100), '<', 0.1))
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person".*
+     * from "person"
+     * where ("age" + $1) / $2 < $3
+     * ```
+     *
+     * You can also pass in any expression as the only argument:
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .selectAll('person')
+     *   .where((eb) => parens(
+     *     eb('age', '=', 1).or('age', '=', 2))
+     *   ).and(
+     *     eb('first_name', '=', 'Jennifer').or('first_name', '=', 'Arnold')
+     *   ))
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person".*
+     * from "person"
+     * where ("age" = $1 or "age" = $2) and ("first_name" = $3 or "first_name" = $4)
+     * ```
+     */
+    parens<RE extends ReferenceExpression<DB, TB>, OP extends BinaryOperatorExpression>(lhs: RE, op: OP, rhs: OperandValueExpressionOrList<DB, TB, RE>): ExpressionWrapper<DB, TB, OP extends ComparisonOperator ? SqlBool : ExtractTypeFromReferenceExpression<DB, TB, RE>>;
+    parens<T>(expr: Expression<T>): ExpressionWrapper<DB, TB, T>;
     /**
      * See {@link QueryCreator.withSchema}
      *

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

@@ -5,8 +5,8 @@ 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 { parseReferenceExpression, parseStringReference, } from '../parser/reference-parser.js';
-import { parseValueBinaryOperation, } from '../parser/binary-operation-parser.js';
+import { parseJSONReference, parseReferenceExpression, parseStringReference, } from '../parser/reference-parser.js';
+import { parseValueBinaryOperation, parseValueBinaryOperationOrExpression, } 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';
@@ -18,14 +18,17 @@ import { ValueNode } from '../operation-node/value-node.js';
 import { CaseBuilder } from '../query-builder/case-builder.js';
 import { CaseNode } from '../operation-node/case-node.js';
 import { isUndefined } from '../util/object-utils.js';
+import { JSONPathBuilder } from '../query-builder/json-path-builder.js';
 export function createExpressionBuilder(executor = NOOP_QUERY_EXECUTOR) {
+    function binary(lhs, op, rhs) {
+        return new ExpressionWrapper(parseValueBinaryOperation(lhs, op, rhs));
+    }
     function unary(op, expr) {
         return new ExpressionWrapper(parseUnaryOperation(op, expr));
     }
-    return {
-        get fn() {
-            return createFunctionModule();
-        },
+    const eb = Object.assign(binary, {
+        fn: undefined,
+        eb: undefined,
         selectFrom(table) {
             return new SelectQueryBuilder({
                 queryId: createQueryId(),
@@ -40,15 +43,20 @@ export function createExpressionBuilder(executor = NOOP_QUERY_EXECUTOR) {
                     : parseReferenceExpression(reference)),
             });
         },
-        ref(reference) {
-            return new ExpressionWrapper(parseStringReference(reference));
+        ref(reference, op) {
+            if (isUndefined(op)) {
+                return new ExpressionWrapper(parseStringReference(reference));
+            }
+            return new JSONPathBuilder(parseJSONReference(reference, op));
         },
         val(value) {
             return new ExpressionWrapper(parseValueExpressionOrList(value));
         },
+        // @deprecated
         cmpr(lhs, op, rhs) {
             return new ExpressionWrapper(parseValueBinaryOperation(lhs, op, rhs));
         },
+        // @deprecated
         bxp(lhs, op, rhs) {
             return new ExpressionWrapper(parseValueBinaryOperation(lhs, op, rhs));
         },
@@ -88,10 +96,23 @@ export function createExpressionBuilder(executor = NOOP_QUERY_EXECUTOR) {
             }
             return new ExpressionWrapper(ParensNode.create(node));
         },
+        parens(...args) {
+            const node = parseValueBinaryOperationOrExpression(args);
+            if (ParensNode.is(node)) {
+                // No double wrapping.
+                return new ExpressionWrapper(node);
+            }
+            else {
+                return new ExpressionWrapper(ParensNode.create(node));
+            }
+        },
         withSchema(schema) {
             return createExpressionBuilder(executor.withPluginAtFront(new WithSchemaPlugin(schema)));
         },
-    };
+    });
+    eb.fn = createFunctionModule();
+    eb.eb = eb;
+    return eb;
 }
 export function expressionBuilder(_) {
     return createExpressionBuilder();