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

package/src/ConfigProvider.ts

@@ -99,7 +99,7 @@ import * as Str from "./String.ts"
  *
  * **When to use**
  *
- * Use `Node` when implementing a custom `ConfigProvider` by returning raw
+ * Use when implementing a custom `ConfigProvider` by returning raw
  * nodes from the `get` callback passed to {@link make}, or when inspecting raw
  * provider output before schema parsing.
  *
@@ -141,12 +141,12 @@ export type Node =
  *
  * **When to use**
  *
- * Use this when building nodes inside a custom `ConfigProvider`'s `get`
+ * Use when building nodes inside a custom `ConfigProvider`'s `get`
  * callback.
  *
  * **Details**
  *
- * The function does not mutate input and returns a new plain object.
+ * The function returns a new plain object.
  *
  * **Example** (Creating a value node)
  *
@@ -173,7 +173,7 @@ export function makeValue(value: string): Node {
  *
  * **When to use**
  *
- * Use this when describing a directory or JSON object inside a custom
+ * Use when describing a directory or JSON object inside a custom
  * provider.
  *
  * **Details**
@@ -207,7 +207,7 @@ export function makeRecord(keys: ReadonlySet<string>, value?: string): Node {
  *
  * **When to use**
  *
- * Use this when describing a JSON array or a set of numerically-indexed env
+ * Use when describing a JSON array or a set of numerically-indexed env
  * vars inside a custom provider.
  *
  * **Details**
@@ -239,7 +239,7 @@ export function makeArray(length: number, value?: string): Node {
  *
  * **When to use**
  *
- * Use this from a custom provider's `get` callback when the underlying store
+ * Use when you use this from a custom provider's `get` callback when the underlying store
  * is unreachable or produces an I/O error, or match on it in error channels
  * when consuming provider output directly.
  *
@@ -276,6 +276,11 @@ export class SourceError extends Data.TaggedError("SourceError")<{
  * the configuration tree. String segments name object keys; numeric segments
  * index into arrays.
  *
+ * **When to use**
+ *
+ * Use to address raw configuration nodes when implementing or transforming a
+ * `ConfigProvider`.
+ *
  * **Example** (A typical config path)
  *
  * ```ts
@@ -294,7 +299,7 @@ export type Path = ReadonlyArray<string | number>
  *
  * **When to use**
  *
- * Use this to type-annotate variables that hold a provider or to implement a
+ * Use to type-annotate variables that hold a provider or to implement a
  * custom provider via {@link make}.
  *
  * **Details**
@@ -317,34 +322,52 @@ export interface ConfigProvider extends Pipeable {
   /**
    * Returns the node found at `path`, or `undefined` if it does not exist.
    * Fails with `SourceError` when the underlying source cannot be read.
+   *
+   * **When to use**
+   *
+   * Use to resolve a path through this provider's path transformations before
+   * reading the backing source.
    */
   readonly load: (path: Path) => Effect.Effect<Node | undefined, SourceError>
 
   /**
    * Raw access to the underlying source.
+   *
+   * **When to use**
+   *
+   * Use to read from the backing source without applying this provider's path
+   * transformations.
    */
   readonly get: (path: Path) => Effect.Effect<Node | undefined, SourceError>
 
   /**
    * Function to map the input path.
+   *
+   * **When to use**
+   *
+   * Use to store the path transformation applied before raw provider lookup.
    */
   readonly mapInput: ((path: Path) => Path) | undefined
 
   /**
    * Prefix to add to the input path.
+   *
+   * **When to use**
+   *
+   * Use to store the path prefix applied before raw provider lookup.
    */
   readonly prefix: Path | undefined
 }
 
 /**
- * The `ConfigProvider` service reference, registered in the context with a
+ * Context reference for the active raw configuration provider, registered in the context with a
  * default value of `fromEnv()`. Because it is a `Context.Reference`, it is
  * available without explicit provision; `Config` schemas automatically resolve
  * it.
  *
  * **When to use**
  *
- * Use this to override the provider for an entire program via
+ * Use to override the provider for an entire program via
  * `Effect.provideService(ConfigProvider.ConfigProvider, myProvider)`, or to
  * retrieve the current provider inside an Effect with
  * `yield* ConfigProvider.ConfigProvider`.
@@ -389,7 +412,7 @@ const Proto = {
  *
  * **When to use**
  *
- * Use this when implementing a provider backed by a custom store, such as a
+ * Use when implementing a provider backed by a custom store, such as a
  * database, remote API, or in-memory map.
  *
  * **Details**
@@ -450,7 +473,7 @@ export function make(
  *
  * **When to use**
  *
- * Use this to layer multiple config sources, such as env vars plus a defaults
+ * Use to layer multiple config sources, such as env vars plus a defaults
  * file, or to provide partial overrides on top of a base config.
  *
  * **Details**
@@ -487,7 +510,7 @@ export const orElse: {
    *
    * **When to use**
    *
-   * Use this to layer multiple config sources, such as env vars plus a defaults
+   * Use to layer multiple config sources, such as env vars plus a defaults
    * file, or to provide partial overrides on top of a base config.
    *
    * **Details**
@@ -524,7 +547,7 @@ export const orElse: {
    *
    * **When to use**
    *
-   * Use this to layer multiple config sources, such as env vars plus a defaults
+   * Use to layer multiple config sources, such as env vars plus a defaults
    * file, or to provide partial overrides on top of a base config.
    *
    * **Details**
@@ -566,7 +589,7 @@ export const orElse: {
  *
  * **When to use**
  *
- * Use this for renaming or re-casing path segments, or for adding suffixes and
+ * Use when you use this for renaming or re-casing path segments, or for adding suffixes and
  * other per-segment transformations. See {@link constantCase} for a common
  * specialization.
  *
@@ -605,7 +628,7 @@ export const mapInput: {
    *
    * **When to use**
    *
-   * Use this for renaming or re-casing path segments, or for adding suffixes and
+   * Use when you use this for renaming or re-casing path segments, or for adding suffixes and
    * other per-segment transformations. See {@link constantCase} for a common
    * specialization.
    *
@@ -644,7 +667,7 @@ export const mapInput: {
    *
    * **When to use**
    *
-   * Use this for renaming or re-casing path segments, or for adding suffixes and
+   * Use when you use this for renaming or re-casing path segments, or for adding suffixes and
    * other per-segment transformations. See {@link constantCase} for a common
    * specialization.
    *
@@ -690,7 +713,7 @@ export const mapInput: {
  *
  * **When to use**
  *
- * Use this to bridge camelCase schema keys to `SCREAMING_SNAKE_CASE`
+ * Use to bridge camelCase schema keys to `SCREAMING_SNAKE_CASE`
  * environment variables.
  *
  * **Details**
@@ -725,7 +748,7 @@ export const constantCase: (self: ConfigProvider) => ConfigProvider = mapInput((
  *
  * **When to use**
  *
- * Use this to namespace config under a prefix like `"app"` or `"database"`, or
+ * Use to namespace config under a prefix like `"app"` or `"database"`, or
  * to reuse the same provider shape for multiple sub-configs.
  *
  * **Details**
@@ -764,7 +787,7 @@ export const nested: {
    *
    * **When to use**
    *
-   * Use this to namespace config under a prefix like `"app"` or `"database"`, or
+   * Use to namespace config under a prefix like `"app"` or `"database"`, or
    * to reuse the same provider shape for multiple sub-configs.
    *
    * **Details**
@@ -803,7 +826,7 @@ export const nested: {
    *
    * **When to use**
    *
-   * Use this to namespace config under a prefix like `"app"` or `"database"`, or
+   * Use to namespace config under a prefix like `"app"` or `"database"`, or
    * to reuse the same provider shape for multiple sub-configs.
    *
    * **Details**
@@ -845,12 +868,12 @@ export const nested: {
 )
 
 /**
- * Installs a `ConfigProvider` as the active provider for all downstream
- * effects, replacing any previously installed provider.
+ * Provides a layer that installs a `ConfigProvider` as the active provider for
+ * all downstream effects, replacing any previously installed provider.
  *
  * **When to use**
  *
- * Use this to set the config source for an entire application or test suite.
+ * Use to set the config source for an entire application or test suite.
  *
  * **Details**
  *
@@ -890,7 +913,7 @@ export const layer = <E = never, R = never>(
  *
  * **When to use**
  *
- * Use this to add defaults that should only apply when the primary provider
+ * Use to add defaults that should only apply when the primary provider
  * has no value for a path, or to override specific keys while keeping the rest
  * from the existing provider by setting `asPrimary: true`.
  *
@@ -940,7 +963,7 @@ export const layerAdd = <E = never, R = never>(
  *
  * **When to use**
  *
- * Use this in unit or integration tests where you want deterministic config
+ * Use when you use this in unit or integration tests where you want deterministic config
  * without touching the environment, or when embedding config directly in code
  * or reading a JSON file.
  *
@@ -1027,7 +1050,7 @@ function describeUnknown(u: unknown): Node | undefined {
  *
  * **When to use**
  *
- * Use this to read configuration from `process.env`, which is the default when
+ * Use to read configuration from `process.env`, which is the default when
  * no provider is explicitly set, or to pass a custom env record for testing or
  * non-Node runtimes.
  *
@@ -1147,7 +1170,7 @@ function trieNodeAt(root: EnvTrieNode, path: Path): EnvTrieNode | undefined {
  *
  * **When to use**
  *
- * Use this when you already have the `.env` contents as a string, such as
+ * Use when you already have the `.env` contents as a string, such as
  * contents fetched from a remote store or embedded in a test. Use
  * {@link fromDotEnv} instead if you want to read a `.env` file from disk.
  *
@@ -1289,7 +1312,7 @@ function searchLast(str: string, rgx: RegExp): number {
  *
  * **When to use**
  *
- * Use this to load environment config from a `.env` file at application
+ * Use to load environment config from a `.env` file at application
  * startup. Use {@link fromDotEnvContents} if you already have the file
  * contents as a string.
  *
@@ -1335,7 +1358,7 @@ export const fromDotEnv: (options?: {
  *
  * **When to use**
  *
- * Use this for Kubernetes ConfigMap or Secret volume mounts, where each key is
+ * Use when you use this for Kubernetes ConfigMap or Secret volume mounts, where each key is
  * a file under a mount path, or for any file-per-key configuration layout.
  *
  * **Details**

package/src/Console.ts

@@ -109,7 +109,16 @@ export interface Console {
 }
 
 /**
- * A reference to the current console service in the Effect system, allowing access to the active console implementation from within the Effect context.
+ * Context reference for the current console service in the Effect system, allowing access to the active console implementation from within the Effect context.
+ *
+ * **When to use**
+ *
+ * Use when an Effect program needs the current console service as a context
+ * reference, such as when providing or overriding a console implementation.
+ *
+ * **Details**
+ *
+ * When no override is provided, the reference resolves to `globalThis.console`.
  *
  * **Example** (Accessing the current console)
  *
@@ -123,6 +132,8 @@ export interface Console {
  * )
  * ```
  *
+ * @see {@link consoleWith} for using the current console service inside an effect
+ *
  * @category references
  * @since 2.0.0
  */
@@ -175,7 +186,17 @@ export const assert = (condition: boolean, ...args: ReadonlyArray<any>): Effect.
   )
 
 /**
- * Clears all previously logged messages from the console.
+ * Runs the current console service's clear operation.
+ *
+ * **When to use**
+ *
+ * Use to request that the active console implementation clear its visible
+ * output.
+ *
+ * **Gotchas**
+ *
+ * The clearing behavior depends on the active console implementation and host
+ * environment.
  *
  * **Example** (Clearing console output)
  *
@@ -331,7 +352,8 @@ export const dirxml = (...args: ReadonlyArray<any>): Effect.Effect<void> =>
   )
 
 /**
- * Outputs an error-level message to the console, typically displayed with error styling by the active console implementation.
+ * Writes an error-level message to the console, typically displayed with error
+ * styling by the active console implementation.
  *
  * **Example** (Writing error messages)
  *
@@ -400,7 +422,8 @@ export const group = (
   )
 
 /**
- * Outputs an informational message to the console, typically displayed with info styling by the active console implementation.
+ * Writes an informational message to the console, typically displayed with info
+ * styling by the active console implementation.
  *
  * **Example** (Writing informational messages)
  *
@@ -427,7 +450,7 @@ export const info = (...args: ReadonlyArray<any>): Effect.Effect<void> =>
   )
 
 /**
- * Outputs a general-purpose message to the console for ordinary logging.
+ * Logs a general-purpose message to the console.
  *
  * **Example** (Writing log messages)
  *
@@ -548,7 +571,8 @@ export const timeLog = (label?: string, ...args: ReadonlyArray<any>): Effect.Eff
   )
 
 /**
- * Outputs the current stack trace to the console to show how the current point in the code was reached.
+ * Writes the current stack trace to the console to show how the current point in
+ * the code was reached.
  *
  * **Example** (Writing stack traces)
  *
@@ -572,7 +596,8 @@ export const trace = (...args: ReadonlyArray<any>): Effect.Effect<void> =>
   )
 
 /**
- * Outputs a warning-level message to the console, typically displayed with warning styling by the active console implementation.
+ * Writes a warning-level message to the console, typically displayed with
+ * warning styling by the active console implementation.
  *
  * **Example** (Writing warning messages)
  *