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

package/src/Resource.ts

@@ -1,4 +1,36 @@
 /**
+ * The `Resource` module provides refreshable, scoped values. A
+ * `Resource<A, E>` stores the latest successful or failed acquisition result and
+ * can be read with {@link get}, refreshed manually with {@link refresh}, or
+ * refreshed automatically with {@link auto}.
+ *
+ * **Mental model**
+ *
+ * - A `Resource` wraps an acquisition `Effect` whose result is kept in a
+ *   `ScopedRef`
+ * - Each refresh re-runs acquisition and replaces the stored `Exit`
+ * - Replacing the stored value releases resources associated with the previous
+ *   scoped value
+ * - Reading a resource returns the current acquired value or fails with the
+ *   current acquisition error
+ *
+ * **Common tasks**
+ *
+ * - Create a manually refreshed resource with {@link manual}
+ * - Create a schedule-driven resource with {@link auto}
+ * - Read the current value with {@link get}
+ * - Force a reload with {@link refresh}
+ * - Check whether an unknown value is a resource with {@link isResource}
+ *
+ * **Gotchas**
+ *
+ * - Creating a resource requires a `Scope`; when the scope closes, scoped
+ *   values held by the resource are released
+ * - Failed acquisitions are stored too, so subsequent {@link get} calls fail
+ *   until a refresh succeeds
+ * - Automatic refreshes run in the resource scope and stop when that scope is
+ *   closed
+ *
  * @since 2.0.0
  */
 import * as Context from "./Context.ts"
