@livestore/common 0.4.0 → 0.5.0-dev.1

package/src/schema/LiveStoreEvent/client.test.ts

@@ -1,10 +1,10 @@
 import { expect } from 'vitest'
 
-import { Option, Schema } from '@livestore/utils/effect'
 import { Vitest } from '@livestore/utils-dev/node-vitest'
+import { Option, Schema } from '@livestore/utils/effect'
 
 import * as EventSequenceNumber from '../EventSequenceNumber/mod.ts'
-import { EncodedWithMeta, isEqualEncoded, type Encoded } from './client.ts'
+import { type Encoded, EncodedWithMeta, isEqualEncoded } from './client.ts'
 
 Vitest.describe('EncodedWithMeta', () => {
   Vitest.test('toGlobal() produces numeric seqNums through JSON.stringify', () => {
@@ -107,10 +107,23 @@ Vitest.describe('isEqualEncoded', () => {
     expect(isEqualEncoded(a, b)).toBe(true)
   })
 
-  Vitest.it('should consider Effect Schema UndefinedOr-encoded args equal to their JSON-roundtripped form', () => {
+  Vitest.it(
+    'should consider Effect Schema UndefinedOr-encoded args with explicit undefined equal to their JSON-roundtripped form',
+    () => {
+      const argsSchema = Schema.Struct({
+        id: Schema.String,
+        flag: Schema.UndefinedOr(Schema.Boolean),
+      })
+      const localArgs = Schema.encodeUnknownSync(argsSchema)({ id: 'abc', flag: undefined } as any)
+      const wireArgs = JSON.parse(JSON.stringify(localArgs))
+      expect(isEqualEncoded(makeEncodedEvent(localArgs), makeEncodedEvent(wireArgs))).toBe(true)
+    },
+  )
+
+  Vitest.it('should consider Effect Schema optionalKey-encoded args equal to their JSON-roundtripped form', () => {
     const argsSchema = Schema.Struct({
       id: Schema.String,
-      flag: Schema.UndefinedOr(Schema.Boolean),
+      label: Schema.optionalKey(Schema.String),
     })
     const localArgs = Schema.encodeUnknownSync(argsSchema)({ id: 'abc' } as any)
     const wireArgs = JSON.parse(JSON.stringify(localArgs))

package/src/schema/LiveStoreEvent/client.ts

@@ -1,5 +1,5 @@
 import { deepEqual, memoizeByRef } from '@livestore/utils'
-import { Option, Schema } from '@livestore/utils/effect'
+import { Effect, Option, Schema, Struct } from '@livestore/utils/effect'
 
 import type { EventDef } from '../EventDef/mod.ts'
 import * as EventSequenceNumber from '../EventSequenceNumber/mod.ts'
@@ -15,7 +15,7 @@ export const Decoded = Schema.Struct({
   parentSeqNum: EventSequenceNumber.Client.Composite,
   clientId: Schema.String,
   sessionId: Schema.String,
-}).annotations({ title: 'LiveStoreEvent.Client.Decoded' })
+}).annotate({ title: 'LiveStoreEvent.Client.Decoded' })
 
 /**
  * Effect Schema for client events with encoded args.
@@ -45,7 +45,7 @@ export const Encoded = Schema.Struct({
   parentSeqNum: EventSequenceNumber.Client.Composite,
   clientId: Schema.String,
   sessionId: Schema.String,
-}).annotations({ title: 'LiveStoreEvent.Client.Encoded' })
+}).annotate({ title: 'LiveStoreEvent.Client.Encoded' })
 
 /** Event with composite sequence numbers and decoded (native TypeScript) args. */
 export type Decoded = ForEventDef.Decoded<EventDef.Any>
@@ -73,36 +73,38 @@ export class EncodedWithMeta extends Schema.Class<EncodedWithMeta>('LiveStoreEve
   sessionId: Schema.String,
   // TODO get rid of `meta` again by cleaning up the usage implementations
   meta: Schema.Struct({
-    sessionChangeset: Schema.Union(
+    sessionChangeset: Schema.Union([
       Schema.TaggedStruct('sessionChangeset', {
-        data: Schema.Uint8Array as any as Schema.Schema<Uint8Array<ArrayBuffer>>,
+        data: Schema.Uint8Array as any as Schema.Codec<Uint8Array<ArrayBuffer>>,
         debug: Schema.Any.pipe(Schema.optional),
       }),
       Schema.TaggedStruct('no-op', {}),
       Schema.TaggedStruct('unset', {}),
-    ),
-    syncMetadata: Schema.Option(Schema.JsonValue),
+    ]),
+    syncMetadata: Schema.Option(Schema.Json),
     /** 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(),
-      }),
-    }),
-  ),
+    materializerHashLeader: Schema.Option(Schema.Finite),
+    materializerHashSession: Schema.Option(Schema.Finite),
+  })
+    .mapFields(Struct.map(Schema.mutableKey))
+    .pipe(
+      Schema.withDecodingDefaultType(
+        Effect.succeed({
+          sessionChangeset: { _tag: 'unset' as const },
+          syncMetadata: Option.none(),
+          materializerHashLeader: Option.none(),
+          materializerHashSession: Option.none(),
+        }),
+      ),
+      Schema.withConstructorDefault(
+        Effect.succeed({
+          sessionChangeset: { _tag: 'unset' as const },
+          syncMetadata: Option.none(),
+          materializerHashLeader: Option.none(),
+          materializerHashSession: Option.none(),
+        }),
+      ),
+    ),
 }) {
   toJSON = (): any => {
     // Only used for logging/debugging
@@ -134,22 +136,22 @@ export class EncodedWithMeta extends Schema.Class<EncodedWithMeta>('LiveStoreEve
    */
   rebase = ({
     parentSeqNum,
-    isClient,
+    isClientOnly,
     rebaseGeneration,
   }: {
     parentSeqNum: EventSequenceNumber.Client.Composite
-    isClient: boolean
+    isClientOnly: boolean
     rebaseGeneration: number
   }) =>
     new EncodedWithMeta({
       ...this,
-      ...EventSequenceNumber.Client.nextPair({ seqNum: parentSeqNum, isClient, rebaseGeneration }),
+      ...EventSequenceNumber.Client.nextPair({ seqNum: parentSeqNum, isClientOnly, rebaseGeneration }),
     })
 
   static fromGlobal = (
     event: Global.Encoded,
     meta: {
-      syncMetadata: Option.Option<Schema.JsonValue>
+      syncMetadata: Option.Option<Schema.Json>
       materializerHashLeader: Option.Option<number>
       materializerHashSession: Option.Option<number>
     },
@@ -204,8 +206,7 @@ export const isEqualEncoded = (a: Encoded, b: Encoded) =>
   a.sessionId === b.sessionId &&
   deepEqual(canonicalizeArgs(a.args), canonicalizeArgs(b.args)) // TODO use schema equality here
 
-const canonicalizeArgs = (args: unknown): unknown =>
-  args === undefined ? args : JSON.parse(JSON.stringify(args))
+const canonicalizeArgs = (args: unknown): unknown => (args === undefined ? args : JSON.parse(JSON.stringify(args)))
 
 /**
  * Creates an Effect Schema union for all event types in a schema (with composite sequence numbers).
@@ -219,7 +220,7 @@ export const makeSchema = <TSchema extends LiveStoreSchema>(
   schema: TSchema,
 ): ForEventDef.ForRecord<TSchema['_EventDefMapType']> =>
   Schema.Union(
-    ...[...schema.eventsDefsMap.values()].map((def) =>
+    [...schema.eventsDefsMap.values()].map((def) =>
       Schema.Struct({
         name: Schema.Literal(def.name),
         args: def.schema,
@@ -229,7 +230,7 @@ export const makeSchema = <TSchema extends LiveStoreSchema>(
         sessionId: Schema.String,
       }),
     ),
-  ).annotations({ title: 'LiveStoreEvent.Client' }) as any
+  ).annotate({ 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

@@ -6,19 +6,19 @@ 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']>
+  args: TEventDef['schema']['Type']
 }
 
 /** 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']>
+  args: TEventDef['schema']['Encoded']
 }
 
 /** 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']>
+  args: TEventDef['schema']['Type']
   seqNum: EventSequenceNumber.Client.Composite
   parentSeqNum: EventSequenceNumber.Client.Composite
   clientId: string
@@ -28,7 +28,7 @@ export type Decoded<TEventDef extends EventDef.Any> = {
 /** 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']>
+  args: TEventDef['schema']['Encoded']
   seqNum: EventSequenceNumber.Client.Composite
   parentSeqNum: EventSequenceNumber.Client.Composite
   clientId: string
@@ -36,11 +36,11 @@ export type Encoded<TEventDef extends EventDef.Any> = {
 }
 
 /** Effect Schema union of all event types in an EventDefRecord (with composite sequence numbers). */
-export type ForRecord<TEventDefRecord extends EventDefRecord> = Schema.Schema<
+export type ForRecord<TEventDefRecord extends EventDefRecord> = Schema.Codec<
   {
     [K in keyof TEventDefRecord]: {
       name: K
-      args: Schema.Schema.Type<TEventDefRecord[K]['schema']>
+      args: TEventDefRecord[K]['schema']['Type']
       seqNum: EventSequenceNumber.Client.Composite
       parentSeqNum: EventSequenceNumber.Client.Composite
       clientId: string
@@ -50,7 +50,7 @@ export type ForRecord<TEventDefRecord extends EventDefRecord> = Schema.Schema<
   {
     [K in keyof TEventDefRecord]: {
       name: K
-      args: Schema.Schema.Encoded<TEventDefRecord[K]['schema']>
+      args: TEventDefRecord[K]['schema']['Encoded']
       seqNum: EventSequenceNumber.Client.Composite
       parentSeqNum: EventSequenceNumber.Client.Composite
       clientId: string

package/src/schema/LiveStoreEvent/global.ts

@@ -23,7 +23,7 @@ export const Encoded = Schema.Struct({
   parentSeqNum: EventSequenceNumber.Global.Schema,
   clientId: Schema.String,
   sessionId: Schema.String,
-}).annotations({ title: 'LiveStoreEvent.Global.Encoded' })
+}).annotate({ title: 'LiveStoreEvent.Global.Encoded' })
 
 /** Event with integer sequence numbers for sync backend wire format. */
 export type Encoded = typeof Encoded.Type

package/src/schema/LiveStoreEvent/input.ts

@@ -15,7 +15,7 @@ import type * as ForEventDef from './for-event-def.ts'
 export const Encoded = Schema.Struct({
   name: Schema.String,
   args: Schema.Any,
-}).annotations({ title: 'LiveStoreEvent.Input.Encoded' })
+}).annotate({ title: 'LiveStoreEvent.Input.Encoded' })
 
 /** Event without sequence numbers, with decoded (native TypeScript) args. */
 export type Decoded = ForEventDef.InputDecoded<EventDef.Any>
@@ -29,17 +29,17 @@ export type ForSchema<TSchema extends LiveStoreSchema> = {
 }[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<
+export type ForRecord<TEventDefRecord extends EventDefRecord> = Schema.Codec<
   {
     [K in keyof TEventDefRecord]: {
       name: K
-      args: Schema.Schema.Type<TEventDefRecord[K]['schema']>
+      args: TEventDefRecord[K]['schema']['Type']
     }
   }[keyof TEventDefRecord],
   {
     [K in keyof TEventDefRecord]: {
       name: K
-      args: Schema.Schema.Encoded<TEventDefRecord[K]['schema']>
+      args: TEventDefRecord[K]['schema']['Encoded']
     }
   }[keyof TEventDefRecord]
 >
@@ -54,10 +54,10 @@ export type ForRecord<TEventDefRecord extends EventDefRecord> = Schema.Schema<
  */
 export const makeSchema = <TSchema extends LiveStoreSchema>(schema: TSchema): ForRecord<TSchema['_EventDefMapType']> =>
   Schema.Union(
-    ...[...schema.eventsDefsMap.values()].map((def) =>
+    [...schema.eventsDefsMap.values()].map((def) =>
       Schema.Struct({
         name: Schema.Literal(def.name),
         args: def.schema,
       }),
     ),
-  ).annotations({ title: 'LiveStoreEvent.Input' }) as any
+  ).annotate({ title: 'LiveStoreEvent.Input' }) as any

package/src/schema/mod.ts

@@ -5,6 +5,7 @@ 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/mod.ts'
 export type { UnknownEvents } from './unknown-events.ts'

package/src/schema/schema.ts

@@ -1,4 +1,5 @@
-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/mod.ts'
@@ -72,7 +73,7 @@ export interface InternalState {
     readonly tables: Map<string, TableDef.Any>
     readonly migrations: MigrationOptions
     /** Compound hash of all table defs etc */
-    readonly hash: number
+    readonly hash: string
   }
   readonly materializers: Map<string, Materializer>
 }
@@ -108,7 +109,7 @@ export const makeSchema = <TInputSchema extends InputSchema>(
 
   const eventsDefsMap = new Map<string, EventDef.AnyWithoutFn>()
 
-  if (isReadonlyArray(inputSchema.events) === true) {
+  if (EffectArray.isArray<InputSchema['events']>(inputSchema.events) === true) {
     for (const eventDef of inputSchema.events) {
       eventsDefsMap.set(eventDef.name, eventDef)
     }

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

@@ -10,9 +10,25 @@ import {
   createOptimisticEventSchema,
   mergeDefaultValues,
 } from './client-document-def.ts'
+import { fingerprint } from './db-schema/ast/fingerprint.ts'
 import { getResultSchema } from './query-builder/impl.ts'
 
 describe('client document table', () => {
+  test('tracks application value-schema changes in the storage fingerprint', () => {
+    const first = clientDocument({
+      name: 'documents',
+      schema: Schema.Struct({ title: Schema.String.check(Schema.isMinLength(1)) }),
+      default: { id: 'default', value: { title: 'valid' } },
+    })
+    const second = clientDocument({
+      name: 'documents',
+      schema: Schema.Struct({ title: Schema.String.check(Schema.isMinLength(2)) }),
+      default: { id: 'default', value: { title: 'valid' } },
+    })
+
+    expect(fingerprint(first.sqliteDef.ast)).not.toBe(fingerprint(second.sqliteDef.ast))
+  })
+
   test('set event', () => {
     expect(patchId(tables.UiState.set({ showSidebar: false }, 'session-1'))).toMatchInlineSnapshot(`
       {
@@ -43,7 +59,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,
@@ -78,9 +94,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",
@@ -101,9 +116,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",
@@ -121,7 +135,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 },
@@ -204,7 +218,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',
         ),
@@ -223,6 +237,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(`
         {
@@ -260,7 +295,7 @@ describe('client document table', () => {
   describe('optimistic schema', () => {
     /** Models persisted JSON using epoch numbers + base64 while app code expects Date + Uint8Array. */
     const valueSchema = Schema.Struct({
-      createdAt: Schema.DateFromNumber,
+      createdAt: Schema.DateFromMillis,
       avatar: Schema.Uint8ArrayFromBase64,
     })
     const defaultValue = {
@@ -281,9 +316,9 @@ describe('client document table', () => {
         defaultValue,
         partialSet: false,
       })
-      const rowSchema = Schema.parseJson(optimisticSchema)
+      const rowSchema = Schema.fromJsonString(optimisticSchema)
 
-      expect(Schema.decodeUnknownSync(rowSchema)(JSON.stringify(value))).toEqual(defaultValue)
+      expect(Schema.decodeSync(rowSchema)(JSON.stringify(value))).toEqual(defaultValue)
     })
 
     test('decodes valid persisted JSON (encoded shape)', () => {
@@ -292,9 +327,9 @@ describe('client document table', () => {
         defaultValue,
         partialSet: false,
       })
-      const rowSchema = Schema.parseJson(optimisticSchema)
+      const rowSchema = Schema.fromJsonString(optimisticSchema)
 
-      expect(Schema.decodeUnknownSync(rowSchema)(JSON.stringify(validPayload))).toEqual({
+      expect(Schema.decodeSync(rowSchema)(JSON.stringify(validPayload))).toEqual({
         createdAt: new Date(42),
         avatar: new Uint8Array([1, 2]),
       })
@@ -306,9 +341,9 @@ describe('client document table', () => {
         defaultValue,
         partialSet: false,
       })
-      const rowSchema = Schema.parseJson(optimisticSchema)
+      const rowSchema = Schema.fromJsonString(optimisticSchema)
 
-      expect(Schema.decodeUnknownSync(rowSchema)(JSON.stringify(extraFieldsPayload))).toEqual({
+      expect(Schema.decodeSync(rowSchema)(JSON.stringify(extraFieldsPayload))).toEqual({
         createdAt: new Date(42),
         avatar: new Uint8Array([1, 2]),
       })
@@ -326,7 +361,7 @@ describe('client document table', () => {
         value: JSON.stringify(value),
       }
 
-      expect(Schema.decodeUnknownSync(Doc.rowSchema)(row)).toEqual({ id: 'row-1', value: defaultValue })
+      expect(Schema.decodeSync(Doc.rowSchema)(row)).toEqual({ id: 'row-1', value: defaultValue })
     })
 
     test('decodes clientDocument rowSchema with valid encoded JSON', () => {
@@ -341,7 +376,7 @@ describe('client document table', () => {
         value: JSON.stringify(validPayload),
       }
 
-      expect(Schema.decodeUnknownSync(Doc.rowSchema)(row)).toEqual({
+      expect(Schema.decodeSync(Doc.rowSchema)(row)).toEqual({
         id: 'row-1',
         value: { createdAt: new Date(42), avatar: new Uint8Array([1, 2]) },
       })
@@ -363,7 +398,7 @@ describe('client document table', () => {
         },
       ]
 
-      expect(Schema.decodeUnknownSync(resultSchema)(rawDbResults)).toEqual(defaultValue)
+      expect(Schema.decodeSync(resultSchema)(rawDbResults)).toEqual(defaultValue)
     })
 
     test('decodes RowQuery result schema with valid encoded JSON', () => {
@@ -382,7 +417,7 @@ describe('client document table', () => {
         },
       ]
 
-      expect(Schema.decodeUnknownSync(resultSchema)(rawDbResults)).toEqual({
+      expect(Schema.decodeSync(resultSchema)(rawDbResults)).toEqual({
         createdAt: new Date(42),
         avatar: new Uint8Array([1, 2]),
       })