effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/SchemaTransformation.ts

@@ -754,15 +754,12 @@ export function passthrough<T>(): Transformation<T, T> {
 }
 
 /**
- * A passthrough transformation typed so that `T extends E` — the decoded
- * type is a supertype of the encoded type.
+ * A passthrough transformation typed so that `T extends E`, where the decoded
+ * type `T` is a subtype of the encoded type `E`.
  *
- * When to use this:
- * - Widening: the decoded side accepts a broader type than the encoded side.
- *
- * Behavior:
- * - Both decode and encode are no-ops (same as {@link passthrough}).
- * - Returns a shared singleton instance.
+ * Use this when the runtime value is unchanged but the decoded side should be
+ * narrower than the encoded side. Both decode and encode are no-ops and return a
+ * shared singleton transformation.
  *
  * **Example** (Supertype passthrough)
  *
@@ -996,15 +993,12 @@ export const durationFromNanos: Transformation<Duration.Duration, bigint> = tran
 })
 
 /**
- * Decodes a `number` (milliseconds) into a `Duration` and encodes a
- * `Duration` back to `number` milliseconds.
- *
- * When to use this:
- * - Working with millisecond-precision timestamps (e.g. `Date.now()`).
+ * Decodes a `number` of milliseconds into a `Duration` and encodes a `Duration`
+ * back to milliseconds.
  *
- * Behavior:
- * - Decode: creates a Duration from milliseconds. Always succeeds.
- * - Encode: converts a Duration to milliseconds. Always succeeds.
+ * Use this for timeouts, delays, elapsed intervals, or other duration values
+ * stored as millisecond counts. Decode creates a duration from the number, and
+ * encode returns the duration length in milliseconds.
  *
  * **Example** (Duration from milliseconds)
  *
@@ -1485,16 +1479,13 @@ export const stringFromUriComponent: Transformation<string, string> = new Transf
 )
 
 /**
- * Decodes a JSON `string` into an `unknown` value and encodes an `unknown`
- * value back to a JSON string.
+ * Decodes a JSON string with `JSON.parse` and encodes a value with
+ * `JSON.stringify`.
  *
- * When to use this:
- * - Parsing JSON strings from HTTP bodies, message queues, or storage.
- * - Typically composed with a further schema to validate the parsed structure.
- *
- * Behavior:
- * - Decode: calls `JSON.parse`. Fails if the string is not valid JSON.
- * - Encode: calls `JSON.stringify`.
+ * Use this for JSON stored or transmitted as a string, usually before composing
+ * with another schema that validates the parsed structure. Decode fails with
+ * `InvalidValue` for invalid JSON, and encode can fail with `InvalidValue` when
+ * `JSON.stringify` cannot serialize the value.
  *
  * **Example** (Parsing JSON)
  *
@@ -1518,15 +1509,13 @@ export const fromJsonString = new Transformation<unknown, string>(
 )
 
 /**
- * Decodes a `FormData` instance into an `unknown` record and encodes an
- * `unknown` record back to `FormData`.
+ * Decodes a `FormData` instance into a nested record using bracket-path keys and
+ * encodes object-like values back into `FormData`.
  *
- * When to use this:
- * - Handling HTML form submissions or multipart API requests.
- *
- * Behavior:
- * - Decode: extracts entries from the FormData into a plain object.
- * - Encode: constructs a FormData from the record's entries.
+ * Use this for form or multipart payloads where keys such as `user[name]` or
+ * `items[0]` should become nested data. Decode preserves string and `Blob`
+ * leaves. Encode flattens nested objects and arrays into bracket-path entries
+ * and returns an empty `FormData` for non-object inputs.
  *
  * **Example** (Decoding FormData)
  *
@@ -1550,15 +1539,13 @@ export const fromFormData = new Transformation<unknown, FormData>(
 )
 
 /**
- * Decodes a `URLSearchParams` instance into an `unknown` record and encodes
- * an `unknown` record back to `URLSearchParams`.
+ * Decodes `URLSearchParams` into a nested record using bracket-path keys and
+ * encodes object-like values back into `URLSearchParams`.
  *
- * When to use this:
- * - Parsing URL query parameters.
- *
- * Behavior:
- * - Decode: extracts entries from URLSearchParams into a plain object.
- * - Encode: constructs URLSearchParams from the record's entries.
+ * Use this for query strings where keys such as `filter[name]` or `items[0]`
+ * should become nested data. Decode produces string leaves. Encode flattens
+ * nested objects and arrays into bracket-path entries and returns empty
+ * `URLSearchParams` for non-object inputs.
  *
  * **Example** (Decoding URLSearchParams)
  *
@@ -1582,6 +1569,12 @@ export const fromURLSearchParams = new Transformation<unknown, URLSearchParams>(
 )
 
 /**
+ * Decodes a numeric time-zone offset in milliseconds into a
+ * `DateTime.TimeZone.Offset` and encodes it back to the offset number.
+ *
+ * Decode uses `DateTime.zoneMakeOffset`; encode returns the offset's `offset`
+ * field.
+ *
  * @since 4.0.0
  */
 export const timeZoneOffsetFromNumber: Transformation<DateTime.TimeZone.Offset, number> = transform<
