@livestore/common 0.4.0-dev.2 → 0.4.0-dev.21

package/src/schema/LiveStoreEvent/client.ts

@@ -0,0 +1,221 @@
+import { memoizeByRef } from '@livestore/utils'
+import { Option, Schema } from '@livestore/utils/effect'
+
+import type { EventDef } from '../EventDef/mod.ts'
+import * as EventSequenceNumber from '../EventSequenceNumber/mod.ts'
+import type { LiveStoreSchema } from '../schema.ts'
+import type * as ForEventDef from './for-event-def.ts'
+import type * as Global from './global.ts'
+
+/** Effect Schema for client events with decoded args. */
+export const Decoded = Schema.Struct({
+  name: Schema.String,
+  args: Schema.Any,
+  seqNum: EventSequenceNumber.Client.Composite,
+  parentSeqNum: EventSequenceNumber.Client.Composite,
+  clientId: Schema.String,
+  sessionId: Schema.String,
+}).annotations({ title: 'LiveStoreEvent.Client.Decoded' })
+
+/**
+ * Effect Schema for client events with encoded args.
+ * @example
+ * ```ts
+ * // Confirmed event (client=0)
+ * const event: LiveStoreEvent.Client.Encoded = {
+ *   name: 'todoCreated-v1',
+ *   args: { id: 'abc', text: 'Buy milk' },
+ *   seqNum: { global: 5, client: 0, rebaseGeneration: 0 },
+ *   parentSeqNum: { global: 4, client: 0, rebaseGeneration: 0 },
+ *   clientId: 'client-xyz',
+ *   sessionId: 'session-123'
+ * }
+ *
+ * // Pending local event (client=1, not yet synced)
+ * const pending: LiveStoreEvent.Client.Encoded = {
+ *   ...event,
+ *   seqNum: { global: 5, client: 1, rebaseGeneration: 0 },  // e5.1
+ * }
+ * ```
+ */
+export const Encoded = Schema.Struct({
+  name: Schema.String,
+  args: Schema.Any,
+  seqNum: EventSequenceNumber.Client.Composite,
+  parentSeqNum: EventSequenceNumber.Client.Composite,
+  clientId: Schema.String,
+  sessionId: Schema.String,
+}).annotations({ title: 'LiveStoreEvent.Client.Encoded' })
+
+/** Event with composite sequence numbers and decoded (native TypeScript) args. */
+export type Decoded = ForEventDef.Decoded<EventDef.Any>
+
+/** Event with composite sequence numbers and encoded (serialized) args. */
+export type Encoded = ForEventDef.Encoded<EventDef.Any>
+
+/** Union of all client event types for a given schema (type-safe event discrimination). */
+export type ForSchema<TSchema extends LiveStoreSchema> = {
+  [K in keyof TSchema['_EventDefMapType']]: ForEventDef.Decoded<TSchema['_EventDefMapType'][K]>
+}[keyof TSchema['_EventDefMapType']]
+
+/**
+ * Internal event representation with metadata for sync processing.
+ * Includes changeset data and materializer hashes for conflict detection and rebasing.
+ *
+ * Note: This class is exported for internal use. The preferred access is via `LiveStoreEvent.Client.EncodedWithMeta`.
+ */
+export class EncodedWithMeta extends Schema.Class<EncodedWithMeta>('LiveStoreEvent.Client.EncodedWithMeta')({
+  name: Schema.String,
+  args: Schema.Any,
+  seqNum: EventSequenceNumber.Client.Composite,
+  parentSeqNum: EventSequenceNumber.Client.Composite,
+  clientId: Schema.String,
+  sessionId: Schema.String,
+  // TODO get rid of `meta` again by cleaning up the usage implementations
+  meta: Schema.Struct({
+    sessionChangeset: Schema.Union(
+      Schema.TaggedStruct('sessionChangeset', {
+        data: Schema.Uint8Array as any as Schema.Schema<Uint8Array<ArrayBuffer>>,
+        debug: Schema.Any.pipe(Schema.optional),
+      }),
+      Schema.TaggedStruct('no-op', {}),
+      Schema.TaggedStruct('unset', {}),
+    ),
+    syncMetadata: Schema.Option(Schema.JsonValue),
+    /** Used to detect if the materializer is side effecting (during dev) */
+    materializerHashLeader: Schema.Option(Schema.Number),
+    materializerHashSession: Schema.Option(Schema.Number),
+  }).pipe(
+    Schema.mutable,
+    Schema.optional,
+    Schema.withDefaults({
+      constructor: () => ({
+        sessionChangeset: { _tag: 'unset' as const },
+        syncMetadata: Option.none(),
+        materializerHashLeader: Option.none(),
+        materializerHashSession: Option.none(),
+      }),
+      decoding: () => ({
+        sessionChangeset: { _tag: 'unset' as const },
+        syncMetadata: Option.none(),
+        materializerHashLeader: Option.none(),
+        materializerHashSession: Option.none(),
+      }),
+    }),
+  ),
+}) {
+  toJSON = (): any => {
+    // Only used for logging/debugging
+    // - More readable way to print the seqNum + parentSeqNum
+    // - not including `meta`, `clientId`, `sessionId`
+    return {
+      seqNum: `${EventSequenceNumber.Client.toString(this.seqNum)} → ${EventSequenceNumber.Client.toString(this.parentSeqNum)} (${this.clientId}, ${this.sessionId})`,
+      name: this.name,
+      args: this.args,
+    }
+  }
+
+  /**
+   * Example: (global event)
+   * For event e2 → e1 which should be rebased on event e3 → e2
+   * the resulting event num will be e4 → e3
+   *
+   * Example: (client event)
+   * For event e2.1 → e2 which should be rebased on event e3 → e2
+   * the resulting event num will be e3.1 → e3
+   *
+   * Syntax: e2.2 → e2.1
+   *          ^ ^    ^ ^
+   *          | |    | +- client parent number
+   *          | |    +--- global parent number
+   *          | +-- client number
+   *          +---- global number
+   * Client num is omitted for global events
+   */
+  rebase = ({
+    parentSeqNum,
+    isClient,
+    rebaseGeneration,
+  }: {
+    parentSeqNum: EventSequenceNumber.Client.Composite
+    isClient: boolean
+    rebaseGeneration: number
+  }) =>
+    new EncodedWithMeta({
+      ...this,
+      ...EventSequenceNumber.Client.nextPair({ seqNum: parentSeqNum, isClient, rebaseGeneration }),
+    })
+
+  static fromGlobal = (
+    event: Global.Encoded,
+    meta: {
+      syncMetadata: Option.Option<Schema.JsonValue>
+      materializerHashLeader: Option.Option<number>
+      materializerHashSession: Option.Option<number>
+    },
+  ) =>
+    new EncodedWithMeta({
+      ...event,
+      seqNum: {
+        global: event.seqNum,
+        client: EventSequenceNumber.Client.DEFAULT,
+        rebaseGeneration: EventSequenceNumber.Client.REBASE_GENERATION_DEFAULT,
+      },
+      parentSeqNum: {
+        global: event.parentSeqNum,
+        client: EventSequenceNumber.Client.DEFAULT,
+        rebaseGeneration: EventSequenceNumber.Client.REBASE_GENERATION_DEFAULT,
+      },
+      meta: {
+        sessionChangeset: { _tag: 'unset' as const },
+        syncMetadata: meta.syncMetadata,
+        materializerHashLeader: meta.materializerHashLeader,
+        materializerHashSession: meta.materializerHashSession,
+      },
+    })
+
+  toGlobal = (): Global.Encoded => ({
+    ...this,
+    seqNum: this.seqNum.global,
+    parentSeqNum: this.parentSeqNum.global,
+  })
+}
+
+/**
+ * Structural equality check for client events. Compares seqNum (global + client),
+ * name, clientId, sessionId, and args. The `meta` field is ignored.
+ */
+export const isEqualEncoded = (a: Encoded, b: Encoded) =>
+  a.seqNum.global === b.seqNum.global &&
+  a.seqNum.client === b.seqNum.client &&
+  a.name === b.name &&
+  a.clientId === b.clientId &&
+  a.sessionId === b.sessionId &&
+  JSON.stringify(a.args) === JSON.stringify(b.args) // TODO use schema equality here
+
+/**
+ * Creates an Effect Schema union for all event types in a schema (with composite sequence numbers).
+ * @example
+ * ```ts
+ * const eventSchema = LiveStoreEvent.Client.makeSchema(schema)
+ * const event = Schema.decodeUnknownSync(eventSchema)(rawEvent)
+ * ```
+ */
+export const makeSchema = <TSchema extends LiveStoreSchema>(
+  schema: TSchema,
+): ForEventDef.ForRecord<TSchema['_EventDefMapType']> =>
+  Schema.Union(
+    ...[...schema.eventsDefsMap.values()].map((def) =>
+      Schema.Struct({
+        name: Schema.Literal(def.name),
+        args: def.schema,
+        seqNum: EventSequenceNumber.Client.Composite,
+        parentSeqNum: EventSequenceNumber.Client.Composite,
+        clientId: Schema.String,
+        sessionId: Schema.String,
+      }),
+    ),
+  ).annotations({ title: 'LiveStoreEvent.Client' }) as any
+
+/** Memoized `makeSchema` - caches the generated schema by reference. */
+export const makeSchemaMemo = memoizeByRef(makeSchema)

