effect 3.10.18 → 3.11.0

package/src/Boolean.ts

@@ -17,10 +17,12 @@ import * as predicate from "./Predicate.js"
  * @param input - The value to test.
  *
  * @example
+ * ```ts
  * import { isBoolean } from "effect/Boolean"
  *
  * assert.deepStrictEqual(isBoolean(true), true)
  * assert.deepStrictEqual(isBoolean("true"), false)
+ * ```
  *
  * @category guards
  * @since 2.0.0
@@ -36,9 +38,11 @@ export const isBoolean: (input: unknown) => input is boolean = predicate.isBoole
  * @param onTrue - a lazy evaluation function that will be executed when the `value` is `true`.
  *
  * @example
+ * ```ts
  * import { Boolean } from "effect"
  *
  * assert.deepStrictEqual(Boolean.match(true, { onFalse: () => "It's false!", onTrue: () => "It's true!" }), "It's true!")
+ * ```
  *
  * @category pattern matching
  * @since 2.0.0
@@ -53,9 +57,11 @@ export const match: {
    * @param onTrue - a lazy evaluation function that will be executed when the `value` is `true`.
    *
    * @example
+   * ```ts
    * import { Boolean } from "effect"
    *
    * assert.deepStrictEqual(Boolean.match(true, { onFalse: () => "It's false!", onTrue: () => "It's true!" }), "It's true!")
+   * ```
    *
    * @category pattern matching
    * @since 2.0.0
@@ -75,9 +81,11 @@ export const match: {
    * @param onTrue - a lazy evaluation function that will be executed when the `value` is `true`.
    *
    * @example
+   * ```ts
    * import { Boolean } from "effect"
    *
    * assert.deepStrictEqual(Boolean.match(true, { onFalse: () => "It's false!", onTrue: () => "It's true!" }), "It's true!")
+   * ```
    *
    * @category pattern matching
    * @since 2.0.0
@@ -110,10 +118,12 @@ export const Order: order.Order<boolean> = order.boolean
  * Negates the given boolean: `!self`
  *
  * @example
+ * ```ts
  * import { not } from "effect/Boolean"
  *
  * assert.deepStrictEqual(not(true), false)
  * assert.deepStrictEqual(not(false), true)
+ * ```
  *
  * @category combinators
  * @since 2.0.0
@@ -124,12 +134,14 @@ export const not = (self: boolean): boolean => !self
  * Combines two boolean using AND: `self && that`.
  *
  * @example
+ * ```ts
  * import { and } from "effect/Boolean"
  *
  * assert.deepStrictEqual(and(true, true), true)
  * assert.deepStrictEqual(and(true, false), false)
  * assert.deepStrictEqual(and(false, true), false)
  * assert.deepStrictEqual(and(false, false), false)
+ * ```
  *
  * @category combinators
  * @since 2.0.0
@@ -139,12 +151,14 @@ export const and: {
    * Combines two boolean using AND: `self && that`.
    *
    * @example
+   * ```ts
    * import { and } from "effect/Boolean"
    *
    * assert.deepStrictEqual(and(true, true), true)
    * assert.deepStrictEqual(and(true, false), false)
    * assert.deepStrictEqual(and(false, true), false)
    * assert.deepStrictEqual(and(false, false), false)
+   * ```
    *
    * @category combinators
    * @since 2.0.0
@@ -154,12 +168,14 @@ export const and: {
    * Combines two boolean using AND: `self && that`.
    *
    * @example
+   * ```ts
    * import { and } from "effect/Boolean"
    *
    * assert.deepStrictEqual(and(true, true), true)
    * assert.deepStrictEqual(and(true, false), false)
    * assert.deepStrictEqual(and(false, true), false)
    * assert.deepStrictEqual(and(false, false), false)
+   * ```
    *
    * @category combinators
    * @since 2.0.0
@@ -171,12 +187,14 @@ export const and: {
  * Combines two boolean using NAND: `!(self && that)`.
  *
  * @example
+ * ```ts
  * import { nand } from "effect/Boolean"
  *
  * assert.deepStrictEqual(nand(true, true), false)
  * assert.deepStrictEqual(nand(true, false), true)
  * assert.deepStrictEqual(nand(false, true), true)
  * assert.deepStrictEqual(nand(false, false), true)
+ * ```
  *
  * @category combinators
  * @since 2.0.0
@@ -186,12 +204,14 @@ export const nand: {
    * Combines two boolean using NAND: `!(self && that)`.
    *
    * @example
+   * ```ts
    * import { nand } from "effect/Boolean"
    *
    * assert.deepStrictEqual(nand(true, true), false)
    * assert.deepStrictEqual(nand(true, false), true)
    * assert.deepStrictEqual(nand(false, true), true)
    * assert.deepStrictEqual(nand(false, false), true)
+   * ```
    *
    * @category combinators
    * @since 2.0.0
@@ -201,12 +221,14 @@ export const nand: {
    * Combines two boolean using NAND: `!(self && that)`.
    *
    * @example
+   * ```ts
    * import { nand } from "effect/Boolean"
    *
    * assert.deepStrictEqual(nand(true, true), false)
    * assert.deepStrictEqual(nand(true, false), true)
    * assert.deepStrictEqual(nand(false, true), true)
    * assert.deepStrictEqual(nand(false, false), true)
+   * ```
    *
    * @category combinators
    * @since 2.0.0
@@ -218,12 +240,14 @@ export const nand: {
  * Combines two boolean using OR: `self || that`.
  *
  * @example
+ * ```ts
  * import { or } from "effect/Boolean"
  *
  * assert.deepStrictEqual(or(true, true), true)
  * assert.deepStrictEqual(or(true, false), true)
  * assert.deepStrictEqual(or(false, true), true)
  * assert.deepStrictEqual(or(false, false), false)
+ * ```
  *
  * @category combinators
  * @since 2.0.0
@@ -233,12 +257,14 @@ export const or: {
    * Combines two boolean using OR: `self || that`.
    *
    * @example
+   * ```ts
    * import { or } from "effect/Boolean"
    *
    * assert.deepStrictEqual(or(true, true), true)
    * assert.deepStrictEqual(or(true, false), true)
    * assert.deepStrictEqual(or(false, true), true)
    * assert.deepStrictEqual(or(false, false), false)
+   * ```
    *
    * @category combinators
    * @since 2.0.0
@@ -248,12 +274,14 @@ export const or: {
    * Combines two boolean using OR: `self || that`.
    *
    * @example
+   * ```ts
    * import { or } from "effect/Boolean"
    *
    * assert.deepStrictEqual(or(true, true), true)
    * assert.deepStrictEqual(or(true, false), true)
    * assert.deepStrictEqual(or(false, true), true)
    * assert.deepStrictEqual(or(false, false), false)
+   * ```
    *
    * @category combinators
    * @since 2.0.0
@@ -265,12 +293,14 @@ export const or: {
  * Combines two booleans using NOR: `!(self || that)`.
  *
  * @example
+ * ```ts
  * import { nor } from "effect/Boolean"
  *
  * assert.deepStrictEqual(nor(true, true), false)
  * assert.deepStrictEqual(nor(true, false), false)
  * assert.deepStrictEqual(nor(false, true), false)
  * assert.deepStrictEqual(nor(false, false), true)
+ * ```
  *
  * @category combinators
  * @since 2.0.0
@@ -280,12 +310,14 @@ export const nor: {
    * Combines two booleans using NOR: `!(self || that)`.
    *
    * @example
+   * ```ts
    * import { nor } from "effect/Boolean"
    *
    * assert.deepStrictEqual(nor(true, true), false)
    * assert.deepStrictEqual(nor(true, false), false)
    * assert.deepStrictEqual(nor(false, true), false)
    * assert.deepStrictEqual(nor(false, false), true)
+   * ```
    *
    * @category combinators
    * @since 2.0.0
@@ -295,12 +327,14 @@ export const nor: {
    * Combines two booleans using NOR: `!(self || that)`.
    *
    * @example
+   * ```ts
    * import { nor } from "effect/Boolean"
    *
    * assert.deepStrictEqual(nor(true, true), false)
    * assert.deepStrictEqual(nor(true, false), false)
    * assert.deepStrictEqual(nor(false, true), false)
    * assert.deepStrictEqual(nor(false, false), true)
+   * ```
    *
    * @category combinators
    * @since 2.0.0
@@ -312,12 +346,14 @@ export const nor: {
  * Combines two booleans using XOR: `(!self && that) || (self && !that)`.
  *
  * @example
+ * ```ts
  * import { xor } from "effect/Boolean"
  *
  * assert.deepStrictEqual(xor(true, true), false)
  * assert.deepStrictEqual(xor(true, false), true)
  * assert.deepStrictEqual(xor(false, true), true)
  * assert.deepStrictEqual(xor(false, false), false)
+ * ```
  *
  * @category combinators
  * @since 2.0.0
@@ -327,12 +363,14 @@ export const xor: {
    * Combines two booleans using XOR: `(!self && that) || (self && !that)`.
    *
    * @example
+   * ```ts
    * import { xor } from "effect/Boolean"
    *
    * assert.deepStrictEqual(xor(true, true), false)
    * assert.deepStrictEqual(xor(true, false), true)
    * assert.deepStrictEqual(xor(false, true), true)
    * assert.deepStrictEqual(xor(false, false), false)
+   * ```
    *
    * @category combinators
    * @since 2.0.0
@@ -342,12 +380,14 @@ export const xor: {
    * Combines two booleans using XOR: `(!self && that) || (self && !that)`.
    *
    * @example
+   * ```ts
    * import { xor } from "effect/Boolean"
    *
    * assert.deepStrictEqual(xor(true, true), false)
    * assert.deepStrictEqual(xor(true, false), true)
    * assert.deepStrictEqual(xor(false, true), true)
    * assert.deepStrictEqual(xor(false, false), false)
+   * ```
    *
    * @category combinators
    * @since 2.0.0
@@ -359,12 +399,14 @@ export const xor: {
  * Combines two booleans using EQV (aka XNOR): `!xor(self, that)`.
  *
  * @example
+ * ```ts
  * import { eqv } from "effect/Boolean"
  *
  * assert.deepStrictEqual(eqv(true, true), true)
  * assert.deepStrictEqual(eqv(true, false), false)
  * assert.deepStrictEqual(eqv(false, true), false)
  * assert.deepStrictEqual(eqv(false, false), true)
+ * ```
  *
  * @category combinators
  * @since 2.0.0
@@ -374,12 +416,14 @@ export const eqv: {
    * Combines two booleans using EQV (aka XNOR): `!xor(self, that)`.
    *
    * @example
+   * ```ts
    * import { eqv } from "effect/Boolean"
    *
    * assert.deepStrictEqual(eqv(true, true), true)
    * assert.deepStrictEqual(eqv(true, false), false)
    * assert.deepStrictEqual(eqv(false, true), false)
    * assert.deepStrictEqual(eqv(false, false), true)
+   * ```
    *
    * @category combinators
    * @since 2.0.0
@@ -389,12 +433,14 @@ export const eqv: {
    * Combines two booleans using EQV (aka XNOR): `!xor(self, that)`.
    *
    * @example
+   * ```ts
    * import { eqv } from "effect/Boolean"
    *
    * assert.deepStrictEqual(eqv(true, true), true)
    * assert.deepStrictEqual(eqv(true, false), false)
    * assert.deepStrictEqual(eqv(false, true), false)
    * assert.deepStrictEqual(eqv(false, false), true)
+   * ```
    *
    * @category combinators
    * @since 2.0.0
@@ -406,12 +452,14 @@ export const eqv: {
  * Combines two booleans using an implication: `(!self || that)`.
  *
  * @example
+ * ```ts
  * import { implies } from "effect/Boolean"
  *
  * assert.deepStrictEqual(implies(true, true), true)
  * assert.deepStrictEqual(implies(true, false), false)
  * assert.deepStrictEqual(implies(false, true), true)
  * assert.deepStrictEqual(implies(false, false), true)
+ * ```
  *
  * @category combinators
  * @since 2.0.0
@@ -421,12 +469,14 @@ export const implies: {
    * Combines two booleans using an implication: `(!self || that)`.
    *
    * @example
+   * ```ts
    * import { implies } from "effect/Boolean"
    *
    * assert.deepStrictEqual(implies(true, true), true)
    * assert.deepStrictEqual(implies(true, false), false)
    * assert.deepStrictEqual(implies(false, true), true)
    * assert.deepStrictEqual(implies(false, false), true)
+   * ```
    *
    * @category combinators
    * @since 2.0.0
@@ -436,12 +486,14 @@ export const implies: {
    * Combines two booleans using an implication: `(!self || that)`.
    *
    * @example
+   * ```ts
    * import { implies } from "effect/Boolean"
    *
    * assert.deepStrictEqual(implies(true, true), true)
    * assert.deepStrictEqual(implies(true, false), false)
    * assert.deepStrictEqual(implies(false, true), true)
    * assert.deepStrictEqual(implies(false, false), true)
+   * ```
    *
    * @category combinators
    * @since 2.0.0
@@ -455,10 +507,12 @@ export const implies: {
  * @param collection - An iterable collection of booleans.
  *
  * @example
+ * ```ts
  * import { every } from "effect/Boolean"
  *
  * assert.deepStrictEqual(every([true, true, true]), true)
  * assert.deepStrictEqual(every([true, false, true]), false)
+ * ```
  *
  * @since 2.0.0
  */
@@ -477,10 +531,12 @@ export const every = (collection: Iterable<boolean>): boolean => {
  * @param collection - An iterable collection of booleans.
  *
  * @example
+ * ```ts
  * import { some } from "effect/Boolean"
  *
  * assert.deepStrictEqual(some([true, false, true]), true)
  * assert.deepStrictEqual(some([false, false, false]), false)
+ * ```
  *
  * @since 2.0.0
  */

package/src/Brand.ts

@@ -196,6 +196,7 @@ export const errors: (...errors: Array<Brand.BrandErrors>) => Brand.BrandErrors
  * @param onFailure - Takes the unbranded value that did not pass the `refinement` predicate and returns a `BrandErrors`.
  *
  * @example
+ * ```ts
  * import { Brand } from "effect"
  *
  * type Int = number & Brand.Brand<"Int">
@@ -207,6 +208,7 @@ export const errors: (...errors: Array<Brand.BrandErrors>) => Brand.BrandErrors
  *
  * assert.strictEqual(Int(1), 1)
  * assert.throws(() => Int(1.1))
+ * ```
  *
  * @since 2.0.0
  * @category constructors
@@ -247,6 +249,7 @@ export function refined<A extends Brand<any>>(
  * If you also want to perform some validation, see {@link refined}.
  *
  * @example
+ * ```ts
  * import { Brand } from "effect"
  *
  * type UserId = number & Brand.Brand<"UserId">
@@ -254,6 +257,7 @@ export function refined<A extends Brand<any>>(
  * const UserId = Brand.nominal<UserId>()
  *
  * assert.strictEqual(UserId(1), 1)
+ * ```
  *
  * @since 2.0.0
  * @category constructors
@@ -275,6 +279,7 @@ export const nominal = <A extends Brand<any>>(): Brand.Constructor<
  * This API is useful when you want to validate that the input data passes multiple brand validators.
  *
  * @example
+ * ```ts
  * import { Brand } from "effect"
  *
  * type Int = number & Brand.Brand<"Int">
@@ -292,6 +297,7 @@ export const nominal = <A extends Brand<any>>(): Brand.Constructor<
  *
  * assert.strictEqual(PositiveInt(1), 1)
  * assert.throws(() => PositiveInt(1.1))
+ * ```
  *
  * @since 2.0.0
  * @category combining

package/src/Channel.ts

@@ -2578,7 +2578,7 @@ export const repeated: <OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>(
  */
 export const run: <OutErr, InErr, OutDone, InDone, Env>(
   self: Channel<never, unknown, OutErr, InErr, OutDone, InDone, Env>
-) => Effect.Effect<OutDone, OutErr, Exclude<Env, Scope.Scope>> = channel.run
+) => Effect.Effect<OutDone, OutErr, Env> = channel.run
 
 /**
  * Run the channel until it finishes with a done value or fails with an error
@@ -2591,7 +2591,7 @@ export const run: <OutErr, InErr, OutDone, InDone, Env>(
  */
 export const runCollect: <OutElem, OutErr, InErr, OutDone, InDone, Env>(
   self: Channel<OutElem, unknown, OutErr, InErr, OutDone, InDone, Env>
-) => Effect.Effect<[Chunk.Chunk<OutElem>, OutDone], OutErr, Exclude<Env, Scope.Scope>> = channel.runCollect
+) => Effect.Effect<[Chunk.Chunk<OutElem>, OutDone], OutErr, Env> = channel.runCollect
 
 /**
  * Runs a channel until the end is received.
@@ -2601,7 +2601,21 @@ export const runCollect: <OutElem, OutErr, InErr, OutDone, InDone, Env>(
  */
 export const runDrain: <OutElem, OutErr, InErr, OutDone, InDone, Env>(
   self: Channel<OutElem, unknown, OutErr, InErr, OutDone, InDone, Env>
-) => Effect.Effect<OutDone, OutErr, Exclude<Env, Scope.Scope>> = channel.runDrain
+) => Effect.Effect<OutDone, OutErr, Env> = channel.runDrain
+
+/**
+ * Run the channel until it finishes with a done value or fails with an error.
+ * The channel must not read any input or write any output.
+ *
+ * Closing the channel, which includes execution of all the finalizers
+ * attached to the channel will be added to the current scope as a finalizer.
+ *
+ * @since 3.11.0
+ * @category destructors
+ */
+export const runScoped: <OutErr, InErr, OutDone, InDone, Env>(
+  self: Channel<never, unknown, OutErr, InErr, OutDone, InDone, Env>
+) => Effect.Effect<OutDone, OutErr, Env | Scope.Scope> = channel.runScoped
 
 /**
  * Use a scoped effect to emit an output element.
@@ -2613,6 +2627,18 @@ export const scoped: <A, E, R>(
   effect: Effect.Effect<A, E, R>
 ) => Channel<A, unknown, E, unknown, unknown, unknown, Exclude<R, Scope.Scope>> = channel.scoped
 
+/**
+ * Use a function that receives a scope and returns an effect to emit an output
+ * element. The output element will be the result of the returned effect, if
+ * successful.
+ *
+ * @since 3.11.0
+ * @category constructors
+ */
+export const scopedWith: <A, E, R>(
+  f: (scope: Scope.Scope) => Effect.Effect<A, E, R>
+) => Channel<A, unknown, E, unknown, unknown, unknown, R> = channel.scopedWith
+
 /**
  * Splits strings on newlines. Handles both Windows newlines (`\r\n`) and UNIX
  * newlines (`\n`).
@@ -2682,6 +2708,43 @@ export const toPull: <OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>(
 ) => Effect.Effect<Effect.Effect<Either.Either<OutElem, OutDone>, OutErr, Env>, never, Scope.Scope | Env> =
   channel.toPull
 
+/**
+ * Returns an `Effect` that can be used to repeatedly pull elements from the
+ * constructed `Channel` within the provided `Scope`. The pull effect fails
+ * with the channel's failure in case the channel fails, or returns either the
+ * channel's done value or an emitted element.
+ *
+ * @since 3.11.0
+ * @category destructors
+ */
+export const toPullIn: {
+  /**
+   * Returns an `Effect` that can be used to repeatedly pull elements from the
+   * constructed `Channel` within the provided `Scope`. The pull effect fails
+   * with the channel's failure in case the channel fails, or returns either the
+   * channel's done value or an emitted element.
+   *
+   * @since 3.11.0
+   * @category destructors
+   */
+  (scope: Scope.Scope): <OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>(
+    self: Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>
+  ) => Effect.Effect<Effect.Effect<Either.Either<OutElem, OutDone>, OutErr, Env>, never, Env>
+  /**
+   * Returns an `Effect` that can be used to repeatedly pull elements from the
+   * constructed `Channel` within the provided `Scope`. The pull effect fails
+   * with the channel's failure in case the channel fails, or returns either the
+   * channel's done value or an emitted element.
+   *
+   * @since 3.11.0
+   * @category destructors
+   */
+  <OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>(
+    self: Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>,
+    scope: Scope.Scope
+  ): Effect.Effect<Effect.Effect<Either.Either<OutElem, OutDone>, OutErr, Env>, never, Env>
+} = channel.toPullIn
+
 /**
  * Converts a `Channel` to a `Queue`.
  *
@@ -2721,7 +2784,8 @@ export {
 }
 
 /**
- * Makes a channel from an effect that returns a channel in case of success.
+ * Constructs a `Channel` from an effect that will result in a `Channel` if
+ * successful.
  *
  * @since 2.0.0
  * @category constructors
@@ -2731,7 +2795,8 @@ export const unwrap: <OutElem, InElem, OutErr, InErr, OutDone, InDone, R2, E, R>
 ) => Channel<OutElem, InElem, E | OutErr, InErr, OutDone, InDone, R | R2> = channel.unwrap
 
 /**
- * Makes a channel from a managed that returns a channel in case of success.
+ * Constructs a `Channel` from a scoped effect that will result in a
+ * `Channel` if successful.
  *
  * @since 2.0.0
  * @category constructors
@@ -2740,6 +2805,17 @@ export const unwrapScoped: <OutElem, InElem, OutErr, InErr, OutDone, InDone, Env
   self: Effect.Effect<Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>, E, R>
 ) => Channel<OutElem, InElem, E | OutErr, InErr, OutDone, InDone, Env | Exclude<R, Scope.Scope>> = channel.unwrapScoped
 
+/**
+ * Constructs a `Channel` from a function which receives a `Scope` and returns
+ * an effect that will result in a `Channel` if successful.
+ *
+ * @since 3.11.0
+ * @category constructors
+ */
+export const unwrapScopedWith: <OutElem, InElem, OutErr, InErr, OutDone, InDone, Env, E, R>(
+  f: (scope: Scope.Scope) => Effect.Effect<Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>, E, R>
+) => Channel<OutElem, InElem, E | OutErr, InErr, OutDone, InDone, R | Env> = channel.unwrapScopedWith
+
 /**
  * Updates a service in the context of this channel.
  *