effect 3.8.4 → 3.8.5

package/src/LogLevel.ts

@@ -178,7 +178,21 @@ export const allLevels = core.allLogLevels
  * @category utils
  */
 export const locally: {
+  /**
+   * Locally applies the specified `LogLevel` to an `Effect` workflow, reverting
+   * to the previous `LogLevel` after the `Effect` workflow completes.
+   *
+   * @since 2.0.0
+   * @category utils
+   */
   (self: LogLevel): <A, E, R>(use: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /**
+   * Locally applies the specified `LogLevel` to an `Effect` workflow, reverting
+   * to the previous `LogLevel` after the `Effect` workflow completes.
+   *
+   * @since 2.0.0
+   * @category utils
+   */
   <A, E, R>(use: Effect.Effect<A, E, R>, self: LogLevel): Effect.Effect<A, E, R>
 } = dual(
   2,
@@ -200,7 +214,15 @@ export const Order: order.Order<LogLevel> = pipe(
  * @category ordering
  */
 export const lessThan: {
+  /**
+   * @since 2.0.0
+   * @category ordering
+   */
   (that: LogLevel): (self: LogLevel) => boolean
+  /**
+   * @since 2.0.0
+   * @category ordering
+   */
   (self: LogLevel, that: LogLevel): boolean
 } = order.lessThan(Order)
 
@@ -209,7 +231,15 @@ export const lessThan: {
  * @category ordering
  */
 export const lessThanEqual: {
+  /**
+   * @since 2.0.0
+   * @category ordering
+   */
   (that: LogLevel): (self: LogLevel) => boolean
+  /**
+   * @since 2.0.0
+   * @category ordering
+   */
   (self: LogLevel, that: LogLevel): boolean
 } = order.lessThanOrEqualTo(Order)
 
@@ -218,7 +248,15 @@ export const lessThanEqual: {
  * @category ordering
  */
 export const greaterThan: {
+  /**
+   * @since 2.0.0
+   * @category ordering
+   */
   (that: LogLevel): (self: LogLevel) => boolean
+  /**
+   * @since 2.0.0
+   * @category ordering
+   */
   (self: LogLevel, that: LogLevel): boolean
 } = order.greaterThan(Order)
 
@@ -227,7 +265,15 @@ export const greaterThan: {
  * @category ordering
  */
 export const greaterThanEqual: {
+  /**
+   * @since 2.0.0
+   * @category ordering
+   */
   (that: LogLevel): (self: LogLevel) => boolean
+  /**
+   * @since 2.0.0
+   * @category ordering
+   */
   (self: LogLevel, that: LogLevel): boolean
 } = order.greaterThanOrEqualTo(Order)
 

package/src/Logger.ts

@@ -134,9 +134,17 @@ export const addScoped: <A, E, R>(
  * @category mapping
  */
 export const mapInput: {
+  /**
+   * @since 2.0.0
+   * @category mapping
+   */
   <Message, Message2>(
     f: (message: Message2) => Message
   ): <Output>(self: Logger<Message, Output>) => Logger<Message2, Output>
+  /**
+   * @since 2.0.0
+   * @category mapping
+   */
   <Output, Message, Message2>(
     self: Logger<Message, Output>,
     f: (message: Message2) => Message
@@ -148,9 +156,17 @@ export const mapInput: {
  * @category mapping
  */
 export const mapInputOptions: {
+  /**
+   * @since 2.0.0
+   * @category mapping
+   */
   <Message, Message2>(
     f: (options: Logger.Options<Message2>) => Logger.Options<Message>
   ): <Output>(self: Logger<Message, Output>) => Logger<Message2, Output>
+  /**
+   * @since 2.0.0
+   * @category mapping
+   */
   <Output, Message, Message2>(
     self: Logger<Message, Output>,
     f: (options: Logger.Options<Message2>) => Logger.Options<Message>
@@ -165,9 +181,23 @@ export const mapInputOptions: {
  * @category filtering
  */
 export const filterLogLevel: {
+  /**
+   * Returns a version of this logger that only logs messages when the log level
+   * satisfies the specified predicate.
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   (
     f: (logLevel: LogLevel.LogLevel) => boolean
   ): <Message, Output>(self: Logger<Message, Output>) => Logger<Message, Option.Option<Output>>
+  /**
+   * Returns a version of this logger that only logs messages when the log level
+   * satisfies the specified predicate.
+   *
+   * @since 2.0.0
+   * @category filtering
+   */
   <Message, Output>(
     self: Logger<Message, Output>,
     f: (logLevel: LogLevel.LogLevel) => boolean
@@ -179,13 +209,18 @@ export const filterLogLevel: {
  * @category mapping
  */
 export const map: {
+  /**
+   * @since 2.0.0
+   * @category mapping
+   */
   <Output, Output2>(
     f: (output: Output) => Output2
   ): <Message>(self: Logger<Message, Output>) => Logger<Message, Output2>
-  <Message, Output, Output2>(
-    self: Logger<Message, Output>,
-    f: (output: Output) => Output2
-  ): Logger<Message, Output2>
+  /**
+   * @since 2.0.0
+   * @category mapping
+   */
+  <Message, Output, Output2>(self: Logger<Message, Output>, f: (output: Output) => Output2): Logger<Message, Output2>
 } = internal.map
 
 /**
@@ -221,10 +256,74 @@ export const map: {
  * @category mapping
  */
 export const batched: {
+  /**
+   * 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"
+   *
+   * const LoggerLive = Logger.replaceScoped(
+   *   Logger.defaultLogger,
+   *   Logger.logfmtLogger.pipe(
+   *     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
+   * // ]
+   *
+   * @since 2.0.0
+   * @category mapping
+   */
   <Output, R>(
     window: DurationInput,
     f: (messages: Array<Types.NoInfer<Output>>) => Effect<void, never, R>
   ): <Message>(self: Logger<Message, Output>) => Effect<Logger<Message, void>, never, R | Scope>
+  /**
+   * 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"
+   *
+   * const LoggerLive = Logger.replaceScoped(
+   *   Logger.defaultLogger,
+   *   Logger.logfmtLogger.pipe(
+   *     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
+   * // ]
+   *
+   * @since 2.0.0
+   * @category mapping
+   */
   <Message, Output, R>(
     self: Logger<Message, Output>,
     window: DurationInput,
@@ -285,7 +384,15 @@ export const remove: <A>(logger: Logger<unknown, A>) => Layer.Layer<never> = cir
  * @category context
  */
 export const replace: {
+  /**
+   * @since 2.0.0
+   * @category context
+   */
   <B>(that: Logger<unknown, B>): <A>(self: Logger<unknown, A>) => Layer.Layer<never>
+  /**
+   * @since 2.0.0
+   * @category context
+   */
   <A, B>(self: Logger<unknown, A>, that: Logger<unknown, B>): Layer.Layer<never>
 } = circular.replaceLogger
 
@@ -294,7 +401,15 @@ export const replace: {
  * @category context
  */
 export const replaceEffect: {
+  /**
+   * @since 2.0.0
+   * @category context
+   */
   <B, E, R>(that: Effect<Logger<unknown, B>, E, R>): <A>(self: Logger<unknown, A>) => Layer.Layer<never, E, R>
+  /**
+   * @since 2.0.0
+   * @category context
+   */
   <A, B, E, R>(self: Logger<unknown, A>, that: Effect<Logger<unknown, B>, E, R>): Layer.Layer<never, E, R>
 } = circular.replaceLoggerEffect
 
@@ -303,9 +418,17 @@ export const replaceEffect: {
  * @category context
  */
 export const replaceScoped: {
+  /**
+   * @since 2.0.0
+   * @category context
+   */
   <B, E, R>(
     that: Effect<Logger<unknown, B>, E, R>
   ): <A>(self: Logger<unknown, A>) => Layer.Layer<never, E, Exclude<R, Scope>>
+  /**
+   * @since 2.0.0
+   * @category context
+   */
   <A, B, E, R>(
     self: Logger<unknown, A>,
     that: Effect<Logger<unknown, B>, E, R>
@@ -335,7 +458,15 @@ export const sync: <A>(evaluate: LazyArg<A>) => Logger<unknown, A> = internal.sy
  * @category constructors
  */
 export const test: {
+  /**
+   * @since 2.0.0
+   * @category constructors
+   */
   <Message>(input: Message): <Output>(self: Logger<Message, Output>) => Output
+  /**
+   * @since 2.0.0
+   * @category constructors
+   */
   <Message, Output>(self: Logger<Message, Output>, input: Message): Output
 } = internalCircular.test
 
@@ -355,7 +486,37 @@ export const test: {
  * @category context
  */
 export const withMinimumLogLevel: {
+  /**
+   * 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
+   */
   (level: LogLevel.LogLevel): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>
+  /**
+   * 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
+   */
   <A, E, R>(self: Effect<A, E, R>, level: LogLevel.LogLevel): Effect<A, E, R>
 } = circular.withMinimumLogLevel
 
@@ -374,9 +535,23 @@ export const withSpanAnnotations: <Message, Output>(self: Logger<Message, Output
  * @category zipping
  */
 export const zip: {
+  /**
+   * Combines this logger with the specified logger to produce a new logger that
+   * logs to both this logger and that logger.
+   *
+   * @since 2.0.0
+   * @category zipping
+   */
   <Message2, Output2>(
     that: Logger<Message2, Output2>
   ): <Message, Output>(self: Logger<Message, Output>) => Logger<Message & Message2, [Output, Output2]>
+  /**
+   * Combines this logger with the specified logger to produce a new logger that
+   * logs to both this logger and that logger.
+   *
+   * @since 2.0.0
+   * @category zipping
+   */
   <Message, Output, Message2, Output2>(
     self: Logger<Message, Output>,
     that: Logger<Message2, Output2>
@@ -388,9 +563,17 @@ export const zip: {
  * @category zipping
  */
 export const zipLeft: {
+  /**
+   * @since 2.0.0
+   * @category zipping
+   */
   <Message2, Output2>(
     that: Logger<Message2, Output2>
   ): <Message, Output>(self: Logger<Message, Output>) => Logger<Message & Message2, Output>
+  /**
+   * @since 2.0.0
+   * @category zipping
+   */
   <Message, Output, Message2, Output2>(
     self: Logger<Message, Output>,
     that: Logger<Message2, Output2>
@@ -402,9 +585,17 @@ export const zipLeft: {
  * @category zipping
  */
 export const zipRight: {
+  /**
+   * @since 2.0.0
+   * @category zipping
+   */
   <Message2, Output2>(
     that: Logger<Message2, Output2>
   ): <Message, Output>(self: Logger<Message, Output>) => Logger<Message & Message2, Output2>
+  /**
+   * @since 2.0.0
+   * @category zipping
+   */
   <Message, Output, Message2, Output2>(
     self: Logger<Message, Output>,
     that: Logger<Message2, Output2>

package/src/Mailbox.ts

@@ -213,7 +213,23 @@ export const make: <A, E = never>(capacity?: number | undefined) => Effect<Mailb
  * @category combinators
  */
 export const into: {
+  /**
+   * Run an `Effect` into a `Mailbox`, where success ends the mailbox and failure
+   * fails the mailbox.
+   *
+   * @since 3.8.0
+   * @experimental
+   * @category combinators
+   */
   <A, E>(self: Mailbox<A, E>): <AX, EX extends E, RX>(effect: Effect<AX, EX, RX>) => Effect<boolean, never, RX>
+  /**
+   * Run an `Effect` into a `Mailbox`, where success ends the mailbox and failure
+   * fails the mailbox.
+   *
+   * @since 3.8.0
+   * @experimental
+   * @category combinators
+   */
   <AX, E, EX extends E, RX, A>(effect: Effect<AX, EX, RX>, self: Mailbox<A, E>): Effect<boolean, never, RX>
 } = internal.into
 

package/src/MergeDecision.ts

@@ -79,12 +79,20 @@ export const isMergeDecision: (u: unknown) => u is MergeDecision<unknown, unknow
  * @category folding
  */
 export const match: {
+  /**
+   * @since 2.0.0
+   * @category folding
+   */
   <R, E0, Z0, E, Z, Z2>(
     options: {
       readonly onDone: (effect: Effect.Effect<Z, E, R>) => Z2
       readonly onAwait: (f: (exit: Exit.Exit<Z0, E0>) => Effect.Effect<Z, E, R>) => Z2
     }
   ): (self: MergeDecision<R, E0, Z0, E, Z>) => Z2
+  /**
+   * @since 2.0.0
+   * @category folding
+   */
   <R, E0, Z0, E, Z, Z2>(
     self: MergeDecision<R, E0, Z0, E, Z>,
     options: {

package/src/MergeState.ts

@@ -148,6 +148,10 @@ export const isRightDone: <Env, Err, Err1, Err2, Elem, Done, Done1, Done2>(
  * @category folding
  */
 export const match: {
+  /**
+   * @since 2.0.0
+   * @category folding
+   */
   <Env, Err, Err1, Err2, Elem, Done, Done1, Done2, Z>(
     options: {
       readonly onBothRunning: (
@@ -158,6 +162,10 @@ export const match: {
       readonly onRightDone: (f: (exit: Exit.Exit<Done, Err>) => Effect.Effect<Done2, Err2, Env>) => Z
     }
   ): (self: MergeState<Env, Err, Err1, Err2, Elem, Done, Done1, Done2>) => Z
+  /**
+   * @since 2.0.0
+   * @category folding
+   */
   <Env, Err, Err1, Err2, Elem, Done, Done1, Done2, Z>(
     self: MergeState<Env, Err, Err1, Err2, Elem, Done, Done1, Done2>,
     options: {

package/src/MergeStrategy.ts

@@ -96,12 +96,29 @@ export const isBufferSliding: (self: MergeStrategy) => self is BufferSliding = i
  * @category folding
  */
 export const match: {
-  <A>(options: {
-    readonly onBackPressure: () => A
-    readonly onBufferSliding: () => A
-  }): (self: MergeStrategy) => A
-  <A>(self: MergeStrategy, options: {
-    readonly onBackPressure: () => A
-    readonly onBufferSliding: () => A
-  }): A
+  /**
+   * Folds an `MergeStrategy` into a value of type `A`.
+   *
+   * @since 2.0.0
+   * @category folding
+   */
+  <A>(
+    options: {
+      readonly onBackPressure: () => A
+      readonly onBufferSliding: () => A
+    }
+  ): (self: MergeStrategy) => A
+  /**
+   * Folds an `MergeStrategy` into a value of type `A`.
+   *
+   * @since 2.0.0
+   * @category folding
+   */
+  <A>(
+    self: MergeStrategy,
+    options: {
+      readonly onBackPressure: () => A
+      readonly onBufferSliding: () => A
+    }
+  ): A
 } = internal.match