package/src/schema/LiveStoreEvent/for-event-def.ts

@@ -0,0 +1,60 @@
+import type { Schema } from '@livestore/utils/effect'
+
+import type { EventDef, EventDefRecord } from '../EventDef/mod.ts'
+import type * as EventSequenceNumber from '../EventSequenceNumber/mod.ts'
+
+/** Event without sequence numbers, with decoded (native TypeScript) args. Used as input to `store.commit()`. */
+export type InputDecoded<TEventDef extends EventDef.Any> = {
+  name: TEventDef['name']
+  args: Schema.Schema.Type<TEventDef['schema']>
+}
+
+/** Event without sequence numbers, with encoded (serialized) args. Used as input to `store.commit()`. */
+export type InputEncoded<TEventDef extends EventDef.Any> = {
+  name: TEventDef['name']
+  args: Schema.Schema.Encoded<TEventDef['schema']>
+}
+
+/** Full event with composite sequence numbers and decoded args. Includes clientId/sessionId for sync. */
+export type Decoded<TEventDef extends EventDef.Any> = {
+  name: TEventDef['name']
+  args: Schema.Schema.Type<TEventDef['schema']>
+  seqNum: EventSequenceNumber.Client.Composite
+  parentSeqNum: EventSequenceNumber.Client.Composite
+  clientId: string
+  sessionId: string
+}
+
+/** Full event with composite sequence numbers and encoded args. Includes clientId/sessionId for sync. */
+export type Encoded<TEventDef extends EventDef.Any> = {
+  name: TEventDef['name']
+  args: Schema.Schema.Encoded<TEventDef['schema']>
+  seqNum: EventSequenceNumber.Client.Composite
+  parentSeqNum: EventSequenceNumber.Client.Composite
+  clientId: string
+  sessionId: string
+}
+
+/** Effect Schema union of all event types in an EventDefRecord (with composite sequence numbers). */
+export type ForRecord<TEventDefRecord extends EventDefRecord> = Schema.Schema<
+  {
+    [K in keyof TEventDefRecord]: {
+      name: K
+      args: Schema.Schema.Type<TEventDefRecord[K]['schema']>
+      seqNum: EventSequenceNumber.Client.Composite
+      parentSeqNum: EventSequenceNumber.Client.Composite
+      clientId: string
+      sessionId: string
+    }
+  }[keyof TEventDefRecord],
+  {
+    [K in keyof TEventDefRecord]: {
+      name: K
+      args: Schema.Schema.Encoded<TEventDefRecord[K]['schema']>
+      seqNum: EventSequenceNumber.Client.Composite
+      parentSeqNum: EventSequenceNumber.Client.Composite
+      clientId: string
+      sessionId: string
+    }
+  }[keyof TEventDefRecord]
+>

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,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

@@ -2,7 +2,7 @@ import { Schema } from '@livestore/utils/effect'
 import { describe, expect, test } from 'vitest'
 
 import { tables } from '../../../__tests__/fixture.ts'
-import type * as LiveStoreEvent from '../../LiveStoreEvent.ts'
+import type * as LiveStoreEvent from '../../LiveStoreEvent/mod.ts'
 import { ClientDocumentTableDefSymbol, clientDocument, mergeDefaultValues } from './client-document-def.ts'
 
 describe('client document table', () => {
@@ -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,10 +231,26 @@ 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",
+          },
+        }
+      `)
+    })
   })
 })
 
-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 }