@livestore/common 0.4.0 → 0.5.0-dev.0

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

@@ -1,6 +1,5 @@
-/** biome-ignore-all lint/complexity/noArguments: using arguments is fine here */
 import { casesHandled, shouldNeverHappen } from '@livestore/utils'
-import { Match, Option, Predicate, Schema } from '@livestore/utils/effect'
+import { Match, Option, Predicate, Schema, Struct } from '@livestore/utils/effect'
 
 import type { TableDefBase } from '../table-def.ts'
 import type { QueryBuilder, QueryBuilderAst } from './api.ts'
@@ -22,7 +21,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
         const [col] = params as any as [string]
         return makeQueryBuilder(tableDef, {
           ...ast,
-          resultSchemaSingle: ast.resultSchemaSingle.pipe(Schema.pluck(col)),
+          resultSchemaSingle: ast.tableDef.rowSchema.pipe(Schema.pluck(col)),
           select: { columns: [col] },
         })
       }
@@ -34,7 +33,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
       return makeQueryBuilder(tableDef, {
         ...ast,
         resultSchemaSingle:
-          columns.length === 0 ? ast.resultSchemaSingle : ast.resultSchemaSingle.pipe(Schema.pick(...columns)),
+          columns.length === 0 ? ast.resultSchemaSingle : ast.tableDef.rowSchema.mapFields(Struct.pick(columns)),
         select: { columns },
       }) as any
     },
