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

package/src/limits.test.ts

@@ -0,0 +1,43 @@
+import type { EventSequenceNumber, LiveStoreEvent } from '@livestore/common/schema'
+import { describe, expect, it } from 'vitest'
+
+import {
+  chunkEventsForS2,
+  computeRecordMeteredBytes,
+  MAX_BATCH_METERED_BYTES,
+  MAX_RECORD_METERED_BYTES,
+  S2LimitExceededError,
+} from './limits.ts'
+
+const encoder = new TextEncoder()
+
+const makeEvent = (payloadLength: number, index = 0): LiveStoreEvent.Global.Encoded => ({
+  name: `event-${index}`,
+  args: { payload: 'x'.repeat(payloadLength) },
+  seqNum: index as EventSequenceNumber.Global.Type,
+  parentSeqNum: index as EventSequenceNumber.Global.Type,
+  clientId: 'client',
+  sessionId: 'session',
+})
+
+describe('S2 limits helpers', () => {
+  it('computes metered bytes for record bodies', () => {
+    const record = { body: JSON.stringify({ hello: 'world' }) }
+    const expected = 8 + encoder.encode(record.body ?? '').byteLength
+    expect(computeRecordMeteredBytes(record)).toBe(expected)
+  })
+
+  it('splits large batches while respecting metered byte limits', () => {
+    const events = [makeEvent(400_000, 1), makeEvent(400_000, 2), makeEvent(400_000, 3)]
+    const chunks = chunkEventsForS2(events)
+
+    expect(chunks).toHaveLength(2)
+    expect(chunks.map((chunk) => chunk.events.length)).toStrictEqual([2, 1])
+    expect(chunks.every((chunk) => chunk.meteredBytes <= MAX_BATCH_METERED_BYTES)).toBe(true)
+  })
+
+  it('throws when a single record exceeds the metered byte cap', () => {
+    const oversize = makeEvent(MAX_RECORD_METERED_BYTES, 1)
+    expect(() => chunkEventsForS2([oversize])).toThrow(S2LimitExceededError)
+  })
+})

package/src/limits.ts

