effect 4.0.6 → 4.1.0

package/src/Data.ts

@@ -392,13 +392,14 @@ export declare namespace TaggedEnum {
    * @category utility types
    * @since 3.1.0
    */
-  export type Constructor<A extends { readonly _tag: string }> = Types.Simplify<
-    {
+  export type Constructor<A extends { readonly _tag: string }> =
+    & {
       readonly [Tag in A["_tag"]]: ConstructorFrom<
         Extract<A, { readonly _tag: Tag }>,
         "_tag"
       >
-    } & {
+    }
+    & {
       readonly $is: <Tag extends A["_tag"]>(
         tag: Tag
       ) => (u: unknown) => u is Extract<A, { readonly _tag: Tag }>
@@ -424,7 +425,6 @@ export declare namespace TaggedEnum {
         ): Unify<ReturnType<Cases[A["_tag"]]>>
       }
     }
-  >
 
   /**
    * Function type that constructs a tagged-union variant from its fields,
@@ -446,6 +446,61 @@ export declare namespace TaggedEnum {
     args: Types.VoidIfEmpty<{ readonly [P in keyof A as P extends Tag ? never : P]: A[P] }>
   ) => A
 
+  /**
+   * The full constructors-and-matchers object type returned by {@link taggedEnum}
+   * for a {@link WithGenerics} definition.
+   *
+   * **When to use**
+   *
+   * Use when you want to annotate an exported constructor bundle for a generic
+   * tagged enum.
+   *
+   * **Details**
+   *
+   * Includes one generic constructor per variant (keyed by tag name) plus the
+   * `$is` / `$match` helpers from {@link GenericMatchers}.
+   *
+   * @see {@link Constructor} — the non-generic equivalent
+   * @see {@link GenericCaseConstructor} — the constructor for one variant
+   *
+   * @category utility types
+   * @since 4.0.7
+   */
+  export type GenericConstructor<Z extends WithGenerics<1 | 2 | 3 | 4>> =
+    & {
+      readonly [Tag in Z["taggedEnum"]["_tag"]]: GenericCaseConstructor<Z, Tag>[Z["numberOfGenerics"]]
+    }
+    & GenericMatchers<Z>
+
+  /**
+   * The generic constructors for one variant of a {@link WithGenerics}
+   * definition, keyed by the number of generics.
+   *
+   * **When to use**
+   *
+   * Use to type an individual constructor for one variant of a generic tagged
+   * enum, by indexing with the definition's `numberOfGenerics`.
+   *
+   * @see {@link GenericConstructor} — the full constructor object type
+   *
+   * @category utility types
+   * @since 4.0.7
+   */
+  export interface GenericCaseConstructor<Z extends WithGenerics<number>, Tag extends Z["taggedEnum"]["_tag"]> {
+    readonly 1: <A>(
+      args: Args<Kind<Z, A>, Tag, Extract<Kind<Z, A>, { readonly _tag: Tag }>>
+    ) => Value<Kind<Z, A>, Tag>
+    readonly 2: <A, B>(
+      args: Args<Kind<Z, A, B>, Tag, Extract<Kind<Z, A, B>, { readonly _tag: Tag }>>
+    ) => Value<Kind<Z, A, B>, Tag>
+    readonly 3: <A, B, C>(
+      args: Args<Kind<Z, A, B, C>, Tag, Extract<Kind<Z, A, B, C>, { readonly _tag: Tag }>>
+    ) => Value<Kind<Z, A, B, C>, Tag>
+    readonly 4: <A, B, C, D>(
+      args: Args<Kind<Z, A, B, C, D>, Tag, Extract<Kind<Z, A, B, C, D>, { readonly _tag: Tag }>>
+    ) => Value<Kind<Z, A, B, C, D>, Tag>
+  }
+
   /**
    * Type-guard and pattern-matching interface for generic tagged enums.
    *
@@ -655,267 +710,7 @@ export const taggedEnum: {
    * @category constructors
    * @since 2.0.0
    */
-  <Z extends TaggedEnum.WithGenerics<1>>(): Types.Simplify<
-    {
-      readonly [Tag in Z["taggedEnum"]["_tag"]]: <A>(
-        args: TaggedEnum.Args<
-          TaggedEnum.Kind<Z, A>,
-          Tag,
-          Extract<TaggedEnum.Kind<Z, A>, { readonly _tag: Tag }>
-        >
-      ) => TaggedEnum.Value<TaggedEnum.Kind<Z, A>, Tag>
-    } & TaggedEnum.GenericMatchers<Z>
-  >
-
-  /**
-   * Creates constructors and matchers for a `TaggedEnum` type.
-   *
-   * **When to use**
-   *
-   * Use when you model a closed union with plain data objects and want
-   * construction, tag checks, and exhaustive matching from the same definition.
-   *
-   * **Details**
-   *
-   * Returns an object with:
-   * - One constructor per variant (keyed by tag name)
-   * - `$is(tag)` — returns a type-guard function that checks only the `_tag` field
-   * - `$match` — exhaustive pattern matching (data-first or data-last)
-   *
-   * **Gotchas**
-   *
-   * - Constructors produce **plain objects**, not class instances.
-   * - `$is(tag)` only checks the `_tag` field, not the full structure. It relies
-   *   on the tag being globally unique and the value being produced by your
-   *   constructors. For untrusted input, validate with the `Schema` module first.
-   *
-   * **Example** (Creating and matching tagged enum values)
-   *
-   * ```ts import.meta.vitest
-   * import { Data } from "effect"
-   *
-   * type HttpError = Data.TaggedEnum<{
-   *   BadRequest: { readonly message: string }
-   *   NotFound: { readonly url: string }
-   * }>
-   *
-   * const { BadRequest, NotFound, $is, $match } = Data.taggedEnum<HttpError>()
-   *
-   * const err = NotFound({ url: "/missing" })
-   *
-   * $is("NotFound")(err) // => true
-   *
-   * $match(err, {
-   *   BadRequest: (e) => e.message,
-   *   NotFound: (e) => `${e.url} not found`
-   * }) // => "/missing not found"
-   * ```
-   *
-   * **Example** (Defining a generic tagged enum)
-   *
-   * ```ts import.meta.vitest
-   * import { Data } from "effect"
-   *
-   * type MyResult<E, A> = Data.TaggedEnum<{
-   *   Failure: { readonly error: E }
-   *   Success: { readonly value: A }
-   * }>
-   * interface MyResultDef extends Data.TaggedEnum.WithGenerics<2> {
-   *   readonly taggedEnum: MyResult<this["A"], this["B"]>
-   * }
-   * const { Failure, Success } = Data.taggedEnum<MyResultDef>()
-   *
-   * const ok = Success({ value: 42 })
-   * // ok: { readonly _tag: "Success"; readonly value: number }
-   * ok // => { value: 42, _tag: "Success" }
-   * ```
-   *
-   * @see {@link TaggedEnum} — the type-level companion
-   * @see {@link TaggedEnum.Constructor} — the returned object type
-   * @see {@link TaggedEnum.WithGenerics} — generic enum support
-   *
-   * @stability stable
-   * @category constructors
-   * @since 2.0.0
-   */
-  <Z extends TaggedEnum.WithGenerics<2>>(): Types.Simplify<
-    {
-      readonly [Tag in Z["taggedEnum"]["_tag"]]: <A, B>(
-        args: TaggedEnum.Args<
-          TaggedEnum.Kind<Z, A, B>,
-          Tag,
-          Extract<TaggedEnum.Kind<Z, A, B>, { readonly _tag: Tag }>
-        >
-      ) => TaggedEnum.Value<TaggedEnum.Kind<Z, A, B>, Tag>
-    } & TaggedEnum.GenericMatchers<Z>
-  >
-
-  /**
-   * Creates constructors and matchers for a `TaggedEnum` type.
-   *
-   * **When to use**
-   *
-   * Use when you model a closed union with plain data objects and want
-   * construction, tag checks, and exhaustive matching from the same definition.
-   *
-   * **Details**
-   *
-   * Returns an object with:
-   * - One constructor per variant (keyed by tag name)
-   * - `$is(tag)` — returns a type-guard function that checks only the `_tag` field
-   * - `$match` — exhaustive pattern matching (data-first or data-last)
-   *
-   * **Gotchas**
-   *
-   * - Constructors produce **plain objects**, not class instances.
-   * - `$is(tag)` only checks the `_tag` field, not the full structure. It relies
-   *   on the tag being globally unique and the value being produced by your
-   *   constructors. For untrusted input, validate with the `Schema` module first.
-   *
-   * **Example** (Creating and matching tagged enum values)
-   *
-   * ```ts import.meta.vitest
-   * import { Data } from "effect"
-   *
-   * type HttpError = Data.TaggedEnum<{
-   *   BadRequest: { readonly message: string }
-   *   NotFound: { readonly url: string }
-   * }>
-   *
-   * const { BadRequest, NotFound, $is, $match } = Data.taggedEnum<HttpError>()
-   *
-   * const err = NotFound({ url: "/missing" })
-   *
-   * $is("NotFound")(err) // => true
-   *
-   * $match(err, {
-   *   BadRequest: (e) => e.message,
-   *   NotFound: (e) => `${e.url} not found`
-   * }) // => "/missing not found"
-   * ```
-   *
-   * **Example** (Defining a generic tagged enum)
-   *
-   * ```ts import.meta.vitest
-   * import { Data } from "effect"
-   *
-   * type MyResult<E, A> = Data.TaggedEnum<{
-   *   Failure: { readonly error: E }
-   *   Success: { readonly value: A }
-   * }>
-   * interface MyResultDef extends Data.TaggedEnum.WithGenerics<2> {
-   *   readonly taggedEnum: MyResult<this["A"], this["B"]>
-   * }
-   * const { Failure, Success } = Data.taggedEnum<MyResultDef>()
-   *
-   * const ok = Success({ value: 42 })
-   * // ok: { readonly _tag: "Success"; readonly value: number }
-   * ok // => { value: 42, _tag: "Success" }
-   * ```
-   *
-   * @see {@link TaggedEnum} — the type-level companion
-   * @see {@link TaggedEnum.Constructor} — the returned object type
-   * @see {@link TaggedEnum.WithGenerics} — generic enum support
-   *
-   * @stability stable
-   * @category constructors
-   * @since 2.0.0
-   */
-  <Z extends TaggedEnum.WithGenerics<3>>(): Types.Simplify<
-    {
-      readonly [Tag in Z["taggedEnum"]["_tag"]]: <A, B, C>(
-        args: TaggedEnum.Args<
-          TaggedEnum.Kind<Z, A, B, C>,
-          Tag,
-          Extract<TaggedEnum.Kind<Z, A, B, C>, { readonly _tag: Tag }>
-        >
-      ) => TaggedEnum.Value<TaggedEnum.Kind<Z, A, B, C>, Tag>
-    } & TaggedEnum.GenericMatchers<Z>
-  >
-
-  /**
-   * Creates constructors and matchers for a `TaggedEnum` type.
-   *
-   * **When to use**
-   *
-   * Use when you model a closed union with plain data objects and want
-   * construction, tag checks, and exhaustive matching from the same definition.
-   *
-   * **Details**
-   *
-   * Returns an object with:
-   * - One constructor per variant (keyed by tag name)
-   * - `$is(tag)` — returns a type-guard function that checks only the `_tag` field
-   * - `$match` — exhaustive pattern matching (data-first or data-last)
-   *
-   * **Gotchas**
-   *
-   * - Constructors produce **plain objects**, not class instances.
-   * - `$is(tag)` only checks the `_tag` field, not the full structure. It relies
-   *   on the tag being globally unique and the value being produced by your
-   *   constructors. For untrusted input, validate with the `Schema` module first.
-   *
-   * **Example** (Creating and matching tagged enum values)
-   *
-   * ```ts import.meta.vitest
-   * import { Data } from "effect"
-   *
-   * type HttpError = Data.TaggedEnum<{
-   *   BadRequest: { readonly message: string }
-   *   NotFound: { readonly url: string }
-   * }>
-   *
-   * const { BadRequest, NotFound, $is, $match } = Data.taggedEnum<HttpError>()
-   *
-   * const err = NotFound({ url: "/missing" })
-   *
-   * $is("NotFound")(err) // => true
-   *
-   * $match(err, {
-   *   BadRequest: (e) => e.message,
-   *   NotFound: (e) => `${e.url} not found`
-   * }) // => "/missing not found"
-   * ```
-   *
-   * **Example** (Defining a generic tagged enum)
-   *
-   * ```ts import.meta.vitest
-   * import { Data } from "effect"
-   *
-   * type MyResult<E, A> = Data.TaggedEnum<{
-   *   Failure: { readonly error: E }
-   *   Success: { readonly value: A }
-   * }>
-   * interface MyResultDef extends Data.TaggedEnum.WithGenerics<2> {
-   *   readonly taggedEnum: MyResult<this["A"], this["B"]>
-   * }
-   * const { Failure, Success } = Data.taggedEnum<MyResultDef>()
-   *
-   * const ok = Success({ value: 42 })
-   * // ok: { readonly _tag: "Success"; readonly value: number }
-   * ok // => { value: 42, _tag: "Success" }
-   * ```
-   *
-   * @see {@link TaggedEnum} — the type-level companion
-   * @see {@link TaggedEnum.Constructor} — the returned object type
-   * @see {@link TaggedEnum.WithGenerics} — generic enum support
-   *
-   * @stability stable
-   * @category constructors
-   * @since 2.0.0
-   */
-  <Z extends TaggedEnum.WithGenerics<4>>(): Types.Simplify<
-    {
-      readonly [Tag in Z["taggedEnum"]["_tag"]]: <A, B, C, D>(
-        args: TaggedEnum.Args<
-          TaggedEnum.Kind<Z, A, B, C, D>,
-          Tag,
-          Extract<TaggedEnum.Kind<Z, A, B, C, D>, { readonly _tag: Tag }>
-        >
-      ) => TaggedEnum.Value<TaggedEnum.Kind<Z, A, B, C, D>, Tag>
-    } & TaggedEnum.GenericMatchers<Z>
-  >
-
+  <Z extends TaggedEnum.WithGenerics<1 | 2 | 3 | 4>>(): TaggedEnum.GenericConstructor<Z>
   /**
    * Creates constructors and matchers for a `TaggedEnum` type.
    *

package/src/Duration.ts

@@ -848,6 +848,30 @@ export const days = (days: number): Duration => make(days * 86_400_000)
  */
 export const weeks = (weeks: number): Duration => make(weeks * 604_800_000)
 
+/**
+ * Converts a Duration to microseconds.
+ *
+ * **Example** (Converting durations to microseconds)
+ *
+ * ```ts import.meta.vitest
+ * import { Duration } from "effect"
+ *
+ * Duration.toMicros(Duration.millis(5)) // => 5000
+ * Duration.toMicros(Duration.nanos(123n)) // => 0.123
+ * ```
+ *
+ * @stability stable
+ * @category getters
+ * @since 4.1.0
+ */
+export const toMicros = (self: Input): number =>
+  match(fromInputUnsafe(self), {
+    onMillis: (millis) => millis * 1_000,
+    onNanos: (nanos) => nanosToUnit(nanos, 1_000),
+    onInfinity: () => Infinity,
+    onNegativeInfinity: () => -Infinity
+  })
+
 /**
  * Converts a Duration to milliseconds.
  *
@@ -2534,6 +2558,122 @@ export const format = (self: Duration): string => {
   return pieces.join(" ")
 }
 
+/**
+ * Formats a `Duration` as an ISO 8601 duration string.
+ *
+ * **Details**
+ *
+ * The duration is balanced into days (24 hours), hours, minutes and seconds,
+ * with up to nine fractional second digits. Weeks, months and years are never
+ * produced. Negative durations get a leading `-`, zero is `"PT0S"` and
+ * infinite durations return `Option.none()`.
+ *
+ * **Example** (Formatting durations as ISO 8601)
+ *
+ * ```ts import.meta.vitest
+ * import { Duration, Option } from "effect"
+ *
+ * Duration.formatIso(Duration.minutes(90)) // => Option.some("PT1H30M")
+ * Duration.formatIso(Duration.millis(-1500)) // => Option.some("-PT1.5S")
+ * Duration.formatIso(Duration.hours(26)) // => Option.some("P1DT2H")
+ * Duration.formatIso(Duration.infinity) // => Option.none()
+ * ```
+ *
+ * @see {@link fromIso} for parsing ISO 8601 duration strings
+ *
+ * @stability stable
+ * @category converting
+ * @since 4.1.0
+ */
+export const formatIso = (self: Duration): Option.Option<string> => {
+  if (!isFinite(self)) {
+    return Option.none()
+  }
+  const n = toNanosUnsafe(self)
+  const a = n < bigint0 ? -n : n
+  const days = a / bigintNanosPerDay
+  const hours = a % bigintNanosPerDay / bigintNanosPerHour
+  const minutes = a % bigintNanosPerHour / bigintNanosPerMinute
+  const seconds = a % bigintNanosPerMinute / bigint1e9
+  const fraction = a % bigint1e9
+
+  let time = ""
+  if (hours !== bigint0) time += `${hours}H`
+  if (minutes !== bigint0) time += `${minutes}M`
+  if (fraction !== bigint0) {
+    time += `${seconds}.${fraction.toString().padStart(9, "0").replace(/0+$/, "")}S`
+  } else if (seconds !== bigint0) {
+    time += `${seconds}S`
+  }
+
+  let out = n < bigint0 ? "-P" : "P"
+  if (days !== bigint0) out += `${days}D`
+  if (time !== "") out += `T${time}`
+  return Option.some(out === "P" ? "PT0S" : out)
+}
+
+const DURATION_ISO_REGEXP =
+  /^([+-])?P(?!$)(?:(\d+)W)?(?:(\d+)D)?(?:T(?!$)(?:(\d+)(?:[.,](\d{1,9}))?H)?(?:(\d+)(?:[.,](\d{1,9}))?M)?(?:(\d+)(?:[.,](\d{1,9}))?S)?)?$/
+
+// `scale` is the number of nanoseconds in one unit
+const parseIsoComponent = (whole: string | undefined, fraction: string | undefined, scale: bigint): bigint =>
+  (whole === undefined ? bigint0 : BigInt(whole) * scale) +
+  (fraction === undefined ? bigint0 : BigInt(fraction.padEnd(9, "0")) * (scale / bigint1e9))
+
+/**
+ * Parses an ISO 8601 duration string into a `Duration`.
+ *
+ * **Details**
+ *
+ * Accepts an optional `+` or `-` sign followed by weeks (`W`), days (`D`),
+ * hours (`H`), minutes (`M`) and seconds (`S`). A day is 24 hours and a week
+ * is 7 days. Only the last time component may have a fraction, of up to nine
+ * digits, separated by `.` or `,`.
+ *
+ * **Gotchas**
+ *
+ * Years (`Y`) and months (`M` before `T`) are rejected because they have no
+ * fixed length. Fractional weeks and days are rejected.
+ *
+ * **Example** (Parsing ISO 8601 durations)
+ *
+ * ```ts import.meta.vitest
+ * import { Duration, Option } from "effect"
+ *
+ * Duration.fromIso("PT1H30M") // => Option.some(Duration.minutes(90))
+ * Duration.fromIso("-PT1.5S") // => Option.some(Duration.millis(-1500))
+ * Duration.fromIso("P1W2D") // => Option.some(Duration.days(9))
+ * Duration.fromIso("P1M") // => Option.none()
+ * ```
+ *
+ * @see {@link formatIso} for formatting a `Duration` as an ISO 8601 string
+ *
+ * @stability stable
+ * @category constructors
+ * @since 4.1.0
+ */
+export const fromIso = (input: string): Option.Option<Duration> => {
+  const match = DURATION_ISO_REGEXP.exec(input)
+  if (match === null) {
+    return Option.none()
+  }
+  const [, sign, w, d, h, hf, m, mf, s, sf] = match
+  // a fraction is only allowed on the last time component
+  if ((hf !== undefined && (m !== undefined || s !== undefined)) || (mf !== undefined && s !== undefined)) {
+    return Option.none()
+  }
+  const total = parseIsoComponent(w, undefined, bigintNanosPerWeek) +
+    parseIsoComponent(d, undefined, bigintNanosPerDay) +
+    parseIsoComponent(h, hf, bigintNanosPerHour) +
+    parseIsoComponent(m, mf, bigintNanosPerMinute) +
+    parseIsoComponent(s, sf, bigint1e9)
+  const signed = sign === "-" ? -total : total
+  const ms = Number(signed / bigint1e6)
+  return Option.some(
+    signed % bigint1e6 === bigint0 && Number.isSafeInteger(ms) ? millis(ms) : nanos(signed)
+  )
+}
+
 /**
  * Reducer for summing `Duration`s.
  *