@livestore/sync-electric 0.4.0-dev.8 → 0.4.0

package/src/index.ts

@@ -1,10 +1,4 @@
-import {
-  InvalidPullError,
-  InvalidPushError,
-  type IsOfflineError,
-  SyncBackend,
-  UnexpectedError,
-} from '@livestore/common'
+import { type IsOfflineError, SyncBackend, UnknownError } from '@livestore/common'
 import { LiveStoreEvent } from '@livestore/common/schema'
 import { notYetImplemented } from '@livestore/utils'
 import {
@@ -23,8 +17,8 @@ import {
 
 import * as ApiSchema from './api-schema.ts'
 
-export class InvalidOperationError extends Schema.TaggedError<InvalidOperationError>()('InvalidOperationError', {
-  operation: Schema.Union(Schema.Literal('delete'), Schema.Literal('update')),
+export class InvalidOperationError extends Schema.TaggedError<InvalidOperationError>('~@livestore/sync-electric/InvalidOperationError')('InvalidOperationError', {
+  operation: Schema.Literal('delete', 'update'),
   message: Schema.String,
 }) {}
 
@@ -79,12 +73,7 @@ const LiveStoreEventGlobalFromStringRecord = Schema.Struct({
   clientId: Schema.String,
   sessionId: Schema.String,
 })
-  .pipe(
-    Schema.transform(LiveStoreEvent.AnyEncodedGlobal, {
-      decode: (_) => _,
-      encode: (_) => _,
-    }),
-  )
+  .pipe(Schema.compose(LiveStoreEvent.Global.Encoded))
   .annotations({ title: '@livestore/sync-electric:LiveStoreEventGlobalFromStringRecord' })
 
 const ResponseItemInsert = Schema.Struct({
@@ -161,6 +150,47 @@ export const SyncMetadata = Schema.Struct({
 
 export type SyncMetadata = typeof SyncMetadata.Type
 
+/**
+ * Creates a sync backend that uses ElectricSQL for real-time event synchronization.
+ *
+ * ElectricSQL enables real-time sync by streaming PostgreSQL changes to clients.
+ * This backend handles push (inserting events) and pull (streaming events via Electric's
+ * shape-based sync protocol).
+ *
+ * The endpoint should typically be part of your API layer to handle authentication,
+ * rate limiting, and proxying requests to the Electric server.
+ *
+ * @example
+ * ```ts
+ * import { makeSyncBackend } from '@livestore/sync-electric'
+ *
+ * const adapter = makePersistedAdapter({
+ *   sync: {
+ *     backend: makeSyncBackend({
+ *       endpoint: '/api/electric',
+ *     }),
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With separate endpoints for push/pull/ping
+ * const backend = makeSyncBackend({
+ *   endpoint: {
+ *     push: '/api/push-event',
+ *     pull: '/api/pull-events',
+ *     ping: '/api/ping',
+ *   },
+ *   ping: {
+ *     enabled: true,
+ *     requestInterval: 15_000, // 15 seconds
+ *   },
+ * })
+ * ```
+ *
+ * @see https://livestore.dev/docs/sync/electric for setup guide
+ */
 export const makeSyncBackend =
   ({ endpoint, ...options }: SyncBackendOptions): SyncBackend.SyncBackendConstructor<SyncMetadata> =>
   ({ storeId, payload }) =>
@@ -181,13 +211,13 @@ export const makeSyncBackend =
             /** The batch of events */
             ReadonlyArray<{
               metadata: Option.Option<SyncMetadata>
-              eventEncoded: LiveStoreEvent.AnyEncodedGlobal
+              eventEncoded: LiveStoreEvent.Global.Encoded
             }>,
             /** The next handle to use for the next pull */
             Option.Option<SyncMetadata>,
           ]
         >,
-        InvalidPullError | IsOfflineError
+        UnknownError | IsOfflineError
       > =>
         Effect.gen(function* () {
           const argsJson = yield* Schema.encode(ApiSchema.ArgsSchema)(
@@ -199,7 +229,7 @@ export const makeSyncBackend =
 
           if (resp.status === 401) {
             const body = yield* resp.text.pipe(Effect.catchAll(() => Effect.succeed('-')))
-            return yield* InvalidPullError.make({
+            return yield* new UnknownError({
               cause: new Error(`Unauthorized (401): Couldn't connect to ElectricSQL: ${body}`),
             })
           } else if (resp.status === 400) {
@@ -220,9 +250,7 @@ export const makeSyncBackend =
             return notYetImplemented(`Electric shape not found`)
           } else if (resp.status < 200 || resp.status >= 300) {
             const body = yield* resp.text
-            return yield* InvalidPullError.make({
-              cause: new Error(`Unexpected status code: ${resp.status}: ${body}`),
-            })
+            return yield* new UnknownError({ cause: new Error(`Unexpected status code: ${resp.status}: ${body}`) })
           }
 
           const headers = yield* HttpClientResponse.schemaHeaders(ResponseHeaders)(resp)
@@ -243,7 +271,7 @@ export const makeSyncBackend =
 
           // Check for delete/update operations and throw descriptive error
           const invalidOperations = ReadonlyArray.filterMap(allItems, (item) =>
-            Schema.is(ResponseItemInvalid)(item) ? Option.some(item.headers.operation) : Option.none(),
+            Schema.is(ResponseItemInvalid)(item) === true ? Option.some(item.headers.operation) : Option.none(),
           )
 
           if (invalidOperations.length > 0) {
@@ -256,7 +284,7 @@ export const makeSyncBackend =
 
           const items = allItems.filter(Schema.is(ResponseItemInsert)).map((item) => ({
             metadata: Option.some({ offset: nextHandle.offset, handle: nextHandle.handle }),
-            eventEncoded: item.value as LiveStoreEvent.AnyEncodedGlobal,
+            eventEncoded: item.value,
           }))
 
           yield* Effect.annotateCurrentSpan({ itemsCount: items.length, nextHandle })
@@ -264,7 +292,9 @@ export const makeSyncBackend =
           return Option.some([items, Option.some(nextHandle)] as const)
         }).pipe(
           Effect.scoped,
-          Effect.mapError((cause) => (cause._tag === 'InvalidPullError' ? cause : InvalidPullError.make({ cause }))),
+          Effect.mapError((cause) =>
+            cause._tag === 'UnknownError' ? cause : new UnknownError({ cause }),
+          ),
           Effect.withSpan('electric-provider:runPull', { attributes: { handle, live } }),
         )
 
@@ -279,7 +309,7 @@ export const makeSyncBackend =
 
         yield* SubscriptionRef.set(isConnected, true)
       }).pipe(
-        UnexpectedError.mapToUnexpectedError,
+        UnknownError.mapToUnknownError,
         Effect.timeout(pingTimeout),
         Effect.catchTag('TimeoutException', () => SubscriptionRef.set(isConnected, false)),
         Effect.withSpan('electric-provider:ping'),
@@ -294,9 +324,8 @@ export const makeSyncBackend =
 
       // If the pull endpoint has the same origin as the current page, we can assume that we already have a connection
       // otherwise we send a HEAD request to speed up the connection process
-      const connect: SyncBackend.SyncBackend<SyncMetadata>['connect'] = pullEndpointHasSameOrigin
-        ? Effect.void
-        : ping.pipe(UnexpectedError.mapToUnexpectedError)
+      const connect: SyncBackend.SyncBackend<SyncMetadata>['connect'] =
+        pullEndpointHasSameOrigin === true ? Effect.void : ping.pipe(UnknownError.mapToUnknownError)
 
       return SyncBackend.of({
         connect,
@@ -306,7 +335,7 @@ export const makeSyncBackend =
           return Stream.unfoldEffect(cursor.pipe(Option.flatMap((_) => _.metadata)), (metadataOption) =>
             Effect.gen(function* () {
               const result = yield* runPull(metadataOption, { live: options?.live ?? false })
-              if (Option.isNone(result)) return Option.none()
+              if (Option.isNone(result) === true) return Option.none()
 
               const [batch, nextMetadataOption] = result.value
 
@@ -317,7 +346,7 @@ export const makeSyncBackend =
               }
 
               // Make sure we emit at least once even if there's no data or we're live-pulling
-              if (hasEmittedAtLeastOnce === false || options?.live) {
+              if (hasEmittedAtLeastOnce === false || options?.live === true) {
                 hasEmittedAtLeastOnce = true
                 return Option.some([{ batch, hasMore: false }, nextMetadataOption])
               }
@@ -328,28 +357,27 @@ export const makeSyncBackend =
           ).pipe(
             Stream.map(({ batch, hasMore }) => ({
               batch,
-              pageInfo: hasMore ? SyncBackend.pageInfoMoreUnknown : SyncBackend.pageInfoNoMore,
+              pageInfo: hasMore === true ? SyncBackend.pageInfoMoreUnknown : SyncBackend.pageInfoNoMore,
             })),
             Stream.withSpan('electric-provider:pull'),
           )
         },
 
-        push: (batch) =>
-          Effect.gen(function* () {
-            const resp = yield* HttpClientRequest.schemaBodyJson(ApiSchema.PushPayload)(
-              HttpClientRequest.post(pushEndpoint),
-              ApiSchema.PushPayload.make({ storeId, batch }),
-            ).pipe(
-              Effect.andThen(httpClient.pipe(HttpClient.filterStatusOk).execute),
-              Effect.andThen(HttpClientResponse.schemaBodyJson(Schema.Struct({ success: Schema.Boolean }))),
-              Effect.scoped,
-              Effect.mapError((cause) => InvalidPushError.make({ cause: UnexpectedError.make({ cause }) })),
-            )
-
-            if (!resp.success) {
-              return yield* InvalidPushError.make({ cause: new UnexpectedError({ cause: new Error('Push failed') }) })
-            }
-          }).pipe(Effect.withSpan('electric-provider:push')),
+        push: Effect.fn('electric-provider:push')(function* (batch) {
+          const resp = yield* HttpClientRequest.schemaBodyJson(ApiSchema.PushPayload)(
+            HttpClientRequest.post(pushEndpoint),
+            ApiSchema.PushPayload.make({ storeId, batch }),
+          ).pipe(
+            Effect.andThen(httpClient.pipe(HttpClient.filterStatusOk).execute),
+            Effect.andThen(HttpClientResponse.schemaBodyJson(Schema.Struct({ success: Schema.Boolean }))),
+            Effect.scoped,
+            Effect.mapError((cause) => UnknownError.make({ cause })),
+          )
+
+          if (resp.success === false) {
+            return yield* new UnknownError({ cause: new Error('Push failed') })
+          }
+        }),
         ping,
         isConnected,
         metadata: {

package/src/make-electric-url.ts

@@ -1,5 +1,6 @@
 import { shouldNeverHappen } from '@livestore/utils'
 import { Hash, Schema } from '@livestore/utils/effect'
+
 import * as ApiSchema from './api-schema.ts'
 
 /**
@@ -75,7 +76,7 @@ export const makeElectricUrl = ({
   } else {
     searchParams.set('offset', args.handle.value.offset)
     searchParams.set('handle', args.handle.value.handle)
-    searchParams.set('live', args.live ? 'true' : 'false')
+    searchParams.set('live', args.live === true ? 'true' : 'false')
   }
 
   const payload = args.payload
@@ -103,8 +104,27 @@ export const toTableName = (storeId: string) => {
 }
 
 /**
- * Needs to be bumped when the storage format changes (e.g. eventlogTable schema changes)
+ * CRITICAL: Increment this version whenever you modify the Postgres table schema structure.
+ *
+ * Bump required when:
+ * - Adding/removing/renaming columns in the eventlog table (see examples/web-todomvc-sync-electric/src/server/db.ts)
+ * - Changing column types or constraints
+ * - Modifying primary keys or indexes
+ *
+ * Bump NOT required when:
+ * - Changing query patterns or fetch logic
+ * - Adding new tables (as long as existing table schema remains unchanged)
+ * - Updating client-side implementation details
+ *
+ * Impact: Changing this version triggers a "soft reset" - new table names are created
+ * and old data becomes inaccessible (but remains in the database).
  *
- * Changing this version number will lead to a "soft reset".
+ * Current schema (PostgreSQL):
+ * - seqNum (INTEGER PRIMARY KEY)
+ * - parentSeqNum (INTEGER)
+ * - name (TEXT NOT NULL)
+ * - args (JSONB NOT NULL)
+ * - clientId (TEXT NOT NULL)
+ * - sessionId (TEXT NOT NULL)
  */
 export const PERSISTENCE_FORMAT_VERSION = 6