@livestore/common 0.4.0-dev.0 → 0.4.0-dev.10

package/src/schema/schema.ts

@@ -6,10 +6,14 @@ import { tableIsClientDocumentTable } from './state/sqlite/client-document-def.t
 import type { SqliteDsl } from './state/sqlite/db-schema/mod.ts'
 import { stateSystemTables } from './state/sqlite/system-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,30 @@ 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 && hasStateSqliteTables && hasStateMaterializers && hasDevtoolsAlias
+}
+
 // TODO abstract this further away from sqlite/tables
 export interface InternalState {
   readonly sqlite: {
@@ -55,6 +84,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>(
@@ -89,12 +122,15 @@ export const makeSchema = <TInputSchema extends InputSchema>(
     }
   }
 
+  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',
     },
@@ -110,7 +146,7 @@ export const getEventDef = <TSchema extends LiveStoreSchema>(
 } => {
   const eventDef = schema.eventsDefsMap.get(eventName)
   if (eventDef === undefined) {
-    return shouldNeverHappen(`No mutation definition found for \`${eventName}\`.`)
+    return shouldNeverHappen(`No event definition found for \`${eventName}\`.`)
   }
   const materializer = schema.state.materializers.get(eventName)
   if (materializer === undefined) {

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

@@ -50,6 +50,7 @@ describe('client document table', () => {
         currentFacts: new Map(),
         query: {} as any, // unused
         eventDef: Doc[ClientDocumentTableDefSymbol].derived.setEventDef,
+        event: {} as any, // unused in this test
       })
     }
 
@@ -230,6 +231,22 @@ describe('client document table', () => {
         }
       `)
     })
+
+    test('any value (Schema.Any) should fully replace', () => {
+      expect(forSchema(Schema.Any, { a: 1 }, 'id1')).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "id1",
+            "{"a":1}",
+            "{"a":1}",
+          ],
+          "sql": "INSERT INTO 'test' (id, value) VALUES (?, ?) ON CONFLICT (id) DO UPDATE SET value = ?",
+          "writeTables": Set {
+            "test",
+          },
+        }
+      `)
+    })
   })
 })
 

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

@@ -1,6 +1,6 @@
 import { shouldNeverHappen } from '@livestore/utils'
 import type { Option, Types } from '@livestore/utils/effect'
-import { Schema, SchemaAST } from '@livestore/utils/effect'
+import { Schema } from '@livestore/utils/effect'
 
 import { SessionIdSymbol } from '../../../adapter-types.ts'
 import { sql } from '../../../util.ts'
@@ -62,9 +62,16 @@ export const clientDocument = <
     },
   } satisfies ClientDocumentTableOptions<TType>
 
+  // Column needs optimistic schema to read historical data formats
+  const optimisticColumnSchema = createOptimisticEventSchema({
+    valueSchema,
+    defaultValue: options.default.value,
+    partialSet: false, // Column always stores full documents
+  })
+
   const columns = {
     id: SqliteDsl.text({ primaryKey: true }),
-    value: SqliteDsl.json({ schema: valueSchema }),
+    value: SqliteDsl.json({ schema: optimisticColumnSchema }),
   }
 
   const tableDef = table({ name, columns })
@@ -140,6 +147,105 @@ export const mergeDefaultValues = <T>(defaultValues: T, explicitDefaultValues: T
   }, {} as any)
 }
 
