@livestore/sync-cf 0.4.0-dev.8 → 0.4.0-dev.9

package/dist/cf-worker/worker.d.ts

@@ -1,34 +1,19 @@
+import type { HelperTypes } from '@livestore/common-cf';
 import type { Schema } from '@livestore/utils/effect';
 import type { CfTypes, SearchParams } from '../common/mod.ts';
 import { type Env } from './shared.ts';
-export declare namespace HelperTypes {
-    type AnyDON = CfTypes.DurableObjectNamespace<undefined>;
-    type DOKeys<T> = {
-        [K in keyof T]-?: T[K] extends AnyDON ? K : never;
-    }[keyof T];
-    type NonBuiltins<T> = Omit<T, keyof Env>;
-    /**
-     * Helper type to extract DurableObject keys from Env to give consumer type safety.
-     *
-     * @example
-     * ```ts
-     *  type PlatformEnv = {
-     *    DB: D1Database
-     *    ADMIN_TOKEN: string
-     *    SYNC_BACKEND_DO: DurableObjectNamespace<SyncBackendDO>
-     * }
-     *  export default makeWorker<PlatformEnv>({
-     *    durableObject: { name: "SYNC_BACKEND_DO" },
-     *    // ^ (property) name?: "SYNC_BACKEND_DO" | undefined
-     *  });
-     */
-    export type ExtractDurableObjectKeys<TEnv = Env> = DOKeys<NonBuiltins<TEnv>> extends never ? string : DOKeys<NonBuiltins<TEnv>>;
-    export {};
-}
 export type CFWorker<TEnv extends Env = Env, _T extends CfTypes.Rpc.DurableObjectBranded | undefined = undefined> = {
     fetch: <CFHostMetada = unknown>(request: CfTypes.Request<CFHostMetada>, env: TEnv, ctx: CfTypes.ExecutionContext) => Promise<CfTypes.Response>;
 };
+/**
+ * Options accepted by {@link makeWorker}. The Durable Object binding has to be
+ * supplied explicitly so we never fall back to deprecated defaults when Cloudflare config changes.
+ */
 export type MakeWorkerOptions<TEnv extends Env = Env> = {
+    /**
+     * Binding name of the sync Durable Object declared in wrangler config.
+     */
+    syncBackendBinding: HelperTypes.ExtractDurableObjectKeys<TEnv>;
     /**
      * Validates the payload during WebSocket connection establishment.
      * Note: This runs only at connection time, not for individual push events.
@@ -39,16 +24,15 @@ export type MakeWorkerOptions<TEnv extends Env = Env> = {
     }) => void | Promise<void>;
     /** @default false */
     enableCORS?: boolean;
-    durableObject?: {
-        /**
-         * Needs to match the binding name from the wrangler config
-         *
-         * @default 'SYNC_BACKEND_DO'
-         */
-        name?: HelperTypes.ExtractDurableObjectKeys<TEnv>;
-    };
 };
-export declare const makeWorker: <TEnv extends Env = Env, TDurableObjectRpc extends CfTypes.Rpc.DurableObjectBranded | undefined = undefined>(options?: MakeWorkerOptions<TEnv>) => CFWorker<TEnv, TDurableObjectRpc>;
+/**
+ * Produces a Cloudflare Worker `fetch` handler that delegates sync traffic to the
+ * Durable Object identified by `syncBackendBinding`.
+ *
+ * For more complex setups prefer implementing a custom `fetch` and call {@link handleSyncRequest}
+ * from the branch that handles LiveStore sync requests.
+ */
+export declare const makeWorker: <TEnv extends Env = Env, TDurableObjectRpc extends CfTypes.Rpc.DurableObjectBranded | undefined = undefined>(options: MakeWorkerOptions<TEnv>) => CFWorker<TEnv, TDurableObjectRpc>;
 /**
  * Handles `/sync` endpoint.
  *
@@ -63,16 +47,18 @@ export declare const makeWorker: <TEnv extends Env = Env, TDurableObjectRpc exte
  *
  * export default {
  *   fetch: async (request, env, ctx) => {
- *     const requestParamsResult = getSyncRequestSearchParams(request)
+ *     const searchParams = matchSyncRequest(request)
  *
  *     // Is LiveStore sync request
- *     if (requestParamsResult._tag === 'Some') {
+ *     if (searchParams !== undefined) {
  *       return handleSyncRequest({
  *         request,
- *         searchParams: requestParamsResult.value,
+ *         searchParams,
  *         env,
  *         ctx,
- *         options: { headers: {}, validatePayload }
+ *         syncBackendBinding: 'SYNC_BACKEND_DO',
+ *         headers: {},
+ *         validatePayload,
  *       })
  *     }
  *
@@ -83,18 +69,17 @@ export declare const makeWorker: <TEnv extends Env = Env, TDurableObjectRpc exte
  *
  * @throws {UnexpectedError} If the payload is invalid
  */