@@ -48,8 +47,8 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
           .filter(([, value]) => value !== undefined)
           .map<QueryBuilderAst.Where>(([col, 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)
+              ? // 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 },
           )
 
@@ -125,14 +124,19 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
       return makeQueryBuilder(tableDef, { ...ast, offset: Option.some(offset) })
     },
     count: () => {
-      if (isRowQuery(ast) === true || 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, {
         _tag: 'CountQuery',
         tableDef,
         where: ast.where,
-        resultSchema: Schema.Struct({ count: Schema.Number }).pipe(
+        resultSchema: Schema.Struct({ count: Schema.Finite }).pipe(
           Schema.pluck('count'),
           Schema.Array,
           Schema.headOrElse(),
@@ -223,7 +227,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
       return makeQueryBuilder(tableDef, {
         ...ast,
         returning: columns,
-        resultSchema: tableDef.rowSchema.pipe(Schema.pick(...columns), Schema.Array),
+        resultSchema: tableDef.rowSchema.mapFields(Struct.pick(columns)).pipe(Schema.Array),
       }) as any
     },
 
@@ -316,7 +320,7 @@ export const invalidQueryBuilder = (msg?: string) => {
   return shouldNeverHappen(`Invalid query builder${msg !== undefined ? `: ${msg}` : ''}`)
 }
 
-export const getResultSchema = (qb: QueryBuilder<any, any, any>): Schema.Schema<any> => {
+export const getResultSchema = (qb: QueryBuilder<any, any, any>) => {
   const queryAst = qb[QueryBuilderAstSymbol]
   switch (queryAst._tag) {
     case 'SelectQuery': {
@@ -331,13 +335,13 @@ export const getResultSchema = (qb: QueryBuilder<any, any, any>): Schema.Schema<
         return arraySchema.pipe(Schema.headOrElse())
       } else {
         const fallbackValue = queryAst.pickFirst.fallback()
-        return Schema.Union(arraySchema, Schema.Tuple(Schema.Literal(fallbackValue))).pipe(
+        return Schema.Array(Schema.Union([queryAst.resultSchemaSingle, Schema.Literal(fallbackValue)])).pipe(
           Schema.headOrElse(() => fallbackValue),
         )
       }
     }
     case 'CountQuery': {
-      return Schema.Struct({ count: Schema.Number }).pipe(Schema.pluck('count'), Schema.Array, Schema.headOrElse())
+      return Schema.Struct({ count: Schema.Finite }).pipe(Schema.pluck('count'), Schema.Array, Schema.headOrElse())
     }
     case 'InsertQuery':
     case 'UpdateQuery':
@@ -345,16 +349,16 @@ export const getResultSchema = (qb: QueryBuilder<any, any, any>): Schema.Schema<
       // For write operations with RETURNING clause, we need to return the appropriate schema
       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)
+        return queryAst.tableDef.rowSchema.mapFields(Struct.pick(queryAst.returning)).pipe(Schema.Array)
       }
 
       // For write operations without RETURNING, the result is the number of affected rows
-      return Schema.Number
+      return Schema.Finite
     }
     case 'RowQuery': {
       return queryAst.tableDef.rowSchema.pipe(
         Schema.pluck('value'),
-        Schema.annotations({ title: `${queryAst.tableDef.sqliteDef.name}.value` }),
+        Schema.annotate({ title: `${queryAst.tableDef.sqliteDef.name}.value` }),
         Schema.Array,
         Schema.headOrElse(),
       )

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

@@ -52,6 +52,6 @@ export const getDefaultValuesDecoded = <TTableDef extends TableDefBase>(
       const defaultValue = column!.default.value
       const resolvedDefault = SqliteDsl.resolveColumnDefault(defaultValue)
 
-      return Schema.validateSync(column!.schema)(resolvedDefault)
+      return Schema.decodeSync(Schema.toType(column!.schema))(resolvedDefault)
     }),
   )

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

@@ -30,11 +30,11 @@ export const eventlogMetaTable = table({
     parentSeqNumRebaseGeneration: SqliteDsl.integer({}),
     /** Event definition name */
     name: SqliteDsl.text({}),
-    argsJson: SqliteDsl.text({ schema: Schema.parseJson(Schema.Any) }),
+    argsJson: SqliteDsl.text({ schema: Schema.fromJsonString(Schema.Any) }),
     clientId: SqliteDsl.text({}),
     sessionId: SqliteDsl.text({}),
     schemaHash: SqliteDsl.integer({}),
-    syncMetadataJson: SqliteDsl.text({ schema: Schema.parseJson(Schema.Option(Schema.JsonValue)) }),
+    syncMetadataJson: SqliteDsl.text({ schema: Schema.fromJsonString(Schema.toCodecJson(Schema.Option(Schema.Json))) }),
   },
   indexes: [
     { columns: ['seqNumGlobal'], name: 'idx_eventlog_seqNumGlobal' },

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

@@ -43,6 +43,27 @@ export const schemaEventDefsMetaTable = table({
 
 export type SchemaEventDefsMetaRow = typeof schemaEventDefsMetaTable.Type
 
+export const STATE_HEAD_META_TABLE = '__livestore_state_head'
+
+/**
+ * Single-row marker for the latest event sequence number reflected by the state DB.
+ *
+ * @remarks
+ * This is separate from the session changeset table because confirmed changesets
+ * can be removed after they are no longer needed for rollback.
+ */
+export const stateHeadMetaTable = table({
+  name: STATE_HEAD_META_TABLE,
+  columns: {
+    id: SqliteDsl.integer({ primaryKey: true }),
+    seqNumGlobal: SqliteDsl.integer({ schema: EventSequenceNumber.Global.Schema }),
+    seqNumClient: SqliteDsl.integer({ schema: EventSequenceNumber.Client.Schema }),
+    seqNumRebaseGeneration: SqliteDsl.integer({}),
+  },
+})
+
+export type StateHeadMetaRow = typeof stateHeadMetaTable.Type
+
 /**
  * Table which stores SQLite changeset blobs which is used for rolling back
  * read-model state during rebasing.
@@ -64,6 +85,25 @@ export const sessionChangesetMetaTable = table({
 
 export type SessionChangesetMetaRow = typeof sessionChangesetMetaTable.Type
 
-export const stateSystemTables = [schemaMetaTable, schemaEventDefsMetaTable, sessionChangesetMetaTable] as const
+// TODO: Rename the physical table once legacy session changeset consumers have been migrated.
+export const MATERIALIZATION_JOURNAL_META_TABLE = SESSION_CHANGESET_META_TABLE
+
+/**
+ * Materialization journal used to roll back state database changes during rebasing.
+ *
+ * @remarks
+ * This aliases the legacy table definition until all session changeset consumers
+ * have adopted the journal service.
+ */
+export const materializationJournalMetaTable = sessionChangesetMetaTable
+
+export type MaterializationJournalMetaRow = SessionChangesetMetaRow
+
+export const stateSystemTables = [
+  schemaMetaTable,
+  schemaEventDefsMetaTable,
+  stateHeadMetaTable,
+  sessionChangesetMetaTable,
+] as const
 
 export const isStateSystemTable = (tableName: string) => stateSystemTables.some((_) => _.sqliteDef.name === tableName)

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

@@ -1,8 +1,8 @@
-import { objectToString } from '@livestore/utils'
-
-import { Schema } from '@livestore/utils/effect'
+import { TestSchema } from 'effect/testing'
 import { describe, expect, expectTypeOf, it } from 'vitest'
 
+import { Schema, SchemaAST, SchemaTransformation } from '@livestore/utils/effect'
+
 import { State } from '../../mod.ts'
 
 describe('table function overloads', () => {
@@ -11,7 +11,7 @@ describe('table function overloads', () => {
       id: Schema.String,
       text: Schema.String,
       completed: Schema.Boolean,
-    }).annotations({ title: 'todos' })
+    }).annotate({ title: 'todos' })
 
     const todosTable = State.SQLite.table({
       schema: TodoSchema,
@@ -25,7 +25,7 @@ describe('table function overloads', () => {
       id: Schema.String,
       text: Schema.String,
       completed: Schema.Boolean,
-    }).annotations({ identifier: 'TodoItem' })
+    }).annotate({ identifier: 'TodoItem' })
 
     const todosTable = State.SQLite.table({ schema: TodoSchema })
 
@@ -37,7 +37,7 @@ describe('table function overloads', () => {
       id: Schema.String,
       text: Schema.String,
       completed: Schema.Boolean,
-    }).annotations({
+    }).annotate({
       title: 'todos',
       identifier: 'TodoItem',
     })
@@ -59,7 +59,7 @@ describe('table function overloads', () => {
     )
   })
 
-  it('should work with columns parameter', () => {
+  it('should work with columns parameter', async () => {
     const todosTable = State.SQLite.table({
       name: 'todos',
       columns: {
@@ -74,7 +74,6 @@ describe('table function overloads', () => {
       },
     })
 
-    expect((todosTable.rowSchema as any).fields.completed.toString()).toMatchInlineSnapshot(`"(number <-> boolean)"`)
     expect(todosTable.sqliteDef.name).toBe('todos')
     expect(todosTable.sqliteDef.columns).toHaveProperty('id')
     expect(todosTable.sqliteDef.columns).toHaveProperty('text')
@@ -82,15 +81,42 @@ describe('table function overloads', () => {
     expect(todosTable.sqliteDef.columns).toHaveProperty('optionalComplex')
 
     expect(todosTable.sqliteDef.columns.optionalBoolean.nullable).toBe(true)
-    expect(objectToString(todosTable.sqliteDef.columns.optionalBoolean.schema)).toBe('(number <-> boolean) | null')
-    expect((todosTable.rowSchema as any).fields.optionalBoolean.toString()).toBe('(number <-> boolean) | null')
+    expect(Schema.encodeSync(todosTable.sqliteDef.columns.optionalBoolean.schema)(false)).toBe(0)
 
     expect(todosTable.sqliteDef.columns.optionalComplex.nullable).toBe(true)
-    expect(objectToString(todosTable.sqliteDef.columns.optionalComplex.schema)).toBe(
-      '(parseJson <-> { readonly color: string } | undefined) | null',
+
+    const asserts = new TestSchema.Asserts(todosTable.rowSchema)
+    await asserts.decoding().succeed(
+      {
+        id: 'todo-1',
+        text: 'Buy milk',
+        completed: 1,
+        optionalBoolean: null,
+        optionalComplex: JSON.stringify({ color: 'red' }),
+      },
+      {
+        id: 'todo-1',
+        text: 'Buy milk',
+        completed: true,
+        optionalBoolean: null,
+        optionalComplex: { color: 'red' },
+      },
     )
-    expect((todosTable.rowSchema as any).fields.optionalComplex.toString()).toBe(
-      '(parseJson <-> { readonly color: string } | undefined) | null',
+    await asserts.decoding().succeed(
+      {
+        id: 'todo-1',
+        text: 'Buy milk',
+        completed: 0,
+        optionalBoolean: null,
+        optionalComplex: null,
+      },
+      {
+        id: 'todo-1',
+        text: 'Buy milk',
+        completed: false,
+        optionalBoolean: null,
+        optionalComplex: null,
+      },
     )
   })
 
@@ -205,32 +231,33 @@ describe('table function overloads', () => {
       contactEmail: Schema.String.pipe(State.SQLite.withUnique),
     })
 
-    const Nested = Schema.transform(
-      Flat,
-      Schema.Struct({
-        id: Schema.String,
-        contact: Schema.Struct({
-          firstName: Schema.String,
-          lastName: Schema.String,
-          email: Schema.String,
-        }),
-      }),
-      {
-        decode: ({ id, contactFirstName, contactLastName, contactEmail }) => ({
-          id,
-          contact: {
-            firstName: contactFirstName,
-            lastName: contactLastName,
-            email: contactEmail,
-          },
+    const Nested = Flat.pipe(
+      Schema.decodeTo(
+        Schema.Struct({
+          id: Schema.String,
+          contact: Schema.Struct({
+            firstName: Schema.String,
+            lastName: Schema.String,
+            email: Schema.String,
+          }),
         }),
-        encode: ({ id, contact }) => ({
-          id,
-          contactFirstName: contact.firstName,
-          contactLastName: contact.lastName,
-          contactEmail: contact.email,
+        SchemaTransformation.transform({
+          decode: ({ id, contactFirstName, contactLastName, contactEmail }) => ({
+            id,
+            contact: {
+              firstName: contactFirstName,
+              lastName: contactLastName,
+              email: contactEmail,
+            },
+          }),
+          encode: ({ id, contact }) => ({
+            id,
+            contactFirstName: contact.firstName,
+            contactLastName: contact.lastName,
+            contactEmail: contact.email,
+          }),
         }),
-      },
+      ),
     )
 
     const contactsTable = State.SQLite.table({
@@ -266,13 +293,13 @@ describe('table function overloads', () => {
     expect(todosTable.sqliteDef.name).toBe('TodoItem')
   })
 
-  it('should properly infer types from schema', () => {
+  it('should properly infer types from schema', async () => {
     const UserSchema = Schema.Struct({
       id: Schema.String,
       name: Schema.String,
       age: Schema.Int,
       active: Schema.Boolean,
-      metadata: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+      metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
     })
 
     const userTable = State.SQLite.table({
@@ -297,13 +324,6 @@ describe('table function overloads', () => {
     type ActiveColumn = typeof userTable.sqliteDef.columns.active
     type MetadataColumn = typeof userTable.sqliteDef.columns.metadata
 
-    // Should derive proper column schema
-    expect((userTable.rowSchema as any).fields.age.toString()).toMatchInlineSnapshot(`"Int"`)
-    expect((userTable.rowSchema as any).fields.active.toString()).toMatchInlineSnapshot(`"(number <-> boolean)"`)
-    expect((userTable.rowSchema as any).fields.metadata.toString()).toMatchInlineSnapshot(
-      `"(parseJson <-> { readonly [x: string]: unknown }) | null"`,
-    )
-
     // These should compile without errors
     const _idCheck: IdColumn['schema']['Type'] = 'string'
     const _nameCheck: NameColumn['schema']['Type'] = 'string'
@@ -318,6 +338,28 @@ describe('table function overloads', () => {
     expect(userTable.sqliteDef.columns.active.columnType).toBe('integer')
     expect(userTable.sqliteDef.columns.metadata.columnType).toBe('text')
     expect(userTable.sqliteDef.columns.metadata.nullable).toBe(true)
+
+    const asserts = new TestSchema.Asserts(userTable.rowSchema)
+    await asserts.decoding().succeed(
+      {
+        id: 'test-id',
+        name: 'John',
+        age: 30,
+        active: 1,
+        metadata: JSON.stringify({ key1: 'value1', key2: 123 }),
+      },
+      {
+        id: 'test-id',
+        name: 'John',
+        age: 30,
+        active: true,
+        metadata: { key1: 'value1', key2: 123 },
+      },
+    )
+    const activeAsserts = new TestSchema.Asserts(userTable.sqliteDef.columns.active.schema)
+    const metadataAsserts = new TestSchema.Asserts(userTable.sqliteDef.columns.metadata.schema)
+    await activeAsserts.decoding().succeed(0, false)
+    await metadataAsserts.decoding().succeed(null)
   })
 
   it('should allow omitting nullable fields in insert()', () => {
@@ -347,41 +389,117 @@ describe('table function overloads', () => {
       .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' })
+      .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()
+    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,
+      radius: Schema.Finite,
     })
     const CircleSchema = Schema.Struct({
       kind: Schema.Literal('circle'),
-      data: Schema.parseJson(CircleDataSchema),
+      data: Schema.fromJsonString(CircleDataSchema),
     })
 
     const SquareDataSchema = Schema.Struct({
-      sideLength: Schema.Number,
+      sideLength: Schema.Finite,
     })
     const SquareSchema = Schema.Struct({
       kind: Schema.Literal('square'),
-      data: Schema.parseJson(SquareDataSchema),
+      data: Schema.fromJsonString(SquareDataSchema),
     })
 
-    const ShapeSchema = Schema.Union(CircleSchema, SquareSchema)
+    const ShapeSchema = Schema.Union([CircleSchema, SquareSchema])
 
     const shapes = State.SQLite.table({
       name: 'shapes',
@@ -389,9 +507,7 @@ describe('table function overloads', () => {
     })
 
     expect(shapes.sqliteDef.columns.kind.columnType).toBe('text')
-
-    const kindSchema = objectToString(shapes.sqliteDef.columns.kind.schema)
-    expect(kindSchema).toContain('"circle" | "square"')
+    expect(SchemaAST.isUnion(Schema.toEncoded(shapes.sqliteDef.columns.kind.schema).ast)).toBe(true)
 
     expect(() =>
       shapes
@@ -411,4 +527,26 @@ describe('table function overloads', () => {
         .asSql(),
     ).not.toThrow()
   })
+
+  it('treats optional common union fields as nullable columns', () => {
+    const StateSchema = Schema.Union([
+      Schema.Struct({
+        kind: Schema.Literal('empty'),
+        note: Schema.optional(Schema.String),
+      }),
+      Schema.Struct({
+        kind: Schema.Literal('ready'),
+        note: Schema.optional(Schema.String),
+      }),
+    ])
+
+    const states = State.SQLite.table({
+      name: 'states',
+      schema: StateSchema,
+    })
+
+    expect(states.sqliteDef.columns.kind.columnType).toBe('text')
+    expect(states.sqliteDef.columns.note.columnType).toBe('text')
+    expect(states.sqliteDef.columns.note.nullable).toBe(true)
+  })
 })