@@ -0,0 +1,133 @@
+import type { LiveStoreEvent } from '@livestore/common/schema'
+import { splitArrayBySize } from '@livestore/common/sync'
+import { Effect, ReadonlyArray as EffectArray, Schema } from '@livestore/utils/effect'
+
+const textEncoder = new TextEncoder()
+
+/**
+ * Maximum metered size of a single record (docs: https://s2.dev/docs/limits#records).
+ */
+export const MAX_RECORD_METERED_BYTES = 1_048_576 // 1 MiB
+
+/**
+ * Maximum combined metered size of a batch append (docs: https://s2.dev/docs/limits#records).
+ */
+export const MAX_BATCH_METERED_BYTES = 1_048_576 // 1 MiB
+
+/**
+ * Maximum number of records per append (docs: https://s2.dev/docs/limits#records).
+ */
+export const MAX_RECORDS_PER_BATCH = 1_000
+
+const LimitType = Schema.Literals(['record-metered-bytes', 'batch-metered-bytes', 'batch-count'])
+
+export class S2LimitExceededError extends Schema.TaggedError<S2LimitExceededError>(
+  '~@livestore/sync-s2/S2LimitExceededError',
+)('S2LimitExceededError', {
+  limitType: LimitType,
+  max: Schema.Number,
+  actual: Schema.Number,
+  recordIndex: Schema.optional(Schema.Number),
+}) {}
+
+export interface AppendRecordBody {
+  readonly body?: string
+  readonly headers?: ReadonlyArray<{ readonly name: string; readonly value: string }>
+}
+
+// S2 measures bodies/headers in UTF‑8 bytes; centralising this helper keeps the
+// formula readable and consistent with the docs.
+const utf8ByteLength = (value: string): number => textEncoder.encode(value).byteLength
+
+export const computeRecordMeteredBytes = (record: AppendRecordBody): number => {
+  const headers = record.headers ?? []
+  const headerCount = headers.length
+  const headerBytes = headers.reduce(
+    (acc, header) => acc + utf8ByteLength(header.name) + utf8ByteLength(header.value),
+    0,
+  )
+  const bodyBytes = record.body === undefined ? 0 : utf8ByteLength(record.body)
+  return 8 + 2 * headerCount + headerBytes + bodyBytes
+}
+
+export const computeBatchMeteredBytes = (records: ReadonlyArray<AppendRecordBody>): number =>
+  records.reduce((acc, record) => acc + computeRecordMeteredBytes(record), 0)
+
+interface PreparedEvent {
+  readonly event: LiveStoreEvent.Global.Encoded
+  readonly record: AppendRecordBody
+  readonly meteredBytes: number
+  readonly index: number
+}
+
+export interface S2Chunk {
+  readonly events: ReadonlyArray<LiveStoreEvent.Global.Encoded>
+  readonly records: ReadonlyArray<AppendRecordBody>
+  readonly meteredBytes: number
+}
+
+// Pre-stringify events and pre-compute per-record metered bytes so we only pay
+// the JSON cost once when chunking large batches.
+const convertEventsToPrepared = (events: ReadonlyArray<LiveStoreEvent.Global.Encoded>): PreparedEvent[] =>
+  events.map((event, index) => {
+    const body = JSON.stringify(event)
+    const record: AppendRecordBody = { body }
+    const meteredBytes = computeRecordMeteredBytes(record)
+
+    if (meteredBytes > MAX_RECORD_METERED_BYTES) {
+      throw new S2LimitExceededError({
+        limitType: 'record-metered-bytes',
+        max: MAX_RECORD_METERED_BYTES,
+        actual: meteredBytes,
+        recordIndex: index,
+      })
+    }
+
+    return { event, record, meteredBytes, index }
+  })
+
+// Summarises a chunk’s metered bytes. Passed to splitChunkBySize so we enforce
+// S2 limits directly instead of relying on JSON size heuristics.
+const makeChunkMeasure = (items: ReadonlyArray<PreparedEvent>): number =>
+  items.reduce((acc, item) => acc + item.meteredBytes, 0)
+
+const mapPreparedChunks = (chunks: ReadonlyArray<ReadonlyArray<PreparedEvent>>): ReadonlyArray<S2Chunk> =>
+  chunks.map((chunkItems) => {
+    const events = chunkItems.map((item) => item.event)
+    const records = chunkItems.map((item) => item.record)
+    return {
+      events,
+      records,
+      meteredBytes: makeChunkMeasure(chunkItems),
+    }
+  })
+
+export const chunkEventsForS2 = (events: ReadonlyArray<LiveStoreEvent.Global.Encoded>): ReadonlyArray<S2Chunk> => {
+  const prepared = convertEventsToPrepared(events)
+
+  if (EffectArray.isReadonlyArrayNonEmpty(prepared) === false) {
+    return []
+  }
+
+  try {
+    const chunks = splitArrayBySize<PreparedEvent>({
+      maxItems: MAX_RECORDS_PER_BATCH,
+      maxBytes: MAX_BATCH_METERED_BYTES,
+      encode: (items) => ({ records: items.map((item) => item.record) }),
+      measure: makeChunkMeasure,
+    })(prepared).pipe(Effect.runSync)
+
+    return mapPreparedChunks(chunks)
+  } catch (error) {
+    if (error !== undefined && typeof error === 'object' && (error as any)._tag === 'OversizeChunkItemError') {
+      const oversize = error as { size: number; maxBytes: number; _tag: string }
+      throw new S2LimitExceededError({
+        limitType: 'record-metered-bytes',
+        max: oversize.maxBytes,
+        actual: oversize.size,
+      })
+    }
+
+    throw error
+  }
+}

package/src/make-s2-url.ts

@@ -1,5 +1,6 @@
 import { shouldNeverHappen } from '@livestore/utils'
-import { Schema } from '@livestore/utils/effect'
+import { Result, Schema } from '@livestore/utils/effect'
+
 import * as ApiSchema from './api-schema.ts'
 
 export const makeS2StreamName = (storeId: string) => storeId.replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 100)
