effect 3.5.0 → 3.5.1

package/src/Effect.ts

@@ -4798,9 +4798,25 @@ export const matchEffect: {
 // -------------------------------------------------------------------------------------
 
 /**
- * Logs the specified message or cause at the current log level.
+ * Logs one or more messages or error causes at the current log level, which is INFO by default.
+ * This function allows logging multiple items at once and can include detailed error information using `Cause` instances.
  *
- * You can set the current log level using `FiberRef.currentLogLevel`.
+ * To adjust the log level, use the `Logger.withMinimumLogLevel` function.
+ *
+ * @example
+ * import { Cause, Effect } from "effect"
+ *
+ * const program = Effect.log(
+ *   "message1",
+ *   "message2",
+ *   Cause.die("Oh no!"),
+ *   Cause.die("Oh uh!")
+ * )
+ *
+ * // Effect.runFork(program)
+ * // Output:
+ * // timestamp=... level=INFO fiber=#0 message=message1 message=message2 cause="Error: Oh no!
+ * // Error: Oh uh!"
  *
  * @since 2.0.0
  * @category logging
@@ -4827,7 +4843,19 @@ export const logWithLevel = (
 export const logTrace: (...message: ReadonlyArray<any>) => Effect<void, never, never> = effect.logTrace
 
 /**
- * Logs the specified message or cause at the Debug log level.
+ * Logs the specified messages at the DEBUG log level.
+ * DEBUG messages are not shown by default.
+ *
+ * To view DEBUG messages, adjust the logging settings using
+ * `Logger.withMinimumLogLevel` and set the log level to `LogLevel.Debug`.
+ *
+ * @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 logging
@@ -4867,7 +4895,20 @@ export const logError: (...message: ReadonlyArray<any>) => Effect<void, never, n
 export const logFatal: (...message: ReadonlyArray<any>) => Effect<void, never, never> = effect.logFatal
 
 /**
- * Adjusts the label for the current logging span.
+ * Adds a log span to your effects, which tracks and logs the duration of
+ * operations or tasks. This is useful for performance monitoring and debugging
+ * time-sensitive processes.
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   yield* Effect.sleep("1 second")
+ *   yield* Effect.log("The job is finished!")
+ * }).pipe(Effect.withLogSpan("myspan"))
+ *
+ * // Effect.runFork(program)
+ * // timestamp=... level=INFO fiber=#0 message="The job is finished!" myspan=1011ms
  *
  * @since 2.0.0
  * @category logging
@@ -4878,7 +4919,21 @@ export const withLogSpan: {
 } = effect.withLogSpan
 
 /**
- * Annotates each log in this effect with the specified log annotation.
+ * Augments log outputs by appending custom annotations to log entries generated
+ * within an effect. This function provides a way to add more context and detail
+ * to log messages, making them more informative and easier to trace.
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   yield* Effect.log("message1")
+ *   yield* Effect.log("message2")
+ * }).pipe(Effect.annotateLogs("key", "value")) // Annotation as key/value pair
+ *
+ * // Effect.runFork(program)
+ * // timestamp=... level=INFO fiber=#0 message=message1 key=value
+ * // timestamp=... level=INFO fiber=#0 message=message2 key=value
  *
  * @since 2.0.0
  * @category logging
@@ -4891,21 +4946,29 @@ export const annotateLogs: {
 } = effect.annotateLogs
 
 /**
- * Annotates each log with the specified log annotation(s), until the Scope is closed.
+ * Applies log annotations with a limited scope, restricting their appearance to
+ * specific sections of your effect computations. Use
+ * `Effect.annotateLogsScoped` to add metadata to logs that only appear within a
+ * defined `Scope`, making it easier to manage context-specific logging.
  *
- * @since 3.1.0
- * @category logging
  * @example
  * import { Effect } from "effect"
  *
- * Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   yield* Effect.log("no annotations")
- *   yield* Effect.annotateLogsScoped({ foo: "bar" })
- *   yield* Effect.log("annotated with foo=bar")
- * }).pipe(
- *   Effect.scoped,
- *   Effect.andThen(Effect.log("no annotations again"))
- * )
+ *   yield* Effect.annotateLogsScoped({ key: "value" })
+ *   yield* Effect.log("message1") // Annotation is applied to this log
+ *   yield* Effect.log("message2") // Annotation is applied to this log
+ * }).pipe(Effect.scoped, Effect.andThen(Effect.log("no annotations again")))
+ *
+ * // Effect.runFork(program)
+ * // timestamp=... level=INFO fiber=#0 message="no annotations"
+ * // timestamp=... level=INFO fiber=#0 message=message1 key=value
+ * // timestamp=... level=INFO fiber=#0 message=message2 key=value
+ * // timestamp=... level=INFO fiber=#0 message="no annotations again"
+ *
+ * @since 3.1.0
+ * @category logging
  */
 export const annotateLogsScoped: {
   (key: string, value: unknown): Effect<void, never, Scope.Scope>

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/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++) {
@@ -409,6 +406,10 @@ const defaultDateFormat = (date: Date): string =>
     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 processIsBun = typeof process === "object" && "isBun" in process && process.isBun === true
+const hasWindow = typeof window === "object"
+
 /** @internal */
 export const prettyLogger = (options?: {
   readonly colors?: "auto" | boolean | undefined
@@ -457,7 +458,7 @@ export const prettyLogger = (options?: {
         console.groupCollapsed(firstLine)
       } else {
         log(firstLine)
-        console.group()
+        if (!processIsBun) console.group()
       }
       if (!Cause.isEmpty(cause)) {
         if (isBrowser) {
@@ -478,7 +479,8 @@ export const prettyLogger = (options?: {
           log(color(`${key}:`, colors.bold, colors.white), value)
         }
       }
-      console.groupEnd()
+
+      if (!processIsBun) console.groupEnd()
     }
   )
 }

package/src/internal/version.ts

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