@livestore/utils 0.2.0 → 0.3.0-dev.1

package/src/effect/TaskTracing.ts

@@ -0,0 +1,43 @@
+import { Predicate } from 'effect'
+import * as Context from 'effect/Context'
+import * as Effect from 'effect/Effect'
+import { pipe } from 'effect/Function'
+import * as Layer from 'effect/Layer'
+import * as Tracer from 'effect/Tracer'
+
+export const withAsyncTaggingTracing =
+  (makeTrace: (name: string) => { run: (fn: any) => any }) =>
+  <A, E, R>(eff: Effect.Effect<A, E, R>) => {
+    if (Predicate.hasProperty(console, 'createTask') === false) {
+      return eff
+    }
+
+    const makeTracer = Effect.gen(function* () {
+      const oldTracer = yield* Effect.tracer
+      return Tracer.make({
+        span: (name, ...args) => {
+          const span = oldTracer.span(name, ...args)
+          const trace = makeTrace(name)
+          ;(span as any).runInTask = (f: any) => trace.run(f)
+          return span
+        },
+        context: (f, fiber) => {
+          const maybeParentSpan = Context.getOption(Tracer.ParentSpan)(fiber.currentContext)
+
+          if (maybeParentSpan._tag === 'None') return oldTracer.context(f, fiber)
+          const parentSpan = maybeParentSpan.value
+          if (parentSpan._tag === 'ExternalSpan') return oldTracer.context(f, fiber)
+          const span = parentSpan
+          if ('runInTask' in span && typeof span.runInTask === 'function') {
+            return span.runInTask(() => oldTracer.context(f, fiber))
+          }
+
+          return oldTracer.context(f, fiber)
+        },
+      })
+    })
+
+    const withTracerLayer = pipe(makeTracer, Effect.map(Layer.setTracer), Layer.unwrapEffect)
+
+    return Effect.provide(eff, withTracerLayer)
+  }

package/src/effect/WebChannel/broadcastChannelWithAck.ts

