@livestore/sync-cf 0.3.1 → 0.3.2-dev.1

package/src/cf-worker/mod.ts

@@ -1,2 +1,2 @@
-export * from './durable-object.js'
-export * from './worker.js'
+export * from './durable-object.ts'
+export * from './worker.ts'

package/src/cf-worker/worker.ts

@@ -1,16 +1,57 @@
+import type * as CfWorker from '@cloudflare/workers-types'
 import { UnexpectedError } from '@livestore/common'
 import type { Schema } from '@livestore/utils/effect'
 import { Effect, UrlParams } from '@livestore/utils/effect'
 
-import { SearchParamsSchema } from '../common/mod.js'
-import type { Env } from './durable-object.js'
+import { SearchParamsSchema } from '../common/mod.ts'
+import type { Env } from './durable-object.ts'
 
-export type CFWorker = {
-  fetch: (request: Request, env: Env, ctx: ExecutionContext) => Promise<Response>
+// Redeclaring Response to Cloudflare Worker Response type to avoid lib.dom type clashing
+declare const Response: typeof CfWorker.Response
+
+/**
+ * Helper type to extract DurableObject keys from Env to give consumer type safety.
+ *
+ * @example
+ * ```ts
+ *  type PlatformEnv = {
+ *    DB: D1Database
+ *    ADMIN_TOKEN: string
+ *    WEBSOCKET_SERVER: DurableObjectNamespace<WebSocketServer>
+ * }
+ *  export default makeWorker<PlatformEnv>({
+ *    durableObject: { name: "WEBSOCKET_SERVER" },
+ *    // ^ (property) name?: "WEBSOCKET_SERVER" | undefined
+ *  });
+ */
+type ExtractDurableObjectKeys<TEnv = Env> = TEnv extends Env
+  ? [keyof TEnv] extends [keyof Env]
+    ? string
+    : keyof {
+        [K in keyof TEnv as K extends keyof Env
+          ? never
+          : TEnv[K] extends CfWorker.DurableObjectNamespace<any>
+            ? K
+            : never]: TEnv[K]
+      }
+  : never
+
+// 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 CfWorker.Rpc.DurableObjectBranded | undefined = undefined> = {
+  fetch: <CFHostMetada = unknown>(
+    request: CfWorker.Request<CFHostMetada>,
+    env: TEnv,
+    ctx: CfWorker.ExecutionContext,
+  ) => Promise<CfWorker.Response>
 }
 
