add json traversal support.

package.json

@@ -36,7 +36,7 @@
     "test:node:postgres": "DIALECT=postgres npm run test:node:run",
     "test:node:mysql": "DIALECT=mysql npm run test:node:run",
     "test:node:sqlite": "DIALECT=sqlite npm run test:node:run",
-    "test:node:run": "mocha --timeout 15000 test/node/dist/**/*.test.js",
+    "test:node:run": "mocha --reporter min --timeout 15000 test/node/dist/**/*.test.js",
     "test:browser:build": "rm -rf test/browser/bundle.js && esbuild test/browser/main.ts --bundle --outfile=test/browser/bundle.js",
     "test:browser": "npm run build && npm run test:browser:build && node test/browser/test.js",
     "test:bun": "npm run build && cd test/bun && bun install && bun run test",

src/expression/expression-builder.ts

@@ -18,6 +18,7 @@ import {
 } from '../query-builder/function-module.js'
 import {
   ExtractTypeFromReferenceExpression,
+  parseJSONReference,
   parseReferenceExpression,
   parseStringReference,
   ReferenceExpression,
@@ -40,6 +41,7 @@ import { ParensNode } from '../operation-node/parens-node.js'
 import { ExpressionWrapper } from './expression-wrapper.js'
 import {
   ComparisonOperator,
+  JSONOperatorWith$,
   UnaryOperator,
 } from '../operation-node/operator-node.js'
 import { SqlBool } from '../util/type-utils.js'
@@ -53,6 +55,7 @@ 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 interface ExpressionBuilder<DB, TB extends keyof DB> {
   /**
@@ -298,7 +301,11 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
   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
    *
@@ -314,9 +321,8 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
    *   ]))
    * ```
    *
-   * 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')
@@ -330,19 +336,60 @@ 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})`
    * }))
    * ```
+   *
+   * In the next example we use `ref` to reference a nested JSON property:
+   *
+   * ```ts
+   * db.selectFrom('person')
+   *   .where(({ cmpr, ref }) => cmpr(
+   *     ref('address', '->').key('state').key('abbr'),
+   *     '=',
+   *     'CA'
+   *   ))
+   *   .selectAll()
+   * ```
+   *
+   * The generated SQL (PostgreSQL):
+   *
+   * ```sql
+   * select * from "person" where "address"->'state'->'abbr' = $1
+   * ```
+   *
+   * You can also compile to a JSON path expression by using the `->$`or `->>$` operator:
+   *
+   * ```ts
+   * db.selectFrom('person')
+   *   .select(({ ref }) =>
+   *     ref('experience', '->$')
+   *       .at('last')
+   *       .key('title')
+   *       .as('current_job')
+   *   )
+   * ```
+   *
+   * The generated SQL (MySQL):
+   *
+   * ```sql
+   * select `experience`->'$[last].title' as `current_job` from `person`
+   * ```
    */
   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>>
+
   /**
    * Returns a value expression.
    *
@@ -690,13 +737,14 @@ export function createExpressionBuilder<DB, TB extends keyof DB>(
     },
 
     ref<RE extends StringReference<DB, TB>>(
-      reference: RE
-    ): ExpressionWrapper<
-      DB,
-      TB,
-      ExtractTypeFromReferenceExpression<DB, TB, RE>
-    > {
-      return new ExpressionWrapper(parseStringReference(reference))
+      reference: RE,
+      op?: JSONOperatorWith$
+    ): any {
+      if (isUndefined(op)) {
+        return new ExpressionWrapper(parseStringReference(reference))
+      }
+
+      return new JSONPathBuilder(parseJSONReference(reference, op))
     },
 
     val<VE>(

src/index.ts

@@ -24,6 +24,7 @@ export * from './query-builder/update-result.js'
 export * from './query-builder/on-conflict-builder.js'
 export * from './query-builder/aggregate-function-builder.js'
 export * from './query-builder/case-builder.js'
+export * from './query-builder/json-path-builder.js'
 
 export * from './raw-builder/raw-builder.js'
 export * from './raw-builder/sql.js'
@@ -97,6 +98,7 @@ export * from './plugin/kysely-plugin.js'
 export * from './plugin/camel-case/camel-case-plugin.js'
 export * from './plugin/deduplicate-joins/deduplicate-joins-plugin.js'
 export * from './plugin/with-schema/with-schema-plugin.js'
+export * from './plugin/parse-json-results/parse-json-results-plugin.js'
 
 export * from './operation-node/add-column-node.js'
 export * from './operation-node/add-constraint-node.js'
@@ -183,6 +185,10 @@ export * from './operation-node/set-operation-node.js'
 export * from './operation-node/binary-operation-node.js'
 export * from './operation-node/unary-operation-node.js'
 export * from './operation-node/using-node.js'
+export * from './operation-node/json-reference-node.js'
+export * from './operation-node/json-path-leg-node.js'
+export * from './operation-node/json-path-node.js'
+export * from './operation-node/json-operator-chain-node.js'
 
 export * from './util/column-type.js'
 export * from './util/compilable.js'

src/operation-node/json-operator-chain-node.ts

@@ -0,0 +1,37 @@
+import { freeze } from '../util/object-utils.js'
+import { OperationNode } from './operation-node.js'
+import { OperatorNode } from './operator-node.js'
+import { ValueNode } from './value-node.js'
+
+export interface JSONOperatorChainNode extends OperationNode {
+  readonly kind: 'JSONOperatorChainNode'
+  readonly operator: OperatorNode
+  readonly values: readonly ValueNode[]
+}
+
+/**
+ * @internal
+ */
+export const JSONOperatorChainNode = freeze({
+  is(node: OperationNode): node is JSONOperatorChainNode {
+    return node.kind === 'JSONOperatorChainNode'
+  },
+
+  create(operator: OperatorNode): JSONOperatorChainNode {
+    return freeze({
+      kind: 'JSONOperatorChainNode',
+      operator,
+      values: freeze([]),
+    })
+  },
+
+  cloneWithValue(
+    node: JSONOperatorChainNode,
+    value: ValueNode
+  ): JSONOperatorChainNode {
+    return freeze({
+      ...node,
+      values: freeze([...node.values, value]),
+    })
+  },
+})

src/operation-node/json-path-leg-node.ts

@@ -0,0 +1,27 @@
+import { freeze } from '../util/object-utils.js'
+import { OperationNode } from './operation-node.js'
+
+export type JSONPathLegType = 'Member' | 'ArrayLocation'
+
+export interface JSONPathLegNode extends OperationNode {
+  readonly kind: 'JSONPathLegNode'
+  readonly type: JSONPathLegType
+  readonly value: string | number
+}
+
+/**
+ * @internal
+ */
+export const JSONPathLegNode = freeze({
+  is(node: OperationNode): node is JSONPathLegNode {
+    return node.kind === 'JSONPathLegNode'
+  },
+
+  create(type: JSONPathLegType, value: string | number): JSONPathLegNode {
+    return freeze({
+      kind: 'JSONPathLegNode',
+      type,
+      value,
+    })
+  },
+})

src/operation-node/json-path-node.ts

@@ -0,0 +1,37 @@
+import { freeze } from '../util/object-utils.js'
+import { JSONPathLegNode } from './json-path-leg-node.js'
+import { OperationNode } from './operation-node.js'
+import { OperatorNode } from './operator-node.js'
+
+export interface JSONPathNode extends OperationNode {
+  readonly kind: 'JSONPathNode'
+  readonly inOperator?: OperatorNode
+  readonly pathLegs: ReadonlyArray<JSONPathLegNode>
+}
+
+/**
+ * @internal
+ */
+export const JSONPathNode = freeze({
+  is(node: OperationNode): node is JSONPathNode {
+    return node.kind === 'JSONPathNode'
+  },
+
+  create(inOperator?: OperatorNode): JSONPathNode {
+    return freeze({
+      kind: 'JSONPathNode',
+      inOperator,
+      pathLegs: freeze([]),
+    })
+  },
+
+  cloneWithLeg(
+    jsonPathNode: JSONPathNode,
+    pathLeg: JSONPathLegNode
+  ): JSONPathNode {
+    return freeze({
+      ...jsonPathNode,
+      pathLegs: freeze([...jsonPathNode.pathLegs, pathLeg]),
+    })
+  },
+})

src/operation-node/json-reference-node.ts

@@ -0,0 +1,41 @@
+import { freeze } from '../util/object-utils.js'
+import { JSONOperatorChainNode } from './json-operator-chain-node.js'
+import { JSONPathNode } from './json-path-node.js'
+import { OperationNode } from './operation-node.js'
+import { ReferenceNode } from './reference-node.js'
+
+export interface JSONReferenceNode extends OperationNode {
+  readonly kind: 'JSONReferenceNode'
+  readonly reference: ReferenceNode
+  readonly traversal: JSONPathNode | JSONOperatorChainNode
+}
+
+/**
+ * @internal
+ */
+export const JSONReferenceNode = freeze({
+  is(node: OperationNode): node is JSONReferenceNode {
+    return node.kind === 'JSONReferenceNode'
+  },
+
+  create(
+    reference: ReferenceNode,
+    traversal: JSONPathNode | JSONOperatorChainNode
+  ): JSONReferenceNode {
+    return freeze({
+      kind: 'JSONReferenceNode',
+      reference,
+      traversal,
+    })
+  },
+
+  cloneWithTraversal(
+    node: JSONReferenceNode,
+    traversal: JSONPathNode | JSONOperatorChainNode
+  ): JSONReferenceNode {
+    return freeze({
+      ...node,
+      traversal,
+    })
+  },
+})

src/operation-node/operation-node-transformer.ts

@@ -82,6 +82,10 @@ import { UsingNode } from './using-node.js'
 import { FunctionNode } from './function-node.js'
 import { CaseNode } from './case-node.js'
 import { WhenNode } from './when-node.js'
+import { JSONReferenceNode } from './json-reference-node.js'
+import { JSONPathNode } from './json-path-node.js'
+import { JSONPathLegNode } from './json-path-leg-node.js'
+import { JSONOperatorChainNode } from './json-operator-chain-node.js'
 
 /**
  * Transforms an operation node tree into another one.
@@ -198,6 +202,10 @@ export class OperationNodeTransformer {
     FunctionNode: this.transformFunction.bind(this),
     CaseNode: this.transformCase.bind(this),
     WhenNode: this.transformWhen.bind(this),
+    JSONReferenceNode: this.transformJSONReference.bind(this),
+    JSONPathNode: this.transformJSONPath.bind(this),
+    JSONPathLegNode: this.transformJSONPathLeg.bind(this),
+    JSONOperatorChainNode: this.transformJSONOperatorChain.bind(this),
   })
 
   transformNode<T extends OperationNode | undefined>(node: T): T {
@@ -286,8 +294,8 @@ export class OperationNodeTransformer {
   protected transformReference(node: ReferenceNode): ReferenceNode {
     return requireAllProps<ReferenceNode>({
       kind: 'ReferenceNode',
-      table: this.transformNode(node.table),
       column: this.transformNode(node.column),
+      table: this.transformNode(node.table),
     })
   }
 
@@ -920,6 +928,40 @@ export class OperationNodeTransformer {
     })
   }
 
+  protected transformJSONReference(node: JSONReferenceNode): JSONReferenceNode {
+    return requireAllProps<JSONReferenceNode>({
+      kind: 'JSONReferenceNode',
+      reference: this.transformNode(node.reference),
+      traversal: this.transformNode(node.traversal),
+    })
+  }
+
+  protected transformJSONPath(node: JSONPathNode): JSONPathNode {
+    return requireAllProps<JSONPathNode>({
+      kind: 'JSONPathNode',
+      inOperator: this.transformNode(node.inOperator),
+      pathLegs: this.transformNodeList(node.pathLegs),
+    })
+  }
+
+  protected transformJSONPathLeg(node: JSONPathLegNode): JSONPathLegNode {
+    return requireAllProps<JSONPathLegNode>({
+      kind: 'JSONPathLegNode',
+      type: node.type,
+      value: node.value,
+    })
+  }
+
+  protected transformJSONOperatorChain(
+    node: JSONOperatorChainNode
+  ): JSONOperatorChainNode {
+    return requireAllProps<JSONOperatorChainNode>({
+      kind: 'JSONOperatorChainNode',
+      operator: this.transformNode(node.operator),
+      values: this.transformNodeList(node.values),
+    })
+  }
+
   protected transformDataType(node: DataTypeNode): DataTypeNode {
     // An Object.freezed leaf node. No need to clone.
     return node