@@ -1593,6 +1586,12 @@ export const timeZoneOffsetFromNumber: Transformation<DateTime.TimeZone.Offset,
 })
 
 /**
+ * Decodes an IANA time-zone identifier string into a
+ * `DateTime.TimeZone.Named` and encodes a named time zone back to its `id`.
+ *
+ * Decode fails with `InvalidValue` when the string is not a valid IANA time-zone
+ * identifier.
+ *
  * @since 4.0.0
  */
 export const timeZoneNamedFromString: Transformation<DateTime.TimeZone.Named, string> = transformOrFail<
@@ -1609,6 +1608,13 @@ export const timeZoneNamedFromString: Transformation<DateTime.TimeZone.Named, st
 })
 
 /**
+ * Decodes a string into a `DateTime.TimeZone` and encodes a time zone back to
+ * its string representation.
+ *
+ * Accepted decode inputs include valid IANA identifiers and offset strings such
+ * as `"+03:00"`. Decode fails with `InvalidValue` when the string cannot be
+ * parsed as a time zone.
+ *
  * @since 4.0.0
  */
 export const timeZoneFromString: Transformation<DateTime.TimeZone, string> = transformOrFail<
@@ -1625,6 +1631,13 @@ export const timeZoneFromString: Transformation<DateTime.TimeZone, string> = tra
 })
 
 /**
+ * Decodes a date-time string into a `DateTime.Utc` and encodes it back to an ISO
+ * string.
+ *
+ * Decode accepts strings supported by `DateTime.make`, converts the result to
+ * UTC, and fails with `InvalidValue` when parsing fails. Encode uses
+ * `DateTime.formatIso`.
+ *
  * @since 4.0.0
  */
 export const dateTimeUtcFromString: Transformation<DateTime.Utc, string> = transformOrFail<
@@ -1642,6 +1655,13 @@ export const dateTimeUtcFromString: Transformation<DateTime.Utc, string> = trans
 })
 
 /**
+ * Decodes a zoned date-time string into a `DateTime.Zoned` and encodes it back
+ * to an ISO zoned string.
+ *
+ * Decode uses `DateTime.makeZonedFromString` and fails with `InvalidValue` when
+ * the input is not a valid zoned date-time. Encode uses
+ * `DateTime.formatIsoZoned`.
+ *
  * @since 4.0.0
  */
 export const dateTimeZonedFromString: Transformation<DateTime.Zoned, string> = transformOrFail<

package/src/SchemaUtils.ts

@@ -1,4 +1,20 @@
 /**
+ * The `SchemaUtils` module contains focused helpers for schema patterns that
+ * are useful but too specialized for the core `Schema` API surface.
+ *
+ * Use this module when you need to describe a native class with a schema while
+ * keeping a plain struct as its encoded representation. This is especially
+ * useful for classes such as `Data.Error` subclasses that should decode from
+ * structured data, encode back to that data, and still preserve class identity
+ * for instance checks and schema optics.
+ *
+ * **Gotchas**
+ *
+ * - The constructor is called with the decoded struct fields as a single
+ *   argument, so the class constructor must accept that shape.
+ * - Encoding uses the instance itself as the encoded shape, so the instance
+ *   should expose properties compatible with the provided struct schema.
+ *
  * @since 4.0.0
  */
 import { identity } from "./Function.ts"