+/**
+ * Creates an optimistic schema that accepts historical event formats
+ * and transforms them to the current schema, preserving data and intent.
+ *
+ * Decision Matrix for Schema Changes:
+ *
+ * | Change Type         | Partial Set         | Full Set                        | Strategy                |
+ * |---------------------|---------------------|----------------------------------|-------------------------|
+ * | **Compatible Changes**                                                                                 |
+ * | Add optional field  | Preserve existing   | Preserve existing, new field undefined | Direct decode or merge   |
+ * | Add required field  | Preserve existing   | Preserve existing, new field from default | Merge with defaults      |
+ * | **Incompatible Changes**                                                                              |
+ * | Remove field        | Drop removed field  | Drop removed field, preserve others     | Filter & decode         |
+ * | Type change         | Use default for field | Use default for changed field         | Selective merge         |
+ * | Rename field        | Use default         | Use default (can't detect rename)       | Fall back to default    |
+ * | **Edge Cases**                                                                                       |
+ * | Empty event         | Return {}           | Return full default                     | Fallback handling       |
+ * | Invalid structure   | Return {}           | Return full default                     | Fallback handling       |
+ */
+export const createOptimisticEventSchema = ({
+  valueSchema,
+  defaultValue,
+  partialSet,
+}: {
+  valueSchema: Schema.Schema<any, any>
+  defaultValue: any
+  partialSet: boolean
+}) => {
+  const targetSchema = partialSet ? Schema.partial(valueSchema) : valueSchema
+
+  return Schema.transform(
+    Schema.Unknown, // Accept any historical event structure
+    targetSchema, // Output current schema
+    {
+      decode: (eventValue) => {
+        // Try direct decode first (for current schema events)
+        try {
+          return Schema.decodeUnknownSync(targetSchema)(eventValue)
+        } 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
+          }
+
+          if (partialSet) {
+            // For partial sets: only preserve fields that exist in new schema
+            const partialResult: Record<string, unknown> = {}
+            let hasValidFields = false
+
+            for (const [key, value] of Object.entries(eventValue as Record<string, unknown>)) {
+              if (key in defaultValue) {
+                partialResult[key] = value
+                hasValidFields = true
+              }
+              // Drop fields that don't exist in new schema
+            }
+
+            if (hasValidFields) {
+              try {
+                return Schema.decodeUnknownSync(targetSchema)(partialResult)
+              } catch {
+                // Even filtered fields don't match schema
+                console.warn('Client document: Partial fields incompatible, returning empty partial')
+                return {}
+              }
+            }
+            return {}
+          } else {
+            // Full set: merge old data with new defaults
+            const merged: Record<string, unknown> = { ...defaultValue }
+
+            // Override defaults with valid fields from old event
+            for (const [key, value] of Object.entries(eventValue as Record<string, unknown>)) {
+              if (key in defaultValue) {
+                merged[key] = value
+              }
+              // Drop fields that don't exist in new schema
+            }
+
+            // Try to decode the merged value
+            try {
+              return Schema.decodeUnknownSync(valueSchema)(merged)
+            } 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
+            }
+          }
+        }
+      },
+      encode: (value) => value, // Pass-through for encoding
+    },
+  )
+}
+
 export const deriveEventAndMaterializer = ({
   name,
   valueSchema,
@@ -155,7 +261,7 @@ export const deriveEventAndMaterializer = ({
     name: `${name}Set`,
     schema: Schema.Struct({
       id: Schema.Union(Schema.String, Schema.UniqueSymbolFromSelf(SessionIdSymbol)),
-      value: partialSet ? Schema.partial(valueSchema) : valueSchema,
+      value: createOptimisticEventSchema({ valueSchema, defaultValue, partialSet }),
     }).annotations({ title: `${name}Set:Args` }),
     clientOnly: true,
     derived: true,
@@ -167,7 +273,7 @@ export const deriveEventAndMaterializer = ({
     }
 
     // Override the full value if it's not an object or no partial set is allowed
-    const schemaProps = SchemaAST.getPropertySignatures(valueSchema.ast)
+    const schemaProps = Schema.getResolvedPropertySignatures(valueSchema)
     if (schemaProps.length === 0 || partialSet === false) {
       const valueColJsonSchema = Schema.parseJson(valueSchema)
       const encodedInsertValue = Schema.encodeSyncDebug(valueColJsonSchema)(value ?? defaultValue)
@@ -281,8 +387,14 @@ export namespace ClientDocumentTableOptions {
     }
   }
 
+  type IsStructLike<T> = T extends {} ? true : false
+
   export type WithDefaults<TInput extends Input<any>> = {
-    partialSet: TInput['partialSet'] extends false ? false : true
+    partialSet: TInput['partialSet'] extends false
+      ? false
+      : IsStructLike<TInput['default']['value']> extends true
+        ? true
+        : false
     default: {
       id: TInput['default']['id'] extends string | SessionIdSymbol ? TInput['default']['id'] : undefined
       value: TInput['default']['value']

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

@@ -1,5 +1,5 @@
 import type { Schema } from '@livestore/utils/effect'
-import { dual } 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')
@@ -32,7 +32,7 @@ Here are the knobs you can turn per-column when you CREATE TABLE (or ALTER TABLE
  * Adds a primary key annotation to a schema.
  */
 export const withPrimaryKey = <T extends Schema.Schema.All>(schema: T) =>
-  schema.annotations({ [PrimaryKeyId]: true }) as T
+  applyAnnotations(schema, { [PrimaryKeyId]: true })
 
 /**
  * Adds a column type annotation to a schema.
@@ -43,19 +43,19 @@ export const withColumnType: {
   <T extends Schema.Schema.All>(schema: T, type: SqliteDsl.FieldColumnType): T
 } = dual(2, <T extends Schema.Schema.All>(schema: T, type: SqliteDsl.FieldColumnType) => {
   validateSchemaColumnTypeCompatibility(schema, type)
-  return schema.annotations({ [ColumnType]: type }) as T
+  return applyAnnotations(schema, { [ColumnType]: type })
 })
 
 /**
  * Adds an auto-increment annotation to a schema.
  */
 export const withAutoIncrement = <T extends Schema.Schema.All>(schema: T) =>
-  schema.annotations({ [AutoIncrement]: true }) as T
+  applyAnnotations(schema, { [AutoIncrement]: true })
 
 /**
  * Adds a unique constraint annotation to a schema.
  */
-export const withUnique = <T extends Schema.Schema.All>(schema: T) => schema.annotations({ [Unique]: true }) as T
+export const withUnique = <T extends Schema.Schema.All>(schema: T) => applyAnnotations(schema, { [Unique]: true })
 
 /**
  * Adds a default value annotation to a schema.
@@ -64,7 +64,7 @@ export const withDefault: {
   // TODO make type safe
   <T extends Schema.Schema.All>(schema: T, value: unknown): T
   (value: unknown): <T extends Schema.Schema.All>(schema: T) => T
-} = dual(2, <T extends Schema.Schema.All>(schema: T, value: unknown) => schema.annotations({ [Default]: value }) as T)
+} = dual(2, <T extends Schema.Schema.All>(schema: T, value: unknown) => applyAnnotations(schema, { [Default]: value }))
 
 /**
  * Validates that a schema is compatible with the specified SQLite column type
@@ -75,3 +75,13 @@ const validateSchemaColumnTypeCompatibility = (
 ): void => {
   // TODO actually implement this
 }
+
+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
+    ? { ...overrides, [SchemaAST.IdentifierAnnotationId]: identifier.value }
+    : overrides
+
+  return schema.annotations(annotations) as T
+}