@@ -0,0 +1,126 @@
+import type { Scope } from 'effect'
+import { Deferred, Effect, Predicate, Queue, Schema, Stream } from 'effect'
+
+import type { WebChannel } from './common.js'
+import { WebChannelSymbol } from './common.js'
+
+const ConnectMessage = Schema.TaggedStruct('ConnectMessage', {
+  from: Schema.String,
+})
+
+const ConnectAckMessage = Schema.TaggedStruct('ConnectAckMessage', {
+  from: Schema.String,
+  to: Schema.String,
+})
+
+const DisconnectMessage = Schema.TaggedStruct('DisconnectMessage', {
+  from: Schema.String,
+})
+
+const PayloadMessage = Schema.TaggedStruct('PayloadMessage', {
+  from: Schema.String,
+  to: Schema.String,
+  payload: Schema.Any,
+})
+
+const Message = Schema.Union(ConnectMessage, ConnectAckMessage, DisconnectMessage, PayloadMessage)
+
+/**
+ * Same as `broadcastChannel`, but with a queue in between to guarantee message delivery and meant
+ * for 1:1 connections.
+ */
+export const broadcastChannelWithAck = <MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>({
+  channelName,
+  listenSchema,
+  sendSchema,
+}: {
+  channelName: string
+  listenSchema: Schema.Schema<MsgListen, MsgListenEncoded>
+  sendSchema: Schema.Schema<MsgSend, MsgSendEncoded>
+}): Effect.Effect<WebChannel<MsgListen, MsgSend>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const channel = new BroadcastChannel(channelName)
+    const messageQueue = yield* Queue.unbounded<MsgSend>()
+    const connectionId = crypto.randomUUID()
+
+    const peerIdRef = { current: undefined as undefined | string }
+    const connectedLatch = yield* Effect.makeLatch(false)
+    const supportsTransferables = false
+
+    const postMessage = (msg: typeof Message.Type) => channel.postMessage(Schema.encodeSync(Message)(msg))
+
+    const send = (message: MsgSend) =>
+      Effect.gen(function* () {
+        yield* connectedLatch.await
+
+        const payload = yield* Schema.encode(sendSchema)(message)
+        postMessage(PayloadMessage.make({ from: connectionId, to: peerIdRef.current!, payload }))
+      })
+
+    const listen = Stream.fromEventListener<MessageEvent>(channel, 'message').pipe(
+      Stream.map(({ data }) => data),
+      Stream.map(Schema.decodeOption(Message)),
+      Stream.filterMap((_) => _),
+      Stream.mapEffect((data) =>
+        Effect.gen(function* () {
+          switch (data._tag) {
+            // Case: other side sends connect message (because otherside wasn't yet online when this side send their connect message)
+            case 'ConnectMessage': {
+              peerIdRef.current = data.from
+              postMessage(ConnectAckMessage.make({ from: connectionId, to: data.from }))
+              yield* connectedLatch.open
+              break
+            }
+            // Case: other side sends connect-ack message (because otherside was already online when this side connected)
+            case 'ConnectAckMessage': {
+              if (data.to === connectionId) {
+                peerIdRef.current = data.from
+                yield* connectedLatch.open
+              }
+              break
+            }
+            case 'DisconnectMessage': {
+              if (data.from === peerIdRef.current) {
+                peerIdRef.current = undefined
+                yield* connectedLatch.close
+                yield* establishConnection
+              }
+              break
+            }
+            case 'PayloadMessage': {
+              if (data.to === connectionId) {
+                return Schema.decodeEither(listenSchema)(data.payload)
+              }
+              break
+            }
+          }
+        }),
+      ),
+      Stream.filter(Predicate.isNotUndefined),
+    )
+
+    const establishConnection = Effect.gen(function* () {
+      postMessage(ConnectMessage.make({ from: connectionId }))
+    })
+
+    yield* establishConnection
+
+    yield* Effect.addFinalizer(() =>
+      Effect.gen(function* () {
+        postMessage(DisconnectMessage.make({ from: connectionId }))
+        channel.close()
+        yield* Queue.shutdown(messageQueue)
+      }),
+    )
+
+    const closedDeferred = yield* Deferred.make<void>()
+
+    return {
+      [WebChannelSymbol]: WebChannelSymbol,
+      send,
+      listen,
+      closedDeferred,
+      schema: { listen: listenSchema, send: sendSchema },
+      supportsTransferables,
+    }
+  }).pipe(Effect.withSpan(`WebChannel:broadcastChannelWithAck(${channelName})`))

package/src/effect/WebChannel/common.ts

@@ -0,0 +1,17 @@
+import type { Deferred, Effect, Either, ParseResult, Schema, Stream } from 'effect'
+import { Predicate } from 'effect'
+
+export const WebChannelSymbol = Symbol('WebChannel')
+export type WebChannelSymbol = typeof WebChannelSymbol
+
+export const isWebChannel = <MsgListen, MsgSend>(value: unknown): value is WebChannel<MsgListen, MsgSend> =>
+  typeof value === 'object' && value !== null && Predicate.hasProperty(value, WebChannelSymbol)
+
+export interface WebChannel<MsgListen, MsgSend, E = never> {
+  readonly [WebChannelSymbol]: unknown
+  send: (a: MsgSend) => Effect.Effect<void, ParseResult.ParseError | E>
+  listen: Stream.Stream<Either.Either<MsgListen, ParseResult.ParseError>, E>
+  supportsTransferables: boolean
+  closedDeferred: Deferred.Deferred<void>
+  schema: { listen: Schema.Schema<MsgListen, any>; send: Schema.Schema<MsgSend, any> }
+}

package/src/effect/WebChannel.ts

@@ -1,116 +1,290 @@
-import type { ParseResult, Scope } from 'effect'
-import { Deferred, Effect, Either, Queue, Stream } from 'effect'
+import type { Scope } from 'effect'
+import { Deferred, Effect, Either, Option, Predicate, Queue } from 'effect'
 
 import * as Schema from './Schema/index.js'
