@livestore/utils 0.4.0 → 0.5.0-dev.0

package/src/effect/Debug.ts

@@ -1,13 +1,4 @@
-import * as Cause from 'effect/Cause'
-import * as Context from 'effect/Context'
-import * as Effect from 'effect/Effect'
-import type * as Exit from 'effect/Exit'
-import type * as Fiber from 'effect/Fiber'
-import * as Graph from 'effect/Graph'
-import * as Option from 'effect/Option'
-import * as RuntimeFlags from 'effect/RuntimeFlags'
-import * as Scope from 'effect/Scope'
-import type * as Tracer from 'effect/Tracer'
+import { Cause, Context, Effect, type Exit, type Fiber, Graph, Option, Scope, Tracer } from 'effect'
 
 /**
  * How to use:
@@ -47,7 +38,7 @@ const ensureSpan = (traceId: string, spanId: string): [MutableSpanGraph, number]
   let nodeId = info.nodeIdBySpanId.get(spanId)
   if (nodeId === undefined) {
     nodeId = Graph.addNode(info.graph, {
-      span: { _tag: 'ExternalSpan', spanId, traceId, sampled: false, context: Context.empty() },
+      span: { _tag: 'ExternalSpan', spanId, traceId, sampled: false, annotations: Context.empty() },
       events: [],
       exitTag: undefined,
     })
@@ -88,7 +79,7 @@ const addEvent = (traceId: string, spanId: string, event: SpanEvent) => {
 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)
+    const isInterruptedOnly = exit._tag === 'Failure' && Cause.hasInterruptsOnly(exit.cause)
     return {
       ...previousInfo,
       exitTag: isInterruptedOnly === true ? ('Interrupted' as const) : exit._tag,
@@ -136,7 +127,7 @@ const createPropertyInterceptor = <T extends object, K extends keyof T>(
 type EffectDevtoolsHookEvent =
   | {
       _tag: 'FiberAllocated'
-      fiber: Fiber.RuntimeFiber<any, any>
+      fiber: Fiber.Fiber<any, any>
     }
   | {
       _tag: 'ScopeAllocated'
@@ -144,45 +135,62 @@ type EffectDevtoolsHookEvent =
     }
 
 type GlobalWithFiberCurrent = {
-  'effect/FiberCurrent': Fiber.RuntimeFiber<any, any> | undefined
+  ['~effect/Fiber/currentFiber']: Fiber.Fiber<any, any> | undefined
   'effect/DevtoolsHook'?: {
     onEvent: (event: EffectDevtoolsHookEvent) => void
   }
 }
 
+type MutableTracer = {
+  span: Tracer.Tracer['span']
+  context?: Tracer.Tracer['context']
+}
+
+type EvaluatablePrimitive<X> = Tracer.EffectPrimitive<X> & {
+  readonly ['~effect/Effect/evaluate']: (fiber: Fiber.Fiber<any, any>) => X
+}
+
 const patchedTracer = new WeakSet<Tracer.Tracer>()
-const ensureTracerPatched = (currentTracer: Tracer.Tracer) => {
-  if (patchedTracer.has(currentTracer) === true) {
+const ensureTracerPatched = (tracer: Tracer.Tracer) => {
+  if (patchedTracer.has(tracer) === true) {
     return
   }
-  patchedTracer.add(currentTracer)
+  patchedTracer.add(tracer)
+
+  // Effect v4 exposes the tracer context as readonly and caches it on fibers, so keep mutation localized here.
+  const mutableTracer = tracer as MutableTracer
 
-  const oldSpanConstructor = currentTracer.span
-  currentTracer.span = function (...args) {
-    const span = oldSpanConstructor.apply(this, args)
+  const oldSpanConstructor: Tracer.Tracer['span'] = tracer.span
+  mutableTracer.span = function (this: Tracer.Tracer, options: Parameters<Tracer.Tracer['span']>[0]): Tracer.Span {
+    const span = oldSpanConstructor.call(this, options)
     addNode(span)
 
     const oldSpanEnd = span.end
-    span.end = function (endTime, exit, ...args) {
-      oldSpanEnd.apply(this, [endTime, exit, ...args])
+    span.end = function (this: Tracer.Span, endTime, exit) {
+      oldSpanEnd.call(this, endTime, exit)
       addNodeExit(this.traceId, this.spanId, exit)
     }
 
     const oldSpanEvent = span.event
-    span.event = function (name, startTime, attributes, ...args) {
-      oldSpanEvent.apply(this, [name, startTime, attributes, ...args])
+    span.event = function (this: Tracer.Span, name, startTime, attributes) {
+      oldSpanEvent.call(this, name, startTime, attributes)
       addEvent(this.traceId, this.spanId, { name, startTime, attributes: attributes ?? {} })
     }
 
     return span
   }
 
-  const oldContext = currentTracer.context
-  currentTracer.context = function (f, fiber, ...args) {
-    const context = oldContext.apply(this, [f, fiber, ...args])
+  const oldContext = tracer.context
+  mutableTracer.context = function <X>(
+    this: Tracer.Tracer,
+    primitive: Tracer.EffectPrimitive<X>,
+    fiber: Fiber.Fiber<any, any>,
+  ) {
     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
+    if (oldContext !== undefined) {
+      return oldContext(primitive, fiber)
+    }
+    return (primitive as EvaluatablePrimitive<X>)['~effect/Effect/evaluate'](fiber)
   }
 }
 
@@ -190,7 +198,7 @@ interface ScopeImpl extends Scope.Scope {
   readonly state:
     | {
         readonly _tag: 'Open'
-        readonly finalizers: Map<{}, Scope.Scope.Finalizer>
+        readonly finalizers: Map<{}, (exit: Exit.Exit<unknown, unknown>) => Effect.Effect<unknown>>
       }
     | {
         readonly _tag: 'Closed'
@@ -200,10 +208,10 @@ interface ScopeImpl extends Scope.Scope {
 
 const knownScopes = new Map<
   ScopeImpl,
-  { id: number; allocationFiber: Fiber.RuntimeFiber<any, any> | undefined; allocationSpan: Tracer.AnySpan | undefined }
+  { id: number; allocationFiber: Fiber.Fiber<any, any> | undefined; allocationSpan: Tracer.AnySpan | undefined }
 >()
 let lastScopeId = 0
-const ensureScopePatched = (scope: ScopeImpl, allocationFiber: Fiber.RuntimeFiber<any, any> | undefined) => {
+const ensureScopePatched = (scope: ScopeImpl, allocationFiber: Fiber.Fiber<any, any> | undefined) => {
   if (scope.state._tag === 'Closed') return
   if (knownScopes.has(scope) === true) return
   const id = lastScopeId++
@@ -233,12 +241,12 @@ const cleanupScopes = () => {
   }
 }
 
-const knownFibers = new Set<Fiber.RuntimeFiber<any, any>>()
-const ensureFiberPatched = (fiber: Fiber.RuntimeFiber<any, any>) => {
+const knownFibers = new Set<Fiber.Fiber<any, any>>()
+const ensureFiberPatched = (fiber: Fiber.Fiber<any, any>) => {
   // patch tracer
-  ensureTracerPatched(fiber.currentTracer)
+  ensureTracerPatched(fiber.getRef(Tracer.Tracer))
   // patch scope
-  const currentScope = Context.getOrElse(fiber.currentContext, Scope.Scope, () => undefined)
+  const currentScope = Context.getOrElse(fiber.context, Scope.Scope, () => 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
@@ -251,18 +259,18 @@ const ensureFiberPatched = (fiber: Fiber.RuntimeFiber<any, any>) => {
 }
 
 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)
+let onFiberResumed: undefined | ((fiber: Fiber.Fiber<any, any>) => void)
+let onFiberSuspended: undefined | ((fiber: Fiber.Fiber<any, any>) => void)
+let onFiberCompleted: undefined | ((fiber: Fiber.Fiber<any, any>, exit: Exit.Exit<any, any>) => void)
 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 */