@@ -18,8 +50,8 @@ const TypeId = "~effect/Resource" as const
  * A `Resource` is a value loaded into memory that can be refreshed manually or
  * automatically according to a schedule.
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Resource<in out A, in out E = never> extends Pipeable {
   readonly [TypeId]: typeof TypeId
@@ -28,8 +60,10 @@ export interface Resource<in out A, in out E = never> extends Pipeable {
 }
 
 /**
- * @since 2.0.0
+ * Returns `true` if the specified value is a `Resource`.
+ *
  * @category guards
+ * @since 2.0.0
  */
 export const isResource: (u: unknown) => u is Resource<unknown, unknown> = (
   u: unknown
@@ -58,8 +92,8 @@ const makeUnsafe = <A, E>(
 /**
  * Creates a `Resource` that must be refreshed manually.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const manual = <A, E, R>(
   acquire: Effect.Effect<A, E, R>
@@ -79,8 +113,8 @@ export const manual = <A, E, R>(
  * Creates a `Resource` that refreshes automatically according to the supplied
  * schedule.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const auto = <A, E, R, Out, E2, R2>(
   acquire: Effect.Effect<A, E, R>,
@@ -94,17 +128,21 @@ export const auto = <A, E, R, Out, E2, R2>(
 /**
  * Retrieves the current value stored in this resource.
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const get = <A, E>(self: Resource<A, E>): Effect.Effect<A, E> =>
   Effect.flatMap(ScopedRef.get(self.scopedRef), identity)
 
 /**
- * Refreshes this resource.
+ * Re-runs this resource's acquisition effect and updates the current value.
+ *
+ * Refreshing replaces the value stored in the resource's scoped reference and
+ * releases resources associated with the previous value. If acquisition fails,
+ * the returned effect fails with the acquisition error.
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const refresh = <A, E>(self: Resource<A, E>): Effect.Effect<void, E> =>
   ScopedRef.set(self.scopedRef, Effect.map(self.acquire, Exit.succeed))

package/src/Result.ts

@@ -68,7 +68,6 @@
  * @since 4.0.0
  */
 
-import type { Yieldable } from "./Effect.ts"
 import * as Equivalence from "./Equivalence.ts"
 import type { LazyArg } from "./Function.ts"
 import { constNull, constUndefined, dual, identity } from "./Function.ts"
@@ -154,7 +153,7 @@ export type Result<A, E = never> = Success<A, E> | Failure<A, E>
  * @category Models
  * @since 4.0.0
  */
-export interface Failure<out A, out E> extends Pipeable, Inspectable, Yieldable<Result<A, E>, A, E> {
+export interface Failure<out A, out E> extends Pipeable, Inspectable {
   readonly _tag: "Failure"
   readonly _op: "Failure"
   readonly failure: E
@@ -162,11 +161,25 @@ export interface Failure<out A, out E> extends Pipeable, Inspectable, Yieldable<
     readonly _A: Covariant<E>
     readonly _E: Covariant<A>
   }
+  [Symbol.iterator](): ResultIterator<Result<A, E>>
   [Unify.typeSymbol]?: unknown
   [Unify.unifySymbol]?: ResultUnify<this>
   [Unify.ignoreSymbol]?: ResultUnifyIgnore
 }
 
+/**
+ * Iterator protocol used to yield a `Result` inside {@link gen}, returning the
+ * success value type back to the generator.
+ *
+ * @category Generators
+ * @since 4.0.0
+ */
+export interface ResultIterator<T extends Result<any, any>> {
+  next(
+    ...args: ReadonlyArray<any>
+  ): IteratorResult<T, Result.Success<T>>
+}
+
 /**
  * The success variant of {@link Result}. Wraps a value of type `A`.
  *
@@ -194,7 +207,7 @@ export interface Failure<out A, out E> extends Pipeable, Inspectable, Yieldable<
  * @category Models
  * @since 4.0.0
  */
-export interface Success<out A, out E> extends Pipeable, Inspectable, Yieldable<Result<A, E>, A, E> {
+export interface Success<out A, out E> extends Pipeable, Inspectable {
   readonly _tag: "Success"
   readonly _op: "Success"
   readonly success: A
@@ -202,6 +215,7 @@ export interface Success<out A, out E> extends Pipeable, Inspectable, Yieldable<
     readonly _A: Covariant<E>
     readonly _E: Covariant<A>
   }
+  [Symbol.iterator](): ResultIterator<Result<A, E>>
   [Unify.typeSymbol]?: unknown
   [Unify.unifySymbol]?: ResultUnify<this>
   [Unify.ignoreSymbol]?: ResultUnifyIgnore
@@ -263,22 +277,21 @@ export interface ResultTypeLambda extends TypeLambda {
  * type E = Result.Result.Failure<R>
  * ```
  *
- * @category Type Level
  * @since 4.0.0
  */
 export declare namespace Result {
   /**
    * Extracts the failure type `E` from `Result<A, E>`.
    *
-   * @since 4.0.0
    * @category Type Level
+   * @since 4.0.0
    */
   export type Failure<T extends Result<any, any>> = [T] extends [Result<infer _A, infer _E>] ? _E : never
   /**
    * Extracts the success type `A` from `Result<A, E>`.
    *
-   * @since 4.0.0
    * @category Type Level
+   * @since 4.0.0
    */
   export type Success<T extends Result<any, any>> = [T] extends [Result<infer _A, infer _E>] ? _A : never
 }
@@ -375,10 +388,10 @@ export {
 }
 
 /**
- * A pre-built `Result<void>` holding `undefined` as its failure value.
+ * A pre-built failed `Result` whose failure value is `undefined`.
  *
- * - Use when you need a `Result` that represents "failed with no meaningful value"
- * - Equivalent to `Result.fail(undefined)` but avoids an extra allocation
+ * This is equivalent to `Result.fail(undefined)` with type
+ * `Result<never, void>`, but avoids allocating a new `Failure` wrapper.
  *
  * @see {@link fail}
  *
@@ -1395,8 +1408,8 @@ export const liftPredicate: {
  * @see {@link liftPredicate} to create a `Result` from a raw value with a predicate
  * @see {@link flatMap} for general conditional chaining
  *
- * @since 4.0.0
  * @category Filtering
+ * @since 4.0.0
  */
 export const filterOrFail: {
   /**
@@ -1428,8 +1441,8 @@ export const filterOrFail: {
    * @see {@link liftPredicate} to create a `Result` from a raw value with a predicate
    * @see {@link flatMap} for general conditional chaining
    *
-   * @since 4.0.0
    * @category Filtering
+   * @since 4.0.0
    */
   <A, B extends A, E2>(
     refinement: Refinement<NoInfer<A>, B>,
@@ -1464,8 +1477,8 @@ export const filterOrFail: {
    * @see {@link liftPredicate} to create a `Result` from a raw value with a predicate
    * @see {@link flatMap} for general conditional chaining
    *
-   * @since 4.0.0
    * @category Filtering
+   * @since 4.0.0
    */
   <A, E2>(predicate: Predicate<NoInfer<A>>, orFailWith: (value: NoInfer<A>) => E2): <E>(self: Result<A, E>) => Result<A, E2 | E>
   /**
@@ -1497,8 +1510,8 @@ export const filterOrFail: {
    * @see {@link liftPredicate} to create a `Result` from a raw value with a predicate
    * @see {@link flatMap} for general conditional chaining
    *
-   * @since 4.0.0
    * @category Filtering
+   * @since 4.0.0
    */
   <A, E, B extends A, E2>(
     self: Result<A, E>,
@@ -1534,8 +1547,8 @@ export const filterOrFail: {
    * @see {@link liftPredicate} to create a `Result` from a raw value with a predicate
    * @see {@link flatMap} for general conditional chaining
    *
-   * @since 4.0.0
    * @category Filtering
+   * @since 4.0.0
    */
   <A, E, E2>(self: Result<A, E>, predicate: Predicate<A>, orFailWith: (value: A) => E2): Result<A, E | E2>
 } = dual(3, <A, E, E2>(
@@ -2824,8 +2837,8 @@ export {
  *
  * @see {@link transposeMapOption} to map and transpose in one step
  *
- * @since 3.14.0
  * @category Transposing
+ * @since 3.14.0
  */
 export const transposeOption = <A = never, E = never>(
   self: Option<Result<A, E>>
@@ -2860,8 +2873,8 @@ export const transposeOption = <A = never, E = never>(
  *
  * @see {@link transposeOption} when the Option already contains a Result
  *
- * @since 3.15.0
  * @category Transposing
+ * @since 3.15.0
  */
 export const transposeMapOption = dual<
   /**
@@ -2891,8 +2904,8 @@ export const transposeMapOption = dual<
    *
    * @see {@link transposeOption} when the Option already contains a Result
    *
-   * @since 3.15.0
    * @category Transposing
+   * @since 3.15.0
    */
   <A, B, E = never>(f: (self: A) => Result<B, E>) => (self: Option<A>) => Result<Option<B>, E>,
   /**
@@ -2922,8 +2935,8 @@ export const transposeMapOption = dual<
    *
    * @see {@link transposeOption} when the Option already contains a Result
    *
-   * @since 3.15.0
    * @category Transposing
+   * @since 3.15.0
    */
   <A, B, E = never>(self: Option<A>, f: (self: A) => Result<B, E>) => Result<Option<B>, E>
 >(2, (self, f) => option_.isNone(self) ? succeedNone : map(f(self.value), option_.some))

package/src/Runtime.ts

@@ -5,7 +5,8 @@
  * teardown, error reporting, and exit code management. These utilities are particularly useful
  * for creating CLI applications and server processes that need to manage their lifecycle properly.
  *
- * @example
+ * **Example** (Creating a main runner)
+ *
  * ```ts
  * import { Effect, Fiber, Runtime } from "effect"
  *
@@ -38,10 +39,8 @@ import type * as Fiber from "./Fiber.ts"
  * The teardown function is called when an Effect program completes (either successfully or with failure)
  * and is responsible for determining the appropriate exit code and performing any cleanup operations.
  *
- * @param exit - The result of the Effect program execution
- * @param onExit - Callback to execute with the determined exit code
+ * **Example** (Customizing teardown behavior)
  *
- * @example
  * ```ts
  * import { Effect, Exit, Runtime } from "effect"
  *
@@ -69,6 +68,9 @@ import type * as Fiber from "./Fiber.ts"
  * runMain(program, { teardown: customTeardown })
  * ```
  *
+ * @param exit - The result of the Effect program execution
+ * @param onExit - Callback to execute with the determined exit code
+ *
  * @category Model
  * @since 4.0.0
  */
@@ -82,32 +84,27 @@ export interface Teardown {
  * This teardown function follows standard Unix conventions:
  * - Returns exit code 0 for successful completion
  * - Returns exit code 1 for failures (except interruption-only failures)
- * - Returns exit code 0 for interruption-only failures
+ * - Returns exit code 130 for interruption-only failures
  *
- * @example
- * ```ts
- * import { Effect, Exit, Runtime } from "effect"
+ * **Example** (Using default teardown)
  *
- * // The default teardown behavior
- * const program1 = Effect.succeed(42)
- * const program2 = Effect.fail("error")
- * const program3 = Effect.interrupt
+ * ```ts
+ * import { Exit, Runtime } from "effect"
  *
- * // Using defaultTeardown directly
  * const logExitCode = (exit: Exit.Exit<any, any>) => {
  *   Runtime.defaultTeardown(exit, (code) => {
  *     console.log(`Exit code: ${code}`)
  *   })
  * }
  *
- * // Success case - exit code 0
  * logExitCode(Exit.succeed(42))
+ * // Output: Exit code: 0
  *
- * // Failure case - exit code 1
  * logExitCode(Exit.fail("error"))
+ * // Output: Exit code: 1
  *
- * // Interruption case - exit code 0
  * logExitCode(Exit.interrupt(123))
+ * // Output: Exit code: 130
  * ```
  *
  * @category Teardown
@@ -129,9 +126,8 @@ export const defaultTeardown: Teardown = <E, A>(
  * handling process signals, fiber management, and teardown operations. The provided
  * function receives a fiber and teardown callback to implement platform-specific behavior.
  *
- * @param f - Function that sets up platform-specific behavior for the running Effect
+ * **Example** (Creating platform runners)
  *
- * @example
  * ```ts
  * import { Effect, Fiber, Runtime } from "effect"
  *
@@ -175,6 +171,8 @@ export const defaultTeardown: Teardown = <E, A>(
  * })
  * ```
  *
+ * @param f - Function that sets up platform-specific behavior for the running Effect
+ *
  * @category Run main
  * @since 4.0.0
  */
@@ -231,6 +229,9 @@ declare global {
 }
 
 /**
+ * Type-level key for the `Runtime.errorExitCode` property that can be attached
+ * to an `Error` to customize the process exit code used by `runMain`.
+ *
  * @category Exit code management
  * @since 4.0.0
  */
@@ -240,6 +241,8 @@ export type errorExitCode = "~effect/Runtime/errorExitCode"
  * Allows associating an exit code with an error for determining the process
  * exit code on failure.
  *
+ * **Example** (Setting a process exit code)
+ *
  * ```ts
  * import { Data, Effect, Runtime } from "effect"
  * import { NodeRuntime } from "@effect/platform-node"
@@ -258,6 +261,13 @@ export type errorExitCode = "~effect/Runtime/errorExitCode"
 export const errorExitCode: errorExitCode = "~effect/Runtime/errorExitCode"
 
 /**
+ * Reads the runtime exit-code marker from an unknown error value.
+ *
+ * **Details**
+ * Returns the numeric `[Runtime.errorExitCode]` property when it is present on
+ * an object. Otherwise returns `1`, the default failure exit code used by
+ * `defaultTeardown`.
+ *
  * @category Exit code management
  * @since 4.0.0
  */
@@ -272,13 +282,23 @@ export const getErrorExitCode = (u: unknown): number => {
 }
 
 /**
+ * Type-level key for the `Runtime.errorReported` property that controls default
+ * `runMain` error logging for an `Error`.
+ *
  * @category Error reporting management
  * @since 4.0.0
  */
 export type errorReported = "~effect/Runtime/errorReported"
 
 /**
- * Allows an error to opt-out of error reporting.
+ * Runtime marker that controls default `runMain` error logging for an error.
+ *
+ * **Details**
+ * Set `[Runtime.errorReported]` to `false` on an error object to suppress the
+ * runtime log because the error has already been reported. Omitted or
+ * non-boolean values are treated as `true`, so failures are logged by default.
+ *
+ * **Example** (Suppressing error reporting)
  *
  * ```ts
  * import { Data, Effect, Runtime } from "effect"
@@ -299,6 +319,12 @@ export type errorReported = "~effect/Runtime/errorReported"
 export const errorReported: errorReported = "~effect/Runtime/errorReported"
 
 /**
+ * Reads the runtime error-reporting marker from an unknown error value.
+ *
+ * **Details**
+ * Returns a boolean `[Runtime.errorReported]` property when it is present on an
+ * object. Otherwise returns `true`, so failures are logged by default.
+ *
  * @category Error reporting management
  * @since 4.0.0
  */