@@ -9,9 +10,9 @@ export const makeS2StreamName = (storeId: string) => storeId.replace(/[^a-zA-Z0-
  */
 export const decodePullArgsFromSearchParams = (searchParams: URLSearchParams): typeof ApiSchema.PullArgs.Type => {
   const UrlParamsSchema = Schema.Struct({ args: ApiSchema.ArgsSchema })
-  const argsResult = Schema.decodeUnknownEither(UrlParamsSchema)(Object.fromEntries(searchParams.entries()))
+  const argsResult = Schema.decodeUnknownResult(UrlParamsSchema)(Object.fromEntries(searchParams.entries()))
 
-  if (argsResult._tag === 'Left') {
+  if (Result.isFailure(argsResult) === true) {
     return shouldNeverHappen(
       'Invalid search params provided to decodePullArgsFromSearchParams',
       searchParams,
@@ -19,5 +20,5 @@ export const decodePullArgsFromSearchParams = (searchParams: URLSearchParams): t
     )
   }
 
-  return argsResult.right.args
+  return argsResult.success.args
 }

package/src/mod.ts

@@ -1,5 +1,6 @@
 export * as ApiSchema from './api-schema.ts'
 export * as HttpClientGenerated from './http-client-generated.ts'
+export * from './limits.ts'
 export * from './make-s2-url.ts'
 export * from './s2-proxy-helpers.ts'
 export { makeSyncBackend, type SyncS2Options } from './sync-provider.ts'

package/src/s2-proxy-helpers.ts

@@ -4,7 +4,9 @@
  */
 
 import type { LiveStoreEvent } from '@livestore/livestore'
+
 import type { PullArgs } from './api-schema.ts'
+import { chunkEventsForS2 } from './limits.ts'
 import { makeS2StreamName } from './make-s2-url.ts'
 
 /** Configuration for S2 connections */
@@ -15,8 +17,20 @@ export interface S2Config {
   accountBase?: string
   /** @default 'https://{basin}.b.aws.s2.dev/v1' */
   basinBase?: string
+  /**
+   * When true, adds `S2-Basin` header to requests. This is required for s2-lite
+   * (the open-source self-hosted S2) which uses header-based basin routing instead
+   * of subdomain-based routing used by hosted S2.
+   * @see https://github.com/s2-streamstore/s2-lite
+   */
+  lite?: boolean
 }
 
+export const isLiteMode = (config: S2Config): boolean => config.lite === true
+
+const getBasinHeader = (config: S2Config): Record<string, string> =>
+  isLiteMode(config) === true ? { 's2-basin': config.basin } : {}
+
 // URL construction helpers
 export const getBasinUrl = (config: S2Config, path: string): string => {
   const base = config.basinBase ?? `https://${config.basin}.b.aws.s2.dev/v1`
@@ -31,10 +45,10 @@ export const getAccountUrl = (config: S2Config, path: string): string => {
 export const getStreamRecordsUrl = (
   config: S2Config,
   stream: string,
-  params?: { seq_num?: number; count?: number; clamp?: boolean },
+  params?: { seq_num?: number; count?: number; clamp?: boolean; wait?: number },
 ): string => {
   const base = getBasinUrl(config, `/streams/${encodeURIComponent(stream)}/records`)
-  if (!params) return base
+  if (params == null) return base
 
   const searchParams = new URLSearchParams()
   /** seq_num - The sequence number to start from. See: https://docs.s2.dev/api#seq_num */
@@ -43,8 +57,11 @@ export const getStreamRecordsUrl = (
   if (params.count !== undefined) searchParams.append('count', params.count.toString())
   /** clamp - Whether to clamp the response to the requested count. See: https://docs.s2.dev/api#clamp */
   if (params.clamp !== undefined) searchParams.append('clamp', params.clamp.toString())
+  /** wait - How long to wait for new records before returning. See: https://docs.s2.dev/api#wait */
+  if (params.wait !== undefined) searchParams.append('wait', params.wait.toString())
 
-  return searchParams.toString() ? `${base}?${searchParams}` : base
+  const searchParamsString = searchParams.toString()
+  return searchParamsString.length > 0 ? `${base}?${searchParams}` : base
 }
 
 // Header helpers
@@ -52,14 +69,16 @@ export const getAuthHeaders = (token: string): Record<string, string> => ({
   Authorization: `Bearer ${token}`,
 })
 
-export const getSSEHeaders = (token: string): Record<string, string> => ({
-  ...getAuthHeaders(token),
+export const getSSEHeaders = (config: S2Config): Record<string, string> => ({
+  ...getAuthHeaders(config.token),
+  ...getBasinHeader(config),
   accept: 'text/event-stream',
   's2-format': 'raw',
 })
 
-export const getPushHeaders = (token: string): Record<string, string> => ({
-  ...getAuthHeaders(token),
+export const getPushHeaders = (config: S2Config): Record<string, string> => ({
+  ...getAuthHeaders(config.token),
+  ...getBasinHeader(config),
   'content-type': 'application/json',
   's2-format': 'raw',
 })
@@ -86,6 +105,7 @@ export const ensureStream = async (config: S2Config, stream: string): Promise<vo
       method: 'POST',
       headers: {
         ...getAuthHeaders(config.token),
+        ...getBasinHeader(config),
         'content-type': 'application/json',
       },
       body: JSON.stringify({ stream }),
@@ -111,42 +131,50 @@ export const buildPullRequest = ({
   // cursor points to last processed record, seq_num needs to be the next record
   const seq_num = args.s2SeqNum === 'from-start' ? 0 : args.s2SeqNum + 1
 
-  if (args.live) {
+  if (args.live === true) {
     const url = getStreamRecordsUrl(config, streamName, { seq_num, clamp: true })
-    return { url, headers: getSSEHeaders(config.token) }
+    return { url, headers: getSSEHeaders(config) }
   } else {
-    // Non-live pulls also stream over SSE: we request a very large `count` and
-    // rely on S2 closing the stream once the page tail is reached. This keeps
-    // both live and paged reads on the same transport while still giving us a
-    // natural end-of-stream signal.
-    const url = getStreamRecordsUrl(config, streamName, { seq_num, count: Number.MAX_SAFE_INTEGER, clamp: true })
-    return { url, headers: getSSEHeaders(config.token) }
+    // Non-live pulls also stream over SSE. We ask S2 to return immediately when
+    // the tail is reached by setting wait=0 which gives us an explicit
+    // end-of-stream without requesting an arbitrarily large page size.
+    const url = getStreamRecordsUrl(config, streamName, { seq_num, wait: 0, clamp: true })
+    return { url, headers: getSSEHeaders(config) }
   }
 }
 
-export const buildPushRequest = ({
+export interface S2PushRequest {
+  readonly url: string
+  readonly method: 'POST'
+  readonly headers: Record<string, string>
+  readonly body: string
+}
+
+/**
+ * Builds one or more append requests against S2. The helper applies the
+ * documented 1 MiB / 1000-record limits via `chunkEventsForS2`, so callers
+ * receive a request per compliant chunk instead of hitting 413 responses at
+ * runtime.
+ */
+export const buildPushRequests = ({
   config,
   storeId,
   batch,
 }: {
   config: S2Config
   storeId: string
-  batch: readonly LiveStoreEvent.AnyEncodedGlobal[]
-}): {
-  url: string
-  method: 'POST'
-  headers: Record<string, string>
-  /** JSON-encoded batch */
-  body: string
-} => {
+  batch: readonly LiveStoreEvent.Global.Encoded[]
+}): ReadonlyArray<S2PushRequest> => {
   const streamName = makeS2StreamName(storeId)
   const url = getBasinUrl(config, `/streams/${encodeURIComponent(streamName)}/records`)
-  return {
+  const chunks = chunkEventsForS2(batch)
+
+  return chunks.map((chunk) => ({
     url,
-    method: 'POST',
-    headers: getPushHeaders(config.token),
-    body: JSON.stringify(formatBatchForS2(batch)),
-  }
+    method: 'POST' as const,
+    headers: getPushHeaders(config),
+    body: JSON.stringify({ records: chunk.records }),
+  }))
 }
 
 // Response helpers
@@ -176,21 +204,3 @@ export const errorResponse = (message: string, status = 500): Response => {
     headers: { 'content-type': 'application/json' },
   })
 }
-
-// Batch formatting helper
-export const formatBatchForS2 = (
-  batch: readonly LiveStoreEvent.AnyEncodedGlobal[],
-): { records: { body: string }[] } => {
-  return {
-    records: batch.map((ev) => ({ body: JSON.stringify(ev) })),
-  }
-}
-
-export const asCurl = (request: { url: string; method: string; headers: Record<string, string>; body?: string }) => {
-  const url = request.url
-  const method = request.method
-  const headers = Object.entries(request.headers).map(([key, value]) => `-H "${key}: ${value}"`)
-  const body = request.body
-  const headersStr = headers.join(' ')
-  return `curl -X ${method} ${url} ${headersStr} ${body ? `-d '${body}'` : ''}`
-}

package/src/sync-provider.ts

@@ -28,28 +28,31 @@
  *   DO NOT couple these systems together or assume 1:1 correspondence.
  *
  * Errors
- * - push → InvalidPushError on non‑2xx; pull → InvalidPullError on non‑2xx; ping/connect map timeouts to offline.
+ * - push → UnknownError on non‑2xx; pull → UnknownError on non‑2xx; ping/connect map timeouts to offline.
  * - The proxy should surface helpful status codes and error bodies.
  */
-import { InvalidPullError, InvalidPushError, SyncBackend, UnexpectedError } from '@livestore/common'
+import { SyncBackend, UnknownError } from '@livestore/common'
 import type { EventSequenceNumber } from '@livestore/common/schema'
 import { shouldNeverHappen } from '@livestore/utils'
 import {
   type Duration,
   Effect,
+  Filter,
   HttpClient,
   HttpClientRequest,
   HttpClientResponse,
   Option,
   Schedule,
   Schema,
-  Sse,
   Stream,
   SubscriptionRef,
 } from '@livestore/utils/effect'
+import { Sse } from 'effect/unstable/encoding'
+
 import * as ApiSchema from './api-schema.ts'
 import { decodeReadBatch } from './decode.ts'
 import * as HttpClientGenerated from './http-client-generated.ts'
+import { chunkEventsForS2, S2LimitExceededError } from './limits.ts'
 import type { SyncMetadata } from './types.ts'
 
 export interface SyncS2Options {
@@ -64,19 +67,31 @@ export interface SyncS2Options {
     /** Enable periodic ping; default true */
     enabled?: boolean
     /** Timeout for individual ping request; default 10s */
-    requestTimeout?: Duration.DurationInput
+    requestTimeout?: Duration.Input
     /** Interval between ping requests; default 10s */
-    requestInterval?: Duration.DurationInput
+    requestInterval?: Duration.Input
   }
   retry?: {
     /** Custom retry schedule for non-live pulls (default: 2 recurs, 100ms spaced) */
-    pull?: Schedule.Schedule<number, InvalidPullError>
+    pull?: Schedule.Schedule<number, UnknownError>
     /** Custom retry schedule for pushes (default: 2 recurs, 100ms spaced) */
-    push?: Schedule.Schedule<number, InvalidPushError>
+    push?: Schedule.Schedule<number, UnknownError>
   }
 }
 
-export const defaultRetry = Schedule.compose(Schedule.recurs(2), Schedule.spaced(100))
+export const defaultRetry = Schedule.recurs(2).pipe(Schedule.addDelay(() => Effect.succeed(100)))
+
+const getBrowserOrigin = () => {
+  if (typeof globalThis !== 'object' || globalThis === null || !('location' in globalThis)) {
+    return undefined
+  }
+
+  const { location } = globalThis as typeof globalThis & {
+    location?: { origin?: unknown } | undefined
+  }
+
+  return typeof location?.origin === 'string' ? location.origin : undefined
+}
 
 export const makeSyncBackend =
   ({ endpoint, ping: pingOptions, retry }: SyncS2Options): SyncBackend.SyncBackendConstructor<SyncMetadata> =>
@@ -89,9 +104,9 @@ export const makeSyncBackend =
 
       const httpClient = yield* HttpClient.HttpClient
 
+      const browserOrigin = getBrowserOrigin()
       const pullEndpointHasSameOrigin =
-        pullEndpoint.startsWith('/') ||
-        (globalThis.location !== undefined && globalThis.location.origin === new URL(pullEndpoint).origin)
+        pullEndpoint.startsWith('/') || (browserOrigin !== undefined && browserOrigin === new URL(pullEndpoint).origin)
 
       const pingTimeout = pingOptions?.requestTimeout ?? 10_000
 
@@ -99,9 +114,9 @@ export const makeSyncBackend =
         yield* httpClient.pipe(HttpClient.filterStatusOk).head(pingEndpoint)
         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)),
       )
 
       const pingInterval = pingOptions?.requestInterval ?? 10_000
@@ -110,17 +125,16 @@ export const makeSyncBackend =
       }
 
       // No need to connect if the pull endpoint has the same origin as the current page
-      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)
 
       const runPullSse = (
         cursor: Option.Option<{
-          eventSequenceNumber: EventSequenceNumber.GlobalEventSequenceNumber
+          eventSequenceNumber: EventSequenceNumber.Global.Type
           metadata: Option.Option<SyncMetadata>
         }>,
         live: boolean,
-      ): Stream.Stream<SyncBackend.PullResItem<SyncMetadata>, InvalidPullError> => {
+      ): Stream.Stream<SyncBackend.PullResItem<SyncMetadata>, UnknownError> => {
         // Extract S2 seqNum from metadata for SSE cursor
         const s2SeqNum = cursor.pipe(
           Option.flatMap((_) => _.metadata),
@@ -136,18 +150,20 @@ export const makeSyncBackend =
           .pipe(
             HttpClientResponse.stream,
             // decode text and split into lines
-            Stream.decodeText('utf8'),
-            Stream.pipeThroughChannel(Sse.makeChannel()),
+            Stream.decodeText({ encoding: 'utf8' }),
+            Stream.pipeThroughChannel(Sse.decode()),
             // Filter out pings, map errors to stream failures
             Stream.mapEffect(
               Effect.fnUntraced(function* (msg) {
                 const evt = msg.event.toLowerCase()
                 if (evt === 'ping') return Option.none()
                 if (evt === 'error') {
-                  return yield* new InvalidPullError({ cause: new Error(`SSE error: ${msg.data}`) })
+                  return yield* new UnknownError({ cause: new Error(`SSE error: ${msg.data}`) })
                 }
                 if (evt === 'batch') {
-                  const readBatch = yield* Schema.decode(Schema.parseJson(HttpClientGenerated.ReadBatch))(msg.data)
+                  const readBatch = yield* Schema.decodeEffect(Schema.fromJsonString(HttpClientGenerated.ReadBatch))(
+                    msg.data,
+                  )
                   const batch = decodeReadBatch(readBatch)
 
                   const lastS2SeqNum = batch.at(-1)?.metadata.pipe(
@@ -175,29 +191,29 @@ export const makeSyncBackend =
                 return shouldNeverHappen(`Unexpected SSE event: ${evt}`, msg)
               }),
             ),
-            Stream.filterMap((_) => _), // filter out Option.none()
-            Stream.mapError((cause) => (cause._tag === 'InvalidPullError' ? cause : new InvalidPullError({ cause }))),
+            Stream.filterMap(Filter.fromPredicateOption((_) => _)), // filter out Option.none()
+            Stream.mapError((cause) => (cause._tag === 'UnknownError' ? cause : new UnknownError({ cause }))),
             Stream.retry(retry?.pull ?? defaultRetry),
           )
       }
 
       const ssePull = (
         startCursor: Option.Option<{
-          eventSequenceNumber: EventSequenceNumber.GlobalEventSequenceNumber
+          eventSequenceNumber: EventSequenceNumber.Global.Type
           metadata: Option.Option<SyncMetadata>
         }>,
-      ): Stream.Stream<SyncBackend.PullResItem<SyncMetadata>, InvalidPullError> => {
+      ): Stream.Stream<SyncBackend.PullResItem<SyncMetadata>, UnknownError> => {
         const computeNextCursor = (
           lastItem: Option.Option<SyncBackend.PullResItem<SyncMetadata>>,
           current: Option.Option<{
-            eventSequenceNumber: EventSequenceNumber.GlobalEventSequenceNumber
+            eventSequenceNumber: EventSequenceNumber.Global.Type
             metadata: Option.Option<SyncMetadata>
           }>,
         ) =>
           lastItem.pipe(
             Option.flatMap((item) => {
               const lastBatchItem = item.batch.at(-1)
-              if (!lastBatchItem) return Option.none()
+              if (lastBatchItem == null) return Option.none()
               return Option.some({
                 eventSequenceNumber: lastBatchItem.eventEncoded.seqNum,
                 metadata: lastBatchItem.metadata,
@@ -208,11 +224,11 @@ export const makeSyncBackend =
 
         const loop = (
           cursor: Option.Option<{
-            eventSequenceNumber: EventSequenceNumber.GlobalEventSequenceNumber
+            eventSequenceNumber: EventSequenceNumber.Global.Type
             metadata: Option.Option<SyncMetadata>
           }>,
           isFirst: boolean,
-        ): Stream.Stream<SyncBackend.PullResItem<SyncMetadata>, InvalidPullError> => {
+        ): Stream.Stream<SyncBackend.PullResItem<SyncMetadata>, UnknownError> => {
           const sseStream = (live: boolean) =>
             runPullSse(cursor, live).pipe(
               Stream.emitIfEmpty({
@@ -221,7 +237,7 @@ export const makeSyncBackend =
               } as SyncBackend.PullResItem<SyncMetadata>),
             )
 
-          const stream = isFirst ? sseStream(false) : sseStream(true)
+          const stream = isFirst === true ? sseStream(false) : sseStream(true)
 
           return stream.pipe(
             // Reconnect from last item if stream
@@ -235,7 +251,7 @@ export const makeSyncBackend =
       return SyncBackend.of({
         connect,
         pull: (cursor, options) => {
-          if (options?.live) {
+          if (options?.live === true) {
             return ssePull(cursor)
           } else {
             return runPullSse(cursor, false).pipe(
@@ -247,15 +263,47 @@ export const makeSyncBackend =
           }
         },
         push: (batch) =>
-          HttpClientRequest.schemaBodyJson(ApiSchema.PushPayload)(HttpClientRequest.post(pushEndpoint), {
-            storeId,
-            batch,
-          }).pipe(
-            Effect.andThen(httpClient.pipe(HttpClient.filterStatusOk).execute),
-            Effect.andThen(HttpClientResponse.schemaBodyJson(ApiSchema.PushResponse)),
-            Effect.mapError((cause) => InvalidPushError.make({ cause: UnexpectedError.make({ cause }) })),
-            Effect.retry(retry?.push ?? defaultRetry),
-          ),
+          Effect.gen(function* () {
+            const toUnknownError = (cause: unknown): UnknownError => {
+              if (cause instanceof UnknownError) {
+                return cause
+              }
+
+              if (cause instanceof S2LimitExceededError) {
+                const note =
+                  cause.limitType === 'record-metered-bytes'
+                    ? `S2 record exceeded ${cause.max} metered bytes (actual: ${cause.actual})`
+                    : `S2 batch exceeded ${cause.max} (type: ${cause.limitType}, actual: ${cause.actual})`
+
+                return new UnknownError({
+                  cause,
+                  note,
+                  payload: {
+                    limitType: cause.limitType,
+                    max: cause.max,
+                    actual: cause.actual,
+                    recordIndex: cause.recordIndex,
+                  },
+                })
+              }
+
+              return new UnknownError({ cause })
+            }
+
+            const chunks = yield* Effect.sync(() => chunkEventsForS2(batch)).pipe(Effect.mapError(toUnknownError))
+
+            for (const chunk of chunks) {
+              yield* HttpClientRequest.schemaBodyJson(ApiSchema.PushPayload)(HttpClientRequest.post(pushEndpoint), {
+                storeId,
+                batch: chunk.events,
+              }).pipe(
+                Effect.andThen(httpClient.pipe(HttpClient.filterStatusOk).execute),
+                Effect.andThen(HttpClientResponse.schemaBodyJson(ApiSchema.PushResponse)),
+                Effect.mapError(toUnknownError),
+                Effect.retry(retry?.push ?? defaultRetry),
+              )
+            }
+          }),
         ping,
         isConnected,
         metadata: {

package/src/types.ts

@@ -12,7 +12,7 @@ import { Brand, Schema } from '@livestore/utils/effect'
  */
 export type S2SeqNum = Brand.Branded<number, 'S2SeqNum'>
 export const s2SeqNum = Brand.nominal<S2SeqNum>()
-export const S2SeqNum = Schema.fromBrand(s2SeqNum)(Schema.Int.pipe(Schema.greaterThanOrEqualTo(0)))
+export const S2SeqNum = Schema.fromBrand('S2SeqNum', s2SeqNum)(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)))
 
 /**
  * Metadata for tracking S2-specific cursor information.