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

package/src/debug-info.ts

@@ -1,5 +1,5 @@
 /// <reference lib="dom" />
-import { ParseResult, Schema } from '@livestore/utils/effect'
+import { Schema, SchemaGetter, Struct } from '@livestore/utils/effect'
 
 import { BoundArray } from './bounded-collections.ts'
 import { PreparedBindValues } from './util.ts'
@@ -16,62 +16,73 @@ export type SlowQueryInfo = {
 export const SlowQueryInfo = Schema.Struct({
   queryStr: Schema.String,
   bindValues: Schema.UndefinedOr(PreparedBindValues),
-  durationMs: Schema.Number,
-  rowsCount: Schema.UndefinedOr(Schema.Number),
+  durationMs: Schema.Finite,
+  rowsCount: Schema.UndefinedOr(Schema.Finite),
   queriedTables: Schema.ReadonlySet(Schema.String),
-  startTimePerfNow: Schema.Number,
+  startTimePerfNow: Schema.Finite,
 })
 
-const BoundArraySchemaFromSelf = <A, I, R>(
-  item: Schema.Schema<A, I, R>,
-): Schema.Schema<BoundArray<A>, BoundArray<I>, R> =>
-  Schema.declare(
-    [item],
-    {
-      decode: (item) => (input, parseOptions, ast) => {
-        if (input instanceof BoundArray) {
-          const elements = ParseResult.decodeUnknown(Schema.Array(item))([...input], parseOptions)
-          return ParseResult.map(elements, (as): BoundArray<A> => BoundArray.make(input.sizeLimit, as))
+const isBoundArrayLike = <A>(value: unknown): value is BoundArray<A> => value instanceof BoundArray
+
+const BoundArraySchemaFromSelf = <A, I, RD, RE>(
+  item: Schema.Codec<A, I, RD, RE>,
+): Schema.Codec<BoundArray<A>, BoundArray<A>> =>
+  Schema.declare<BoundArray<A>>(isBoundArrayLike, {
+    identifier: 'BoundArray',
+    expected: 'BoundArray',
+    description: 'Bounded array',
+    toFormatter: () => (_) => `BoundArray(${_.length})`,
+    toArbitrary: () => (fc) => {
+      const itemArbitrary = Schema.toArbitrary(item)(fc)
+      return fc
+        .integer({ min: 0, max: 100 })
+        .chain((sizeLimit) =>
+          fc.array(itemArbitrary, { maxLength: sizeLimit }).map((items) => BoundArray.make(sizeLimit, items)),
+        )
+    },
+    toEquivalence: () => {
+      const elementEquivalence = Schema.toEquivalence(item)
+      return (a, b) => {
+        if (a === b) {
+          return true
         }
-        return ParseResult.fail(new ParseResult.Type(ast, input))
-      },
-      encode: (item) => (input, parseOptions, ast) => {
-        if (input instanceof BoundArray) {
-          const elements = ParseResult.encodeUnknown(Schema.Array(item))([...input], parseOptions)
-          return ParseResult.map(elements, (is): BoundArray<I> => BoundArray.make(input.sizeLimit, is))
+        if (isBoundArrayLike(a) === false || isBoundArrayLike(b) === false) {
+          return false
         }
-        return ParseResult.fail(new ParseResult.Type(ast, input))
-      },
-    },
-    {
-      description: `BoundArray<${Schema.format(item)}>`,
-      pretty: () => (_) => `BoundArray(${_.length})`,
-      arbitrary: () => (fc) => fc.anything() as any,
-      equivalence: () => (a, b) => a === b,
+        if (a.sizeLimit !== b.sizeLimit || a.length !== b.length) {
+          return false
+        }
+        const itemsA = [...a]
+        const itemsB = [...b]
+        for (let i = 0; i < itemsA.length; i++) {
+          if (elementEquivalence(itemsA[i]!, itemsB[i]!) === false) {
+            return false
+          }
+        }
+        return true
+      }
     },
-  )
+  })
 
-export const BoundArraySchema = <ItemDecoded, ItemEncoded>(elSchema: Schema.Schema<ItemDecoded, ItemEncoded>) =>
-  Schema.transform(
-    Schema.Struct({
-      size: Schema.Number,
-      items: Schema.Array(elSchema),
+export const BoundArraySchema = <ItemDecoded, ItemEncoded>(elSchema: Schema.Codec<ItemDecoded, ItemEncoded>) =>
+  Schema.Struct({
+    size: Schema.Finite,
+    items: Schema.Array(elSchema),
+  }).pipe(
+    Schema.decodeTo(BoundArraySchemaFromSelf(Schema.toType(elSchema)), {
+      decode: SchemaGetter.transform((_) => BoundArray.make(_.size, _.items)),
+      encode: SchemaGetter.transform((_) => ({ size: _.sizeLimit, items: [..._] })),
     }),
-    BoundArraySchemaFromSelf(Schema.typeSchema(elSchema)),
-    {
-      encode: (_) => ({ size: _.sizeLimit, items: [..._] }),
-      decode: (_) => BoundArray.make(_.size, _.items),
-    },
   )
 
 export const DebugInfo = Schema.Struct({
   slowQueries: BoundArraySchema(SlowQueryInfo),
-  queryFrameDuration: Schema.Number,
-  queryFrameCount: Schema.Number,
-  events: BoundArraySchema(Schema.Tuple(Schema.String, Schema.Any)),
+  queryFrameDuration: Schema.Finite,
+  queryFrameCount: Schema.Finite,
+  events: BoundArraySchema(Schema.Tuple([Schema.String, Schema.Any])),
 })
 
 export type DebugInfo = typeof DebugInfo.Type
 
-export const MutableDebugInfo = Schema.mutable(DebugInfo)
+export const MutableDebugInfo = DebugInfo.mapFields(Struct.map(Schema.mutableKey))
 export type MutableDebugInfo = typeof MutableDebugInfo.Type

package/src/defs.ts

@@ -3,8 +3,8 @@ import { Schema } from '@livestore/utils/effect'
 export const MigrationsReportEntry = Schema.Struct({
   tableName: Schema.String,
   hashes: Schema.Struct({
-    expected: Schema.Number,
-    actual: Schema.optional(Schema.Number),
+    expected: Schema.Finite,
+    actual: Schema.optional(Schema.Finite),
   }),
 })
 

package/src/devtools/devtools-compatibility.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+
+import { isDevtoolsProtocolVersionSupported, resolveDevtoolsProtocolVersion } from '../version.ts'
+
+/** Verifies: LS.SYS.DT-R02, LS.SYS.VER.PROTO-R01 */
+describe('DevTools protocol compatibility', () => {
+  it('treats legacy pings without a protocol version as protocol 1', () => {
+    expect(resolveDevtoolsProtocolVersion(undefined)).toBe(1)
+    expect(isDevtoolsProtocolVersionSupported(undefined, [1])).toBe(true)
+  })
+
+  it('accepts supported protocol versions independent of package version', () => {
+    expect(isDevtoolsProtocolVersionSupported(1, [1])).toBe(true)
+  })
+
+  it('rejects unsupported protocol versions', () => {
+    expect(isDevtoolsProtocolVersionSupported(2, [1])).toBe(false)
+  })
+})

package/src/devtools/devtools-messages-client-session.ts

@@ -5,111 +5,119 @@ import { EventSequenceNumber } from '../schema/mod.ts'
 import { PreparedBindValues } from '../util.ts'
 import { LSDClientSessionChannelMessage, LSDClientSessionReqResMessage } from './devtools-messages-common.ts'
 
-export class DebugInfoReq extends LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoReq', {}) {}
+export const DebugInfoReq = LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoReq', {})
 
-export class DebugInfoRes extends LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoRes', {
+export const DebugInfoRes = LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoRes', {
   debugInfo: DebugInfo,
-}) {}
+})
 
-export class DebugInfoHistorySubscribe extends LSDClientSessionReqResMessage(
-  'LSD.ClientSession.DebugInfoHistorySubscribe',
-  {
-    subscriptionId: Schema.String,
-  },
-) {}
+export const DebugInfoHistorySubscribe = LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoHistorySubscribe', {
+  subscriptionId: Schema.String,
+})
 
-export class DebugInfoHistoryRes extends LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoHistoryRes', {
+export const DebugInfoHistoryRes = LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoHistoryRes', {
   debugInfoHistory: Schema.Array(DebugInfo),
   subscriptionId: Schema.String,
-}) {}
+})
 
