@livestore/common 0.4.0-dev.9 → 0.4.0

package/src/schema/state/sqlite/db-schema/dsl/field-defs.ts

@@ -1,12 +1,30 @@
 import { casesHandled } from '@livestore/utils'
 import { Option, Schema } from '@livestore/utils/effect'
 
-export type ColumnDefinition<TEncoded, TDecoded> = {
+export type SqlDefaultValue = {
+  readonly sql: string
+}
+
+export const isSqlDefaultValue = (value: unknown): value is SqlDefaultValue => {
+  // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- type guard property access after structural check
+  return typeof value === 'object' && value !== null && 'sql' in value && typeof (value as any).sql === 'string'
+}
+
+export type ColumnDefaultThunk<T> = () => T
+
+export const isDefaultThunk = (value: unknown): value is ColumnDefaultThunk<unknown> => typeof value === 'function'
+
+export type ColumnDefaultValue<T> = T | null | ColumnDefaultThunk<T | null> | SqlDefaultValue
+
+export const resolveColumnDefault = <T>(value: ColumnDefaultValue<T>): T | null | SqlDefaultValue =>
+  isDefaultThunk(value) === true ? value() : value
+
+export type ColumnDefinition<TEncoded, TDecoded, TNullable extends boolean = boolean> = {
   readonly columnType: FieldColumnType
   readonly schema: Schema.Schema<TDecoded, TEncoded>
-  readonly default: Option.Option<TEncoded>
+  readonly default: Option.Option<ColumnDefaultValue<TDecoded>>
   /** @default false */
-  readonly nullable: boolean
+  readonly nullable: TNullable
   /** @default false */
   readonly primaryKey: boolean
   /** @default false */
@@ -23,13 +41,22 @@ export const isColumnDefinition = (value: unknown): value is ColumnDefinition.An
     typeof value === 'object' &&
     value !== null &&
     'columnType' in value &&
+    // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- type guard narrowing; columnType checked to be in valid set
     validColumnTypes.includes(value.columnType as any)
   )
 }
 
