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

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

@@ -31,7 +31,7 @@ export type DbSchemaFromInputSchema<TSchemaInput extends DbSchemaInput> =
 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[]>(
@@ -76,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,
       ]),
     ),
@@ -195,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> = {

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

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

@@ -11,11 +11,11 @@ import type { QueryBuilderAst } from './api.ts'
  * 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
+  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)) return undefined
+  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]
@@ -34,13 +34,13 @@ const getJsonArrayElementSchema = (colSchema: Schema.Schema.Any): Schema.Schema.
 
   // Case 1: Direct transformation (non-nullable JSON array)
   // Schema.parseJson(Schema.Array(ElementSchema)) creates a Transformation AST
-  if (SchemaAST.isTransformation(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)) {
+  if (SchemaAST.isUnion(ast) === true) {
     for (const member of ast.types) {
       const result = extractArrayElementFromTransformation(member)
       if (result !== undefined) return result
@@ -63,7 +63,7 @@ const encodeJsonArrayElementValue = (elementSchema: Schema.Schema.Any, value: un
     return JSON.stringify(encoded)
   }
   if (typeof encoded === 'boolean') {
-    return encoded ? 1 : 0
+    return encoded === true ? 1 : 0
   }
 
   return encoded
@@ -118,9 +118,9 @@ const formatWhereClause = (
       // 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)
         }
 
@@ -145,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(', ')}`
 }
 
@@ -169,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'
@@ -249,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 }
@@ -260,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'
@@ -101,7 +103,7 @@ const db = { todos, todosWithIntId, comments, issue, selections, UiState, UiStat
 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', () => {

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]

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

@@ -1,5 +1,8 @@
+import { objectToString } from '@livestore/utils'
+
 import { Schema } from '@livestore/utils/effect'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, expectTypeOf, it } from 'vitest'
+
 import { State } from '../../mod.ts'
 
 describe('table function overloads', () => {
@@ -79,11 +82,11 @@ describe('table function overloads', () => {
     expect(todosTable.sqliteDef.columns).toHaveProperty('optionalComplex')
 
     expect(todosTable.sqliteDef.columns.optionalBoolean.nullable).toBe(true)
-    expect(todosTable.sqliteDef.columns.optionalBoolean.schema.toString()).toBe('(number <-> boolean) | null')
+    expect(objectToString(todosTable.sqliteDef.columns.optionalBoolean.schema)).toBe('(number <-> boolean) | null')
     expect((todosTable.rowSchema as any).fields.optionalBoolean.toString()).toBe('(number <-> boolean) | null')
 
     expect(todosTable.sqliteDef.columns.optionalComplex.nullable).toBe(true)
-    expect(todosTable.sqliteDef.columns.optionalComplex.schema.toString()).toBe(
+    expect(objectToString(todosTable.sqliteDef.columns.optionalComplex.schema)).toBe(
       '(parseJson <-> { readonly color: string } | undefined) | null',
     )
     expect((todosTable.rowSchema as any).fields.optionalComplex.toString()).toBe(
@@ -91,6 +94,22 @@ describe('table function overloads', () => {
     )
   })
 
+  it('should allow explicit first two generic arguments without options generic', () => {
+    const columns = {
+      id: State.SQLite.text({ primaryKey: true }),
+      text: State.SQLite.text({ default: '' }),
+    }
+
+    const todosTable = State.SQLite.table<'todos', typeof columns>({
+      name: 'todos',
+      columns,
+    })
+
+    expect(todosTable.sqliteDef.name).toBe('todos')
+    expect(todosTable.sqliteDef.columns).toHaveProperty('id')
+    expect(todosTable.sqliteDef.columns).toHaveProperty('text')
+  })
+
   it('should work with schema parameter', () => {
     const TodoSchema = Schema.Struct({
       id: Schema.String,
@@ -301,6 +320,50 @@ describe('table function overloads', () => {
     expect(userTable.sqliteDef.columns.metadata.nullable).toBe(true)
   })
 
+  it('should allow omitting nullable fields in insert()', () => {
+    const UserSchema = Schema.Struct({
+      id: Schema.String.pipe(State.SQLite.withPrimaryKey),
+      undefined: Schema.Undefined,
+      null: Schema.Null,
+      undefinedOrString: Schema.UndefinedOr(Schema.String),
+      nullOrString: Schema.NullOr(Schema.String),
+      optionalString: Schema.optional(Schema.String),
+      optionalNullOrString: Schema.optional(Schema.NullOr(Schema.String)),
+    })
+
+    const usersTable = State.SQLite.table({
+      name: 'users',
+      schema: UserSchema,
+    })
+
+    // Non-nullable fields (id) are required — omitting id should be rejected
+    expectTypeOf<{ undefined: undefined }>().not.toExtend<Parameters<typeof usersTable.insert>[0]>()
+
+    // Nullable fields (NullOr, optional+NullOr) are omittable — SQL defaults to NULL
+    expectTypeOf(usersTable.insert)
+      .toBeCallableWith({ id: '1' })
+      .toBeCallableWith({ id: '1', undefined: undefined })
+      .toBeCallableWith({ id: '1', undefined: undefined, null: null })
+      .toBeCallableWith({ id: '1', undefined: undefined, null: null, undefinedOrString: undefined })
+      .toBeCallableWith({ id: '1', undefined: undefined, null: null, undefinedOrString: 'string' })
+      .toBeCallableWith({ id: '1', undefined: undefined, null: null, undefinedOrString: 'string', nullOrString: null })
+      .toBeCallableWith({ id: '1', undefined: undefined, null: null, undefinedOrString: 'string', nullOrString: 'string' })
+      .toBeCallableWith({ id: '1', undefined: undefined, null: null, undefinedOrString: 'string', nullOrString: 'string', optionalString: 'string' })
+      .toBeCallableWith({ id: '1', undefined: undefined, null: null, undefinedOrString: 'string', nullOrString: 'string', optionalString: 'string', optionalNullOrString: null })
+      .toBeCallableWith({ id: '1', undefined: undefined, null: null, undefinedOrString: 'string', nullOrString: 'string', optionalString: 'string', optionalNullOrString: 'string' })
+
+    expect(() => usersTable.insert({ id: '1' }).asSql()).not.toThrow()
+    expect(() => usersTable.insert({ id: '1', undefined: undefined }).asSql()).not.toThrow()
+    expect(() => usersTable.insert({ id: '1', undefined: undefined, null: null }).asSql()).not.toThrow()
+    expect(() => usersTable.insert({ id: '1', undefined: undefined, null: null, undefinedOrString: undefined }).asSql()).not.toThrow()
+    expect(() => usersTable.insert({ id: '1', undefined: undefined, null: null, undefinedOrString: 'string' }).asSql()).not.toThrow()
+    expect(() => usersTable.insert({ id: '1', undefined: undefined, null: null, undefinedOrString: 'string', nullOrString: null }).asSql()).not.toThrow()
+    expect(() => usersTable.insert({ id: '1', undefined: undefined, null: null, undefinedOrString: 'string', nullOrString: 'string' }).asSql()).not.toThrow()
+    expect(() => usersTable.insert({ id: '1', undefined: undefined, null: null, undefinedOrString: 'string', nullOrString: 'string', optionalString: 'string' }).asSql()).not.toThrow()
+    expect(() => usersTable.insert({ id: '1', undefined: undefined, null: null, undefinedOrString: 'string', nullOrString: 'string', optionalString: 'string', optionalNullOrString: null }).asSql()).not.toThrow()
+    expect(() => usersTable.insert({ id: '1', undefined: undefined, null: null, undefinedOrString: 'string', nullOrString: 'string', optionalString: 'string', optionalNullOrString: 'string' }).asSql()).not.toThrow()
+  })
+
   it('supports discriminated unions with parsed JSON payloads', () => {
     const CircleDataSchema = Schema.Struct({
       radius: Schema.Number,
@@ -327,7 +390,7 @@ describe('table function overloads', () => {
 
     expect(shapes.sqliteDef.columns.kind.columnType).toBe('text')
 
-    const kindSchema = shapes.sqliteDef.columns.kind.schema.toString()
+    const kindSchema = objectToString(shapes.sqliteDef.columns.kind.schema)
     expect(kindSchema).toContain('"circle" | "square"')
 
     expect(() =>

package/src/schema/state/sqlite/table-def.ts

@@ -168,10 +168,7 @@ export function table<
     name: TName
     schema: TSchema
   } & Partial<TOptionsInput>,
-): TableDef<
-  SqliteTableDefForSchemaInput<TName, Schema.Schema.Type<TSchema>, Schema.Schema.Encoded<TSchema>, TSchema>,
-  TableOptions
->
+): TableDef<SqliteTableDefForSchemaInput<TName, Schema.Schema.Type<TSchema>, Schema.Schema.Encoded<TSchema>, TSchema>>
 
 // Overload 3: With schema and no name (uses schema annotations)
 export function table<
@@ -181,10 +178,7 @@ export function table<
   args: {
     schema: TSchema
   } & Partial<TOptionsInput>,
-): TableDef<
-  SqliteTableDefForSchemaInput<string, Schema.Schema.Type<TSchema>, Schema.Schema.Encoded<TSchema>, TSchema>,
-  TableOptions
->
+): TableDef<SqliteTableDefForSchemaInput<string, Schema.Schema.Type<TSchema>, Schema.Schema.Encoded<TSchema>, TSchema>>
 
 // Implementation
 export function table<
@@ -216,9 +210,7 @@ export function table<
   if ('columns' in args) {
     tableName = args.name
     const columnOrColumns = args.columns
-    columns = (
-      SqliteDsl.isColumnDefinition(columnOrColumns) ? { value: columnOrColumns } : columnOrColumns
-    ) as SqliteDsl.Columns
+    columns = SqliteDsl.isColumnDefinition(columnOrColumns) === true ? { value: columnOrColumns } : columnOrColumns
     additionalIndexes = []
   } else if ('schema' in args) {
     const result = schemaFieldsToColumns(Schema.getResolvedPropertySignatures(args.schema))
@@ -377,15 +369,16 @@ export type ToColumns<TColumns extends SqliteDsl.Columns | SqliteDsl.ColumnDefin
       : never
 
 export declare namespace SchemaToColumns {
+  /** Checks if `null` or `undefined` is assignable to `T`, matching the runtime nullable detection. */
+  type IsNullable<T> = null extends T ? true : undefined extends T ? true : false
+
   // Type helper to create column definition with proper schema
-  export type ColumnDefForType<TEncoded, TType> = SqliteDsl.ColumnDefinition<TEncoded, TType>
+  export type ColumnDefForType<TEncoded, TType> = SqliteDsl.ColumnDefinition<TEncoded, TType, IsNullable<TEncoded>>
 
-  // Create columns type from schema Type and Encoded
   export type FromTypes<TType, TEncoded> =
     TEncoded extends Record<string, any>
       ? {
-          [K in keyof TEncoded]-?: ColumnDefForType<
-            TEncoded[K],
+          [K in keyof TEncoded]-?: ColumnDefForType<TEncoded[K],
             TType extends Record<string, any> ? (K extends keyof TType ? TType[K] : TEncoded[K]) : TEncoded[K]
           >
         }

package/src/schema/unknown-events.ts

@@ -17,7 +17,7 @@ export namespace UnknownEvents {
   export type Callback = (
     context: UnknownEventContext,
     error: UnknownEventError,
-  ) => Effect.SyncOrPromiseOrEffect<void, unknown, never>
+  ) => Effect.SyncOrPromiseOrEffect<void, unknown>
 
   export type HandlingConfig =
     | { readonly strategy: 'warn' }
@@ -60,7 +60,7 @@ const handleUnknownEvent = ({
 
     switch (config.strategy) {
       case 'fail': {
-        return yield* Effect.fail(error)
+        return yield* error
       }
       case 'warn': {
         yield* Effect.logWarning('@livestore/common:schema:unknown-event', context)

package/src/schema-management/__tests__/migrations-autoincrement-quoting.test.ts

@@ -1,5 +1,7 @@
-import { Effect, Option, Schema } from '@livestore/utils/effect'
 import { describe, expect, it } from 'vitest'
+
+import { Effect, Option, Schema } from '@livestore/utils/effect'
+
 import { SqliteAst } from '../../schema/state/sqlite/db-schema/mod.ts'
 import type { PreparedStatement, SqliteDb } from '../../sqlite-types.ts'
 import type { PreparedBindValues } from '../../util.ts'

package/src/schema-management/common.ts

@@ -13,7 +13,7 @@ export const dbExecute = (db: SqliteDb, queryStr: string, bindValues?: ParamsObj
   // cachedStmts.set(queryStr, stmt)
   // }
 
-  const preparedBindValues = bindValues ? prepareBindValues(bindValues, queryStr) : undefined
+  const preparedBindValues = bindValues !== undefined ? prepareBindValues(bindValues, queryStr) : undefined
 
   try {
     stmt.execute(preparedBindValues)
@@ -34,7 +34,7 @@ export const dbSelect = <T>(db: SqliteDb, queryStr: string, bindValues?: ParamsO
   // cachedStmts.set(queryStr, stmt)
   // }
 
-  const res = stmt.select<T>(bindValues ? prepareBindValues(bindValues, queryStr) : undefined)
+  const res = stmt.select<T>(bindValues !== undefined ? prepareBindValues(bindValues, queryStr) : undefined)
   stmt.finalize()
   return res
 }

package/src/schema-management/migrations.ts

@@ -200,7 +200,7 @@ export const migrateTable = ({
   )
 
 const createIndexFromDefinition = (tableName: string, index: SqliteAst.Index) => {
-  const uniqueStr = index.unique ? 'UNIQUE' : ''
+  const uniqueStr = index.unique === true ? 'UNIQUE' : ''
   return sql`create ${uniqueStr} index if not exists "${index.name}" on "${tableName}" (${index.columns
     .map((col) => `"${col}"`)
     .join(', ')})`