effect 3.5.0 → 3.5.2

package/src/Logger.ts

@@ -73,6 +73,35 @@ export declare namespace Logger {
 }
 
 /**
+ * Creates a custom logger that formats log messages according to the provided
+ * function.
+ *
+ * @example
+ * import { Effect, Logger, LogLevel } from "effect"
+ *
+ * const logger = Logger.make(({ logLevel, message }) => {
+ *   globalThis.console.log(`[${logLevel.label}] ${message}`)
+ * })
+ *
+ * const task1 = Effect.logDebug("task1 done")
+ * const task2 = Effect.logDebug("task2 done")
+ *
+ * const program = Effect.gen(function*() {
+ *   yield* Effect.log("start")
+ *   yield* task1
+ *   yield* task2
+ *   yield* Effect.log("done")
+ * }).pipe(
+ *   Logger.withMinimumLogLevel(LogLevel.Debug),
+ *   Effect.provide(Logger.replace(Logger.defaultLogger, logger))
+ * )
+ *
+ * // Effect.runFork(program)
+ * // [INFO] start
+ * // [DEBUG] task1 done
+ * // [DEBUG] task2 done
+ * // [INFO] done
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -160,25 +189,36 @@ export const map: {
 } = internal.map
 
 /**
- * @since 2.0.0
- * @category mapping
+ * Creates a batched logger that groups log messages together and processes them
+ * in intervals.
+ *
+ * @param window - The time window in which to batch log messages.
+ *
  * @example
- * import { Console, Effect, Logger } from "effect";
+ * import { Console, Effect, Logger } from "effect"
  *
  * const LoggerLive = Logger.replaceScoped(
  *   Logger.defaultLogger,
  *   Logger.logfmtLogger.pipe(
- *     Logger.batched("500 millis", (messages) =>
- *       Console.log("BATCH", messages.join("\n"))
- *     )
+ *     Logger.batched("500 millis", (messages) => Console.log("BATCH", `[\n${messages.join("\n")}\n]`))
  *   )
- * );
+ * )
+ *
+ * const program = Effect.gen(function*() {
+ *   yield* Effect.log("one")
+ *   yield* Effect.log("two")
+ *   yield* Effect.log("three")
+ * }).pipe(Effect.provide(LoggerLive))
+ *
+ * // Effect.runFork(program)
+ * // BATCH [
+ * // timestamp=... level=INFO fiber=#0 message=one
+ * // timestamp=... level=INFO fiber=#0 message=two
+ * // timestamp=... level=INFO fiber=#0 message=three
+ * // ]
  *
- * Effect.gen(function* (_) {
- *   yield* _(Effect.log("one"));
- *   yield* _(Effect.log("two"));
- *   yield* _(Effect.log("three"));
- * }).pipe(Effect.provide(LoggerLive), Effect.runFork);
+ * @since 2.0.0
+ * @category mapping
  */
 export const batched: {
   <Output, R>(
@@ -278,6 +318,17 @@ export const test: {
 } = internalCircular.test
 
 /**
+ * Sets the minimum log level for subsequent logging operations, allowing
+ * control over which log messages are displayed based on their severity.
+ *
+ * @example
+ * import { Effect, Logger, LogLevel } from "effect"
+ *
+ * const program = Effect.logDebug("message1").pipe(Logger.withMinimumLogLevel(LogLevel.Debug))
+ *
+ * // Effect.runFork(program)
+ * // timestamp=... level=DEBUG fiber=#0 message=message1
+ *
  * @since 2.0.0
  * @category context
  */
@@ -345,12 +396,40 @@ export const zipRight: {
 export const defaultLogger: Logger<unknown, void> = fiberRuntime.defaultLogger
 
 /**
+ * The `jsonLogger` logger formats log entries as JSON objects, making them easy to
+ * integrate with logging systems that consume JSON data.
+ *
+ * @example
+ * import { Effect, Logger } from "effect"
+ *
+ * const program = Effect.log("message1", "message2").pipe(
+ *   Effect.annotateLogs({ key1: "value1", key2: "value2" }),
+ *   Effect.withLogSpan("myspan")
+ * )
+ *
+ * // Effect.runFork(program.pipe(Effect.provide(Logger.json)))
+ * // {"message":["message1","message2"],"logLevel":"INFO","timestamp":"...","annotations":{"key2":"value2","key1":"value1"},"spans":{"myspan":0},"fiberId":"#0"}
+ *
  * @since 2.0.0
  * @category constructors
  */
 export const jsonLogger: Logger<unknown, string> = internal.jsonLogger
 
 /**
+ * This logger outputs logs in a human-readable format that is easy to read
+ * during development or in a production console.
+ *
+ * @example
+ * import { Effect, Logger } from "effect"
+ *
+ * const program = Effect.log("message1", "message2").pipe(
+ *   Effect.annotateLogs({ key1: "value1", key2: "value2" }),
+ *   Effect.withLogSpan("myspan")
+ * )
+ *
+ * // Effect.runFork(program.pipe(Effect.provide(Logger.logFmt)))
+ * // timestamp=... level=INFO fiber=#0 message=message1 message=message2 myspan=0ms key2=value2 key1=value1
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -363,6 +442,27 @@ export const logfmtLogger: Logger<unknown, string> = internal.logfmtLogger
 export const stringLogger: Logger<unknown, string> = internal.stringLogger
 
 /**
+ * The pretty logger utilizes the capabilities of the console API to generate
+ * visually engaging and color-enhanced log outputs. This feature is
+ * particularly useful for improving the readability of log messages during
+ * development and debugging processes.
+ *
+ * @example
+ * import { Effect, Logger } from "effect"
+ *
+ * const program = Effect.log("message1", "message2").pipe(
+ *   Effect.annotateLogs({ key1: "value1", key2: "value2" }),
+ *   Effect.withLogSpan("myspan")
+ * )
+ *
+ * // Effect.runFork(program.pipe(Effect.provide(Logger.pretty)))
+ * //         green --v                      v-- bold and cyan
+ * // [07:51:54.434] INFO (#0) myspan=1ms: message1
+ * //   message2
+ * //    v-- bold
+ * //   key2: value2
+ * //   key1: value1
+ *
  * @since 3.5.0
  * @category constructors
  */
@@ -376,6 +476,29 @@ export const prettyLogger: (
 ) => Logger<unknown, void> = internal.prettyLogger
 
 /**
+ * The structured logger provides detailed log outputs, structured in a way that
+ * retains comprehensive traceability of the events, suitable for deeper
+ * analysis and troubleshooting.
+ *
+ * @example
+ * import { Effect, Logger } from "effect"
+ *
+ * const program = Effect.log("message1", "message2").pipe(
+ *   Effect.annotateLogs({ key1: "value1", key2: "value2" }),
+ *   Effect.withLogSpan("myspan")
+ * )
+ *
+ * // Effect.runFork(program.pipe(Effect.provide(Logger.structured)))
+ * // {
+ * //   message: [ 'message1', 'message2' ],
+ * //   logLevel: 'INFO',
+ * //   timestamp: '2024-07-09T14:05:41.623Z',
+ * //   cause: undefined,
+ * //   annotations: { key2: 'value2', key1: 'value1' },
+ * //   spans: { myspan: 0 },
+ * //   fiberId: '#0'
+ * // }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -399,30 +522,118 @@ export const structuredLogger: Logger<
 export const tracerLogger: Logger<unknown, void> = fiberRuntime.tracerLogger
 
 /**
+ * The `json` logger formats log entries as JSON objects, making them easy to
+ * integrate with logging systems that consume JSON data.
+ *
+ * @example
+ * import { Effect, Logger } from "effect"
+ *
+ * const program = Effect.log("message1", "message2").pipe(
+ *   Effect.annotateLogs({ key1: "value1", key2: "value2" }),
+ *   Effect.withLogSpan("myspan")
+ * )
+ *
+ * // Effect.runFork(program.pipe(Effect.provide(Logger.json)))
+ * // {"message":["message1","message2"],"logLevel":"INFO","timestamp":"...","annotations":{"key2":"value2","key1":"value1"},"spans":{"myspan":0},"fiberId":"#0"}
+ *
  * @since 2.0.0
  * @category constructors
  */
 export const json: Layer.Layer<never> = replace(fiberRuntime.defaultLogger, fiberRuntime.jsonLogger)
 
 /**
+ * This logger outputs logs in a human-readable format that is easy to read
+ * during development or in a production console.
+ *
+ * @example
+ * import { Effect, Logger } from "effect"
+ *
+ * const program = Effect.log("message1", "message2").pipe(
+ *   Effect.annotateLogs({ key1: "value1", key2: "value2" }),
+ *   Effect.withLogSpan("myspan")
+ * )
+ *
+ * // Effect.runFork(program.pipe(Effect.provide(Logger.logFmt)))
+ * // timestamp=... level=INFO fiber=#0 message=message1 message=message2 myspan=0ms key2=value2 key1=value1
+ *
  * @since 2.0.0
  * @category constructors
  */
 export const logFmt: Layer.Layer<never> = replace(fiberRuntime.defaultLogger, fiberRuntime.logFmtLogger)
 
 /**
+ * The pretty logger utilizes the capabilities of the console API to generate
+ * visually engaging and color-enhanced log outputs. This feature is
+ * particularly useful for improving the readability of log messages during
+ * development and debugging processes.
+ *
+ * @example
+ * import { Effect, Logger } from "effect"
+ *
+ * const program = Effect.log("message1", "message2").pipe(
+ *   Effect.annotateLogs({ key1: "value1", key2: "value2" }),
+ *   Effect.withLogSpan("myspan")
+ * )
+ *
+ * // Effect.runFork(program.pipe(Effect.provide(Logger.pretty)))
+ * //         green --v                      v-- bold and cyan
+ * // [07:51:54.434] INFO (#0) myspan=1ms: message1
+ * //   message2
+ * //    v-- bold
+ * //   key2: value2
+ * //   key1: value1
+ *
  * @since 3.5.0
  * @category constructors
  */
 export const pretty: Layer.Layer<never> = replace(fiberRuntime.defaultLogger, fiberRuntime.prettyLogger)
 
 /**
+ * The structured logger provides detailed log outputs, structured in a way that
+ * retains comprehensive traceability of the events, suitable for deeper
+ * analysis and troubleshooting.
+ *
+ * @example
+ * import { Effect, Logger } from "effect"
+ *
+ * const program = Effect.log("message1", "message2").pipe(
+ *   Effect.annotateLogs({ key1: "value1", key2: "value2" }),
+ *   Effect.withLogSpan("myspan")
+ * )
+ *
+ * // Effect.runFork(program.pipe(Effect.provide(Logger.structured)))
+ * // {
+ * //   message: [ 'message1', 'message2' ],
+ * //   logLevel: 'INFO',
+ * //   timestamp: '2024-07-09T14:05:41.623Z',
+ * //   cause: undefined,
+ * //   annotations: { key2: 'value2', key1: 'value1' },
+ * //   spans: { myspan: 0 },
+ * //   fiberId: '#0'
+ * // }
+ *
  * @since 2.0.0
  * @category constructors
  */
 export const structured: Layer.Layer<never> = replace(fiberRuntime.defaultLogger, fiberRuntime.structuredLogger)
 
 /**
+ * Sets the minimum log level for logging operations, allowing control over
+ * which log messages are displayed based on their severity.
+ *
+ * @example
+ * import { Effect, Logger, LogLevel } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   yield* Effect.log("Executing task...")
+ *   yield* Effect.sleep("100 millis")
+ *   console.log("task done")
+ * })
+ *
+ * // Logging disabled using a layer
+ * // Effect.runFork(program.pipe(Effect.provide(Logger.minimumLogLevel(LogLevel.None))))
+ * // task done
+ *
  * @since 2.0.0
  * @category context
  */

package/src/Random.ts

@@ -122,6 +122,21 @@ export const Random: Context.Tag<Random, Random> = internal.randomTag
 /**
  * Constructs the `Random` service, seeding the pseudo-random number generator
  * with an hash of the specified seed.
+ * This constructor is useful for generating predictable sequences of random values for specific use cases.
+ *
+ * Example uses:
+ * - Generating random UI data for visual tests.
+ * - Creating data that needs to change daily but remain the same throughout a single day, such as using a date as the seed.
+ *
+ * @param seed - The seed value used to initialize the generator.
+ *
+ * @example
+ * import { Effect, Random } from "effect"
+ *
+ * const random1 = Random.make("myseed")
+ * const random2 = Random.make("myseed")
+ *
+ * assert.equal(Effect.runSync(random1.next), Effect.runSync(random2.next))
  *
  * @since 3.5.0
  * @category constructors

package/src/internal/cause.ts

@@ -1100,9 +1100,13 @@ const prettyErrorStack = (message: string, stack: string, span?: Span | undefine
       const stackFn = spanToTrace.get(current)
       if (typeof stackFn === "function") {
         const stack = stackFn()
-        const locationMatch = stack.match(locationRegex)
-        const location = locationMatch ? locationMatch[1] : stack.replace(/^at /, "")
-        out.push(`    at ${current.name} (${location})`)
+        if (typeof stack === "string") {
+          const locationMatch = stack.match(locationRegex)
+          const location = locationMatch ? locationMatch[1] : stack.replace(/^at /, "")
+          out.push(`    at ${current.name} (${location})`)
+        } else {
+          out.push(`    at ${current.name}`)
+        }
       } else {
         out.push(`    at ${current.name}`)
       }

package/src/internal/core.ts

@@ -5,6 +5,7 @@ import * as Chunk from "../Chunk.js"
 import * as Context from "../Context.js"
 import type * as Deferred from "../Deferred.js"
 import type * as Differ from "../Differ.js"
+import * as Duration from "../Duration.js"
 import type * as Effect from "../Effect.js"
 import * as Either from "../Either.js"
 import * as Equal from "../Equal.js"
@@ -2297,6 +2298,9 @@ export const TimeoutExceptionTypeId: Cause.TimeoutExceptionTypeId = Symbol.for(
 export const TimeoutException = makeException<Cause.TimeoutException>({
   [TimeoutExceptionTypeId]: TimeoutExceptionTypeId
 }, "TimeoutException")
+/** @internal */
+export const timeoutExceptionFromDuration = (duration: Duration.DurationInput): Cause.TimeoutException =>
+  new TimeoutException(`Operation timed out before the specified duration of '${Duration.format(duration)}' elapsed`)
 
 /** @internal */
 export const isTimeoutException = (u: unknown): u is Cause.TimeoutException => hasProperty(u, TimeoutExceptionTypeId)

package/src/internal/effect/circular.ts

@@ -419,7 +419,7 @@ export const timeout = dual<
   ) => Effect.Effect<A, E | Cause.TimeoutException, R>
 >(2, (self, duration) =>
   timeoutFail(self, {
-    onTimeout: () => new core.TimeoutException(),
+    onTimeout: () => core.timeoutExceptionFromDuration(duration),
     duration
   }))
 

package/src/internal/logger.ts

@@ -369,9 +369,6 @@ export const isLogger = (u: unknown): u is Logger.Logger<unknown, unknown> => {
   return typeof u === "object" && u != null && LoggerTypeId in u
 }
 
-const processStdoutIsTTY = typeof process === "object" && "stdout" in process && process.stdout.isTTY === true
-const hasWindow = typeof window === "object"
-
 const withColor = (text: string, ...colors: ReadonlyArray<string>) => {
   let out = ""
   for (let i = 0; i < colors.length; i++) {
@@ -403,12 +400,26 @@ const logLevelColors: Record<LogLevel.LogLevel["_tag"], ReadonlyArray<string>> =
   Error: [colors.red],
   Fatal: [colors.bgBrightRed, colors.black]
 }
+const logLevelStyle: Record<LogLevel.LogLevel["_tag"], string> = {
+  None: "",
+  All: "",
+  Trace: "color:gray",
+  Debug: "color:blue",
+  Info: "color:green",
+  Warning: "color:orange",
+  Error: "color:red",
+  Fatal: "background-color:red;color:white"
+}
 
 const defaultDateFormat = (date: Date): string =>
   `${date.getHours().toString().padStart(2, "0")}:${date.getMinutes().toString().padStart(2, "0")}:${
     date.getSeconds().toString().padStart(2, "0")
   }.${date.getMilliseconds().toString().padStart(3, "0")}`
 
+const processStdoutIsTTY = typeof process === "object" && "stdout" in process && process.stdout.isTTY === true
+const hasWindow = typeof window === "object"
+const isWorker = typeof self === "object" && self.constructor && self.constructor.name.includes("Worker")
+
 /** @internal */
 export const prettyLogger = (options?: {
   readonly colors?: "auto" | boolean | undefined
@@ -417,21 +428,31 @@ export const prettyLogger = (options?: {
   readonly mode?: "browser" | "tty" | "auto" | undefined
 }) => {
   const mode_ = options?.mode ?? "auto"
-  const mode = mode_ === "auto" ? (hasWindow ? "browser" : "tty") : mode_
+  const mode = mode_ === "auto" ? (hasWindow || isWorker ? "browser" : "tty") : mode_
   const isBrowser = mode === "browser"
   const showColors = typeof options?.colors === "boolean" ? options.colors : processStdoutIsTTY || isBrowser
-  const color = showColors ? withColor : withColorNoop
   const formatDate = options?.formatDate ?? defaultDateFormat
+  return isBrowser
+    ? prettyLoggerBrowser({ colors: showColors, formatDate })
+    : prettyLoggerTty({ colors: showColors, formatDate, stderr: options?.stderr === true })
+}
 
+const prettyLoggerTty = (options: {
+  readonly colors: boolean
+  readonly stderr: boolean
+  readonly formatDate: (date: Date) => string
+}) => {
+  const processIsBun = typeof process === "object" && "isBun" in process && process.isBun === true
+  const color = options.colors && processStdoutIsTTY ? withColor : withColorNoop
   return makeLogger<unknown, void>(
     ({ annotations, cause, context, date, fiberId, logLevel, message: message_, spans }) => {
       const services = FiberRefs.getOrDefault(context, defaultServices.currentServices)
       const console = Context.get(services, consoleTag).unsafe
-      const log = options?.stderr === true ? console.error : console.log
+      const log = options.stderr === true ? console.error : console.log
 
       const message = Arr.ensure(message_)
 
-      let firstLine = color(`[${formatDate(date)}]`, colors.white)
+      let firstLine = color(`[${options.formatDate(date)}]`, colors.white)
         + ` ${color(logLevel.label, ...logLevelColors[logLevel._tag])}`
         + ` (${_fiberId.threadName(fiberId)})`
 
@@ -453,18 +474,11 @@ export const prettyLogger = (options?: {
         }
       }
 
-      if (isBrowser) {
-        console.groupCollapsed(firstLine)
-      } else {
-        log(firstLine)
-        console.group()
-      }
+      log(firstLine)
+      if (!processIsBun) console.group()
+
       if (!Cause.isEmpty(cause)) {
-        if (isBrowser) {
-          console.error(Cause.pretty(cause, { renderErrorCause: true }))
-        } else {
-          log(Cause.pretty(cause, { renderErrorCause: true }))
-        }
+        log(Cause.pretty(cause, { renderErrorCause: true }))
       }
 
       if (messageIndex < message.length) {
@@ -478,6 +492,76 @@ export const prettyLogger = (options?: {
           log(color(`${key}:`, colors.bold, colors.white), value)
         }
       }
+
+      if (!processIsBun) console.groupEnd()
+    }
+  )
+}
+
+const prettyLoggerBrowser = (options: {
+  readonly colors: boolean
+  readonly formatDate: (date: Date) => string
+}) => {
+  const color = options.colors ? "%c" : ""
+  return makeLogger<unknown, void>(
+    ({ annotations, cause, context, date, fiberId, logLevel, message: message_, spans }) => {
+      const services = FiberRefs.getOrDefault(context, defaultServices.currentServices)
+      const console = Context.get(services, consoleTag).unsafe
+      const message = Arr.ensure(message_)
+
+      let firstLine = `${color}[${options.formatDate(date)}]`
+      const firstParams = []
+      if (options.colors) {
+        firstParams.push("color:gray")
+      }
+      firstLine += ` ${color}${logLevel.label}${color} (${_fiberId.threadName(fiberId)})`
+      if (options.colors) {
+        firstParams.push(logLevelStyle[logLevel._tag], "")
+      }
+      if (List.isCons(spans)) {
+        const now = date.getTime()
+        const render = renderLogSpanLogfmt(now)
+        for (const span of spans) {
+          firstLine += " " + render(span)
+        }
+      }
+
+      firstLine += ":"
+
+      let messageIndex = 0
+      if (message.length > 0) {
+        const firstMaybeString = structuredMessage(message[0])
+        if (typeof firstMaybeString === "string") {
+          firstLine += ` ${color}${firstMaybeString}`
+          if (options.colors) {
+            firstParams.push("color:blue")
+          }
+          messageIndex++
+        }
+      }
+
+      console.groupCollapsed(firstLine, ...firstParams)
+
+      if (!Cause.isEmpty(cause)) {
+        console.error(Cause.pretty(cause, { renderErrorCause: true }))
+      }
+
+      if (messageIndex < message.length) {
+        for (; messageIndex < message.length; messageIndex++) {
+          console.log(message[messageIndex])
+        }
+      }
+
+      if (HashMap.size(annotations) > 0) {
+        for (const [key, value] of annotations) {
+          if (options.colors) {
+            console.log(`%c${key}:`, "color:gray", value)
+          } else {
+            console.log(`${key}:`, value)
+          }
+        }
+      }
+
       console.groupEnd()
     }
   )

package/src/internal/version.ts

@@ -1,4 +1,4 @@
-let moduleVersion = "3.5.0"
+let moduleVersion = "3.5.2"
 
 export const getCurrentVersion = () => moduleVersion