@@ -6,6 +22,13 @@ import * as Schema from "./Schema.ts"
 import * as Transformation from "./SchemaTransformation.ts"
 
 /**
+ * Builds an experimental schema for instances of a native class using a struct
+ * schema as the encoded representation.
+ *
+ * Decoding constructs `new constructor(props)` from the encoded fields.
+ * Encoding uses the instance as the encoded shape, so the class should expose
+ * properties compatible with the provided encoding schema.
+ *
  * @since 4.0.0
  * @experimental
  */

package/src/Scope.ts

@@ -27,7 +27,8 @@ const CloseableTypeId = effect.ScopeCloseableTypeId
  * automatically cleaned up when the scope is closed. Scopes can use
  * either sequential or parallel finalization strategies.
  *
- * @example
+ * **Example** (Managing scoped resources)
+ *
  * ```ts
  * import { Effect, Exit, Scope } from "effect"
  *
@@ -44,8 +45,8 @@ const CloseableTypeId = effect.ScopeCloseableTypeId
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Scope {
   readonly [TypeId]: typeof TypeId
@@ -56,7 +57,8 @@ export interface Scope {
  * A `Closeable` scope extends the base `Scope` interface with the ability
  * to be closed, executing all registered finalizers.
  *
- * @example
+ * **Example** (Closing a scope)
+ *
  * ```ts
  * import { Console, Effect, Exit, Scope } from "effect"
  *
