@livestore/sync-electric 0.4.0 → 0.5.0-dev.1

package/package.json

@@ -1,80 +1,63 @@
 {
+  "$genie": {
+    "source": "package.json.genie.ts",
+    "warning": "DO NOT EDIT - changes will be overwritten",
+    "workspaceClosureDirs": [
+      "packages/@livestore/sync-electric",
+      "repos/livestore/packages/@livestore/common",
+      "repos/livestore/packages/@livestore/utils",
+      "repos/livestore/packages/@livestore/utils-dev",
+      "repos/livestore/packages/@livestore/webmesh"
+    ]
+  },
   "name": "@livestore/sync-electric",
-  "version": "0.4.0",
+  "version": "0.5.0-dev.1",
+  "type": "module",
+  "sideEffects": false,
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/livestorejs/livestore.git"
+    "url": "git+https://github.com/livestorejs/livestore-contrib.git"
+  },
+  "exports": {
+    ".": "./dist/index.js"
   },
   "files": [
     "dist",
     "package.json",
     "src"
   ],
-  "type": "module",
-  "sideEffects": false,
-  "exports": {
-    ".": "./dist/index.js"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
   "dependencies": {
-    "@livestore/common": "^0.4.0",
-    "@livestore/utils": "^0.4.0"
+    "@livestore/common": "0.5.0-dev.1",
+    "@livestore/utils": "0.5.0-dev.1"
   },
   "devDependencies": {
-    "@effect/ai": "0.35.0",
-    "@effect/cli": "0.75.1",
-    "@effect/cluster": "0.58.2",
-    "@effect/experimental": "0.60.0",
-    "@effect/opentelemetry": "0.63.0",
-    "@effect/platform": "0.96.1",
-    "@effect/platform-browser": "0.76.0",
-    "@effect/platform-bun": "0.89.0",
-    "@effect/platform-node": "0.106.0",
-    "@effect/printer": "0.49.0",
-    "@effect/printer-ansi": "0.49.0",
-    "@effect/rpc": "0.75.1",
-    "@effect/sql": "0.51.1",
-    "@effect/typeclass": "0.40.0",
-    "@effect/vitest": "0.29.0",
+    "@effect/opentelemetry": "4.0.3",
+    "@effect/platform-browser": "4.0.3",
+    "@effect/platform-bun": "4.0.3",
+    "@effect/platform-node": "4.0.3",
+    "@effect/platform-node-shared": "4.0.3",
+    "@effect/vitest": "4.0.3",
     "@opentelemetry/api": "1.9.0",
     "@opentelemetry/resources": "2.2.0",
     "@standard-schema/spec": "1.1.0",
-    "effect": "3.21.2"
+    "effect": "4.0.3",
+    "vitest": "4.1.9"
   },
   "peerDependencies": {
-    "@effect/ai": "^0.35.0",
-    "@effect/cli": "^0.75.1",
-    "@effect/cluster": "^0.58.2",
-    "@effect/experimental": "^0.60.0",
-    "@effect/opentelemetry": "^0.63.0",
-    "@effect/platform": "^0.96.1",
-    "@effect/platform-browser": "^0.76.0",
-    "@effect/platform-bun": "^0.89.0",
-    "@effect/platform-node": "^0.106.0",
-    "@effect/printer": "^0.49.0",
-    "@effect/printer-ansi": "^0.49.0",
-    "@effect/rpc": "^0.75.1",
-    "@effect/sql": "^0.51.1",
-    "@effect/typeclass": "^0.40.0",
-    "@effect/vitest": "^0.29.0",
+    "@effect/opentelemetry": "^4.0.3",
+    "@effect/platform-browser": "^4.0.3",
+    "@effect/platform-bun": "^4.0.3",
+    "@effect/platform-node": "^4.0.3",
+    "@effect/platform-node-shared": "^4.0.3",
+    "@effect/vitest": "^4.0.3",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/resources": "^2.2.0",
     "@standard-schema/spec": "^1.1.0",
-    "effect": "^3.21.2"
+    "effect": "^4.0.3"
   },
-  "$genie": {
-    "source": "package.json.genie.ts",
-    "warning": "DO NOT EDIT - changes will be overwritten",
-    "workspaceClosureDirs": [
-      "packages/@livestore/common",
-      "packages/@livestore/sync-electric",
-      "packages/@livestore/utils",
-      "packages/@livestore/utils-dev",
-      "packages/@livestore/webmesh"
-    ]
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
     "build": "",

package/src/api-schema.test.ts

@@ -0,0 +1,49 @@
+import { Option, Schema } from '@livestore/utils/effect'
+import { describe, expect, it } from 'vitest'
+
+import * as ApiSchema from './api-schema.ts'
+import { makeElectricUrl } from './make-electric-url.ts'
+
+const HandleStruct = { offset: 'off-1', handle: 'h-1' } as const
+
+const cases = [
+  { name: 'none + no payload', storeId: 's1', payload: undefined, handle: Option.none(), live: false },
+  { name: 'some + payload', storeId: 's2', payload: { foo: 'bar' }, handle: Option.some(HandleStruct), live: true },
+  { name: 'none + payload present', storeId: 's3', payload: { a: 1 }, handle: Option.none(), live: false },
+  { name: 'some + no payload', storeId: 's4', payload: undefined, handle: Option.some(HandleStruct), live: true },
+  { name: 'none + null payload', storeId: 's5', payload: null, handle: Option.none(), live: false },
+] as const
+
+describe('sync-electric ArgsSchema round-trip', () => {
+  for (const c of cases) {
+    it(`round-trips ${c.name}`, () => {
+      const input = ApiSchema.PullPayload.make({
+        storeId: c.storeId,
+        payload: c.payload,
+        handle: c.handle,
+        live: c.live,
+      })
+
+      const encoded = Schema.encodeSync(ApiSchema.ArgsSchema)(input)
+      expect(typeof encoded).toBe('string')
+
+      const decoded = Schema.decodeSync(ApiSchema.ArgsSchema)(encoded)
+
+      expect(Option.isOption(decoded.handle)).toBe(true)
+      expect(decoded.handle._tag).toBe(c.handle._tag)
+      if (Option.isSome(c.handle) === true) {
+        expect((decoded.handle as Option.Some<typeof HandleStruct>).value).toEqual(HandleStruct)
+      }
+      expect(decoded.payload).toEqual(c.payload)
+      expect(decoded.storeId).toBe(c.storeId)
+      expect(decoded.live).toBe(c.live)
+
+      // Full path through makeElectricUrl: URLSearchParams -> Struct({ args }) -> ArgsSchema
+      const searchParams = new URLSearchParams({ args: encoded })
+      const result = makeElectricUrl({ electricHost: 'http://electric.test', searchParams })
+      expect(result.storeId).toBe(c.storeId)
+      expect(result.needsInit).toBe(Option.isNone(c.handle))
+      expect(result.payload).toEqual(c.payload)
+    })
+  }
+})

package/src/api-schema.ts

@@ -4,21 +4,29 @@ import { Schema } from '@livestore/utils/effect'
 export const PushPayload = Schema.TaggedStruct('@livestore/sync-electric.Push', {
   storeId: Schema.String,
   batch: Schema.Array(LiveStoreEvent.Global.Encoded),
-}).annotations({ title: '@livestore/sync-electric.PushPayload' })
+}).annotate({ title: '@livestore/sync-electric.PushPayload' })
 
 export const PullPayload = Schema.TaggedStruct('@livestore/sync-electric.Pull', {
   storeId: Schema.String,
-  payload: Schema.UndefinedOr(Schema.JsonValue),
-  handle: Schema.Option(
-    Schema.Struct({
-      offset: Schema.String,
-      handle: Schema.String,
-    }),
+  // `optional` so an absent payload is omitted from the JSON entirely (a required key with an
+  // `undefined` value would be dropped by `JSON.stringify` and then fail decoding as "Missing key").
+  payload: Schema.optional(Schema.Json),
+  // `toCodecJson` makes the `Option` encode to its JSON-safe struct form (`{ _tag: "None" }` /
+  // `{ _tag: "Some", value }`). A bare `Schema.Option` encodes to a runtime `Option`, whose
+  // `toJSON` leaks `{"_id":"Option",...}` when `fromJsonString` runs `JSON.stringify`, and that
+  // shape then fails to decode back into an `Option`.
+  handle: Schema.toCodecJson(
+    Schema.Option(
+      Schema.Struct({
+        offset: Schema.String,
+        handle: Schema.String,
+      }),
+    ),
   ),
   live: Schema.Boolean,
-}).annotations({ title: '@livestore/sync-electric.PullPayload' })
+}).annotate({ title: '@livestore/sync-electric.PullPayload' })
 
