effect 3.8.4 → 3.8.5

package/src/Micro.ts

@@ -403,7 +403,17 @@ export const causeSquash = <E>(self: MicroCause<E>): unknown =>
  * @category MicroCause
  */
 export const causeWithTrace: {
+  /**
+   * @since 3.4.6
+   * @experimental
+   * @category MicroCause
+   */
   (trace: string): <E>(self: MicroCause<E>) => MicroCause<E>
+  /**
+   * @since 3.4.6
+   * @experimental
+   * @category MicroCause
+   */
   <E>(self: MicroCause<E>, trace: string): MicroCause<E>
 } = dual(2, <E>(self: MicroCause<E>, trace: string): MicroCause<E> => {
   const traces = [...self.traces, trace]
@@ -606,7 +616,17 @@ export const envUnsafeMakeEmpty = (): Env<never> => {
  * @category environment
  */
 export const envGet: {
+  /**
+   * @since 3.4.0
+   * @experimental
+   * @category environment
+   */
   <A>(ref: EnvRef<A>): <R>(self: Env<R>) => A
+  /**
+   * @since 3.4.0
+   * @experimental
+   * @category environment
+   */
   <A, R>(self: Env<R>, ref: EnvRef<A>): A
 } = dual(2, <R, A>(self: Env<R>, ref: EnvRef<A>): A => ref.key in self.refs ? (self.refs[ref.key] as A) : ref.initial)
 
@@ -616,7 +636,17 @@ export const envGet: {
  * @category environment
  */
 export const envSet: {
+  /**
+   * @since 3.4.0
+   * @experimental
+   * @category environment
+   */
   <A>(ref: EnvRef<A>, value: A): <R>(self: Env<R>) => Env<R>
+  /**
+   * @since 3.4.0
+   * @experimental
+   * @category environment
+   */
   <A, R>(self: Env<R>, ref: EnvRef<A>, value: A): Env<R>
 } = dual(3, <R, A>(self: Env<R>, ref: EnvRef<A>, value: A): Env<R> => {
   const refs = Object.assign(Object.create(null), self.refs)
@@ -630,7 +660,17 @@ export const envSet: {
  * @category environment
  */
 export const envMutate: {
+  /**
+   * @since 3.4.0
+   * @experimental
+   * @category environment
+   */
   (f: (map: Record<string, unknown>) => void): <R>(self: Env<R>) => Env<R>
+  /**
+   * @since 3.4.0
+   * @experimental
+   * @category environment
+   */
   <R>(self: Env<R>, f: (map: Record<string, unknown>) => void): Env<R>
 } = dual(
   2,
@@ -684,7 +724,21 @@ export const getEnvRef = <A>(envRef: EnvRef<A>): Micro<A> =>
  * @category environment
  */
 export const locally: {
+  /**
+   * Set the value of the given `EnvRef` for the duration of the effect.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category environment
+   */
   <A>(fiberRef: EnvRef<A>, value: A): <XA, E, R>(self: Micro<XA, E, R>) => Micro<XA, E, R>
+  /**
+   * Set the value of the given `EnvRef` for the duration of the effect.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category environment
+   */
   <XA, E, R, A>(self: Micro<XA, E, R>, fiberRef: EnvRef<A>, value: A): Micro<XA, E, R>
 } = dual(
   3,
@@ -709,7 +763,21 @@ export const context = <R>(): Micro<Context.Context<R>> => getEnvRef(currentCont
  * @category environment
  */
 export const provideContext: {
+  /**
+   * Merge the given `Context` with the current context.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category environment
+   */
   <XR>(context: Context.Context<XR>): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E, Exclude<R, XR>>
+  /**
+   * Merge the given `Context` with the current context.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category environment
+   */
   <A, E, R, XR>(self: Micro<A, E, R>, context: Context.Context<XR>): Micro<A, E, Exclude<R, XR>>
 } = dual(
   2,
@@ -729,7 +797,21 @@ export const provideContext: {
  * @category environment
  */
 export const provideService: {
+  /**
+   * Add the provided service to the current context.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category environment
+   */
   <I, S>(tag: Context.Tag<I, S>, service: S): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E, Exclude<R, I>>
+  /**
+   * Add the provided service to the current context.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category environment
+   */
   <A, E, R, I, S>(self: Micro<A, E, R>, tag: Context.Tag<I, S>, service: S): Micro<A, E, Exclude<R, I>>
 } = dual(
   3,
@@ -750,10 +832,26 @@ export const provideService: {
  * @category environment
  */
 export const provideServiceEffect: {
+  /**
+   * Create a service using the provided `Micro` effect, and add it to the
+   * current context.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category environment
+   */
   <I, S, E2, R2>(
     tag: Context.Tag<I, S>,
     acquire: Micro<S, E2, R2>
   ): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E | E2, Exclude<R, I> | R2>
+  /**
+   * Create a service using the provided `Micro` effect, and add it to the
+   * current context.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category environment
+   */
   <A, E, R, I, S, E2, R2>(
     self: Micro<A, E, R>,
     tag: Context.Tag<I, S>,
@@ -995,7 +1093,39 @@ export const currentScheduler: EnvRef<MicroScheduler> = envRefMake(
  * )
  */
 export const withConcurrency: {
+  /**
+   * If you have a `Micro` that uses `concurrency: "inherit"`, you can use this
+   * api to control the concurrency of that `Micro` when it is run.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category environment refs
+   * @example
+   * import * as Micro from "effect/Micro"
+   *
+   * Micro.forEach([1, 2, 3], (n) => Micro.succeed(n), {
+   *   concurrency: "inherit"
+   * }).pipe(
+   *   Micro.withConcurrency(2) // use a concurrency of 2
+   * )
+   */
   (concurrency: "unbounded" | number): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E, R>
+  /**
+   * If you have a `Micro` that uses `concurrency: "inherit"`, you can use this
+   * api to control the concurrency of that `Micro` when it is run.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category environment refs
+   * @example
+   * import * as Micro from "effect/Micro"
+   *
+   * Micro.forEach([1, 2, 3], (n) => Micro.succeed(n), {
+   *   concurrency: "inherit"
+   * }).pipe(
+   *   Micro.withConcurrency(2) // use a concurrency of 2
+   * )
+   */
   <A, E, R>(self: Micro<A, E, R>, concurrency: "unbounded" | number): Micro<A, E, R>
 } = dual(
   2,
@@ -1482,7 +1612,23 @@ export const flatten = <A, E, R, E2, R2>(self: Micro<Micro<A, E, R>, E2, R2>): M
  * @category mapping & sequencing
  */
 export const map: {
+  /**
+   * Transforms the success value of the `Micro` effect with the specified
+   * function.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category mapping & sequencing
+   */
   <A, B>(f: (a: A) => B): <E, R>(self: Micro<A, E, R>) => Micro<B, E, R>
+  /**
+   * Transforms the success value of the `Micro` effect with the specified
+   * function.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category mapping & sequencing
+   */
   <A, E, R, B>(self: Micro<A, E, R>, f: (a: A) => B): Micro<B, E, R>
 } = dual(2, <A, E, R, B>(self: Micro<A, E, R>, f: (a: A) => B): Micro<B, E, R> =>
   make(function(env, onExit) {
@@ -1500,7 +1646,23 @@ export const map: {
  * @category mapping & sequencing
  */
 export const as: {
+  /**
+   * Create a `Micro` effect that will replace the success value of the given
+   * effect.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category mapping & sequencing
+   */
   <A, B>(value: B): <E, R>(self: Micro<A, E, R>) => Micro<B, E, R>
+  /**
+   * Create a `Micro` effect that will replace the success value of the given
+   * effect.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category mapping & sequencing
+   */
   <A, E, R, B>(self: Micro<A, E, R>, value: B): Micro<B, E, R>
 } = dual(2, <A, E, R, B>(self: Micro<A, E, R>, value: B): Micro<B, E, R> => map(self, (_) => value))
 
@@ -1522,7 +1684,23 @@ export const asSome = <A, E, R>(self: Micro<A, E, R>): Micro<Option.Option<A>, E
  * @category mapping & sequencing
  */
 export const flatMap: {
+  /**
+   * Map the success value of this `Micro` effect to another `Micro` effect, then
+   * flatten the result.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category mapping & sequencing
+   */
   <A, B, E2, R2>(f: (a: A) => Micro<B, E2, R2>): <E, R>(self: Micro<A, E, R>) => Micro<B, E | E2, R | R2>
+  /**
+   * Map the success value of this `Micro` effect to another `Micro` effect, then
+   * flatten the result.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category mapping & sequencing
+   */
   <A, E, R, B, E2, R2>(self: Micro<A, E, R>, f: (a: A) => Micro<B, E2, R2>): Micro<B, E | E2, R | R2>
 } = dual(
   2,
@@ -1562,23 +1740,63 @@ export const flip = <A, E, R>(self: Micro<A, E, R>): Micro<E, A, R> =>
  * @category mapping & sequencing
  */
 export const andThen: {
-  <A, X>(
-    f: (a: A) => X
-  ): <E, R>(
+  /**
+   * A more flexible version of `flatMap`, that combines `map` and `flatMap` into
+   * a single api.
+   *
+   * It also allows you to pass in a `Micro` effect directly, which will be
+   * executed after the current effect.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category mapping & sequencing
+   */
+  <A, X>(f: (a: A) => X): <E, R>(
     self: Micro<A, E, R>
   ) => [X] extends [Micro<infer A1, infer E1, infer R1>] ? Micro<A1, E | E1, R | R1>
     : Micro<X, E, R>
-  <X>(
-    f: NotFunction<X>
-  ): <A, E, R>(
+  /**
+   * A more flexible version of `flatMap`, that combines `map` and `flatMap` into
+   * a single api.
+   *
+   * It also allows you to pass in a `Micro` effect directly, which will be
+   * executed after the current effect.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category mapping & sequencing
+   */
+  <X>(f: NotFunction<X>): <A, E, R>(
     self: Micro<A, E, R>
   ) => [X] extends [Micro<infer A1, infer E1, infer R1>] ? Micro<A1, E | E1, R | R1>
     : Micro<X, E, R>
+  /**
+   * A more flexible version of `flatMap`, that combines `map` and `flatMap` into
+   * a single api.
+   *
+   * It also allows you to pass in a `Micro` effect directly, which will be
+   * executed after the current effect.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category mapping & sequencing
+   */
   <A, E, R, X>(
     self: Micro<A, E, R>,
     f: (a: A) => X
   ): [X] extends [Micro<infer A1, infer E1, infer R1>] ? Micro<A1, E | E1, R | R1>
     : Micro<X, E, R>
+  /**
+   * A more flexible version of `flatMap`, that combines `map` and `flatMap` into
+   * a single api.
+   *
+   * It also allows you to pass in a `Micro` effect directly, which will be
+   * executed after the current effect.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category mapping & sequencing
+   */
   <A, E, R, X>(
     self: Micro<A, E, R>,
     f: NotFunction<X>
@@ -1614,23 +1832,55 @@ export const andThen: {
  * @category mapping & sequencing
  */
 export const tap: {
-  <A, X>(
-    f: (a: NoInfer<A>) => X
-  ): <E, R>(
+  /**
+   * Execute a side effect from the success value of the `Micro` effect.
+   *
+   * It is similar to the `andThen` api, but the success value is ignored.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category mapping & sequencing
+   */
+  <A, X>(f: (a: NoInfer<A>) => X): <E, R>(
     self: Micro<A, E, R>
   ) => [X] extends [Micro<infer _A1, infer E1, infer R1>] ? Micro<A, E | E1, R | R1>
     : Micro<A, E, R>
-  <X>(
-    f: NotFunction<X>
-  ): <A, E, R>(
+  /**
+   * Execute a side effect from the success value of the `Micro` effect.
+   *
+   * It is similar to the `andThen` api, but the success value is ignored.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category mapping & sequencing
+   */
+  <X>(f: NotFunction<X>): <A, E, R>(
     self: Micro<A, E, R>
   ) => [X] extends [Micro<infer _A1, infer E1, infer R1>] ? Micro<A, E | E1, R | R1>
     : Micro<A, E, R>
+  /**
+   * Execute a side effect from the success value of the `Micro` effect.
+   *
+   * It is similar to the `andThen` api, but the success value is ignored.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category mapping & sequencing
+   */
   <A, E, R, X>(
     self: Micro<A, E, R>,
     f: (a: NoInfer<A>) => X
   ): [X] extends [Micro<infer _A1, infer E1, infer R1>] ? Micro<A, E | E1, R | R1>
     : Micro<A, E, R>
+  /**
+   * Execute a side effect from the success value of the `Micro` effect.
+   *
+   * It is similar to the `andThen` api, but the success value is ignored.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category mapping & sequencing
+   */
   <A, E, R, X>(
     self: Micro<A, E, R>,
     f: NotFunction<X>
@@ -1797,7 +2047,23 @@ export const raceAllFirst = <Eff extends Micro<any, any, any>>(
  * @category sequencing
  */
 export const race: {
+  /**
+   * Returns an effect that races two effects, yielding the value of the first
+   * effect to succeed. Losers of the race will be interrupted immediately
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category sequencing
+   */
   <A2, E2, R2>(that: Micro<A2, E2, R2>): <A, E, R>(self: Micro<A, E, R>) => Micro<A | A2, E | E2, R | R2>
+  /**
+   * Returns an effect that races two effects, yielding the value of the first
+   * effect to succeed. Losers of the race will be interrupted immediately
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category sequencing
+   */
   <A, E, R, A2, E2, R2>(self: Micro<A, E, R>, that: Micro<A2, E2, R2>): Micro<A | A2, E | E2, R | R2>
 } = dual(
   2,
@@ -1814,7 +2080,23 @@ export const race: {
  * @category sequencing
  */
 export const raceFirst: {
+  /**
+   * Returns an effect that races two effects, yielding the value of the first
+   * effect to succeed *or* fail. Losers of the race will be interrupted immediately
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category sequencing
+   */
   <A2, E2, R2>(that: Micro<A2, E2, R2>): <A, E, R>(self: Micro<A, E, R>) => Micro<A | A2, E | E2, R | R2>
+  /**
+   * Returns an effect that races two effects, yielding the value of the first
+   * effect to succeed *or* fail. Losers of the race will be interrupted immediately
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category sequencing
+   */
   <A, E, R, A2, E2, R2>(self: Micro<A, E, R>, that: Micro<A2, E2, R2>): Micro<A | A2, E | E2, R | R2>
 } = dual(
   2,
@@ -1835,12 +2117,36 @@ export const raceFirst: {
  * @category zipping
  */
 export const zip: {
+  // ----------------------------------------------------------------------------
+  // zipping
+  // ----------------------------------------------------------------------------
+
+  /**
+   * Combine two `Micro` effects into a single effect that produces a tuple of
+   * their results.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category zipping
+   */
   <A2, E2, R2>(
     that: Micro<A2, E2, R2>,
     options?:
       | { readonly concurrent?: boolean | undefined }
       | undefined
   ): <A, E, R>(self: Micro<A, E, R>) => Micro<[A, A2], E2 | E, R2 | R>
+  // ----------------------------------------------------------------------------
+  // zipping
+  // ----------------------------------------------------------------------------
+
+  /**
+   * Combine two `Micro` effects into a single effect that produces a tuple of
+   * their results.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category zipping
+   */
   <A, E, R, A2, E2, R2>(
     self: Micro<A, E, R>,
     that: Micro<A2, E2, R2>,
@@ -1862,11 +2168,29 @@ export const zip: {
  * @category zipping
  */
 export const zipWith: {
+  /**
+   * The `Micro.zipWith` function combines two `Micro` effects and allows you to
+   * apply a function to the results of the combined effects, transforming them
+   * into a single value.
+   *
+   * @since 3.4.3
+   * @experimental
+   * @category zipping
+   */
   <A2, E2, R2, A, B>(
     that: Micro<A2, E2, R2>,
     f: (a: A, b: A2) => B,
     options?: { readonly concurrent?: boolean | undefined }
   ): <E, R>(self: Micro<A, E, R>) => Micro<B, E2 | E, R2 | R>
+  /**
+   * The `Micro.zipWith` function combines two `Micro` effects and allows you to
+   * apply a function to the results of the combined effects, transforming them
+   * into a single value.
+   *
+   * @since 3.4.3
+   * @experimental
+   * @category zipping
+   */
   <A, E, R, A2, E2, R2, B>(
     self: Micro<A, E, R>,
     that: Micro<A2, E2, R2>,
@@ -1902,19 +2226,79 @@ export const zipWith: {
  * @category filtering & conditionals
  */
 export const filterOrFailCause: {
+  // ----------------------------------------------------------------------------
+  // filtering & conditionals
+  // ----------------------------------------------------------------------------
+
+  /**
+   * Filter the specified effect with the provided function, failing with specified
+   * `MicroCause` if the predicate fails.
+   *
+   * In addition to the filtering capabilities discussed earlier, you have the option to further
+   * refine and narrow down the type of the success channel by providing a
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category filtering & conditionals
+   */
   <A, B extends A, E2>(
     refinement: Refinement<A, B>,
     orFailWith: (a: NoInfer<A>) => MicroCause<E2>
   ): <E, R>(self: Micro<A, E, R>) => Micro<B, E2 | E, R>
+  // ----------------------------------------------------------------------------
+  // filtering & conditionals
+  // ----------------------------------------------------------------------------
+
+  /**
+   * Filter the specified effect with the provided function, failing with specified
+   * `MicroCause` if the predicate fails.
+   *
+   * In addition to the filtering capabilities discussed earlier, you have the option to further
+   * refine and narrow down the type of the success channel by providing a
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category filtering & conditionals
+   */
   <A, E2>(
     predicate: Predicate<NoInfer<A>>,
     orFailWith: (a: NoInfer<A>) => MicroCause<E2>
   ): <E, R>(self: Micro<A, E, R>) => Micro<A, E2 | E, R>
+  // ----------------------------------------------------------------------------
+  // filtering & conditionals
+  // ----------------------------------------------------------------------------
+
+  /**
+   * Filter the specified effect with the provided function, failing with specified
+   * `MicroCause` if the predicate fails.
+   *
+   * In addition to the filtering capabilities discussed earlier, you have the option to further
+   * refine and narrow down the type of the success channel by providing a
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category filtering & conditionals
+   */
   <A, E, R, B extends A, E2>(
     self: Micro<A, E, R>,
     refinement: Refinement<A, B>,
     orFailWith: (a: A) => MicroCause<E2>
   ): Micro<B, E | E2, R>
+  // ----------------------------------------------------------------------------
+  // filtering & conditionals
+  // ----------------------------------------------------------------------------
+
+  /**
+   * Filter the specified effect with the provided function, failing with specified
+   * `MicroCause` if the predicate fails.
+   *
+   * In addition to the filtering capabilities discussed earlier, you have the option to further
+   * refine and narrow down the type of the success channel by providing a
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category filtering & conditionals
+   */
   <A, E, R, E2>(
     self: Micro<A, E, R>,
     predicate: Predicate<A>,
@@ -1938,19 +2322,63 @@ export const filterOrFailCause: {
  * @category filtering & conditionals
  */
 export const filterOrFail: {
+  /**
+   * Filter the specified effect with the provided function, failing with specified
+   * error if the predicate fails.
+   *
+   * In addition to the filtering capabilities discussed earlier, you have the option to further
+   * refine and narrow down the type of the success channel by providing a
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category filtering & conditionals
+   */
   <A, B extends A, E2>(
     refinement: Refinement<A, B>,
     orFailWith: (a: NoInfer<A>) => E2
   ): <E, R>(self: Micro<A, E, R>) => Micro<B, E2 | E, R>
+  /**
+   * Filter the specified effect with the provided function, failing with specified
+   * error if the predicate fails.
+   *
+   * In addition to the filtering capabilities discussed earlier, you have the option to further
+   * refine and narrow down the type of the success channel by providing a
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category filtering & conditionals
+   */
   <A, E2>(
     predicate: Predicate<NoInfer<A>>,
     orFailWith: (a: NoInfer<A>) => E2
   ): <E, R>(self: Micro<A, E, R>) => Micro<A, E2 | E, R>
+  /**
+   * Filter the specified effect with the provided function, failing with specified
+   * error if the predicate fails.
+   *
+   * In addition to the filtering capabilities discussed earlier, you have the option to further
+   * refine and narrow down the type of the success channel by providing a
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category filtering & conditionals
+   */
   <A, E, R, B extends A, E2>(
     self: Micro<A, E, R>,
     refinement: Refinement<A, B>,
     orFailWith: (a: A) => E2
   ): Micro<B, E | E2, R>
+  /**
+   * Filter the specified effect with the provided function, failing with specified
+   * error if the predicate fails.
+   *
+   * In addition to the filtering capabilities discussed earlier, you have the option to further
+   * refine and narrow down the type of the success channel by providing a
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category filtering & conditionals
+   */
   <A, E, R, E2>(self: Micro<A, E, R>, predicate: Predicate<A>, orFailWith: (a: A) => E2): Micro<A, E | E2, R>
 } = dual((args) => isMicro(args[0]), <A, E, R, B extends A, E2>(
   self: Micro<A, E, R>,
@@ -1966,9 +2394,23 @@ export const filterOrFail: {
  * @category filtering & conditionals
  */
 export const when: {
+  /**
+   * The moral equivalent of `if (p) exp`.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category filtering & conditionals
+   */
   <E2 = never, R2 = never>(
     condition: LazyArg<boolean> | Micro<boolean, E2, R2>
   ): <A, E, R>(self: Micro<A, E, R>) => Micro<Option.Option<A>, E | E2, R | R2>
+  /**
+   * The moral equivalent of `if (p) exp`.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category filtering & conditionals
+   */
   <A, E, R, E2 = never, R2 = never>(
     self: Micro<A, E, R>,
     condition: LazyArg<boolean> | Micro<boolean, E2, R2>
@@ -1997,16 +2439,49 @@ export const when: {
  * @category repetition
  */
 export const repeatExit: {
-  <A, E>(options: {
-    while: Predicate<MicroExit<A, E>>
-    times?: number | undefined
-    schedule?: MicroSchedule | undefined
-  }): <R>(self: Micro<A, E, R>) => Micro<A, E, R>
-  <A, E, R>(self: Micro<A, E, R>, options: {
-    while: Predicate<MicroExit<A, E>>
-    times?: number | undefined
-    schedule?: MicroSchedule | undefined
-  }): Micro<A, E, R>
+  // ----------------------------------------------------------------------------
+  // repetition
+  // ----------------------------------------------------------------------------
+
+  /**
+   * Repeat the given `Micro` using the provided options.
+   *
+   * The `while` predicate will be checked after each iteration, and can use the
+   * fall `MicroExit` of the effect to determine if the repetition should continue.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category repetition
+   */
+  <A, E>(
+    options: {
+      while: Predicate<MicroExit<A, E>>
+      times?: number | undefined
+      schedule?: MicroSchedule | undefined
+    }
+  ): <R>(self: Micro<A, E, R>) => Micro<A, E, R>
+  // ----------------------------------------------------------------------------
+  // repetition
+  // ----------------------------------------------------------------------------
+
+  /**
+   * Repeat the given `Micro` using the provided options.
+   *
+   * The `while` predicate will be checked after each iteration, and can use the
+   * fall `MicroExit` of the effect to determine if the repetition should continue.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category repetition
+   */
+  <A, E, R>(
+    self: Micro<A, E, R>,
+    options: {
+      while: Predicate<MicroExit<A, E>>
+      times?: number | undefined
+      schedule?: MicroSchedule | undefined
+    }
+  ): Micro<A, E, R>
 } = dual(2, <A, E, R>(self: Micro<A, E, R>, options: {
   while: Predicate<MicroExit<A, E>>
   times?: number | undefined
@@ -2049,6 +2524,14 @@ export const repeatExit: {
  * @category repetition
  */
 export const repeat: {
+  /**
+   * Repeat the given `Micro` effect using the provided options. Only successful
+   * results will be repeated.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category repetition
+   */
   <A, E>(
     options?: {
       while?: Predicate<A> | undefined
@@ -2056,6 +2539,14 @@ export const repeat: {
       schedule?: MicroSchedule | undefined
     } | undefined
   ): <R>(self: Micro<A, E, R>) => Micro<A, E, R>
+  /**
+   * Repeat the given `Micro` effect using the provided options. Only successful
+   * results will be repeated.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category repetition
+   */
   <A, E, R>(
     self: Micro<A, E, R>,
     options?: {
@@ -2142,7 +2633,23 @@ export const scheduleExponential = (baseMillis: number, factor = 2): MicroSchedu
  * @category scheduling
  */
 export const scheduleAddDelay: {
+  /**
+   * Returns a new `MicroSchedule` with an added calculated delay to each delay
+   * returned by this schedule.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category scheduling
+   */
   (f: () => number): (self: MicroSchedule) => MicroSchedule
+  /**
+   * Returns a new `MicroSchedule` with an added calculated delay to each delay
+   * returned by this schedule.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category scheduling
+   */
   (self: MicroSchedule, f: () => number): MicroSchedule
 } = dual(
   2,
@@ -2159,7 +2666,23 @@ export const scheduleAddDelay: {
  * @category scheduling
  */
 export const scheduleWithMaxDelay: {
+  /**
+   * Transform a `MicroSchedule` to one that will have a delay that will never exceed
+   * the specified maximum.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category scheduling
+   */
   (max: number): (self: MicroSchedule) => MicroSchedule
+  /**
+   * Transform a `MicroSchedule` to one that will have a delay that will never exceed
+   * the specified maximum.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category scheduling
+   */
   (self: MicroSchedule, max: number): MicroSchedule
 } = dual(
   2,
@@ -2176,7 +2699,23 @@ export const scheduleWithMaxDelay: {
  * @category scheduling
  */
 export const scheduleWithMaxElapsed: {
+  /**
+   * Transform a `MicroSchedule` to one that will stop repeating after the specified
+   * amount of time.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category scheduling
+   */
   (max: number): (self: MicroSchedule) => MicroSchedule
+  /**
+   * Transform a `MicroSchedule` to one that will stop repeating after the specified
+   * amount of time.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category scheduling
+   */
   (self: MicroSchedule, max: number): MicroSchedule
 } = dual(
   2,
@@ -2193,7 +2732,23 @@ export const scheduleWithMaxElapsed: {
  * @category scheduling
  */
 export const scheduleUnion: {
+  /**
+   * Combines two `MicroSchedule`s, by recurring if either schedule wants to
+   * recur, using the minimum of the two durations between recurrences.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category scheduling
+   */
   (that: MicroSchedule): (self: MicroSchedule) => MicroSchedule
+  /**
+   * Combines two `MicroSchedule`s, by recurring if either schedule wants to
+   * recur, using the minimum of the two durations between recurrences.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category scheduling
+   */
   (self: MicroSchedule, that: MicroSchedule): MicroSchedule
 } = dual(
   2,
@@ -2210,7 +2765,23 @@ export const scheduleUnion: {
  * @category scheduling
  */
 export const scheduleIntersect: {
+  /**
+   * Combines two `MicroSchedule`s, by recurring only if both schedules want to
+   * recur, using the maximum of the two durations between recurrences.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category scheduling
+   */
   (that: MicroSchedule): (self: MicroSchedule) => MicroSchedule
+  /**
+   * Combines two `MicroSchedule`s, by recurring only if both schedules want to
+   * recur, using the maximum of the two durations between recurrences.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category scheduling
+   */
   (self: MicroSchedule, that: MicroSchedule): MicroSchedule
 } = dual(
   2,
@@ -2231,9 +2802,33 @@ export const scheduleIntersect: {
  * @category error handling
  */
 export const catchAllCause: {
+  // ----------------------------------------------------------------------------
+  // error handling
+  // ----------------------------------------------------------------------------
+
+  /**
+   * Catch the full `MicroCause` object of the given `Micro` effect, allowing you to
+   * recover from any kind of cause.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
   <E, B, E2, R2>(
     f: (cause: NoInfer<MicroCause<E>>) => Micro<B, E2, R2>
   ): <A, R>(self: Micro<A, E, R>) => Micro<A | B, E2, R | R2>
+  // ----------------------------------------------------------------------------
+  // error handling
+  // ----------------------------------------------------------------------------
+
+  /**
+   * Catch the full `MicroCause` object of the given `Micro` effect, allowing you to
+   * recover from any kind of cause.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
   <A, E, R, B, E2, R2>(
     self: Micro<A, E, R>,
     f: (cause: NoInfer<MicroCause<E>>) => Micro<B, E2, R2>
@@ -2255,19 +2850,51 @@ export const catchAllCause: {
  * @category error handling
  */
 export const catchCauseIf: {
+  /**
+   * Selectively catch a `MicroCause` object of the given `Micro` effect,
+   * using the provided predicate to determine if the failure should be caught.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
   <E, B, E2, R2, EB extends MicroCause<E>>(
     refinement: Refinement<MicroCause<E>, EB>,
     f: (cause: EB) => Micro<B, E2, R2>
   ): <A, R>(self: Micro<A, E, R>) => Micro<A | B, Exclude<E, MicroCause.Error<EB>> | E2, R | R2>
+  /**
+   * Selectively catch a `MicroCause` object of the given `Micro` effect,
+   * using the provided predicate to determine if the failure should be caught.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
   <E, B, E2, R2>(
     predicate: Predicate<MicroCause<NoInfer<E>>>,
     f: (cause: NoInfer<MicroCause<E>>) => Micro<B, E2, R2>
   ): <A, R>(self: Micro<A, E, R>) => Micro<A | B, E | E2, R | R2>
+  /**
+   * Selectively catch a `MicroCause` object of the given `Micro` effect,
+   * using the provided predicate to determine if the failure should be caught.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
   <A, E, R, B, E2, R2, EB extends MicroCause<E>>(
     self: Micro<A, E, R>,
     refinement: Refinement<MicroCause<E>, EB>,
     f: (cause: EB) => Micro<B, E2, R2>
   ): Micro<A | B, Exclude<E, MicroCause.Error<EB>> | E2, R | R2>
+  /**
+   * Selectively catch a `MicroCause` object of the given `Micro` effect,
+   * using the provided predicate to determine if the failure should be caught.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
   <A, E, R, B, E2, R2>(
     self: Micro<A, E, R>,
     predicate: Predicate<MicroCause<NoInfer<E>>>,
@@ -2298,9 +2925,25 @@ export const catchCauseIf: {
  * @category error handling
  */
 export const catchAll: {
-  <E, B, E2, R2>(
-    f: (e: NoInfer<E>) => Micro<B, E2, R2>
-  ): <A, R>(self: Micro<A, E, R>) => Micro<A | B, E2, R | R2>
+  /**
+   * Catch the error of the given `Micro` effect, allowing you to recover from it.
+   *
+   * It only catches expected (`MicroCause.Fail`) errors.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
+  <E, B, E2, R2>(f: (e: NoInfer<E>) => Micro<B, E2, R2>): <A, R>(self: Micro<A, E, R>) => Micro<A | B, E2, R | R2>
+  /**
+   * Catch the error of the given `Micro` effect, allowing you to recover from it.
+   *
+   * It only catches expected (`MicroCause.Fail`) errors.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
   <A, E, R, B, E2, R2>(self: Micro<A, E, R>, f: (e: NoInfer<E>) => Micro<B, E2, R2>): Micro<A | B, E2, R | R2>
 } = dual(
   2,
@@ -2318,9 +2961,21 @@ export const catchAll: {
  * @category error handling
  */
 export const catchAllDefect: {
-  <E, B, E2, R2>(
-    f: (defect: unknown) => Micro<B, E2, R2>
-  ): <A, R>(self: Micro<A, E, R>) => Micro<A | B, E | E2, R | R2>
+  /**
+   * Catch any unexpected errors of the given `Micro` effect, allowing you to recover from them.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
+  <E, B, E2, R2>(f: (defect: unknown) => Micro<B, E2, R2>): <A, R>(self: Micro<A, E, R>) => Micro<A | B, E | E2, R | R2>
+  /**
+   * Catch any unexpected errors of the given `Micro` effect, allowing you to recover from them.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
   <A, E, R, B, E2, R2>(self: Micro<A, E, R>, f: (defect: unknown) => Micro<B, E2, R2>): Micro<A | B, E | E2, R | R2>
 } = dual(
   2,
@@ -2336,9 +2991,23 @@ export const catchAllDefect: {
  * @category error handling
  */
 export const tapErrorCause: {
+  /**
+   * Perform a side effect using the full `MicroCause` object of the given `Micro`.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
   <E, B, E2, R2>(
     f: (cause: NoInfer<MicroCause<E>>) => Micro<B, E2, R2>
   ): <A, R>(self: Micro<A, E, R>) => Micro<A, E | E2, R | R2>
+  /**
+   * Perform a side effect using the full `MicroCause` object of the given `Micro`.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
   <A, E, R, B, E2, R2>(
     self: Micro<A, E, R>,
     f: (cause: NoInfer<MicroCause<E>>) => Micro<B, E2, R2>
@@ -2360,19 +3029,51 @@ export const tapErrorCause: {
  * @category error handling
  */
 export const tapErrorCauseIf: {
+  /**
+   * Perform a side effect using if a `MicroCause` object matches the specified
+   * predicate.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <E, B, E2, R2, EB extends MicroCause<E>>(
     refinement: Refinement<MicroCause<E>, EB>,
     f: (a: EB) => Micro<B, E2, R2>
   ): <A, R>(self: Micro<A, E, R>) => Micro<A, E | E2, R | R2>
+  /**
+   * Perform a side effect using if a `MicroCause` object matches the specified
+   * predicate.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <E, B, E2, R2>(
     predicate: (cause: NoInfer<MicroCause<E>>) => boolean,
     f: (a: NoInfer<MicroCause<E>>) => Micro<B, E2, R2>
   ): <A, R>(self: Micro<A, E, R>) => Micro<A, E | E2, R | R2>
+  /**
+   * Perform a side effect using if a `MicroCause` object matches the specified
+   * predicate.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <A, E, R, B, E2, R2, EB extends MicroCause<E>>(
     self: Micro<A, E, R>,
     refinement: Refinement<MicroCause<E>, EB>,
     f: (a: EB) => Micro<B, E2, R2>
   ): Micro<A, E | E2, R | R2>
+  /**
+   * Perform a side effect using if a `MicroCause` object matches the specified
+   * predicate.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <A, E, R, B, E2, R2>(
     self: Micro<A, E, R>,
     predicate: (cause: NoInfer<MicroCause<E>>) => boolean,
@@ -2395,9 +3096,21 @@ export const tapErrorCauseIf: {
  * @category error handling
  */
 export const tapError: {
-  <E, B, E2, R2>(
-    f: (e: NoInfer<E>) => Micro<B, E2, R2>
-  ): <A, R>(self: Micro<A, E, R>) => Micro<A, E | E2, R | R2>
+  /**
+   * Perform a side effect from expected errors of the given `Micro`.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
+  <E, B, E2, R2>(f: (e: NoInfer<E>) => Micro<B, E2, R2>): <A, R>(self: Micro<A, E, R>) => Micro<A, E | E2, R | R2>
+  /**
+   * Perform a side effect from expected errors of the given `Micro`.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
   <A, E, R, B, E2, R2>(self: Micro<A, E, R>, f: (e: NoInfer<E>) => Micro<B, E2, R2>): Micro<A, E | E2, R | R2>
 } = dual(
   2,
@@ -2413,9 +3126,21 @@ export const tapError: {
  * @category error handling
  */
 export const tapDefect: {
-  <E, B, E2, R2>(
-    f: (defect: unknown) => Micro<B, E2, R2>
-  ): <A, R>(self: Micro<A, E, R>) => Micro<A, E | E2, R | R2>
+  /**
+   * Perform a side effect from unexpected errors of the given `Micro`.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
+  <E, B, E2, R2>(f: (defect: unknown) => Micro<B, E2, R2>): <A, R>(self: Micro<A, E, R>) => Micro<A, E | E2, R | R2>
+  /**
+   * Perform a side effect from unexpected errors of the given `Micro`.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
   <A, E, R, B, E2, R2>(self: Micro<A, E, R>, f: (defect: unknown) => Micro<B, E2, R2>): Micro<A, E | E2, R | R2>
 } = dual(
   2,
@@ -2431,19 +3156,47 @@ export const tapDefect: {
  * @category error handling
  */
 export const catchIf: {
+  /**
+   * Catch any expected errors that match the specified predicate.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <E, EB extends E, A2, E2, R2>(
     refinement: Refinement<NoInfer<E>, EB>,
     f: (e: EB) => Micro<A2, E2, R2>
   ): <A, R>(self: Micro<A, E, R>) => Micro<A2 | A, E2 | Exclude<E, EB>, R2 | R>
+  /**
+   * Catch any expected errors that match the specified predicate.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <E, A2, E2, R2>(
     predicate: Predicate<NoInfer<E>>,
     f: (e: NoInfer<E>) => Micro<A2, E2, R2>
   ): <A, R>(self: Micro<A, E, R>) => Micro<A2 | A, E | E2, R2 | R>
+  /**
+   * Catch any expected errors that match the specified predicate.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <A, E, R, EB extends E, A2, E2, R2>(
     self: Micro<A, E, R>,
     refinement: Refinement<E, EB>,
     f: (e: EB) => Micro<A2, E2, R2>
   ): Micro<A | A2, E2 | Exclude<E, EB>, R | R2>
+  /**
+   * Catch any expected errors that match the specified predicate.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <A, E, R, A2, E2, R2>(
     self: Micro<A, E, R>,
     predicate: Predicate<E>,
@@ -2471,10 +3224,24 @@ export const catchIf: {
  * @category error handling
  */
 export const catchTag: {
+  /**
+   * Recovers from the specified tagged error.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <K extends E extends { _tag: string } ? E["_tag"] : never, E, A1, E1, R1>(
     k: K,
     f: (e: Extract<E, { _tag: K }>) => Micro<A1, E1, R1>
   ): <A, R>(self: Micro<A, E, R>) => Micro<A1 | A, E1 | Exclude<E, { _tag: K }>, R1 | R>
+  /**
+   * Recovers from the specified tagged error.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <A, E, R, K extends E extends { _tag: string } ? E["_tag"] : never, R1, E1, A1>(
     self: Micro<A, E, R>,
     k: K,
@@ -2495,7 +3262,21 @@ export const catchTag: {
  * @category error handling
  */
 export const mapErrorCause: {
+  /**
+   * Transform the full `MicroCause` object of the given `Micro` effect.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
   <E, E2>(f: (e: MicroCause<E>) => MicroCause<E2>): <A, R>(self: Micro<A, E, R>) => Micro<A, E2, R>
+  /**
+   * Transform the full `MicroCause` object of the given `Micro` effect.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category error handling
+   */
   <A, E, R, E2>(self: Micro<A, E, R>, f: (e: MicroCause<E>) => MicroCause<E2>): Micro<A, E2, R>
 } = dual(
   2,
@@ -2511,7 +3292,21 @@ export const mapErrorCause: {
  * @category error handling
  */
 export const mapError: {
+  /**
+   * Transform any expected errors of the given `Micro` effect.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <E, E2>(f: (e: E) => E2): <A, R>(self: Micro<A, E, R>) => Micro<A, E2, R>
+  /**
+   * Transform any expected errors of the given `Micro` effect.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <A, E, R, E2>(self: Micro<A, E, R>, f: (e: E) => E2): Micro<A, E2, R>
 } = dual(
   2,
@@ -2536,7 +3331,21 @@ export const orDie = <A, E, R>(self: Micro<A, E, R>): Micro<A, never, R> => catc
  * @category error handling
  */
 export const orElseSucceed: {
+  /**
+   * Recover from all errors by succeeding with the given value.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <B>(f: LazyArg<B>): <A, E, R>(self: Micro<A, E, R>) => Micro<A | B, never, R>
+  /**
+   * Recover from all errors by succeeding with the given value.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <A, E, R, B>(self: Micro<A, E, R>, f: LazyArg<B>): Micro<A | B, never, R>
 } = dual(
   2,
@@ -2599,6 +3408,13 @@ export const either = <A, E, R>(self: Micro<A, E, R>): Micro<Either.Either<A, E>
  * @category error handling
  */
 export const retry: {
+  /**
+   * Retry the given `Micro` effect using the provided options.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <A, E>(
     options?: {
       while?: Predicate<E> | undefined
@@ -2606,6 +3422,13 @@ export const retry: {
       schedule?: MicroSchedule | undefined
     } | undefined
   ): <R>(self: Micro<A, E, R>) => Micro<A, E, R>
+  /**
+   * Retry the given `Micro` effect using the provided options.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <A, E, R>(
     self: Micro<A, E, R>,
     options?: {
@@ -2638,7 +3461,23 @@ export const retry: {
  * @category error handling
  */
 export const withTrace: {
+  /**
+   * Add a stack trace to any failures that occur in the effect. The trace will be
+   * added to the `traces` field of the `MicroCause` object.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   (name: string): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E, R>
+  /**
+   * Add a stack trace to any failures that occur in the effect. The trace will be
+   * added to the `traces` field of the `MicroCause` object.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category error handling
+   */
   <A, E, R>(self: Micro<A, E, R>, name: string): Micro<A, E, R>
 } = function() {
   const prevLimit = globalThis.Error.stackTraceLimit
@@ -2679,12 +3518,30 @@ export const withTrace: {
  * @category pattern matching
  */
 export const matchCauseEffect: {
+  // ----------------------------------------------------------------------------
+  // pattern matching
+  // ----------------------------------------------------------------------------
+
+  /**
+   * @since 3.4.6
+   * @experimental
+   * @category pattern matching
+   */
   <E, A2, E2, R2, A, A3, E3, R3>(
     options: {
       readonly onFailure: (cause: MicroCause<E>) => Micro<A2, E2, R2>
       readonly onSuccess: (a: A) => Micro<A3, E3, R3>
     }
   ): <R>(self: Micro<A, E, R>) => Micro<A2 | A3, E2 | E3, R2 | R3 | R>
+  // ----------------------------------------------------------------------------
+  // pattern matching
+  // ----------------------------------------------------------------------------
+
+  /**
+   * @since 3.4.6
+   * @experimental
+   * @category pattern matching
+   */
   <A, E, R, A2, E2, R2, A3, E3, R3>(
     self: Micro<A, E, R>,
     options: {
@@ -2719,12 +3576,22 @@ export const matchCauseEffect: {
  * @category pattern matching
  */
 export const matchCause: {
+  /**
+   * @since 3.4.6
+   * @experimental
+   * @category pattern matching
+   */
   <E, A2, A, A3>(
     options: {
       readonly onFailure: (cause: MicroCause<E>) => A2
       readonly onSuccess: (a: A) => A3
     }
   ): <R>(self: Micro<A, E, R>) => Micro<A2 | A3, never, R>
+  /**
+   * @since 3.4.6
+   * @experimental
+   * @category pattern matching
+   */
   <A, E, R, A2, A3>(
     self: Micro<A, E, R>,
     options: {
@@ -2753,12 +3620,22 @@ export const matchCause: {
  * @category pattern matching
  */
 export const matchEffect: {
+  /**
+   * @since 3.4.6
+   * @experimental
+   * @category pattern matching
+   */
   <E, A2, E2, R2, A, A3, E3, R3>(
     options: {
       readonly onFailure: (e: E) => Micro<A2, E2, R2>
       readonly onSuccess: (a: A) => Micro<A3, E3, R3>
     }
   ): <R>(self: Micro<A, E, R>) => Micro<A2 | A3, E2 | E3, R2 | R3 | R>
+  /**
+   * @since 3.4.6
+   * @experimental
+   * @category pattern matching
+   */
   <A, E, R, A2, E2, R2, A3, E3, R3>(
     self: Micro<A, E, R>,
     options: {
@@ -2787,12 +3664,22 @@ export const matchEffect: {
  * @category pattern matching
  */
 export const match: {
+  /**
+   * @since 3.4.0
+   * @experimental
+   * @category pattern matching
+   */
   <E, A2, A, A3>(
     options: {
       readonly onFailure: (error: E) => A2
       readonly onSuccess: (value: A) => A3
     }
   ): <R>(self: Micro<A, E, R>) => Micro<A2 | A3, never, R>
+  /**
+   * @since 3.4.0
+   * @experimental
+   * @category pattern matching
+   */
   <A, E, R, A2, A3>(
     self: Micro<A, E, R>,
     options: {
@@ -2845,7 +3732,23 @@ export const sleep = (millis: number): Micro<void> =>
  * @category delays & timeouts
  */
 export const delay: {
+  /**
+   * Returns an effect that will delay the execution of this effect by the
+   * specified duration.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category delays & timeouts
+   */
   (millis: number): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E, R>
+  /**
+   * Returns an effect that will delay the execution of this effect by the
+   * specified duration.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category delays & timeouts
+   */
   <A, E, R>(self: Micro<A, E, R>, millis: number): Micro<A, E, R>
 } = dual(
   2,
@@ -2863,14 +3766,39 @@ export const delay: {
  * @category delays & timeouts
  */
 export const timeoutOrElse: {
-  <A2, E2, R2>(options: {
-    readonly duration: number
-    readonly onTimeout: LazyArg<Micro<A2, E2, R2>>
-  }): <A, E, R>(self: Micro<A, E, R>) => Micro<A | A2, E | E2, R | R2>
-  <A, E, R, A2, E2, R2>(self: Micro<A, E, R>, options: {
-    readonly duration: number
-    readonly onTimeout: LazyArg<Micro<A2, E2, R2>>
-  }): Micro<A | A2, E | E2, R | R2>
+  /**
+   * Returns an effect that will timeout this effect, that will execute the
+   * fallback effect if the timeout elapses before the effect has produced a value.
+   *
+   * If the timeout elapses, the running effect will be safely interrupted.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category delays & timeouts
+   */
+  <A2, E2, R2>(
+    options: {
+      readonly duration: number
+      readonly onTimeout: LazyArg<Micro<A2, E2, R2>>
+    }
+  ): <A, E, R>(self: Micro<A, E, R>) => Micro<A | A2, E | E2, R | R2>
+  /**
+   * Returns an effect that will timeout this effect, that will execute the
+   * fallback effect if the timeout elapses before the effect has produced a value.
+   *
+   * If the timeout elapses, the running effect will be safely interrupted.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category delays & timeouts
+   */
+  <A, E, R, A2, E2, R2>(
+    self: Micro<A, E, R>,
+    options: {
+      readonly duration: number
+      readonly onTimeout: LazyArg<Micro<A2, E2, R2>>
+    }
+  ): Micro<A | A2, E | E2, R | R2>
 } = dual(
   2,
   <A, E, R, A2, E2, R2>(self: Micro<A, E, R>, options: {
@@ -2892,7 +3820,29 @@ export const timeoutOrElse: {
  * @category delays & timeouts
  */
 export const timeout: {
+  /**
+   * Returns an effect that will timeout this effect, that will fail with a
+   * `TimeoutException` if the timeout elapses before the effect has produced a
+   * value.
+   *
+   * If the timeout elapses, the running effect will be safely interrupted.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category delays & timeouts
+   */
   (millis: number): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E | TimeoutException, R>
+  /**
+   * Returns an effect that will timeout this effect, that will fail with a
+   * `TimeoutException` if the timeout elapses before the effect has produced a
+   * value.
+   *
+   * If the timeout elapses, the running effect will be safely interrupted.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category delays & timeouts
+   */
   <A, E, R>(self: Micro<A, E, R>, millis: number): Micro<A, E | TimeoutException, R>
 } = dual(
   2,
@@ -2912,7 +3862,29 @@ export const timeout: {
  * @category delays & timeouts
  */
 export const timeoutOption: {
+  /**
+   * Returns an effect that will timeout this effect, succeeding with a `None`
+   * if the timeout elapses before the effect has produced a value; and `Some` of
+   * the produced value otherwise.
+   *
+   * If the timeout elapses, the running effect will be safely interrupted.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category delays & timeouts
+   */
   (millis: number): <A, E, R>(self: Micro<A, E, R>) => Micro<Option.Option<A>, E, R>
+  /**
+   * Returns an effect that will timeout this effect, succeeding with a `None`
+   * if the timeout elapses before the effect has produced a value; and `Some` of
+   * the produced value otherwise.
+   *
+   * If the timeout elapses, the running effect will be safely interrupted.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category delays & timeouts
+   */
   <A, E, R>(self: Micro<A, E, R>, millis: number): Micro<Option.Option<A>, E, R>
 } = dual(
   2,
@@ -3069,7 +4041,21 @@ export const scope: Micro<MicroScope, never, MicroScope> = service(MicroScope)
  * @category resources & finalization
  */
 export const provideScope: {
+  /**
+   * Provide a `MicroScope` to an effect.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category resources & finalization
+   */
   (scope: MicroScope): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E, Exclude<R, MicroScope>>
+  /**
+   * Provide a `MicroScope` to an effect.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category resources & finalization
+   */
   <A, E, R>(self: Micro<A, E, R>, scope: MicroScope): Micro<A, E, Exclude<R, MicroScope>>
 } = dual(
   2,
@@ -3128,9 +4114,25 @@ export const addFinalizer = (
  * @category resources & finalization
  */
 export const onExit: {
+  /**
+   * When the `Micro` effect is completed, run the given finalizer effect with the
+   * `MicroExit` of the executed effect.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category resources & finalization
+   */
   <A, E, XE, XR>(
     f: (exit: MicroExit<A, E>) => Micro<void, XE, XR>
   ): <R>(self: Micro<A, E, R>) => Micro<A, E | XE, R | XR>
+  /**
+   * When the `Micro` effect is completed, run the given finalizer effect with the
+   * `MicroExit` of the executed effect.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category resources & finalization
+   */
   <A, E, R, XE, XR>(self: Micro<A, E, R>, f: (exit: MicroExit<A, E>) => Micro<void, XE, XR>): Micro<A, E | XE, R | XR>
 } = dual(
   2,
@@ -3149,19 +4151,51 @@ export const onExit: {
  * @category resources & finalization
  */
 export const onExitIf: {
+  /**
+   * When the `Micro` effect is completed, run the given finalizer effect if it
+   * matches the specified predicate.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category resources & finalization
+   */
   <A, E, XE, XR, B extends MicroExit<A, E>>(
     refinement: Refinement<MicroExit<A, E>, B>,
     f: (exit: B) => Micro<void, XE, XR>
   ): <R>(self: Micro<A, E, R>) => Micro<A, E | XE, R | XR>
+  /**
+   * When the `Micro` effect is completed, run the given finalizer effect if it
+   * matches the specified predicate.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category resources & finalization
+   */
   <A, E, XE, XR>(
     predicate: Predicate<MicroExit<NoInfer<A>, NoInfer<E>>>,
     f: (exit: MicroExit<NoInfer<A>, NoInfer<E>>) => Micro<void, XE, XR>
   ): <R>(self: Micro<A, E, R>) => Micro<A, E | XE, R | XR>
+  /**
+   * When the `Micro` effect is completed, run the given finalizer effect if it
+   * matches the specified predicate.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category resources & finalization
+   */
   <A, E, R, XE, XR, B extends MicroExit<A, E>>(
     self: Micro<A, E, R>,
     refinement: Refinement<MicroExit<A, E>, B>,
     f: (exit: B) => Micro<void, XE, XR>
   ): Micro<A, E | XE, R | XR>
+  /**
+   * When the `Micro` effect is completed, run the given finalizer effect if it
+   * matches the specified predicate.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category resources & finalization
+   */
   <A, E, R, XE, XR>(
     self: Micro<A, E, R>,
     predicate: Predicate<MicroExit<NoInfer<A>, NoInfer<E>>>,
@@ -3199,9 +4233,21 @@ export const onExitIf: {
  * @category resources & finalization
  */
 export const ensuring: {
-  <XE, XR>(
-    finalizer: Micro<void, XE, XR>
-  ): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E | XE, R | XR>
+  /**
+   * Regardless of the result of the this `Micro` effect, run the finalizer effect.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category resources & finalization
+   */
+  <XE, XR>(finalizer: Micro<void, XE, XR>): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E | XE, R | XR>
+  /**
+   * Regardless of the result of the this `Micro` effect, run the finalizer effect.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category resources & finalization
+   */
   <A, E, R, XE, XR>(self: Micro<A, E, R>, finalizer: Micro<void, XE, XR>): Micro<A, E | XE, R | XR>
 } = dual(
   2,
@@ -3218,9 +4264,25 @@ export const ensuring: {
  * @category resources & finalization
  */
 export const onError: {
+  /**
+   * When the `Micro` effect fails, run the given finalizer effect with the
+   * `MicroCause` of the executed effect.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category resources & finalization
+   */
   <A, E, XE, XR>(
     f: (cause: MicroCause<NoInfer<E>>) => Micro<void, XE, XR>
   ): <R>(self: Micro<A, E, R>) => Micro<A, E | XE, R | XR>
+  /**
+   * When the `Micro` effect fails, run the given finalizer effect with the
+   * `MicroCause` of the executed effect.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category resources & finalization
+   */
   <A, E, R, XE, XR>(
     self: Micro<A, E, R>,
     f: (cause: MicroCause<NoInfer<E>>) => Micro<void, XE, XR>
@@ -3241,9 +4303,21 @@ export const onError: {
  * @category resources & finalization
  */
 export const onInterrupt: {
-  <XE, XR>(
-    finalizer: Micro<void, XE, XR>
-  ): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E | XE, R | XR>
+  /**
+   * If this `Micro` effect is aborted, run the finalizer effect.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category resources & finalization
+   */
+  <XE, XR>(finalizer: Micro<void, XE, XR>): <A, E, R>(self: Micro<A, E, R>) => Micro<A, E | XE, R | XR>
+  /**
+   * If this `Micro` effect is aborted, run the finalizer effect.
+   *
+   * @since 3.4.6
+   * @experimental
+   * @category resources & finalization
+   */
   <A, E, R, XE, XR>(self: Micro<A, E, R>, finalizer: Micro<void, XE, XR>): Micro<A, E | XE, R | XR>
 } = dual(
   2,
@@ -3499,14 +4573,48 @@ export const all = <
  * @category collecting & elements
  */
 export const forEach: {
-  <A, B, E, R>(iterable: Iterable<A>, f: (a: A, index: number) => Micro<B, E, R>, options?: {
-    readonly concurrency?: Concurrency | undefined
-    readonly discard?: false | undefined
-  }): Micro<Array<B>, E, R>
-  <A, B, E, R>(iterable: Iterable<A>, f: (a: A, index: number) => Micro<B, E, R>, options: {
-    readonly concurrency?: Concurrency | undefined
-    readonly discard: true
-  }): Micro<void, E, R>
+  /**
+   * For each element of the provided iterable, run the effect and collect the results.
+   *
+   * If the `discard` option is set to `true`, the results will be discarded and
+   * the effect will return `void`.
+   *
+   * The `concurrency` option can be set to control how many effects are run in
+   * parallel. By default, the effects are run sequentially.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category collecting & elements
+   */
+  <A, B, E, R>(
+    iterable: Iterable<A>,
+    f: (a: A, index: number) => Micro<B, E, R>,
+    options?: {
+      readonly concurrency?: Concurrency | undefined
+      readonly discard?: false | undefined
+    }
+  ): Micro<Array<B>, E, R>
+  /**
+   * For each element of the provided iterable, run the effect and collect the results.
+   *
+   * If the `discard` option is set to `true`, the results will be discarded and
+   * the effect will return `void`.
+   *
+   * The `concurrency` option can be set to control how many effects are run in
+   * parallel. By default, the effects are run sequentially.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category collecting & elements
+   */
+  <A, B, E, R>(
+    iterable: Iterable<A>,
+    f: (a: A, index: number) => Micro<B, E, R>,
+    options: {
+      readonly concurrency?: Concurrency | undefined
+      readonly discard: true
+    }
+  ): Micro<void, E, R>
 } = <
   A,
   B,
@@ -3648,7 +4756,21 @@ export const Do: Micro<{}> = succeed({})
  * @category do notation
  */
 export const bindTo: {
+  /**
+   * Bind the success value of this `Micro` effect to the provided name.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category do notation
+   */
   <N extends string>(name: N): <A, E, R>(self: Micro<A, E, R>) => Micro<{ [K in N]: A }, E, R>
+  /**
+   * Bind the success value of this `Micro` effect to the provided name.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category do notation
+   */
   <A, E, R, N extends string>(self: Micro<A, E, R>, name: N): Micro<{ [K in N]: A }, E, R>
 } = doNotation.bindTo<MicroTypeLambda>(map)
 
@@ -3660,10 +4782,24 @@ export const bindTo: {
  * @category do notation
  */
 export const bind: {
+  /**
+   * Bind the success value of this `Micro` effect to the provided name.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category do notation
+   */
   <N extends string, A extends Record<string, any>, B, E2, R2>(
     name: N,
     f: (a: A) => Micro<B, E2, R2>
   ): <E, R>(self: Micro<A, E, R>) => Micro<Simplify<Omit<A, N> & { [K in N]: B }>, E | E2, R | R2>
+  /**
+   * Bind the success value of this `Micro` effect to the provided name.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category do notation
+   */
   <A extends Record<string, any>, E, R, B, E2, R2, N extends string>(
     self: Micro<A, E, R>,
     name: N,
@@ -3905,7 +5041,27 @@ export const forkDaemon = <A, E, R>(self: Micro<A, E, R>): Micro<Handle<A, E>, n
  * @category handle & forking
  */
 export const forkIn: {
+  /**
+   * Run the `Micro` effect in a new `Handle` that can be awaited, joined, or
+   * aborted.
+   *
+   * The lifetime of the handle will be attached to the provided `MicroScope`.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category handle & forking
+   */
   (scope: MicroScope): <A, E, R>(self: Micro<A, E, R>) => Micro<Handle<A, E>, never, R>
+  /**
+   * Run the `Micro` effect in a new `Handle` that can be awaited, joined, or
+   * aborted.
+   *
+   * The lifetime of the handle will be attached to the provided `MicroScope`.
+   *
+   * @since 3.4.0
+   * @experimental
+   * @category handle & forking
+   */
   <A, E, R>(self: Micro<A, E, R>, scope: MicroScope): Micro<Handle<A, E>, never, R>
 } = dual(
   2,