-export class DebugInfoHistoryUnsubscribe extends LSDClientSessionReqResMessage(
+export const DebugInfoHistoryUnsubscribe = LSDClientSessionReqResMessage(
   'LSD.ClientSession.DebugInfoHistoryUnsubscribe',
   {
     subscriptionId: Schema.String,
   },
-) {}
+)
 
-export class DebugInfoResetReq extends LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoResetReq', {}) {}
+export const DebugInfoResetReq = LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoResetReq', {})
 
-export class DebugInfoResetRes extends LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoResetRes', {}) {}
+export const DebugInfoResetRes = LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoResetRes', {})
 
-export class DebugInfoRerunQueryReq extends LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoRerunQueryReq', {
+export const DebugInfoRerunQueryReq = LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoRerunQueryReq', {
   queryStr: Schema.String,
   bindValues: Schema.UndefinedOr(PreparedBindValues),
   queriedTables: Schema.ReadonlySet(Schema.String),
-}) {}
+})
 
-export class DebugInfoRerunQueryRes extends LSDClientSessionReqResMessage(
-  'LSD.ClientSession.DebugInfoRerunQueryRes',
-  {},
-) {}
+export const DebugInfoRerunQueryRes = LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoRerunQueryRes', {})
 
-export class SyncHeadSubscribe extends LSDClientSessionReqResMessage('LSD.ClientSession.SyncHeadSubscribe', {
+export const SyncHeadSubscribe = LSDClientSessionReqResMessage('LSD.ClientSession.SyncHeadSubscribe', {
   subscriptionId: Schema.String,
-}) {}
-export class SyncHeadUnsubscribe extends LSDClientSessionReqResMessage('LSD.ClientSession.SyncHeadUnsubscribe', {
+})
+export const SyncHeadUnsubscribe = LSDClientSessionReqResMessage('LSD.ClientSession.SyncHeadUnsubscribe', {
   subscriptionId: Schema.String,
-}) {}
-export class SyncHeadRes extends LSDClientSessionReqResMessage('LSD.ClientSession.SyncHeadRes', {
-  local: EventSequenceNumber.EventSequenceNumber,
-  upstream: EventSequenceNumber.EventSequenceNumber,
+})
+export const SyncHeadRes = LSDClientSessionReqResMessage('LSD.ClientSession.SyncHeadRes', {
+  local: EventSequenceNumber.Client.Composite,
+  upstream: EventSequenceNumber.Client.Composite,
   subscriptionId: Schema.String,
-}) {}
+})
 
