effect 4.0.0-rc.111 → 4.0.0-rc.113

package/src/Effectable.ts

@@ -1,6 +1,6 @@
 /**
  * Low-level helpers for making custom values behave like Effects. The module
- * exposes a prototype builder and an abstract base class that let
+ * exposes a prototype builder, an abstract base class, and a mixin that let
  * domain-specific values, such as service keys or configuration descriptions,
  * be evaluated by Effect and yielded inside `Effect.gen`.
  *
@@ -8,7 +8,7 @@
  */
 import type * as Effect from "./Effect.ts"
 import type * as Fiber from "./Fiber.ts"
-import { evaluate, makePrimitiveProto } from "./internal/core.ts"
+import { type EffectTypeId, evaluate, makePrimitiveProto } from "./internal/core.ts"
 
 /**
  * Create a low-level `Effect` prototype.
@@ -24,6 +24,7 @@ import { evaluate, makePrimitiveProto } from "./internal/core.ts"
  * When the effect is evaluated, it calls `evaluate` with the current fiber.
  *
  * @see {@link Class} for a class-based approach to defining custom Effect values
+ * @see {@link Mixin} for wrapping an existing class constructor
  *
  * @category prototypes
  * @since 4.0.0
@@ -40,14 +41,16 @@ export const Prototype = <A extends Effect.Effect<any, any, any>>(options: {
     [evaluate]: options.evaluate
   }) as any
 
+const proto = Prototype<Class<any, any, any>>({
+  label: "Effectable",
+  evaluate(_) {
+    return this.asEffect()
+  }
+})
+
 const Base: new<A, E, R>() => Effect.Effect<A, E, R> = (() => {
   const Base = function() {}
-  Base.prototype = Prototype({
-    label: "Effectable",
-    evaluate(_) {
-      return this
-    }
-  })
+  Base.prototype = proto
   return Base as any
 })()
 
@@ -60,9 +63,75 @@ const Base: new<A, E, R>() => Effect.Effect<A, E, R> = (() => {
  * as `Effect` values.
  *
  * @see {@link Prototype} for a lower-level primitive approach to creating custom Effect-like values without a class
+ * @see {@link Mixin} for wrapping an existing class constructor
  * @category constructors
  * @since 2.0.0
  */
 export abstract class Class<A, E = never, R = never> extends Base<A, E, R> {
-  abstract override: Effect.Effect<A, E, R>
+  abstract asEffect(): Effect.Effect<A, E, R>
+}
+
+type AsEffectReturn<Self> = Self extends {
+  asEffect(): infer A extends Effect.Effect<any, any, any>
+} ? A
+  : never
+
+declare abstract class MixinBase extends Class<any, any, any> {
+  constructor(...args: ReadonlyArray<any>)
+  override readonly [EffectTypeId]: AsEffectReturn<this>[typeof EffectTypeId]
+  override [Symbol.iterator](): Effect.EffectIterator<AsEffectReturn<this>>
+}
+
+/**
+ * Returns a subclass of the provided class that inserts the Effect prototype
+ * into the inheritance chain.
+ *
+ * **When to use**
+ *
+ * Use to make instances of an existing class behave as `Effect` values without
+ * extending {@link Class} or modifying the original prototype.
+ *
+ * **Details**
+ *
+ * Pass the class to wrap, then implement `asEffect` on the final class. The
+ * returned class is abstract, and the success, error, and service types are
+ * inferred from the concrete `asEffect` return type. Concrete and abstract base
+ * classes are supported. Constructor parameters and instance members are
+ * preserved, except that Effect's prototype members shadow base prototype
+ * members with the same name: `pipe`, `toString`, `toJSON`, `[Symbol.iterator]`,
+ * and `[Symbol.for("nodejs.util.inspect.custom")]`.
+ *
+ * **Example** (Evaluating a mixed-in class)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Effectable } from "effect"
+ *
+ * class Box {
+ *   constructor(readonly value: number) {}
+ * }
+ *
+ * class EffectBox extends Effectable.Mixin(Box) {
+ *   asEffect() {
+ *     return Effect.succeed(this.value)
+ *   }
+ * }
+ *
+ * const box = new EffectBox(2)
+ * Effect.isEffect(box) // => true
+ * await Effect.runPromise(box) // => 2
+ * ```
+ *
+ * @see {@link Prototype} for a lower-level primitive approach to creating custom Effect-like values without a class
+ * @see {@link Class} for a base constructor to extend
+ * @category constructors
+ * @since 4.0.0
+ */
+export const Mixin = <TBase extends abstract new(...args: ReadonlyArray<any>) => object>(
+  klass: TBase
+): TBase & typeof MixinBase => {
+  abstract class Mixed extends klass {
+    abstract asEffect(): Effect.Effect<any, any, any>
+  }
+  Object.defineProperties(Mixed.prototype, Object.getOwnPropertyDescriptors(proto))
+  return Mixed as TBase & typeof MixinBase
 }