+import * as Stream from './Stream.js'
+import { type WebChannel, WebChannelSymbol } from './WebChannel/common.js'
 
-export type WebChannel<MsgIn, MsgOut, E = never> = {
-  send: (a: MsgOut) => Effect.Effect<void, ParseResult.ParseError | E>
-  listen: Stream.Stream<Either.Either<MsgIn, ParseResult.ParseError>, E>
-  closedDeferred: Deferred.Deferred<void>
-}
+export * from './WebChannel/broadcastChannelWithAck.js'
+
+export * from './WebChannel/common.js'
 
-export const broadcastChannel = <MsgIn, MsgOut, MsgInEncoded, MsgOutEncoded>({
+export const broadcastChannel = <MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>({
   channelName,
-  listenSchema,
-  sendSchema,
+  schema: inputSchema,
 }: {
   channelName: string
-  listenSchema: Schema.Schema<MsgIn, MsgInEncoded>
-  sendSchema: Schema.Schema<MsgOut, MsgOutEncoded>
-}): Effect.Effect<WebChannel<MsgIn, MsgOut>, never, Scope.Scope> =>
+  schema: InputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>
+}): Effect.Effect<WebChannel<MsgListen, MsgSend>, never, Scope.Scope> =>
   Effect.gen(function* () {
+    const schema = mapSchema(inputSchema)
+
     const channel = new BroadcastChannel(channelName)
 
     yield* Effect.addFinalizer(() => Effect.try(() => channel.close()).pipe(Effect.ignoreLogged))
 
-    const send = (message: MsgOut) =>
+    const send = (message: MsgSend) =>
       Effect.gen(function* () {
-        const messageEncoded = yield* Schema.encode(sendSchema)(message)
+        const messageEncoded = yield* Schema.encode(schema.send)(message)
         channel.postMessage(messageEncoded)
       })
 
     // TODO also listen to `messageerror` in parallel
     const listen = Stream.fromEventListener<MessageEvent>(channel, 'message').pipe(
-      Stream.map((_) => Schema.decodeEither(listenSchema)(_.data)),
+      Stream.map((_) => Schema.decodeEither(schema.listen)(_.data)),
     )
 
     const closedDeferred = yield* Deferred.make<void>()
+    const supportsTransferables = false
 
-    return { send, listen, closedDeferred }
+    return {
+      [WebChannelSymbol]: WebChannelSymbol,
+      send,
+      listen,
+      closedDeferred,
+      schema,
+      supportsTransferables,
+    }
   }).pipe(Effect.withSpan(`WebChannel:broadcastChannel(${channelName})`))
 
-export const windowChannel = <MsgIn, MsgOut, MsgInEncoded, MsgOutEncoded>({
+export const windowChannel = <MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>({
   window,
   targetOrigin = '*',
-  listenSchema,
-  sendSchema,
+  schema: inputSchema,
 }: {
   window: Window
   targetOrigin?: string
-  listenSchema: Schema.Schema<MsgIn, MsgInEncoded>
-  sendSchema: Schema.Schema<MsgOut, MsgOutEncoded>
-}): Effect.Effect<WebChannel<MsgIn, MsgOut>, never, Scope.Scope> =>
+  schema: InputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>
+}): Effect.Effect<WebChannel<MsgListen, MsgSend>, never, Scope.Scope> =>
   Effect.gen(function* () {
-    const send = (message: MsgOut) =>
+    const schema = mapSchema(inputSchema)
+
+    const send = (message: MsgSend) =>
       Effect.gen(function* () {
-        const [messageEncoded, transferables] = yield* Schema.encodeWithTransferables(sendSchema)(message)
+        const [messageEncoded, transferables] = yield* Schema.encodeWithTransferables(schema.send)(message)
         window.postMessage(messageEncoded, targetOrigin, transferables)
       })
 
     const listen = Stream.fromEventListener<MessageEvent>(window, 'message').pipe(
-      Stream.map((_) => Schema.decodeEither(listenSchema)(_.data)),
+      Stream.map((_) => Schema.decodeEither(schema.listen)(_.data)),
     )
 
     const closedDeferred = yield* Deferred.make<void>()
+    const supportsTransferables = true
 
-    return { send, listen, closedDeferred }
+    return {
+      [WebChannelSymbol]: WebChannelSymbol,
+      send,
+      listen,
+      closedDeferred,
+      schema,
+      supportsTransferables,
+    }
   }).pipe(Effect.withSpan(`WebChannel:windowChannel`))
 