-export const ApiPayload = Schema.Union(PullPayload, PushPayload)
+export const ApiPayload = Schema.Union([PullPayload, PushPayload])
 
 // Format for the query params
-export const ArgsSchema = Schema.compose(Schema.StringFromUriComponent, Schema.parseJson(PullPayload))
+export const ArgsSchema = Schema.StringFromUriComponent.pipe(Schema.decodeTo(Schema.fromJsonString(PullPayload)))

package/src/index.ts

@@ -9,6 +9,7 @@ import {
   HttpClientResponse,
   Option,
   ReadonlyArray,
+  Result,
   Schedule,
   Schema,
   Stream,
@@ -17,8 +18,10 @@ import {
 
 import * as ApiSchema from './api-schema.ts'
 
-export class InvalidOperationError extends Schema.TaggedError<InvalidOperationError>('~@livestore/sync-electric/InvalidOperationError')('InvalidOperationError', {
-  operation: Schema.Literal('delete', 'update'),
+export class InvalidOperationError extends Schema.TaggedError<InvalidOperationError>(
+  '~@livestore/sync-electric/InvalidOperationError',
+)('InvalidOperationError', {
+  operation: Schema.Literals(['delete', 'update']),
   message: Schema.String,
 }) {}
 
@@ -66,37 +69,37 @@ Also see: https://github.com/electric-sql/electric/blob/main/packages/typescript
 */
 
 const LiveStoreEventGlobalFromStringRecord = Schema.Struct({
-  seqNum: Schema.NumberFromString,
-  parentSeqNum: Schema.NumberFromString,
+  seqNum: Schema.FiniteFromString,
+  parentSeqNum: Schema.FiniteFromString,
   name: Schema.String,
-  args: Schema.parseJson(Schema.Any),
+  args: Schema.fromJsonString(Schema.Any),
   clientId: Schema.String,
   sessionId: Schema.String,
 })
-  .pipe(Schema.compose(LiveStoreEvent.Global.Encoded))
-  .annotations({ title: '@livestore/sync-electric:LiveStoreEventGlobalFromStringRecord' })
+  .pipe(Schema.decodeTo(LiveStoreEvent.Global.Encoded))
+  .annotate({ title: '@livestore/sync-electric:LiveStoreEventGlobalFromStringRecord' })
 
 const ResponseItemInsert = Schema.Struct({
   /** Postgres path (e.g. `"public"."events_9069baf0_b3e6_42f7_980f_188416eab3fx3"/"0"`) */
   key: Schema.optional(Schema.String),
   value: LiveStoreEventGlobalFromStringRecord,
   headers: Schema.Struct({ operation: Schema.Literal('insert'), relation: Schema.Array(Schema.String) }),
-}).annotations({ title: '@livestore/sync-electric:ResponseItemInsert' })
+}).annotate({ title: '@livestore/sync-electric:ResponseItemInsert' })
 
 const ResponseItemInvalid = Schema.Struct({
   /** Postgres path (e.g. `"public"."events_9069baf0_b3e6_42f7_980f_188416eab3fx3"/"0"`) */
   key: Schema.optional(Schema.String),
   value: Schema.Any,
-  headers: Schema.Struct({ operation: Schema.Literal('update', 'delete'), relation: Schema.Array(Schema.String) }),
-}).annotations({ title: '@livestore/sync-electric:ResponseItemInvalid' })
+  headers: Schema.Struct({ operation: Schema.Literals(['update', 'delete']), relation: Schema.Array(Schema.String) }),
+}).annotate({ title: '@livestore/sync-electric:ResponseItemInvalid' })
 
 const ResponseItemControl = Schema.Struct({
   key: Schema.optional(Schema.String),
   value: Schema.optional(Schema.Any),
   headers: Schema.Struct({ control: Schema.String }),
-}).annotations({ title: '@livestore/sync-electric:ResponseItemControl' })
+}).annotate({ title: '@livestore/sync-electric:ResponseItemControl' })
 