-export class ReactivityGraphSubscribe extends LSDClientSessionReqResMessage(
-  'LSD.ClientSession.ReactivityGraphSubscribe',
-  {
-    includeResults: Schema.Boolean,
-    subscriptionId: Schema.String,
-  },
-) {}
+export const ReactivityGraphSubscribe = LSDClientSessionReqResMessage('LSD.ClientSession.ReactivityGraphSubscribe', {
+  includeResults: Schema.Boolean,
+  subscriptionId: Schema.String,
+})
 
-export class ReactivityGraphUnsubscribe extends LSDClientSessionReqResMessage(
+export const ReactivityGraphUnsubscribe = LSDClientSessionReqResMessage(
   'LSD.ClientSession.ReactivityGraphUnsubscribe',
   {
     subscriptionId: Schema.String,
   },
-) {}
+)
 
-export class ReactivityGraphRes extends LSDClientSessionReqResMessage('LSD.ClientSession.ReactivityGraphRes', {
+export const ReactivityGraphRes = LSDClientSessionReqResMessage('LSD.ClientSession.ReactivityGraphRes', {
   reactivityGraph: Schema.Any,
   subscriptionId: Schema.String,
-}) {}
+})
 
-export class LiveQueriesSubscribe extends LSDClientSessionReqResMessage('LSD.ClientSession.LiveQueriesSubscribe', {
+export const LiveQueriesSubscribe = LSDClientSessionReqResMessage('LSD.ClientSession.LiveQueriesSubscribe', {
   subscriptionId: Schema.String,
-}) {}
+})
 
