@livestore/common 0.4.0-dev.21 → 0.4.0-dev.23

package/src/schema/state/sqlite/mod.ts

@@ -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']
         }>,
@@ -336,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'],

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) === 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, '""')}"`
 
@@ -35,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)
         }
 
@@ -65,7 +145,7 @@ const formatWhereClause = (
 }
 
 const formatReturningClause = (returning?: string[]): string => {
-  if (!returning || returning.length === 0) return ''
+  if (returning == null || returning.length === 0) return ''
   return ` RETURNING ${returning.map(quoteIdentifier).join(', ')}`
 }
 
@@ -89,7 +169,7 @@ 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'
@@ -169,7 +249,7 @@ export const astToSql = (ast: QueryBuilderAst): { query: string; bindValues: Sql
       .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 }
@@ -180,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 }

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

@@ -1,6 +1,8 @@
-import { Schema } from '@livestore/utils/effect'
 import { describe, expect, it } from 'vitest'
 
+import { Schema } from '@livestore/utils/effect'
+import { objectToString } from '@livestore/utils'
+
 import { State } from '../../../mod.ts'
 import type { QueryBuilder } from './api.ts'
 import { getResultSchema } from './impl.ts'
@@ -81,12 +83,27 @@ 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,
   query: qb.asSql().query,