-  readonly onFiberResumed?: (fiber: Fiber.RuntimeFiber<any, any>) => void
+  readonly onFiberResumed?: (fiber: Fiber.Fiber<any, any>) => void
   /** An optional callback that will be called when any fiber stops performing a run loop */
-  readonly onFiberSuspended?: (fiber: Fiber.RuntimeFiber<any, any>) => void
+  readonly onFiberSuspended?: (fiber: Fiber.Fiber<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
+  readonly onFiberCompleted?: (fiber: Fiber.Fiber<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
@@ -275,9 +283,9 @@ export const attachSlowDebugInstrumentation = (options: {
   onFiberResumed = options.onFiberResumed
   onFiberSuspended = options.onFiberSuspended
   onFiberCompleted = options.onFiberCompleted
-  let lastFiber: undefined | Fiber.RuntimeFiber<any, any>
+  let lastFiber: undefined | Fiber.Fiber<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) => {
+  createPropertyInterceptor(globalThis as any as GlobalWithFiberCurrent, '~effect/Fiber/currentFiber', (value) => {
     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)
@@ -289,7 +297,7 @@ export const attachSlowDebugInstrumentation = (options: {
       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'])
+          ensureScopePatched(event.scope as any as ScopeImpl, _globalThis['~effect/Fiber/currentFiber'])
           break
         case 'FiberAllocated':
           ensureFiberPatched(event.fiber)
@@ -327,9 +335,9 @@ const getSpanDuration = (span: Tracer.AnySpan): string => {
 }
 
 const filterGraphKeepAncestors = <N, E>(
-  graph: Graph.Graph<N, E>,
+  graph: Graph.Graph<N, E, 'directed'>,
   predicate: (nodeData: N, nodeId: number) => boolean,
-): Graph.Graph<N, E> => {
+): Graph.Graph<N, E, 'directed'> => {
   // 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>()
@@ -351,14 +359,15 @@ const filterGraphKeepAncestors = <N, E>(
 
   // Create a filtered copy of the graph
   return Graph.mutate(graph, (mutable) => {
-    for (const [nodeId] of mutable.nodes) {
+    const nodeIds = Array.from(Graph.indices(Graph.nodes(mutable)))
+    for (const nodeId of nodeIds) {
       if (shouldInclude.has(nodeId) === true) continue
       Graph.removeNode(mutable, nodeId)
     }
   })
 }
 
-const renderSpanNode = (graph: Graph.Graph<GraphNodeInfo, void>, nodeId: number): string[] => {
+const renderSpanNode = (graph: Graph.Graph<GraphNodeInfo, void, 'directed'>, nodeId: number): string[] => {
   const node = Graph.getNode(graph, nodeId)
   if (Option.isNone(node) === true) return []
   const info = node.value
@@ -371,17 +380,17 @@ const renderSpanNode = (graph: Graph.Graph<GraphNodeInfo, void>, nodeId: number)
     .filter(
       (fiber) => fiber.currentSpan?.spanId === info.span.spanId && fiber.currentSpan?.traceId === info.span.traceId,
     )
-    .map((fiber) => `#${fiber.id().id}`)
+    .map((fiber) => `#${fiber.id}`)
     .join(', ')
   const runningOnFibers = fiberIds.length > 0 ? ` [fibers ${fiberIds}]` : ''
 
   return [` ${status} ${name}${durationStr}${runningOnFibers}`]
 }
 
-const renderTree = <N, E, T extends Graph.Kind>(
-  graph: Graph.Graph<N, E, T>,
+const renderTree = <N, E>(
+  graph: Graph.Graph<N, E, 'directed'>,
   nodeIds: Array<number>,
-  renderNode: (graph: Graph.Graph<N, E, T>, nodeId: number) => string[],
+  renderNode: (graph: Graph.Graph<N, E, 'directed'>, nodeId: number) => string[],
 ): string[] => {
   let lines: string[] = []
   for (let childIndex = 0; childIndex < nodeIds.length; childIndex++) {
@@ -422,9 +431,7 @@ 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 === false ? ' [uninterruptible]' : ''}`]
+    lines = [...lines, `- #${fiber.id}`]
   }
   if (knownFibers.size === 0) {
     lines = [...lines, '- No active effect fibers']
@@ -451,12 +458,12 @@ export const logDebug = (options: LogDebugOptions = {}) => {
   lines = [...lines, 'Open Scopes:']
   for (const [scope, info] of knownScopes) {
     const fiberIds = Array.from(knownFibers)
-      .filter((fiber) => Context.getOrElse(fiber.currentContext, Scope.Scope, () => undefined) === scope)
-      .map((fiber) => `#${fiber.id().id}`)
+      .filter((fiber) => Context.getOrElse(fiber.context, Scope.Scope, () => undefined) === scope)
+      .map((fiber) => `#${fiber.id}`)
       .join(', ')
     const usedByFibers = fiberIds.length > 0 ? ` [used by: ${fiberIds}]` : ''
     const allocationFiber =
-      info.allocationFiber !== undefined ? ` [allocated in fiber #${info.allocationFiber.id().id}]` : ''
+      info.allocationFiber !== undefined ? ` [allocated in fiber #${info.allocationFiber.id}]` : ''
     const allocationSpan =
       info.allocationSpan !== undefined ? ` [allocated in span: ${getSpanName(info.allocationSpan)}]` : ''
     lines = [...lines, `- #${info.id}${usedByFibers}${allocationFiber}${allocationSpan}`]

package/src/effect/Effect.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, expectTypeOf, it } from '@effect/vitest'
+import { Cause, Effect } from 'effect'
+
+import { trySyncOrPromiseOrEffect } from './Effect.ts'
+
+interface RequiredService {
+  readonly RequiredService: unique symbol
+}
+
+declare const contextualEffect: Effect.Effect<number, 'effect-error', RequiredService>
+
+describe('trySyncOrPromiseOrEffect', () => {
+  it.effect('returns a plain value', () =>
+    Effect.gen(function* () {
+      const result = yield* trySyncOrPromiseOrEffect(() => 42 as const)
+
+      expect(result).toBe(42)
+    }),
+  )
+
+  it.effect('evaluates the operation lazily for each execution', () =>
+    Effect.gen(function* () {
+      let executions = 0
+      const effect = trySyncOrPromiseOrEffect(() => ++executions)
+
+      expect(executions).toBe(0)
+      expect(yield* effect).toBe(1)
+      expect(yield* effect).toBe(2)
+    }),
+  )
+
+  it.effect('maps a synchronous throw to an UnknownError', () =>
+    Effect.gen(function* () {
+      const thrown = new Error('thrown')
+      const failure = yield* trySyncOrPromiseOrEffect(() => {
+        throw thrown
+      }).pipe(Effect.flip)
+
+      expect(failure).toBeInstanceOf(Cause.UnknownError)
+      if (failure instanceof Cause.UnknownError) {
+        expect(failure.cause).toBe(thrown)
+      }
+    }),
+  )
+
+  it.effect('awaits a resolving Promise', () =>
+    Effect.gen(function* () {
+      const result = yield* trySyncOrPromiseOrEffect(() => Promise.resolve('resolved'))
+
+      expect(result).toBe('resolved')
+    }),
+  )
+
+  it.effect('maps a rejected Promise to an UnknownError', () =>
+    Effect.gen(function* () {
+      const rejected = new Error('rejected')
+      const failure = yield* trySyncOrPromiseOrEffect(() => Promise.reject(rejected)).pipe(Effect.flip)
+
+      expect(failure).toBeInstanceOf(Cause.UnknownError)
+      if (failure instanceof Cause.UnknownError) {
+        expect(failure.cause).toBe(rejected)
+      }
+    }),
+  )
+
+  it.effect('maps a throwing Promise-like then getter to an UnknownError', () =>
+    Effect.gen(function* () {
+      const thrown = new Error('throwing then getter')
+      const thenable = {
+        // oxlint-disable-next-line eslint-plugin-unicorn(no-thenable) -- intentionally exercises Promise-like classification
+        get then(): PromiseLike<never>['then'] {
+          throw thrown
+        },
+      } satisfies PromiseLike<never>
+
+      const failure = yield* trySyncOrPromiseOrEffect(() => thenable).pipe(Effect.flip)
+
+      expect(failure).toBeInstanceOf(Cause.UnknownError)
+      if (failure instanceof Cause.UnknownError) {
+        expect(failure.cause).toBe(thrown)
+      }
+    }),
+  )
+
+  it.effect('executes and returns the value of a returned Effect', () =>
+    Effect.gen(function* () {
+      const result = yield* trySyncOrPromiseOrEffect(() => Effect.succeed('effect-value'))
+
+      expect(result).toBe('effect-value')
+    }),
+  )
+
+  it.effect('preserves a returned Effect failure', () =>
+    Effect.gen(function* () {
+      const expected = { _tag: 'ExpectedError' as const }
+      const failure = yield* trySyncOrPromiseOrEffect(() => Effect.fail(expected)).pipe(Effect.flip)
+
+      expect(failure).toBe(expected)
+    }),
+  )
+
+  it('preserves returned Effect success, error, and requirements types', () => {
+    const normalized = trySyncOrPromiseOrEffect(() => contextualEffect)
+
+    expectTypeOf(normalized).toEqualTypeOf<
+      Effect.Effect<number, 'effect-error' | Cause.UnknownError, RequiredService>
+    >()
+  })
+
+  it('returns an Effect when the operation only throws', () => {
+    const normalized = trySyncOrPromiseOrEffect((): never => {
+      throw new Error('thrown')
+    })
+
+    expectTypeOf(normalized).toEqualTypeOf<Effect.Effect<never, Cause.UnknownError>>()
+  })
+})