-export class LiveQueriesUnsubscribe extends LSDClientSessionReqResMessage('LSD.ClientSession.LiveQueriesUnsubscribe', {
+export const LiveQueriesUnsubscribe = LSDClientSessionReqResMessage('LSD.ClientSession.LiveQueriesUnsubscribe', {
   subscriptionId: Schema.String,
-}) {}
+})
 
-export class SerializedLiveQuery extends Schema.Struct({
-  _tag: Schema.Literal('computed', 'db', 'graphql', 'signal'),
-  id: Schema.Number,
+export const SerializedLiveQuery = Schema.Struct({
+  _tag: Schema.Literals(['computed', 'db', 'graphql', 'signal']),
+  id: Schema.Finite,
   label: Schema.String,
   hash: Schema.String,
-  runs: Schema.Number,
-  executionTimes: Schema.Array(Schema.Number),
+  runs: Schema.Finite,
+  executionTimes: Schema.Array(Schema.Finite),
   lastestResult: Schema.Any,
   activeSubscriptions: Schema.Array(
     Schema.Struct({ frames: Schema.Array(Schema.Struct({ name: Schema.String, filePath: Schema.String })) }),
   ),
-}) {}
+})
 
-export class LiveQueriesRes extends LSDClientSessionReqResMessage('LSD.ClientSession.LiveQueriesRes', {
+export const LiveQueriesRes = LSDClientSessionReqResMessage('LSD.ClientSession.LiveQueriesRes', {
   liveQueries: Schema.Array(SerializedLiveQuery),
   subscriptionId: Schema.String,
-}) {}
-
-export class Ping extends LSDClientSessionReqResMessage('LSD.ClientSession.Ping', {}) {}
-
-export class Pong extends LSDClientSessionReqResMessage('LSD.ClientSession.Pong', {}) {}
-
-export class Disconnect extends LSDClientSessionChannelMessage('LSD.ClientSession.Disconnect', {}) {}
-
-export const MessageToApp = Schema.Union(
+})
+
+export const Ping = LSDClientSessionReqResMessage('LSD.ClientSession.Ping', {
+  devtoolsProtocolVersion: Schema.optional(Schema.Finite),
+})
+
+export const Pong = LSDClientSessionReqResMessage('LSD.ClientSession.Pong', {
+  devtoolsProtocolVersion: Schema.optional(Schema.Finite),
+})
+
+/**
+ * Sent by the app when the DevTools protocol isn't compatible.
+ * Contains package versions for display and protocol versions for the actual compatibility decision.
+ */
+export const VersionMismatch = LSDClientSessionReqResMessage('LSD.ClientSession.VersionMismatch', {
+  /** The version running in the app */
+  appVersion: Schema.String,
+  /** The version that was sent by DevTools (that caused the mismatch) */
+  receivedVersion: Schema.String,
+  appDevtoolsProtocolVersion: Schema.Finite,
+  receivedDevtoolsProtocolVersion: Schema.optional(Schema.Finite),
+})
+
+export const Disconnect = LSDClientSessionChannelMessage('LSD.ClientSession.Disconnect', {})
+
+export const MessageToApp = Schema.Union([
   DebugInfoReq,
   DebugInfoHistorySubscribe,
   DebugInfoHistoryUnsubscribe,
@@ -123,11 +131,11 @@ export const MessageToApp = Schema.Union(
   Ping,
   SyncHeadSubscribe,
   SyncHeadUnsubscribe,
-).annotations({ identifier: 'LSD.ClientSession.MessageToApp' })
+]).annotate({ identifier: 'LSD.ClientSession.MessageToApp' })
 
 export type MessageToApp = typeof MessageToApp.Type
 
-export const MessageFromApp = Schema.Union(
+export const MessageFromApp = Schema.Union([
   DebugInfoRes,
   DebugInfoHistoryRes,
   DebugInfoResetRes,
@@ -136,7 +144,8 @@ export const MessageFromApp = Schema.Union(
   LiveQueriesRes,
   Disconnect,
   Pong,
+  VersionMismatch,
   SyncHeadRes,
-).annotations({ identifier: 'LSD.ClientSession.MessageFromApp' })
+]).annotate({ identifier: 'LSD.ClientSession.MessageFromApp' })
 
 export type MessageFromApp = typeof MessageFromApp.Type

package/src/devtools/devtools-messages-common.ts

@@ -1,26 +1,21 @@
 import { Schema } from '@livestore/utils/effect'
 
-import { liveStoreVersion as pkgVersion } from '../version.ts'
-
-export const NetworkStatus = Schema.Struct({
-  isConnected: Schema.Boolean,
-  timestampMs: Schema.Number,
-  /** Whether the network status devtools latch is closed. Used to simulate network disconnection. */
-  latchClosed: Schema.Boolean,
-})
-
-export type NetworkStatus = typeof NetworkStatus.Type
+export { NetworkStatus } from '../sync/sync-backend.ts'
 
 export const requestId = Schema.String
 export const clientId = Schema.String
 export const sessionId = Schema.String
-export const liveStoreVersion = Schema.Literal(pkgVersion)
+/**
+ * Display/package version field for DevTools messages.
+ * Compatibility is decided by the optional DevTools protocol version carried by handshake messages.
+ */
+export const liveStoreVersion = Schema.String
 
 export const LSDMessage = <Tag extends string, Fields extends Schema.Struct.Fields>(tag: Tag, fields: Fields) =>
   Schema.TaggedStruct(tag, {
     liveStoreVersion,
     ...fields,
-  }).annotations({ identifier: tag })
+  }).annotate({ identifier: tag })
 
 export const LSDChannelMessage = <Tag extends string, Fields extends Schema.Struct.Fields>(tag: Tag, fields: Fields) =>
   LSDMessage(tag, {
@@ -92,23 +87,24 @@ export const LeaderReqResMessage = <
     requestId,
     liveStoreVersion,
     ...fields.success,
-  }).annotations({ identifier: `${tag}.Response.Success` })
+  }).annotate({ identifier: `${tag}.Response.Success` })
 
-  const Error = fields.error
-    ? Schema.TaggedStruct(`${tag}.Response.Error`, {
-        requestId,
-        liveStoreVersion,
-        ...fields.error,
-      }).annotations({ identifier: `${tag}.Response.Error` })
-    : Schema.Never
+  const Error =
+    fields.error !== undefined
+      ? Schema.TaggedStruct(`${tag}.Response.Error`, {
+          requestId,
+          liveStoreVersion,
+          ...fields.error,
+        }).annotate({ identifier: `${tag}.Response.Error` })
+      : Schema.Never
 
   return {
     Request: Schema.TaggedStruct(`${tag}.Request`, {
       requestId,
       liveStoreVersion,
       ...fields.payload,
-    }).annotations({ identifier: `${tag}.Request` }),
-    Response: Schema.Union(Success, Error),
+    }).annotate({ identifier: `${tag}.Request` }),
+    Response: Schema.Union([Success, Error]),
     Success,
     Error,
   } as any