@@ -71,18 +73,20 @@ export interface Scope {
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Closeable extends Scope {
   readonly [CloseableTypeId]: typeof CloseableTypeId
 }
 
 /**
- * The `State` namespace contains types representing the different states
- * a scope can be in: Open (accepting new finalizers) or Closed (no longer accepting finalizers).
+ * The `State` namespace contains the concrete states of a scope: `Empty`
+ * before any finalizers are registered, `Open` with registered finalizers, and
+ * `Closed` with the exit value used to close the scope.
+ *
+ * **Example** (Checking scope states)
  *
- * @example
  * ```ts
  * import { Effect, Exit, Scope } from "effect"
  *
@@ -105,14 +109,17 @@ export interface Closeable extends Scope {
  * ```
  *
  * @since 2.0.0
- * @category models
  */
 export namespace State {
   /**
-   * Represents an open scope state where finalizers can be added and
-   * the scope is still accepting new resources.
+   * Represents an open scope with no registered finalizers yet.
+   *
+   * Adding the first finalizer transitions the scope to `Open`; closing an
+   * empty scope transitions directly to `Closed` without producing a finalizer
+   * effect.
+   *
+   * **Example** (Inspecting an empty scope state)
    *
-   * @example
    * ```ts
    * import { Scope } from "effect"
    *
@@ -125,8 +132,8 @@ export namespace State {
    * }
    * ```
    *
-   * @since 2.0.0
    * @category models
+   * @since 2.0.0
    */
   export type Empty = {
     readonly _tag: "Empty"
@@ -135,7 +142,8 @@ export namespace State {
    * Represents an open scope state where finalizers can be added and
    * the scope is still accepting new resources.
    *
-   * @example
+   * **Example** (Inspecting an open scope state)
+   *
    * ```ts
    * import { Scope } from "effect"
    *
@@ -148,8 +156,8 @@ export namespace State {
    * }
    * ```
    *
-   * @since 2.0.0
    * @category models
+   * @since 2.0.0
    */
   export type Open = {
     readonly _tag: "Open"
@@ -159,7 +167,8 @@ export namespace State {
    * Represents a closed scope state where finalizers have been executed
    * and the scope is no longer accepting new resources.
    *
-   * @example
+   * **Example** (Inspecting a closed scope state)
+   *
    * ```ts
    * import { Effect, Exit, Scope } from "effect"
    *
@@ -177,8 +186,8 @@ export namespace State {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category models
+   * @since 2.0.0
    */
   export type Closed = {
     readonly _tag: "Closed"
@@ -189,7 +198,8 @@ export namespace State {
 /**
  * The service tag for `Scope`, used for dependency injection in the Effect system.
  *
- * @example
+ * **Example** (Accessing the scope service)
+ *
  * ```ts
  * import { Effect, Scope } from "effect"
  *
@@ -205,15 +215,16 @@ export namespace State {
  * const scoped = Effect.scoped(program)
  * ```
  *
- * @since 2.0.0
  * @category tags
+ * @since 2.0.0
  */
 export const Scope: Context.Service<Scope, Scope> = effect.scopeTag
 
 /**
  * Creates a new `Scope` with the specified finalizer strategy.
  *
- * @example
+ * **Example** (Creating a scope)
+ *
  * ```ts
  * import { Console, Effect, Exit, Scope } from "effect"
  *
@@ -241,7 +252,8 @@ export const make: (finalizerStrategy?: "sequential" | "parallel") => Effect<Clo
  * This is useful when you need a scope immediately but should be used with caution
  * as it doesn't provide the same safety guarantees as the `Effect`-wrapped version.
  *
- * @example
+ * **Example** (Creating a scope synchronously)
+ *
  * ```ts
  * import { Console, Effect, Exit, Scope } from "effect"
  *
@@ -255,8 +267,8 @@ export const make: (finalizerStrategy?: "sequential" | "parallel") => Effect<Clo
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const makeUnsafe: (finalizerStrategy?: "sequential" | "parallel") => Closeable = effect.scopeMakeUnsafe
 
@@ -270,7 +282,8 @@ export const makeUnsafe: (finalizerStrategy?: "sequential" | "parallel") => Clos
  *
  * - `Scope.extend`
  *
- * @example
+ * **Example** (Providing a scope)
+ *
  * ```ts
  * import { Console, Effect, Scope } from "effect"
  *
@@ -288,8 +301,8 @@ export const makeUnsafe: (finalizerStrategy?: "sequential" | "parallel") => Clos
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const provide: {
   /**
@@ -302,7 +315,8 @@ export const provide: {
    *
    * - `Scope.extend`
    *
-   * @example
+   * **Example** (Providing a scope)
+   *
    * ```ts
    * import { Console, Effect, Scope } from "effect"
    *
@@ -320,8 +334,8 @@ export const provide: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (value: Scope): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, Scope>>
   /**
@@ -334,7 +348,8 @@ export const provide: {
    *
    * - `Scope.extend`
    *
-   * @example
+   * **Example** (Providing a scope)
+   *
    * ```ts
    * import { Console, Effect, Scope } from "effect"
    *
@@ -352,17 +367,21 @@ export const provide: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, E, R>(self: Effect<A, E, R>, value: Scope): Effect<A, E, Exclude<R, Scope>>
 } = effect.provideScope
 
 /**
- * Adds a finalizer to a scope that will be executed when the scope is closed.
- * Finalizers are cleanup functions that receive the exit value of the scope.
+ * Registers an exit-aware finalizer on a scope.
+ *
+ * If the scope is open, the finalizer runs when the scope closes and receives
+ * the scope's exit value. If the scope is already closed, the finalizer runs
+ * immediately with the stored exit value.
+ *
+ * **Example** (Adding an exit-aware finalizer)
  *
- * @example
  * ```ts
  * import { Console, Effect, Exit, Scope } from "effect"
  *
@@ -395,11 +414,14 @@ export const addFinalizerExit: (scope: Scope, finalizer: (exit: Exit<any, any>)
   effect.scopeAddFinalizerExit
 
 /**
- * Adds a finalizer to a scope. The finalizer is a simple `Effect` that will be
- * executed when the scope is closed, regardless of whether the scope closes
- * successfully or with an error.
+ * Registers a finalizer effect on a scope.
+ *
+ * If the scope is open, the finalizer runs when the scope closes, regardless of
+ * whether the scope closes successfully or with an error. If the scope is
+ * already closed, the finalizer runs immediately.
+ *
+ * **Example** (Adding finalizers)
  *
- * @example
  * ```ts
  * import { Console, Effect, Exit, Scope } from "effect"
  *
@@ -419,16 +441,20 @@ export const addFinalizerExit: (scope: Scope, finalizer: (exit: Exit<any, any>)
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const addFinalizer: (scope: Scope, finalizer: Effect<unknown>) => Effect<void> = effect.scopeAddFinalizer
 
 /**
- * Creates a child scope from a parent scope. The child scope inherits the
- * parent's finalization strategy unless overridden.
+ * Creates a closeable child scope registered with a parent scope.
+ *
+ * Closing the parent closes the child with the same exit value, and closing the
+ * child detaches it from the parent. The optional finalizer strategy configures
+ * the child scope and defaults to `"sequential"` when omitted.
+ *
+ * **Example** (Creating a child scope)
  *
- * @example
  * ```ts
  * import { Console, Effect, Exit, Scope } from "effect"
  *
@@ -459,10 +485,14 @@ export const fork: (
 ) => Effect<Closeable> = effect.scopeFork
 
 /**
- * Creates a child scope from a parent scope synchronously without wrapping it in an `Effect`.
- * The child scope inherits the parent's finalization strategy unless overridden.
+ * Synchronously creates a closeable child scope registered with a parent scope.
+ *
+ * Closing the parent closes the child with the same exit value, and closing the
+ * child detaches it from the parent. The optional finalizer strategy configures
+ * the child scope and defaults to `"sequential"` when omitted.
+ *
+ * **Example** (Creating a child scope synchronously)
  *
- * @example
  * ```ts
  * import { Console, Effect, Exit, Scope } from "effect"
  *
@@ -480,8 +510,8 @@ export const fork: (
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const forkUnsafe: (scope: Scope, finalizerStrategy?: "sequential" | "parallel") => Closeable =
   effect.scopeForkUnsafe
@@ -490,7 +520,8 @@ export const forkUnsafe: (scope: Scope, finalizerStrategy?: "sequential" | "para
  * Closes a scope, running all registered finalizers in the appropriate order.
  * The exit value is passed to each finalizer.
  *
- * @example
+ * **Example** (Running scope finalizers)
+ *
  * ```ts
  * import { Console, Effect, Exit, Scope } from "effect"
  *
@@ -517,22 +548,50 @@ export const forkUnsafe: (scope: Scope, finalizerStrategy?: "sequential" | "para
 export const close: <A, E>(self: Scope, exit: Exit<A, E>) => Effect<void> = effect.scopeClose
 
 /**
+ * Unsafely transitions a scope to `Closed` with the provided exit value.
+ *
+ * Returns an effect that runs registered finalizers, or `undefined` when the
+ * scope was already closed or no finalizers need to run. Prefer `close` unless
+ * you are implementing lower-level scope machinery and can correctly run the
+ * returned effect.
+ *
  * @since 4.0.0
  */
 export const closeUnsafe: <A, E>(self: Scope, exit_: Exit<A, E>) => Effect<void, never, never> | undefined =
   effect.scopeCloseUnsafe
 
 /**
+ * Runs an effect with the provided closeable scope in its context and closes
+ * that scope when the effect exits.
+ *
+ * The scope is closed with the same exit value as the effect, so registered
+ * finalizers can observe whether the effect succeeded, failed, or was
+ * interrupted.
+ *
  * @category combinators
  * @since 4.0.0
  */
 export const use: {
   /**
+   * Runs an effect with the provided closeable scope in its context and closes
+   * that scope when the effect exits.
+   *
+   * The scope is closed with the same exit value as the effect, so registered
+   * finalizers can observe whether the effect succeeded, failed, or was
+   * interrupted.
+   *
    * @category combinators
    * @since 4.0.0
    */
   (scope: Closeable): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, Scope>>
   /**
+   * Runs an effect with the provided closeable scope in its context and closes
+   * that scope when the effect exits.
+   *
+   * The scope is closed with the same exit value as the effect, so registered
+   * finalizers can observe whether the effect succeeded, failed, or was
+   * interrupted.
+   *
    * @category combinators
    * @since 4.0.0
    */