-export const messagePortChannel = <MsgIn, MsgOut, MsgInEncoded, MsgOutEncoded>({
-  port,
-  listenSchema,
-  sendSchema,
-}: {
-  port: MessagePort
-  listenSchema: Schema.Schema<MsgIn, MsgInEncoded>
-  sendSchema: Schema.Schema<MsgOut, MsgOutEncoded>
-}): Effect.Effect<WebChannel<MsgIn, MsgOut>, never, Scope.Scope> =>
+export const messagePortChannel: {
+  <MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>(args: {
+    port: MessagePort
+    schema: InputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>
+  }): Effect.Effect<WebChannel<MsgListen, MsgSend>, never, Scope.Scope>
+} = ({ port, schema: inputSchema }) =>
   Effect.gen(function* () {
-    const send = (message: MsgOut) =>
+    const schema = mapSchema(inputSchema)
+
+    const send = (message: any) =>
       Effect.gen(function* () {
-        const [messageEncoded, transferables] = yield* Schema.encodeWithTransferables(sendSchema)(message)
+        const [messageEncoded, transferables] = yield* Schema.encodeWithTransferables(schema.send)(message)
         port.postMessage(messageEncoded, transferables)
       })
 
     const listen = Stream.fromEventListener<MessageEvent>(port, 'message').pipe(
-      Stream.map((_) => Schema.decodeEither(listenSchema)(_.data)),
+      Stream.map((_) => Schema.decodeEither(schema.listen)(_.data)),
     )
 
     port.start()
 
     const closedDeferred = yield* Deferred.make<void>()
+    const supportsTransferables = true
 
     yield* Effect.addFinalizer(() => Effect.try(() => port.close()).pipe(Effect.ignoreLogged))
 
-    return { send, listen, closedDeferred }
+    return {
+      [WebChannelSymbol]: WebChannelSymbol,
+      send,
+      listen,
+      closedDeferred,
+      schema,
+      supportsTransferables,
+    }
   }).pipe(Effect.withSpan(`WebChannel:messagePortChannel`))
 