-const ResponseItem = Schema.Union(ResponseItemInsert, ResponseItemInvalid, ResponseItemControl)
+const ResponseItem = Schema.Union([ResponseItemInsert, ResponseItemInvalid, ResponseItemControl])
 
 const ResponseHeaders = Schema.Struct({
   'electric-handle': Schema.String,
@@ -133,12 +136,12 @@ export interface SyncBackendOptions {
      * How long to wait for a ping response before timing out
      * @default 10 seconds
      */
-    requestTimeout?: Duration.DurationInput
+    requestTimeout?: Duration.Input
     /**
      * How often to send ping requests
      * @default 10 seconds
      */
-    requestInterval?: Duration.DurationInput
+    requestInterval?: Duration.Input
   }
 }
 
@@ -220,7 +223,7 @@ export const makeSyncBackend =
         UnknownError | IsOfflineError
       > =>
         Effect.gen(function* () {
-          const argsJson = yield* Schema.encode(ApiSchema.ArgsSchema)(
+          const argsJson = yield* Schema.encodeEffect(ApiSchema.ArgsSchema)(
             ApiSchema.PullPayload.make({ storeId, handle, payload, live }),
           )
           const url = `${pullEndpoint}?args=${argsJson}`
@@ -228,7 +231,7 @@ export const makeSyncBackend =
           const resp = yield* httpClient.get(url)
 
           if (resp.status === 401) {
-            const body = yield* resp.text.pipe(Effect.catchAll(() => Effect.succeed('-')))
+            const body = yield* resp.text.pipe(Effect.orElseSucceed(() => '-'))
             return yield* new UnknownError({
               cause: new Error(`Unauthorized (401): Couldn't connect to ElectricSQL: ${body}`),
             })
@@ -265,13 +268,11 @@ export const makeSyncBackend =
             return Option.some([[], Option.some(nextHandle)] as const)
           }
 
-          const allItems = yield* HttpClientResponse.schemaBodyJson(Schema.Array(ResponseItem), {
-            onExcessProperty: 'preserve',
-          })(resp)
+          const allItems = yield* HttpClientResponse.schemaBodyJson(Schema.Array(ResponseItem))(resp)
 
           // Check for delete/update operations and throw descriptive error
           const invalidOperations = ReadonlyArray.filterMap(allItems, (item) =>
-            Schema.is(ResponseItemInvalid)(item) === true ? Option.some(item.headers.operation) : Option.none(),
+            Schema.is(ResponseItemInvalid)(item) === true ? Result.succeed(item.headers.operation) : Result.failVoid,
           )
 
           if (invalidOperations.length > 0) {
@@ -292,9 +293,7 @@ export const makeSyncBackend =
           return Option.some([items, Option.some(nextHandle)] as const)
         }).pipe(
           Effect.scoped,
-          Effect.mapError((cause) =>
-            cause._tag === 'UnknownError' ? cause : new UnknownError({ cause }),
-          ),
+          Effect.mapError((cause) => (Schema.is(UnknownError)(cause) === true ? cause : new UnknownError({ cause }))),
           Effect.withSpan('electric-provider:runPull', { attributes: { handle, live } }),
         )
 
@@ -310,8 +309,10 @@ export const makeSyncBackend =
         yield* SubscriptionRef.set(isConnected, true)
       }).pipe(
         UnknownError.mapToUnknownError,
-        Effect.timeout(pingTimeout),
-        Effect.catchTag('TimeoutException', () => SubscriptionRef.set(isConnected, false)),
+        Effect.timeoutOrElse({
+          duration: pingTimeout,
+          orElse: () => SubscriptionRef.set(isConnected, false),
+        }),
         Effect.withSpan('electric-provider:ping'),
       )
 
@@ -332,27 +333,27 @@ export const makeSyncBackend =
         pull: (cursor, options) => {
           let hasEmittedAtLeastOnce = false
 
-          return Stream.unfoldEffect(cursor.pipe(Option.flatMap((_) => _.metadata)), (metadataOption) =>
+          return Stream.unfold(cursor.pipe(Option.flatMap((_) => _.metadata)), (metadataOption) =>
             Effect.gen(function* () {
               const result = yield* runPull(metadataOption, { live: options?.live ?? false })
-              if (Option.isNone(result) === true) return Option.none()
+              if (Option.isNone(result) === true) return undefined
 
               const [batch, nextMetadataOption] = result.value
 
               // Continue pagination if we have data
               if (batch.length > 0) {
                 hasEmittedAtLeastOnce = true
-                return Option.some([{ batch, hasMore: true }, nextMetadataOption])
+                return [{ batch, hasMore: true as boolean }, nextMetadataOption] as const
               }
 
               // Make sure we emit at least once even if there's no data or we're live-pulling
               if (hasEmittedAtLeastOnce === false || options?.live === true) {
                 hasEmittedAtLeastOnce = true
-                return Option.some([{ batch, hasMore: false }, nextMetadataOption])
+                return [{ batch, hasMore: false as boolean }, nextMetadataOption] as const
               }
 
               // Stop on empty batch (when not live)
-              return Option.none()
+              return undefined
             }),
           ).pipe(
             Stream.map(({ batch, hasMore }) => ({

package/src/make-electric-url.ts

@@ -1,5 +1,5 @@
 import { shouldNeverHappen } from '@livestore/utils'
-import { Hash, Schema } from '@livestore/utils/effect'
+import { Hash, Result, Schema } from '@livestore/utils/effect'
 
 import * as ApiSchema from './api-schema.ts'
 
@@ -40,13 +40,13 @@ export const makeElectricUrl = ({
    */
   needsInit: boolean
   /** Sync payload provided by the client */
-  payload: Schema.JsonValue | undefined
+  payload: Schema.Json | undefined
 } => {
   const endpointUrl = `${electricHost}/v1/shape`
   const UrlParamsSchema = Schema.Struct({ args: ApiSchema.ArgsSchema })
-  const argsResult = Schema.decodeUnknownEither(UrlParamsSchema)(Object.fromEntries(providedSearchParams.entries()))
+  const argsResult = Schema.decodeUnknownResult(UrlParamsSchema)(Object.fromEntries(providedSearchParams.entries()))
 
-  if (argsResult._tag === 'Left') {
+  if (Result.isFailure(argsResult) === true) {
     return shouldNeverHappen(
       'Invalid search params provided to makeElectricUrl',
       providedSearchParams,
@@ -54,7 +54,7 @@ export const makeElectricUrl = ({
     )
   }
 
-  const args = argsResult.right.args
+  const args = argsResult.success.args
   const tableName = toTableName(args.storeId)
   // TODO refactor with Effect URLSearchParams schema
   // https://electric-sql.com/openapi.html