@livestore/common 0.4.0-dev.9 → 0.5.0-dev.0

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,
+}).annotate({ 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.Codec<
+  {
+    [K in keyof TEventDefRecord]: {
+      name: K
+      args: TEventDefRecord[K]['schema']['Type']
+    }
+  }[keyof TEventDefRecord],
+  {
+    [K in keyof TEventDefRecord]: {
+      name: K
+      args: TEventDefRecord[K]['schema']['Encoded']
+    }
+  }[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,
+      }),
+    ),
+  ).annotate({ 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,12 @@
-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/persistence.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,20 @@
-import { isReadonlyArray, shouldNeverHappen } from '@livestore/utils'
+import { shouldNeverHappen } from '@livestore/utils'
+import { ReadonlyArray as EffectArray } from '@livestore/utils/effect'
 
 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 +27,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 +38,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 +90,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 +109,13 @@ export const makeSchema = <TInputSchema extends InputSchema>(
 
   const eventsDefsMap = new Map<string, EventDef.AnyWithoutFn>()
 
-  if (isReadonlyArray(inputSchema.events)) {
+  if (EffectArray.isArray<InputSchema['events']>(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 +123,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', () => {
@@ -36,7 +43,7 @@ describe('client document table', () => {
   })
 
   describe('materializer', () => {
-    const forSchema = <T>(schema: Schema.Schema<T, any>, value: T, id?: string, options?: { partialSet?: boolean }) => {
+    const forSchema = <T>(schema: Schema.Codec<T, any>, value: T, id?: string, options?: { partialSet?: boolean }) => {
       const Doc = clientDocument({
         name: 'test',
         schema,
@@ -71,9 +78,8 @@ describe('client document table', () => {
     })
 
     test('struct value (partial set=true)', () => {
-      expect(
-        forSchema(Schema.Struct({ a: Schema.String }), { a: 'hello' }, 'id1', { partialSet: true }),
-      ).toMatchInlineSnapshot(`
+      expect(forSchema(Schema.Struct({ a: Schema.String }), { a: 'hello' }, 'id1', { partialSet: true }))
+        .toMatchInlineSnapshot(`
           {
             "bindValues": [
               "id1",
@@ -94,9 +100,8 @@ describe('client document table', () => {
     })
 
     test('struct value (partial set=false)', () => {
-      expect(
-        forSchema(Schema.Struct({ a: Schema.String }), { a: 'hello' }, 'id1', { partialSet: false }),
-      ).toMatchInlineSnapshot(`
+      expect(forSchema(Schema.Struct({ a: Schema.String }), { a: 'hello' }, 'id1', { partialSet: false }))
+        .toMatchInlineSnapshot(`
         {
           "bindValues": [
             "id1",
@@ -114,7 +119,7 @@ describe('client document table', () => {
     test('struct value (partial set=true) advanced', () => {
       expect(
         forSchema(
-          Schema.Struct({ a: Schema.String, b: Schema.String, c: Schema.Number }),
+          Schema.Struct({ a: Schema.String, b: Schema.String, c: Schema.Finite }),
           { a: 'hello', c: 123 } as any,
           'id1',
           { partialSet: true },
@@ -197,7 +202,7 @@ describe('client document table', () => {
     test('struct union value', () => {
       expect(
         forSchema(
-          Schema.Union(Schema.Struct({ a: Schema.String }), Schema.Struct({ b: Schema.String })),
+          Schema.Union([Schema.Struct({ a: Schema.String }), Schema.Struct({ b: Schema.String })]),
           { a: 'hello' },
           'id1',
         ),
@@ -216,6 +221,27 @@ describe('client document table', () => {
       `)
     })
 
+    test('struct union with shared fields fully replaces', () => {
+      const ValueSchema = Schema.Union([
+        Schema.Struct({ kind: Schema.Literal('a'), value: Schema.String }),
+        Schema.Struct({ kind: Schema.Literal('b'), value: Schema.String }),
+      ])
+
+      expect(forSchema(ValueSchema, { kind: 'a', value: 'hello' }, 'id1')).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "id1",
+            "{"kind":"a","value":"hello"}",
+            "{"kind":"a","value":"hello"}",
+          ],
+          "sql": "INSERT INTO 'test' (id, value) VALUES (?, ?) ON CONFLICT (id) DO UPDATE SET value = ?",
+          "writeTables": Set {
+            "test",
+          },
+        }
+      `)
+    })
+
     test('array value', () => {
       expect(forSchema(Schema.Array(Schema.String), ['hello', 'world'], 'id1')).toMatchInlineSnapshot(`
         {
@@ -248,14 +274,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.DateFromMillis,
+      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.fromJsonString(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.fromJsonString(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.fromJsonString(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 }