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

package/dist/make-electric-url.js

@@ -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.js";
 /**
  * This function should be called in a trusted environment (e.g. a proxy server) as it
@@ -8,11 +8,11 @@ import * as ApiSchema from "./api-schema.js";
 export const makeElectricUrl = ({ electricHost, searchParams: providedSearchParams, sourceId, sourceSecret, apiSecret, }) => {
     const endpointUrl = `${electricHost}/v1/shape`;
     const UrlParamsSchema = Schema.Struct({ args: ApiSchema.ArgsSchema });
-    const argsResult = Schema.decodeUnknownEither(UrlParamsSchema)(Object.fromEntries(providedSearchParams.entries()));
-    if (argsResult._tag === 'Left') {
+    const argsResult = Schema.decodeUnknownResult(UrlParamsSchema)(Object.fromEntries(providedSearchParams.entries()));
+    if (Result.isFailure(argsResult) === true) {
         return shouldNeverHappen('Invalid search params provided to makeElectricUrl', providedSearchParams, Object.fromEntries(providedSearchParams.entries()));
     }
-    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
@@ -35,7 +35,7 @@ export const makeElectricUrl = ({ electricHost, searchParams: providedSearchPara
     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;
     const url = `${endpointUrl}?${searchParams.toString()}`;
@@ -52,9 +52,28 @@ export const toTableName = (storeId) => {
     return tableName;
 };
 /**
- * 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.
  *
- * Changing this version number will lead to a "soft reset".
+ * 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).
+ *
+ * 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;
 //# sourceMappingURL=make-electric-url.js.map

package/dist/make-electric-url.js.map

@@ -1 +1 @@
-{"version":3,"file":"make-electric-url.js","sourceRoot":"","sources":["../src/make-electric-url.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"make-electric-url.js","sourceRoot":"","sources":["../src/make-electric-url.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,25 +1,64 @@
 {
   "name": "@livestore/sync-electric",
-  "version": "0.4.0-dev.9",
+  "version": "0.5.0-dev.0",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/livestorejs/livestore-contrib.git"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "src"
+  ],
   "type": "module",
   "sideEffects": false,
   "exports": {
     ".": "./dist/index.js"
   },
-  "dependencies": {
-    "@livestore/common": "0.4.0-dev.9",
-    "@livestore/utils": "0.4.0-dev.9"
-  },
-  "devDependencies": {},
-  "files": [
-    "package.json",
-    "src",
-    "dist"
-  ],
-  "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@livestore/common": "0.5.0-dev.0",
+    "@livestore/utils": "0.5.0-dev.0"
+  },
+  "devDependencies": {
+    "@effect/opentelemetry": "4.0.0-rc.111",
+    "@effect/platform-browser": "4.0.0-rc.111",
+    "@effect/platform-bun": "4.0.0-rc.111",
+    "@effect/platform-node": "4.0.0-rc.111",
+    "@effect/platform-node-shared": "4.0.0-rc.111",
+    "@effect/vitest": "4.0.0-rc.111",
+    "@opentelemetry/api": "1.9.0",
+    "@opentelemetry/resources": "2.2.0",
+    "@standard-schema/spec": "1.1.0",
+    "effect": "4.0.0-rc.111",
+    "vitest": "4.1.9"
+  },
+  "peerDependencies": {
+    "@effect/opentelemetry": "^4.0.0-rc.111",
+    "@effect/platform-browser": "^4.0.0-rc.111",
+    "@effect/platform-bun": "^4.0.0-rc.111",
+    "@effect/platform-node": "^4.0.0-rc.111",
+    "@effect/platform-node-shared": "^4.0.0-rc.111",
+    "@effect/vitest": "^4.0.0-rc.111",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/resources": "^2.2.0",
+    "@standard-schema/spec": "^1.1.0",
+    "effect": "^4.0.0-rc.111"
+  },
+  "$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"
+    ]
+  },
   "scripts": {
     "build": "",
     "test": "echo 'No tests yet'"

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

@@ -3,22 +3,30 @@ import { Schema } from '@livestore/utils/effect'
 
 export const PushPayload = Schema.TaggedStruct('@livestore/sync-electric.Push', {
   storeId: Schema.String,
-  batch: Schema.Array(LiveStoreEvent.AnyEncodedGlobal),
-}).annotations({ title: '@livestore/sync-electric.PushPayload' })
+  batch: Schema.Array(LiveStoreEvent.Global.Encoded),
+}).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

@@ -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 {
@@ -15,6 +9,7 @@ import {
   HttpClientResponse,
   Option,
   ReadonlyArray,
+  Result,
   Schedule,
   Schema,
   Stream,
@@ -23,8 +18,10 @@ 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.Literals(['delete', 'update']),
   message: Schema.String,
 }) {}
 
@@ -75,39 +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.transform(LiveStoreEvent.AnyEncodedGlobal, {
-      decode: (_) => _,
-      encode: (_) => _,
-    }),
-  )
-  .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,
@@ -144,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
   }
 }
 
@@ -161,6 +153,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,16 +214,16 @@ 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)(
+          const argsJson = yield* Schema.encodeEffect(ApiSchema.ArgsSchema)(
             ApiSchema.PullPayload.make({ storeId, handle, payload, live }),
           )
           const url = `${pullEndpoint}?args=${argsJson}`
@@ -198,8 +231,8 @@ export const makeSyncBackend =
           const resp = yield* httpClient.get(url)
 
           if (resp.status === 401) {
-            const body = yield* resp.text.pipe(Effect.catchAll(() => Effect.succeed('-')))
-            return yield* InvalidPullError.make({
+            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}`),
             })
           } else if (resp.status === 400) {
@@ -220,9 +253,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 +274,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 ? Result.succeed(item.headers.operation) : Result.failVoid,
           )
 
           if (invalidOperations.length > 0) {
@@ -256,7 +287,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 +295,7 @@ 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) => (Schema.is(UnknownError)(cause) === true ? cause : new UnknownError({ cause }))),
           Effect.withSpan('electric-provider:runPull', { attributes: { handle, live } }),
         )
 
@@ -279,9 +310,9 @@ export const makeSyncBackend =
 
         yield* SubscriptionRef.set(isConnected, true)
       }).pipe(
-        UnexpectedError.mapToUnexpectedError,
+        UnknownError.mapToUnknownError,
         Effect.timeout(pingTimeout),
-        Effect.catchTag('TimeoutException', () => SubscriptionRef.set(isConnected, false)),
+        Effect.catchTag('TimeoutError', () => SubscriptionRef.set(isConnected, false)),
         Effect.withSpan('electric-provider:ping'),
       )
 
@@ -294,62 +325,60 @@ 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,
         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)) 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) {
+              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 }) => ({
               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 { Hash, Result, Schema } from '@livestore/utils/effect'
+
 import * as ApiSchema from './api-schema.ts'
 
 /**
@@ -39,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,
@@ -53,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
@@ -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