@livestore/utils 0.4.0-dev.9 → 0.5.0-dev.0

package/src/effect/WebChannel/common.ts

@@ -1,5 +1,4 @@
-import type { Deferred, Either, ParseResult } from 'effect'
-import { Effect, Predicate, Schema, Stream } from 'effect'
+import { type Deferred, Effect, Predicate, Result, Schema, Stream } from 'effect'
 
 export const WebChannelSymbol = Symbol('WebChannel')
 export type WebChannelSymbol = typeof WebChannelSymbol
@@ -9,13 +8,13 @@ export const isWebChannel = <MsgListen, MsgSend>(value: unknown): value is WebCh
 
 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>
+  send: (a: MsgSend) => Effect.Effect<void, Schema.SchemaError | E>
+  listen: Stream.Stream<Result.Result<MsgListen, Schema.SchemaError>, E>
   supportsTransferables: boolean
   closedDeferred: Deferred.Deferred<void>
   shutdown: Effect.Effect<void>
-  schema: { listen: Schema.Schema<MsgListen, any>; send: Schema.Schema<MsgSend, any> }
-  debugInfo?: Record<string, any>
+  schema: { listen: Schema.Codec<MsgListen, any>; send: Schema.Codec<MsgSend, any> }
+  debugInfo?: Record<string, any> | undefined
 }
 
 export const DebugPingMessage = Schema.TaggedStruct('WebChannel.DebugPing', {
@@ -31,43 +30,43 @@ export const WebChannelPong = Schema.TaggedStruct('WebChannel.Pong', {
   requestId: Schema.String,
 })
 
-export const WebChannelHeartbeat = Schema.Union(WebChannelPing, WebChannelPong)
+export const WebChannelHeartbeat = Schema.Union([WebChannelPing, WebChannelPong])
 
 type WebChannelMessages = typeof DebugPingMessage.Type | typeof WebChannelPing.Type | typeof WebChannelPong.Type
 
 export const schemaWithWebChannelMessages = <MsgListen, MsgSend>(
   schema: OutputSchema<MsgListen, MsgSend, any, any>,
 ): OutputSchema<MsgListen | WebChannelMessages, MsgSend | WebChannelMessages, any, any> => ({
-  send: Schema.Union(schema.send, DebugPingMessage, WebChannelPing, WebChannelPong),
-  listen: Schema.Union(schema.listen, DebugPingMessage, WebChannelPing, WebChannelPong),
+  send: Schema.Union([schema.send, DebugPingMessage, WebChannelPing, WebChannelPong]),
+  listen: Schema.Union([schema.listen, DebugPingMessage, WebChannelPing, WebChannelPong]),
 })
 
 export type InputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded> =
-  | Schema.Schema<MsgListen | MsgSend, MsgListenEncoded | MsgSendEncoded>
+  | Schema.Codec<MsgListen | MsgSend, MsgListenEncoded | MsgSendEncoded>
   | OutputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>
 
 export type OutputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded> = {
-  listen: Schema.Schema<MsgListen, MsgListenEncoded>
-  send: Schema.Schema<MsgSend, MsgSendEncoded>
+  listen: Schema.Codec<MsgListen, MsgListenEncoded>
+  send: Schema.Codec<MsgSend, MsgSendEncoded>
 }
 
 export const mapSchema = <MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>(
   schema: InputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>,
 ): OutputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded> =>
-  Predicate.hasProperty(schema, 'send') && Predicate.hasProperty(schema, 'listen')
+  Predicate.hasProperty(schema, 'send') === true && Predicate.hasProperty(schema, 'listen') === true
     ? (schemaWithWebChannelMessages(schema) as any)
     : (schemaWithWebChannelMessages({ send: schema, listen: schema }) as any)
 
 export const listenToDebugPing =
   (channelName: string) =>
   <MsgListen>(
-    stream: Stream.Stream<Either.Either<MsgListen, ParseResult.ParseError>, never>,
-  ): Stream.Stream<Either.Either<MsgListen, ParseResult.ParseError>, never> =>
+    stream: Stream.Stream<Result.Result<MsgListen, Schema.SchemaError>>,
+  ): Stream.Stream<Result.Result<MsgListen, Schema.SchemaError>> =>
     stream.pipe(
       Stream.filterEffect(
         Effect.fn(function* (msg) {
-          if (msg._tag === 'Right' && Schema.is(DebugPingMessage)(msg.right)) {
-            yield* Effect.logDebug(`WebChannel:ping [${channelName}] ${msg.right.message}`, msg.right.payload)
+          if (Result.isSuccess(msg) === true && Schema.is(DebugPingMessage)(msg.success) === true) {
+            yield* Effect.logDebug(`WebChannel:ping [${channelName}] ${msg.success.message}`, msg.success.payload)
             return false
           }
           return true

package/src/effect/WebSocket.test.ts

@@ -1,11 +1,11 @@
-import { FetchHttpClient } from '@effect/platform'
 import * as Vitest from '@effect/vitest'
 import { Effect, Exit } from 'effect'
+import { FetchHttpClient } from 'effect/unstable/http'
 
 import { makeWebSocket } from './WebSocket.ts'
 
 Vitest.describe('WebSocket', () => {
-  Vitest.scopedLive(
+  Vitest.live(
     'should create a WebSocket connection',
     Effect.fn(function* () {
       const exit = yield* makeWebSocket({ url: 'ws://localhost:1000' }).pipe(Effect.timeout(500), Effect.exit)

package/src/effect/WebSocket.ts

@@ -1,10 +1,13 @@
-import { HttpClient } from '@effect/platform'
 import type { Schedule, Scope } from 'effect'
 import { Effect, Exit, identity, Schema } from 'effect'
+import { HttpClient } from 'effect/unstable/http'
 
-export class WebSocketError extends Schema.TaggedError<WebSocketError>()('WebSocketError', {
-  cause: Schema.Defect,
-}) {}
+export class WebSocketError extends Schema.TaggedError<WebSocketError>('~@livestore/utils/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
@@ -25,7 +28,7 @@ export const makeWebSocket = ({
   Effect.gen(function* () {
     yield* validateUrl(url)
 
-    const socket = yield* Effect.async<globalThis.WebSocket, WebSocketError>((cb, signal) => {
+    const socket = yield* Effect.callback<globalThis.WebSocket, WebSocketError>((cb, signal) => {
       try {
         const socket = new globalThis.WebSocket(url)
 
@@ -63,7 +66,7 @@ export const makeWebSocket = ({
       }
     }).pipe(
       Effect.tapErrorTag('WebSocketError', () => tryLogWebsocketConnectError(url)),
-      reconnect ? Effect.retry(reconnect) : identity,
+      reconnect !== undefined && reconnect !== false ? Effect.retry(reconnect) : identity,
     )
 
     /**
@@ -81,16 +84,17 @@ export const makeWebSocket = ({
      */
     yield* Effect.addFinalizer(
       Effect.fn(function* (exit) {
-        try {
-          if (Exit.isFailure(exit)) {
-            socket.close(3000)
-          } else {
-            socket.close(1000)
-          }
-        } catch (error) {
-          return yield* Effect.die(new WebSocketError({ cause: error }))
-        }
-      }),
+        yield* Effect.try({
+          try: () => {
+            if (Exit.isFailure(exit) === true) {
+              socket.close(3000)
+            } else {
+              socket.close(1000)
+            }
+          },
+          catch: (error) => new WebSocketError({ cause: error }),
+        })
+      }, Effect.orDie),
     )
 
     return socket

package/src/effect/mod.browser-build.test.ts

@@ -0,0 +1,19 @@
+import { build } from 'esbuild'
+import { expect, it } from 'vitest'
+
+it('bundles the Effect facade for browsers without Node builtins', async () => {
+  const result = await build({
+    bundle: true,
+    format: 'esm',
+    platform: 'browser',
+    stdin: {
+      contents: `import { Schema } from './mod.ts'; export const BrowserSchema = Schema.Struct({ value: Schema.String })`,
+      loader: 'ts',
+      resolveDir: import.meta.dirname,
+      sourcefile: 'browser-build-fixture.ts',
+    },
+    write: false,
+  })
+
+  expect(result.outputFiles).toHaveLength(1)
+})

package/src/effect/{index.ts → mod.ts}

@@ -1,34 +1,11 @@
 import '../global.ts'
 
+export { Otlp } from 'effect/unstable/observability'
+export { Msgpack } from 'effect/unstable/encoding'
 export {
-  AiError,
-  LanguageModel,
-  LanguageModel as AiLanguageModel,
-  McpSchema,
-  McpServer,
-  Model,
-  Model as AiModel,
-  Prompt,
-  Tool,
-  Tool as AiTool,
-  Toolkit,
-  Toolkit as AiToolkit,
-} from '@effect/ai'
-// export { DevTools as EffectDevtools } from '@effect/experimental'
-export { Sse } from '@effect/experimental'
-export * as Otlp from '@effect/opentelemetry/Otlp'
-export {
-  Command,
-  CommandExecutor,
-  Error as PlatformError,
   FetchHttpClient,
-  FileSystem,
   Headers,
-  HttpApi,
-  HttpApiClient,
-  HttpApiEndpoint,
-  HttpApiGroup,
-  HttpApp,
+  HttpEffect,
   HttpClient,
   HttpClientError,
   HttpClientRequest,
@@ -38,20 +15,15 @@ export {
   HttpServer,
   HttpServerRequest,
   HttpServerResponse,
-  KeyValueStore,
-  MsgPack,
-  Socket,
-  Terminal,
-  Transferable,
   UrlParams,
-  Worker,
-  WorkerError,
-  WorkerRunner,
-} from '@effect/platform'
-export { BrowserWorker, BrowserWorkerRunner } from '@effect/platform-browser'
+} from 'effect/unstable/http'
+export { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from 'effect/unstable/httpapi'
+export { KeyValueStore } from 'effect/unstable/persistence'
+export { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process'
+export { Socket } from 'effect/unstable/socket'
+export { Transferable, Worker, WorkerError, WorkerRunner } from 'effect/unstable/workers'
 export {
   Rpc,
-  // RpcClient, // TODO bring back "original" RpcClient from effect/rpc
   RpcClientError,
   RpcGroup,
   RpcMessage,
@@ -61,7 +33,7 @@ export {
   RpcServer,
   RpcTest,
   RpcWorker,
-} from '@effect/rpc'
+} from 'effect/unstable/rpc'
 export * as StandardSchema from '@standard-schema/spec'
 export {
   Array as ReadonlyArray,
@@ -71,85 +43,87 @@ export {
   Channel,
   Chunk,
   Config,
-  ConfigError,
+  ConfigProvider,
   Console,
   Context,
   Data,
   Deferred,
   Duration,
-  Either,
+  Result,
   Equal,
-  ExecutionStrategy,
   Exit,
-  FastCheck,
   Fiber,
+  Filter,
+  FileSystem,
+  Terminal,
   FiberHandle,
-  FiberId,
   FiberMap,
-  FiberRef,
-  FiberRefs,
-  FiberRefsPatch,
   FiberSet,
-  GlobalValue,
+  Formatter,
+  Function,
   Hash,
   HashMap,
   HashSet,
   Inspectable,
   identity,
+  Latch,
   Layer,
-  List,
   LogLevel,
-  LogSpan,
-  Mailbox,
   ManagedRuntime,
   Match,
   Metric,
-  MetricState,
   MutableHashMap,
   MutableHashSet,
+  MutableList,
   Option,
-  ParseResult,
+  Order,
   Predicate,
-  Pretty,
   PrimaryKey,
+  PlatformError,
   PubSub,
-  // Subscribable,
   pipe,
   Queue,
+  RcMap,
+  RcRef,
   Record as ReadonlyRecord,
+  References,
+  Redacted,
   Ref,
   Request,
   Runtime,
-  RuntimeFlags,
   Scope,
-  SortedMap,
-  STM,
+  ScopedRef,
+  Scheduler,
+  SchemaIssue,
+  SchemaAST,
+  SchemaGetter,
+  SchemaParser,
+  SchemaRepresentation,
+  SchemaTransformation,
+  Semaphore,
+  Sink,
+  Struct,
+  Graph,
   SynchronizedRef,
-  TestServices,
-  TQueue,
-  TRef,
   Tracer,
+  TxQueue,
+  TxRef,
   Types,
 } from 'effect'
-export type { NonEmptyArray } from 'effect/Array'
-export { constVoid, dual } from 'effect/Function'
-export { TreeFormatter } from 'effect/ParseResult'
-export type { Serializable, SerializableWithResult } from 'effect/Schema'
-export * as SchemaAST from 'effect/SchemaAST'
-export * as BucketQueue from './BucketQueue.ts'
+export * as FastCheck from 'effect/testing/FastCheck'
+export * as TestClock from 'effect/testing/TestClock'
+export * as TestConsole from 'effect/testing/TestConsole'
+export * as Debug from './Debug.ts'
 export * as Effect from './Effect.ts'
 export * from './Error.ts'
 export * as Logger from './Logger.ts'
 export * as OtelTracer from './OtelTracer.ts'
 export * as RpcClient from './RpcClient.ts'
 export * as Schedule from './Schedule.ts'
-export * as Scheduler from './Scheduler.ts'
 export * as Schema from './Schema/index.ts'
-export * as ServiceContext from './ServiceContext.ts'
 export * as Stream from './Stream.ts'
 export * as Subscribable from './Subscribable.ts'
 export * as SubscriptionRef from './SubscriptionRef.ts'
 export * as TaskTracing from './TaskTracing.ts'
 export * as WebChannel from './WebChannel/mod.ts'
-export * as WebLock from './WebLock.ts'
 export * as WebSocket from './WebSocket.ts'

package/src/effect/spanEvent.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from '@effect/vitest'
+import { Effect, Tracer } from 'effect'
+
+import { spanEvent } from './spanEvent.ts'
+
+type RecordedEvent = { name: string; attributes: Record<string, unknown> | undefined }
+
+/**
+ * Creates a test tracer that captures span events for assertion,
+ * using only the public `Tracer` API (no internal NativeSpan access).
+ * Each span records its own events, retrievable by span name.
+ */
+const makeTestTracer = () => {
+  const spanEvents = new Map<string, Array<RecordedEvent>>()
+
+  const tracer = Tracer.make({
+    span(options) {
+      const events: Array<RecordedEvent> = []
+      spanEvents.set(options.name, events)
+      const attributes = new Map<string, unknown>()
+      return {
+        _tag: 'Span' as const,
+        name: options.name,
+        spanId: `test-${options.name}`,
+        traceId: 'test-trace',
+        parent: options.parent,
+        annotations: options.annotations,
+        status: { _tag: 'Started' as const, startTime: options.startTime },
+        attributes,
+        links: options.links,
+        sampled: true,
+        kind: options.kind,
+        end() {},
+        attribute(key: string, value: unknown) {
+          attributes.set(key, value)
+        },
+        event(eventName: string, _startTime: bigint, attrs?: Record<string, unknown>) {
+          events.push({ name: eventName, attributes: attrs })
+        },
+        addLinks() {},
+      }
+    },
+  })
+
+  return {
+    tracer,
+    getEvents: (spanName: string): Array<RecordedEvent> => spanEvents.get(spanName) ?? [],
+  }
+}
+
+describe('spanEvent', () => {
+  it.effect('should emit a span event with the given message', () => {
+    const { tracer, getEvents } = makeTestTracer()
+    return Effect.gen(function* () {
+      yield* spanEvent('test-event')
+      const events = getEvents('test-span')
+      expect(events).toHaveLength(1)
+      expect(events[0]!.name).toBe('test-event')
+    }).pipe(Effect.withSpan('test-span'), Effect.withTracer(tracer))
+  })
+
+  it.effect('should emit a span event with attributes', () => {
+    const { tracer, getEvents } = makeTestTracer()
+    return Effect.gen(function* () {
+      yield* spanEvent('event-with-attrs', { key1: 'value1', key2: 42 })
+      const events = getEvents('test-span')
+      expect(events).toHaveLength(1)
+      expect(events[0]!.name).toBe('event-with-attrs')
+      expect(events[0]!.attributes).toMatchObject({ key1: 'value1', key2: 42 })
+    }).pipe(Effect.withSpan('test-span'), Effect.withTracer(tracer))
+  })
+
+  it.effect('should emit to the nearest enclosing span', () => {
+    const { tracer, getEvents } = makeTestTracer()
+    return Effect.gen(function* () {
+      yield* spanEvent('outer-event')
+
+      yield* spanEvent('inner-event').pipe(Effect.withSpan('inner-span'))
+
+      const outerEvents = getEvents('outer-span')
+      const innerEvents = getEvents('inner-span')
+
+      expect(outerEvents).toHaveLength(1)
+      expect(outerEvents[0]!.name).toBe('outer-event')
+
+      expect(innerEvents).toHaveLength(1)
+      expect(innerEvents[0]!.name).toBe('inner-event')
+    }).pipe(Effect.withSpan('outer-span'), Effect.withTracer(tracer))
+  })
+
+  it.effect('should be a no-op when no span is in context', () => spanEvent('orphan-event'))
+})

package/src/effect/spanEvent.ts

@@ -0,0 +1,17 @@
+import { Effect, Logger } from 'effect'
+
+/**
+ * Emits a span event on the current Effect span via the tracer logger.
+ *
+ * @remarks
+ *
+ * Unlike raw `otelSpan.addEvent`, this doesn't require manual span threading —
+ * it automatically targets the nearest enclosing `Effect.withSpan`. If no span
+ * is in context, the call is a no-op.
+ */
+export const spanEvent = (message: any, attributes?: Record<string, unknown>) =>
+  Effect.provideService(
+    Effect.log(message).pipe(Effect.annotateLogs(attributes ?? {})),
+    Logger.CurrentLoggers,
+    new Set([Logger.tracerLogger]),
+  )

package/src/env.ts

@@ -26,4 +26,5 @@ export const IS_CI = envTruish(env('CI'))
 
 export const IS_BUN = typeof Bun !== 'undefined'
 
-export const IS_REACT_NATIVE = typeof navigator !== 'undefined' && navigator.product === 'ReactNative'
+export const IS_REACT_NATIVE =
+  typeof navigator !== 'undefined' && (navigator as unknown as Record<string, unknown>)['product'] === 'ReactNative'

package/src/fast-deep-equal.ts

@@ -4,36 +4,36 @@
 export const deepEqual = <T>(a: T, b: T): boolean => {
   if (a === b) return true
 
-  if (a && b && typeof a === 'object' && typeof b === 'object') {
+  if (a != null && b != null && typeof a === 'object' && typeof b === 'object') {
     if (a.constructor !== b.constructor) return false
 
     let length: number
     let i: any
     let keys: any
-    if (Array.isArray(a)) {
+    if (Array.isArray(a) === true) {
       length = a.length
       // @ts-expect-error ...
       if (length !== b.length) return false
       for (i = length; i-- !== 0; )
         // @ts-expect-error ...
-        if (!deepEqual(a[i], b[i])) return false
+        if (deepEqual(a[i], b[i]) === false) return false
       return true
     }
 
     if (a instanceof Map && b instanceof Map) {
       if (a.size !== b.size) return false
-      for (i of a.entries()) if (!b.has(i[0])) return false
-      for (i of a.entries()) if (!deepEqual(i[1], b.get(i[0]))) return false
+      for (i of a.entries()) if (b.has(i[0]) === false) return false
+      for (i of a.entries()) if (deepEqual(i[1], b.get(i[0])) === false) return false
       return true
     }
 
     if (a instanceof Set && b instanceof Set) {
       if (a.size !== b.size) return false
-      for (i of a.entries()) if (!b.has(i[0])) return false
+      for (i of a.entries()) if (b.has(i[0]) === false) return false
       return true
     }
 
-    if (ArrayBuffer.isView(a) && ArrayBuffer.isView(b)) {
+    if (ArrayBuffer.isView(a) === true && ArrayBuffer.isView(b) === true) {
       // @ts-expect-error ...
       length = a.length
       // @ts-expect-error ...
@@ -53,19 +53,18 @@ export const deepEqual = <T>(a: T, b: T): boolean => {
     length = keys.length
     if (length !== Object.keys(b).length) return false
 
-    for (i = length; i-- !== 0; ) if (!Object.hasOwn(b, keys[i])) return false
+    for (i = length; i-- !== 0; ) if (Object.hasOwn(b, keys[i]) === false) return false
 
     for (i = length; i-- !== 0; ) {
       const key = keys[i]
 
       // @ts-expect-error ...
-      if (!deepEqual(a[key], b[key])) return false
+      if (deepEqual(a[key], b[key]) === false) return false
     }
 
     return true
   }
 
   // true if both NaN, false otherwise
-  // biome-ignore lint/suspicious/noSelfCompare: comparing to itself is fine here
   return a !== a && b !== b
 }

package/src/global.ts

@@ -1,6 +1,8 @@
 declare global {
   export type TODO<_Reason extends string = 'unknown'> = any
   export type UNUSED<_Reason extends string = 'unknown'> = any
-}
 
-export {}
+  interface ImportMeta {
+    main: boolean
+  }
+}

package/src/misc.ts

@@ -9,8 +9,8 @@ export const isDevEnv = () => {
     return import.meta.env.DEV
   }
 
-  // @ts-expect-error Only exists in Expo / RN
-  if (globalThis?.__DEV__) {
+  const globals = globalThis as typeof globalThis & { readonly __DEV__?: boolean | undefined }
+  if (globals.__DEV__ === true) {
     return true
   }
 
@@ -46,10 +46,18 @@ export const tryAsFunctionAndNew = <TArg, TResult>(
 export const envTruish = (env: string | undefined) =>
   env !== undefined && env.toLowerCase() !== 'false' && env.toLowerCase() !== '0'
 
-export const shouldNeverHappen = (msg?: string, ...args: any[]): never => {
+/**
+ * Logs and throws for impossible states, pausing at a breakpoint in development.
+ *
+ * @param msg - The error message to log and pass to the error.
+ * @param args - Arbitrary arguments to include in the log.
+ *
+ * @see {@link dieDebugger} for the Effect equivalent.
+ */
+export const shouldNeverHappen = (msg?: string, ...args: ReadonlyArray<unknown>): never => {
   console.error(msg, ...args)
-  if (isDevEnv()) {
-    // biome-ignore lint/suspicious/noDebugger: debugging
+  if (isDevEnv() === true) {
+    // oxlint-disable-next-line eslint(no-debugger) -- intentional breakpoint during development
     debugger
   }