-export const queueChannelProxy = <MsgIn, MsgOut>(): Effect.Effect<
-  { webChannel: WebChannel<MsgIn, MsgOut>; sendQueue: Queue.Queue<MsgOut>; listenQueue: Queue.Queue<MsgIn> },
-  never,
-  Scope.Scope
-> =>
+export const messagePortChannelWithAck: {
+  <MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>(args: {
+    port: MessagePort
+    schema: InputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>
+  }): Effect.Effect<WebChannel<MsgListen, MsgSend>, never, Scope.Scope>
+} = ({ port, schema: inputSchema }) =>
   Effect.gen(function* () {
-    const sendQueue = yield* Queue.unbounded<MsgOut>().pipe(Effect.acquireRelease(Queue.shutdown))
-    const listenQueue = yield* Queue.unbounded<MsgIn>().pipe(Effect.acquireRelease(Queue.shutdown))
+    const schema = mapSchema(inputSchema)
+
+    type RequestId = string
+    const requestAckMap = new Map<RequestId, Deferred.Deferred<void>>()
+
+    const ChannelRequest = Schema.TaggedStruct('ChannelRequest', {
+      id: Schema.String,
+      payload: Schema.Union(schema.listen, schema.send),
+    })
+    const ChannelRequestAck = Schema.TaggedStruct('ChannelRequestAck', {
+      reqId: Schema.String,
+    })
+    const ChannelMessage = Schema.Union(ChannelRequest, ChannelRequestAck)
+    type ChannelMessage = typeof ChannelMessage.Type
+
+    const send = (message: any) =>
+      Effect.gen(function* () {
+        const id = crypto.randomUUID()
+        const [messageEncoded, transferables] = yield* Schema.encodeWithTransferables(ChannelMessage)({
+          _tag: 'ChannelRequest',
+          id,
+          payload: message,
+        })
 
-    const send = (message: MsgOut) => Queue.offer(sendQueue, message)
+        const ack = yield* Deferred.make<void>()
+        requestAckMap.set(id, ack)
+
+        port.postMessage(messageEncoded, transferables)
+
+        yield* ack
+
+        requestAckMap.delete(id)
+      })
+
+    const listen = Stream.fromEventListener<MessageEvent>(port, 'message').pipe(
+      Stream.map((_) => Schema.decodeEither(ChannelMessage)(_.data)),
+      Stream.tap((msg) =>
+        Effect.gen(function* () {
+          if (msg._tag === 'Right') {
+            if (msg.right._tag === 'ChannelRequestAck') {
+              yield* Deferred.succeed(requestAckMap.get(msg.right.reqId)!, void 0)
+            } else if (msg.right._tag === 'ChannelRequest') {
+              port.postMessage(Schema.encodeSync(ChannelMessage)({ _tag: 'ChannelRequestAck', reqId: msg.right.id }))
+            }
+          }
+        }),
+      ),
+      Stream.filterMap((msg) =>
+        msg._tag === 'Left'
+          ? Option.some(msg as any)
+          : msg.right._tag === 'ChannelRequest'
+            ? Option.some(Either.right(msg.right.payload))
+            : Option.none(),
+      ),
+    )
+
+    port.start()
+
+    const closedDeferred = yield* Deferred.make<void>()
+    const supportsTransferables = true
+
+    yield* Effect.addFinalizer(() => Effect.try(() => port.close()).pipe(Effect.ignoreLogged))
+
+    return {
+      [WebChannelSymbol]: WebChannelSymbol,
+      send,
+      listen,
+      closedDeferred,
+      schema,
+      supportsTransferables,
+    }
+  }).pipe(Effect.withSpan(`WebChannel:messagePortChannelWithAck`))
+
+export type InputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded> =
+  | Schema.Schema<MsgListen | MsgSend, MsgListenEncoded | MsgSendEncoded>
+  | {
+      listen: Schema.Schema<MsgListen, MsgListenEncoded>
+      send: Schema.Schema<MsgSend, MsgSendEncoded>
+    }
+
+export const mapSchema = <MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>(
+  schema: InputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>,
+): {
+  listen: Schema.Schema<MsgListen, MsgListenEncoded>
+  send: Schema.Schema<MsgSend, MsgSendEncoded>
+} =>
+  Predicate.hasProperty(schema, 'send') && Predicate.hasProperty(schema, 'listen')
+    ? { send: schema.send, listen: schema.listen }
+    : ({ send: schema, listen: schema } as any)
+
+export type QueueChannelProxy<MsgListen, MsgSend> = {
+  /** Only meant to be used externally */
+  webChannel: WebChannel<MsgListen, MsgSend>
+  /**
+   * Meant to be listened to (e.g. via `Stream.fromQueue`) for messages that have been sent
+   * via `webChannel.send()`.
+   */
+  sendQueue: Queue.Dequeue<MsgSend>
+  /**
+   * Meant to be pushed to (e.g. via `Queue.offer`) for messages that will be received
+   * via `webChannel.listen()`.
+   */
+  listenQueue: Queue.Enqueue<MsgListen>
+}
+
+/**
+ * From the outside the `sendQueue` is only accessible read-only,
+ * and the `listenQueue` is only accessible write-only.
+ */
+export const queueChannelProxy = <MsgListen, MsgSend>({
+  schema: inputSchema,
+}: {
+  schema:
+    | Schema.Schema<MsgListen | MsgSend, any>
+    | { listen: Schema.Schema<MsgListen, any>; send: Schema.Schema<MsgSend, any> }
+}): Effect.Effect<QueueChannelProxy<MsgListen, MsgSend>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const sendQueue = yield* Queue.unbounded<MsgSend>().pipe(Effect.acquireRelease(Queue.shutdown))
+    const listenQueue = yield* Queue.unbounded<MsgListen>().pipe(Effect.acquireRelease(Queue.shutdown))
+
+    const send = (message: MsgSend) => Queue.offer(sendQueue, message)
 
     const listen = Stream.fromQueue(listenQueue).pipe(Stream.map(Either.right))
 
     const closedDeferred = yield* Deferred.make<void>()
