@livestore/common 0.4.0 → 0.5.0-dev.0

package/src/sync/syncstate.ts

@@ -58,24 +58,24 @@ export class SyncState extends Schema.Class<SyncState>('SyncState')({
 /**
  * This payload propagates a rebase from the upstream node
  */
-export class PayloadUpstreamRebase extends Schema.TaggedStruct('upstream-rebase', {
+export const PayloadUpstreamRebase = Schema.TaggedStruct('upstream-rebase', {
   /** Events which need to be rolled back */
   rollbackEvents: Schema.Array(LiveStoreEvent.Client.EncodedWithMeta),
   /** Events which need to be applied after the rollback (already rebased by the upstream node) */
   newEvents: Schema.Array(LiveStoreEvent.Client.EncodedWithMeta),
-}) {}
+})
 
-export class PayloadUpstreamAdvance extends Schema.TaggedStruct('upstream-advance', {
+export const PayloadUpstreamAdvance = Schema.TaggedStruct('upstream-advance', {
   newEvents: Schema.Array(LiveStoreEvent.Client.EncodedWithMeta),
-}) {}
+})
 
-export class PayloadLocalPush extends Schema.TaggedStruct('local-push', {
+export const PayloadLocalPush = Schema.TaggedStruct('local-push', {
   newEvents: Schema.Array(LiveStoreEvent.Client.EncodedWithMeta),
-}) {}
+})
 
-export class Payload extends Schema.Union(PayloadUpstreamRebase, PayloadUpstreamAdvance, PayloadLocalPush) {}
+export const Payload = Schema.Union([PayloadUpstreamRebase, PayloadUpstreamAdvance, PayloadLocalPush])
 
-export class PayloadUpstream extends Schema.Union(PayloadUpstreamRebase, PayloadUpstreamAdvance) {}
+export const PayloadUpstream = Schema.Union([PayloadUpstreamRebase, PayloadUpstreamAdvance])
 
 /** Only used for debugging purposes */
 export class MergeContext extends Schema.Class<MergeContext>('MergeContext')({
@@ -159,14 +159,10 @@ export class MergeResultReject extends Schema.Class<MergeResultReject>('MergeRes
   }
 }
 
-export class MergeResult extends Schema.Union(
-  MergeResultAdvance,
-  MergeResultRebase,
-  MergeResultReject,
-) {}
+export const MergeResult = Schema.Union([MergeResultAdvance, MergeResultRebase, MergeResultReject])
 
 export const payloadFromMergeResult = (
-  mergeResult: typeof MergeResultAdvance.Type | typeof MergeResultRebase.Type,
+  mergeResult: MergeResultAdvance | MergeResultRebase,
 ): typeof PayloadUpstream.Type =>
   Match.value(mergeResult).pipe(
     Match.tag('advance', (result) => ({
@@ -191,16 +187,31 @@ TODO: possibly even keep the client events in a separate table in the client lea
 export const merge = Effect.fnUntraced(function* ({
   syncState,
   payload,
-  isClientEvent,
+  isClientOnlyEvent,
   isEqualEvent,
-  ignoreClientEvents = false,
+  ignoreClientOnlyEvents = false,
 }: {
   syncState: SyncState
   payload: typeof Payload.Type
-  isClientEvent: (event: LiveStoreEvent.Client.EncodedWithMeta) => boolean
+  /**
+   * `LiveStoreEvent.Client.EncodedWithMeta` does not carry the event definition's
+   * `clientOnly` flag. The caller supplies this schema-aware predicate so `merge`
+   * can preserve the correct sequence-number shape when rebasing: client-only
+   * events advance the client component, synced events advance the global component.
+   */
+  isClientOnlyEvent: (event: LiveStoreEvent.Client.EncodedWithMeta) => boolean
+  /**
+   * Pending events are confirmed by comparing their logical encoded identity with
+   * upstream events. This is caller-supplied because comparing encoded args may
+   * require event-schema knowledge that the generic merge algorithm does not own.
+   * Implementations should ignore transport/runtime metadata.
+   */
   isEqualEvent: (a: LiveStoreEvent.Client.EncodedWithMeta, b: LiveStoreEvent.Client.EncodedWithMeta) => boolean
-  /** This is used in the leader which should ignore client events when receiving an upstream-advance payload */
-  ignoreClientEvents?: boolean
+  /**
+   * This is used in the leader which should ignore client events when
+   * receiving an upstream-advance payload
+   */
+  ignoreClientOnlyEvents?: boolean
 }) {
   yield* validateSyncState(syncState)
   yield* validatePayload(payload)
@@ -218,7 +229,7 @@ export const merge = Effect.fnUntraced(function* ({
       const rebasedPending = rebaseEvents({
         events: syncState.pending,
         baseEventSequenceNumber: newUpstreamHead,
-        isClientEvent,
+        isClientOnlyEvent,
       })
 
       return yield* validateMergeResult(
@@ -282,8 +293,8 @@ export const merge = Effect.fnUntraced(function* ({
         existingEvents: syncState.pending,
         incomingEvents: payload.newEvents,
         isEqualEvent,
-        isClientEvent,
-        ignoreClientEvents,
+        isClientOnlyEvent,
+        ignoreClientOnlyEvents,
       })
 
       // No divergent pending events, thus we can just advance (some of) the pending events
@@ -304,7 +315,7 @@ export const merge = Effect.fnUntraced(function* ({
         const [pendingMatching, pendingRemaining] = ReadonlyArray.splitWhere(
           syncState.pending,
           (pendingEvent, index) => {
-            if (ignoreClientEvents === true && isClientEvent(pendingEvent) === true) {
+            if (ignoreClientOnlyEvents === true && isClientOnlyEvent(pendingEvent) === true) {
               clientIndexOffset++
               return false
             }
@@ -336,15 +347,15 @@ export const merge = Effect.fnUntraced(function* ({
         const rebasedPending = rebaseEvents({
           events: divergentPending,
           baseEventSequenceNumber: newUpstreamHead,
-          isClientEvent,
+          isClientOnlyEvent: isClientOnlyEvent,
         })
 
         const divergentNewEventsIndex = findDivergencePoint({
           existingEvents: payload.newEvents,
           incomingEvents: syncState.pending,
           isEqualEvent,
-          isClientEvent,
-          ignoreClientEvents,
+          isClientOnlyEvent: isClientOnlyEvent,
+          ignoreClientOnlyEvents: ignoreClientOnlyEvents,
         })
 
         return yield* validateMergeResult(
@@ -387,7 +398,7 @@ export const merge = Effect.fnUntraced(function* ({
       if (invalidEventSequenceNumber === true) {
         const expectedMinimumId = EventSequenceNumber.Client.nextPair({
           seqNum: syncState.localHead,
-          isClient: true,
+          isClientOnly: true,
         }).seqNum
         return yield* validateMergeResult(
           MergeResultReject.make({
@@ -397,9 +408,11 @@ export const merge = Effect.fnUntraced(function* ({
           }),
         )
       } else {
-        const nonClientEvents =
-          ignoreClientEvents === true ? payload.newEvents.filter((event) => !isClientEvent(event)) : payload.newEvents
-        const newPending = [...syncState.pending, ...nonClientEvents]
+        const nonClientOnlyEvents =
+          ignoreClientOnlyEvents === true
+            ? payload.newEvents.filter((event) => !isClientOnlyEvent(event))
+            : payload.newEvents
+        const newPending = [...syncState.pending, ...nonClientOnlyEvents]
         const newLocalHead =
           newPending.at(-1)?.seqNum ?? EventSequenceNumber.Client.max(syncState.localHead, syncState.upstreamHead)
 
@@ -422,7 +435,7 @@ export const merge = Effect.fnUntraced(function* ({
     default:
       return casesHandled(payload)
   }
-  })
+})
 
 /**
  * Gets the index relative to `existingEvents` where the divergence point is
@@ -432,28 +445,28 @@ export const findDivergencePoint = ({
   existingEvents,
   incomingEvents,
   isEqualEvent,
-  isClientEvent,
-  ignoreClientEvents,
+  isClientOnlyEvent,
+  ignoreClientOnlyEvents,
 }: {
   existingEvents: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>
   incomingEvents: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>
   isEqualEvent: (a: LiveStoreEvent.Client.EncodedWithMeta, b: LiveStoreEvent.Client.EncodedWithMeta) => boolean
-  isClientEvent: (event: LiveStoreEvent.Client.EncodedWithMeta) => boolean
-  ignoreClientEvents: boolean
+  isClientOnlyEvent: (event: LiveStoreEvent.Client.EncodedWithMeta) => boolean
+  ignoreClientOnlyEvents: boolean
 }): number => {
-  if (ignoreClientEvents === true) {
-    const filteredExistingEvents = existingEvents.filter((event) => !isClientEvent(event))
-    const divergencePointWithoutClientEvents = findDivergencePoint({
+  if (ignoreClientOnlyEvents === true) {
+    const filteredExistingEvents = existingEvents.filter((event) => !isClientOnlyEvent(event))
+    const divergencePointWithoutClientOnlyEvents = findDivergencePoint({
       existingEvents: filteredExistingEvents,
       incomingEvents,
       isEqualEvent,
-      isClientEvent,
-      ignoreClientEvents: false,
+      isClientOnlyEvent,
+      ignoreClientOnlyEvents: false,
     })
 
-    if (divergencePointWithoutClientEvents === -1) return -1
+    if (divergencePointWithoutClientOnlyEvents === -1) return -1
 
-    const divergencePointEventSequenceNumber = existingEvents[divergencePointWithoutClientEvents]!.seqNum
+    const divergencePointEventSequenceNumber = existingEvents[divergencePointWithoutClientOnlyEvents]!.seqNum
     // Now find the divergence point in the original array
     return existingEvents.findIndex((event) =>
       EventSequenceNumber.Client.isEqual(event.seqNum, divergencePointEventSequenceNumber),
@@ -470,19 +483,20 @@ export const findDivergencePoint = ({
 const rebaseEvents = ({
   events,
   baseEventSequenceNumber,
-  isClientEvent,
+  isClientOnlyEvent,
 }: {
   events: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>
   baseEventSequenceNumber: EventSequenceNumber.Client.Composite
-  isClientEvent: (event: LiveStoreEvent.Client.EncodedWithMeta) => boolean
+  isClientOnlyEvent: (event: LiveStoreEvent.Client.EncodedWithMeta) => boolean
 }): ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta> => {
   let prevEventSequenceNumber = baseEventSequenceNumber
   const rebaseGeneration = baseEventSequenceNumber.rebaseGeneration + 1
   return events.map((event) => {
-    const isClient = isClientEvent(event)
+    // Rebasing must preserve whether an event is client-only: client-only
+    // events become eN.1/eN.2, while synced events become eN+1.
     const newEvent = event.rebase({
       parentSeqNum: prevEventSequenceNumber,
-      isClient,
+      isClientOnly: isClientOnlyEvent(event),
       rebaseGeneration,
     })
     prevEventSequenceNumber = newEvent.seqNum
@@ -497,7 +511,7 @@ const rebaseEvents = ({
  * it could make sense to "flatten" update results into a single update result which the client session
  * can process more efficiently which avoids push-threshing
  */
-const _flattenMergeResults = (_updateResults: ReadonlyArray<MergeResult>) => {}
+const _flattenMergeResults = (_updateResults: ReadonlyArray<typeof MergeResult>) => {}
 
 const validatePayload = (payload: typeof Payload.Type) =>
   Effect.gen(function* () {
@@ -515,9 +529,7 @@ const validatePayload = (payload: typeof Payload.Type) =>
     }
   })
 
-const validateSyncState = Effect.fnUntraced(function* (
-  syncState: SyncState,
-) {
+const validateSyncState = Effect.fnUntraced(function* (syncState: SyncState) {
   for (let i = 0; i < syncState.pending.length; i++) {
     const event = syncState.pending[i]!
     const nextEvent = syncState.pending[i + 1]
@@ -553,9 +565,7 @@ const validateSyncState = Effect.fnUntraced(function* (
   }
 })
 
-const validateMergeResult = Effect.fnUntraced(function* (
-  mergeResult: typeof MergeResult.Type,
-) {
+const validateMergeResult = Effect.fnUntraced(function* (mergeResult: typeof MergeResult.Type) {
   if (mergeResult._tag === 'reject') return mergeResult
 
   yield* validateSyncState(mergeResult.newSyncState)

package/src/sync/transport-chunking.ts

@@ -1,14 +1,15 @@
-import { Chunk, Effect, Schema } from '@livestore/utils/effect'
+import type { ReadonlyArray as EffectArray } from '@livestore/utils/effect'
+import { Effect, Schema } from '@livestore/utils/effect'
 
 const textEncoder = new TextEncoder()
 
 /**
- * Configuration describing how to break a chunk into smaller payload-safe chunks.
+ * Configuration describing how to break an array batch into smaller payload-safe batches.
  */
 export interface ChunkingOptions<A> {
-  /** Maximum number of items that may appear in any emitted chunk. */
+  /** Maximum number of items that may appear in any emitted batch. */
   readonly maxItems: number
-  /** Maximum encoded byte size allowed for any emitted chunk. */
+  /** Maximum encoded byte size allowed for any emitted batch. */
   readonly maxBytes: number
   /**
    * Callback that produces a JSON-serialisable structure whose byte size should
@@ -22,19 +23,23 @@ export interface ChunkingOptions<A> {
   readonly measure?: (items: ReadonlyArray<A>) => number
 }
 
-/**
- * Derives a function that splits an input chunk into sub-chunks confined by
- * both item count and encoded byte size limits. Designed for transports with
- * strict frame caps (e.g. Cloudflare hibernated WebSockets).
- */
-export class OversizeChunkItemError extends Schema.TaggedError<OversizeChunkItemError>('~@livestore/common/OversizeChunkItemError')('OversizeChunkItemError', {
-  size: Schema.Number,
-  maxBytes: Schema.Number,
+export class OversizeChunkItemError extends Schema.TaggedError<OversizeChunkItemError>(
+  '~@livestore/common/OversizeChunkItemError',
+)('OversizeChunkItemError', {
+  size: Schema.Finite,
+  maxBytes: Schema.Finite,
 }) {}
 
-export const splitChunkBySize =
+/**
+ * Derives a function that splits an input array into sub-arrays confined by
+ * both item count and encoded byte size limits. Designed for stream boundaries
+ * and transports with strict frame caps (e.g. Cloudflare hibernated WebSockets).
+ */
+export const splitArrayBySize =
   <A>(options: ChunkingOptions<A>) =>
-  (chunk: Chunk.Chunk<A>): Effect.Effect<Chunk.Chunk<Chunk.Chunk<A>>, OversizeChunkItemError> =>
+  (
+    items: EffectArray.NonEmptyReadonlyArray<A>,
+  ): Effect.Effect<EffectArray.NonEmptyArray<ReadonlyArray<A>>, OversizeChunkItemError> =>
     Effect.gen(function* () {
       const maxItems = Math.max(1, options.maxItems)
       const maxBytes = Math.max(1, options.maxBytes)
@@ -50,41 +55,31 @@ export const splitChunkBySize =
         return textEncoder.encode(JSON.stringify(encoded)).byteLength
       }
 
-      const items = Chunk.toReadonlyArray(chunk)
-      if (items.length === 0) {
-        return Chunk.fromIterable<Chunk.Chunk<A>>([])
-      }
+      const [first, ...rest] = items
+      let current: EffectArray.NonEmptyArray<A> = [first]
+      const result: EffectArray.NonEmptyArray<ReadonlyArray<A>> = [current]
 
-      const result: Array<Chunk.Chunk<A>> = []
-      let current: Array<A> = []
-
-      const flushCurrent = () => {
-        if (current.length > 0) {
-          result.push(Chunk.fromIterable(current))
-          current = []
-        }
+      if (computeSize(current) > maxBytes) {
+        return yield* new OversizeChunkItemError({ size: computeSize(current), maxBytes })
       }
 
-      for (const item of items) {
+      for (const item of rest) {
         current.push(item)
         const exceedsLimit = current.length > maxItems || computeSize(current) > maxBytes
 
         if (exceedsLimit === true) {
-          // remove the item we just added and emit the previous chunk if it exists
-          const last = current.pop()!
-          flushCurrent()
+          // Remove the item we just added; the previous batch was already recorded in `result`.
+          current.splice(current.length - 1, 1)
+          current = [item]
 
-          if (last !== undefined) {
-            current = [last]
-            const singleItemTooLarge = computeSize(current) > maxBytes
-            if (singleItemTooLarge === true || current.length > maxItems) {
-              return yield* new OversizeChunkItemError({ size: computeSize([last]), maxBytes })
-            }
+          const singleItemTooLarge = computeSize(current) > maxBytes
+          if (singleItemTooLarge === true || current.length > maxItems) {
+            return yield* new OversizeChunkItemError({ size: computeSize(current), maxBytes })
           }
+
+          result.push(current)
         }
       }
 
-      flushCurrent()
-
-      return Chunk.fromIterable(result)
+      return result
     })

package/src/util.ts

@@ -1,24 +1,33 @@
 /// <reference lib="es2022" />
 
-import type { Brand } from '@livestore/utils/effect'
-import { Schema } from '@livestore/utils/effect'
+import { type Brand, Schema } from '@livestore/utils/effect'
 
 export type ParamsObject = Record<string, SqlValue>
 export type SqlValue = string | number | Uint8Array<ArrayBuffer> | null
 
 export type Bindable = ReadonlyArray<SqlValue> | ParamsObject
 
-export const SqlValueSchema = Schema.Union(
+/**
+ * Numeric schema for the SQLite `REAL` domain. Unlike `Schema.Finite` it accepts
+ * `Infinity`/`NaN`, because SQLite `REAL` columns can legitimately store them and
+ * bind values / DEFAULT codecs must round-trip those through the devtools/debug
+ * protocol. This is the single carve-out for the SQLite REAL numeric domain — use it
+ * instead of a bare `Schema.Number` so the `schemaNumber` exception lives in one place.
+ */
+// @effect-diagnostics-next-line schemaNumber:off -- see SqliteReal docstring: SQLite REAL permits Infinity/NaN, so Schema.Finite would wrongly reject valid values
+export const SqliteReal = Schema.Number
+
+export const SqlValueSchema = Schema.Union([
   Schema.String,
-  Schema.Number,
-  Schema.Uint8Array as any as Schema.Schema<Uint8Array<ArrayBuffer>>,
+  SqliteReal,
+  Schema.Uint8Array as any as Schema.Codec<Uint8Array<ArrayBuffer>>,
   Schema.Null,
-)
+])
 
-export const PreparedBindValues = Schema.Union(
+export const PreparedBindValues = Schema.Union([
   Schema.Array(SqlValueSchema),
-  Schema.Record({ key: Schema.String, value: SqlValueSchema }),
-).pipe(Schema.brand('PreparedBindValues'))
+  Schema.Record(Schema.String, SqlValueSchema),
+]).pipe(Schema.brand('PreparedBindValues'))
 
 export type PreparedBindValues = Brand.Branded<Bindable, 'PreparedBindValues'>
 

package/src/version.ts

@@ -7,8 +7,7 @@ import pkg from '../package.json' with { type: 'json' }
  */
 export const liveStoreVersion: string = (globalThis as any).__LIVESTORE_VERSION_OVERRIDE__ ?? pkg.version
 
-export const devtoolsProtocolVersion: number =
-  (globalThis as any).__LIVESTORE_DEVTOOLS_PROTOCOL_VERSION_OVERRIDE__ ?? 1
+export const devtoolsProtocolVersion: number = (globalThis as any).__LIVESTORE_DEVTOOLS_PROTOCOL_VERSION_OVERRIDE__ ?? 1
 
 export const supportedDevtoolsProtocolVersions: ReadonlyArray<number> = [devtoolsProtocolVersion]
 

package/dist/sql-queries/misc.d.ts

@@ -1,2 +0,0 @@
-export declare const objectEntries: <T extends Record<string, any>>(obj: T) => [keyof T & string, T[keyof T]][];
-//# sourceMappingURL=misc.d.ts.map

package/dist/sql-queries/misc.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"misc.d.ts","sourceRoot":"","sources":["../../src/sql-queries/misc.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,KAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAC3C,CAAA"}

package/dist/sql-queries/misc.js

@@ -1,2 +0,0 @@
-export const objectEntries = (obj) => Object.entries(obj);
-//# sourceMappingURL=misc.js.map

package/dist/sql-queries/misc.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"misc.js","sourceRoot":"","sources":["../../src/sql-queries/misc.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,aAAa,GAAG,CAAgC,GAAM,EAAoC,EAAE,CACvG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAqC,CAAA"}

package/src/sql-queries/misc.ts

@@ -1,2 +0,0 @@
-export const objectEntries = <T extends Record<string, any>>(obj: T): [keyof T & string, T[keyof T]][] =>
-  Object.entries(obj) as [keyof T & string, T[keyof T]][]