effect 3.12.5 → 3.12.6

package/dist/esm/internal/version.js

@@ -1,4 +1,4 @@
-let moduleVersion = "3.12.5";
+let moduleVersion = "3.12.6";
 export const getCurrentVersion = () => moduleVersion;
 export const setCurrentVersion = version => {
   moduleVersion = version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect",
-  "version": "3.12.5",
+  "version": "3.12.6",
   "description": "The missing standard library for TypeScript, for writing production-grade software.",
   "license": "MIT",
   "repository": {

package/src/Array.ts

@@ -4,7 +4,7 @@
  * @since 2.0.0
  */
 
-import type { Either as array_ } from "./Either.js"
+import type { Either } from "./Either.js"
 import * as E from "./Either.js"
 import * as Equal from "./Equal.js"
 import * as Equivalence from "./Equivalence.js"
@@ -4787,7 +4787,7 @@ export const partitionMap: {
    * @category filtering
    * @since 2.0.0
    */
-  <A, B, C>(f: (a: A, i: number) => array_<C, B>): (self: Iterable<A>) => [left: Array<B>, right: Array<C>]
+  <A, B, C>(f: (a: A, i: number) => Either<C, B>): (self: Iterable<A>) => [left: Array<B>, right: Array<C>]
   /**
    * Applies a function to each element of the `Iterable`, categorizing the results into two separate arrays.
    * This function is particularly useful for operations where each element can result in two possible types,
@@ -4813,10 +4813,10 @@ export const partitionMap: {
    * @category filtering
    * @since 2.0.0
    */
-  <A, B, C>(self: Iterable<A>, f: (a: A, i: number) => array_<C, B>): [left: Array<B>, right: Array<C>]
+  <A, B, C>(self: Iterable<A>, f: (a: A, i: number) => Either<C, B>): [left: Array<B>, right: Array<C>]
 } = dual(
   2,
-  <A, B, C>(self: Iterable<A>, f: (a: A, i: number) => array_<C, B>): [left: Array<B>, right: Array<C>] => {
+  <A, B, C>(self: Iterable<A>, f: (a: A, i: number) => Either<C, B>): [left: Array<B>, right: Array<C>] => {
     const left: Array<B> = []
     const right: Array<C> = []
     const as = fromIterable(self)
@@ -4869,7 +4869,7 @@ export const getSomes: <T extends Iterable<Option<X>>, X = any>(
  * @category filtering
  * @since 2.0.0
  */
-export const getLefts = <T extends Iterable<array_<any, any>>>(self: T): Array<array_.Left<ReadonlyArray.Infer<T>>> => {
+export const getLefts = <T extends Iterable<Either<any, any>>>(self: T): Array<Either.Left<ReadonlyArray.Infer<T>>> => {
   const out: Array<any> = []
   for (const a of self) {
     if (E.isLeft(a)) {
@@ -4896,9 +4896,9 @@ export const getLefts = <T extends Iterable<array_<any, any>>>(self: T): Array<a
  * @category filtering
  * @since 2.0.0
  */
-export const getRights = <T extends Iterable<array_<any, any>>>(
+export const getRights = <T extends Iterable<Either<any, any>>>(
   self: T
-): Array<array_.Right<ReadonlyArray.Infer<T>>> => {
+): Array<Either.Right<ReadonlyArray.Infer<T>>> => {
   const out: Array<any> = []
   for (const a of self) {
     if (E.isRight(a)) {
@@ -4951,6 +4951,17 @@ export const filter: {
 /**
  * Separate elements based on a predicate that also exposes the index of the element.
  *
+ * @example
+ * ```ts
+ * import { Array } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4]
+ *
+ * const result = Array.partition(numbers, n => n % 2 === 0)
+ *
+ * assert.deepStrictEqual(result, [[1, 3], [2, 4]])
+ * ```
+ *
  * @category filtering
  * @since 2.0.0
  */
@@ -4958,6 +4969,17 @@ export const partition: {
   /**
    * Separate elements based on a predicate that also exposes the index of the element.
    *
+   * @example
+   * ```ts
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4]
+   *
+   * const result = Array.partition(numbers, n => n % 2 === 0)
+   *
+   * assert.deepStrictEqual(result, [[1, 3], [2, 4]])
+   * ```
+   *
    * @category filtering
    * @since 2.0.0
    */
@@ -4967,6 +4989,17 @@ export const partition: {
   /**
    * Separate elements based on a predicate that also exposes the index of the element.
    *
+   * @example
+   * ```ts
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4]
+   *
+   * const result = Array.partition(numbers, n => n % 2 === 0)
+   *
+   * assert.deepStrictEqual(result, [[1, 3], [2, 4]])
+   * ```
+   *
    * @category filtering
    * @since 2.0.0
    */
@@ -4976,6 +5009,17 @@ export const partition: {
   /**
    * Separate elements based on a predicate that also exposes the index of the element.
    *
+   * @example
+   * ```ts
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4]
+   *
+   * const result = Array.partition(numbers, n => n % 2 === 0)
+   *
+   * assert.deepStrictEqual(result, [[1, 3], [2, 4]])
+   * ```
+   *
    * @category filtering
    * @since 2.0.0
    */
@@ -4986,6 +5030,17 @@ export const partition: {
   /**
    * Separate elements based on a predicate that also exposes the index of the element.
    *
+   * @example
+   * ```ts
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4]
+   *
+   * const result = Array.partition(numbers, n => n % 2 === 0)
+   *
+   * assert.deepStrictEqual(result, [[1, 3], [2, 4]])
+   * ```
+   *
    * @category filtering
    * @since 2.0.0
    */
@@ -5010,21 +5065,12 @@ export const partition: {
 /**
  * Separates an `Iterable` into two arrays based on a predicate.
  *
- * @example
- * ```ts
- * import { Array } from "effect"
- *
- * const numbers = [1, 2, 3, 4]
- * const result = Array.partition(numbers, n => n % 2 === 0)
- * assert.deepStrictEqual(result, [[1, 3], [2, 4]])
- * ```
- *
  * @category filtering
  * @since 2.0.0
  */
-export const separate: <T extends Iterable<array_<any, any>>>(
+export const separate: <T extends Iterable<Either<any, any>>>(
   self: T
-) => [Array<array_.Left<ReadonlyArray.Infer<T>>>, Array<array_.Right<ReadonlyArray.Infer<T>>>] = partitionMap(
+) => [Array<Either.Left<ReadonlyArray.Infer<T>>>, Array<Either.Right<ReadonlyArray.Infer<T>>>] = partitionMap(
   identity
 )
 
@@ -5296,7 +5342,7 @@ export const flatMapNullable: {
  * @since 2.0.0
  */
 export const liftEither = <A extends Array<unknown>, E, B>(
-  f: (...a: A) => array_<B, E>
+  f: (...a: A) => Either<B, E>
 ) =>
 (...a: A): Array<B> => {
   const e = f(...a)

package/src/Cause.ts

@@ -453,7 +453,7 @@ export const sequential: <E, E2>(left: Cause<E>, right: Cause<E2>) => Cause<E |
  * @since 2.0.0
  * @category refinements
  */
-export const isCause: (u: unknown) => u is Cause<never> = internal.isCause
+export const isCause: (u: unknown) => u is Cause<unknown> = internal.isCause
 
 /**
  * Returns `true` if the specified `Cause` is an `Empty` type, `false`
@@ -1089,8 +1089,32 @@ export const isRuntimeException: (u: unknown) => u is RuntimeException = core.is
 export const TimeoutException: new(message?: string | undefined) => TimeoutException = core.TimeoutException
 
 /**
- * Represents a checked exception which occurs when an unknown error is thrown, such as
- * from a rejected promise.
+ * Creates an instance of `UnknownException`, an error object used to handle
+ * unknown errors such as those from rejected promises.
+ *
+ * **Details**
+ *
+ * This function constructs an `UnknownException` with flexible behavior for
+ * managing the error message and cause.
+ *
+ * The required `error` argument is passed as the `cause` to the global `Error`
+ * constructor, ensuring that the original cause is preserved in the error chain
+ * for debugging purposes. This ensures that the origin stack trace is
+ * preserved.
+ *
+ * The `error` argument is always stored in the `error` property of the
+ * `UnknownException` instance for reference, regardless of its type.
+ *
+ * Additionally, if you provide a `message` argument, it is used as the error
+ * message. If no `message` is provided, the error message defaults to `"An
+ * unknown error occurred"`.
+ *
+ * **When to Use**
+ *
+ * Use this function when you need to handle unexpected or unknown errors in
+ * your application, particularly when the source of the error might not provide
+ * a clear message. This is useful for wrapping generic errors thrown from
+ * promises or external APIs.
  *
  * @since 2.0.0
  * @category errors

package/src/Cron.ts

@@ -2,6 +2,7 @@
  * @since 2.0.0
  */
 import * as Arr from "./Array.js"
+import * as Data from "./Data.js"
 import type * as DateTime from "./DateTime.js"
 import * as Either from "./Either.js"
 import * as Equal from "./Equal.js"
@@ -202,25 +203,14 @@ export type ParseErrorTypeId = typeof ParseErrorTypeId
  * @since 2.0.0
  * @category models
  */
-export interface ParseError {
-  readonly _tag: "ParseError"
-  readonly [ParseErrorTypeId]: ParseErrorTypeId
+export class ParseError extends Data.TaggedError("CronParseError")<{
   readonly message: string
   readonly input?: string
-}
-
-const ParseErrorProto = {
-  _tag: "ParseError",
-  [ParseErrorTypeId]: ParseErrorTypeId
-}
-
-const ParseError = (message: string, input?: string): ParseError => {
-  const o: Mutable<ParseError> = Object.create(ParseErrorProto)
-  o.message = message
-  if (input !== undefined) {
-    o.input = input
-  }
-  return o
+}> {
+  /**
+   * @since 2.0.0
+   */
+  readonly [ParseErrorTypeId] = ParseErrorTypeId
 }
 
 /**
@@ -259,7 +249,12 @@ export const isParseError = (u: unknown): u is ParseError => hasProperty(u, Pars
 export const parse = (cron: string, tz?: DateTime.TimeZone | string): Either.Either<Cron, ParseError> => {
   const segments = cron.split(" ").filter(String.isNonEmpty)
   if (segments.length !== 5 && segments.length !== 6) {
-    return Either.left(ParseError(`Invalid number of segments in cron expression`, cron))
+    return Either.left(
+      new ParseError({
+        message: `Invalid number of segments in cron expression`,
+        input: cron
+      })
+    )
   }
 
   if (segments.length === 5) {
@@ -269,7 +264,11 @@ export const parse = (cron: string, tz?: DateTime.TimeZone | string): Either.Eit
   const [seconds, minutes, hours, days, months, weekdays] = segments
   const zone = tz === undefined || dateTime.isTimeZone(tz) ?
     Either.right(tz) :
-    Either.fromOption(dateTime.zoneFromString(tz), () => ParseError(`Invalid time zone in cron expression`, tz))
+    Either.fromOption(dateTime.zoneFromString(tz), () =>
+      new ParseError({
+        message: `Invalid time zone in cron expression`,
+        input: tz
+      }))
 
   return Either.all({
     tz: zone,
@@ -639,13 +638,13 @@ const parseSegment = (
 
     if (step !== undefined) {
       if (!Number.isInteger(step)) {
-        return Either.left(ParseError(`Expected step value to be a positive integer`, input))
+        return Either.left(new ParseError({ message: `Expected step value to be a positive integer`, input }))
       }
       if (step < 1) {
-        return Either.left(ParseError(`Expected step value to be greater than 0`, input))
+        return Either.left(new ParseError({ message: `Expected step value to be greater than 0`, input }))
       }
       if (step > options.max) {
-        return Either.left(ParseError(`Expected step value to be less than ${options.max}`, input))
+        return Either.left(new ParseError({ message: `Expected step value to be less than ${options.max}`, input }))
       }
     }
 
@@ -656,23 +655,27 @@ const parseSegment = (
     } else {
       const [left, right] = splitRange(raw, options.aliases)
       if (!Number.isInteger(left)) {
-        return Either.left(ParseError(`Expected a positive integer`, input))
+        return Either.left(new ParseError({ message: `Expected a positive integer`, input }))
       }
       if (left < options.min || left > options.max) {
-        return Either.left(ParseError(`Expected a value between ${options.min} and ${options.max}`, input))
+        return Either.left(
+          new ParseError({ message: `Expected a value between ${options.min} and ${options.max}`, input })
+        )
       }
 
       if (right === undefined) {
         values.add(left)
       } else {
         if (!Number.isInteger(right)) {
-          return Either.left(ParseError(`Expected a positive integer`, input))
+          return Either.left(new ParseError({ message: `Expected a positive integer`, input }))
         }
         if (right < options.min || right > options.max) {
-          return Either.left(ParseError(`Expected a value between ${options.min} and ${options.max}`, input))
+          return Either.left(
+            new ParseError({ message: `Expected a value between ${options.min} and ${options.max}`, input })
+          )
         }
         if (left > right) {
-          return Either.left(ParseError(`Invalid value range`, input))
+          return Either.left(new ParseError({ message: `Invalid value range`, input }))
         }
 
         for (let i = left; i <= right; i += step ?? 1) {

package/src/Duration.ts

@@ -41,9 +41,17 @@ export interface Duration extends Equal.Equal, Pipeable, Inspectable {
  * @category models
  */
 export type DurationValue =
-  | { _tag: "Millis"; millis: number }
-  | { _tag: "Nanos"; nanos: bigint }
-  | { _tag: "Infinity" }
+  | {
+    readonly _tag: "Millis"
+    readonly millis: number
+  }
+  | {
+    readonly _tag: "Nanos"
+    readonly nanos: bigint
+  }
+  | {
+    readonly _tag: "Infinity"
+  }
 
 /**
  * @since 2.0.0

package/src/Effect.ts

@@ -15712,13 +15712,14 @@ export {
  * original effect succeeds, the success value is wrapped in `Option.some`. If
  * the effect fails, the failure is converted to `Option.none`.
  *
- * This is useful for handling cases where you want to explicitly represent the
- * absence of a value due to a failure, while preventing direct failure of the
- * resulting effect (its error type is `never`). Note that fatal errors, such as
- * defects, are not wrapped and will still result in failure.
+ * This is particularly useful for scenarios where you want to represent the
+ * absence of a value explicitly, without causing the resulting effect to fail.
+ * The resulting effect has an error type of `never`, meaning it cannot fail
+ * directly. However, unrecoverable errors, also referred to as defects, are
+ * not captured and will still result in failure.
  *
  * @see {@link either} for a version that uses `Either` instead.
- * @see {@link exit} for a version that uses `Exit` instead.
+ * @see {@link exit} for a version that encapsulates both recoverable errors and defects in an `Exit`.
  *
  * @example
  * ```ts
@@ -15768,18 +15769,24 @@ export const option: <A, E, R>(self: Effect<A, E, R>) => Effect<Option.Option<A>
  *
  * This function converts an effect that may fail into an effect that always
  * succeeds, wrapping the outcome in an `Either` type. The result will be
- * `Either.Left` if the effect fails, containing the error, or `Either.Right` if
- * it succeeds, containing the result.
+ * `Either.Left` if the effect fails, containing the recoverable error, or
+ * `Either.Right` if it succeeds, containing the result.
  *
- * Using this function, you can handle errors explicitly without causing the
- * effect to fail. This can be especially useful in scenarios where you want to
- * chain effects and deal with success and failure in the same logical flow.
+ * Using this function, you can handle recoverable errors explicitly without
+ * causing the effect to fail. This is particularly useful in scenarios where
+ * you want to chain effects and manage both success and failure in the same
+ * logical flow.
  *
- * The resulting effect cannot fail directly because failures are represented
- * inside the `Either` type.
+ * It's important to note that unrecoverable errors, often referred to as
+ * "defects," are still thrown and not captured within the `Either` type. Only
+ * failures that are explicitly represented as recoverable errors in the effect
+ * are encapsulated.
+ *
+ * The resulting effect cannot fail directly because all recoverable failures
+ * are represented inside the `Either` type.
  *
  * @see {@link option} for a version that uses `Option` instead.
- * @see {@link exit} for a version that uses `Exit` instead.
+ * @see {@link exit} for a version that encapsulates both recoverable errors and defects in an `Exit`.
  *
  * @example
  * ```ts
@@ -15831,16 +15838,18 @@ export const either: <A, E, R>(self: Effect<A, E, R>) => Effect<Either.Either<A,
  * **Details**
  *
  * This function converts an effect into one that always succeeds, wrapping its
- * outcome in the `Exit` type. The `Exit` type allows explicit handling of both
- * success (`Exit.Success`) and failure (`Exit.Failure`) cases.
+ * outcome in the `Exit` type. The `Exit` type provides explicit handling of
+ * both success (`Exit.Success`) and failure (`Exit.Failure`) cases, including
+ * defects (unrecoverable errors).
  *
- * The failure is no longer propagated directly but encapsulated inside the
- * `Exit.Failure` type. This makes the resulting effect robust and incapable of
- * direct failure (the error type is set to `never`).
+ * Unlike {@link either} or {@link option}, this function also encapsulates
+ * defects, which are typically unrecoverable and would otherwise terminate the
+ * effect. With the `Exit` type, defects are represented in `Exit.Failure`,
+ * allowing for detailed introspection and structured error handling.
  *
- * This function is useful for managing and reasoning about effects with complex
- * outcomes, as it allows for detailed introspection of errors, including
- * defects and unexpected failures.
+ * This makes the resulting effect robust and incapable of direct failure (its
+ * error type is `never`). It is particularly useful for workflows where all
+ * outcomes, including unexpected defects, must be managed and analyzed.
  *
  * @see {@link option} for a version that uses `Option` instead.
  * @see {@link either} for a version that uses `Either` instead.
@@ -26848,6 +26857,9 @@ export const Tag: <const Id extends string>(id: Id) => <
     return makeTagProxy(TagClass as any)
   }
 
+/** @internal */
+type MissingSelfGeneric = `Missing \`Self\` generic - use \`class Self extends Effect.Service<Self>()...\``
+
 /**
  * Simplifies the creation and management of services in Effect by defining both
  * a `Tag` and a `Layer`.
@@ -26892,7 +26904,7 @@ export const Tag: <const Id extends string>(id: Id) => <
  * @category Context
  * @experimental might be up for breaking changes
  */
-export const Service: <Self>() => {
+export const Service: <Self = never>() => [Self] extends [never] ? MissingSelfGeneric : {
   <
     const Key extends string,
     const Make extends
@@ -27065,7 +27077,7 @@ export const Service: <Self>() => {
 
     return proxy === true ? makeTagProxy(TagClass) : TagClass
   }
-}
+} as any
 
 /**
  * @since 3.9.0

package/src/FiberHandle.ts

@@ -90,15 +90,15 @@ const unsafeMake = <A = unknown, E = unknown>(
  * ```ts
  * import { Effect, FiberHandle } from "effect"
  *
- * Effect.gen(function*(_) {
- *   const handle = yield* _(FiberHandle.make())
+ * Effect.gen(function*() {
+ *   const handle = yield* FiberHandle.make()
  *
  *   // run some effects
- *   yield* _(FiberHandle.run(handle, Effect.never))
+ *   yield* FiberHandle.run(handle, Effect.never)
  *   // this will interrupt the previous fiber
- *   yield* _(FiberHandle.run(handle, Effect.never))
+ *   yield* FiberHandle.run(handle, Effect.never)
  *
- *   yield* _(Effect.sleep(1000))
+ *   yield* Effect.sleep(1000)
  * }).pipe(
  *   Effect.scoped // The fiber will be interrupted when the scope is closed
  * )
@@ -434,9 +434,9 @@ export const run: {
  *    getAll: Effect.Effect<Array<unknown>>
  * }>("Users")
  *
- * Effect.gen(function*(_) {
- *   const handle = yield* _(FiberHandle.make())
- *   const run = yield* _(FiberHandle.runtime(handle)<Users>())
+ * Effect.gen(function*() {
+ *   const handle = yield* FiberHandle.make()
+ *   const run = yield* FiberHandle.runtime(handle)<Users>()
  *
  *   // run an effect and set the fiber in the handle
  *   run(Effect.andThen(Users, _ => _.getAll))

package/src/FiberMap.ts

@@ -101,14 +101,14 @@ const unsafeMake = <K, A = unknown, E = unknown>(
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
- * Effect.gen(function*(_) {
- *   const map = yield* _(FiberMap.make<string>())
+ * Effect.gen(function*() {
+ *   const map = yield* FiberMap.make<string>()
  *
  *   // run some effects and add the fibers to the map
- *   yield* _(FiberMap.run(map, "fiber a", Effect.never))
- *   yield* _(FiberMap.run(map, "fiber b", Effect.never))
+ *   yield* FiberMap.run(map, "fiber a", Effect.never)
+ *   yield* FiberMap.run(map, "fiber b", Effect.never)
  *
- *   yield* _(Effect.sleep(1000))
+ *   yield* Effect.sleep(1000)
  * }).pipe(
  *   Effect.scoped // The fibers will be interrupted when the scope is closed
  * )
@@ -619,9 +619,9 @@ export const run: {
  *    getAll: Effect.Effect<Array<unknown>>
  * }>("Users")
  *
- * Effect.gen(function*(_) {
- *   const map = yield* _(FiberMap.make<string>())
- *   const run = yield* _(FiberMap.runtime(map)<Users>())
+ * Effect.gen(function*() {
+ *   const map = yield* FiberMap.make<string>()
+ *   const run = yield* FiberMap.runtime(map)<Users>()
  *
  *   // run some effects and add the fibers to the map
  *   run("effect-a", Effect.andThen(Users, _ => _.getAll))

package/src/FiberSet.ts

@@ -98,14 +98,14 @@ const unsafeMake = <A, E>(
  * ```ts
  * import { Effect, FiberSet } from "effect"
  *
- * Effect.gen(function*(_) {
- *   const set = yield* _(FiberSet.make())
+ * Effect.gen(function*() {
+ *   const set = yield* FiberSet.make()
  *
  *   // run some effects and add the fibers to the set
- *   yield* _(FiberSet.run(set, Effect.never))
- *   yield* _(FiberSet.run(set, Effect.never))
+ *   yield* FiberSet.run(set, Effect.never)
+ *   yield* FiberSet.run(set, Effect.never)
  *
- *   yield* _(Effect.sleep(1000))
+ *   yield* Effect.sleep(1000)
  * }).pipe(
  *   Effect.scoped // The fibers will be interrupted when the scope is closed
  * )
@@ -372,9 +372,9 @@ export const run: {
  *    getAll: Effect.Effect<Array<unknown>>
  * }>("Users")
  *
- * Effect.gen(function*(_) {
- *   const set = yield* _(FiberSet.make())
- *   const run = yield* _(FiberSet.runtime(set)<Users>())
+ * Effect.gen(function*() {
+ *   const set = yield* FiberSet.make()
+ *   const run = yield* FiberSet.runtime(set)<Users>()
  *
  *   // run some effects and add the fibers to the set
  *   run(Effect.andThen(Users, _ => _.getAll))