feat: Add support for D1 JSON functions in WHERE clause

This commit introduces the ability to use Cloudflare D1's JSON
functions (e.g., json_extract, json_array_length, json_type)
within the `.where()` method of the modular query builder.

A new `json(expression, ...bindings)` helper function has been added
to allow users to specify JSON operations. The `where` method
has been updated to process these expressions and integrate them
correctly into the generated SQL query along with their parameters.

Relevant interfaces have been updated (`WhereClause`, `WhereInput`)
to support these changes, and comprehensive unit tests have been
added to verify the new functionality across various scenarios.

Author: google-labs-jules[bot]

src/interfaces.ts

@@ -15,7 +15,14 @@ export type QueryBuilderOptions<IsAsync extends boolean = true> = {
 export type DefaultObject = Record<string, Primitive>
 export type DefaultReturnObject = Record<string, null | string | number | boolean | bigint>
 
-export type Where =
+export type WhereClause = {
+  conditions: Array<string>
+  params: Array<Primitive>
+}
+
+// The Where type for individual calls can still be flexible,
+// but internally SelectOne and SelectAll will use WhereClause.
+export type WhereInput =
   | {
       conditions: string | Array<string>
       // TODO: enable named parameters with DefaultObject
@@ -34,7 +41,7 @@ export type Join = {
 export type SelectOne = {
   tableName: string
   fields?: string | Array<string>
-  where?: Where
+  where?: WhereClause // Changed from Where to WhereClause
   join?: Join | Array<Join>
   groupBy?: string | Array<string>
   having?: string | Array<string>
@@ -66,7 +73,7 @@ export type SelectAll = SelectOne & {
 export type ConflictUpsert = {
   column: string | Array<string>
   data: DefaultObject
-  where?: Where
+  where?: WhereInput
 }
 
 export type Insert = {
@@ -93,7 +100,7 @@ export type test<I extends Insert = Insert> = I
 export type Update = {
   tableName: string
   data: DefaultObject
-  where?: Where
+  where?: WhereInput
   returning?: string | Array<string>
   onConflict?: string | ConflictTypes
 }
@@ -105,7 +112,7 @@ export type UpdateWithoutReturning = Omit<Update, 'returning'>
 
 export type Delete = {
   tableName: string
-  where: Where // This field is optional, but is kept required in type to warn users of delete without where
+  where: WhereInput // This field is optional, but is kept required in type to warn users of delete without where
   returning?: string | Array<string>
   orderBy?: string | Array<string> | Record<string, string | OrderTypes>
   limit?: number

src/modularBuilder.ts

@@ -7,8 +7,9 @@ import {
   Primitive,
   SelectAll,
   SelectOne,
+  WhereClause,
 } from './interfaces'
-import { Query, QueryWithExtra } from './tools'
+import { JsonExpression, Query, QueryWithExtra, Raw } from './tools'
 
 export interface SelectExecuteOptions {
   lazy?: boolean
@@ -49,32 +50,71 @@ export class SelectBuilder<GenericResultWrapper, GenericResult = DefaultReturnOb
     return this._parseArray('fields', this._options.fields, fields)
   }
 
+  // Overload signatures for the where method
   where(
-    conditions: string | Array<string>,
+    condition: string,
     params?: Primitive | Primitive[]
+  ): SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>
+  where(
+    conditions: Array<string>,
+    params?: Primitive | Primitive[]
+  ): SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>
+  where(
+    field: string | JsonExpression,
+    operator: string,
+    value: Primitive
+  ): SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>
+  where(
+    arg1: string | Array<string> | JsonExpression,
+    arg2?: Primitive | Primitive[] | string,
+    arg3?: Primitive
   ): SelectBuilder<GenericResultWrapper, GenericResult, IsAsync> {
-    if (!Array.isArray(conditions)) {
-      conditions = [conditions]
-    }
-    if (params === undefined) params = []
-    if (!Array.isArray(params)) {
-      params = [params]
-    }
-
-    if ((this._options.where as any)?.conditions) {
-      conditions = (this._options.where as any).conditions.concat(conditions)
-    }
-
-    if ((this._options.where as any)?.params) {
-      params = (this._options.where as any).params.concat(params)
+    const currentWhere: WhereClause = this._options.where || { conditions: [], params: [] }
+    const newConditions = [...currentWhere.conditions]
+    const newParams = [...currentWhere.params]
+
+    if (arg3 !== undefined && typeof arg2 === 'string') {
+      // Overload: where(field: string | JsonExpression, operator: string, value: Primitive)
+      const fieldOrJsonExpr = arg1 as string | JsonExpression
+      const operator = arg2
+      const value = arg3
+
+      if ((fieldOrJsonExpr as JsonExpression).isJsonExpression) {
+        const jsonExpr = fieldOrJsonExpr as JsonExpression
+        newConditions.push(`${jsonExpr.expression} ${operator} ?`)
+        newParams.push(...jsonExpr.bindings, value)
+      } else {
+        // Assuming fieldOrJsonExpr is a string (field name)
+        // We should also handle if it's a Raw instance for safety, though less common here
+        let fieldStr = fieldOrJsonExpr as string
+        if((fieldOrJsonExpr as Raw).isRaw) {
+          fieldStr = (fieldOrJsonExpr as Raw).content;
+        }
+        newConditions.push(`${fieldStr} ${operator} ?`)
+        newParams.push(value)
+      }
+    } else {
+      // Overload: where(conditions: string | Array<string>, params?: Primitive | Primitive[])
+      let conditionsArg = arg1 as string | Array<string>
+      let paramsArg = (arg2 || []) as Primitive | Primitive[]
+
+      if (!Array.isArray(conditionsArg)) {
+        conditionsArg = [conditionsArg]
+      }
+      if (!Array.isArray(paramsArg)) {
+        paramsArg = [paramsArg]
+      }
+
+      newConditions.push(...conditionsArg)
+      newParams.push(...paramsArg)
     }
 
     return new SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>(
       {
         ...this._options,
         where: {
-          conditions: conditions,
-          params: params,
+          conditions: newConditions,
+          params: newParams,
         },
       },
       this._fetchAll,
@@ -124,22 +164,16 @@ export class SelectBuilder<GenericResultWrapper, GenericResult = DefaultReturnOb
       whereInParams = values.flat()
     }
 
-    let conditions: string | Array<string> = [whereInCondition]
-    let params: Primitive[] = whereInParams
-    if ((this._options.where as any)?.conditions) {
-      conditions = (this._options.where as any)?.conditions.concat(conditions)
-    }
-
-    if ((this._options.where as any)?.params) {
-      params = (this._options.where as any)?.params.concat(params)
-    }
+    const currentWhere: WhereClause = this._options.where || { conditions: [], params: [] };
+    const newConditions = [...currentWhere.conditions, whereInCondition];
+    const newParams = [...currentWhere.params, ...whereInParams];
 
     return new SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>(
       {
         ...this._options,
         where: {
-          conditions: conditions,
-          params: params,
+          conditions: newConditions,
+          params: newParams,
         },
       },
       this._fetchAll,

src/tools.ts

@@ -67,3 +67,12 @@ export class QueryWithExtra<GenericResultWrapper, Result = any, IsAsync extends
 export function trimQuery(query: string): string {
   return query.replace(/\s\s+/g, ' ')
 }
+
+export class JsonExpression {
+  public isJsonExpression = true
+  constructor(public readonly expression: string, public readonly bindings: Primitive[] = []) {}
+}
+
+export function json(expression: string, ...bindings: Primitive[]): JsonExpression {
+  return new JsonExpression(expression, bindings);
+}

tests/unit/select.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { JoinTypes, OrderTypes } from '../../src/enums'
+import { json } from '../../src/tools'
 import { QuerybuilderTest } from '../utils'
 
 describe('Select Builder', () => {
@@ -933,4 +934,132 @@ describe('Select Builder', () => {
       expect(result.fetchType).toEqual('ALL')
     }
   })
+
+  describe('JSON Functions in WHERE clause', () => {
+    it('select with json_extract', () => {
+      const result = new QuerybuilderTest()
+        .select('dataTable')
+        .where(json("json_extract(data, '$.name')"), '=', 'John Doe')
+        .getQueryAll()
+
+      expect(result.query).toEqual("SELECT * FROM dataTable WHERE json_extract(data, '$.name') = ?")
+      expect(result.arguments).toEqual(['John Doe'])
+      expect(result.fetchType).toEqual('ALL')
+    })
+
+    it('select with json_extract and path binding', () => {
+      const result = new QuerybuilderTest()
+        .select('dataTable')
+        .where(json('json_extract(data, ?)', '$.name'), '=', 'Jane Doe')
+        .getQueryAll()
+
+      expect(result.query).toEqual('SELECT * FROM dataTable WHERE json_extract(data, ?) = ?')
+      expect(result.arguments).toEqual(['$.name', 'Jane Doe'])
+      expect(result.fetchType).toEqual('ALL')
+    })
+
+    it('select with json_extract and multiple path bindings', () => {
+      const result = new QuerybuilderTest()
+        .select('dataTable')
+        .where(json('json_extract(data, ? || ?)', '$.users[', 0), '=', 'First User')
+        .getQueryAll()
+
+      expect(result.query).toEqual('SELECT * FROM dataTable WHERE json_extract(data, ? || ?) = ?')
+      expect(result.arguments).toEqual(['$.users[', 0, 'First User'])
+      expect(result.fetchType).toEqual('ALL')
+    })
+
+    it('select with json_array_length', () => {
+      const result = new QuerybuilderTest()
+        .select('dataTable')
+        .where(json("json_array_length(logins, '$.history')"), '>', 5)
+        .getQueryAll()
+
+      expect(result.query).toEqual("SELECT * FROM dataTable WHERE json_array_length(logins, '$.history') > ?")
+      expect(result.arguments).toEqual([5])
+      expect(result.fetchType).toEqual('ALL')
+    })
+
+    it('select with json_type and path binding', () => {
+        const result = new QuerybuilderTest()
+          .select('dataTable')
+          .where(json('json_type(attributes, ?)', '$.settings.theme'), '=', 'dark')
+          .getQueryAll()
+
+        expect(result.query).toEqual('SELECT * FROM dataTable WHERE json_type(attributes, ?) = ?')
+        expect(result.arguments).toEqual(['$.settings.theme', 'dark'])
+        expect(result.fetchType).toEqual('ALL')
+      })
+
+    it('select with chained where clauses including JSON functions', () => {
+      const result = new QuerybuilderTest()
+        .select('dataTable')
+        .where('processed = ?', true)
+        .where(json('json_extract(data, ?)', '$.status'), '=', 'active')
+        .where('retries', '<', 3)
+        .getQueryAll()
+
+      expect(result.query).toEqual(
+        'SELECT * FROM dataTable WHERE (processed = ?) AND (json_extract(data, ?) = ?) AND (retries < ?)'
+      )
+      expect(result.arguments).toEqual([true, '$.status', 'active', 3])
+      expect(result.fetchType).toEqual('ALL')
+    })
+
+    it('select one with json_extract', () => {
+        const result = new QuerybuilderTest()
+          .select('dataTable')
+          .where(json("json_extract(data, '$.name')"), '=', 'John Doe')
+          .getQueryOne()
+
+        expect(result.query).toEqual("SELECT * FROM dataTable WHERE json_extract(data, '$.name') = ? LIMIT 1")
+        expect(result.arguments).toEqual(['John Doe'])
+        expect(result.fetchType).toEqual('ONE')
+      })
+
+    it('select with json function in where and regular field condition', () => {
+        const qb = new QuerybuilderTest().select('myTable');
+        const result = qb
+            .where(json('JSON_EXTRACT(meta, ?)', '$.isAdmin'), '=', 1)
+            .where('age', '>', 30)
+            .getQueryAll();
+
+        expect(result.query).toBe('SELECT * FROM myTable WHERE (JSON_EXTRACT(meta, ?) = ?) AND (age > ?)');
+        expect(result.arguments).toEqual(['$.isAdmin', 1, 30]);
+    });
+
+    it('select with regular field condition then json function in where', () => {
+        const qb = new QuerybuilderTest().select('myTable');
+        const result = qb
+            .where('age', '>', 30)
+            .where(json('JSON_EXTRACT(meta, ?)', '$.isAdmin'), '=', 1)
+            .getQueryAll();
+
+        expect(result.query).toBe('SELECT * FROM myTable WHERE (age > ?) AND (JSON_EXTRACT(meta, ?) = ?)');
+        expect(result.arguments).toEqual([30, '$.isAdmin', 1]);
+    });
+
+    it('select with multiple json functions in where', () => {
+        const qb = new QuerybuilderTest().select('myTable');
+        const result = qb
+            .where(json('JSON_EXTRACT(meta, ?)', '$.isAdmin'), '=', 1)
+            .where(json('JSON_TYPE(meta, ?)', '$.tags'), '=', 'array')
+            .getQueryAll();
+
+        expect(result.query).toBe('SELECT * FROM myTable WHERE (JSON_EXTRACT(meta, ?) = ?) AND (JSON_TYPE(meta, ?) = ?)');
+        expect(result.arguments).toEqual(['$.isAdmin', 1, '$.tags', 'array']);
+    });
+
+    it('select with json function using direct path and another with bound path', () => {
+        const qb = new QuerybuilderTest().select('myTable');
+        const result = qb
+            .where(json("JSON_EXTRACT(meta, '$.config.enabled')"), '=', true)
+            .where(json('JSON_EXTRACT(meta, ?)', '$.user.id'), '=', 'uuid-123')
+            .getQueryAll();
+
+        expect(result.query).toBe("SELECT * FROM myTable WHERE (JSON_EXTRACT(meta, '$.config.enabled') = ?) AND (JSON_EXTRACT(meta, ?) = ?)");
+        expect(result.arguments).toEqual([true, '$.user.id', 'uuid-123']);
+    });
+
+  })
 })