-export type MakeWorkerOptions = {
-  validatePayload?: (payload: Schema.JsonValue | undefined) => void | Promise<void>
+export type MakeWorkerOptions<TEnv extends Env = Env> = {
+  /**
+   * Validates the payload during WebSocket connection establishment.
+   * Note: This runs only at connection time, not for individual push events.
+   * For push event validation, use the `onPush` callback in the durable object.
+   */
+  validatePayload?: (payload: Schema.JsonValue | undefined, context: { storeId: string }) => void | Promise<void>
   /** @default false */
   enableCORS?: boolean
   durableObject?: {
@@ -19,11 +60,16 @@ export type MakeWorkerOptions = {
      *
      * @default 'WEBSOCKET_SERVER'
      */
-    name?: string
+    name?: ExtractDurableObjectKeys<TEnv>
   }
 }
 
-export const makeWorker = (options: MakeWorkerOptions = {}): CFWorker => {
+export const makeWorker = <
+  TEnv extends Env = Env,
+  TDurableObjectRpc extends CfWorker.Rpc.DurableObjectBranded | undefined = undefined,
+>(
+  options: MakeWorkerOptions<TEnv> = {},
+): CFWorker<TEnv, TDurableObjectRpc> => {
   return {
     fetch: async (request, env, _ctx) => {
       const url = new URL(request.url)
@@ -37,7 +83,7 @@ export const makeWorker = (options: MakeWorkerOptions = {}): CFWorker => {
         })
       }
 
-      const corsHeaders: HeadersInit = options.enableCORS
+      const corsHeaders: CfWorker.HeadersInit = options.enableCORS
         ? {
             'Access-Control-Allow-Origin': '*',
             'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
@@ -53,7 +99,7 @@ export const makeWorker = (options: MakeWorkerOptions = {}): CFWorker => {
       }
 
       if (url.pathname.endsWith('/websocket')) {
-        return handleWebSocket(request, env, _ctx, {
+        return handleWebSocket<TEnv, TDurableObjectRpc>(request, env, _ctx, {
           headers: corsHeaders,
           validatePayload: options.validatePayload,
           durableObject: options.durableObject,
@@ -79,7 +125,8 @@ export const makeWorker = (options: MakeWorkerOptions = {}): CFWorker => {
  *
  * @example
  * ```ts
- * const validatePayload = (payload: Schema.JsonValue | undefined) => {
+ * const validatePayload = (payload: Schema.JsonValue | undefined, context: { storeId: string }) => {
+ *   console.log(`Validating connection for store: ${context.storeId}`)
  *   if (payload?.authToken !== 'insecure-token-change-me') {
  *     throw new Error('Invalid auth token')
  *   }
@@ -98,16 +145,20 @@ export const makeWorker = (options: MakeWorkerOptions = {}): CFWorker => {
  *
  * @throws {UnexpectedError} If the payload is invalid
  */
-export const handleWebSocket = (
-  request: Request,
-  env: Env,
-  _ctx: ExecutionContext,
+export const handleWebSocket = <
+  TEnv extends Env = Env,
+  TDurableObjectRpc extends CfWorker.Rpc.DurableObjectBranded | undefined = undefined,
+  CFHostMetada = unknown,
+>(
+  request: CfWorker.Request<CFHostMetada>,
+  env: TEnv,
+  _ctx: CfWorker.ExecutionContext,
   options: {
-    headers?: HeadersInit
-    durableObject?: MakeWorkerOptions['durableObject']
-    validatePayload?: (payload: Schema.JsonValue | undefined) => void | Promise<void>
+    headers?: CfWorker.HeadersInit
+    durableObject?: MakeWorkerOptions<TEnv>['durableObject']
+    validatePayload?: (payload: Schema.JsonValue | undefined, context: { storeId: string }) => void | Promise<void>
   },
-): Promise<Response> =>
+): Promise<CfWorker.Response> =>
   Effect.gen(function* () {
     const url = new URL(request.url)
 
@@ -124,7 +175,7 @@ export const handleWebSocket = (
     const { storeId, payload } = paramsResult.right
 
     if (options.validatePayload !== undefined) {
-      const result = yield* Effect.promise(async () => options.validatePayload!(payload)).pipe(
+      const result = yield* Effect.promise(async () => options.validatePayload!(payload, { storeId })).pipe(
         UnexpectedError.mapToUnexpectedError,
         Effect.either,
       )
@@ -136,15 +187,28 @@ export const handleWebSocket = (
     }
 
     const durableObjectName = options.durableObject?.name ?? 'WEBSOCKET_SERVER'
-    const durableObjectNamespace = (env as any)[durableObjectName] as DurableObjectNamespace
+    if (!(durableObjectName in env)) {
+      return new Response(`Failed dependency: Required Durable Object binding '${durableObjectName}' not available`, {
+        status: 424,
+        headers: options.headers,
+      })
+    }
+
+    const durableObjectNamespace = env[
+      durableObjectName as keyof TEnv
+    ] as CfWorker.DurableObjectNamespace<TDurableObjectRpc>
 
     const id = durableObjectNamespace.idFromName(storeId)
     const durableObject = durableObjectNamespace.get(id)
 
     const upgradeHeader = request.headers.get('Upgrade')
     if (!upgradeHeader || upgradeHeader !== 'websocket') {
-      return new Response('Durable Object expected Upgrade: websocket', { status: 426, headers: options?.headers })
+      return new Response('Durable Object expected Upgrade: websocket', {
+        status: 426,
+        headers: options?.headers,
+      })
     }
 
-    return yield* Effect.promise(() => durableObject.fetch(request))
+    // Cloudflare Durable Object type clashing with lib.dom Response type, which is why we need the casts here.
+    return yield* Effect.promise(() => durableObject.fetch(request as any) as unknown as Promise<CfWorker.Response>)
   }).pipe(Effect.tapCauseLogPretty, Effect.runPromise)

package/src/common/mod.ts

@@ -1,6 +1,6 @@
 import { Schema } from '@livestore/utils/effect'
 
-export * as WSMessage from './ws-message-types.js'
+export * as WSMessage from './ws-message-types.ts'
 
 export const SearchParamsSchema = Schema.Struct({
   storeId: Schema.String,

package/src/sync-impl/mod.ts

@@ -1 +1 @@
-export * from './ws-impl.js'
+export * from './ws-impl.ts'

package/src/sync-impl/ws-impl.ts

@@ -19,8 +19,8 @@ import {
 } from '@livestore/utils/effect'
 import { nanoid } from '@livestore/utils/nanoid'
 
-import { SearchParamsSchema, WSMessage } from '../common/mod.js'
-import type { SyncMetadata } from '../common/ws-message-types.js'
+import { SearchParamsSchema, WSMessage } from '../common/mod.ts'
+import type { SyncMetadata } from '../common/ws-message-types.ts'
 
 export interface WsSyncOptions {
   url: string
@@ -235,10 +235,10 @@ const connect = (wsUrl: string) =>
 
       // NOTE it seems that this callback doesn't work reliably on a worker but only via `window.addEventListener`
       // We might need to proxy the event from the main thread to the worker if we want this to work reliably.
-      // eslint-disable-next-line unicorn/prefer-global-this
+
       if (typeof self !== 'undefined' && typeof self.addEventListener === 'function') {
         // TODO support an Expo equivalent for this
-        // eslint-disable-next-line unicorn/prefer-global-this
+
         yield* Effect.eventListener(self, 'offline', () => Deferred.succeed(connectionClosed, void 0))
       }