@livestore/utils 0.4.0-dev.21 → 0.4.0-dev.23

package/src/effect/Debug.ts

@@ -9,6 +9,12 @@ import * as RuntimeFlags from 'effect/RuntimeFlags'
 import * as Scope from 'effect/Scope'
 import type * as Tracer from 'effect/Tracer'
 
+/**
+ * How to use:
+ * 1. Call `Debug.attachSlowDebugInstrumentation` in the root/main file of your program to ensure it is loaded as soon as possible.
+ * 2. Call `Debug.logDebug` to log the current state of the effect system.
+ */
+
 interface SpanEvent {
   readonly name: string
   readonly startTime: bigint
@@ -29,7 +35,7 @@ export type MutableSpanGraphInfo = {
 
 const graphByTraceId = new Map<string, MutableSpanGraphInfo>()
 
-function ensureSpan(traceId: string, spanId: string): [MutableSpanGraph, number] {
+const ensureSpan = (traceId: string, spanId: string): [MutableSpanGraph, number] => {
   let info = graphByTraceId.get(traceId)
   if (info === undefined) {
     info = {
@@ -50,20 +56,20 @@ function ensureSpan(traceId: string, spanId: string): [MutableSpanGraph, number]
   return [info.graph, nodeId]
 }
 
-function sortSpan(
+const sortSpan = (
   prev: Tracer.AnySpan,
   next: Tracer.AnySpan,
-): [info: Tracer.AnySpan, isUpgrade: boolean, timingUpdated: boolean] {
+): [info: Tracer.AnySpan, isUpgrade: boolean, timingUpdated: boolean] => {
   if (prev._tag === 'ExternalSpan' && next._tag === 'Span') return [next, true, true]
   if (prev._tag === 'Span' && next._tag === 'Span' && next.status._tag === 'Ended') return [next, false, true]
   return [prev, false, false]
 }
 
-function addNode(span: Tracer.AnySpan) {
+const addNode = (span: Tracer.AnySpan) => {
   const [mutableGraph, nodeId] = ensureSpan(span.traceId, span.spanId)
   Graph.updateNode(mutableGraph, nodeId, (previousInfo) => {
     const [latestInfo, upgraded] = sortSpan(previousInfo.span, span)
-    if (upgraded && latestInfo._tag === 'Span' && Option.isSome(latestInfo.parent)) {
+    if (upgraded === true && latestInfo._tag === 'Span' && Option.isSome(latestInfo.parent) === true) {
       const parentNodeId = addNode(latestInfo.parent.value)
       Graph.addEdge(mutableGraph, parentNodeId, nodeId, undefined)
     }
@@ -72,30 +78,30 @@ function addNode(span: Tracer.AnySpan) {
   return nodeId
 }
 
-function addEvent(traceId: string, spanId: string, event: SpanEvent) {
+const addEvent = (traceId: string, spanId: string, event: SpanEvent) => {
   const [mutableGraph, nodeId] = ensureSpan(traceId, spanId)
   Graph.updateNode(mutableGraph, nodeId, (previousInfo) => {
     return { ...previousInfo, events: [...previousInfo.events, event] }
   })
   return nodeId
 }
-function addNodeExit(traceId: string, spanId: string, exit: Exit.Exit<any, any>) {
+const addNodeExit = (traceId: string, spanId: string, exit: Exit.Exit<any, any>) => {
   const [mutableGraph, nodeId] = ensureSpan(traceId, spanId)
   Graph.updateNode(mutableGraph, nodeId, (previousInfo) => {
     const isInterruptedOnly = exit._tag === 'Failure' && Cause.isInterruptedOnly(exit.cause)
     return {
       ...previousInfo,
-      exitTag: isInterruptedOnly ? ('Interrupted' as const) : exit._tag,
+      exitTag: isInterruptedOnly === true ? ('Interrupted' as const) : exit._tag,
     }
   })
   return nodeId
 }
 
-function createPropertyInterceptor<T extends object, K extends keyof T>(
+const createPropertyInterceptor = <T extends object, K extends keyof T>(
   obj: T,
   property: K,
   interceptor: (value: T[K]) => void,
-): void {
+): void => {
   const descriptor = Object.getOwnPropertyDescriptor(obj, property)
 
   const previousSetter = descriptor?.set
@@ -103,19 +109,19 @@ function createPropertyInterceptor<T extends object, K extends keyof T>(
   let currentValue: T[K]
   const previousGetter = descriptor?.get
 
-  if (!previousGetter) {
+  if (previousGetter == null) {
     currentValue = obj[property]
   }
 
   Object.defineProperty(obj, property, {
     get(): T[K] {
-      if (previousGetter) {
+      if (previousGetter !== undefined) {
         return previousGetter.call(obj)
       }
       return currentValue
     },
     set(value: T[K]) {
-      if (previousSetter) {
+      if (previousSetter !== undefined) {
         previousSetter.call(obj, value)
       } else {
         currentValue = value
@@ -145,8 +151,8 @@ type GlobalWithFiberCurrent = {
 }
 
 const patchedTracer = new WeakSet<Tracer.Tracer>()
-function ensureTracerPatched(currentTracer: Tracer.Tracer) {
-  if (patchedTracer.has(currentTracer)) {
+const ensureTracerPatched = (currentTracer: Tracer.Tracer) => {
+  if (patchedTracer.has(currentTracer) === true) {
     return
   }
   patchedTracer.add(currentTracer)
@@ -175,6 +181,7 @@ function ensureTracerPatched(currentTracer: Tracer.Tracer) {
   currentTracer.context = function (f, fiber, ...args) {
     const context = oldContext.apply(this, [f, fiber, ...args])
     ensureFiberPatched(fiber)
+    // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Effect Tracer.context return type is opaque; patching requires cast
     return context as any
   }
 }
@@ -196,14 +203,16 @@ const knownScopes = new Map<
   { id: number; allocationFiber: Fiber.RuntimeFiber<any, any> | undefined; allocationSpan: Tracer.AnySpan | undefined }
 >()
 let lastScopeId = 0
-function ensureScopePatched(scope: ScopeImpl, allocationFiber: Fiber.RuntimeFiber<any, any> | undefined) {
+const ensureScopePatched = (scope: ScopeImpl, allocationFiber: Fiber.RuntimeFiber<any, any> | undefined) => {
   if (scope.state._tag === 'Closed') return
-  if (knownScopes.has(scope)) return
+  if (knownScopes.has(scope) === true) return
   const id = lastScopeId++
-  if (patchScopeClose) {
+  if (patchScopeClose === true) {
+    // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- patching Scope.close; ScopeImpl is an internal interface not exported by Effect
     const oldClose = (scope as any).close
+    // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- patching Scope.close; ScopeImpl is an internal interface not exported by Effect
     ;(scope as any).close = function (...args: any[]) {
-      return oldClose.apply(this as any, args).pipe(
+      return oldClose.apply(this, args).pipe(
         Effect.withSpan(`scope.${id}.closeRunFinalizers`),
         Effect.ensuring(
           Effect.sync(() => {
@@ -225,14 +234,15 @@ const cleanupScopes = () => {
 }
 
 const knownFibers = new Set<Fiber.RuntimeFiber<any, any>>()
-function ensureFiberPatched(fiber: Fiber.RuntimeFiber<any, any>) {
+const ensureFiberPatched = (fiber: Fiber.RuntimeFiber<any, any>) => {
   // patch tracer
   ensureTracerPatched(fiber.currentTracer)
   // patch scope
   const currentScope = Context.getOrElse(fiber.currentContext, Scope.Scope, () => undefined)
-  if (currentScope) ensureScopePatched(currentScope as any as ScopeImpl, undefined)
+  // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- casting Scope to ScopeImpl; internal Effect type not publicly exported
+  if (currentScope !== undefined) ensureScopePatched(currentScope as any as ScopeImpl, undefined)
   // patch fiber
-  if (knownFibers.has(fiber)) return
+  if (knownFibers.has(fiber) === true) return
   knownFibers.add(fiber)
   fiber.addObserver((exit) => {
     knownFibers.delete(fiber)
@@ -244,7 +254,7 @@ let patchScopeClose = false
 let onFiberResumed: undefined | ((fiber: Fiber.RuntimeFiber<any, any>) => void)
 let onFiberSuspended: undefined | ((fiber: Fiber.RuntimeFiber<any, any>) => void)
 let onFiberCompleted: undefined | ((fiber: Fiber.RuntimeFiber<any, any>, exit: Exit.Exit<any, any>) => void)
-export function attachSlowDebugInstrumentation(options: {
+export const attachSlowDebugInstrumentation = (options: {
   /** If set to true, the scope prototype will be patched to attach a span to visualize pending scope closing */
   readonly patchScopeClose?: boolean
   /** An optional callback that will be called when any fiber resumes performing a run loop */
@@ -253,9 +263,10 @@ export function attachSlowDebugInstrumentation(options: {
   readonly onFiberSuspended?: (fiber: Fiber.RuntimeFiber<any, any>) => void
   /** An optional callback that will be called when any fiber completes with a exit */
   readonly onFiberCompleted?: (fiber: Fiber.RuntimeFiber<any, any>, exit: Exit.Exit<any, any>) => void
-}) {
+}): void => {
+  // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- accessing Effect's global fiber tracking via well-known symbol keys
   const _globalThis = globalThis as any as GlobalWithFiberCurrent
-  if (_globalThis['effect/DevtoolsHook']) {
+  if (_globalThis['effect/DevtoolsHook'] !== undefined) {
     return console.error(
       'attachDebugInstrumentation has already been called! To show the tree, call attachDebugInstrumentation() in the root/main file of your program to ensure it is loaded as soon as possible.',
     )
@@ -265,10 +276,11 @@ export function attachSlowDebugInstrumentation(options: {
   onFiberSuspended = options.onFiberSuspended
   onFiberCompleted = options.onFiberCompleted
   let lastFiber: undefined | Fiber.RuntimeFiber<any, any>
+  // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- accessing Effect's global fiber tracking via well-known symbol keys
   createPropertyInterceptor(globalThis as any as GlobalWithFiberCurrent, 'effect/FiberCurrent', (value) => {
-    if (value && knownFibers.has(value)) onFiberResumed?.(value)
-    if (value) ensureFiberPatched(value)
-    if (!value && lastFiber && knownFibers.has(lastFiber)) onFiberSuspended?.(lastFiber)
+    if (value !== undefined && knownFibers.has(value) === true) onFiberResumed?.(value)
+    if (value !== undefined) ensureFiberPatched(value)
+    if (value == null && lastFiber !== undefined && knownFibers.has(lastFiber) === true) onFiberSuspended?.(lastFiber)
     lastFiber = value
   })
   _globalThis['effect/DevtoolsHook'] = {
@@ -276,6 +288,7 @@ export function attachSlowDebugInstrumentation(options: {
       console.log('onEvent', event)
       switch (event._tag) {
         case 'ScopeAllocated':
+          // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- casting Scope to ScopeImpl; internal Effect type not publicly exported
           ensureScopePatched(event.scope as any as ScopeImpl, _globalThis['effect/FiberCurrent'])
           break
         case 'FiberAllocated':
@@ -286,7 +299,7 @@ export function attachSlowDebugInstrumentation(options: {
   }
 }
 
-function formatDuration(startTime: bigint, endTime: bigint | undefined): string {
+const formatDuration = (startTime: bigint, endTime: bigint | undefined): string => {
   if (endTime === undefined) return '[running]'
   const durationMs = Number(endTime - startTime) / 1000000 // Convert nanoseconds to milliseconds
   if (durationMs < 1000) return `${durationMs.toFixed(0)}ms`
@@ -294,12 +307,12 @@ function formatDuration(startTime: bigint, endTime: bigint | undefined): string
   return `${(durationMs / 60000).toFixed(2)}m`
 }
 
-function getSpanName(span: Tracer.AnySpan): string {
+const getSpanName = (span: Tracer.AnySpan): string => {
   if (span._tag === 'ExternalSpan') return `[external] ${span.spanId}`
   return span.name
 }
 
-function getSpanStatus(info: GraphNodeInfo): string {
+const getSpanStatus = (info: GraphNodeInfo): string => {
   if (info.span._tag === 'ExternalSpan') return '?'
   if (info.exitTag === 'Success') return '✓'
   if (info.exitTag === 'Failure') return '✗'
@@ -307,16 +320,16 @@ function getSpanStatus(info: GraphNodeInfo): string {
   return '⋮'
 }
 
-function getSpanDuration(span: Tracer.AnySpan): string {
+const getSpanDuration = (span: Tracer.AnySpan): string => {
   if (span._tag === 'ExternalSpan') return ''
   const endTime = span.status._tag === 'Ended' ? span.status.endTime : undefined
   return formatDuration(span.status.startTime, endTime)
 }
 
-function filterGraphKeepAncestors<N, E>(
+const filterGraphKeepAncestors = <N, E>(
   graph: Graph.Graph<N, E>,
   predicate: (nodeData: N, nodeId: number) => boolean,
-): Graph.Graph<N, E> {
+): Graph.Graph<N, E> => {
   // Find all root nodes (nodes with no incoming edges)
   const rootNodes = Array.from(Graph.indices(Graph.externals(graph, { direction: 'incoming' })))
   const shouldInclude = new Set<number>()
@@ -324,35 +337,35 @@ function filterGraphKeepAncestors<N, E>(
   // Use postorder DFS to evaluate children before parents
   for (const nodeId of Graph.indices(Graph.dfsPostOrder(graph, { start: rootNodes, direction: 'outgoing' }))) {
     const node = Graph.getNode(graph, nodeId)
-    if (Option.isNone(node)) continue
+    if (Option.isNone(node) === true) continue
 
     const matchesPredicate = predicate(node.value, nodeId)
-    if (matchesPredicate) {
+    if (matchesPredicate === true) {
       shouldInclude.add(nodeId)
     } else {
       const children = Graph.neighborsDirected(graph, nodeId, 'outgoing')
       const hasMatchingChildren = children.some((childId) => shouldInclude.has(childId))
-      if (hasMatchingChildren) shouldInclude.add(nodeId)
+      if (hasMatchingChildren === true) shouldInclude.add(nodeId)
     }
   }
 
   // Create a filtered copy of the graph
   return Graph.mutate(graph, (mutable) => {
     for (const [nodeId] of mutable.nodes) {
-      if (shouldInclude.has(nodeId)) continue
+      if (shouldInclude.has(nodeId) === true) continue
       Graph.removeNode(mutable, nodeId)
     }
   })
 }
 
-function renderSpanNode(graph: Graph.Graph<GraphNodeInfo, void, 'directed'>, nodeId: number): string[] {
+const renderSpanNode = (graph: Graph.Graph<GraphNodeInfo, void>, nodeId: number): string[] => {
   const node = Graph.getNode(graph, nodeId)
-  if (Option.isNone(node)) return []
+  if (Option.isNone(node) === true) return []
   const info = node.value
   const status = getSpanStatus(info)
   const name = getSpanName(info.span)
   const duration = getSpanDuration(info.span)
-  const durationStr = duration ? ` ${duration}` : ''
+  const durationStr = duration !== undefined ? ` ${duration}` : ''
 
   const fiberIds = Array.from(knownFibers)
     .filter(
@@ -365,11 +378,11 @@ function renderSpanNode(graph: Graph.Graph<GraphNodeInfo, void, 'directed'>, nod
   return [` ${status} ${name}${durationStr}${runningOnFibers}`]
 }
 
-function renderTree<N, E, T extends Graph.Kind>(
+const renderTree = <N, E, T extends Graph.Kind>(
   graph: Graph.Graph<N, E, T>,
   nodeIds: Array<number>,
   renderNode: (graph: Graph.Graph<N, E, T>, nodeId: number) => string[],
-): string[] {
+): string[] => {
   let lines: string[] = []
   for (let childIndex = 0; childIndex < nodeIds.length; childIndex++) {
     const isLastChild = childIndex === nodeIds.length - 1
@@ -380,9 +393,9 @@ function renderTree<N, E, T extends Graph.Kind>(
       ...lines,
       ...childLines.map((l, lineIndex) => {
         if (lineIndex === 0) {
-          return (isLastChild ? ' └─' : ' ├─') + l
+          return (isLastChild === true ? ' └─' : ' ├─') + l
         }
-        return (isLastChild ? '  ' : ' │') + l
+        return (isLastChild === true ? '  ' : ' │') + l
       }),
     ]
   }
@@ -396,8 +409,9 @@ export interface LogDebugOptions {
 }
 
 export const logDebug = (options: LogDebugOptions = {}) => {
+  // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- accessing Effect's global fiber tracking via well-known symbol keys
   const _globalThis = globalThis as any as GlobalWithFiberCurrent
-  if (!_globalThis['effect/DevtoolsHook']) {
+  if (_globalThis['effect/DevtoolsHook'] == null) {
     return console.error(
       'attachDebugInstrumentation has not been called! To show the tree, call attachDebugInstrumentation() in the root/main file of your program to ensure it is loaded as soon as possible.',
     )
@@ -408,8 +422,9 @@ export const logDebug = (options: LogDebugOptions = {}) => {
   // fibers
   lines = [...lines, 'Active Fibers:']
   for (const fiber of knownFibers) {
+    // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- accessing fiber.currentRuntimeFlags; internal Effect runtime property
     const interruptible = RuntimeFlags.interruptible((fiber as any).currentRuntimeFlags)
-    lines = [...lines, `- #${fiber.id().id}${!interruptible ? ' [uninterruptible]' : ''}`]
+    lines = [...lines, `- #${fiber.id().id}${interruptible === false ? ' [uninterruptible]' : ''}`]
   }
   if (knownFibers.size === 0) {
     lines = [...lines, '- No active effect fibers']
@@ -419,12 +434,13 @@ export const logDebug = (options: LogDebugOptions = {}) => {
   // spans
   for (const [traceId, info] of graphByTraceId) {
     const graph = Graph.endMutation(info.graph)
-    const filteredGraph = options.regex
-      ? filterGraphKeepAncestors(graph, (nodeData, _nodeId) => {
-          const name = getSpanName(nodeData.span)
-          return options.regex!.test(name)
-        })
-      : graph
+    const filteredGraph =
+      options.regex !== undefined
+        ? filterGraphKeepAncestors(graph, (nodeData, _nodeId) => {
+            const name = getSpanName(nodeData.span)
+            return options.regex!.test(name)
+          })
+        : graph
     const filteredRootNodes = Array.from(Graph.indices(Graph.externals(filteredGraph, { direction: 'incoming' })))
 
     lines = [...lines, `Spans Trace ${traceId}:`, ...renderTree(filteredGraph, filteredRootNodes, renderSpanNode)]
@@ -439,8 +455,10 @@ export const logDebug = (options: LogDebugOptions = {}) => {
       .map((fiber) => `#${fiber.id().id}`)
       .join(', ')
     const usedByFibers = fiberIds.length > 0 ? ` [used by: ${fiberIds}]` : ''
-    const allocationFiber = info.allocationFiber ? ` [allocated in fiber #${info.allocationFiber.id().id}]` : ''
-    const allocationSpan = info.allocationSpan ? ` [allocated in span: ${getSpanName(info.allocationSpan)}]` : ''
+    const allocationFiber =
+      info.allocationFiber !== undefined ? ` [allocated in fiber #${info.allocationFiber.id().id}]` : ''
+    const allocationSpan =
+      info.allocationSpan !== undefined ? ` [allocated in span: ${getSpanName(info.allocationSpan)}]` : ''
     lines = [...lines, `- #${info.id}${usedByFibers}${allocationFiber}${allocationSpan}`]
   }
   if (knownScopes.size === 0) {

package/src/effect/Effect.ts

@@ -6,9 +6,6 @@ import {
   Duration,
   Effect,
   Fiber,
-  FiberRef,
-  HashSet,
-  Logger,
   pipe,
   Scope,
   type Stream,
@@ -18,10 +15,11 @@ import { log } from 'effect/Console'
 import { dual, type LazyArg } from 'effect/Function'
 import type { Predicate, Refinement } from 'effect/Predicate'
 
-import { isPromise } from '../mod.ts'
+import { isDevEnv, isPromise, objectToString } from '../mod.ts'
 import { UnknownError } from './Error.ts'
 
 export * from 'effect/Effect'
+export { spanEvent } from './spanEvent.ts'
 
 // export const log = <A>(message: A, ...rest: any[]): Effect.Effect<void> =>
 //   Effect.sync(() => {
@@ -57,16 +55,16 @@ export type SyncOrPromiseOrEffect<TResult, TError = never, TContext = never> =
 
 export const tryAll = <Res>(
   fn: () => Res,
-): Res extends Effect.Effect<infer A, infer E, never>
-  ? Effect.Effect<A, E | UnknownException, never>
+): Res extends Effect.Effect<infer A, infer E>
+  ? Effect.Effect<A, E | UnknownException>
   : Res extends Promise<infer A>
-    ? Effect.Effect<A, UnknownException, never>
-    : Effect.Effect<Res, UnknownException, never> =>
+    ? Effect.Effect<A, UnknownException>
+    : Effect.Effect<Res, UnknownException> =>
   Effect.try(() => fn()).pipe(
     Effect.andThen((fnRes) =>
-      Effect.isEffect(fnRes)
+      Effect.isEffect(fnRes) === true
         ? (fnRes as any as Effect.Effect<any>)
-        : isPromise(fnRes)
+        : isPromise(fnRes) === true
           ? Effect.promise(() => fnRes)
           : Effect.succeed(fnRes),
     ),
@@ -89,7 +87,7 @@ export const logBefore =
 export const tapCauseLogPretty = <R, E, A>(eff: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
   Effect.tapErrorCause(eff, (cause) =>
     Effect.gen(function* () {
-      if (Cause.isInterruptedOnly(cause)) {
+      if (Cause.isInterruptedOnly(cause) === true) {
         // console.log('interrupted', Cause.pretty(err), err)
         return
       }
@@ -107,6 +105,47 @@ export const tapCauseLogPretty = <R, E, A>(eff: Effect.Effect<A, E, R>): Effect.
     }),
   )
 
+/**
+ * Creates a defect, pausing at a breakpoint in development.
+ *
+ * @param msg - The error message to include in the defect.
+ * @param args - Arbitrary arguments available for inspection during debugging.
+ *
+ * @see {@link shouldNeverHappen} for the non-Effect equivalent that throws synchronously.
+ * @see {@link orDieDebugger}
+ */
+export const dieDebugger = (msg: string, ...args: ReadonlyArray<unknown>): Effect.Effect<never> =>
+  Effect.suspend(() => {
+    if (isDevEnv() === true) {
+      // oxlint-disable-next-line eslint(no-debugger) -- intentional breakpoint during development
+      debugger
+      void args // Keeps the variable in scope so it's inspectable when the debugger pauses
+    }
+    return Effect.dieMessage(msg)
+  })
+
+/**
+ * Converts a failure into a defect, pausing at a breakpoint in development.
+ *
+ * @param self - The effect on which to apply the operation.
+ *
+ * @see {@link Effect.orDie}
+ * @see {@link dieDebugger}
+ */
+export const orDieDebugger = <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, never, R> =>
+  Effect.matchEffect(self, {
+    onFailure: (error) =>
+      // Keep the debugger hook so that `debugger` runs only when the wrapped effect actually fails, not while building the wrapper.
+      Effect.dieSync(() => {
+        if (isDevEnv() === true) {
+          // oxlint-disable-next-line eslint(no-debugger) -- intentional breakpoint for impossible states during development
+          debugger
+        }
+        return error
+      }),
+    onSuccess: Effect.succeed,
+  })
+
 export const ignoreIf: {
   <E, EB extends E>(
     refinement: Refinement<NoInfer<E>, EB>,
@@ -124,11 +163,11 @@ export const ignoreIf: {
 export const eventListener = <TEvent = unknown>(
   target: Stream.EventListener<TEvent>,
   type: string,
-  handler: (event: TEvent) => Effect.Effect<void, never, never>,
+  handler: (event: TEvent) => Effect.Effect<void>,
   options?: { once?: boolean },
 ) =>
   Effect.gen(function* () {
-    const runtime = yield* Effect.runtime<never>()
+    const runtime = yield* Effect.runtime()
 
     const handlerFn = (event: TEvent) => handler(event).pipe(Effect.provide(runtime), Effect.runFork)
 
@@ -137,16 +176,11 @@ export const eventListener = <TEvent = unknown>(
     yield* Effect.addFinalizer(() => Effect.sync(() => target.removeEventListener(type, handlerFn)))
   })
 
-export const spanEvent = (message: any, attributes?: Record<string, any>) =>
-  Effect.locallyWith(Effect.log(message).pipe(Effect.annotateLogs(attributes ?? {})), FiberRef.currentLoggers, () =>
-    HashSet.make(Logger.tracerLogger),
-  )
-
 export const logWarnIfTakesLongerThan =
   ({ label, duration }: { label: string; duration: Duration.DurationInput }) =>
   <R, E, A>(eff: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
     Effect.gen(function* () {
-      const runtime = yield* Effect.runtime<never>()
+      const runtime = yield* Effect.runtime()
 
       let tookLongerThanTimer = false
 
@@ -154,7 +188,7 @@ export const logWarnIfTakesLongerThan =
         Effect.tap(() => {
           tookLongerThanTimer = true
           // TODO include span info
-          return Effect.logWarning(`${label}: Took longer than ${duration}ms`)
+          return Effect.logWarning(`${label}: Took longer than ${objectToString(duration)}ms`)
         }),
         Effect.provide(runtime),
         Effect.runFork,
@@ -169,13 +203,14 @@ export const logWarnIfTakesLongerThan =
 
             yield* Fiber.interrupt(timeoutFiber)
 
-            if (tookLongerThanTimer) {
+            if (tookLongerThanTimer === true) {
               yield* Effect.logWarning(`${label}: Interrupted after ${end - start}ms`)
             }
           }),
         ),
       )
 
+      // eslint-disable-next-line overeng/explicit-boolean-compare -- mutated in forked fiber; TS can't see the mutation
       if (tookLongerThanTimer) {
         const end = Date.now()
         yield* Effect.logWarning(`${label}: Actual duration: ${end - start}ms`)
@@ -208,19 +243,61 @@ export const debugLogEnv = (msg?: string): Effect.Effect<Context.Context<never>>
     Effect.tap((env) => log(msg ?? 'debugLogEnv', env)),
   )
 
-export const timeoutDie =
-  <E1>(options: { onTimeout: LazyArg<E1>; duration: Duration.DurationInput }) =>
-  <R, E, A>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
-    Effect.orDie(Effect.timeoutFail(options)(self))
-
-export const timeoutDieMsg =
-  (options: { error: string; duration: Duration.DurationInput }) =>
-  <R, E, A>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
-    Effect.orDie(
-      Effect.timeoutFail({ onTimeout: () => new UnknownError({ cause: options.error }), duration: options.duration })(
-        self,
-      ),
-    )
+/**
+ * Enforces a time limit on an effect, triggering a defect on timeout.
+ *
+ * @remarks
+ *
+ * This function allows you to enforce a time limit on the execution of an
+ * effect. If the effect does not complete within the given duration, it dies
+ * with a {@link Cause.TimeoutException} as an unchecked defect. Unlike
+ * {@link Effect.timeout}, which adds `TimeoutException` to the error channel,
+ * this function keeps the error channel unchanged by treating the timeout as
+ * a defect.
+ *
+ * The returned effect will either:
+ * - Succeed with the original effect's result if it completes within the
+ *   specified duration.
+ * - Die with a {@link Cause.TimeoutException} defect if the time limit is exceeded.
+ *
+ * @see {@link timeoutOrDieMessage} for a version with a custom message.
+ * @see {@link Effect.timeout} for a version that raises a `TimeoutException` as a typed error.
+ * @see {@link Effect.timeoutFailCause} for a version that raises a custom defect.
+ */
+export const timeoutOrDie = (duration: Duration.DurationInput) =>
+  <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+    Effect.timeoutFailCause(self, {
+      duration,
+      onTimeout: () => Cause.die(new Cause.TimeoutException())
+    })
+
+/**
+ * Enforces a time limit on an effect, triggering a defect with a custom
+ * message on timeout.
+ *
+ * @remarks
+ *
+ * This function behaves like {@link timeoutOrDie}, but allows you to provide
+ * a custom message for the {@link Cause.TimeoutException} defect. This is useful
+ * for adding context about which operation timed out, making it easier to
+ * diagnose issues in logs or error reports.
+ *
+ * The returned effect will either:
+ * - Succeed with the original effect's result if it completes within the
+ *   specified duration.
+ * - Die with a {@link Cause.TimeoutException} defect containing the provided
+ *   message if the time limit is exceeded.
+ *
+ * @see {@link timeoutOrDie} for a version without a custom message.
+ * @see {@link Effect.timeout} for a version that raises a `TimeoutException` as a typed error.
+ * @see {@link Effect.timeoutFailCause} for a version that raises a custom defect.
+ */
+export const timeoutOrDieMessage = (duration: Duration.DurationInput, message: string) =>
+  <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+    Effect.timeoutFailCause(self, {
+      duration,
+      onTimeout: () => Cause.die(new Cause.TimeoutException(message))
+    })
 
 export const toForkedDeferred = <R, E, A>(
   eff: Effect.Effect<A, E, R>,
@@ -274,7 +351,12 @@ const getSpanTrace = () => {
 
 const logSpanTrace = () => console.log(getSpanTrace())
 
-// @ts-expect-error TODO fix types
+declare global {
+  /** Debug helper: returns the current Effect span trace */
+  var getSpanTrace: () => string
+  /** Debug helper: logs the current Effect span trace */
+  var logSpanTrace: () => void
+}
+
 globalThis.getSpanTrace = getSpanTrace
-// @ts-expect-error TODO fix types
 globalThis.logSpanTrace = logSpanTrace

package/src/effect/Error.ts

@@ -1,6 +1,6 @@
 import { Schema } from 'effect'
 
-export class UnknownError extends Schema.TaggedError<UnknownError>()('UnknownError', {
+export class UnknownError extends Schema.TaggedError<UnknownError>('~@livestore/utils/UnknownError')('UnknownError', {
   cause: Schema.Any,
   payload: Schema.optional(Schema.Any),
 }) {}

package/src/effect/Logger.ts

@@ -23,7 +23,7 @@ export const consoleLogger = (threadName: string) =>
     const consoleFn =
       logLevel === LogLevel.Debug
         ? // Cloudflare Workers doesn't support console.debug 🤷
-          isCloudflareWorker
+          isCloudflareWorker === true
           ? console.log
           : console.debug
         : logLevel === LogLevel.Info
@@ -34,7 +34,7 @@ export const consoleLogger = (threadName: string) =>
 
     const annotationsObj = Object.fromEntries(HashMap.entries(annotations))
 
-    const messages = Array.isArray(message) ? message : [message]
+    const messages = Array.isArray(message) === true ? message : [message]
     if (Cause.isEmpty(cause) === false) {
       messages.push(Cause.pretty(cause, { renderErrorCause: true }))
     }