effect 3.1.1 → 3.1.2

package/src/Context.ts

@@ -99,7 +99,7 @@ export declare namespace Tag {
  * @param key - A key that will be used to compare tags.
  *
  * @example
- * import * as Context from "effect/Context"
+ * import { Context } from "effect"
  *
  * assert.strictEqual(Context.GenericTag("PORT").key === Context.GenericTag("PORT").key, true)
  *
@@ -146,7 +146,7 @@ export const unsafeMake: <Services>(unsafeMap: Map<string, any>) => Context<Serv
  * @param input - The value to be checked if it is a `Context`.
  *
  * @example
- * import * as Context from "effect/Context"
+ * import { Context } from "effect"
  *
  * assert.strictEqual(Context.isContext(Context.empty()), true)
  *
@@ -161,7 +161,7 @@ export const isContext: (input: unknown) => input is Context<never> = internal.i
  * @param input - The value to be checked if it is a `Tag`.
  *
  * @example
- * import * as Context from "effect/Context"
+ * import { Context } from "effect"
  *
  * assert.strictEqual(Context.isTag(Context.GenericTag("Tag")), true)
  *
@@ -174,7 +174,7 @@ export const isTag: (input: unknown) => input is Tag<any, any> = internal.isTag
  * Returns an empty `Context`.
  *
  * @example
- * import * as Context from "effect/Context"
+ * import { Context } from "effect"
  *
  * assert.strictEqual(Context.isContext(Context.empty()), true)
  *
@@ -187,7 +187,7 @@ export const empty: () => Context<never> = internal.empty
  * Creates a new `Context` with a single service associated to the tag.
  *
  * @example
- * import * as Context from "effect/Context"
+ * import { Context } from "effect"
  *
  * const Port = Context.GenericTag<{ PORT: number }>("Port")
  *
@@ -205,8 +205,7 @@ export const make: <T extends Tag<any, any>>(tag: T, service: Tag.Service<T>) =>
  * Adds a service to a given `Context`.
  *
  * @example
- * import * as Context from "effect/Context"
- * import { pipe } from "effect/Function"
+ * import { Context, pipe } from "effect"
  *
  * const Port = Context.GenericTag<{ PORT: number }>("Port")
  * const Timeout = Context.GenericTag<{ TIMEOUT: number }>("Timeout")
@@ -242,8 +241,7 @@ export const add: {
  * @param tag - The `Tag` of the service to retrieve.
  *
  * @example
- * import * as Context from "effect/Context"
- * import { pipe } from "effect/Function"
+ * import { pipe, Context } from "effect"
  *
  * const Port = Context.GenericTag<{ PORT: number }>("Port")
  * const Timeout = Context.GenericTag<{ TIMEOUT: number }>("Timeout")
@@ -273,7 +271,7 @@ export const get: {
  * @param tag - The `Tag` of the service to retrieve.
  *
  * @example
- * import * as Context from "effect/Context"
+ * import { Context } from "effect"
  *
  * const Port = Context.GenericTag<{ PORT: number }>("Port")
  * const Timeout = Context.GenericTag<{ TIMEOUT: number }>("Timeout")
@@ -299,16 +297,15 @@ export const unsafeGet: {
  * @param tag - The `Tag` of the service to retrieve.
  *
  * @example
- * import * as Context from "effect/Context"
- * import * as O from "effect/Option"
+ * import { Context, Option } from "effect"
  *
  * const Port = Context.GenericTag<{ PORT: number }>("Port")
  * const Timeout = Context.GenericTag<{ TIMEOUT: number }>("Timeout")
  *
  * const Services = Context.make(Port, { PORT: 8080 })
  *
- * assert.deepStrictEqual(Context.getOption(Services, Port), O.some({ PORT: 8080 }))
- * assert.deepStrictEqual(Context.getOption(Services, Timeout), O.none())
+ * assert.deepStrictEqual(Context.getOption(Services, Port), Option.some({ PORT: 8080 }))
+ * assert.deepStrictEqual(Context.getOption(Services, Timeout), Option.none())
  *
  * @since 2.0.0
  * @category getters
@@ -325,7 +322,7 @@ export const getOption: {
  * @param that - The second `Context` to merge.
  *
  * @example
- * import * as Context from "effect/Context"
+ * import { Context } from "effect"
  *
  * const Port = Context.GenericTag<{ PORT: number }>("Port")
  * const Timeout = Context.GenericTag<{ TIMEOUT: number }>("Timeout")
@@ -352,9 +349,7 @@ export const merge: {
  * @param tags - The list of `Tag`s to be included in the new `Context`.
  *
  * @example
- * import * as Context from "effect/Context"
- * import { pipe } from "effect/Function"
- * import * as O from "effect/Option"
+ * import { pipe, Context, Option } from "effect"
  *
  * const Port = Context.GenericTag<{ PORT: number }>("Port")
  * const Timeout = Context.GenericTag<{ TIMEOUT: number }>("Timeout")
@@ -366,8 +361,8 @@ export const merge: {
  *
  * const Services = pipe(someContext, Context.pick(Port))
  *
- * assert.deepStrictEqual(Context.getOption(Services, Port), O.some({ PORT: 8080 }))
- * assert.deepStrictEqual(Context.getOption(Services, Timeout), O.none())
+ * assert.deepStrictEqual(Context.getOption(Services, Port), Option.some({ PORT: 8080 }))
+ * assert.deepStrictEqual(Context.getOption(Services, Timeout), Option.none())
  *
  * @since 2.0.0
  */

package/src/Cron.ts

@@ -170,8 +170,7 @@ export const isParseError = (u: unknown): u is ParseError => hasProperty(u, Pars
  * @param cron - The cron expression to parse.
  *
  * @example
- * import * as Cron from "effect/Cron"
- * import * as Either from "effect/Either"
+ * import { Cron, Either } from "effect"
  *
  * // At 04:00 on every day-of-month from 8 through 14.
  * assert.deepStrictEqual(Cron.parse("0 4 8-14 * *"), Either.right(Cron.make({
@@ -208,8 +207,7 @@ export const parse = (cron: string): Either.Either<Cron, ParseError> => {
  * @param date - The `Date` to check against.
  *
  * @example
- * import * as Cron from "effect/Cron"
- * import * as Either from "effect/Either"
+ * import { Cron, Either } from "effect"
  *
  * const cron = Either.getOrThrow(Cron.parse("0 4 8-14 * *"))
  * assert.deepStrictEqual(Cron.match(cron, new Date("2021-01-08 04:00:00")), true)
@@ -258,8 +256,7 @@ export const match = (cron: Cron, date: Date): boolean => {
  * Uses the current time as a starting point if no value is provided for `now`.
  *
  * @example
- * import * as Cron from "effect/Cron"
- * import * as Either from "effect/Either"
+ * import { Cron, Either } from "effect"
  *
  * const after = new Date("2021-01-01 00:00:00")
  * const cron = Either.getOrThrow(Cron.parse("0 4 8-14 * *"))

package/src/Data.ts

@@ -26,8 +26,7 @@ export declare namespace Case {
 
 /**
  * @example
- * import * as Data from "effect/Data"
- * import * as Equal from "effect/Equal"
+ * import { Data, Equal } from "effect"
  *
  * const alice = Data.struct({ name: "Alice", age: 30 })
  *
@@ -53,8 +52,7 @@ export const unsafeStruct = <A extends Record<string, any>>(as: A): { readonly [
 
 /**
  * @example
- * import * as Data from "effect/Data"
- * import * as Equal from "effect/Equal"
+ * import { Data, Equal } from "effect"
  *
  * const alice = Data.tuple("Alice", 30)
  *
@@ -73,8 +71,7 @@ export const tuple = <As extends ReadonlyArray<any>>(...as: As): Readonly<As> =>
 
 /**
  * @example
- * import * as Data from "effect/Data"
- * import * as Equal from "effect/Equal"
+ * import { Data, Equal } from "effect"
  *
  * const alice = Data.struct({ name: "Alice", age: 30 })
  * const bob = Data.struct({ name: "Bob", age: 40 })
@@ -112,8 +109,7 @@ export {
    * Provides a constructor for the specified `Case`.
    *
    * @example
-   * import * as Data from "effect/Data"
-   * import * as Equal from "effect/Equal"
+   * import { Data, Equal } from "effect"
    *
    * interface Person {
    *   readonly name: string
@@ -141,7 +137,7 @@ export {
  * Provides a tagged constructor for the specified `Case`.
  *
  * @example
- * import * as Data from "effect/Data"
+ * import { Data } from "effect"
  *
  * interface Person {
  *   readonly _tag: "Person" // the tag
@@ -170,8 +166,7 @@ export const tagged = <A extends { readonly _tag: string }>(
  * Provides a constructor for a Case Class.
  *
  * @example
- * import * as Data from "effect/Data"
- * import * as Equal from "effect/Equal"
+ * import { Data, Equal } from "effect"
  *
  * class Person extends Data.Class<{ readonly name: string }> {}
  *
@@ -196,8 +191,7 @@ export const Class: new<A extends Record<string, any> = {}>(
  * Provides a Tagged constructor for a Case Class.
  *
  * @example
- * import * as Data from "effect/Data"
- * import * as Equal from "effect/Equal"
+ * import { Data, Equal } from "effect"
  *
  * class Person extends Data.TaggedClass("Person")<{ readonly name: string }> {}
  *
@@ -240,7 +234,7 @@ export const Structural: new<A>(
  * Create a tagged enum data type, which is a union of `Data` structs.
  *
  * ```ts
- * import * as Data from "effect/Data"
+ * import { Data } from "effect"
  *
  * type HttpError = Data.TaggedEnum<{
  *   BadRequest: { readonly status: 400, readonly message: string }
@@ -358,7 +352,7 @@ export declare namespace TaggedEnum {
  * the constructor.
  *
  * @example
- * import * as Data from "effect/Data"
+ * import { Data } from "effect"
  *
  * const { BadRequest, NotFound } = Data.taggedEnum<
  *   | { readonly _tag: "BadRequest"; readonly status: 400; readonly message: string }
@@ -368,7 +362,7 @@ export declare namespace TaggedEnum {
  * const notFound = NotFound({ status: 404, message: "Not Found" })
  *
  * @example
- * import * as Data from "effect/Data"
+ * import { Data } from "effect"
  *
  * type MyResult<E, A> = Data.TaggedEnum<{
  *   Failure: { readonly error: E }

package/src/Duration.ts

@@ -694,7 +694,7 @@ export const equals: {
  * @since 2.0.0
  *
  * @example
- * import * as Duration from "effect/Duration"
+ * import { Duration } from "effect"
  *
  * Duration.format(Duration.millis(1000)) // "1s"
  * Duration.format(Duration.millis(1001)) // "1s 1ms"

package/src/Effect.ts

@@ -56,7 +56,7 @@ import * as Scheduler from "./Scheduler.js"
 import type * as Scope from "./Scope.js"
 import type * as Supervisor from "./Supervisor.js"
 import type * as Tracer from "./Tracer.js"
-import type { Concurrency, Covariant, MergeRecord, NoInfer, NotFunction } from "./Types.js"
+import type { Concurrency, Covariant, NoInfer, NotFunction } from "./Types.js"
 import type * as Unify from "./Unify.js"
 import type { YieldWrap } from "./Utils.js"
 
@@ -321,8 +321,7 @@ export const cachedFunction: <A, B, E, R>(
  * evaluated multiple times.
  *
  * @example
- * import * as Effect from "effect/Effect"
- * import * as Console from "effect/Console"
+ * import { Effect, Console } from "effect"
  *
  * const program = Effect.gen(function* (_) {
  *   const twice = Console.log("twice")
@@ -958,8 +957,7 @@ export const validateAll: {
  * If `elements` is empty then `Effect.fail([])` is returned.
  *
  * @example
- * import * as Effect from "effect/Effect"
- * import * as Exit from "effect/Exit"
+ * import { Effect, Exit } from "effect"
  *
  * const f = (n: number) => (n > 0 ? Effect.succeed(n) : Effect.fail(`${n} is negative`))
  *
@@ -1035,7 +1033,7 @@ export const asyncEffect: <A, E, R, R3, E2, R2>(
  * It is meant to be called with a bag of instructions that become available in the "this" of the effect.
  *
  * @example
- * import * as Effect from "effect/Effect"
+ * import { Effect } from "effect"
  *
  * const throwingFunction = () => { throw new Error() }
  * const blowUp = Effect.custom(throwingFunction, function() {
@@ -3263,56 +3261,148 @@ export const updateService: {
 // -------------------------------------------------------------------------------------
 
 /**
- * @since 2.0.0
+ * The "do simulation" in allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+ *
+ * Here's how the do simulation works:
+ *
+ * 1. Start the do simulation using the `Do` value
+ * 2. Within the do simulation scope, you can use the `bind` function to define variables and bind them to `Effect` values
+ * 3. You can accumulate multiple `bind` statements to define multiple variables within the scope
+ * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
+ *
+ * @see {@link bind}
+ * @see {@link bindTo}
+ * @see {@link let_ let}
+ *
+ * @example
+ * import { Effect, pipe } from "effect"
+ *
+ * const result = pipe(
+ *   Effect.Do,
+ *   Effect.bind("x", () => Effect.succeed(2)),
+ *   Effect.bind("y", () => Effect.succeed(3)),
+ *   Effect.let("sum", ({ x, y }) => x + y)
+ * )
+ * assert.deepStrictEqual(Effect.runSync(result), { x: 2, y: 3, sum: 5 })
+ *
  * @category do notation
+ * @since 2.0.0
  */
 export const Do: Effect<{}> = effect.Do
 
 /**
- * Binds an effectful value in a `do` scope
+ * The "do simulation" in allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+ *
+ * Here's how the do simulation works:
+ *
+ * 1. Start the do simulation using the `Do` value
+ * 2. Within the do simulation scope, you can use the `bind` function to define variables and bind them to `Effect` values
+ * 3. You can accumulate multiple `bind` statements to define multiple variables within the scope
+ * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
+ *
+ * @see {@link Do}
+ * @see {@link bindTo}
+ * @see {@link let_ let}
+ *
+ * @example
+ * import { Effect, pipe } from "effect"
+ *
+ * const result = pipe(
+ *   Effect.Do,
+ *   Effect.bind("x", () => Effect.succeed(2)),
+ *   Effect.bind("y", () => Effect.succeed(3)),
+ *   Effect.let("sum", ({ x, y }) => x + y)
+ * )
+ * assert.deepStrictEqual(Effect.runSync(result), { x: 2, y: 3, sum: 5 })
  *
- * @since 2.0.0
  * @category do notation
+ * @since 2.0.0
  */
 export const bind: {
-  <N extends string, K, A, E2, R2>(
-    tag: Exclude<N, keyof K>,
-    f: (_: K) => Effect<A, E2, R2>
-  ): <E, R>(self: Effect<K, E, R>) => Effect<MergeRecord<K, { [k in N]: A }>, E2 | E, R2 | R>
-  <K, E, R, N extends string, A, E2, R2>(
-    self: Effect<K, E, R>,
-    tag: Exclude<N, keyof K>,
-    f: (_: K) => Effect<A, E2, R2>
-  ): Effect<MergeRecord<K, { [k in N]: A }>, E2 | E, R2 | R>
+  <N extends string, A extends object, B, E2, R2>(
+    name: Exclude<N, keyof A>,
+    f: (a: A) => Effect<B, E2, R2>
+  ): <E1, R1>(self: Effect<A, E1, R1>) => Effect<{ [K in N | keyof A]: K extends keyof A ? A[K] : B }, E2 | E1, R2 | R1>
+  <A extends object, N extends string, E1, R1, B, E2, R2>(
+    self: Effect<A, E1, R1>,
+    name: Exclude<N, keyof A>,
+    f: (a: A) => Effect<B, E2, R2>
+  ): Effect<{ [K in N | keyof A]: K extends keyof A ? A[K] : B }, E1 | E2, R1 | R2>
 } = effect.bind
 
 /**
+ * The "do simulation" in allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+ *
+ * Here's how the do simulation works:
+ *
+ * 1. Start the do simulation using the `Do` value
+ * 2. Within the do simulation scope, you can use the `bind` function to define variables and bind them to `Effect` values
+ * 3. You can accumulate multiple `bind` statements to define multiple variables within the scope
+ * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
+ *
+ * @see {@link Do}
+ * @see {@link bind}
+ * @see {@link let_ let}
+ *
+ * @example
+ * import { Effect, pipe } from "effect"
+ *
+ * const result = pipe(
+ *   Effect.Do,
+ *   Effect.bind("x", () => Effect.succeed(2)),
+ *   Effect.bind("y", () => Effect.succeed(3)),
+ *   Effect.let("sum", ({ x, y }) => x + y)
+ * )
+ * assert.deepStrictEqual(Effect.runSync(result), { x: 2, y: 3, sum: 5 })
+ *
  * @category do notation
  * @since 2.0.0
  */
 export const bindTo: {
-  <N extends string>(tag: N): <A, E, R>(self: Effect<A, E, R>) => Effect<Record<N, A>, E, R>
-  <A, E, R, N extends string>(self: Effect<A, E, R>, tag: N): Effect<Record<N, A>, E, R>
+  <N extends string>(name: N): <A, E, R>(self: Effect<A, E, R>) => Effect<{ [K in N]: A }, E, R>
+  <A, E, R, N extends string>(self: Effect<A, E, R>, name: N): Effect<{ [K in N]: A }, E, R>
 } = effect.bindTo
 
 const let_: {
-  <N extends string, K, A>(
-    tag: Exclude<N, keyof K>,
-    f: (_: K) => A
-  ): <E, R>(self: Effect<K, E, R>) => Effect<MergeRecord<K, { [k in N]: A }>, E, R>
-  <K, E, R, N extends string, A>(
-    self: Effect<K, E, R>,
-    tag: Exclude<N, keyof K>,
-    f: (_: K) => A
-  ): Effect<MergeRecord<K, { [k in N]: A }>, E, R>
+  <N extends string, A extends object, B>(
+    name: Exclude<N, keyof A>,
+    f: (a: A) => B
+  ): <E, R>(self: Effect<A, E, R>) => Effect<{ [K in N | keyof A]: K extends keyof A ? A[K] : B }, E, R>
+  <A extends object, N extends string, E, R, B>(
+    self: Effect<A, E, R>,
+    name: Exclude<N, keyof A>,
+    f: (a: A) => B
+  ): Effect<{ [K in N | keyof A]: K extends keyof A ? A[K] : B }, E, R>
 } = effect.let_
 
 export {
   /**
-   * Like bind for values
+   * The "do simulation" in allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+   *
+   * Here's how the do simulation works:
+   *
+   * 1. Start the do simulation using the `Do` value
+   * 2. Within the do simulation scope, you can use the `bind` function to define variables and bind them to `Effect` values
+   * 3. You can accumulate multiple `bind` statements to define multiple variables within the scope
+   * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
+   *
+   * @see {@link Do}
+   * @see {@link bind}
+   * @see {@link bindTo}
+   *
+   * @example
+   * import { Effect, pipe } from "effect"
+   *
+   * const result = pipe(
+   *   Effect.Do,
+   *   Effect.bind("x", () => Effect.succeed(2)),
+   *   Effect.bind("y", () => Effect.succeed(3)),
+   *   Effect.let("sum", ({ x, y }) => x + y)
+   * )
+   * assert.deepStrictEqual(Effect.runSync(result), { x: 2, y: 3, sum: 5 })
    *
-   * @since 2.0.0
    * @category do notation
+   * @since 2.0.0
    */
   let_ as let
 }
@@ -3628,7 +3718,7 @@ export const flatMap: {
  * - a function returning an effect
  *
  * @example
- * import * as Effect from "effect/Effect"
+ * import { Effect } from "effect"
  *
  * assert.deepStrictEqual(Effect.runSync(Effect.succeed("aa").pipe(Effect.andThen(1))), 1)
  * assert.deepStrictEqual(Effect.runSync(Effect.succeed("aa").pipe(Effect.andThen((s) => s.length))), 2)