effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/LayerMap.ts

@@ -115,8 +115,7 @@ export interface LayerMap<in out K, in out I, in out E = never> {
 }
 
 /**
- * A `LayerMap` allows you to create a map of Layer's that can be used to
- * dynamically access resources based on a key.
+ * Creates a `LayerMap` that dynamically provides resources based on a key.
  *
  * **Example** (Creating a layer map)
  *
@@ -272,11 +271,19 @@ export const fromRecord = <
 /**
  * Service class shape produced by `LayerMap.Service`.
  *
+ * **When to use**
+ *
+ * Use as the public type for classes returned by `LayerMap.Service` when an API
+ * needs to accept, return, or alias the generated service class and its static
+ * helpers.
+ *
  * **Details**
  *
  * It combines a `Context.Service` tag for the `LayerMap` with default layers
  * and helper accessors for retrieving, using, and invalidating keyed resources.
  *
+ * @see {@link Service} for creating concrete `LayerMap` service classes
+ *
  * @category services
  * @since 3.14.0
  */

package/src/LogLevel.ts

@@ -48,6 +48,11 @@ import * as References from "./References.ts"
  * Represents every level used by Effect logging, including concrete message
  * severities and the `All` and `None` sentinel levels.
  *
+ * **When to use**
+ *
+ * Use to type values that may be either concrete log message severities or
+ * logging configuration sentinels.
+ *
  * **Details**
  *
  * The levels are ordered from most severe to least severe:
@@ -89,22 +94,55 @@ export type LogLevel = "All" | "Fatal" | "Error" | "Warn" | "Info" | "Debug" | "
  * Log levels that represent actual message severities, excluding the `All` and
  * `None` sentinel levels.
  *
+ * **When to use**
+ *
+ * Use when typing emitted log message severities, such as explicit log calls,
+ * current log level references, or error-report severity annotations, where
+ * `All` and `None` are not valid values.
+ *
+ * @see {@link LogLevel} for the wider log-level type that also accepts the
+ * `All` and `None` sentinel levels
+ * @see {@link values} for the runtime list of all accepted `LogLevel` values,
+ * including sentinels
+ *
  * @category models
  * @since 4.0.0
  */
 export type Severity = "Fatal" | "Error" | "Warn" | "Info" | "Debug" | "Trace"
 
 /**
- * All `LogLevel` values in order from `All` through the concrete severities to
+ * Returns all `LogLevel` values in order from `All` through the concrete severities to
  * `None`.
  *
+ * **When to use**
+ *
+ * Use to enumerate or validate all accepted `LogLevel` string values, including
+ * the `All` and `None` sentinel levels.
+ *
+ * **Details**
+ *
+ * The array order matches the module severity order: `All`, concrete
+ * severities from `Fatal` to `Trace`, then `None`.
+ *
+ * **Gotchas**
+ *
+ * This list includes `All` and `None`, so it is not limited to concrete emitted
+ * severities.
+ *
+ * @see {@link Severity} for the concrete message severity type that excludes `All` and `None`
+ * @see {@link Order} for comparing these levels by severity order
+ *
  * @category models
  * @since 4.0.0
  */
 export const values: ReadonlyArray<LogLevel> = ["All", "Fatal", "Error", "Warn", "Info", "Debug", "Trace", "None"]
 
 /**
- * An `Order` instance for `LogLevel` that defines the severity ordering.
+ * Order instance for `LogLevel` that defines the severity ordering.
+ *
+ * **When to use**
+ *
+ * Use to sort or compare log levels according to Effect's severity order.
  *
  * **Details**
  *
@@ -128,7 +166,16 @@ export const values: ReadonlyArray<LogLevel> = ["All", "Fatal", "Error", "Warn",
 export const Order: Ord.Order<LogLevel> = effect.LogLevelOrder
 
 /**
- * An `Equivalence` instance for log levels using strict equality (`===`).
+ * Equivalence instance for log levels using strict equality (`===`).
+ *
+ * **When to use**
+ *
+ * Use to compare two `LogLevel` values when only the exact same level should
+ * match.
+ *
+ * **Details**
+ *
+ * Each log level string, including `All` and `None`, only matches itself.
  *
  * **Example** (Comparing log levels)
  *
@@ -139,6 +186,9 @@ export const Order: Ord.Order<LogLevel> = effect.LogLevelOrder
  * console.log(LogLevel.Equivalence("Error", "Info")) // false
  * ```
  *
+ * @see {@link Order} for severity ordering rather than exact level equality
+ * @see {@link isGreaterThanOrEqualTo} for minimum-threshold checks
+ *
  * @category instances
  * @since 4.0.0
  */
