@livestore/common 0.4.0-dev.8 → 0.4.0

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:
@@ -35,7 +38,6 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
         select: { columns },
       }) as any
     },
-    // biome-ignore lint/complexity/useArrowFunction: prefer function over arrow function for this case
     where: function () {
       if (ast._tag === 'InsertQuery') return invalidQueryBuilder('Cannot use where with insert')
       if (ast._tag === 'RowQuery') return invalidQueryBuilder('Cannot use where with row')
@@ -45,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 },
           )
@@ -55,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],
@@ -75,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 }],
@@ -92,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,
@@ -99,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 }],
@@ -117,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, {
@@ -172,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,
@@ -186,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)
 
@@ -200,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,
@@ -209,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,
@@ -222,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,
@@ -236,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,
@@ -249,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: () => {
@@ -278,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}`)
   }
@@ -299,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> => {
@@ -329,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)
       }
@@ -345,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.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest'
+
+import * as State from '../mod.ts'
+import { getDefaultValuesDecoded, getDefaultValuesEncoded } from './schema-helpers.ts'
+
+describe('schema-helpers', () => {
+  it('resolves thunk defaults when decoding values', () => {
+    let counter = 0
+    const table = State.SQLite.table({
+      name: 'sessions',
+      columns: {
+        id: State.SQLite.text({ primaryKey: true }),
+        token: State.SQLite.text({ default: () => `token-${++counter}` }),
+      },
+    })
+
+    expect(counter).toBe(0)
+
+    const firstDefaults = getDefaultValuesDecoded(table)
+    const secondDefaults = getDefaultValuesDecoded(table)
+
+    expect(firstDefaults.token).toBe('token-1')
+    expect(secondDefaults.token).toBe('token-2')
+  })
+
+  it('resolves thunk defaults when encoding values', () => {
+    let counter = 0
+    const table = State.SQLite.table({
+      name: 'sessions_encoded',
+      columns: {
+        id: State.SQLite.text({ primaryKey: true }),
+        token: State.SQLite.text({ default: () => `encoded-${++counter}` }),
+      },
+    })
+
+    expect(counter).toBe(0)
+
+    const firstDefaults = getDefaultValuesEncoded(table)
+    const secondDefaults = getDefaultValuesEncoded(table)
+
+    expect(firstDefaults.token).toBe('encoded-1')
+    expect(secondDefaults.token).toBe('encoded-2')
+  })
+})

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

@@ -2,9 +2,9 @@ import { shouldNeverHappen } from '@livestore/utils'
 import { pipe, ReadonlyRecord, Schema } from '@livestore/utils/effect'
 
 import { SqliteDsl } from './db-schema/mod.ts'
-import type { TableDef, TableDefBase } from './table-def.ts'
+import type { TableDefBase } from './table-def.ts'
 
-export const getDefaultValuesEncoded = <TTableDef extends TableDef>(
+export const getDefaultValuesEncoded = <TTableDef extends TableDefBase>(
   tableDef: TTableDef,
   fallbackValues?: Record<string, any>,
 ) =>
@@ -13,17 +13,21 @@ export const getDefaultValuesEncoded = <TTableDef extends TableDef>(
     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]
+      if (column!.default._tag === 'None') {
+        return column!.nullable === true
+          ? null
+          : shouldNeverHappen(`Column ${columnName} has no default value and is not nullable`)
+      }
+
+      const defaultValue = column!.default.value
+      const resolvedDefault = SqliteDsl.resolveColumnDefault(defaultValue)
+
+      return Schema.encodeSync(column!.schema)(resolvedDefault)
     }),
-    ReadonlyRecord.map((column, columnName) =>
-      fallbackValues?.[columnName] === undefined
-        ? column!.default._tag === 'None'
-          ? column!.nullable === true
-            ? null
-            : shouldNeverHappen(`Column ${columnName} has no default value and is not nullable`)
-          : Schema.encodeSync(column!.schema)(column!.default.value)
-        : fallbackValues[columnName],
-    ),
   )
 
 export const getDefaultValuesDecoded = <TTableDef extends TableDefBase>(
@@ -35,15 +39,19 @@ 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]
+      if (column!.default._tag === 'None') {
+        return column!.nullable === true
+          ? null
+          : shouldNeverHappen(`Column ${columnName} has no default value and is not nullable`)
+      }
+
+      const defaultValue = column!.default.value
+      const resolvedDefault = SqliteDsl.resolveColumnDefault(defaultValue)
+
+      return Schema.validateSync(column!.schema)(resolvedDefault)
     }),
-    ReadonlyRecord.map((column, columnName) =>
-      fallbackValues?.[columnName] === undefined
-        ? column!.default._tag === 'None'
-          ? column!.nullable === true
-            ? null
-            : shouldNeverHappen(`Column ${columnName} has no default value and is not nullable`)
-          : Schema.validateSync(column!.schema)(column!.default.value)
-        : fallbackValues[columnName],
-    ),
   )

package/src/schema/state/sqlite/system-tables/eventlog-tables.ts

@@ -0,0 +1,64 @@
+import { Schema } from '@livestore/utils/effect'
+
+import * as EventSequenceNumber from '../../../EventSequenceNumber/mod.ts'
+import { SqliteDsl } from '../db-schema/mod.ts'
+import { table } from '../table-def.ts'
+
+/**
+ * EVENTLOG DATABASE SYSTEM TABLES
+ *
+ * ⚠️  CRITICAL: NEVER modify eventlog schemas without bumping `liveStoreStorageFormatVersion`!
+ * Eventlog is the source of truth - schema changes cause permanent data loss.
+ *
+ * TODO: Implement proper eventlog versioning system to prevent accidental data loss
+ */
+
+export const EVENTLOG_META_TABLE = 'eventlog'
+
+/**
+ * Main client-side event log storing all events (global and local/rebased).
+ */
+export const eventlogMetaTable = table({
+  name: EVENTLOG_META_TABLE,
+  columns: {
+    // TODO Adjust modeling so a global event never needs a client id component
+    seqNumGlobal: SqliteDsl.integer({ primaryKey: true, schema: EventSequenceNumber.Global.Schema }),
+    seqNumClient: SqliteDsl.integer({ primaryKey: true, schema: EventSequenceNumber.Client.Schema }),
+    seqNumRebaseGeneration: SqliteDsl.integer({ primaryKey: true }),
+    parentSeqNumGlobal: SqliteDsl.integer({ schema: EventSequenceNumber.Global.Schema }),
+    parentSeqNumClient: SqliteDsl.integer({ schema: EventSequenceNumber.Client.Schema }),
+    parentSeqNumRebaseGeneration: SqliteDsl.integer({}),
+    /** Event definition name */
+    name: SqliteDsl.text({}),
+    argsJson: SqliteDsl.text({ schema: Schema.parseJson(Schema.Any) }),
+    clientId: SqliteDsl.text({}),
+    sessionId: SqliteDsl.text({}),
+    schemaHash: SqliteDsl.integer({}),
+    syncMetadataJson: SqliteDsl.text({ schema: Schema.parseJson(Schema.Option(Schema.JsonValue)) }),
+  },
+  indexes: [
+    { columns: ['seqNumGlobal'], name: 'idx_eventlog_seqNumGlobal' },
+    { columns: ['seqNumGlobal', 'seqNumClient', 'seqNumRebaseGeneration'], name: 'idx_eventlog_seqNum' },
+  ],
+})
+
+export type EventlogMetaRow = typeof eventlogMetaTable.Type
+
+export const SYNC_STATUS_TABLE = '__livestore_sync_status'
+
+/**
+ * Tracks sync status including the remote head position and backend identity.
+ */
+// TODO support sync backend identity (to detect if sync backend changes)
+export const syncStatusTable = table({
+  name: SYNC_STATUS_TABLE,
+  columns: {
+    head: SqliteDsl.integer({ primaryKey: true }),
+    // Null means the sync backend is not yet connected and we haven't yet seen a backend ID
+    backendId: SqliteDsl.text({ nullable: true }),
+  },
+})
+
+export type SyncStatusRow = typeof syncStatusTable.Type
+
+export const eventlogSystemTables = [eventlogMetaTable, syncStatusTable] as const

package/src/schema/state/sqlite/system-tables/mod.ts

@@ -0,0 +1,2 @@
+export * from './eventlog-tables.ts'
+export * from './state-tables.ts'

package/src/schema/state/sqlite/system-tables/state-tables.ts

@@ -0,0 +1,69 @@
+import * as EventSequenceNumber from '../../../EventSequenceNumber/mod.ts'
+import { SqliteDsl } from '../db-schema/mod.ts'
+import { table } from '../table-def.ts'
+
+/**
+ * STATE DATABASE SYSTEM TABLES
+ *
+ * ⚠️  SAFE TO CHANGE: State tables are automatically rebuilt from eventlog when schema changes.
+ * No need to bump `liveStoreStorageFormatVersion` (uses hash-based migration via SqliteAst.hash()).
+ */
+
+export const SCHEMA_META_TABLE = '__livestore_schema'
+
+/**
+ * Tracks schema hashes for user-defined tables to detect schema changes.
+ */
+export const schemaMetaTable = table({
+  name: SCHEMA_META_TABLE,
+  columns: {
+    tableName: SqliteDsl.text({ primaryKey: true }),
+    schemaHash: SqliteDsl.integer({ nullable: false }),
+    /** ISO date format */
+    updatedAt: SqliteDsl.text({ nullable: false }),
+  },
+})
+
+export type SchemaMetaRow = typeof schemaMetaTable.Type
+
+export const SCHEMA_EVENT_DEFS_META_TABLE = '__livestore_schema_event_defs'
+
+/**
+ * Tracks schema hashes for event definitions to detect event schema changes.
+ */
+export const schemaEventDefsMetaTable = table({
+  name: SCHEMA_EVENT_DEFS_META_TABLE,
+  columns: {
+    eventName: SqliteDsl.text({ primaryKey: true }),
+    schemaHash: SqliteDsl.integer({ nullable: false }),
+    /** ISO date format */
+    updatedAt: SqliteDsl.text({ nullable: false }),
+  },
+})
+
+export type SchemaEventDefsMetaRow = typeof schemaEventDefsMetaTable.Type
+
+/**
+ * Table which stores SQLite changeset blobs which is used for rolling back
+ * read-model state during rebasing.
+ */
+export const SESSION_CHANGESET_META_TABLE = '__livestore_session_changeset'
+
+export const sessionChangesetMetaTable = table({
+  name: SESSION_CHANGESET_META_TABLE,
+  columns: {
+    // TODO bring back primary key
+    seqNumGlobal: SqliteDsl.integer({ schema: EventSequenceNumber.Global.Schema }),
+    seqNumClient: SqliteDsl.integer({ schema: EventSequenceNumber.Client.Schema }),
+    seqNumRebaseGeneration: SqliteDsl.integer({}),
+    changeset: SqliteDsl.blob({ nullable: true }),
+    debug: SqliteDsl.json({ nullable: true }),
+  },
+  indexes: [{ columns: ['seqNumGlobal', 'seqNumClient'], name: 'idx_session_changeset_id' }],
+})
+
+export type SessionChangesetMetaRow = typeof sessionChangesetMetaTable.Type
+
+export const stateSystemTables = [schemaMetaTable, schemaEventDefsMetaTable, sessionChangesetMetaTable] as const
+
+export const isStateSystemTable = (tableName: string) => stateSystemTables.some((_) => _.sqliteDef.name === tableName)

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,
@@ -300,4 +319,96 @@ describe('table function overloads', () => {
     expect(userTable.sqliteDef.columns.metadata.columnType).toBe('text')
     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,
+    })
+    const CircleSchema = Schema.Struct({
+      kind: Schema.Literal('circle'),
+      data: Schema.parseJson(CircleDataSchema),
+    })
+
+    const SquareDataSchema = Schema.Struct({
+      sideLength: Schema.Number,
+    })
+    const SquareSchema = Schema.Struct({
+      kind: Schema.Literal('square'),
+      data: Schema.parseJson(SquareDataSchema),
+    })
+
+    const ShapeSchema = Schema.Union(CircleSchema, SquareSchema)
+
+    const shapes = State.SQLite.table({
+      name: 'shapes',
+      schema: ShapeSchema,
+    })
+
+    expect(shapes.sqliteDef.columns.kind.columnType).toBe('text')
+
+    const kindSchema = objectToString(shapes.sqliteDef.columns.kind.schema)
+    expect(kindSchema).toContain('"circle" | "square"')
+
+    expect(() =>
+      shapes
+        .insert({
+          kind: 'square',
+          data: { sideLength: 10 },
+        })
+        .asSql(),
+    ).not.toThrow()
+
+    expect(() =>
+      shapes
+        .insert({
+          kind: 'circle',
+          data: { radius: 5 },
+        })
+        .asSql(),
+    ).not.toThrow()
+  })
 })

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,18 +369,20 @@ 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>
-
-  // 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],
-          TType extends Record<string, any> ? (K extends keyof TType ? TType[K] : TEncoded[K]) : TEncoded[K]
-        >
-      }
-    : SqliteDsl.Columns
+  export type ColumnDefForType<TEncoded, TType> = SqliteDsl.ColumnDefinition<TEncoded, TType, IsNullable<TEncoded>>
+
+  export type FromTypes<TType, TEncoded> =
+    TEncoded extends Record<string, any>
+      ? {
+          [K in keyof TEncoded]-?: ColumnDefForType<TEncoded[K],
+            TType extends Record<string, any> ? (K extends keyof TType ? TType[K] : TEncoded[K]) : TEncoded[K]
+          >
+        }
+      : SqliteDsl.Columns
 }
 
 export declare namespace TableDefInput {