kysely 0.24.2 → 0.26.0

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

@@ -17,14 +17,20 @@ const unary_operation_parser_js_1 = require("../parser/unary-operation-parser.js
 const value_parser_js_1 = require("../parser/value-parser.js");
 const noop_query_executor_js_1 = require("../query-executor/noop-query-executor.js");
 const value_node_js_1 = require("../operation-node/value-node.js");
+const case_builder_js_1 = require("../query-builder/case-builder.js");
+const case_node_js_1 = require("../operation-node/case-node.js");
+const object_utils_js_1 = require("../util/object-utils.js");
+const json_path_builder_js_1 = require("../query-builder/json-path-builder.js");
 function createExpressionBuilder(executor = noop_query_executor_js_1.NOOP_QUERY_EXECUTOR) {
+    function binary(lhs, op, rhs) {
+        return new expression_wrapper_js_1.ExpressionWrapper((0, binary_operation_parser_js_1.parseValueBinaryOperation)(lhs, op, rhs));
+    }
     function unary(op, expr) {
         return new expression_wrapper_js_1.ExpressionWrapper((0, unary_operation_parser_js_1.parseUnaryOperation)(op, expr));
     }
-    return {
-        get fn() {
-            return (0, function_module_js_1.createFunctionModule)();
-        },
+    const eb = Object.assign(binary, {
+        fn: undefined,
+        eb: undefined,
         selectFrom(table) {
             return new select_query_builder_js_1.SelectQueryBuilder({
                 queryId: (0, query_id_js_1.createQueryId)(),
@@ -32,15 +38,27 @@ function createExpressionBuilder(executor = noop_query_executor_js_1.NOOP_QUERY_
                 queryNode: select_query_node_js_1.SelectQueryNode.create((0, table_parser_js_1.parseTableExpressionOrList)(table)),
             });
         },
-        ref(reference) {
-            return new expression_wrapper_js_1.ExpressionWrapper((0, reference_parser_js_1.parseStringReference)(reference));
+        case(reference) {
+            return new case_builder_js_1.CaseBuilder({
+                node: case_node_js_1.CaseNode.create((0, object_utils_js_1.isUndefined)(reference)
+                    ? undefined
+                    : (0, reference_parser_js_1.parseReferenceExpression)(reference)),
+            });
+        },
+        ref(reference, op) {
+            if ((0, object_utils_js_1.isUndefined)(op)) {
+                return new expression_wrapper_js_1.ExpressionWrapper((0, reference_parser_js_1.parseStringReference)(reference));
+            }
+            return new json_path_builder_js_1.JSONPathBuilder((0, reference_parser_js_1.parseJSONReference)(reference, op));
         },
         val(value) {
             return new expression_wrapper_js_1.ExpressionWrapper((0, value_parser_js_1.parseValueExpressionOrList)(value));
         },
+        // @deprecated
         cmpr(lhs, op, rhs) {
             return new expression_wrapper_js_1.ExpressionWrapper((0, binary_operation_parser_js_1.parseValueBinaryOperation)(lhs, op, rhs));
         },
+        // @deprecated
         bxp(lhs, op, rhs) {
             return new expression_wrapper_js_1.ExpressionWrapper((0, binary_operation_parser_js_1.parseValueBinaryOperation)(lhs, op, rhs));
         },
@@ -80,10 +98,23 @@ function createExpressionBuilder(executor = noop_query_executor_js_1.NOOP_QUERY_
             }
             return new expression_wrapper_js_1.ExpressionWrapper(parens_node_js_1.ParensNode.create(node));
         },
+        parens(...args) {
+            const node = (0, binary_operation_parser_js_1.parseValueBinaryOperationOrExpression)(args);
+            if (parens_node_js_1.ParensNode.is(node)) {
+                // No double wrapping.
+                return new expression_wrapper_js_1.ExpressionWrapper(node);
+            }
+            else {
+                return new expression_wrapper_js_1.ExpressionWrapper(parens_node_js_1.ParensNode.create(node));
+            }
+        },
         withSchema(schema) {
             return createExpressionBuilder(executor.withPluginAtFront(new with_schema_plugin_js_1.WithSchemaPlugin(schema)));
         },
-    };
+    });
+    eb.fn = (0, function_module_js_1.createFunctionModule)();
+    eb.eb = eb;
+    return eb;
 }
 exports.createExpressionBuilder = createExpressionBuilder;
 function expressionBuilder(_) {

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

@@ -1,7 +1,14 @@
 import { AliasNode } from '../operation-node/alias-node.js';
+import { AndNode } from '../operation-node/and-node.js';
 import { OperationNode } from '../operation-node/operation-node.js';
+import { OrNode } from '../operation-node/or-node.js';
+import { ParensNode } from '../operation-node/parens-node.js';
+import { ComparisonOperatorExpression, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
+import { ReferenceExpression } from '../parser/reference-parser.js';
+import { KyselyTypeError } from '../util/type-error.js';
+import { SqlBool } from '../util/type-utils.js';
 import { AliasedExpression, Expression } from './expression.js';
-export declare class ExpressionWrapper<T> implements Expression<T> {
+export declare class ExpressionWrapper<DB, TB extends keyof DB, T> implements Expression<T> {
     #private;
     constructor(node: OperationNode);
     /** @private */
@@ -31,8 +38,8 @@ export declare class ExpressionWrapper<T> implements Expression<T> {
      * ```ts
      * const result = await db
      *   .selectFrom('person')
-     *   .select(eb =>
-     *     eb.cmpr('first_name', '=', 'Jennifer').as('is_jennifer')
+     *   .select((eb) =>
+     *     eb('first_name', '=', 'Jennifer').as('is_jennifer')
      *   )
      *   .executeTakeFirstOrThrow()
      *
@@ -50,12 +57,136 @@ export declare class ExpressionWrapper<T> implements Expression<T> {
     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.
+     * Combines `this` and another expression using `OR`.
+     *
+     * Also see {@link ExpressionBuilder.or}
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .selectAll()
+     *   .where(eb => eb('first_name', '=', 'Jennifer')
+     *     .or('first_name', '=', 'Arnold')
+     *     .or('first_name', '=', 'Sylvester')
+     *   )
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```ts
+     * select *
+     * from "person"
+     * where (
+     *   "first_name" = $1
+     *   or "first_name" = $2
+     *   or "first_name" = $3
+     * )
+     * ```
+     *
+     * You can also pass any expression as the only argument to
+     * this method:
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .selectAll()
+     *   .where(eb => eb('first_name', '=', 'Jennifer')
+     *     .or(eb('first_name', '=', 'Sylvester').and('last_name', '=', 'Stallone'))
+     *     .or(eb.exists(
+     *       eb.selectFrom('pet')
+     *         .select('id')
+     *         .whereRef('pet.owner_id', '=', 'person.id')
+     *     )
+     *   )
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```ts
+     * select *
+     * from "person"
+     * where (
+     *   "first_name" = $1
+     *   or ("first_name" = $2 and "last_name" = $3)
+     *   or exists (
+     *     select "id"
+     *     from "pet"
+     *     where "pet"."owner_id" = "person"."id"
+     *   )
+     * )
+     * ```
+     */
+    or<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): T extends SqlBool ? OrWrapper<DB, TB, SqlBool> : KyselyTypeError<'or() method can only be called on boolean expressions'>;
+    or(expression: Expression<SqlBool>): T extends SqlBool ? OrWrapper<DB, TB, SqlBool> : KyselyTypeError<'or() method can only be called on boolean expressions'>;
+    /**
+     * Combines `this` and another expression using `AND`.
+     *
+     * Also see {@link ExpressionBuilder.and}
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .selectAll()
+     *   .where(eb => eb('first_name', '=', 'Jennifer')
+     *     .and('last_name', '=', 'Aniston')
+     *     .and('age', '>', 40)
+     *   )
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```ts
+     * select *
+     * from "person"
+     * where (
+     *   "first_name" = $1
+     *   and "last_name" = $2
+     *   and "age" > $3
+     * )
+     * ```
+     *
+     * You can also pass any expression as the only argument to
+     * this method:
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .selectAll()
+     *   .where(eb => eb('first_name', '=', 'Jennifer')
+     *     .and(eb('first_name', '=', 'Sylvester').or('last_name', '=', 'Stallone'))
+     *     .and(eb.exists(
+     *       eb.selectFrom('pet')
+     *         .select('id')
+     *         .whereRef('pet.owner_id', '=', 'person.id')
+     *     )
+     *   )
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```ts
+     * select *
+     * from "person"
+     * where (
+     *   "first_name" = $1
+     *   and ("first_name" = $2 or "last_name" = $3)
+     *   and exists (
+     *     select "id"
+     *     from "pet"
+     *     where "pet"."owner_id" = "person"."id"
+     *   )
+     * )
+     * ```
+     */
+    and<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): T extends SqlBool ? AndWrapper<DB, TB, SqlBool> : KyselyTypeError<'and() method can only be called on boolean expressions'>;
+    and(expression: Expression<SqlBool>): T extends SqlBool ? AndWrapper<DB, TB, SqlBool> : KyselyTypeError<'and() method can only be called on boolean expressions'>;
+    /**
+     * Change the output type of the 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>;
+    $castTo<T>(): ExpressionWrapper<DB, TB, T>;
     /**
      * Creates the OperationNode that describes how to compile this expression into SQL.
      *
@@ -90,3 +221,163 @@ export declare class AliasedExpressionWrapper<T, A extends string> implements Al
      */
     toOperationNode(): AliasNode;
 }
+export declare class OrWrapper<DB, TB extends keyof DB, T extends SqlBool> implements Expression<T> {
+    #private;
+    constructor(node: OrNode);
+    /** @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('first_name', '=', 'Jennifer')
+     *       .or('first_name', '=', 'Sylvester')
+     *       .as('is_jennifer_or_sylvester')
+     *   )
+     *   .executeTakeFirstOrThrow()
+     *
+     * // `is_jennifer_or_sylvester: SqlBool` field exists in the result type.
+     * console.log(result.is_jennifer_or_sylvester)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```ts
+     * select "first_name" = $1 or "first_name" = $2 as "is_jennifer_or_sylvester"
+     * from "person"
+     * ```
+     */
+    as<A extends string>(alias: A): AliasedExpression<T, A>;
+    as<A extends string>(alias: Expression<unknown>): AliasedExpression<T, A>;
+    /**
+     * Combines `this` and another expression using `OR`.
+     *
+     * See {@link ExpressionWrapper.or} for examples.
+     */
+    or<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): OrWrapper<DB, TB, T>;
+    or(expression: Expression<SqlBool>): OrWrapper<DB, TB, T>;
+    /**
+     * Change the output type of the expression.
+     *
+     * This method call doesn't change the SQL in any way. This methods simply
+     * returns a copy of this `OrWrapper` with a new output type.
+     */
+    $castTo<T extends SqlBool>(): OrWrapper<DB, TB, 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(): ParensNode;
+}
+export declare class AndWrapper<DB, TB extends keyof DB, T extends SqlBool> implements Expression<T> {
+    #private;
+    constructor(node: AndNode);
+    /** @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('first_name', '=', 'Jennifer')
+     *       .and('last_name', '=', 'Aniston')
+     *       .as('is_jennifer_aniston')
+     *   )
+     *   .executeTakeFirstOrThrow()
+     *
+     * // `is_jennifer_aniston: SqlBool` field exists in the result type.
+     * console.log(result.is_jennifer_or_sylvester)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```ts
+     * select "first_name" = $1 and "first_name" = $2 as "is_jennifer_aniston"
+     * from "person"
+     * ```
+     */
+    as<A extends string>(alias: A): AliasedExpression<T, A>;
+    as<A extends string>(alias: Expression<unknown>): AliasedExpression<T, A>;
+    /**
+     * Combines `this` and another expression using `AND`.
+     *
+     * See {@link ExpressionWrapper.and} for examples.
+     */
+    and<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): AndWrapper<DB, TB, T>;
+    and(expression: Expression<SqlBool>): AndWrapper<DB, TB, T>;
+    /**
+     * Change the output type of the expression.
+     *
+     * This method call doesn't change the SQL in any way. This methods simply
+     * returns a copy of this `AndWrapper` with a new output type.
+     */
+    $castTo<T extends SqlBool>(): AndWrapper<DB, TB, 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(): ParensNode;
+}

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

@@ -1,9 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AliasedExpressionWrapper = exports.ExpressionWrapper = void 0;
+exports.AndWrapper = exports.OrWrapper = exports.AliasedExpressionWrapper = exports.ExpressionWrapper = void 0;
 const alias_node_js_1 = require("../operation-node/alias-node.js");
+const and_node_js_1 = require("../operation-node/and-node.js");
 const identifier_node_js_1 = require("../operation-node/identifier-node.js");
 const operation_node_source_js_1 = require("../operation-node/operation-node-source.js");
+const or_node_js_1 = require("../operation-node/or-node.js");
+const parens_node_js_1 = require("../operation-node/parens-node.js");
+const binary_operation_parser_js_1 = require("../parser/binary-operation-parser.js");
 class ExpressionWrapper {
     #node;
     constructor(node) {
@@ -16,8 +20,14 @@ class ExpressionWrapper {
     as(alias) {
         return new AliasedExpressionWrapper(this, alias);
     }
+    or(...args) {
+        return new OrWrapper(or_node_js_1.OrNode.create(this.#node, (0, binary_operation_parser_js_1.parseFilter)(args)));
+    }
+    and(...args) {
+        return new AndWrapper(and_node_js_1.AndNode.create(this.#node, (0, binary_operation_parser_js_1.parseFilter)(args)));
+    }
     /**
-     * Change the output type of the raw expression.
+     * Change the output type of the 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.
@@ -52,3 +62,61 @@ class AliasedExpressionWrapper {
     }
 }
 exports.AliasedExpressionWrapper = AliasedExpressionWrapper;
+class OrWrapper {
+    #node;
+    constructor(node) {
+        this.#node = node;
+    }
+    /** @private */
+    get expressionType() {
+        return undefined;
+    }
+    as(alias) {
+        return new AliasedExpressionWrapper(this, alias);
+    }
+    or(...args) {
+        return new OrWrapper(or_node_js_1.OrNode.create(this.#node, (0, binary_operation_parser_js_1.parseFilter)(args)));
+    }
+    /**
+     * Change the output type of the expression.
+     *
+     * This method call doesn't change the SQL in any way. This methods simply
+     * returns a copy of this `OrWrapper` with a new output type.
+     */
+    $castTo() {
+        return new OrWrapper(this.#node);
+    }
+    toOperationNode() {
+        return parens_node_js_1.ParensNode.create(this.#node);
+    }
+}
+exports.OrWrapper = OrWrapper;
+class AndWrapper {
+    #node;
+    constructor(node) {
+        this.#node = node;
+    }
+    /** @private */
+    get expressionType() {
+        return undefined;
+    }
+    as(alias) {
+        return new AliasedExpressionWrapper(this, alias);
+    }
+    and(...args) {
+        return new AndWrapper(and_node_js_1.AndNode.create(this.#node, (0, binary_operation_parser_js_1.parseFilter)(args)));
+    }
+    /**
+     * Change the output type of the expression.
+     *
+     * This method call doesn't change the SQL in any way. This methods simply
+     * returns a copy of this `AndWrapper` with a new output type.
+     */
+    $castTo() {
+        return new AndWrapper(this.#node);
+    }
+    toOperationNode() {
+        return parens_node_js_1.ParensNode.create(this.#node);
+    }
+}
+exports.AndWrapper = AndWrapper;

package/dist/cjs/helpers/mysql.d.ts

@@ -3,7 +3,7 @@ import { SelectQueryBuilder } from '../query-builder/select-query-builder.js';
 import { RawBuilder } from '../raw-builder/raw-builder.js';
 import { Simplify } from '../util/type-utils.js';
 /**
- * A MySQL helper for aggregating a subquery (or other expression) into a JSON array.
+ * A MySQL helper for aggregating a subquery into a JSON array.
  *
  * NOTE: This helper is only guaranteed to fully work with the built-in `MysqlDialect`.
  * While the produced SQL is compatibe with all MySQL databases, some 3rd party dialects
@@ -49,7 +49,7 @@ import { Simplify } from '../util/type-utils.js';
  */
 export declare function jsonArrayFrom<O>(expr: SelectQueryBuilder<any, any, O>): RawBuilder<Simplify<O>[]>;
 /**
- * A MySQL helper for turning a subquery (or other expression) into a JSON object.
+ * A MySQL helper for turning a subquery into a JSON object.
  *
  * The subquery must only return one row.
  *
@@ -95,7 +95,7 @@ export declare function jsonArrayFrom<O>(expr: SelectQueryBuilder<any, any, O>):
  * from `person`
  * ```
  */
-export declare function jsonObjectFrom<O>(expr: SelectQueryBuilder<any, any, O>): RawBuilder<Simplify<O>>;
+export declare function jsonObjectFrom<O>(expr: SelectQueryBuilder<any, any, O>): RawBuilder<Simplify<O> | null>;
 /**
  * The MySQL `json_object` function.
  *

package/dist/cjs/helpers/mysql.js

@@ -7,7 +7,7 @@ const identifier_node_js_1 = require("../operation-node/identifier-node.js");
 const reference_node_js_1 = require("../operation-node/reference-node.js");
 const sql_js_1 = require("../raw-builder/sql.js");
 /**
- * A MySQL helper for aggregating a subquery (or other expression) into a JSON array.
+ * A MySQL helper for aggregating a subquery into a JSON array.
  *
  * NOTE: This helper is only guaranteed to fully work with the built-in `MysqlDialect`.
  * While the produced SQL is compatibe with all MySQL databases, some 3rd party dialects
@@ -56,7 +56,7 @@ function jsonArrayFrom(expr) {
 }
 exports.jsonArrayFrom = jsonArrayFrom;
 /**
- * A MySQL helper for turning a subquery (or other expression) into a JSON object.
+ * A MySQL helper for turning a subquery into a JSON object.
  *
  * The subquery must only return one row.
  *

package/dist/cjs/helpers/postgres.d.ts

@@ -4,13 +4,23 @@ import { Simplify } from '../util/type-utils.js';
 /**
  * A postgres helper for aggregating a subquery (or other expression) into a JSONB array.
  *
- * NOTE: This helper is only guaranteed to fully work with the built-in `PostgresDialect`.
- * While the produced SQL is compatibe with all PostgreSQL databases, some 3rd party dialects
- * may not parse the nested results into arrays.
- *
  * ### Examples
  *
+ * <!-- siteExample("select", "Nested array", 110) -->
+ *
+ * While kysely is not an ORM and it doesn't have the concept of relations, we do provide
+ * helpers for fetching nested objects and arrays in a single query. In this example we
+ * use the `jsonArrayFrom` helper to fetch person's pets along with the person's id.
+ *
+ * Please keep in mind that the helpers under the `kysely/helpers` folder, including
+ * `jsonArrayFrom`, are not guaranteed to work with third party dialects. In order for
+ * them to work, the dialect must automatically parse the `json` data type into
+ * javascript JSON values like objects and arrays. Some dialects might simply return
+ * the data as a JSON string.
+ *
  * ```ts
+ * import { jsonArrayFrom } from 'kysely/helpers/postgres'
+ *
  * const result = await db
  *   .selectFrom('person')
  *   .select((eb) => [
@@ -18,15 +28,11 @@ import { Simplify } from '../util/type-utils.js';
  *     jsonArrayFrom(
  *       eb.selectFrom('pet')
  *         .select(['pet.id as pet_id', 'pet.name'])
- *         .where('pet.owner_id', '=', 'person.id')
+ *         .whereRef('pet.owner_id', '=', 'person.id')
  *         .orderBy('pet.name')
  *     ).as('pets')
  *   ])
  *   .execute()
- *
- * result[0].id
- * result[0].pets[0].pet_id
- * result[0].pets[0].name
  * ```
  *
  * The generated SQL (PostgreSQL):
@@ -49,13 +55,23 @@ export declare function jsonArrayFrom<O>(expr: Expression<O>): RawBuilder<Simpli
  *
  * The subquery must only return one row.
  *
- * NOTE: This helper is only guaranteed to fully work with the built-in `PostgresDialect`.
- * While the produced SQL is compatibe with all PostgreSQL databases, some 3rd party dialects
- * may not parse the nested results into objects.
- *
  * ### Examples
  *
+ * <!-- siteExample("select", "Nested object", 120) -->
+ *
+ * While kysely is not an ORM and it doesn't have the concept of relations, we do provide
+ * helpers for fetching nested objects and arrays in a single query. In this example we
+ * use the `jsonObjectFrom` helper to fetch person's favorite pet along with the person's id.
+ *
+ * Please keep in mind that the helpers under the `kysely/helpers` folder, including
+ * `jsonObjectFrom`, are not guaranteed to work with third party dialects. In order for
+ * them to work, the dialect must automatically parse the `json` data type into
+ * javascript JSON values like objects and arrays. Some dialects might simply return
+ * the data as a JSON string.
+ *
  * ```ts
+ * import { jsonObjectFrom } from 'kysely/helpers/postgres'
+ *
  * const result = await db
  *   .selectFrom('person')
  *   .select((eb) => [
@@ -63,15 +79,11 @@ export declare function jsonArrayFrom<O>(expr: Expression<O>): RawBuilder<Simpli
  *     jsonObjectFrom(
  *       eb.selectFrom('pet')
  *         .select(['pet.id as pet_id', 'pet.name'])
- *         .where('pet.owner_id', '=', 'person.id')
+ *         .whereRef('pet.owner_id', '=', 'person.id')
  *         .where('pet.is_favorite', '=', true)
  *     ).as('favorite_pet')
  *   ])
  *   .execute()
- *
- * result[0].id
- * result[0].favorite_pet.pet_id
- * result[0].favorite_pet.name
  * ```
  *
  * The generated SQL (PostgreSQL):
@@ -88,7 +100,7 @@ export declare function jsonArrayFrom<O>(expr: Expression<O>): RawBuilder<Simpli
  * from "person"
  * ```
  */
-export declare function jsonObjectFrom<O>(expr: Expression<O>): RawBuilder<Simplify<O>>;
+export declare function jsonObjectFrom<O>(expr: Expression<O>): RawBuilder<Simplify<O> | null>;
 /**
  * The PostgreSQL `json_build_object` function.
  *