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

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.decodeUnknownSync(ApiSchema.ArgsSchema)(encoded)
+
+      expect(Option.isOption(decoded.handle)).toBe(true)
+      expect(decoded.handle._tag).toBe(c.handle._tag)
+      if (Option.isSome(c.handle)) {
+        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,
 }) {}
 
@@ -69,34 +72,34 @@ const LiveStoreEventGlobalFromStringRecord = Schema.Struct({
   seqNum: Schema.NumberFromString,
   parentSeqNum: Schema.NumberFromString,
   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.catch(() => Effect.succeed('-')))
             return yield* new UnknownError({
               cause: new Error(`Unauthorized (401): Couldn't connect to ElectricSQL: ${body}`),
             })
@@ -271,7 +274,7 @@ export const makeSyncBackend =
 
           // 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 +295,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 } }),
         )
 
@@ -311,7 +312,7 @@ export const makeSyncBackend =
       }).pipe(
         UnknownError.mapToUnknownError,
         Effect.timeout(pingTimeout),
-        Effect.catchTag('TimeoutException', () => SubscriptionRef.set(isConnected, false)),
+        Effect.catchTag('TimeoutError', () => 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