@livestore/common 0.4.0-dev.20 → 0.4.0-dev.22

package/src/schema/state/sqlite/client-document-def.test.ts

@@ -3,7 +3,13 @@ import { describe, expect, test } from 'vitest'
 
 import { tables } from '../../../__tests__/fixture.ts'
 import type * as LiveStoreEvent from '../../LiveStoreEvent/mod.ts'
-import { ClientDocumentTableDefSymbol, clientDocument, mergeDefaultValues } from './client-document-def.ts'
+import {
+  ClientDocumentTableDefSymbol,
+  clientDocument,
+  createOptimisticEventSchema,
+  mergeDefaultValues,
+} from './client-document-def.ts'
+import { getResultSchema } from './query-builder/impl.ts'
 
 describe('client document table', () => {
   test('set event', () => {
@@ -248,6 +254,139 @@ describe('client document table', () => {
       `)
     })
   })
+
+  /** Ensures optimistic decoding stays robust when persisted JSON is incompatible. */
+  describe('optimistic schema', () => {
+    /** Models persisted JSON using epoch numbers + base64 while app code expects Date + Uint8Array. */
+    const valueSchema = Schema.Struct({
+      createdAt: Schema.DateFromNumber,
+      avatar: Schema.Uint8ArrayFromBase64,
+    })
+    const defaultValue = {
+      createdAt: new Date(0),
+      avatar: new Uint8Array(),
+    }
+    const invalidPayloads: Array<{ label: string; value: unknown }> = [
+      { label: 'decoded-shape JSON', value: { createdAt: new Date(0), avatar: new Uint8Array([1, 2]) } },
+      { label: 'wrong types', value: { createdAt: 'not-a-number', avatar: { nested: 'bad' } } },
+      { label: 'missing required fields', value: {} },
+    ]
+    const validPayload = { createdAt: 42, avatar: 'AQI=' }
+    const extraFieldsPayload = { createdAt: 42, avatar: 'AQI=', extra: 'ignored' }
+
+    test.each(invalidPayloads)('decodes invalid persisted JSON ($label)', ({ value }) => {
+      const optimisticSchema = createOptimisticEventSchema({
+        valueSchema,
+        defaultValue,
+        partialSet: false,
+      })
+      const rowSchema = Schema.parseJson(optimisticSchema)
+
+      expect(Schema.decodeUnknownSync(rowSchema)(JSON.stringify(value))).toEqual(defaultValue)
+    })
+
+    test('decodes valid persisted JSON (encoded shape)', () => {
+      const optimisticSchema = createOptimisticEventSchema({
+        valueSchema,
+        defaultValue,
+        partialSet: false,
+      })
+      const rowSchema = Schema.parseJson(optimisticSchema)
+
+      expect(Schema.decodeUnknownSync(rowSchema)(JSON.stringify(validPayload))).toEqual({
+        createdAt: new Date(42),
+        avatar: new Uint8Array([1, 2]),
+      })
+    })
+
+    test('decodes valid persisted JSON with extra fields', () => {
+      const optimisticSchema = createOptimisticEventSchema({
+        valueSchema,
+        defaultValue,
+        partialSet: false,
+      })
+      const rowSchema = Schema.parseJson(optimisticSchema)
+
+      expect(Schema.decodeUnknownSync(rowSchema)(JSON.stringify(extraFieldsPayload))).toEqual({
+        createdAt: new Date(42),
+        avatar: new Uint8Array([1, 2]),
+      })
+    })
+
+    test.each(invalidPayloads)('decodes clientDocument rowSchema with invalid JSON ($label)', ({ value }) => {
+      const Doc = clientDocument({
+        name: 'test_numbers',
+        schema: valueSchema,
+        default: { value: defaultValue },
+        partialSet: false,
+      })
+      const row = {
+        id: 'row-1',
+        value: JSON.stringify(value),
+      }
+
+      expect(Schema.decodeUnknownSync(Doc.rowSchema)(row)).toEqual({ id: 'row-1', value: defaultValue })
+    })
+
+    test('decodes clientDocument rowSchema with valid encoded JSON', () => {
+      const Doc = clientDocument({
+        name: 'test_numbers',
+        schema: valueSchema,
+        default: { value: defaultValue },
+        partialSet: false,
+      })
+      const row = {
+        id: 'row-1',
+        value: JSON.stringify(validPayload),
+      }
+
+      expect(Schema.decodeUnknownSync(Doc.rowSchema)(row)).toEqual({
+        id: 'row-1',
+        value: { createdAt: new Date(42), avatar: new Uint8Array([1, 2]) },
+      })
+    })
+
+    test.each(invalidPayloads)('decodes RowQuery result schema with invalid JSON ($label)', ({ value }) => {
+      const Doc = clientDocument({
+        name: 'test_numbers',
+        schema: valueSchema,
+        default: { value: defaultValue },
+        partialSet: false,
+      })
+      const query = Doc.get('row-1')
+      const resultSchema = getResultSchema(query)
+      const rawDbResults = [
+        {
+          id: 'row-1',
+          value: JSON.stringify(value),
+        },
+      ]
+
+      expect(Schema.decodeUnknownSync(resultSchema)(rawDbResults)).toEqual(defaultValue)
+    })
+
+    test('decodes RowQuery result schema with valid encoded JSON', () => {
+      const Doc = clientDocument({
+        name: 'test_numbers',
+        schema: valueSchema,
+        default: { value: defaultValue },
+        partialSet: false,
+      })
+      const query = Doc.get('row-1')
+      const resultSchema = getResultSchema(query)
+      const rawDbResults = [
+        {
+          id: 'row-1',
+          value: JSON.stringify(validPayload),
+        },
+      ]
+
+      expect(Schema.decodeUnknownSync(resultSchema)(rawDbResults)).toEqual({
+        createdAt: new Date(42),
+        avatar: new Uint8Array([1, 2]),
+      })
+    })
+  })
 })
 
 const patchId = (muationEvent: LiveStoreEvent.Input.Decoded) => {
@@ -255,7 +394,6 @@ const patchId = (muationEvent: LiveStoreEvent.Input.Decoded) => {
   const id = `00000000-0000-0000-0000-000000000000`
   return { ...muationEvent, id }
 }
-
 describe('mergeDefaultValues', () => {
   test('merges values from both objects', () => {
     const defaults = { a: 1, b: 2 }

package/src/schema/state/sqlite/client-document-def.ts

@@ -98,7 +98,9 @@ export const clientDocument = <
       value: options.partialSet ? Schema.partial(valueSchema) : valueSchema,
     }).annotations({ title: `${name}Set:Args` }),
   })
-  Object.defineProperty(setEventDef, 'options', { value: { derived: true, clientOnly: true, facts: undefined } })
+  Object.defineProperty(setEventDef, 'options', {
+    value: { derived: true, clientOnly: true, facts: undefined, deprecated: undefined },
+  })
 
   const clientDocumentTableDefTrait: ClientDocumentTableDef.Trait<
     TName,
@@ -176,6 +178,9 @@ export const createOptimisticEventSchema = ({
   partialSet: boolean
 }) => {
   const targetSchema = partialSet ? Schema.partial(valueSchema) : valueSchema
+  // The transform decode must yield values in the target schema's ENCODED shape.
+  // This keeps JSON columns consistent when Encoded != Type (e.g. Option).
+  const encodeTarget = Schema.encodeSync(targetSchema)
 
   return Schema.transform(
     Schema.Unknown, // Accept any historical event structure
@@ -184,14 +189,16 @@ export const createOptimisticEventSchema = ({
       decode: (eventValue) => {
         // Try direct decode first (for current schema events)
         try {
-          return Schema.decodeUnknownSync(targetSchema)(eventValue)
+          const decoded = Schema.decodeUnknownSync(targetSchema)(eventValue)
+          // Re-encode so downstream parseJson/column decoding sees encoded values.
+          return encodeTarget(decoded)
         } catch {
           // Optimistic decoding for historical events
 
           // Handle null/undefined/non-object cases
           if (typeof eventValue !== 'object' || eventValue === null) {
             console.warn(`Client document: Non-object event value, using ${partialSet ? 'empty partial' : 'defaults'}`)
-            return partialSet ? {} : defaultValue
+            return encodeTarget(partialSet ? {} : defaultValue)
           }
 
           if (partialSet) {
@@ -209,14 +216,15 @@ export const createOptimisticEventSchema = ({
 
             if (hasValidFields) {
               try {
-                return Schema.decodeUnknownSync(targetSchema)(partialResult)
+                const decoded = Schema.decodeUnknownSync(targetSchema)(partialResult)
+                return encodeTarget(decoded)
               } catch {
                 // Even filtered fields don't match schema
                 console.warn('Client document: Partial fields incompatible, returning empty partial')
-                return {}
+                return encodeTarget({})
               }
             }
-            return {}
+            return encodeTarget({})
           } else {
             // Full set: merge old data with new defaults
             const merged: Record<string, unknown> = { ...defaultValue }
@@ -231,12 +239,13 @@ export const createOptimisticEventSchema = ({
 
             // Try to decode the merged value
             try {
-              return Schema.decodeUnknownSync(valueSchema)(merged)
+              const decoded = Schema.decodeUnknownSync(valueSchema)(merged)
+              return encodeTarget(decoded)
             } catch {
               // Merged value still doesn't match (e.g., type changes)
               // Fall back to pure defaults
               console.warn('Client document: Could not preserve event data, using defaults')
-              return defaultValue
+              return encodeTarget(defaultValue)
             }
           }
         }
@@ -513,27 +522,17 @@ export namespace ClientDocumentTableDef {
     }
   }
 
-  export type GetOptions<TTableDef extends TraitAny> = TTableDef extends ClientDocumentTableDef.Trait<
-    any,
-    any,
-    any,
-    infer TOptions
-  >
-    ? TOptions
-    : never
+  export type GetOptions<TTableDef extends TraitAny> =
+    TTableDef extends ClientDocumentTableDef.Trait<any, any, any, infer TOptions> ? TOptions : never
 
   export type TraitAny = Trait<any, any, any, any>
 
-  export type DefaultIdType<TTableDef extends TraitAny> = TTableDef extends ClientDocumentTableDef.Trait<
-    any,
-    any,
-    any,
-    infer TOptions
-  >
-    ? TOptions['default']['id'] extends SessionIdSymbol | string
-      ? TOptions['default']['id']
+  export type DefaultIdType<TTableDef extends TraitAny> =
+    TTableDef extends ClientDocumentTableDef.Trait<any, any, any, infer TOptions>
+      ? TOptions['default']['id'] extends SessionIdSymbol | string
+        ? TOptions['default']['id']
+        : never
       : never
-    : never
 
   export type SetEventDefLike<
     TName extends string,
@@ -554,7 +553,7 @@ export namespace ClientDocumentTableDef {
       readonly name: `${TName}Set`
       readonly args: { id: string; value: TType }
     }
-    readonly options: { derived: true; clientOnly: true; facts: undefined }
+    readonly options: { derived: true; clientOnly: true; facts: undefined; deprecated: undefined }
   }
 
   export type SetEventDef<TName extends string, TType, TOptions extends ClientDocumentTableOptions<TType>> = EventDef<

package/src/schema/state/sqlite/column-def.test.ts

@@ -144,11 +144,10 @@ describe('getColumnDefForSchema', () => {
 
     it('should map tagged unions to json column', () => {
       const ResultSchema = Schema.Union(
-        Schema.Struct({
-          _tag: Schema.Literal('success'),
+        Schema.TaggedStruct('success', {
           value: Schema.String,
         }),
-        Schema.Struct({ _tag: Schema.Literal('error'), error: Schema.String }),
+        Schema.TaggedStruct('error', { error: Schema.String }),
       )
 
       const columnDef = State.SQLite.getColumnDefForSchema(ResultSchema)

package/src/schema/state/sqlite/db-schema/dsl/mod.ts

@@ -20,13 +20,12 @@ export type DbSchemaInput = Record<string, TableDefinition<any, any>> | Readonly
  * - array: we use the table name of each array item (= table definition) as the object key
  * - object: we discard the keys of the input object and use the table name of each object value (= table definition) as the new object key
  */
-export type DbSchemaFromInputSchema<TSchemaInput extends DbSchemaInput> = TSchemaInput extends ReadonlyArray<
-  TableDefinition<any, any>
->
-  ? { [K in TSchemaInput[number] as K['name']]: K }
-  : TSchemaInput extends Record<string, TableDefinition<any, any>>
-    ? { [K in keyof TSchemaInput as TSchemaInput[K]['name']]: TSchemaInput[K] }
-    : never
+export type DbSchemaFromInputSchema<TSchemaInput extends DbSchemaInput> =
+  TSchemaInput extends ReadonlyArray<TableDefinition<any, any>>
+    ? { [K in TSchemaInput[number] as K['name']]: K }
+    : TSchemaInput extends Record<string, TableDefinition<any, any>>
+      ? { [K in keyof TSchemaInput as TSchemaInput[K]['name']]: TSchemaInput[K] }
+      : never
 
 // TODO ensure via runtime check (possibly even via type-level check) that all index names are unique
 export const makeDbSchema = <TDbSchemaInput extends DbSchemaInput>(
@@ -116,12 +115,8 @@ export type TableDefinition<TName extends string, TColumns extends Columns> = {
 
 export type Columns = Record<string, ColumnDefinition<any, any>>
 
-export type IsSingleColumn<TColumns extends Columns | ColumnDefinition<any, any>> = TColumns extends ColumnDefinition<
-  any,
-  any
->
-  ? true
-  : false
+export type IsSingleColumn<TColumns extends Columns | ColumnDefinition<any, any>> =
+  TColumns extends ColumnDefinition<any, any> ? true : false
 
 /**
  * NOTE this is only needed to avoid a TS limitation where `StructSchemaForColumns` in the default case
@@ -214,9 +209,8 @@ export namespace FromColumns {
 
   export type RequiredInsertColumnNames<TColumns extends Columns> = keyof RequiredInsertColumns<TColumns>
 
-  export type RequiresInsertValues<TColumns extends Columns> = RequiredInsertColumnNames<TColumns> extends never
-    ? false
-    : true
+  export type RequiresInsertValues<TColumns extends Columns> =
+    RequiredInsertColumnNames<TColumns> extends never ? false : true
 
   export type InsertRowDecoded<TColumns extends Columns> = Types.Simplify<
     Pick<RowDecodedAll<TColumns>, RequiredInsertColumnNames<TColumns>> &

package/src/schema/state/sqlite/query-builder/api.ts

@@ -128,15 +128,25 @@ export type QueryBuilder<
 
 export namespace QueryBuilder {
   export type Any = QueryBuilder<any, any, any>
-  export type WhereOps = WhereOps.Equality | WhereOps.Order | WhereOps.Like | WhereOps.In
+  export type WhereOps = WhereOps.Equality | WhereOps.Order | WhereOps.Like | WhereOps.In | WhereOps.JsonArray
 
   export namespace WhereOps {
     export type Equality = '=' | '!='
     export type Order = '<' | '>' | '<=' | '>='
     export type Like = 'LIKE' | 'NOT LIKE' | 'ILIKE' | 'NOT ILIKE'
     export type In = 'IN' | 'NOT IN'
+    /**
+     * Operators for checking if a JSON array column contains a value.
+     *
+     * ⚠️ **Performance note**: These operators use SQLite's `json_each()` table-valued function
+     * which **cannot be indexed** and requires a full table scan. For large tables with frequent
+     * lookups, consider denormalizing the data into a separate indexed table.
+     *
+     * @see https://sqlite.org/json1.html#jeach
+     */
+    export type JsonArray = 'JSON_CONTAINS' | 'JSON_NOT_CONTAINS'
 
-    export type SingleValue = Equality | Order | Like
+    export type SingleValue = Equality | Order | Like | JsonArray
     export type MultiValue = In
   }
 
@@ -155,14 +165,26 @@ export namespace QueryBuilder {
     | 'returning'
     | 'onConflict'
 
+  /** Extracts the element type from an array type, or returns never if not an array */
+  type ArrayElement<T> = T extends ReadonlyArray<infer E> ? E : never
+
   export type WhereParams<TTableDef extends TableDefBase> = Partial<{
     [K in keyof TTableDef['sqliteDef']['columns']]:
       | TTableDef['sqliteDef']['columns'][K]['schema']['Type']
-      | { op: QueryBuilder.WhereOps.SingleValue; value: TTableDef['sqliteDef']['columns'][K]['schema']['Type'] }
+      | {
+          op: Exclude<QueryBuilder.WhereOps.SingleValue, QueryBuilder.WhereOps.JsonArray>
+          value: TTableDef['sqliteDef']['columns'][K]['schema']['Type']
+        }
       | {
           op: QueryBuilder.WhereOps.MultiValue
           value: ReadonlyArray<TTableDef['sqliteDef']['columns'][K]['schema']['Type']>
         }
+      | (ArrayElement<TTableDef['sqliteDef']['columns'][K]['schema']['Type']> extends never
+          ? never
+          : {
+              op: QueryBuilder.WhereOps.JsonArray
+              value: ArrayElement<TTableDef['sqliteDef']['columns'][K]['schema']['Type']>
+            })
       | undefined
   }>
 
@@ -242,7 +264,12 @@ export namespace QueryBuilder {
       ): QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'select'>
       <TColName extends keyof TTableDef['sqliteDef']['columns']>(
         col: TColName,
-        op: QueryBuilder.WhereOps,
+        op: QueryBuilder.WhereOps.MultiValue,
+        value: ReadonlyArray<TTableDef['sqliteDef']['columns'][TColName]['schema']['Type']>,
+      ): QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'select'>
+      <TColName extends keyof TTableDef['sqliteDef']['columns']>(
+        col: TColName,
+        op: QueryBuilder.WhereOps.SingleValue,
         value: TTableDef['sqliteDef']['columns'][TColName]['schema']['Type'],
       ): QueryBuilder<TResult, TTableDef, TWithout | 'row' | 'select'>
     }

package/src/schema/state/sqlite/query-builder/astToSql.ts

@@ -1,11 +1,74 @@
 import { shouldNeverHappen } from '@livestore/utils'
-import { Schema } from '@livestore/utils/effect'
+import { Schema, SchemaAST } from '@livestore/utils/effect'
 
 import { SessionIdSymbol } from '../../../../adapter-types.ts'
 import type { SqlValue } from '../../../../util.ts'
 import type { State } from '../../../mod.ts'
 import type { QueryBuilderAst } from './api.ts'
 
+/**
+ * Extracts array element schema from a JSON array transformation AST.
+ * Returns the element schema, or undefined if not a JSON array transformation.
+ */
+const extractArrayElementFromTransformation = (ast: SchemaAST.AST): Schema.Schema.Any | undefined => {
+  if (!SchemaAST.isTransformation(ast)) return undefined
+
+  const toAst = ast.to
+  // Check if the "to" side is a TupleType (Effect's internal representation of Array)
+  if (!SchemaAST.isTupleType(toAst)) return undefined
+
+  // For Schema.Array, rest contains { type: AST } elements - get the first one's type
+  const restElement = toAst.rest[0]
+  if (restElement === undefined) return undefined
+
+  return Schema.make(restElement.type)
+}
+
+/**
+ * For JSON array columns, extracts the element schema from Schema.parseJson(Schema.Array(ElementSchema)).
+ * Also handles nullable JSON arrays (Schema.NullOr(Schema.parseJson(Schema.Array(...)))).
+ * Returns the element schema, or undefined if the column is not a JSON array.
+ */
+const getJsonArrayElementSchema = (colSchema: Schema.Schema.Any): Schema.Schema.Any | undefined => {
+  const ast = colSchema.ast
+
+  // Case 1: Direct transformation (non-nullable JSON array)
+  // Schema.parseJson(Schema.Array(ElementSchema)) creates a Transformation AST
+  if (SchemaAST.isTransformation(ast)) {
+    return extractArrayElementFromTransformation(ast)
+  }
+
+  // Case 2: Nullable JSON array - Schema.NullOr wraps the parseJson in a Union
+  // Structure: Union([Transformation (JSON array), Literal (null)])
+  if (SchemaAST.isUnion(ast)) {
+    for (const member of ast.types) {
+      const result = extractArrayElementFromTransformation(member)
+      if (result !== undefined) return result
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Encodes a JSON array element to the representation returned by SQLite's json_each().
+ * Objects/arrays are stringified so they match json_each's TEXT representation.
+ */
+const encodeJsonArrayElementValue = (elementSchema: Schema.Schema.Any, value: unknown): SqlValue => {
+  const encoded = Schema.encodeSync(elementSchema as Schema.Schema<unknown, SqlValue>)(value)
+
+  if (encoded === null) return null
+  if (typeof encoded === 'object') {
+    // Objects and arrays need to be JSON-stringified to match json_each() output
+    return JSON.stringify(encoded)
+  }
+  if (typeof encoded === 'boolean') {
+    return encoded ? 1 : 0
+  }
+
+  return encoded
+}
+
 // Helper functions for SQL generation
 const quoteIdentifier = (identifier: string): string => `"${identifier.replace(/"/g, '""')}"`
 
@@ -35,6 +98,23 @@ const formatWhereClause = (
         throw new Error(`Column ${col} not found`)
       }
 
+      // Handle JSON array containment operators
+      if (op === 'JSON_CONTAINS' || op === 'JSON_NOT_CONTAINS') {
+        const elementSchema = getJsonArrayElementSchema(colDef.schema)
+        if (elementSchema === undefined) {
+          throw new Error(
+            `${op} operator can only be used on JSON array columns, but column "${col}" is not a JSON array`,
+          )
+        }
+
+        const existsOp = op === 'JSON_CONTAINS' ? 'EXISTS' : 'NOT EXISTS'
+        // Encode the element value using the element schema
+        // Objects are JSON-stringified to match json_each() output
+        const encodedValue = encodeJsonArrayElementValue(elementSchema, value)
+        bindValues.push(encodedValue)
+        return `${existsOp} (SELECT 1 FROM json_each(${quotedCol}) WHERE value = ?)`
+      }
+
       // Handle array values for IN/NOT IN operators
       const isArray = op === 'IN' || op === 'NOT IN'
 

package/src/schema/state/sqlite/query-builder/impl.test.ts

@@ -81,7 +81,22 @@ const selections = State.SQLite.table({
   },
 })
 
-const db = { todos, todosWithIntId, comments, issue, selections, UiState, UiStateWithDefaultId }
+const Source = Schema.Literal('google', 'linkedin', 'facebook')
+const ProfileAttribute = Schema.Struct({ key: Schema.String, value: Schema.String })
+
+const personProfiles = State.SQLite.table({
+  name: 'person_profiles',
+  columns: {
+    personId: State.SQLite.text({ primaryKey: true }),
+    sources: State.SQLite.json({ schema: Schema.Array(Source), default: [] }),
+    tags: State.SQLite.json({ schema: Schema.Array(Schema.String), default: [] }),
+    attributes: State.SQLite.json({ schema: Schema.Array(ProfileAttribute), default: [] }),
+    /** Nullable JSON array column for testing JSON_CONTAINS on nullable columns */
+    optionalTags: State.SQLite.json({ schema: Schema.Array(Schema.String), nullable: true }),
+  },
+})
+
+const db = { todos, todosWithIntId, comments, issue, selections, UiState, UiStateWithDefaultId, personProfiles }
 
 const dump = (qb: QueryBuilder<any, any, any>) => ({
   bindValues: qb.asSql().bindValues,
@@ -364,6 +379,131 @@ describe('query builder', () => {
         }
       `)
     })
+
+    it('should handle JSON_CONTAINS operator for JSON array columns', () => {
+      expect(
+        dump(db.personProfiles.where({ sources: { op: 'JSON_CONTAINS', value: 'google' } })),
+      ).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "google",
+          ],
+          "query": "SELECT * FROM 'person_profiles' WHERE EXISTS (SELECT 1 FROM json_each("sources") WHERE value = ?)",
+          "schema": "ReadonlyArray<person_profiles>",
+        }
+      `)
+
+      // With select
+      expect(
+        dump(db.personProfiles.select('personId').where({ sources: { op: 'JSON_CONTAINS', value: 'linkedin' } })),
+      ).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "linkedin",
+          ],
+          "query": "SELECT "personId" FROM 'person_profiles' WHERE EXISTS (SELECT 1 FROM json_each("sources") WHERE value = ?)",
+          "schema": "ReadonlyArray<({ readonly personId: string } <-> string)>",
+        }
+      `)
+
+      // With plain string array column
+      expect(
+        dump(db.personProfiles.where({ tags: { op: 'JSON_CONTAINS', value: 'important' } })),
+      ).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "important",
+          ],
+          "query": "SELECT * FROM 'person_profiles' WHERE EXISTS (SELECT 1 FROM json_each("tags") WHERE value = ?)",
+          "schema": "ReadonlyArray<person_profiles>",
+        }
+      `)
+    })
+
+    it('should handle JSON_NOT_CONTAINS operator for JSON array columns', () => {
+      expect(
+        dump(db.personProfiles.where({ sources: { op: 'JSON_NOT_CONTAINS', value: 'google' } })),
+      ).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "google",
+          ],
+          "query": "SELECT * FROM 'person_profiles' WHERE NOT EXISTS (SELECT 1 FROM json_each("sources") WHERE value = ?)",
+          "schema": "ReadonlyArray<person_profiles>",
+        }
+      `)
+    })
+
+    it('should JSON-stringify object elements for JSON_CONTAINS', () => {
+      expect(
+        dump(
+          db.personProfiles.where({
+            attributes: { op: 'JSON_CONTAINS', value: { key: 'language', value: 'typescript' } },
+          }),
+        ),
+      ).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "{"key":"language","value":"typescript"}",
+          ],
+          "query": "SELECT * FROM 'person_profiles' WHERE EXISTS (SELECT 1 FROM json_each("attributes") WHERE value = ?)",
+          "schema": "ReadonlyArray<person_profiles>",
+        }
+      `)
+    })
+
+    it('should handle combining JSON_CONTAINS with other WHERE clauses', () => {
+      expect(
+        dump(
+          db.personProfiles
+            .where({ sources: { op: 'JSON_CONTAINS', value: 'google' } })
+            .where({ sources: { op: 'JSON_NOT_CONTAINS', value: 'facebook' } }),
+        ),
+      ).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "google",
+            "facebook",
+          ],
+          "query": "SELECT * FROM 'person_profiles' WHERE EXISTS (SELECT 1 FROM json_each("sources") WHERE value = ?) AND NOT EXISTS (SELECT 1 FROM json_each("sources") WHERE value = ?)",
+          "schema": "ReadonlyArray<person_profiles>",
+        }
+      `)
+    })
+
+    it('should handle JSON_CONTAINS on nullable JSON array columns', () => {
+      expect(
+        dump(db.personProfiles.where({ optionalTags: { op: 'JSON_CONTAINS', value: 'important' } })),
+      ).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "important",
+          ],
+          "query": "SELECT * FROM 'person_profiles' WHERE EXISTS (SELECT 1 FROM json_each("optionalTags") WHERE value = ?)",
+          "schema": "ReadonlyArray<person_profiles>",
+        }
+      `)
+
+      // With JSON_NOT_CONTAINS
+      expect(
+        dump(db.personProfiles.where({ optionalTags: { op: 'JSON_NOT_CONTAINS', value: 'archived' } })),
+      ).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "archived",
+          ],
+          "query": "SELECT * FROM 'person_profiles' WHERE NOT EXISTS (SELECT 1 FROM json_each("optionalTags") WHERE value = ?)",
+          "schema": "ReadonlyArray<person_profiles>",
+        }
+      `)
+    })
+
+    it('should throw error when using JSON_CONTAINS on non-JSON array column', () => {
+      expect(() =>
+        // Type system prevents this at compile time for non-array columns, but test runtime check
+        dump(db.todos.where({ status: { op: 'JSON_CONTAINS', value: 'active' } } as any)),
+      ).toThrow('JSON_CONTAINS operator can only be used on JSON array columns')
+    })
   })
 
   // describe('getOrCreate queries', () => {