+    const supportsTransferables = true
 
-    const webChannel = { send, listen, closedDeferred }
+    const schema = mapSchema(inputSchema)
+
+    const webChannel = {
+      [WebChannelSymbol]: WebChannelSymbol,
+      send,
+      listen,
+      closedDeferred,
+      schema,
+      supportsTransferables,
+    }
 
     return { webChannel, sendQueue, listenQueue }
   })
+
+// export const proxy = <MsgListen, MsgSend>({
+//   originWebChannel,
+//   proxyWebChannel,
+// }: {
+//   originWebChannel: WebChannel<MsgListen, MsgSend>
+//   proxyWebChannel: QueueChannelProxy<MsgListen, MsgSend>
+// }) =>
+//   Effect.gen(function* () {
+//     const proxyListen = originWebChannel.listen.pipe(
+//       Stream.flatten(),
+//       Stream.tap((_) => Queue.offer(proxyWebChannel.listenQueue, _)),
+//       Stream.runDrain,
+//     )
+
+//     const proxySend = proxyWebChannel.sendQueue.pipe(
+//       Stream.fromQueue,
+//       Stream.tap(originWebChannel.send),
+//       Stream.runDrain,
+//     )
+
+//     yield* Effect.all([proxyListen, proxySend], { concurrency: 2 })
+//   })

package/src/effect/WebLock.ts

@@ -93,3 +93,78 @@ export const tryGetDeferredLock = (deferred: Deferred.Deferred<void>, lockName:
       ])
     })
   })
+
+export const stealDeferredLock = (deferred: Deferred.Deferred<void>, lockName: string) =>
+  Effect.async<boolean>((cb, signal) => {
+    navigator.locks.request(lockName, { mode: 'exclusive', steal: true }, (lock) => {
+      cb(Effect.succeed(lock !== null))
+
+      // the code below is still running
+
+      const abortPromise = new Promise<void>((resolve) => {
+        signal.addEventListener('abort', () => {
+          resolve()
+        })
+      })
+
+      // holding lock until deferred is resolved
+      return Promise.race([Effect.runPromise(Deferred.await(deferred)), abortPromise])
+      // .finally(() =>
+      //   console.log('[@livestore/utils:WebLock] tryGetDeferredLock. finally', lockName),
+      // )
+    })
+  })
+
+export const waitForLock = (lockName: string) =>
+  Effect.async<void>((cb, signal) => {
+    if (signal.aborted) return
+
+    navigator.locks.request(lockName, { mode: 'shared', signal, ifAvailable: false }, (_lock) => {
+      cb(Effect.succeed(void 0))
+    })
+  })
+
+/** Attempts to get the lock if available and waits for it to be stolen */
+export const getLockAndWaitForSteal = (lockName: string) =>
+  Effect.async<void>((cb, signal) => {
+    if (signal.aborted) return
+
+    navigator.locks
+      .request(lockName, { mode: 'exclusive', ifAvailable: true }, async (lock) => {
+        if (lock === null) {
+          // Lock wasn't available, resolve immediately
+          cb(Effect.succeed(void 0))
+          return
+        }
+
+        // We got the lock, now wait for it to be stolen
+        // When the lock is stolen, the promise will resolve
+        await new Promise<void>((resolve) => {
+          // Create a never-resolving promise unless interrupted
+          const holdLock = new Promise(() => {})
+
+          // Listen for the abort signal
+          signal.addEventListener('abort', () => {
+            resolve()
+          })
+
+          return Promise.race([holdLock, signal.aborted ? Promise.resolve() : holdLock]).catch(() => {})
+        }).catch(() => {})
+
+        cb(Effect.succeed(void 0))
+      })
+      .catch((error) => {
+        if (
+          error.code === 20 &&
+          (error.message === 'signal is aborted without reason' ||
+            error.message === `Lock broken by another request with the 'steal' option.`)
+        ) {
+          // Given signal interruption is handled via Effect, we can ignore this case
+          // or the case when the lock is stolen
+          cb(Effect.succeed(void 0))
+        } else {
+          console.error('[@livestore/utils:WebLock] getLockAndWaitForSteal. error', error)
+          throw error
+        }
+      })
+  })