+type MaybeNull<T, TNullable extends boolean> = T | (TNullable extends true ? null : never)
+
+type ColumnDefaultArg<T, TNullable extends boolean> =
+  | MaybeNull<T, TNullable>
+  | ColumnDefaultThunk<MaybeNull<T, TNullable>>
+  | SqlDefaultValue
+  | NoDefault
+
 export type ColumnDefinitionInput = {
   readonly schema?: Schema.Schema<unknown>
-  readonly default?: unknown | NoDefault
+  readonly default?: ColumnDefaultArg<unknown, boolean>
   readonly nullable?: boolean
   readonly primaryKey?: boolean
   readonly autoIncrement?: boolean
@@ -38,14 +65,6 @@ export type ColumnDefinitionInput = {
 export const NoDefault = Symbol.for('NoDefault')
 export type NoDefault = typeof NoDefault
 
-export type SqlDefaultValue = {
-  readonly sql: string
-}
-
-export const isSqlDefaultValue = (value: unknown): value is SqlDefaultValue => {
-  return typeof value === 'object' && value !== null && 'sql' in value && typeof value.sql === 'string'
-}
-
 export type ColDefFn<TColumnType extends FieldColumnType> = {
   (): {
     columnType: TColumnType
@@ -59,7 +78,7 @@ export type ColDefFn<TColumnType extends FieldColumnType> = {
     TEncoded extends DefaultEncodedForColumnType<TColumnType>,
     TDecoded = DefaultEncodedForColumnType<TColumnType>,
     const TNullable extends boolean = false,
-    const TDefault extends TDecoded | SqlDefaultValue | NoDefault | (TNullable extends true ? null : never) = NoDefault,
+    const TDefault extends ColumnDefaultArg<NoInfer<TDecoded>, TNullable> = NoDefault,
     const TPrimaryKey extends boolean = false,
     const TAutoIncrement extends boolean = false,
   >(args: {
@@ -88,6 +107,7 @@ const makeColDef =
     const schema = nullable === true ? Schema.NullOr(schemaWithoutNull) : schemaWithoutNull
     const default_ = def?.default === undefined || def.default === NoDefault ? Option.none() : Option.some(def.default)
 
+    // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- column factory return type uses complex conditional generics; consumer type safety enforced by ColDefFn signature
     return {
       columnType,
       schema,
@@ -132,7 +152,7 @@ export type SpecializedColDefFn<
   <
     TDecoded = TBaseDecoded,
     const TNullable extends boolean = false,
-    const TDefault extends TDecoded | NoDefault | (TNullable extends true ? null : never) = NoDefault,
+    const TDefault extends ColumnDefaultArg<NoInfer<TDecoded>, TNullable> = NoDefault,
     const TPrimaryKey extends boolean = false,
     const TAutoIncrement extends boolean = false,
   >(
@@ -183,10 +203,12 @@ type MakeSpecializedColDefFn = {
 
 const makeSpecializedColDef: MakeSpecializedColDefFn = (columnType, opts) => (def?: ColumnDefinitionInput) => {
   const nullable = def?.nullable ?? false
+  // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- schema type variance; custom schema compatibility checked at call site
   const schemaWithoutNull = opts._tag === 'baseSchemaFn' ? opts.baseSchemaFn(def?.schema as any) : opts.baseSchema
   const schema = nullable === true ? Schema.NullOr(schemaWithoutNull) : schemaWithoutNull
   const default_ = def?.default === undefined || def.default === NoDefault ? Option.none() : Option.some(def.default)
 
+  // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- specialized column factory return type uses complex conditional generics; consumer type safety enforced by SpecializedColDefFn signature
   return {
     columnType,
     schema,
@@ -219,7 +241,7 @@ export const boolean: SpecializedColDefFn<'integer', false, boolean> = makeSpeci
   _tag: 'baseSchema',
   baseSchema: Schema.transform(Schema.Number, Schema.Boolean, {
     decode: (_) => _ === 1,
-    encode: (_) => (_ ? 1 : 0),
+    encode: (_) => (_ === true ? 1 : 0),
   }),
 })
 
@@ -242,15 +264,19 @@ export const defaultSchemaForColumnType = <TColumnType extends FieldColumnType>(
 
   switch (columnType) {
     case 'text': {
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- switch-based type narrowing for column type to schema mapping; each case is correct for its branch
       return Schema.String as any as Schema.Schema<T>
     }
     case 'integer': {
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- switch-based type narrowing for column type to schema mapping; each case is correct for its branch
       return Schema.Number as any as Schema.Schema<T>
     }
     case 'real': {
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- switch-based type narrowing for column type to schema mapping; each case is correct for its branch
       return Schema.Number as any as Schema.Schema<T>
     }
     case 'blob': {
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- switch-based type narrowing for column type to schema mapping; each case is correct for its branch
       return Schema.Uint8ArrayFromSelf as any as Schema.Schema<T>
     }
     default: {

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

@@ -20,19 +20,18 @@ 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>(
   schema: TDbSchemaInput,
 ): DbSchemaFromInputSchema<TDbSchemaInput> => {
-  return Array.isArray(schema) ? Object.fromEntries(schema.map((_) => [_.name, _])) : (schema as any)
+  return Array.isArray(schema) === true ? Object.fromEntries(schema.map((_) => [_.name, _])) : (schema as any)
 }
 
 export const table = <TTableName extends string, TColumns extends Columns, TIndexes extends Index[]>(
@@ -77,6 +76,7 @@ export const insertStructSchemaForTable = <TTableDefinition extends TableDefinit
     Object.fromEntries(
       tableDef.ast.columns.map((column) => [
         column.name,
+
         column.nullable === true || column.default._tag === 'Some' ? Schema.optional(column.schema) : column.schema,
       ]),
     ),
@@ -116,12 +116,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
@@ -200,8 +196,7 @@ export namespace FromColumns {
   }
 
   export type NullableColumnNames<TColumns extends Columns> = keyof {
-    // TODO double check why there is a `true` in the type
-    [K in keyof TColumns as TColumns[K] extends ColumnDefinition<any, true> ? K : never]: {}
+    [K in keyof TColumns as TColumns[K]['nullable'] extends true ? K : never]: {}
   }
 
   export type RequiredInsertColumns<TColumns extends Columns> = {
@@ -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/mod.ts

@@ -1,14 +1,14 @@
 import { shouldNeverHappen } from '@livestore/utils'
 
 import type { MigrationOptions } from '../../../adapter-types.ts'
-import type { Materializer } from '../../EventDef.ts'
+import type { Materializer } from '../../EventDef/mod.ts'
 import type { InternalState } from '../../schema.ts'
 import { ClientDocumentTableDefSymbol, tableIsClientDocumentTable } from './client-document-def.ts'
 import { SqliteAst } from './db-schema/mod.ts'
-import { stateSystemTables } from './system-tables.ts'
+import { stateSystemTables } from './system-tables/state-tables.ts'
 import type { TableDef, TableDefBase } from './table-def.ts'
 
-export * from '../../EventDef.ts'
+export * from '../../EventDef/mod.ts'
 export {
   type ClientDocumentTableDef,
   ClientDocumentTableDefSymbol,
@@ -22,16 +22,15 @@ export * from './column-spec.ts'
 export * from './table-def.ts'
 
 export const makeState = <TStateInput extends InputState>(inputSchema: TStateInput): InternalState => {
-  const inputTables: ReadonlyArray<TableDef> = Array.isArray(inputSchema.tables)
-    ? inputSchema.tables
-    : Object.values(inputSchema.tables)
+  const inputTables: ReadonlyArray<TableDef> =
+    Array.isArray(inputSchema.tables) === true ? inputSchema.tables : Object.values(inputSchema.tables)
 
   const tables = new Map<string, TableDef.Any>()
 
   for (const tableDef of inputTables) {
     const sqliteDef = tableDef.sqliteDef
     // TODO validate tables (e.g. index names are unique)
-    if (tables.has(sqliteDef.ast.name)) {
+    if (tables.has(sqliteDef.ast.name) === true) {
       shouldNeverHappen(`Duplicate table name: ${sqliteDef.ast.name}. Please use unique names for tables.`)
     }
     tables.set(sqliteDef.ast.name, tableDef)
@@ -48,7 +47,7 @@ export const makeState = <TStateInput extends InputState>(inputSchema: TStateInp
   }
 
   for (const tableDef of inputTables) {
-    if (tableIsClientDocumentTable(tableDef)) {
+    if (tableIsClientDocumentTable(tableDef) === true) {
       materializers.set(
         tableDef[ClientDocumentTableDefSymbol].derived.setEventDef.name,
         tableDef[ClientDocumentTableDefSymbol].derived.setMaterializer,

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
   }>
 
@@ -208,9 +230,8 @@ export namespace QueryBuilder {
       /** Select multiple columns */
       <TColumns extends keyof TTableDef['sqliteDef']['columns'] & string>(
         ...columns: TColumns[]
-        // TODO also support arbitrary SQL selects
-        // params: QueryBuilderSelectParams,
-      ): QueryBuilder<
+      )// params: QueryBuilderSelectParams, // TODO also support arbitrary SQL selects
+      : QueryBuilder<
         ReadonlyArray<{
           readonly [K in TColumns]: TTableDef['sqliteDef']['columns'][K]['schema']['Type']
         }>,
@@ -242,7 +263,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'>
     }
@@ -331,12 +357,20 @@ export namespace QueryBuilder {
     >
 
     /**
-     * Insert a new row into the table
+     * Insert a new row into the table.
+     *
+     * @remarks
+     *
+     * Follows SQL semantics: nullable columns and columns with defaults are omittable.
+     * `NullOr(S)` and `optional(NullOr(S))` both produce nullable columns, so both are omittable.
+     *
+     * @example
      *
-     * Example:
      * ```ts
      * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' })
      * ```
+     *
+     * @param values - The row values to insert.
      */
     readonly insert: (
       values: TTableDef['insertSchema']['Type'],
@@ -347,22 +381,26 @@ export namespace QueryBuilder {
     >
 
     /**
-     * Example: If the row already exists, it will be ignored.
+     * Upsert: insert a row, or handle conflicts on existing rows.
+     * Equivalent to SQLite's `INSERT ... ON CONFLICT` clause.
+     *
+     * Actions:
+     * - `'ignore'`: Skip the insert if a row with the same key exists
+     * - `'replace'`: Delete the existing row and insert the new one
+     * - `'update'`: Update specific columns on the existing row
+     *
      * ```ts
+     * // Ignore: skip if row exists
      * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'ignore')
-     * ```
      *
-     * Example: If the row already exists, it will be replaced.
-     * ```ts
+     * // Replace: delete existing row and insert new one
      * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'replace')
-     * ```
      *
-     * Example: If the row already exists, it will be updated.
-     * ```ts
+     * // Update: merge specific columns into existing row
      * db.todos.insert({ id: '123', text: 'Buy milk', status: 'active' }).onConflict('id', 'update', { text: 'Buy soy milk' })
      * ```
      *
-     * NOTE This API doesn't yet support composite primary keys.
+     * NOTE: Composite primary keys are not yet supported.
      */
     readonly onConflict: {
       <TTarget extends SingleOrReadonlyArray<keyof TTableDef['sqliteDef']['columns']>>(

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

@@ -1,12 +1,77 @@
 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) === false) return undefined
+
+  const toAst = ast.to
+  // Check if the "to" side is a TupleType (Effect's internal representation of Array)
+  if (SchemaAST.isTupleType(toAst) === false) 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) === true) {
+    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) === true) {
+    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 === true ? 1 : 0
+  }
+
+  return encoded
+}
+
 // Helper functions for SQL generation
+const quoteIdentifier = (identifier: string): string => `"${identifier.replace(/"/g, '""')}"`
+
 const formatWhereClause = (
   whereConditions: ReadonlyArray<QueryBuilderAst.Where>,
   tableDef: State.SQLite.TableDefBase,
@@ -16,13 +81,15 @@ const formatWhereClause = (
 
   const whereClause = whereConditions
     .map(({ col, op, value }) => {
+      const quotedCol = quoteIdentifier(col)
+
       // Handle NULL values
       if (value === null) {
         if (op !== '=' && op !== '!=') {
           throw new Error(`Unsupported operator for NULL value: ${op}`)
         }
         const opStmt = op === '=' ? 'IS' : 'IS NOT'
-        return `${col} ${opStmt} NULL`
+        return `${quotedCol} ${opStmt} NULL`
       }
 
       // Get column definition and encode value
@@ -31,12 +98,29 @@ 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'
 
-      if (isArray) {
+      if (isArray === true) {
         // Verify value is an array
-        if (!Array.isArray(value)) {
+        if (Array.isArray(value) === false) {
           return shouldNeverHappen(`Expected array value for ${op} operator but got`, value)
         }
 
@@ -48,11 +132,11 @@ const formatWhereClause = (
         const encodedValues = value.map((v) => Schema.encodeSync(colDef.schema)(v)) as SqlValue[]
         bindValues.push(...encodedValues)
         const placeholders = encodedValues.map(() => '?').join(', ')
-        return `${col} ${op} (${placeholders})`
+        return `${quotedCol} ${op} (${placeholders})`
       } else {
         const encodedValue = Schema.encodeSync(colDef.schema)(value)
         bindValues.push(encodedValue as SqlValue)
-        return `${col} ${op} ?`
+        return `${quotedCol} ${op} ?`
       }
     })
     .join(' AND ')
@@ -61,8 +145,8 @@ const formatWhereClause = (
 }
 
 const formatReturningClause = (returning?: string[]): string => {
-  if (!returning || returning.length === 0) return ''
-  return ` RETURNING ${returning.join(', ')}`
+  if (returning == null || returning.length === 0) return ''
+  return ` RETURNING ${returning.map(quoteIdentifier).join(', ')}`
 }
 
 export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: SqlValue[]; usedTables: Set<string> } => {
@@ -72,6 +156,7 @@ export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: Sql
   // INSERT query
   if (ast._tag === 'InsertQuery') {
     const columns = Object.keys(ast.values)
+    const quotedColumns = columns.map(quoteIdentifier)
     const placeholders = columns.map(() => '?').join(', ')
     const encodedValues = Schema.encodeSync(ast.tableDef.insertSchema)(ast.values)
 
@@ -84,14 +169,15 @@ export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: Sql
     let conflictClause = '' // Store the ON CONFLICT clause separately
 
     // Handle ON CONFLICT clause
-    if (ast.onConflict) {
+    if (ast.onConflict !== undefined) {
       // Handle REPLACE specifically as it changes the INSERT verb
       if (ast.onConflict.action._tag === 'replace') {
         insertVerb = 'INSERT OR REPLACE'
         // For REPLACE, the conflict target is implied and no further clause is needed
       } else {
         // Build the ON CONFLICT clause for IGNORE or UPDATE
-        conflictClause = ` ON CONFLICT (${ast.onConflict.targets.join(', ')}) `
+        const conflictTargets = ast.onConflict.targets.map(quoteIdentifier).join(', ')
+        conflictClause = ` ON CONFLICT (${conflictTargets}) `
         if (ast.onConflict.action._tag === 'ignore') {
           conflictClause += 'DO NOTHING'
         } else {
@@ -105,8 +191,9 @@ export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: Sql
           const updates = updateCols
             .map((col) => {
               const value = updateValues[col]
+              const quotedCol = quoteIdentifier(col)
               // If the value is undefined, use excluded.col
-              return value === undefined ? `${col} = excluded.${col}` : `${col} = ?`
+              return value === undefined ? `${quotedCol} = excluded.${quotedCol}` : `${quotedCol} = ?`
             })
             .join(', ')
 
@@ -129,7 +216,7 @@ export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: Sql
     }
 
     // Construct the main query part
-    let query = `${insertVerb} INTO '${ast.tableDef.sqliteDef.name}' (${columns.join(', ')}) VALUES (${placeholders})`
+    let query = `${insertVerb} INTO '${ast.tableDef.sqliteDef.name}' (${quotedColumns.join(', ')}) VALUES (${placeholders})`
 
     // Append the conflict clause if it was generated (i.e., not for REPLACE)
     query += conflictClause
@@ -157,10 +244,12 @@ export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: Sql
       bindValues.push(encodedValues[col] as SqlValue)
     })
 
-    let query = `UPDATE '${ast.tableDef.sqliteDef.name}' SET ${setColumns.map((col) => `${col} = ?`).join(', ')}`
+    let query = `UPDATE '${ast.tableDef.sqliteDef.name}' SET ${setColumns
+      .map((col) => `${quoteIdentifier(col)} = ?`)
+      .join(', ')}`
 
     const whereClause = formatWhereClause(ast.where, ast.tableDef, bindValues)
-    if (whereClause) query += ` ${whereClause}`
+    if (whereClause !== undefined) query += ` ${whereClause}`
 
     query += formatReturningClause(ast.returning)
     return { query, bindValues, usedTables }
@@ -171,7 +260,7 @@ export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: Sql
     let query = `DELETE FROM '${ast.tableDef.sqliteDef.name}'`
 
     const whereClause = formatWhereClause(ast.where, ast.tableDef, bindValues)
-    if (whereClause) query += ` ${whereClause}`
+    if (whereClause !== undefined) query += ` ${whereClause}`
 
     query += formatReturningClause(ast.returning)
     return { query, bindValues, usedTables }
@@ -201,31 +290,31 @@ export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: Sql
     const encodedId = ast.id === SessionIdSymbol ? ast.id : Schema.encodeSync(idColDef.schema)(ast.id)
 
     return {
-      query: `SELECT * FROM '${ast.tableDef.sqliteDef.name}' WHERE id = ?`,
+      query: `SELECT * FROM '${ast.tableDef.sqliteDef.name}' WHERE ${quoteIdentifier('id')} = ?`,
       bindValues: [encodedId as SqlValue],
       usedTables,
     }
   }
 
   // SELECT query
-  const columnsStmt = ast.select.columns.length === 0 ? '*' : ast.select.columns.join(', ')
+  const columnsStmt = ast.select.columns.length === 0 ? '*' : ast.select.columns.map(quoteIdentifier).join(', ')
   const selectStmt = `SELECT ${columnsStmt}`
   const fromStmt = `FROM '${ast.tableDef.sqliteDef.name}'`
   const whereStmt = formatWhereClause(ast.where, ast.tableDef, bindValues)
 
   const orderByStmt =
     ast.orderBy.length > 0
-      ? `ORDER BY ${ast.orderBy.map(({ col, direction }) => `${col} ${direction}`).join(', ')}`
+      ? `ORDER BY ${ast.orderBy.map(({ col, direction }) => `${quoteIdentifier(col)} ${direction}`).join(', ')}`
       : ''
 
   const limitStmt = ast.limit._tag === 'Some' ? `LIMIT ?` : ''
   const offsetStmt = ast.offset._tag === 'Some' ? `OFFSET ?` : ''
 
-  // Push offset and limit values in the correct order matching the query string
-  if (ast.offset._tag === 'Some') bindValues.push(ast.offset.value)
+  // Push limit and offset values in the correct order matching the query string
   if (ast.limit._tag === 'Some') bindValues.push(ast.limit.value)
+  if (ast.offset._tag === 'Some') bindValues.push(ast.offset.value)
 
-  const query = [selectStmt, fromStmt, whereStmt, orderByStmt, offsetStmt, limitStmt]
+  const query = [selectStmt, fromStmt, whereStmt, orderByStmt, limitStmt, offsetStmt]
     .map((clause) => clause.trim())
     .filter((clause) => clause.length > 0)
     .join(' ')