-  schema: getResultSchema(qb).toString(),
+  schema: objectToString(getResultSchema(qb)),
 })
 
 describe('query builder', () => {
@@ -364,6 +381,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', () => {

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

@@ -9,7 +9,7 @@ import { astToSql } from './astToSql.ts'
 export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
   tableDef: TTableDef,
   ast: QueryBuilderAst = emptyAst(tableDef),
-): QueryBuilder<TResult, TTableDef, never> => {
+): QueryBuilder<TResult, TTableDef> => {
   const api = {
     select() {
       assertSelectQueryBuilderAst(ast)
@@ -18,6 +18,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
 
       // Pluck if there's only one column selected
       if (params.length === 1) {
+        // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- arguments-based overload dispatch requires manual narrowing
         const [col] = params as any as [string]
         return makeQueryBuilder(tableDef, {
           ...ast,
@@ -26,8 +27,10 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
         })
       }
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- arguments-based overload dispatch requires manual narrowing
       const columns = params as unknown as ReadonlyArray<string>
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
       return makeQueryBuilder(tableDef, {
         ...ast,
         resultSchemaSingle:
@@ -44,7 +47,8 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
         const newOps = Object.entries(params)
           .filter(([, value]) => value !== undefined)
           .map<QueryBuilderAst.Where>(([col, value]) =>
-            Predicate.hasProperty(value, 'op') && Predicate.hasProperty(value, 'value')
+            Predicate.hasProperty(value, 'op') === true && Predicate.hasProperty(value, 'value') === true
+              // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- where clause construction; shape validated at runtime
               ? ({ col, op: value.op, value: value.value } as any)
               : { col, op: '=', value },
           )
@@ -54,6 +58,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
           case 'SelectQuery':
           case 'UpdateQuery':
           case 'DeleteQuery': {
+            // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
             return makeQueryBuilder(tableDef, {
               ...ast,
               where: [...ast.where, ...newOps],
@@ -74,6 +79,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
         case 'SelectQuery':
         case 'UpdateQuery':
         case 'DeleteQuery': {
+          // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
           return makeQueryBuilder(tableDef, {
             ...ast,
             where: [...ast.where, { col, op, value }],
@@ -91,6 +97,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
       if (arguments.length === 0 || arguments.length > 2) return invalidQueryBuilder()
 
       if (arguments.length === 1) {
+        // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- arguments-based overload dispatch requires manual narrowing
         const params = arguments[0] as QueryBuilder.OrderByParams<TTableDef>
         return makeQueryBuilder(tableDef, {
           ...ast,
@@ -98,8 +105,10 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
         })
       }
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- arguments-based overload dispatch requires manual narrowing
       const [col, direction] = arguments as any as [keyof TTableDef['sqliteDef']['columns'] & string, 'asc' | 'desc']
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
       return makeQueryBuilder(tableDef, {
         ...ast,
         orderBy: [...ast.orderBy, { col, direction }],
@@ -116,7 +125,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
       return makeQueryBuilder(tableDef, { ...ast, offset: Option.some(offset) })
     },
     count: () => {
-      if (isRowQuery(ast) || ast._tag === 'InsertQuery' || ast._tag === 'UpdateQuery' || ast._tag === 'DeleteQuery')
+      if (isRowQuery(ast) === true || ast._tag === 'InsertQuery' || ast._tag === 'UpdateQuery' || ast._tag === 'DeleteQuery')
         return invalidQueryBuilder()
 
       return makeQueryBuilder(tableDef, {
@@ -171,6 +180,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
     insert: (values) => {
       const filteredValues = Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined))
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
       return makeQueryBuilder(tableDef, {
         _tag: 'InsertQuery',
         tableDef,
@@ -185,7 +195,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
       action: 'ignore' | 'replace' | 'update',
       updateValues?: Record<string, unknown>,
     ) => {
-      const targets = Array.isArray(targetOrTargets) ? targetOrTargets : [targetOrTargets]
+      const targets = Array.isArray(targetOrTargets) === true ? targetOrTargets : [targetOrTargets]
 
       assertInsertQueryBuilderAst(ast)
 
@@ -199,6 +209,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
         Match.exhaustive,
       )
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
       return makeQueryBuilder(tableDef, {
         ...ast,
         onConflict,
@@ -208,6 +219,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
     returning: (...columns) => {
       assertWriteQueryBuilderAst(ast)
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
       return makeQueryBuilder(tableDef, {
         ...ast,
         returning: columns,
@@ -221,6 +233,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
       // Preserve where clauses if coming from a SelectQuery
       const whereClause = ast._tag === 'SelectQuery' ? ast.where : []
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
       return makeQueryBuilder(tableDef, {
         _tag: 'UpdateQuery',
         tableDef,
@@ -235,6 +248,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
       // Preserve where clauses if coming from a SelectQuery
       const whereClause = ast._tag === 'SelectQuery' ? ast.where : []
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
       return makeQueryBuilder(tableDef, {
         _tag: 'DeleteQuery',
         tableDef,
@@ -248,6 +262,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
   return {
     [QueryBuilderTypeId]: QueryBuilderTypeId,
     [QueryBuilderAstSymbol]: ast,
+    // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- phantom type field for generic inference only
     ResultType: 'only-for-type-inference' as TResult,
     asSql: () => astToSql(ast),
     toString: () => {
@@ -277,19 +292,19 @@ const emptyAst = (tableDef: TableDefBase): QueryBuilderAst.SelectQuery => ({
 
 // Helper functions
 
-function assertSelectQueryBuilderAst(ast: QueryBuilderAst): asserts ast is QueryBuilderAst.SelectQuery {
+const assertSelectQueryBuilderAst: (ast: QueryBuilderAst) => asserts ast is QueryBuilderAst.SelectQuery = (ast) => {
   if (ast._tag !== 'SelectQuery') {
     return shouldNeverHappen(`Expected SelectQuery but got ${ast._tag}`)
   }
 }
 
-function assertInsertQueryBuilderAst(ast: QueryBuilderAst): asserts ast is QueryBuilderAst.InsertQuery {
+const assertInsertQueryBuilderAst: (ast: QueryBuilderAst) => asserts ast is QueryBuilderAst.InsertQuery = (ast) => {
   if (ast._tag !== 'InsertQuery') {
     return shouldNeverHappen(`Expected InsertQuery but got ${ast._tag}`)
   }
 }
 
-function assertWriteQueryBuilderAst(ast: QueryBuilderAst): asserts ast is QueryBuilderAst.WriteQuery {
+const assertWriteQueryBuilderAst: (ast: QueryBuilderAst) => asserts ast is QueryBuilderAst.WriteQuery = (ast) => {
   if (ast._tag !== 'InsertQuery' && ast._tag !== 'UpdateQuery' && ast._tag !== 'DeleteQuery') {
     return shouldNeverHappen(`Expected WriteQuery but got ${ast._tag}`)
   }
@@ -298,7 +313,7 @@ function assertWriteQueryBuilderAst(ast: QueryBuilderAst): asserts ast is QueryB
 const isRowQuery = (ast: QueryBuilderAst): ast is QueryBuilderAst.RowQuery => ast._tag === 'RowQuery'
 
 export const invalidQueryBuilder = (msg?: string) => {
-  return shouldNeverHappen(`Invalid query builder${msg ? `: ${msg}` : ''}`)
+  return shouldNeverHappen(`Invalid query builder${msg !== undefined ? `: ${msg}` : ''}`)
 }
 
 export const getResultSchema = (qb: QueryBuilder<any, any, any>): Schema.Schema<any> => {
@@ -328,7 +343,7 @@ export const getResultSchema = (qb: QueryBuilder<any, any, any>): Schema.Schema<
     case 'UpdateQuery':
     case 'DeleteQuery': {
       // For write operations with RETURNING clause, we need to return the appropriate schema
-      if (queryAst.returning && queryAst.returning.length > 0) {
+      if (queryAst.returning !== undefined && queryAst.returning.length > 0) {
         // Create a schema for the returned columns
         return queryAst.tableDef.rowSchema.pipe(Schema.pick(...queryAst.returning), Schema.Array)
       }
@@ -344,8 +359,7 @@ export const getResultSchema = (qb: QueryBuilder<any, any, any>): Schema.Schema<
         Schema.headOrElse(),
       )
     }
-    default: {
-      casesHandled(queryAst)
-    }
+    default:
+      return casesHandled(queryAst)
   }
 }

package/src/schema/state/sqlite/schema-helpers.ts

@@ -13,7 +13,7 @@ export const getDefaultValuesEncoded = <TTableDef extends TableDefBase>(
     ReadonlyRecord.filter((col, key) => {
       if (fallbackValues?.[key] !== undefined) return true
       if (key === 'id') return false
-      return col!.default._tag === 'None' || SqliteDsl.isSqlDefaultValue(col!.default.value) === false
+      return col!.default._tag === 'None' || !SqliteDsl.isSqlDefaultValue(col!.default.value)
     }),
     ReadonlyRecord.map((column, columnName) => {
       if (fallbackValues?.[columnName] !== undefined) return fallbackValues[columnName]
@@ -39,7 +39,7 @@ export const getDefaultValuesDecoded = <TTableDef extends TableDefBase>(
     ReadonlyRecord.filter((col, key) => {
       if (fallbackValues?.[key] !== undefined) return true
       if (key === 'id') return false
-      return col!.default._tag === 'None' || SqliteDsl.isSqlDefaultValue(col!.default.value) === false
+      return col!.default._tag === 'None' || !SqliteDsl.isSqlDefaultValue(col!.default.value)
     }),
     ReadonlyRecord.map((column, columnName) => {
       if (fallbackValues?.[columnName] !== undefined) return fallbackValues[columnName]