@livestore/common 0.4.0-dev.8 → 0.4.0

package/src/schema/LiveStoreEvent/global.ts

@@ -0,0 +1,45 @@
+import { Schema } from '@livestore/utils/effect'
+
+import * as EventSequenceNumber from '../EventSequenceNumber/mod.ts'
+
+/**
+ * Effect Schema for global events with integer sequence numbers.
+ * @example
+ * ```ts
+ * const event: LiveStoreEvent.Global.Encoded = {
+ *   name: 'todoCreated-v1',
+ *   args: { id: 'abc', text: 'Buy milk' },
+ *   seqNum: 5,       // This event's position in the global log
+ *   parentSeqNum: 4, // Points to the previous event
+ *   clientId: 'client-xyz',
+ *   sessionId: 'session-123'
+ * }
+ * ```
+ */
+export const Encoded = Schema.Struct({
+  name: Schema.String,
+  args: Schema.Any,
+  seqNum: EventSequenceNumber.Global.Schema,
+  parentSeqNum: EventSequenceNumber.Global.Schema,
+  clientId: Schema.String,
+  sessionId: Schema.String,
+}).annotations({ title: 'LiveStoreEvent.Global.Encoded' })
+
+/** Event with integer sequence numbers for sync backend wire format. */
+export type Encoded = typeof Encoded.Type
+
+/** Converts a Global event to Client format by expanding integer seqNums to composite form. */
+export const toClientEncoded = (
+  event: Encoded,
+): {
+  name: string
+  args: any
+  seqNum: EventSequenceNumber.Client.Composite
+  parentSeqNum: EventSequenceNumber.Client.Composite
+  clientId: string
+  sessionId: string
+} => ({
+  ...event,
+  seqNum: EventSequenceNumber.Client.fromGlobal(event.seqNum),
+  parentSeqNum: EventSequenceNumber.Client.fromGlobal(event.parentSeqNum),
+})

package/src/schema/LiveStoreEvent/input.ts

@@ -0,0 +1,63 @@
+import { Schema } from '@livestore/utils/effect'
+
+import type { EventDef, EventDefRecord } from '../EventDef/mod.ts'
+import type { LiveStoreSchema } from '../schema.ts'
+import type * as ForEventDef from './for-event-def.ts'
+
+/**
+ * Effect Schema for validating/decoding input events with encoded args.
+ * @example
+ * ```ts
+ * import { Schema } from '@effect/schema'
+ * const decoded = Schema.decodeUnknownSync(LiveStoreEvent.Input.Encoded)(rawEvent)
+ * ```
+ */
+export const Encoded = Schema.Struct({
+  name: Schema.String,
+  args: Schema.Any,
+}).annotations({ title: 'LiveStoreEvent.Input.Encoded' })
+
+/** Event without sequence numbers, with decoded (native TypeScript) args. */
+export type Decoded = ForEventDef.InputDecoded<EventDef.Any>
+
+/** Event without sequence numbers, with encoded (serialized) args. */
+export type Encoded = ForEventDef.InputEncoded<EventDef.Any>
+
+/** Union of all input event types for a given schema (type-safe event discrimination). */
+export type ForSchema<TSchema extends LiveStoreSchema> = {
+  [K in keyof TSchema['_EventDefMapType']]: ForEventDef.InputDecoded<TSchema['_EventDefMapType'][K]>
+}[keyof TSchema['_EventDefMapType']]
+
+/** Effect Schema union of all event types in an EventDefRecord (input format, no sequence numbers). */
+export type ForRecord<TEventDefRecord extends EventDefRecord> = Schema.Schema<
+  {
+    [K in keyof TEventDefRecord]: {
+      name: K
+      args: Schema.Schema.Type<TEventDefRecord[K]['schema']>
+    }
+  }[keyof TEventDefRecord],
+  {
+    [K in keyof TEventDefRecord]: {
+      name: K
+      args: Schema.Schema.Encoded<TEventDefRecord[K]['schema']>
+    }
+  }[keyof TEventDefRecord]
+>
+
+/**
+ * Creates an Effect Schema union for all event types in a schema (input format, no sequence numbers).
+ * @example
+ * ```ts
+ * const inputSchema = LiveStoreEvent.Input.makeSchema(schema)
+ * const event = Schema.decodeUnknownSync(inputSchema)(rawEvent)
+ * ```
+ */
+export const makeSchema = <TSchema extends LiveStoreSchema>(schema: TSchema): ForRecord<TSchema['_EventDefMapType']> =>
+  Schema.Union(
+    ...[...schema.eventsDefsMap.values()].map((def) =>
+      Schema.Struct({
+        name: Schema.Literal(def.name),
+        args: def.schema,
+      }),
+    ),
+  ).annotations({ title: 'LiveStoreEvent.Input' }) as any

