@clayroach/effect 3.19.14-source-capture.7 → 3.19.14-source-trace.1

package/src/Effect.ts

@@ -60,6 +60,7 @@ import type * as RuntimeFlagsPatch from "./RuntimeFlagsPatch.js"
 import type * as Schedule from "./Schedule.js"
 import * as Scheduler from "./Scheduler.js"
 import type * as Scope from "./Scope.js"
+import type * as SourceLocation from "./SourceLocation.js"
 import type * as Supervisor from "./Supervisor.js"
 import type * as Tracer from "./Tracer.js"
 import type {
@@ -2781,6 +2782,13 @@ export const gen: {
  */
 export interface Adapter {
   <A, E, R>(self: Effect<A, E, R>): Effect<A, E, R>
+  /**
+   * Overload for source trace injection.
+   * Used by @effect/unplugin to inject source location metadata.
+   *
+   * @since 3.20.0
+   */
+  <A, E, R>(self: Effect<A, E, R>, trace: SourceLocation.SourceLocation): Effect<A, E, R>
   <A, _A, _E, _R>(a: A, ab: (a: A) => Effect<_A, _E, _R>): Effect<_A, _E, _R>
   <A, B, _A, _E, _R>(a: A, ab: (a: A) => B, bc: (b: B) => Effect<_A, _E, _R>): Effect<_A, _E, _R>
   <A, B, C, _A, _E, _R>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => Effect<_A, _E, _R>): Effect<_A, _E, _R>
@@ -12945,36 +12953,6 @@ export const withTracerTiming: {
   <A, E, R>(effect: Effect<A, E, R>, enabled: boolean): Effect<A, E, R>
 } = core.withTracerTiming
 
-/**
- * Controls whether source location capture is enabled for forked fibers.
- *
- * **Details**
- *
- * When enabled, `Effect.fork` and similar operations will capture the call
- * site (file, line, column) and store it in a FiberRef that can be read by
- * Supervisors. This enables automatic tracing with meaningful span names
- * like `"sendEmail (user-handlers.ts:42)"` instead of `"anonymous"`.
- *
- * Source capture is disabled by default for performance reasons. Use this
- * API or `Layer.enableSourceCapture` to enable it for specific scopes.
- *
- * @example
- * ```ts
- * import { Effect } from "effect"
- *
- * Effect.gen(function* () {
- *   yield* Effect.fork(myTask)  // Call site is captured
- * }).pipe(Effect.withCaptureStackTraces(true))
- * ```
- *
- * @since 3.15.0
- * @category Tracing
- */
-export const withCaptureStackTraces: {
-  (enabled: boolean): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>
-  <A, E, R>(effect: Effect<A, E, R>, enabled: boolean): Effect<A, E, R>
-} = core.withCaptureStackTraces
-
 /**
  * Adds annotations to each span in the effect for enhanced traceability.
  *

package/src/FiberRef.ts

@@ -22,6 +22,7 @@ import type * as Request from "./Request.js"
 import type * as RuntimeFlags from "./RuntimeFlags.js"
 import * as Scheduler from "./Scheduler.js"
 import type * as Scope from "./Scope.js"
+import type * as SourceLocation from "./SourceLocation.js"
 import type * as Supervisor from "./Supervisor.js"
 import type * as Tracer from "./Tracer.js"
 import type * as Types from "./Types.js"
@@ -387,6 +388,18 @@ export const currentRuntimeFlags: FiberRef<RuntimeFlags.RuntimeFlags> = fiberRun
  */
 export const currentScheduler: FiberRef<Scheduler.Scheduler> = Scheduler.currentScheduler
 
+/**
+ * The current source location trace, used for build-time instrumentation.
+ *
+ * This FiberRef contains the source location of the currently executing effect
+ * step within an `Effect.gen` block. It is automatically set by the
+ * `@effect/unplugin` build-time transformer.
+ *
+ * @since 3.20.0
+ * @category fiberRefs
+ */
+export const currentSourceTrace: FiberRef<SourceLocation.SourceLocation | undefined> = core.currentSourceTrace
+
 /**
  * @since 2.0.0
  * @category fiberRefs

package/src/Layer.ts

@@ -1107,29 +1107,6 @@ export const setTracerTiming: (enabled: boolean) => Layer<never> = (enabled: boo
     fiberRuntime.fiberRefLocallyScoped(core.currentTracerTimingEnabled, enabled)
   )
 
-/**
- * A layer that enables source location capture for forked fibers.
- *
- * When enabled, `Effect.fork` and similar operations will capture the call
- * site (file, line, column) and store it in a FiberRef that can be read by
- * Supervisors. This enables automatic tracing with meaningful span names
- * like `"sendEmail (user-handlers.ts:42)"` instead of `"anonymous"`.
- *
- * @example
- * ```ts
- * import { Effect, Layer } from "effect"
- *
- * // Enable source capture for entire program
- * Effect.runPromise(
- *   program.pipe(Effect.provide(Layer.enableSourceCapture))
- * )
- * ```
- *
- * @since 3.15.0
- * @category tracing
- */
-export const enableSourceCapture: Layer<never> = internal.enableSourceCapture
-
 /**
  * @since 2.0.0
  * @category logging

package/src/RuntimeFlags.ts

@@ -59,17 +59,6 @@ export const Interruption: RuntimeFlag = internal.Interruption
  */
 export const OpSupervision: RuntimeFlag = internal.OpSupervision
 
-/**
- * The operation tracing flag determines whether or not the Effect runtime system
- * will capture metadata for high-level operations (such as Effect.all, Effect.forEach)
- * in the trace field. This metadata can be consumed by supervisors via OpSupervision
- * to enable automatic span creation without manual instrumentation.
- *
- * @since 3.10.0
- * @category constructors
- */
-export const OperationTracing: RuntimeFlag = internal.OperationTracing
-
 /**
  * The runtime metrics flag determines whether or not the Effect runtime system
  * will collect metrics about the Effect runtime. Use of this flag will have a
@@ -171,12 +160,6 @@ export const disableInterruption: Layer.Layer<never> = circular.disableInterrupt
  */
 export const disableOpSupervision: Layer.Layer<never> = circular.disableOpSupervision
 
-/**
- * @since 3.10.0
- * @category context
- */
-export const disableOperationTracing: Layer.Layer<never> = circular.disableOperationTracing
-
 /**
  * @since 2.0.0
  * @category context
@@ -229,12 +212,6 @@ export const enableInterruption: Layer.Layer<never> = circular.enableInterruptio
  */
 export const enableOpSupervision: Layer.Layer<never> = circular.enableOpSupervision
 
-/**
- * @since 3.10.0
- * @category context
- */
-export const enableOperationTracing: Layer.Layer<never> = circular.enableOperationTracing
-
 /**
  * @since 2.0.0
  * @category context
@@ -312,15 +289,6 @@ export const none: RuntimeFlags = internal.none
  */
 export const opSupervision: (self: RuntimeFlags) => boolean = internal.opSupervision
 
-/**
- * Returns `true` if the `OperationTracing` `RuntimeFlag` is enabled, `false`
- * otherwise.
- *
- * @since 3.10.0
- * @category getters
- */
-export const operationTracing: (self: RuntimeFlags) => boolean = internal.operationTracing
-
 /**
  * Patches a set of `RuntimeFlag`s with a `RuntimeFlagsPatch`, returning the
  * patched set of `RuntimeFlag`s.

package/src/SourceLocation.ts

@@ -0,0 +1,108 @@
+/**
+ * Source location metadata for build-time instrumentation.
+ *
+ * This module provides types and utilities for tracking source code locations
+ * through the Effect runtime. It enables automatic log prefixing, OpenTelemetry
+ * code attributes, and DevTools integration.
+ *
+ * @since 3.20.0
+ */
+
+/**
+ * @since 3.20.0
+ * @category symbols
+ */
+export const SourceLocationTypeId: unique symbol = Symbol.for("effect/SourceLocation")
+
+/**
+ * @since 3.20.0
+ * @category symbols
+ */
+export type SourceLocationTypeId = typeof SourceLocationTypeId
+
+/**
+ * Represents a source code location, typically injected at build time.
+ *
+ * @example
+ * ```ts
+ * const trace: SourceLocation = {
+ *   [SourceLocationTypeId]: SourceLocationTypeId,
+ *   path: "src/services/UserRepo.ts",
+ *   line: 42,
+ *   column: 12,
+ *   label: "fetchUser"
+ * }
+ * ```
+ *
+ * @since 3.20.0
+ * @category models
+ */
+export interface SourceLocation {
+  readonly [SourceLocationTypeId]: SourceLocationTypeId
+  /**
+   * The relative file path from the project root.
+   * Example: "src/services/UserRepo.ts"
+   */
+  readonly path: string
+  /**
+   * The 1-based line number in the source file.
+   */
+  readonly line: number
+  /**
+   * The 0-based column number in the source file.
+   */
+  readonly column: number
+  /**
+   * An optional label for this location, typically the variable name
+   * or function name associated with the effect.
+   */
+  readonly label?: string | undefined
+}
+
+/**
+ * Constructs a SourceLocation object.
+ *
+ * @since 3.20.0
+ * @category constructors
+ */
+export const make = (
+  path: string,
+  line: number,
+  column: number,
+  label?: string | undefined
+): SourceLocation => ({
+  [SourceLocationTypeId]: SourceLocationTypeId,
+  path,
+  line,
+  column,
+  label
+})
+
+/**
+ * Formats a SourceLocation as a string for display.
+ *
+ * @example
+ * ```ts
+ * import { SourceLocation } from "effect"
+ *
+ * const trace = SourceLocation.make("src/UserRepo.ts", 42, 12, "fetchUser")
+ * console.log(SourceLocation.format(trace))
+ * // Output: "src/UserRepo.ts:42"
+ * ```
+ *
+ * @since 3.20.0
+ * @category formatting
+ */
+export const format = (location: SourceLocation): string =>
+  location.label
+    ? `${location.path}:${location.line} (${location.label})`
+    : `${location.path}:${location.line}`
+
+/**
+ * Type guard to check if a value is a SourceLocation.
+ *
+ * @since 3.20.0
+ * @category guards
+ */
+export const isSourceLocation = (u: unknown): u is SourceLocation =>
+  typeof u === "object" && u !== null && SourceLocationTypeId in u

package/src/Tracer.ts

@@ -5,7 +5,6 @@ import type * as Context from "./Context.js"
 import type * as Effect from "./Effect.js"
 import type * as Exit from "./Exit.js"
 import type * as Fiber from "./Fiber.js"
-import type * as FiberRef from "./FiberRef.js"
 import type { LazyArg } from "./Function.js"
 import * as defaultServices from "./internal/defaultServices.js"
 import * as internal from "./internal/tracer.js"
@@ -181,18 +180,3 @@ export interface DisablePropagation {
  * @category annotations
  */
 export const DisablePropagation: Context.Reference<DisablePropagation, boolean> = internal.DisablePropagation
-
-/**
- * FiberRef for propagating OpenTelemetry span context through Effect's fiber hierarchy.
- *
- * When fibers are forked, they inherit this FiberRef's value from their parent.
- * This allows supervisors to maintain correct parent-child span relationships
- * even when the OTel AsyncLocalStorage context is lost due to Effect's fiber scheduler.
- *
- * The value is typed as `unknown` to avoid a direct dependency on @opentelemetry/api.
- * Consumers should cast to `OtelApi.Context` when using.
- *
- * @since 3.20.0
- * @category otel
- */
-export const currentOtelSpanContext: FiberRef.FiberRef<unknown> = internal.currentOtelSpanContext

package/src/index.ts

@@ -1302,6 +1302,13 @@ export * as ScopedCache from "./ScopedCache.js"
  */
 export * as ScopedRef from "./ScopedRef.js"
 
+/**
+ * Source location metadata for build-time instrumentation.
+ *
+ * @since 3.20.0
+ */
+export * as SourceLocation from "./SourceLocation.js"
+
 /**
  * @since 2.0.0
  * @deprecated

package/src/internal/config.ts

@@ -415,14 +415,14 @@ export const orElseIf = dual<
       readonly if: Predicate<ConfigError.ConfigError>
       readonly orElse: LazyArg<Config.Config<A2>>
     }
-  ) => <A>(self: Config.Config<A>) => Config.Config<A>,
+  ) => <A>(self: Config.Config<A>) => Config.Config<A | A2>,
   <A, A2>(
     self: Config.Config<A>,
     options: {
       readonly if: Predicate<ConfigError.ConfigError>
       readonly orElse: LazyArg<Config.Config<A2>>
     }
-  ) => Config.Config<A>
+  ) => Config.Config<A | A2>
 >(2, (self, options) => {
   const fallback = Object.create(proto)
   fallback._tag = OpCodes.OP_FALLBACK

package/src/internal/core.ts

@@ -35,6 +35,7 @@ import type * as RequestResolver from "../RequestResolver.js"
 import type * as RuntimeFlags from "../RuntimeFlags.js"
 import * as RuntimeFlagsPatch from "../RuntimeFlagsPatch.js"
 import type * as Scope from "../Scope.js"
+import type * as SourceLocation from "../SourceLocation.js"
 import type * as Tracer from "../Tracer.js"
 import type { NoInfer, NotFunction } from "../Types.js"
 import { internalCall, YieldWrap } from "../Utils.js"
@@ -1415,10 +1416,26 @@ export const fromIterator = <Eff extends YieldWrap<Effect.Effect<any, any, any>>
     return effect
   })
 
+/**
+ * The adapter function injected into Effect.gen generators.
+ * Accepts an effect and an optional source location trace.
+ * When a trace is provided, it wraps the effect with `fiberRefLocally`
+ * to set the currentSourceTrace FiberRef during execution.
+ *
+ * @internal
+ */
+export const genAdapter = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  trace?: SourceLocation.SourceLocation
+): Effect.Effect<A, E, R> =>
+  trace !== undefined
+    ? fiberRefLocally(effect, currentSourceTrace, trace)
+    : effect
+
 /* @internal */
 export const gen: typeof Effect.gen = function() {
   const f = arguments.length === 1 ? arguments[0] : arguments[1].bind(arguments[0])
-  return fromIterator(() => f(pipe))
+  return fromIterator(() => f(genAdapter))
 }
 
 /** @internal */
@@ -1484,28 +1501,6 @@ export const withTracerTiming = dual<
     enabled
   ))
 