package/src/effect/WebSocket.ts

@@ -0,0 +1,72 @@
+import type { Schedule, Scope } from 'effect'
+import { Effect, Exit, identity, Schema } from 'effect'
+
+export class WebSocketError extends Schema.TaggedError<WebSocketError>()('WebSocketError', {
+  cause: Schema.Defect,
+}) {}
+
+// TODO refactor using Effect socket implementation
+// https://github.com/Effect-TS/effect/blob/main/packages%2Fexperimental%2Fsrc%2FDevTools%2FClient.ts#L113
+// "In a Stream pipeline everything above the pipeThrough is the outgoing (send) messages. Everything below is the incoming (message event) messages."
+// https://github.com/Effect-TS/effect/blob/main/packages%2Fplatform%2Fsrc%2FSocket.ts#L451
+
+/**
+ * Creates a WebSocket connection and waits for the connection to be established.
+ * Automatically closes the connection when the scope is closed.
+ */
+export const makeWebSocket = ({
+  url,
+  reconnect,
+}: {
+  url: string
+  reconnect?: Schedule.Schedule<unknown> | false
+}): Effect.Effect<globalThis.WebSocket, WebSocketError, Scope.Scope> =>
+  Effect.gen(function* () {
+    const socket = yield* Effect.tryPromise({
+      try: async () => {
+        // console.debug('[WebSocket] connecting to', url)
+        const socket = new globalThis.WebSocket(url)
+
+        if (socket.readyState === globalThis.WebSocket.OPEN) {
+          return socket
+        }
+
+        return await new Promise<globalThis.WebSocket>((resolve, reject) => {
+          socket.addEventListener('open', () => resolve(socket), { once: true })
+          // eslint-disable-next-line unicorn/prefer-add-event-listener
+          socket.onerror = (event) => reject(event)
+        })
+      },
+      catch: (errorEvent: any) => {
+        if (errorEvent.currentTarget != null && errorEvent.currentTarget instanceof globalThis.WebSocket) {
+          errorEvent.currentTarget.close(3000, `closing websocket connection due to error: ${errorEvent.toString()}`)
+        }
+
+        return new WebSocketError({ cause: errorEvent })
+      },
+    }).pipe(
+      /**
+       * Common WebSocket close codes: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/close
+       *   1000: Normal closure
+       *   1001: Endpoint is going away, a server is terminating the connection because it has received a request that indicates the client is ending the connection.
+       *   1002: Protocol error, a server is terminating the connection because it has received data on the connection that was not consistent with the type of the connection.
+       *   1011: Internal server error, a server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request.
+       *
+       * For reference, here are the valid WebSocket close code ranges:
+       *   1000-1999: Reserved for protocol usage
+       *   2000-2999: Reserved for WebSocket extensions
+       *   3000-3999: Available for libraries and frameworks
+       *   4000-4999: Available for applications
+       */
+      Effect.acquireRelease((socket, exit) =>
+        Effect.sync(() =>
+          Exit.isFailure(exit)
+            ? socket.close(3000, `closing webmesh websocket connection due to error: ${exit.cause.toString()}`)
+            : socket.close(1000, 'closing webmesh websocket connection gracefully'),
+        ),
+      ),
+      reconnect ? Effect.retry(reconnect) : identity,
+    )
+
+    return socket
+  })