-export declare const handleSyncRequest: <TEnv extends Env = Env, TDurableObjectRpc extends CfTypes.Rpc.DurableObjectBranded | undefined = undefined, CFHostMetada = unknown>({ request, searchParams, env, options, }: {
+export declare const handleSyncRequest: <TEnv extends Env = Env, TDurableObjectRpc extends CfTypes.Rpc.DurableObjectBranded | undefined = undefined, CFHostMetada = unknown>({ request, searchParams: { storeId, payload, transport }, env, syncBackendBinding, headers, validatePayload, }: {
     request: CfTypes.Request<CFHostMetada>;
     searchParams: SearchParams;
     env: TEnv;
     /** Only there for type-level reasons */
     ctx: CfTypes.ExecutionContext;
-    options?: {
-        headers?: CfTypes.HeadersInit;
-        durableObject?: MakeWorkerOptions<TEnv>["durableObject"];
-        validatePayload?: (payload: Schema.JsonValue | undefined, context: {
-            storeId: string;
-        }) => void | Promise<void>;
-    };
+    /** Binding name of the sync backend Durable Object */
+    syncBackendBinding: MakeWorkerOptions<TEnv>["syncBackendBinding"];
+    headers?: CfTypes.HeadersInit | undefined;
+    validatePayload?: (payload: Schema.JsonValue | undefined, context: {
+        storeId: string;
+    }) => void | Promise<void>;
 }) => Promise<CfTypes.Response>;
 //# sourceMappingURL=worker.d.ts.map

package/dist/cf-worker/worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/cf-worker/worker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/cf-worker/worker.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAE7D,OAAO,EAAE,KAAK,GAAG,EAAoB,MAAM,aAAa,CAAA;AAMxD,MAAM,MAAM,QAAQ,CAAC,IAAI,SAAS,GAAG,GAAG,GAAG,EAAE,EAAE,SAAS,OAAO,CAAC,GAAG,CAAC,oBAAoB,GAAG,SAAS,GAAG,SAAS,IAAI;IAClH,KAAK,EAAE,CAAC,YAAY,GAAG,OAAO,EAC5B,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,EACtC,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,OAAO,CAAC,gBAAgB,KAC1B,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC/B,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,CAAC,IAAI,SAAS,GAAG,GAAG,GAAG,IAAI;IACtD;;OAEG;IACH,kBAAkB,EAAE,WAAW,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAA;IAC9D;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,SAAS,GAAG,SAAS,EAAE,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/G,qBAAqB;IACrB,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GACrB,IAAI,SAAS,GAAG,GAAG,GAAG,EACtB,iBAAiB,SAAS,OAAO,CAAC,GAAG,CAAC,oBAAoB,GAAG,SAAS,GAAG,SAAS,EAElF,SAAS,iBAAiB,CAAC,IAAI,CAAC,KAC/B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAuDlC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,iBAAiB,GAC5B,IAAI,SAAS,GAAG,GAAG,GAAG,EACtB,iBAAiB,SAAS,OAAO,CAAC,GAAG,CAAC,oBAAoB,GAAG,SAAS,GAAG,SAAS,EAClF,YAAY,GAAG,OAAO,EACtB,gHAOC;IACD,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAA;IACtC,YAAY,EAAE,YAAY,CAAA;IAC1B,GAAG,EAAE,IAAI,CAAA;IACT,wCAAwC;IACxC,GAAG,EAAE,OAAO,CAAC,gBAAgB,CAAA;IAC7B,sDAAsD;IACtD,kBAAkB,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAC,oBAAoB,CAAC,CAAA;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,GAAG,SAAS,CAAA;IACzC,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,SAAS,GAAG,SAAS,EAAE,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAChH,KAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAyC0B,CAAA"}

package/dist/cf-worker/worker.js

@@ -1,7 +1,14 @@
 import { UnexpectedError } from '@livestore/common';
 import { Effect } from '@livestore/utils/effect';
-import { DEFAULT_SYNC_DURABLE_OBJECT_NAME, getSyncRequestSearchParams } from "./shared.js";
-export const makeWorker = (options = {}) => {
+import { matchSyncRequest } from "./shared.js";
+/**
+ * Produces a Cloudflare Worker `fetch` handler that delegates sync traffic to the
+ * Durable Object identified by `syncBackendBinding`.
+ *
+ * For more complex setups prefer implementing a custom `fetch` and call {@link handleSyncRequest}
+ * from the branch that handles LiveStore sync requests.
+ */
+export const makeWorker = (options) => {
     return {
         fetch: async (request, env, _ctx) => {
             const url = new URL(request.url);
@@ -18,19 +25,17 @@ export const makeWorker = (options = {}) => {
                     headers: corsHeaders,
                 });
             }
-            const requestParamsResult = getSyncRequestSearchParams(request);
+            const searchParams = matchSyncRequest(request);
             // Check if this is a sync request first, before showing info message
-            if (requestParamsResult._tag === 'Some') {
+            if (searchParams !== undefined) {
                 return handleSyncRequest({
                     request,
-                    searchParams: requestParamsResult.value,
+                    searchParams,
                     env,
                     ctx: _ctx,
-                    options: {
-                        headers: corsHeaders,
-                        validatePayload: options.validatePayload,
-                        durableObject: options.durableObject,
-                    },
+                    syncBackendBinding: options.syncBackendBinding,
+                    headers: corsHeaders,
+                    validatePayload: options.validatePayload,
                 });
             }
             // Only show info message for GET requests to / without sync parameters
@@ -66,16 +71,18 @@ export const makeWorker = (options = {}) => {
  *
  * export default {
  *   fetch: async (request, env, ctx) => {
- *     const requestParamsResult = getSyncRequestSearchParams(request)
+ *     const searchParams = matchSyncRequest(request)
  *
  *     // Is LiveStore sync request
- *     if (requestParamsResult._tag === 'Some') {
+ *     if (searchParams !== undefined) {
  *       return handleSyncRequest({
  *         request,
- *         searchParams: requestParamsResult.value,
+ *         searchParams,
  *         env,
  *         ctx,
- *         options: { headers: {}, validatePayload }
+ *         syncBackendBinding: 'SYNC_BACKEND_DO',
+ *         headers: {},
+ *         validatePayload,
  *       })
  *     }
  *
@@ -86,23 +93,21 @@ export const makeWorker = (options = {}) => {
  *
  * @throws {UnexpectedError} If the payload is invalid
  */
-export const handleSyncRequest = ({ request, searchParams, env, options = {}, }) => Effect.gen(function* () {
-    const { storeId, payload, transport } = searchParams;
-    if (options.validatePayload !== undefined) {
-        const result = yield* Effect.promise(async () => options.validatePayload(payload, { storeId })).pipe(UnexpectedError.mapToUnexpectedError, Effect.either);
+export const handleSyncRequest = ({ request, searchParams: { storeId, payload, transport }, env, syncBackendBinding, headers, validatePayload, }) => Effect.gen(function* () {
+    if (validatePayload !== undefined) {
+        const result = yield* Effect.promise(async () => validatePayload(payload, { storeId })).pipe(UnexpectedError.mapToUnexpectedError, Effect.either);
         if (result._tag === 'Left') {
             console.error('Invalid payload', result.left);
-            return new Response(result.left.toString(), { status: 400, headers: options.headers });
+            return new Response(result.left.toString(), { status: 400, headers });
         }
     }
-    const durableObjectName = options.durableObject?.name ?? DEFAULT_SYNC_DURABLE_OBJECT_NAME;
-    if (!(durableObjectName in env)) {
-        return new Response(`Failed dependency: Required Durable Object binding '${durableObjectName}' not available`, {
+    if (!(syncBackendBinding in env)) {
+        return new Response(`Failed dependency: Required Durable Object binding '${syncBackendBinding}' not available`, {
             status: 424,
-            headers: options.headers,
+            headers,
         });
     }
-    const durableObjectNamespace = env[durableObjectName];
+    const durableObjectNamespace = env[syncBackendBinding];
     const id = durableObjectNamespace.idFromName(storeId);
     const durableObject = durableObjectNamespace.get(id);
     // Handle WebSocket upgrade request
@@ -110,7 +115,7 @@ export const handleSyncRequest = ({ request, searchParams, env, options = {}, })
     if (transport === 'ws' && (upgradeHeader === null || upgradeHeader !== 'websocket')) {
         return new Response('Durable Object expected Upgrade: websocket', {
             status: 426,
-            headers: options?.headers,
+            headers,
         });
     }
     return yield* Effect.promise(() => durableObject.fetch(request));

package/dist/cf-worker/worker.js.map

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

package/dist/common/sync-message-types.d.ts

@@ -42,12 +42,7 @@ export declare const PullResponse: Schema.Struct<{
     backendId: Schema.SchemaClass<string, string, never>;
 }>;
 export declare const emptyPullResponse: (backendId: string) => {
-    readonly backendId: string;
     readonly batch: readonly {
-        readonly metadata: import("effect/Option").Option<{
-            readonly createdAt: string;
-            readonly _tag: "SyncMessage.SyncMetadata";
-        }>;
         readonly eventEncoded: {
             readonly name: string;
             readonly args: any;
@@ -56,6 +51,10 @@ export declare const emptyPullResponse: (backendId: string) => {
             readonly clientId: string;
             readonly sessionId: string;
         };
+        readonly metadata: import("effect/Option").Option<{
+            readonly _tag: "SyncMessage.SyncMetadata";
+            readonly createdAt: string;
+        }>;
     }[];
     readonly pageInfo: {
         readonly _tag: "MoreUnknown";
@@ -65,6 +64,7 @@ export declare const emptyPullResponse: (backendId: string) => {
     } | {
         readonly _tag: "NoMore";
     };
+    readonly backendId: string;
 };
 export type PullResponse = typeof PullResponse.Type;
 export declare const PushRequest: Schema.Struct<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livestore/sync-cf",
-  "version": "0.4.0-dev.8",
+  "version": "0.4.0-dev.9",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -9,10 +9,10 @@
     "./cf-worker": "./dist/cf-worker/mod.js"
   },
   "dependencies": {
-    "@cloudflare/workers-types": "4.20250823.0",
-    "@livestore/common": "0.4.0-dev.8",
-    "@livestore/utils": "0.4.0-dev.8",
-    "@livestore/common-cf": "0.4.0-dev.8"
+    "@cloudflare/workers-types": "4.20250923.0",
+    "@livestore/common": "0.4.0-dev.9",
+    "@livestore/common-cf": "0.4.0-dev.9",
+    "@livestore/utils": "0.4.0-dev.9"
   },
   "files": [
     "dist",

package/src/cf-worker/do/durable-object.ts

@@ -16,8 +16,8 @@ import {
 } from '@livestore/utils/effect'
 import {
   type Env,
-  getSyncRequestSearchParams,
   type MakeDurableObjectClassOptions,
+  matchSyncRequest,
   type SyncBackendRpcInterface,
   WebSocketAttachmentSchema,
 } from '../shared.ts'
@@ -33,10 +33,10 @@ declare class Response extends CfDeclare.Response {}
 declare class WebSocketPair extends CfDeclare.WebSocketPair {}
 declare class WebSocketRequestResponsePair extends CfDeclare.WebSocketRequestResponsePair {}
 
-const DurableObjectBase = DurableObject as any as new (
+const DurableObjectBase = DurableObject<Env> as any as new (
   state: CfTypes.DurableObjectState,
   env: Env,
-) => CfTypes.DurableObject
+) => CfTypes.DurableObject & { ctx: CfTypes.DurableObjectState; env: Env }
 
 // Type aliases needed to avoid TS bug https://github.com/microsoft/TypeScript/issues/55021
 export type DoState = CfTypes.DurableObjectState
@@ -99,13 +99,9 @@ export const makeDurableObject: MakeDurableObjectClass = (options) => {
 
   return class SyncBackendDOBase extends DurableObjectBase implements SyncBackendRpcInterface {
     __DURABLE_OBJECT_BRAND = 'SyncBackendDOBase' as never
-    ctx: CfTypes.DurableObjectState
-    env: Env
 
     constructor(ctx: CfTypes.DurableObjectState, env: Env) {
       super(ctx, env)
-      this.ctx = ctx
-      this.env = env
 
       const WebSocketRpcServerLive = makeRpcServer({ doSelf: this, doOptions: options })
 
@@ -148,12 +144,12 @@ export const makeDurableObject: MakeDurableObjectClass = (options) => {
 
     fetch = async (request: Request): Promise<Response> =>
       Effect.gen(this, function* () {
-        const requestParamsResult = getSyncRequestSearchParams(request)
-        if (requestParamsResult._tag === 'None') {
+        const searchParams = matchSyncRequest(request)
+        if (searchParams === undefined) {
           throw new Error('No search params found in request URL')
         }
 
-        const { storeId, payload, transport } = requestParamsResult.value
+        const { storeId, payload, transport } = searchParams
 
         if (enabledTransports.has(transport) === false) {
           throw new Error(`Transport ${transport} is not enabled (based on \`options.enabledTransports\`)`)

package/src/cf-worker/do/pull.ts

@@ -1,8 +1,11 @@
 import { BackendIdMismatchError, InvalidPullError, SyncBackend, UnexpectedError } from '@livestore/common'
-import { Chunk, Effect, Option, type Schema, Stream } from '@livestore/utils/effect'
+import { Chunk, Effect, Option, Schema, Stream } from '@livestore/utils/effect'
 import { SyncMessage } from '../../common/mod.ts'
-import { PULL_CHUNK_SIZE } from '../shared.ts'
+import { MAX_PULL_EVENTS_PER_MESSAGE, MAX_WS_MESSAGE_BYTES } from '../shared.ts'
 import { DoCtx } from './layer.ts'
+import { splitChunkBySize } from './ws-chunking.ts'
+
+const encodePullResponse = Schema.encodeSync(SyncMessage.PullResponse)
 
 // Notes on stream handling:
 // We're intentionally closing the stream once we've read all existing events
@@ -35,7 +38,16 @@ export const makeEndingPullStream = (
     )
 
     return storedEvents.pipe(
-      Stream.grouped(PULL_CHUNK_SIZE),
+      Stream.mapChunks(
+        splitChunkBySize({
+          maxItems: MAX_PULL_EVENTS_PER_MESSAGE,
+          maxBytes: MAX_WS_MESSAGE_BYTES,
+          encode: (batch) =>
+            encodePullResponse(
+              SyncMessage.PullResponse.make({ batch, pageInfo: SyncBackend.pageInfoNoMore, backendId }),
+            ),
+        }),
+      ),
       Stream.mapAccum(total, (remaining, chunk) => {
         const asArray = Chunk.toReadonlyArray(chunk)
         const nextRemaining = Math.max(0, remaining - asArray.length)

package/src/cf-worker/do/push.ts

@@ -6,10 +6,21 @@ import {
   UnexpectedError,
 } from '@livestore/common'
 import { type CfTypes, emitStreamResponse } from '@livestore/common-cf'
-import { Effect, Option, type RpcMessage, Schema } from '@livestore/utils/effect'
+import { Chunk, Effect, Option, type RpcMessage, Schema } from '@livestore/utils/effect'
 import { SyncMessage } from '../../common/mod.ts'
-import { type Env, type MakeDurableObjectClassOptions, type StoreId, WebSocketAttachmentSchema } from '../shared.ts'
+import {
+  type Env,
+  MAX_PULL_EVENTS_PER_MESSAGE,
+  MAX_WS_MESSAGE_BYTES,
+  type MakeDurableObjectClassOptions,
+  type StoreId,
+  WebSocketAttachmentSchema,
+} from '../shared.ts'
 import { DoCtx } from './layer.ts'
+import { splitChunkBySize } from './ws-chunking.ts'
+
+const encodePullResponse = Schema.encodeSync(SyncMessage.PullResponse)
+type PullBatchItem = SyncMessage.PullResponse['batch'][number]
 
 export const makePush =
   ({
@@ -51,6 +62,13 @@ export const makePush =
         // Validate the batch
         const firstEventParent = pushRequest.batch[0]!.parentSeqNum
         if (firstEventParent !== currentHead) {
+          // yield* Effect.logDebug('ServerAheadError: backend head mismatch', {
+          //   expectedHead: currentHead,
+          //   providedHead: firstEventParent,
+          //   batchSize: pushRequest.batch.length,
+          //   backendId,
+          // })
+
           return yield* new ServerAheadError({ minimumExpectedNum: currentHead, providedNum: firstEventParent })
         }
 
@@ -68,40 +86,69 @@ export const makePush =
       yield* Effect.gen(function* () {
         const connectedClients = ctx.getWebSockets()
 
-        // Dual broadcasting: WebSocket + RPC clients
-        const pullRes = SyncMessage.PullResponse.make({
-          batch: pushRequest.batch.map((eventEncoded) => ({
-            eventEncoded,
-            metadata: Option.some(SyncMessage.SyncMetadata.make({ createdAt })),
-          })),
-          pageInfo: SyncBackend.pageInfoNoMore,
-          backendId,
-        })
+        // Preparing chunks of responses to make sure we don't exceed the WS message size limit.
+        const responses = Chunk.fromIterable(pushRequest.batch).pipe(
+          splitChunkBySize({
+            maxItems: MAX_PULL_EVENTS_PER_MESSAGE,
+            maxBytes: MAX_WS_MESSAGE_BYTES,
+            encode: (items) =>
+              encodePullResponse(
+                SyncMessage.PullResponse.make({
+                  batch: items.map(
+                    (eventEncoded): PullBatchItem => ({
+                      eventEncoded,
+                      metadata: Option.some(SyncMessage.SyncMetadata.make({ createdAt })),
+                    }),
+                  ),
+                  pageInfo: SyncBackend.pageInfoNoMore,
+                  backendId,
+                }),
+              ),
+          }),
+          Chunk.map((eventsChunk) => {
+            const batchWithMetadata = Chunk.toReadonlyArray(eventsChunk).map((eventEncoded) => ({
+              eventEncoded,
+              metadata: Option.some(SyncMessage.SyncMetadata.make({ createdAt })),
+            }))
+
+            const response = SyncMessage.PullResponse.make({
+              batch: batchWithMetadata,
+              pageInfo: SyncBackend.pageInfoNoMore,
+              backendId,
+            })
+
+            return {
+              response,
+              encoded: Schema.encodeSync(SyncMessage.PullResponse)(response),
+            }
+          }),
+        )
 
-        const pullResEnc = Schema.encodeSync(SyncMessage.PullResponse)(pullRes)
+        // Dual broadcasting: WebSocket + RPC clients
 
         // Broadcast to WebSocket clients
         if (connectedClients.length > 0) {
-          // Only calling once for now.
-          if (options?.onPullRes) {
-            yield* Effect.tryAll(() => options.onPullRes!(pullRes)).pipe(UnexpectedError.mapToUnexpectedError)
-          }
+          for (const { response, encoded } of responses) {
+            // Only calling once for now.
+            if (options?.onPullRes) {
+              yield* Effect.tryAll(() => options.onPullRes!(response)).pipe(UnexpectedError.mapToUnexpectedError)
+            }
 
-          // NOTE we're also sending the pullRes to the pushing ws client as a confirmation
-          for (const conn of connectedClients) {
-            // conn.send(pullResEnc)
-            const attachment = Schema.decodeSync(WebSocketAttachmentSchema)(conn.deserializeAttachment())
-
-            // We're doing something a bit "advanced" here as we're directly emitting Effect RPC-compatible
-            // response messsages on the Effect RPC-managed websocket connection to the WS client.
-            // For this we need to get the RPC `requestId` from the WebSocket attachment.
-            for (const requestId of attachment.pullRequestIds) {
-              const res: RpcMessage.ResponseChunkEncoded = {
-                _tag: 'Chunk',
-                requestId,
-                values: [pullResEnc],
+            // NOTE we're also sending the pullRes chunk to the pushing ws client as confirmation
+            for (const conn of connectedClients) {
+              const attachment = Schema.decodeSync(WebSocketAttachmentSchema)(conn.deserializeAttachment())
+
+              // We're doing something a bit "advanced" here as we're directly emitting Effect RPC-compatible
+              // response messsages on the Effect RPC-managed websocket connection to the WS client.
+              // For this we need to get the RPC `requestId` from the WebSocket attachment.
+              for (const requestId of attachment.pullRequestIds) {
+                const res: RpcMessage.ResponseChunkEncoded = {
+                  _tag: 'Chunk',
+                  requestId,
+                  values: [encoded],
+                }
+                conn.send(JSON.stringify(res))
               }
-              conn.send(JSON.stringify(res))
             }
           }
 
@@ -110,17 +157,16 @@ export const makePush =
 
         // RPC broadcasting would require reconstructing client stubs from clientIds
         if (rpcSubscriptions.size > 0) {
-          yield* Effect.forEach(
-            rpcSubscriptions.values(),
-            (subscription) =>
-              emitStreamResponse({
+          for (const subscription of rpcSubscriptions.values()) {
+            for (const { encoded } of responses) {
+              yield* emitStreamResponse({
                 callerContext: subscription.callerContext,
                 env,
                 requestId: subscription.requestId,
-                values: [pullResEnc],
-              }).pipe(Effect.tapCauseLogPretty, Effect.exit),
-            { concurrency: 'unbounded' },
-          )
+                values: [encoded],
+              }).pipe(Effect.tapCauseLogPretty, Effect.exit)
+            }
+          }
 
           yield* Effect.logDebug(`Broadcasted to ${rpcSubscriptions.size} RPC clients`)
         }

package/src/cf-worker/do/transport/do-rpc-server.ts

@@ -1,5 +1,5 @@
 import { InvalidPullError, InvalidPushError } from '@livestore/common'
-import { toDurableObjectHandler } from '@livestore/common-cf'
+import { type CfTypes, toDurableObjectHandler } from '@livestore/common-cf'
 import {
   Effect,
   Headers,
@@ -22,7 +22,9 @@ export interface DoRpcHandlerOptions {
   input: Omit<DoCtxInput, 'from'>
 }
 
-export const createDoRpcHandler = (options: DoRpcHandlerOptions) =>
+export const createDoRpcHandler = (
+  options: DoRpcHandlerOptions,
+): Effect.Effect<Uint8Array<ArrayBuffer> | CfTypes.ReadableStream> =>
   Effect.gen(this, function* () {
     const { payload, input } = options
     // const { rpcSubscriptions, backendId, doOptions, ctx, env } = yield* DoCtx

package/src/cf-worker/do/ws-chunking.ts

@@ -0,0 +1,76 @@
+import { Chunk } from '@livestore/utils/effect'
+
+const textEncoder = new TextEncoder()
+
+/**
+ * Configuration describing how to break a chunk into smaller payload-safe chunks.
+ */
+export interface ChunkingOptions<A> {
+  /** Maximum number of items that may appear in any emitted chunk. */
+  readonly maxItems: number
+  /** Maximum encoded byte size allowed for any emitted chunk. */
+  readonly maxBytes: number
+  /**
+   * Callback that produces a JSON-serialisable structure whose byte size should
+   * fit within {@link maxBytes}. This lets callers control framing overhead.
+   */
+  readonly encode: (items: ReadonlyArray<A>) => unknown
+}
+
+/**
+ * Derives a function that splits an input chunk into sub-chunks confined by
+ * both item count and encoded byte size limits. Designed for transports with
+ * strict frame caps (e.g. Cloudflare hibernated WebSockets).
+ */
+export const splitChunkBySize =
+  <A>(options: ChunkingOptions<A>) =>
+  (chunk: Chunk.Chunk<A>): Chunk.Chunk<Chunk.Chunk<A>> => {
+    const maxItems = Math.max(1, options.maxItems)
+    const maxBytes = Math.max(1, options.maxBytes)
+    const encode = options.encode
+
+    const measure = (items: ReadonlyArray<A>) => {
+      const encoded = encode(items)
+      return textEncoder.encode(JSON.stringify(encoded)).byteLength
+    }
+
+    const items = Chunk.toReadonlyArray(chunk)
+    if (items.length === 0) {
+      return Chunk.fromIterable<Chunk.Chunk<A>>([])
+    }
+
+    const result: Array<Chunk.Chunk<A>> = []
+    let current: Array<A> = []
+
+    const flushCurrent = () => {
+      if (current.length > 0) {
+        result.push(Chunk.fromIterable(current))
+        current = []
+      }
+    }
+
+    for (const item of items) {
+      current.push(item)
+      const exceedsLimit = current.length > maxItems || measure(current) > maxBytes
+
+      if (exceedsLimit) {
+        // remove the item we just added and emit the previous chunk if it exists
+        const last = current.pop()!
+        flushCurrent()
+
+        if (last !== undefined) {
+          current = [last]
+          const singleItemTooLarge = measure(current) > maxBytes
+          if (singleItemTooLarge || current.length > maxItems) {
+            // Emit the oversized item on its own; downstream can decide how to handle it.
+            result.push(Chunk.of(last))
+            current = []
+          }
+        }
+      }
+    }
+
+    flushCurrent()
+
+    return Chunk.fromIterable(result)
+  }