package/src/schema/LiveStoreEvent/mod.ts

@@ -0,0 +1,4 @@
+export * as Client from './client.ts'
+export * as ForEventDef from './for-event-def.ts'
+export * as Global from './global.ts'
+export * as Input from './input.ts'

package/src/schema/events.ts

@@ -1 +1 @@
-export { clientOnly, defineEvent, synced } from './EventDef.ts'
+export { clientOnly, defineEvent, synced } from './EventDef/mod.ts'

package/src/schema/mod.ts

@@ -1,9 +1,11 @@
-export * from './EventDef.ts'
-export * as EventSequenceNumber from './EventSequenceNumber.ts'
+export * from './EventDef/mod.ts'
+export * as EventSequenceNumber from './EventSequenceNumber/mod.ts'
 export * as Events from './events.ts'
-export * as LiveStoreEvent from './LiveStoreEvent.ts'
+export * as LiveStoreEvent from './LiveStoreEvent/mod.ts'
 export * from './schema.ts'
 export * as State from './state/mod.ts'
 export { SqliteAst, SqliteDsl } from './state/sqlite/db-schema/mod.ts'
 export * from './state/sqlite/schema-helpers.ts'
-export * as SystemTables from './state/sqlite/system-tables.ts'
+export * as SystemTables from './state/sqlite/system-tables/mod.ts'
+export type { UnknownEvents } from './unknown-events.ts'
+export { normalizeUnknownEventHandling, resolveEventDef } from './unknown-events.ts'

package/src/schema/schema.ts

@@ -1,15 +1,19 @@
 import { isReadonlyArray, shouldNeverHappen } from '@livestore/utils'
 
 import type { MigrationOptions } from '../adapter-types.ts'
-import type { EventDef, EventDefRecord, Materializer } from './EventDef.ts'
+import type { EventDef, EventDefRecord, Materializer } from './EventDef/mod.ts'
 import { tableIsClientDocumentTable } from './state/sqlite/client-document-def.ts'
 import type { SqliteDsl } from './state/sqlite/db-schema/mod.ts'
-import { stateSystemTables } from './state/sqlite/system-tables.ts'
+import { stateSystemTables } from './state/sqlite/system-tables/state-tables.ts'
 import type { TableDef } from './state/sqlite/table-def.ts'
+import type { UnknownEvents } from './unknown-events.ts'
+import { normalizeUnknownEventHandling } from './unknown-events.ts'
 
 export const LiveStoreSchemaSymbol = Symbol.for('livestore.LiveStoreSchema')
 export type LiveStoreSchemaSymbol = typeof LiveStoreSchemaSymbol
 
+export const UNKNOWN_EVENT_SCHEMA_HASH = -1
+
 export interface LiveStoreSchema<
   TDbSchema extends SqliteDsl.DbSchema = SqliteDsl.DbSchema,
   TEventsDefRecord extends EventDefRecord = EventDefRecord,
@@ -22,6 +26,7 @@ export interface LiveStoreSchema<
 
   readonly state: InternalState
   readonly eventsDefsMap: Map<string, EventDef.AnyWithoutFn>
