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

package/src/cf-worker/worker.ts

@@ -1,42 +1,14 @@
 import { UnexpectedError } from '@livestore/common'
+import type { HelperTypes } from '@livestore/common-cf'
 import type { Schema } from '@livestore/utils/effect'
 import { Effect } from '@livestore/utils/effect'
 import type { CfTypes, SearchParams } from '../common/mod.ts'
 import type { CfDeclare } from './mod.ts'
-import { DEFAULT_SYNC_DURABLE_OBJECT_NAME, type Env, getSyncRequestSearchParams } from './shared.ts'
+import { type Env, matchSyncRequest } from './shared.ts'
 
 // NOTE We need to redeclare runtime types here to avoid type conflicts with the lib.dom Response type.
 declare class Response extends CfDeclare.Response {}
 
-export 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>>
-}
-
 // HINT: If we ever extend user's custom worker RPC, type T can help here with expected return type safety. Currently unused.
 export type CFWorker<TEnv extends Env = Env, _T extends CfTypes.Rpc.DurableObjectBranded | undefined = undefined> = {
   fetch: <CFHostMetada = unknown>(
@@ -46,7 +18,15 @@ export type CFWorker<TEnv extends Env = Env, _T extends CfTypes.Rpc.DurableObjec
   ) => 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.
@@ -55,21 +35,20 @@ export type MakeWorkerOptions<TEnv extends Env = Env> = {
   validatePayload?: (payload: Schema.JsonValue | undefined, context: { storeId: string }) => 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>
-  }
 }
 