@@ -147,6 +197,26 @@ export const Equivalence: Equ.Equivalence<LogLevel> = Equ.strictEqual<LogLevel>(
 /**
  * Returns the ordinal value of the log level.
  *
+ * **When to use**
+ *
+ * Use to project a `LogLevel` into the numeric sort key used by
+ * `LogLevel.Order` when custom ordering code or an integration needs a number
+ * instead of an `Order` comparison.
+ *
+ * **Details**
+ *
+ * The mapping is `All` to `Number.MIN_SAFE_INTEGER`, `Trace` to `0`, `Debug` to
+ * `10000`, `Info` to `20000`, `Warn` to `30000`, `Error` to `40000`, `Fatal` to
+ * `50000`, and `None` to `Number.MAX_SAFE_INTEGER`.
+ *
+ * **Gotchas**
+ *
+ * These ordinals are internal sort keys; do not treat them as external severity
+ * numbers.
+ *
+ * @see {@link Order} for comparing log levels without exposing numeric keys
+ * @see {@link isGreaterThanOrEqualTo} for minimum-threshold filtering
+ *
  * @category ordering
  * @since 4.0.0
  */
@@ -157,8 +227,7 @@ export const getOrdinal = (self: LogLevel): number => effect.logLevelToOrder(sel
  *
  * **When to use**
  *
- * Use this for strict severity comparisons when filtering logs based on minimum
- * severity requirements.
+ * Use to check whether one log level is strictly more severe than another.
  *
  * **Details**
  *
@@ -196,8 +265,7 @@ export const isGreaterThan: {
    *
    * **When to use**
    *
-   * Use this for strict severity comparisons when filtering logs based on minimum
-   * severity requirements.
+   * Use to check whether one log level is strictly more severe than another.
    *
    * **Details**
    *
@@ -235,8 +303,7 @@ export const isGreaterThan: {
    *
    * **When to use**
    *
-   * Use this for strict severity comparisons when filtering logs based on minimum
-   * severity requirements.
+   * Use to check whether one log level is strictly more severe than another.
    *
    * **Details**
    *
@@ -276,7 +343,8 @@ export const isGreaterThan: {
  *
  * **When to use**
  *
- * Use this for implementing minimum log level filtering.
+ * Use to implement minimum log-level filtering by checking whether a message
+ * level meets a threshold.
  *
  * **Details**
  *
@@ -322,7 +390,8 @@ export const isGreaterThanOrEqualTo: {
    *
    * **When to use**
    *
-   * Use this for implementing minimum log level filtering.
+   * Use to implement minimum log-level filtering by checking whether a message
+   * level meets a threshold.
    *
    * **Details**
    *
@@ -368,7 +437,8 @@ export const isGreaterThanOrEqualTo: {
    *
    * **When to use**
    *
-   * Use this for implementing minimum log level filtering.
+   * Use to implement minimum log-level filtering by checking whether a message
+   * level meets a threshold.
    *
    * **Details**
    *
@@ -416,8 +486,7 @@ export const isGreaterThanOrEqualTo: {
  *
  * **When to use**
  *
- * Use this for strict severity comparisons when filtering out logs that are too
- * verbose.
+ * Use to check whether one log level is strictly less severe than another.
  *
  * **Details**
  *
@@ -455,8 +524,7 @@ export const isLessThan: {
    *
    * **When to use**
    *
-   * Use this for strict severity comparisons when filtering out logs that are too
-   * verbose.
+   * Use to check whether one log level is strictly less severe than another.
    *
    * **Details**
    *
@@ -494,8 +562,7 @@ export const isLessThan: {
    *
    * **When to use**
    *
-   * Use this for strict severity comparisons when filtering out logs that are too
-   * verbose.
+   * Use to check whether one log level is strictly less severe than another.
    *
    * **Details**
    *
@@ -535,7 +602,8 @@ export const isLessThan: {
  *
  * **When to use**
  *
- * Use this for implementing maximum log level filtering.
+ * Use to implement maximum log-level filtering by checking whether a level is
+ * at or below a threshold.
  *
  * **Details**
  *
@@ -579,7 +647,8 @@ export const isLessThanOrEqualTo: {
    *
    * **When to use**
    *
-   * Use this for implementing maximum log level filtering.
+   * Use to implement maximum log-level filtering by checking whether a level is
+   * at or below a threshold.
    *
    * **Details**
    *
@@ -623,7 +692,8 @@ export const isLessThanOrEqualTo: {
    *
    * **When to use**
    *
-   * Use this for implementing maximum log level filtering.
+   * Use to implement maximum log-level filtering by checking whether a level is
+   * at or below a threshold.
    *
    * **Details**
    *
@@ -667,6 +737,11 @@ export const isLessThanOrEqualTo: {
 /**
  * Checks whether a given log level is enabled for the current fiber.
  *
+ * **When to use**
+ *
+ * Use to check whether a log level would be emitted under the current fiber's
+ * minimum log level.
+ *
  * **Details**
  *
  * A log level is enabled when it is greater than or equal to

package/src/Logger.ts

@@ -240,8 +240,22 @@ export const isLogger = (u: unknown): u is Logger<unknown, unknown> => Predicate
 export const CurrentLoggers: Context.Reference<ReadonlySet<Logger<unknown, any>>> = effect.CurrentLoggers
 
 /**
- * Context reference that controls whether console-style loggers write to
- * `console.error` instead of `console.log`.
+ * Context reference that routes the built-in default logger and TTY pretty
+ * console logger to stderr.
+ *
+ * **When to use**
+ *
+ * Use to keep stdout reserved for protocol messages or data output while still
+ * allowing Effect runtime logs to be emitted.
+ *
+ * **Details**
+ *
+ * The reference defaults to `false`. Providing `true` makes the affected
+ * loggers call `console.error` instead of `console.log`.
+ *
+ * @see {@link defaultLogger} for the runtime logger affected by this reference
+ * @see {@link consolePretty} for the TTY-mode pretty console logger affected by this reference
+ * @see {@link withConsoleError} for routing a specific formatter logger to `console.error`
  *
  * @category references
  * @since 4.0.0
@@ -253,7 +267,7 @@ export const LogToStderr: Context.Reference<boolean> = effect.LogToStderr
  *
  * **When to use**
  *
- * This allows you to modify, enhance, or completely change the output format
+ * Use when this allows you to modify, enhance, or completely change the output format
  * of an existing logger without recreating the entire logging logic.
  *
  * **Example** (Transforming logger output)
@@ -290,7 +304,7 @@ export const map = dual<
    *
    * **When to use**
    *
-   * This allows you to modify, enhance, or completely change the output format
+   * Use when this allows you to modify, enhance, or completely change the output format
    * of an existing logger without recreating the entire logging logic.
    *
    * **Example** (Transforming logger output)
@@ -329,7 +343,7 @@ export const map = dual<
    *
    * **When to use**
    *
-   * This allows you to modify, enhance, or completely change the output format
+   * Use when this allows you to modify, enhance, or completely change the output format
    * of an existing logger without recreating the entire logging logic.
    *
    * **Example** (Transforming logger output)
@@ -369,7 +383,7 @@ export const map = dual<
  *
  * **When to use**
  *
- * This is useful for taking any logger that produces string or object output
+ * Use when this is useful for taking any logger that produces string or object output
  * and routing it to the console for development or debugging purposes.
  *
  * **Example** (Writing logger output with console.log)
@@ -406,7 +420,7 @@ export const withConsoleLog = <Message, Output>(
  *
  * **When to use**
  *
- * This is particularly useful for error logging where you want to ensure
+ * Use when this is particularly useful for error logging where you want to ensure
  * log messages appear in the error stream (stderr) rather than standard output.
  *
  * **Example** (Writing logger output with console.error)
@@ -527,6 +541,8 @@ const format = (
   space?: number | string | undefined
 ) =>
 ({ cause, date, fiber, logLevel, message }: Options<unknown>): string => {
+  const formatUnknown = (value: unknown): string =>
+    typeof value === "string" ? value : Formatter.format(value, { space })
   const formatValue = (value: string): string => value.match(textOnly) ? value : quoteValue(value)
   const format = (label: string, value: string): string => `${effect.formatLabel(label)}=${formatValue(value)}`
   const append = (label: string, value: string): string => " " + format(label, value)
@@ -537,7 +553,7 @@ const format = (
 
   const messages = Array.ensure(message)
   for (let i = 0; i < messages.length; i++) {
-    out += append("message", Formatter.format(messages[i], { space }))
+    out += append("message", formatUnknown(messages[i]))
   }
 
   if (cause.reasons.length > 0) {
@@ -552,7 +568,7 @@ const format = (
 
   const annotations = fiber.getRef(CurrentLogAnnotations)
   for (const [label, value] of Object.entries(annotations)) {
-    out += append(label, Formatter.format(value, { space }))
+    out += append(label, formatUnknown(value))
   }
 
   return out
@@ -837,7 +853,7 @@ export const formatStructured: Logger<unknown, {
 export const formatJson = map(formatStructured, Formatter.formatJson)
 
 /**
- * Creates, in a scope, a logger that batches the output of another logger.
+ * Creates a scoped logger that batches the output of another logger.
  *
  * **Details**
  *
@@ -891,7 +907,7 @@ export const formatJson = map(formatStructured, Formatter.formatJson)
  */
 export const batched = dual<
   /**
-   * Creates, in a scope, a logger that batches the output of another logger.
+   * Creates a scoped logger that batches the output of another logger.
    *
    * **Details**
    *
@@ -952,7 +968,7 @@ export const batched = dual<
     self: Logger<Message, Output>
   ) => Effect.Effect<Logger<Message, void>, never, Scope.Scope>,
   /**
-   * Creates, in a scope, a logger that batches the output of another logger.
+   * Creates a scoped logger that batches the output of another logger.
    *
    * **Details**
    *
@@ -1388,7 +1404,7 @@ export const layer = <
   )
 
 /**
- * Creates, in a scope, a logger that writes string logger output to a file.
+ * Creates a scoped logger that writes string logger output to a file.
  *
  * **Details**
  *
@@ -1487,7 +1503,7 @@ export const layer = <
  */
 export const toFile = dual<
   /**
-   * Creates, in a scope, a logger that writes string logger output to a file.
+   * Creates a scoped logger that writes string logger output to a file.
    *
    * **Details**
    *
@@ -1595,7 +1611,7 @@ export const toFile = dual<
     self: Logger<Message, string>
   ) => Effect.Effect<Logger<Message, void>, PlatformError, Scope.Scope | FileSystem.FileSystem>,
   /**
-   * Creates, in a scope, a logger that writes string logger output to a file.
+   * Creates a scoped logger that writes string logger output to a file.
    *
    * **Details**
    *

package/src/ManagedRuntime.ts

@@ -51,7 +51,23 @@ import type { Mutable } from "./Types.ts"
 const TypeId = "~effect/ManagedRuntime"
 
 /**
- * Checks if the provided argument is a `ManagedRuntime`.
+ * Checks whether the provided argument is a `ManagedRuntime`.
+ *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before treating it as a `ManagedRuntime`.
+ *
+ * **Details**
+ *
+ * The guard checks the internal `ManagedRuntime` marker property. It does not
+ * build the layer or inspect the runtime's services.
+ *
+ * **Gotchas**
+ *
+ * Disposed runtimes still carry the marker, so this guard does not prove the
+ * runtime is still usable.
+ *
+ * @see {@link make} for creating managed runtimes this guard recognizes
  *
  * @category guards
  * @since 3.9.0
@@ -62,12 +78,22 @@ export const isManagedRuntime = (input: unknown): input is ManagedRuntime<unknow
 /**
  * Type helpers associated with `ManagedRuntime`.
  *
+ * **When to use**
+ *
+ * Use to reference type-level helpers for extracting managed runtime services
+ * and layer errors.
+ *
  * @since 3.4.0
  */
 export declare namespace ManagedRuntime {
   /**
    * Extracts the services available from a `ManagedRuntime`.
    *
+   * **When to use**
+   *
+   * Use to derive the service requirements provided by an existing
+   * `ManagedRuntime` type.
+   *
    * @category type-level
    * @since 3.4.0
    */
@@ -76,6 +102,11 @@ export declare namespace ManagedRuntime {
   /**
    * Extracts the layer construction error type of a `ManagedRuntime`.
    *
+   * **When to use**
+   *
+   * Use to derive the layer construction error type from an existing
+   * `ManagedRuntime` type.
+   *
    * @category type-level
    * @since 3.4.0
    */
@@ -86,11 +117,24 @@ export declare namespace ManagedRuntime {
  * A runtime built from a layer that can execute effects requiring that layer's
  * services.
  *
+ * **When to use**
+ *
+ * Use as the reusable runtime value returned by `make` when application entry
+ * points or integration code need to run many effects against the same
+ * layer-built services.
+ *
  * **Details**
  *
- * The runtime builds and caches its service context, owns the scope for
- * resources acquired by the layer, and should be disposed with `dispose` or
- * `disposeEffect` when it is no longer needed.
+ * The runtime builds and caches its service context and owns the scope for
+ * resources acquired by the layer.
+ *
+ * **Gotchas**
+ *
+ * Dispose the runtime with `dispose` or `disposeEffect` when it is no longer
+ * needed.
+ *
+ * @see {@link make} for constructing a managed runtime from a layer
+ * @see {@link Layer.build} for lower-level scoped layer construction
  *
  * @category models
  * @since 2.0.0
@@ -109,6 +153,11 @@ export interface ManagedRuntime<in R, out ER> {
   /**
    * Executes the effect using the provided Scheduler or using the global
    * Scheduler if not provided
+   *
+   * **When to use**
+   *
+   * Use to fork an effect against this runtime's services and get the running
+   * fiber.
    */
   readonly runFork: <A, E>(
     self: Effect.Effect<A, E, R>,
@@ -120,7 +169,7 @@ export interface ManagedRuntime<in R, out ER> {
    *
    * **When to use**
    *
-   * This method is effectful and should only be invoked at the edges of your
+   * Use when invoking this effectful method at the edges of your
    * program.
    */
   readonly runSyncExit: <A, E>(effect: Effect.Effect<A, E, R>) => Exit.Exit<A, ER | E>
@@ -130,7 +179,7 @@ export interface ManagedRuntime<in R, out ER> {
    *
    * **When to use**
    *
-   * This method is effectful and should only be invoked at the edges of your
+   * Use when invoking this effectful method at the edges of your
    * program.
    */
   readonly runSync: <A, E>(effect: Effect.Effect<A, E, R>) => A
@@ -141,7 +190,7 @@ export interface ManagedRuntime<in R, out ER> {
    *
    * **When to use**
    *
-   * This method is effectful and should only be invoked at the edges of your
+   * Use when invoking this effectful method at the edges of your
    * program.
    */
   readonly runCallback: <A, E>(
@@ -160,7 +209,7 @@ export interface ManagedRuntime<in R, out ER> {
    *
    * **When to use**
    *
-   * This method is effectful and should only be used at the edges of your
+   * Use when invoking this effectful method at the edges of your
    * program.
    */
   readonly runPromise: <A, E>(effect: Effect.Effect<A, E, R>, options?: Effect.RunOptions) => Promise<A>
@@ -171,7 +220,7 @@ export interface ManagedRuntime<in R, out ER> {
    *
    * **When to use**
    *
-   * This method is effectful and should only be used at the edges of your
+   * Use when invoking this effectful method at the edges of your
    * program.
    */
   readonly runPromiseExit: <A, E>(
@@ -181,11 +230,19 @@ export interface ManagedRuntime<in R, out ER> {
 
   /**
    * Dispose of the resources associated with the runtime.
+   *
+   * **When to use**
+   *
+   * Use to release this runtime's layer resources from Promise-based code.
    */
   readonly dispose: () => Promise<void>
 
   /**
    * Dispose of the resources associated with the runtime.
+   *
+   * **When to use**
+   *
+   * Use to release this runtime's layer resources from an `Effect` workflow.
    */
   readonly disposeEffect: Effect.Effect<void, never, never>
 }
@@ -193,11 +250,22 @@ export interface ManagedRuntime<in R, out ER> {
 /**
  * Creates a `ManagedRuntime` from a layer.
  *
+ * **When to use**
+ *
+ * Use to create a reusable runtime from a `Layer` for application entry points
+ * or integration code that runs many effects without rebuilding services.
+ *
  * **Details**
  *
  * The layer is built lazily on first use and its context is cached for
  * subsequent runs. Resources acquired by the layer are owned by the runtime and
- * are released when `dispose` or `disposeEffect` is run.
+ * are released when `dispose` or `disposeEffect` is run. `options.memoMap` can
+ * be used to share layer memoization with other layer builds.
+ *
+ * **Gotchas**
+ *
+ * Dispose the runtime when it is no longer needed. A runtime cannot be reused
+ * after disposal.
  *
  * **Example** (Creating a managed runtime)
  *
@@ -225,6 +293,10 @@ export interface ManagedRuntime<in R, out ER> {
  * // Hello, world!
  * ```
  *
+ * @see {@link ManagedRuntime} for the returned runtime interface
+ * @see {@link Layer.MemoMap} for shared layer memoization
+ * @see {@link Layer.build} for lower-level scoped layer construction
+ *
  * @category runtime class
  * @since 2.0.0
  */