+  readonly unknownEventHandling: UnknownEvents.HandlingConfig
   readonly devtools: {
     /** @default 'default' */
     readonly alias: string
@@ -32,6 +37,35 @@ export namespace LiveStoreSchema {
   export type Any = LiveStoreSchema<any, any>
 }
 
+/**
+ * Runtime type guard for LiveStoreSchema.
+ *
+ * The guard intentionally performs lightweight structural checks that are
+ * stable across implementations. It verifies the identifying symbol marker
+ * and the presence of core maps/state used at runtime.
+ */
+export const isLiveStoreSchema = (value: unknown): value is LiveStoreSchema<any, any> => {
+  if (typeof value !== 'object' || value === null) return false
+
+  const v: any = value
+
+  // Identity marker must match exactly
+  if (v.LiveStoreSchemaSymbol !== LiveStoreSchemaSymbol) return false
+
+  // Core structures used at runtime
+  const hasEventsMap = v.eventsDefsMap instanceof Map
+  const hasStateSqliteTables = v.state?.sqlite?.tables instanceof Map
+  const hasStateMaterializers = v.state?.materializers instanceof Map
+  const hasDevtoolsAlias = typeof v.devtools?.alias === 'string'
+
+  return (
+    hasEventsMap === true &&
+    hasStateSqliteTables === true &&
+    hasStateMaterializers === true &&
+    hasDevtoolsAlias === true
+  )
+}
+
 // TODO abstract this further away from sqlite/tables
 export interface InternalState {
   readonly sqlite: {
@@ -55,6 +89,10 @@ export interface InputSchema {
      */
     readonly alias?: string
   }
+  /**
+   * Configures how unknown events should be handled. Defaults to `{ strategy: 'warn' }`.
+   */
+  readonly unknownEventHandling?: UnknownEvents.HandlingConfig
 }
 
 export const makeSchema = <TInputSchema extends InputSchema>(
@@ -70,13 +108,13 @@ export const makeSchema = <TInputSchema extends InputSchema>(
 
   const eventsDefsMap = new Map<string, EventDef.AnyWithoutFn>()
 
-  if (isReadonlyArray(inputSchema.events)) {
+  if (isReadonlyArray(inputSchema.events) === true) {
     for (const eventDef of inputSchema.events) {
       eventsDefsMap.set(eventDef.name, eventDef)
     }
   } else {
     for (const eventDef of Object.values(inputSchema.events ?? {})) {
-      if (eventsDefsMap.has(eventDef.name)) {
+      if (eventsDefsMap.has(eventDef.name) === true) {
         shouldNeverHappen(`Duplicate event name: ${eventDef.name}. Please use unique names for events.`)
       }
       eventsDefsMap.set(eventDef.name, eventDef)
@@ -84,17 +122,20 @@ export const makeSchema = <TInputSchema extends InputSchema>(
   }
 
   for (const tableDef of tables.values()) {
-    if (tableIsClientDocumentTable(tableDef) && eventsDefsMap.has(tableDef.set.name) === false) {
+    if (tableIsClientDocumentTable(tableDef) === true && eventsDefsMap.has(tableDef.set.name) === false) {
       eventsDefsMap.set(tableDef.set.name, tableDef.set)
     }
   }
 
+  const unknownEventHandling = normalizeUnknownEventHandling(inputSchema.unknownEventHandling)
+
   return {
     LiveStoreSchemaSymbol,
     _DbSchemaType: Symbol.for('livestore.DbSchemaType') as any,
     _EventDefMapType: Symbol.for('livestore.EventDefMapType') as any,
     state,
     eventsDefsMap,
+    unknownEventHandling,
     devtools: {
       alias: inputSchema.devtools?.alias ?? 'default',
     },

package/src/schema/state/sqlite/client-document-def.test.ts

@@ -1,9 +1,16 @@
-import { Schema } from '@livestore/utils/effect'
 import { describe, expect, test } from 'vitest'
 
+import { Schema } from '@livestore/utils/effect'
+
 import { tables } from '../../../__tests__/fixture.ts'
-import type * as LiveStoreEvent from '../../LiveStoreEvent.ts'
-import { ClientDocumentTableDefSymbol, clientDocument, mergeDefaultValues } from './client-document-def.ts'
+import type * as LiveStoreEvent from '../../LiveStoreEvent/mod.ts'
+import {
+  ClientDocumentTableDefSymbol,
+  clientDocument,
+  createOptimisticEventSchema,
+  mergeDefaultValues,
+} from './client-document-def.ts'
+import { getResultSchema } from './query-builder/impl.ts'
 
 describe('client document table', () => {
   test('set event', () => {
@@ -248,14 +255,146 @@ describe('client document table', () => {
       `)
     })
   })
+
+  /** Ensures optimistic decoding stays robust when persisted JSON is incompatible. */
+  describe('optimistic schema', () => {
+    /** Models persisted JSON using epoch numbers + base64 while app code expects Date + Uint8Array. */
+    const valueSchema = Schema.Struct({
+      createdAt: Schema.DateFromNumber,
+      avatar: Schema.Uint8ArrayFromBase64,
+    })
+    const defaultValue = {
+      createdAt: new Date(0),
+      avatar: new Uint8Array(),
+    }
+    const invalidPayloads: Array<{ label: string; value: unknown }> = [
+      { label: 'decoded-shape JSON', value: { createdAt: new Date(0), avatar: new Uint8Array([1, 2]) } },
+      { label: 'wrong types', value: { createdAt: 'not-a-number', avatar: { nested: 'bad' } } },
+      { label: 'missing required fields', value: {} },
+    ]
+    const validPayload = { createdAt: 42, avatar: 'AQI=' }
+    const extraFieldsPayload = { createdAt: 42, avatar: 'AQI=', extra: 'ignored' }
+
+    test.each(invalidPayloads)('decodes invalid persisted JSON ($label)', ({ value }) => {
+      const optimisticSchema = createOptimisticEventSchema({
+        valueSchema,
+        defaultValue,
+        partialSet: false,
+      })
+      const rowSchema = Schema.parseJson(optimisticSchema)
+
+      expect(Schema.decodeUnknownSync(rowSchema)(JSON.stringify(value))).toEqual(defaultValue)
+    })
+
+    test('decodes valid persisted JSON (encoded shape)', () => {
+      const optimisticSchema = createOptimisticEventSchema({
+        valueSchema,
+        defaultValue,
+        partialSet: false,
+      })
+      const rowSchema = Schema.parseJson(optimisticSchema)
+
+      expect(Schema.decodeUnknownSync(rowSchema)(JSON.stringify(validPayload))).toEqual({
+        createdAt: new Date(42),
+        avatar: new Uint8Array([1, 2]),
+      })
+    })
+
+    test('decodes valid persisted JSON with extra fields', () => {
+      const optimisticSchema = createOptimisticEventSchema({
+        valueSchema,
+        defaultValue,
+        partialSet: false,
+      })
+      const rowSchema = Schema.parseJson(optimisticSchema)
+
+      expect(Schema.decodeUnknownSync(rowSchema)(JSON.stringify(extraFieldsPayload))).toEqual({
+        createdAt: new Date(42),
+        avatar: new Uint8Array([1, 2]),
+      })
+    })
+
+    test.each(invalidPayloads)('decodes clientDocument rowSchema with invalid JSON ($label)', ({ value }) => {
+      const Doc = clientDocument({
+        name: 'test_numbers',
+        schema: valueSchema,
+        default: { value: defaultValue },
+        partialSet: false,
+      })
+      const row = {
+        id: 'row-1',
+        value: JSON.stringify(value),
+      }
+
+      expect(Schema.decodeUnknownSync(Doc.rowSchema)(row)).toEqual({ id: 'row-1', value: defaultValue })
+    })
+
+    test('decodes clientDocument rowSchema with valid encoded JSON', () => {
+      const Doc = clientDocument({
+        name: 'test_numbers',
+        schema: valueSchema,
+        default: { value: defaultValue },
+        partialSet: false,
+      })
+      const row = {
+        id: 'row-1',
+        value: JSON.stringify(validPayload),
+      }
+
+      expect(Schema.decodeUnknownSync(Doc.rowSchema)(row)).toEqual({
+        id: 'row-1',
+        value: { createdAt: new Date(42), avatar: new Uint8Array([1, 2]) },
+      })
+    })
+
+    test.each(invalidPayloads)('decodes RowQuery result schema with invalid JSON ($label)', ({ value }) => {
+      const Doc = clientDocument({
+        name: 'test_numbers',
+        schema: valueSchema,
+        default: { value: defaultValue },
+        partialSet: false,
+      })
+      const query = Doc.get('row-1')
+      const resultSchema = getResultSchema(query)
+      const rawDbResults = [
+        {
+          id: 'row-1',
+          value: JSON.stringify(value),
+        },
+      ]
+
+      expect(Schema.decodeUnknownSync(resultSchema)(rawDbResults)).toEqual(defaultValue)
+    })
+
+    test('decodes RowQuery result schema with valid encoded JSON', () => {
+      const Doc = clientDocument({
+        name: 'test_numbers',
+        schema: valueSchema,
+        default: { value: defaultValue },
+        partialSet: false,
+      })
+      const query = Doc.get('row-1')
+      const resultSchema = getResultSchema(query)
+      const rawDbResults = [
+        {
+          id: 'row-1',
+          value: JSON.stringify(validPayload),
+        },
+      ]
+
+      expect(Schema.decodeUnknownSync(resultSchema)(rawDbResults)).toEqual({
+        createdAt: new Date(42),
+        avatar: new Uint8Array([1, 2]),
+      })
+    })
+  })
 })
 
-const patchId = (muationEvent: LiveStoreEvent.PartialAnyDecoded) => {
+const patchId = (muationEvent: LiveStoreEvent.Input.Decoded) => {
   // TODO use new id paradigm
   const id = `00000000-0000-0000-0000-000000000000`
   return { ...muationEvent, id }
 }
-
 describe('mergeDefaultValues', () => {
   test('merges values from both objects', () => {
     const defaults = { a: 1, b: 2 }

package/src/schema/state/sqlite/client-document-def.ts

@@ -4,8 +4,8 @@ import { Schema } from '@livestore/utils/effect'
 
 import { SessionIdSymbol } from '../../../adapter-types.ts'
 import { sql } from '../../../util.ts'
-import type { EventDef, Materializer } from '../../EventDef.ts'
-import { defineEvent, defineMaterializer } from '../../EventDef.ts'
+import type { EventDef, Materializer } from '../../EventDef/mod.ts'
+import { defineEvent, defineMaterializer } from '../../EventDef/mod.ts'
 import { SqliteDsl } from './db-schema/mod.ts'
 import type { QueryBuilder, QueryBuilderAst } from './query-builder/mod.ts'
 import { QueryBuilderAstSymbol, QueryBuilderTypeId } from './query-builder/mod.ts'
@@ -95,10 +95,12 @@ export const clientDocument = <
   Object.defineProperty(setEventDef, 'schema', {
     value: Schema.Struct({
       id: Schema.String,
-      value: options.partialSet ? Schema.partial(valueSchema) : valueSchema,
+      value: options.partialSet === true ? Schema.partial(valueSchema) : valueSchema,
     }).annotations({ title: `${name}Set:Args` }),
   })
-  Object.defineProperty(setEventDef, 'options', { value: { derived: true, clientOnly: true, facts: undefined } })
+  Object.defineProperty(setEventDef, 'options', {
+    value: { derived: true, clientOnly: true, facts: undefined, deprecated: undefined },
+  })
 
   const clientDocumentTableDefTrait: ClientDocumentTableDef.Trait<
     TName,
@@ -106,20 +108,26 @@ export const clientDocument = <
     TEncoded,
     ClientDocumentTableOptions<TType>
   > = {
+    // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- dynamic table def composition; type safety ensured by ClientDocumentTableDef.Trait
     get: makeGetQueryBuilder(() => clientDocumentTableDef) as any,
+    // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- dynamic table def composition; type safety ensured by SetEventDefLike signature
     set: setEventDef as any,
+    // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- phantom type field for generic inference only
     Value: 'only-for-type-inference' as any,
     default: options.default,
     valueSchema,
     [ClientDocumentTableDefSymbol]: {
       derived: {
+        // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- dynamic event def composition; type checked at usage sites
         setEventDef: derivedSetEventDef as any,
+        // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- dynamic materializer composition; type checked at usage sites
         setMaterializer: derivedSetMaterializer as any,
       },
       options,
     },
   }
 
+  // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- composing tableDef + clientDocumentTableDefTrait into final type; validated by satisfies above
   const clientDocumentTableDef = {
     ...tableDef,
     ...clientDocumentTableDefTrait,
@@ -139,11 +147,14 @@ export const mergeDefaultValues = <T>(defaultValues: T, explicitDefaultValues: T
   }
 
   // Get all unique keys from both objects
+  // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Object.keys requires indexable type; T is constrained to object by preceding typeof checks
   const allKeys = new Set([...Object.keys(defaultValues as any), ...Object.keys(explicitDefaultValues as any)])
 
   return Array.from(allKeys).reduce((acc, key) => {
+    // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- dynamic key access on generic object; keys validated from Object.keys above
     acc[key] = (explicitDefaultValues as any)[key] ?? (defaultValues as any)[key]
     return acc
+    // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- reduce accumulator type; result type is T
   }, {} as any)
 }
 
@@ -175,7 +186,10 @@ export const createOptimisticEventSchema = ({
   defaultValue: any
   partialSet: boolean
 }) => {
-  const targetSchema = partialSet ? Schema.partial(valueSchema) : valueSchema
+  const targetSchema = partialSet === true ? Schema.partial(valueSchema) : valueSchema
+  // The transform decode must yield values in the target schema's ENCODED shape.
+  // This keeps JSON columns consistent when Encoded != Type (e.g. Option).
+  const encodeTarget = Schema.encodeSync(targetSchema)
 
   return Schema.transform(
     Schema.Unknown, // Accept any historical event structure
@@ -184,17 +198,21 @@ export const createOptimisticEventSchema = ({
       decode: (eventValue) => {
         // Try direct decode first (for current schema events)
         try {
-          return Schema.decodeUnknownSync(targetSchema)(eventValue)
+          const decoded = Schema.decodeUnknownSync(targetSchema)(eventValue)
+          // Re-encode so downstream parseJson/column decoding sees encoded values.
+          return encodeTarget(decoded)
         } catch {
           // Optimistic decoding for historical events
 
           // Handle null/undefined/non-object cases
           if (typeof eventValue !== 'object' || eventValue === null) {
-            console.warn(`Client document: Non-object event value, using ${partialSet ? 'empty partial' : 'defaults'}`)
-            return partialSet ? {} : defaultValue
+            console.warn(
+              `Client document: Non-object event value, using ${partialSet === true ? 'empty partial' : 'defaults'}`,
+            )
+            return encodeTarget(partialSet === true ? {} : defaultValue)
           }
 
-          if (partialSet) {
+          if (partialSet === true) {
             // For partial sets: only preserve fields that exist in new schema
             const partialResult: Record<string, unknown> = {}
             let hasValidFields = false
@@ -207,16 +225,17 @@ export const createOptimisticEventSchema = ({
               // Drop fields that don't exist in new schema
             }
 
-            if (hasValidFields) {
+            if (hasValidFields === true) {
               try {
-                return Schema.decodeUnknownSync(targetSchema)(partialResult)
+                const decoded = Schema.decodeUnknownSync(targetSchema)(partialResult)
+                return encodeTarget(decoded)
               } catch {
                 // Even filtered fields don't match schema
                 console.warn('Client document: Partial fields incompatible, returning empty partial')
-                return {}
+                return encodeTarget({})
               }
             }
-            return {}
+            return encodeTarget({})
           } else {
             // Full set: merge old data with new defaults
             const merged: Record<string, unknown> = { ...defaultValue }
@@ -231,12 +250,13 @@ export const createOptimisticEventSchema = ({
 
             // Try to decode the merged value
             try {
-              return Schema.decodeUnknownSync(valueSchema)(merged)
+              const decoded = Schema.decodeUnknownSync(valueSchema)(merged)
+              return encodeTarget(decoded)
             } catch {
               // Merged value still doesn't match (e.g., type changes)
               // Fall back to pure defaults
               console.warn('Client document: Could not preserve event data, using defaults')
-              return defaultValue
+              return encodeTarget(defaultValue)
             }
           }
         }
@@ -357,11 +377,14 @@ const makeGetQueryBuilder = <TTableDef extends ClientDocumentTableDef<any, any,
     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 any,
       asSql: () => ({ query, bindValues: [id] }),
       toString: () => query.toString(),
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- spreading empty object to satisfy QueryBuilder interface requirements
       ...({} as any), // Needed for type cast
     }
+    // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- makeGetQueryBuilder return type uses complex conditional generics
   }) as any
 }
 
@@ -513,27 +536,17 @@ export namespace ClientDocumentTableDef {
     }
   }
 
-  export type GetOptions<TTableDef extends TraitAny> = TTableDef extends ClientDocumentTableDef.Trait<
-    any,
-    any,
-    any,
-    infer TOptions
-  >
-    ? TOptions
-    : never
+  export type GetOptions<TTableDef extends TraitAny> =
+    TTableDef extends ClientDocumentTableDef.Trait<any, any, any, infer TOptions> ? TOptions : never
 
   export type TraitAny = Trait<any, any, any, any>
 
-  export type DefaultIdType<TTableDef extends TraitAny> = TTableDef extends ClientDocumentTableDef.Trait<
-    any,
-    any,
-    any,
-    infer TOptions
-  >
-    ? TOptions['default']['id'] extends SessionIdSymbol | string
-      ? TOptions['default']['id']
+  export type DefaultIdType<TTableDef extends TraitAny> =
+    TTableDef extends ClientDocumentTableDef.Trait<any, any, any, infer TOptions>
+      ? TOptions['default']['id'] extends SessionIdSymbol | string
+        ? TOptions['default']['id']
+        : never
       : never
-    : never
 
   export type SetEventDefLike<
     TName extends string,
@@ -554,7 +567,7 @@ export namespace ClientDocumentTableDef {
       readonly name: `${TName}Set`
       readonly args: { id: string; value: TType }
     }
-    readonly options: { derived: true; clientOnly: true; facts: undefined }
+    readonly options: { derived: true; clientOnly: true; facts: undefined; deprecated: undefined }
   }
 
   export type SetEventDef<TName extends string, TType, TOptions extends ClientDocumentTableOptions<TType>> = EventDef<
@@ -579,5 +592,5 @@ export namespace ClientDocumentTableDef {
       ) => QueryBuilder<TType, ClientDocumentTableDef.TableDefBase_<TName, TType>, QueryBuilder.ApiFeature>
 }
 
-export const ClientDocumentTableDefSymbol = Symbol('ClientDocumentTableDef')
+export const ClientDocumentTableDefSymbol = Symbol.for('livestore.ClientDocumentTableDef')
 export type ClientDocumentTableDefSymbol = typeof ClientDocumentTableDefSymbol

package/src/schema/state/sqlite/column-annotations.test.ts

@@ -1,6 +1,7 @@
-import { Schema, SchemaAST } from '@livestore/utils/effect'
 import { describe, expect, test } from 'vitest'
 
+import { Schema, SchemaAST } from '@livestore/utils/effect'
+
 import { withColumnType, withPrimaryKey } from './column-annotations.ts'
 
 describe.concurrent('annotations', () => {
@@ -65,7 +66,7 @@ describe.concurrent('annotations', () => {
       })
 
       test('Union of same type with compatible column type', () => {
-        const unionSchema = Schema.Union(Schema.Literal('a'), Schema.Literal('b'))
+        const unionSchema = Schema.Literal('a', 'b')
         expect(() => withColumnType(unionSchema, 'text')).not.toThrow()
       })
 

package/src/schema/state/sqlite/column-annotations.ts

@@ -1,5 +1,6 @@
 import type { Schema } from '@livestore/utils/effect'
 import { dual, Option, SchemaAST } from '@livestore/utils/effect'
+
 import type { SqliteDsl } from './db-schema/mod.ts'
 
 export const PrimaryKeyId = Symbol.for('livestore/state/sqlite/annotations/primary-key')
@@ -79,7 +80,7 @@ const validateSchemaColumnTypeCompatibility = (
 const applyAnnotations = <T extends Schema.Schema.All>(schema: T, overrides: Record<PropertyKey, unknown>): T => {
   const identifier = SchemaAST.getIdentifierAnnotation(schema.ast)
   const shouldPreserveIdentifier = Option.isSome(identifier) && !(SchemaAST.IdentifierAnnotationId in overrides)
-  const annotations: Record<PropertyKey, unknown> = shouldPreserveIdentifier
+  const annotations: Record<PropertyKey, unknown> = shouldPreserveIdentifier === true
     ? { ...overrides, [SchemaAST.IdentifierAnnotationId]: identifier.value }
     : overrides