+/**
+ * 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 = <
   TEnv extends Env = Env,
   TDurableObjectRpc extends CfTypes.Rpc.DurableObjectBranded | undefined = undefined,
 >(
-  options: MakeWorkerOptions<TEnv> = {},
+  options: MakeWorkerOptions<TEnv>,
 ): CFWorker<TEnv, TDurableObjectRpc> => {
   return {
     fetch: async (request, env, _ctx) => {
@@ -90,20 +69,18 @@ export const makeWorker = <
         })
       }
 
-      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<TEnv, TDurableObjectRpc>({
           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,
         })
       }
 
@@ -143,16 +120,18 @@ export const makeWorker = <
  *
  * 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,
  *       })
  *     }
  *
@@ -169,49 +148,47 @@ export const handleSyncRequest = <
   CFHostMetada = unknown,
 >({
   request,
-  searchParams,
+  searchParams: { storeId, payload, transport },
   env,
-  options = {},
+  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> =>
   Effect.gen(function* () {
-    const { storeId, payload, transport } = searchParams
-
-    if (options.validatePayload !== undefined) {
-      const result = yield* Effect.promise(async () => options.validatePayload!(payload, { storeId })).pipe(
+    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)) {
+    if (!(syncBackendBinding in env)) {
       return new Response(
-        `Failed dependency: Required Durable Object binding '${durableObjectName as string}' not available`,
+        `Failed dependency: Required Durable Object binding '${syncBackendBinding as string}' not available`,
         {
           status: 424,
-          headers: options.headers,
+          headers,
         },
       )
     }
 
     const durableObjectNamespace = env[
-      durableObjectName as keyof TEnv
+      syncBackendBinding as keyof TEnv
     ] as CfTypes.DurableObjectNamespace<TDurableObjectRpc>
 
     const id = durableObjectNamespace.idFromName(storeId)
@@ -222,7 +199,7 @@ export const handleSyncRequest = <
     if (transport === 'ws' && (upgradeHeader === null || upgradeHeader !== 'websocket')) {
       return new Response('Durable Object expected Upgrade: websocket', {
         status: 426,
-        headers: options?.headers,
+        headers,
       })
     }
 

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

@@ -1,2 +0,0 @@
-export { type D1Database, type D1Result, type DurableObject, type DurableObjectState, Request, Response, Rpc, WebSocket, WebSocketPair, WebSocketRequestResponsePair, } from '@cloudflare/workers-types';
-//# sourceMappingURL=cf-types.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"cf-types.d.ts","sourceRoot":"","sources":["../../src/cf-worker/cf-types.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,OAAO,EACP,QAAQ,EACR,GAAG,EACH,SAAS,EACT,aAAa,EACb,4BAA4B,GAC7B,MAAM,2BAA2B,CAAA"}

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

@@ -1,2 +0,0 @@
-export { Request, Response, Rpc, WebSocket, WebSocketPair, WebSocketRequestResponsePair, } from '@cloudflare/workers-types';
-//# sourceMappingURL=cf-types.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"cf-types.js","sourceRoot":"","sources":["../../src/cf-worker/cf-types.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,OAAO,EACP,QAAQ,EACR,GAAG,EACH,SAAS,EACT,aAAa,EACb,4BAA4B,GAC7B,MAAM,2BAA2B,CAAA"}

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

@@ -1,189 +0,0 @@
-import { State } from '@livestore/common/schema';
-import { Effect, Option, Schema } from '@livestore/utils/effect';
-import { WSMessage } from '../common/mod.ts';
-import type * as CfWorker from './cf-types.ts';
-export interface Env {
-    DB: CfWorker.D1Database;
-    ADMIN_SECRET: string;
-}
-export declare const eventlogTable: State.SQLite.TableDef<State.SQLite.SqliteTableDefForInput<"eventlog_$PERSISTENCE_FORMAT_VERSION_$storeId", {
-    readonly seqNum: {
-        columnType: "integer";
-        schema: Schema.Schema<number & import("effect/Brand").Brand<"GlobalEventSequenceNumber">, number, never>;
-        default: Option.None<never>;
-        nullable: false;
-        primaryKey: true;
-        autoIncrement: false;
-    };
-    readonly parentSeqNum: {
-        columnType: "integer";
-        schema: Schema.Schema<number & import("effect/Brand").Brand<"GlobalEventSequenceNumber">, number, never>;
-        default: Option.None<never>;
-        nullable: false;
-        primaryKey: false;
-        autoIncrement: false;
-    };
-    readonly name: {
-        columnType: "text";
-        schema: Schema.Schema<string, string, never>;
-        default: Option.None<never>;
-        nullable: false;
-        primaryKey: false;
-        autoIncrement: false;
-    };
-    readonly args: {
-        columnType: "text";
-        schema: Schema.Schema<any, string | null, never>;
-        default: Option.None<never>;
-        nullable: true;
-        primaryKey: false;
-        autoIncrement: false;
-    };
-    /** ISO date format. Currently only used for debugging purposes. */
-    readonly createdAt: {
-        columnType: "text";
-        schema: Schema.Schema<string, string, never>;
-        default: Option.None<never>;
-        nullable: false;
-        primaryKey: false;
-        autoIncrement: false;
-    };
-    readonly clientId: {
-        columnType: "text";
-        schema: Schema.Schema<string, string, never>;
-        default: Option.None<never>;
-        nullable: false;
-        primaryKey: false;
-        autoIncrement: false;
-    };
-    readonly sessionId: {
-        columnType: "text";
-        schema: Schema.Schema<string, string, never>;
-        default: Option.None<never>;
-        nullable: false;
-        primaryKey: false;
-        autoIncrement: false;
-    };
-}>, State.SQLite.WithDefaults<{
-    readonly seqNum: {
-        columnType: "integer";
-        schema: Schema.Schema<number & import("effect/Brand").Brand<"GlobalEventSequenceNumber">, number, never>;
-        default: Option.None<never>;
-        nullable: false;
-        primaryKey: true;
-        autoIncrement: false;
-    };
-    readonly parentSeqNum: {
-        columnType: "integer";
-        schema: Schema.Schema<number & import("effect/Brand").Brand<"GlobalEventSequenceNumber">, number, never>;
-        default: Option.None<never>;
-        nullable: false;
-        primaryKey: false;
-        autoIncrement: false;
-    };
-    readonly name: {
-        columnType: "text";
-        schema: Schema.Schema<string, string, never>;
-        default: Option.None<never>;
-        nullable: false;
-        primaryKey: false;
-        autoIncrement: false;
-    };
-    readonly args: {
-        columnType: "text";
-        schema: Schema.Schema<any, string | null, never>;
-        default: Option.None<never>;
-        nullable: true;
-        primaryKey: false;
-        autoIncrement: false;
-    };
-    /** ISO date format. Currently only used for debugging purposes. */
-    readonly createdAt: {
-        columnType: "text";
-        schema: Schema.Schema<string, string, never>;
-        default: Option.None<never>;
-        nullable: false;
-        primaryKey: false;
-        autoIncrement: false;
-    };
-    readonly clientId: {
-        columnType: "text";
-        schema: Schema.Schema<string, string, never>;
-        default: Option.None<never>;
-        nullable: false;
-        primaryKey: false;
-        autoIncrement: false;
-    };
-    readonly sessionId: {
-        columnType: "text";
-        schema: Schema.Schema<string, string, never>;
-        default: Option.None<never>;
-        nullable: false;
-        primaryKey: false;
-        autoIncrement: false;
-    };
-}>, Schema.Schema<{
-    readonly seqNum: number & import("effect/Brand").Brand<"GlobalEventSequenceNumber">;
-    readonly parentSeqNum: number & import("effect/Brand").Brand<"GlobalEventSequenceNumber">;
-    readonly name: string;
-    readonly args: any;
-    readonly createdAt: string;
-    readonly clientId: string;
-    readonly sessionId: string;
-}, {
-    readonly seqNum: number;
-    readonly parentSeqNum: number;
-    readonly name: string;
-    readonly args: string | null;
-    readonly createdAt: string;
-    readonly clientId: string;
-    readonly sessionId: string;
-}, never>>;
-export declare const PULL_CHUNK_SIZE = 100;
-/**
- * Needs to be bumped when the storage format changes (e.g. eventlogTable schema changes)
- *
- * Changing this version number will lead to a "soft reset".
- */
-export declare const PERSISTENCE_FORMAT_VERSION = 7;
-export type MakeDurableObjectClassOptions = {
-    onPush?: (message: WSMessage.PushReq, context: {
-        storeId: string;
-        payload?: Schema.JsonValue;
-    }) => Effect.Effect<void> | Promise<void>;
-    onPushRes?: (message: WSMessage.PushAck | WSMessage.Error) => Effect.Effect<void> | Promise<void>;
-    onPull?: (message: WSMessage.PullReq, context: {
-        storeId: string;
-        payload?: Schema.JsonValue;
-    }) => Effect.Effect<void> | Promise<void>;
-    onPullRes?: (message: WSMessage.PullRes | WSMessage.Error) => Effect.Effect<void> | Promise<void>;
-};
-export type MakeDurableObjectClass = (options?: MakeDurableObjectClassOptions) => {
-    new (ctx: CfWorker.DurableObjectState, env: Env): CfWorker.DurableObject;
-};
-/**
- * Creates a Durable Object class for handling WebSocket-based sync.
- *
- * Example:
- * ```ts
- * // In your Cloudflare Worker file
- * import { makeDurableObject } from '@livestore/sync-cf/cf-worker'
- *
- * export class WebSocketServer extends makeDurableObject({
- *   onPush: async (message) => {
- *     console.log('onPush', message.batch)
- *   },
- *   onPull: async (message) => {
- *     console.log('onPull', message)
- *   },
- * }) {}
- * ```
- *
- * ```toml
- * # wrangler.toml
- * [new_classes]
- * WebSocketServer = "src/websocket-server.ts"
- * ```
- */
-export declare const makeDurableObject: MakeDurableObjectClass;
-//# sourceMappingURL=durable-object.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"durable-object.d.ts","sourceRoot":"","sources":["../../src/cf-worker/durable-object.ts"],"names":[],"mappings":"AACA,OAAO,EAA4C,KAAK,EAAE,MAAM,0BAA0B,CAAA;AAE1F,OAAO,EAAE,MAAM,EAAoB,MAAM,EAAE,MAAM,EAAa,MAAM,yBAAyB,CAAA;AAC7F,OAAO,EAAsB,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAEhE,OAAO,KAAK,KAAK,QAAQ,MAAM,eAAe,CAAA;AAO9C,MAAM,WAAW,GAAG;IAClB,EAAE,EAAE,QAAQ,CAAC,UAAU,CAAA;IACvB,YAAY,EAAE,MAAM,CAAA;CACrB;AAKD,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAQtB,mEAAmE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAAnE,mEAAmE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAKrE,CAAA;AASF,eAAO,MAAM,eAAe,MAAM,CAAA;AAElC;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAA;AAE3C,MAAM,MAAM,6BAA6B,GAAG;IAC1C,MAAM,CAAC,EAAE,CACP,OAAO,EAAE,SAAS,CAAC,OAAO,EAC1B,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,SAAS,CAAA;KAAE,KACrD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,OAAO,GAAG,SAAS,CAAC,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjG,MAAM,CAAC,EAAE,CACP,OAAO,EAAE,SAAS,CAAC,OAAO,EAC1B,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,SAAS,CAAA;KAAE,KACrD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,OAAO,GAAG,SAAS,CAAC,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClG,CAAA;AAED,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,CAAC,EAAE,6BAA6B,KAAK;IAChF,KAAK,GAAG,EAAE,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE,GAAG,GAAG,QAAQ,CAAC,aAAa,CAAA;CACzE,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,iBAAiB,EAAE,sBA4Q/B,CAAA"}