-/** @internal */
-export const withCaptureStackTraces = dual<
-  (enabled: boolean) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>,
-  <A, E, R>(effect: Effect.Effect<A, E, R>, enabled: boolean) => Effect.Effect<A, E, R>
->(2, (effect, enabled) =>
-  fiberRefLocally(
-    effect,
-    currentCaptureStackTraces,
-    enabled
-  ))
-
-/** @internal */
-export const withCaptureOperations = dual<
-  (enabled: boolean) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>,
-  <A, E, R>(effect: Effect.Effect<A, E, R>, enabled: boolean) => Effect.Effect<A, E, R>
->(2, (effect, enabled) =>
-  fiberRefLocally(
-    effect,
-    currentCaptureOperations,
-    enabled
-  ))
-
 /* @internal */
 export const yieldNow = (options?: {
   readonly priority?: number | undefined
@@ -2171,89 +2166,10 @@ export const currentTracerSpanLinks: FiberRef.FiberRef<Chunk.Chunk<Tracer.SpanLi
   () => fiberRefUnsafeMake(Chunk.empty())
 )
 
-// -----------------------------------------------------------------------------
-// Source Location Capture
-// -----------------------------------------------------------------------------
-
-/**
- * Represents a source code location captured from a stack trace.
- * @internal
- */
-export interface SourceLocation {
-  readonly file: string
-  readonly line: number
-  readonly column: number
-  readonly functionName?: string
-}
-
-/**
- * Represents metadata for a high-level Effect operation.
- * Stored in the `trace` field of Effect primitives when operation tracing is enabled.
- * The `_tag` field identifies this as operation metadata for use by supervisors.
- * @internal
- */
-export interface OperationMeta {
-  readonly _tag: "OperationMeta"   // Tag to identify operation metadata
-  readonly op: string              // Operation name: 'all', 'forEach', 'retry', etc.
-  readonly count?: number          // Item count for all/forEach
-  readonly capturedAt: string      // Stack trace captured at creation time
-}
-
-/**
- * Creates operation metadata for tracing high-level Effect operations.
- * @internal
- */
-export const makeOperationMeta = (
-  op: string,
-  capturedAt: string,
-  count?: number
-): OperationMeta => {
-  const meta: OperationMeta = {
-    _tag: "OperationMeta",
-    op,
-    capturedAt
-  }
-  if (count !== undefined) {
-    (meta as { count?: number }).count = count
-  }
-  return meta
-}
-
-/**
- * FiberRef that controls whether operation tracing is enabled.
- * When enabled, high-level operations like Effect.all, Effect.forEach
- * capture their call site and store metadata in the trace field.
- * @internal
- */
-export const currentCaptureOperations: FiberRef.FiberRef<boolean> = globalValue(
-  Symbol.for("effect/FiberRef/currentCaptureOperations"),
-  () => fiberRefUnsafeMake(false)
-)
-
-/**
- * FiberRef that controls whether source location capture is enabled.
- * When enabled, `Effect.fork` captures the call site and stores it
- * in `currentSourceLocation` for use by Supervisors.
- * @internal
- */
-export const currentCaptureStackTraces: FiberRef.FiberRef<boolean> = globalValue(
-  Symbol.for("effect/FiberRef/currentCaptureStackTraces"),
-  () => fiberRefUnsafeMake(false)
-)
-
-/**
- * FiberRef that holds the captured source location for a fiber.
- * This is set by `Effect.fork` when `currentCaptureStackTraces` is enabled.
- * Each fiber gets its own location (not propagated to children).
- * @internal
- */
-export const currentSourceLocation: FiberRef.FiberRef<SourceLocation | undefined> = globalValue(
-  Symbol.for("effect/FiberRef/currentSourceLocation"),
-  () =>
-    fiberRefUnsafeMake<SourceLocation | undefined>(undefined, {
-      fork: () => undefined, // Don't propagate - each fiber gets its own
-      join: (parent, _) => parent
-    })
+/** @internal */
+export const currentSourceTrace: FiberRef.FiberRef<SourceLocation.SourceLocation | undefined> = globalValue(
+  Symbol.for("effect/FiberRef/currentSourceTrace"),
+  () => fiberRefUnsafeMake<SourceLocation.SourceLocation | undefined>(undefined)
 )
 
 // -----------------------------------------------------------------------------

package/src/internal/effect/circular.ts

@@ -366,16 +366,10 @@ export const forkAll: {
   }): Effect.Effect<void, never, Effect.Effect.Context<Eff>>
 } = dual((args) => Predicate.isIterable(args[0]), <A, E, R>(effects: Iterable<Effect.Effect<A, E, R>>, options: {
   readonly discard: true
-}): Effect.Effect<void, never, R> => {
-  const rawStack = new Error().stack ?? ""
-  const effectsArray = Array.from(effects)
-  const count = effectsArray.length
-  const result: Effect.Effect<void | Fiber.Fiber<Array<A>, E>, never, R> = options?.discard ?
-    core.forEachSequentialDiscard(effectsArray, fiberRuntime.fork) :
-    core.map(core.forEachSequential(effectsArray, fiberRuntime.fork), fiberRuntime.fiberAll)
-  ;(result as any).trace = core.makeOperationMeta("forkAll", rawStack, count)
-  return result
-})
+}): Effect.Effect<void, never, R> =>
+  options?.discard ?
+    core.forEachSequentialDiscard(effects, fiberRuntime.fork) :
+    core.map(core.forEachSequential(effects, fiberRuntime.fork), fiberRuntime.fiberAll))
 
 /** @internal */
 export const forkIn = dual<
@@ -383,9 +377,8 @@ export const forkIn = dual<
   <A, E, R>(self: Effect.Effect<A, E, R>, scope: Scope.Scope) => Effect.Effect<Fiber.RuntimeFiber<A, E>, never, R>
 >(
   2,
-  <A, E, R>(self: Effect.Effect<A, E, R>, scope: Scope.Scope): Effect.Effect<Fiber.RuntimeFiber<A, E>, never, R> => {
-    const rawStack = new Error().stack ?? ""
-    const result: Effect.Effect<Fiber.RuntimeFiber<A, E>, never, R> = core.withFiberRuntime((parent, parentStatus) => {
+  (self, scope) =>
+    core.withFiberRuntime((parent, parentStatus) => {
       const scopeImpl = scope as fiberRuntime.ScopeImpl
       const fiber = fiberRuntime.unsafeFork(self, parent, parentStatus.runtimeFlags, globalScope)
       if (scopeImpl.state._tag === "Open") {
@@ -406,9 +399,6 @@ export const forkIn = dual<
       }
       return core.succeed(fiber)
     })
-    ;(result as any).trace = core.makeOperationMeta("forkIn", rawStack, 1)
-    return result
-  }
 )
 
 /** @internal */