package/src/Encoding.ts

@@ -34,7 +34,7 @@ import * as Result from "./Result.ts"
  * @category type IDs
  * @since 4.0.0
  */
-export const EncodingErrorTypeId = "~effect/encoding/EncodingError" as const
+export const EncodingErrorTypeId = "~effect/Encoding/EncodingError" as const
 
 /**
  * Literal type of the `EncodingErrorTypeId` marker.
@@ -409,6 +409,8 @@ export const encodeHex: (input: Uint8Array | string) => string = (input) =>
  * Generates a random lowercase hexadecimal string, optimized for lengths that
  * are multiples of 8.
  *
+ * **Details**
+ *
  * `length` is not validated. The function generates `length >>> 3` random
  * 8-character words, so non-negative lengths below `2 ** 32` are rounded down
  * to a multiple of 8 and other values follow JavaScript's unsigned 32-bit
@@ -422,13 +424,104 @@ export const encodeHex: (input: Uint8Array | string) => string = (input) =>
  * @since 4.0.0
  */
 export const randomHex = (length: number): string => {
-  let result = ""
-  for (let i = length >>> 3; i > 0; i--) {
-    const word = (Math.random() * 0x100000000) >>> 0
-    result += byteToHex[word >>> 24] + byteToHex[(word >>> 16) & 0xff] + byteToHex[(word >>> 8) & 0xff] +
-      byteToHex[word & 0xff]
+  switch (length) {
+    case 16:
+      return randomHex16()
+    case 32:
+      return randomHex32()
+    default: {
+      let result = ""
+      for (let i = length >>> 3; i > 0; i--) {
+        result += randomHex8()
+      }
+      return result
+    }
   }
-  return result
+}
+
+const hexCharCodes = Uint8Array.from("0123456789abcdef", (c) => c.charCodeAt(0))
+
+const randomWord = (): number => (Math.random() * 0x100000000) >>> 0
+
+// Trace and span identifiers are the common lengths. A single
+// String.fromCharCode call produces a flat string, which avoids rope
+// flattening when the identifier is later serialized.
+const randomHex8 = (): string => {
+  const a = randomWord()
+  return String.fromCharCode(
+    hexCharCodes[a >>> 28],
+    hexCharCodes[(a >>> 24) & 15],
+    hexCharCodes[(a >>> 20) & 15],
+    hexCharCodes[(a >>> 16) & 15],
+    hexCharCodes[(a >>> 12) & 15],
+    hexCharCodes[(a >>> 8) & 15],
+    hexCharCodes[(a >>> 4) & 15],
+    hexCharCodes[a & 15]
+  )
+}
+
+const randomHex16 = (): string => {
+  const a = randomWord()
+  const b = randomWord()
+  return String.fromCharCode(
+    hexCharCodes[a >>> 28],
+    hexCharCodes[(a >>> 24) & 15],
+    hexCharCodes[(a >>> 20) & 15],
+    hexCharCodes[(a >>> 16) & 15],
+    hexCharCodes[(a >>> 12) & 15],
+    hexCharCodes[(a >>> 8) & 15],
+    hexCharCodes[(a >>> 4) & 15],
+    hexCharCodes[a & 15],
+    hexCharCodes[b >>> 28],
+    hexCharCodes[(b >>> 24) & 15],
+    hexCharCodes[(b >>> 20) & 15],
+    hexCharCodes[(b >>> 16) & 15],
+    hexCharCodes[(b >>> 12) & 15],
+    hexCharCodes[(b >>> 8) & 15],
+    hexCharCodes[(b >>> 4) & 15],
+    hexCharCodes[b & 15]
+  )
+}
+
+const randomHex32 = (): string => {
+  const a = randomWord()
+  const b = randomWord()
+  const c = randomWord()
+  const d = randomWord()
+  return String.fromCharCode(
+    hexCharCodes[a >>> 28],
+    hexCharCodes[(a >>> 24) & 15],
+    hexCharCodes[(a >>> 20) & 15],
+    hexCharCodes[(a >>> 16) & 15],
+    hexCharCodes[(a >>> 12) & 15],
+    hexCharCodes[(a >>> 8) & 15],
+    hexCharCodes[(a >>> 4) & 15],
+    hexCharCodes[a & 15],
+    hexCharCodes[b >>> 28],
+    hexCharCodes[(b >>> 24) & 15],
+    hexCharCodes[(b >>> 20) & 15],
+    hexCharCodes[(b >>> 16) & 15],
+    hexCharCodes[(b >>> 12) & 15],
+    hexCharCodes[(b >>> 8) & 15],
+    hexCharCodes[(b >>> 4) & 15],
+    hexCharCodes[b & 15],
+    hexCharCodes[c >>> 28],
+    hexCharCodes[(c >>> 24) & 15],
+    hexCharCodes[(c >>> 20) & 15],
+    hexCharCodes[(c >>> 16) & 15],
+    hexCharCodes[(c >>> 12) & 15],
+    hexCharCodes[(c >>> 8) & 15],
+    hexCharCodes[(c >>> 4) & 15],
+    hexCharCodes[c & 15],
+    hexCharCodes[d >>> 28],
+    hexCharCodes[(d >>> 24) & 15],
+    hexCharCodes[(d >>> 20) & 15],
+    hexCharCodes[(d >>> 16) & 15],
+    hexCharCodes[(d >>> 12) & 15],
+    hexCharCodes[(d >>> 8) & 15],
+    hexCharCodes[(d >>> 4) & 15],
+    hexCharCodes[d & 15]
+  )
 }
 
 /**
@@ -769,10 +862,7 @@ const base64UrlEncodeUint8Array = (data: Uint8Array) =>
 
 // Hex internals
 
-const byteToHex: Array<string> = []
-for (let i = 0; i < 256; i++) {
-  byteToHex.push(i.toString(16).padStart(2, "0"))
-}
+const byteToHex: Array<string> = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, "0"))
 
 const hexEncodeUint8Array = (bytes: Uint8Array): string => {
   let result = ""

package/src/Equal.ts

@@ -52,7 +52,7 @@ import { hasProperty } from "./Predicate.ts"
  * @category symbols
  * @since 2.0.0
  */
-export const symbol = "~effect/interfaces/Equal"
+export const symbol = "~effect/Equal"
 
 /**
  * The interface for types that define their own equality logic.

package/src/ExecutionPlan.ts

@@ -289,6 +289,9 @@ const Proto: Omit<ExecutionPlan<any>, "steps"> = {
     return effect.contextWith((context: Context.Context<any>) =>
       effect.succeed(makeProto(self.steps.map((step) => ({
         ...step,
+        while: step.while
+          ? (input: any) => effect.provideContext(step.while!(input), context)
+          : undefined,
         provide: Layer.isLayer(step.provide)
           ? Layer.provide(step.provide, Layer.succeedContext(context))
           : step.provide

package/src/Fiber.ts

@@ -13,12 +13,13 @@ import type { Effect } from "./Effect.ts"
 import type { Exit } from "./Exit.ts"
 import * as effect from "./internal/effect.ts"
 import type { LogLevel } from "./LogLevel.ts"
+import type { FiberRuntimeMetricsService } from "./Metric.ts"
 import type { Pipeable } from "./Pipeable.ts"
 import { hasProperty } from "./Predicate.ts"
 import type { StackFrame } from "./References.ts"
 import type { Scheduler, SchedulerDispatcher } from "./Scheduler.ts"
 import type { Scope } from "./Scope.ts"
-import type { AnySpan } from "./Tracer.ts"
+import type { AnySpan, Tracer } from "./Tracer.ts"
 import type { Covariant } from "./Types.ts"
 
 const TypeId = "~effect/Fiber"
@@ -75,14 +76,8 @@ export interface Fiber<out A, out E = never> extends Pipeable {
   readonly getRef: <A>(ref: Context.Reference<A>) => A
   readonly context: Context.Context<never>
   setContext(context: Context.Context<never>): void
-  readonly currentScheduler: Scheduler
+  readonly cache: Fiber.Cache
   readonly currentDispatcher: SchedulerDispatcher
-  readonly currentSpan?: AnySpan | undefined
-  readonly currentLogLevel: LogLevel
-  readonly minimumLogLevel: LogLevel
-  readonly currentStackFrame?: StackFrame | undefined
-  readonly maxOpsBeforeYield: number
-  readonly currentPreventYield: boolean
   readonly addObserver: (cb: (exit: Exit<A, E>) => void) => () => void
   readonly interruptUnsafe: (
     fiberId?: number | undefined,
@@ -155,6 +150,36 @@ export declare namespace Fiber {
     readonly _A: Covariant<A>
     readonly _E: Covariant<E>
   }
+
+  /**
+   * Context-derived values cached for the fiber's current `Context`.
+   *
+   * **When to use**
+   *
+   * Use to read runtime services resolved from the fiber's context, such as
+   * the scheduler, current span, or log levels.
+   *
+   * **Details**
+   *
+   * The cache object is computed once per context cache root and shared by
+   * every fiber running with that root, so it must be treated as immutable.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface Cache {
+    readonly scheduler: Scheduler
+    readonly tracer: Tracer | undefined
+    readonly tracerContext: Tracer["context"] | undefined
+    readonly tracerEnabled: boolean
+    readonly span: AnySpan | undefined
+    readonly logLevel: LogLevel
+    readonly minimumLogLevel: LogLevel
+    readonly stackFrame: StackFrame | undefined
+    readonly runtimeMetrics: FiberRuntimeMetricsService | undefined
+    readonly maxOpsBeforeYield: number
+    readonly preventYield: boolean
+  }
 }
 
 const await_: <A, E>(self: Fiber<A, E>) => Effect<Exit<A, E>> = effect.fiberAwait

package/src/FiberHandle.ts

@@ -396,10 +396,10 @@ export const setUnsafe: {
     fiber.interruptUnsafe(internalFiberId)
     return
   } else if (self.state.fiber !== undefined) {
-    if (options?.onlyIfMissing === true) {
-      fiber.interruptUnsafe(internalFiberId)
+    if (self.state.fiber === fiber) {
       return
-    } else if (self.state.fiber === fiber) {
+    } else if (options?.onlyIfMissing === true) {
+      fiber.interruptUnsafe(internalFiberId)
       return
     }
     self.state.fiber.interruptUnsafe(internalFiberId)

package/src/FiberMap.ts

@@ -305,7 +305,8 @@ const isInternalInterruption = Filter.toPredicate(Filter.compose(
  *
  * When the fiber completes, it is removed from the map. If the key already has
  * a fiber, that previous fiber is interrupted unless `onlyIfMissing` is set;
- * in that case the new fiber is interrupted and the existing entry is kept.
+ * in that case a different new fiber is interrupted and the existing entry is
+ * kept, while re-registering the existing fiber is a no-op.
  *
  * **Example** (Adding a fiber unsafely)
  *
@@ -347,7 +348,8 @@ export const setUnsafe: {
    *
    * When the fiber completes, it is removed from the map. If the key already has
    * a fiber, that previous fiber is interrupted unless `onlyIfMissing` is set;
-   * in that case the new fiber is interrupted and the existing entry is kept.
+   * in that case a different new fiber is interrupted and the existing entry is
+   * kept, while re-registering the existing fiber is a no-op.
    *
    * **Example** (Adding a fiber unsafely)
    *
@@ -396,7 +398,8 @@ export const setUnsafe: {
    *
    * When the fiber completes, it is removed from the map. If the key already has
    * a fiber, that previous fiber is interrupted unless `onlyIfMissing` is set;
-   * in that case the new fiber is interrupted and the existing entry is kept.
+   * in that case a different new fiber is interrupted and the existing entry is
+   * kept, while re-registering the existing fiber is a no-op.
    *
    * **Example** (Adding a fiber unsafely)
    *
@@ -449,16 +452,19 @@ export const setUnsafe: {
 
   const previous = MutableHashMap.get(self.state.backing, key)
   if (previous._tag === "Some") {
-    if (options?.onlyIfMissing === true) {
-      fiber.interruptUnsafe(internalFiberId)
+    if (previous.value === fiber) {
       return
-    } else if (previous.value === fiber) {
+    } else if (options?.onlyIfMissing === true) {
+      fiber.interruptUnsafe(internalFiberId)
       return
     }
-    previous.value.interruptUnsafe(internalFiberId)
   }
 
+  // Install the replacement before interruption can re-enter the map through a finalizer.
   MutableHashMap.set(self.state.backing, key, fiber)
+  if (previous._tag === "Some") {
+    previous.value.interruptUnsafe(internalFiberId)
+  }
   fiber.addObserver((exit) => {
     if (self.state._tag === "Closed") {
       return
@@ -487,7 +493,8 @@ export const setUnsafe: {
  *
  * When the fiber completes, it is removed from the map. If the key already has
  * a fiber, that previous fiber is interrupted unless `onlyIfMissing` is set;
- * in that case the new fiber is interrupted and the existing entry is kept.
+ * in that case a different new fiber is interrupted and the existing entry is
+ * kept, while re-registering the existing fiber is a no-op.
  *
  * This is the Effect-wrapped version of `setUnsafe`.
  *
@@ -525,7 +532,8 @@ export const set: {
    *
    * When the fiber completes, it is removed from the map. If the key already has
    * a fiber, that previous fiber is interrupted unless `onlyIfMissing` is set;
-   * in that case the new fiber is interrupted and the existing entry is kept.
+   * in that case a different new fiber is interrupted and the existing entry is
+   * kept, while re-registering the existing fiber is a no-op.
    *
    * This is the Effect-wrapped version of `setUnsafe`.
    *
@@ -570,7 +578,8 @@ export const set: {
    *
    * When the fiber completes, it is removed from the map. If the key already has
    * a fiber, that previous fiber is interrupted unless `onlyIfMissing` is set;
-   * in that case the new fiber is interrupted and the existing entry is kept.
+   * in that case a different new fiber is interrupted and the existing entry is
+   * kept, while re-registering the existing fiber is a no-op.
    *
    * This is the Effect-wrapped version of `setUnsafe`.
    *