effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/Config.ts

@@ -81,10 +81,10 @@ import * as Option from "./Option.ts"
 import * as Predicate from "./Predicate.ts"
 import * as Rec from "./Record.ts"
 import * as Schema from "./Schema.ts"
-import * as AST from "./SchemaAST.ts"
-import * as Issue from "./SchemaIssue.ts"
-import * as Parser from "./SchemaParser.ts"
-import * as Transformation from "./SchemaTransformation.ts"
+import * as SchemaAST from "./SchemaAST.ts"
+import * as SchemaIssue from "./SchemaIssue.ts"
+import * as SchemaParser from "./SchemaParser.ts"
+import * as SchemaTransformation from "./SchemaTransformation.ts"
 
 const TypeId = "~effect/Config"
 
@@ -93,8 +93,8 @@ const TypeId = "~effect/Config"
  *
  * **When to use**
  *
- * Use when runtime type-checking before calling `.parse()` on an unknown value.
- * - Distinguishing a `Config` from a plain value inside {@link unwrap}.
+ * Use when you need to distinguish a `Config` from an unknown value before
+ * calling `.parse` or {@link unwrap}.
  *
  * **Example** (Type guard)
  *
@@ -115,9 +115,7 @@ export const isConfig = (u: unknown): u is Config<unknown> => Predicate.hasPrope
  *
  * **When to use**
  *
- * Use when match on `error.cause._tag` to distinguish source failures from
- *   validation failures.
- * - Pass to {@link fail} to create a Config that always errors.
+ * Use when you need to inspect config loading or validation failures.
  *
  * **Details**
  *
@@ -196,7 +194,7 @@ const Proto = {
  * **When to use**
  *
  * Use to build a custom config that cannot be expressed with {@link schema} or
- * convenience constructors, or to compose configs programmatically.
+ * convenience constructors, or compose configs programmatically.
  *
  * **Details**
  *
@@ -238,8 +236,8 @@ export function make<T>(
  *
  * **When to use**
  *
- * Use when post-processing a config value (e.g. trimming, uppercasing, wrapping).
- * - The transformation cannot fail. Use {@link mapOrFail} if it can.
+ * Use when you need to transform a parsed config value with a function that
+ * cannot fail.
  *
  * **Details**
  *
@@ -269,8 +267,8 @@ export const map: {
    *
    * **When to use**
    *
-   * Use when post-processing a config value (e.g. trimming, uppercasing, wrapping).
-   * - The transformation cannot fail. Use {@link mapOrFail} if it can.
+   * Use when you need to transform a parsed config value with a function that
+   * cannot fail.
    *
    * **Details**
    *
@@ -300,8 +298,8 @@ export const map: {
    *
    * **When to use**
    *
-   * Use when post-processing a config value (e.g. trimming, uppercasing, wrapping).
-   * - The transformation cannot fail. Use {@link mapOrFail} if it can.
+   * Use when you need to transform a parsed config value with a function that
+   * cannot fail.
    *
    * **Details**
    *
@@ -335,8 +333,8 @@ export const map: {
  *
  * **When to use**
  *
- * Use to validate or converting a config value where the transformation can
- *   produce a `ConfigError` (e.g. parsing a URL, checking a range).
+ * Use when you need to transform a parsed config value with a function that can
+ * produce a `ConfigError` (e.g. parsing a URL, checking a range).
  *
  * **Details**
  *
@@ -363,8 +361,8 @@ export const mapOrFail: {
    *
    * **When to use**
    *
-   * Use to validate or converting a config value where the transformation can
-   *   produce a `ConfigError` (e.g. parsing a URL, checking a range).
+   * Use when you need to transform a parsed config value with a function that can
+   * produce a `ConfigError` (e.g. parsing a URL, checking a range).
    *
    * **Details**
    *
@@ -391,8 +389,8 @@ export const mapOrFail: {
    *
    * **When to use**
    *
-   * Use to validate or converting a config value where the transformation can
-   *   produce a `ConfigError` (e.g. parsing a URL, checking a range).
+   * Use when you need to transform a parsed config value with a function that can
+   * produce a `ConfigError` (e.g. parsing a URL, checking a range).
    *
    * **Details**
    *
@@ -423,8 +421,8 @@ export const mapOrFail: {
  *
  * **When to use**
  *
- * Use when trying an alternative config source when the primary one errors.
- * - Providing environment-specific overrides.
+ * Use when you need to try an alternative config source after the primary one
+ * fails.
  *
  * **Details**
  *
@@ -455,8 +453,8 @@ export const orElse: {
    *
    * **When to use**
    *
-   * Use when trying an alternative config source when the primary one errors.
-   * - Providing environment-specific overrides.
+   * Use when you need to try an alternative config source after the primary one
+   * fails.
    *
    * **Details**
    *
@@ -487,8 +485,8 @@ export const orElse: {
    *
    * **When to use**
    *
-   * Use when trying an alternative config source when the primary one errors.
-   * - Providing environment-specific overrides.
+   * Use when you need to try an alternative config source after the primary one
+   * fails.
    *
    * **Details**
    *
@@ -523,7 +521,7 @@ export const orElse: {
  *
  * **When to use**
  *
- * Use when grouping related configs into a tuple or named struct.
+ * Use when you need to group related configs into a tuple or named struct.
  *
  * **Details**
  *
@@ -572,7 +570,7 @@ export function all<const Arg extends Iterable<Config<any>> | Record<string, Con
   }
 }
 
-function isMissingDataOnly(issue: Issue.Issue): boolean {
+function isMissingDataOnly(issue: SchemaIssue.Issue): boolean {
   switch (issue._tag) {
     case "MissingKey":
       return true
@@ -603,7 +601,7 @@ function isMissingDataOnly(issue: Issue.Issue): boolean {
  *
  * **When to use**
  *
- * Use when making a config key optional with a sensible default.
+ * Use when you need to make a config key optional with a sensible default.
  *
  * **Details**
  *
@@ -639,7 +637,7 @@ export const withDefault: {
    *
    * **When to use**
    *
-   * Use when making a config key optional with a sensible default.
+   * Use when you need to make a config key optional with a sensible default.
    *
    * **Details**
    *
@@ -675,7 +673,7 @@ export const withDefault: {
    *
    * **When to use**
    *
-   * Use when making a config key optional with a sensible default.
+   * Use when you need to make a config key optional with a sensible default.
    *
    * **Details**
    *
@@ -724,8 +722,7 @@ export const withDefault: {
  *
  * **When to use**
  *
- * Use when a config key may or may not be present and you want to handle both
- *   cases explicitly.
+ * Use when you need to handle a config key that may or may not be present.
  *
  * **Gotchas**
  *
@@ -874,7 +871,7 @@ const dump: (
 })
 
 const recur: (
-  ast: AST.AST,
+  ast: SchemaAST.AST,
   provider: ConfigProvider.ConfigProvider,
   path: Path
 ) => Effect.Effect<Schema.StringTree, Schema.SchemaError | SourceError> = Effect.fnUntraced(
@@ -893,7 +890,7 @@ const recur: (
           const stat = yield* provider.load(path)
           if (stat && stat._tag === "Record") {
             for (const is of ast.indexSignatures) {
-              const matches = Parser._is(is.parameter)
+              const matches = SchemaParser._is(is.parameter)
               for (const key of stat.keys) {
                 if (!Object.hasOwn(out, key) && matches(key)) {
                   const value = yield* recur(is.type, provider, [...path, key])
@@ -938,15 +935,16 @@ const recur: (
  *
  * **When to use**
  *
- * Use when reading structured or validated config (structs, arrays, unions, branded
- *   types, etc.).
- * - All convenience constructors (`string`, `number`, …) delegate to this.
+ * Use when you need to read structured or schema-validated configuration.
  *
  * **Details**
  *
  * The optional `path` sets the root path segment(s) for the config lookup.
  * Pass a single string for a flat key or an array for nested paths.
  *
+ * Convenience constructors such as `string`, `number`, and `boolean` delegate
+ * to this API.
+ *
  * The codec is used to decode the raw `StringTree` produced by the provider
  * into `T`. Schema validation errors are wrapped in `ConfigError`.
  *
@@ -979,8 +977,8 @@ const recur: (
  */
 export function schema<T, E>(codec: Schema.Codec<T, E>, path?: string | ConfigProvider.Path): Config<T> {
   const codecStringTree = Schema.toCodecStringTree(codec)
-  const decodeUnknownEffect = Parser.decodeUnknownEffect(codecStringTree)
-  const codecStringTreeEncoded = AST.toEncoded(codecStringTree.ast)
+  const decodeUnknownEffect = SchemaParser.decodeUnknownEffect(codecStringTree)
+  const codecStringTreeEncoded = SchemaAST.toEncoded(codecStringTree.ast)
   const defaultPath = typeof path === "string" ? [path] : path ?? []
   return make((provider) => {
     const path = provider.prefix ? [...provider.prefix, ...defaultPath] : defaultPath
@@ -988,7 +986,7 @@ export function schema<T, E>(codec: Schema.Codec<T, E>, path?: string | ConfigPr
       Effect.flatMapEager((tree) =>
         decodeUnknownEffect(tree).pipe(
           Effect.mapErrorEager((issue) =>
-            new Schema.SchemaError(path.length > 0 ? new Issue.Pointer(path, issue) : issue)
+            new Schema.SchemaError(path.length > 0 ? new SchemaIssue.Pointer(path, issue) : issue)
           )
         )
       ),
@@ -1008,8 +1006,8 @@ export const FalseValues = Schema.Literals(["false", "no", "off", "0", "n"])
  *
  * **When to use**
  *
- * Use when passing to {@link schema} for custom paths, or use the
- * {@link boolean} convenience constructor.
+ * Use when you need the reusable boolean schema value for `Config.schema` with
+ * custom paths.
  *
  * **Details**
  *
@@ -1024,7 +1022,7 @@ export const FalseValues = Schema.Literals(["false", "no", "off", "0", "n"])
 export const Boolean = Schema.Literals([...TrueValues.literals, ...FalseValues.literals]).pipe(
   Schema.decodeTo(
     Schema.Boolean,
-    Transformation.transform({
+    SchemaTransformation.transform({
       decode: (value) => value === "true" || value === "yes" || value === "on" || value === "1" || value === "y",
       encode: (value) => value ? "true" : "false"
     })
@@ -1036,8 +1034,8 @@ export const Boolean = Schema.Literals([...TrueValues.literals, ...FalseValues.l
  *
  * **When to use**
  *
- * Use when passing to {@link schema} for custom paths, or use the {@link port}
- * convenience constructor.
+ * Use when you need the reusable port schema value for `Config.schema` with
+ * custom paths.
  *
  * @see {@link port} – convenience constructor
  *
@@ -1051,8 +1049,8 @@ export const Port = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 655
  *
  * **When to use**
  *
- * Use when passing to {@link schema} for custom paths, or use the
- * {@link logLevel} convenience constructor.
+ * Use when you need the reusable log-level schema value for `Config.schema`
+ * with custom paths.
  *
  * **Details**
  *
@@ -1115,7 +1113,7 @@ export const Record = <K extends Schema.Record.Key, V extends Schema.Top>(key: K
   const recordString = Schema.String.pipe(
     Schema.decodeTo(
       Schema.Record(Schema.String, Schema.String),
-      Transformation.splitKeyValue(options)
+      SchemaTransformation.splitKeyValue(options)
     ),
     Schema.decodeTo(record)
   )
@@ -1132,8 +1130,8 @@ export const Record = <K extends Schema.Record.Key, V extends Schema.Top>(key: K
  *
  * **When to use**
  *
- * Use when inside {@link orElse} to re-raise a specific error.
- * - Testing error handling paths.
+ * Use when you need to re-raise a specific config error, such as inside
+ * {@link orElse}.
  *
  * @category constructors
  * @since 2.0.0
@@ -1148,8 +1146,8 @@ export function fail(err: SourceError | Schema.SchemaError) {
  *
  * **When to use**
  *
- * Use when providing a hardcoded constant inside {@link orElse}.
- * - Testing.
+ * Use when you need a hardcoded config value, such as inside {@link orElse} or
+ * tests.
  *
  * **Example** (Constant fallback)
  *
@@ -1226,7 +1224,8 @@ export function nonEmptyString(name?: string) {
  *
  * **When to use**
  *
- * Use to read a numeric config value when `NaN` and `Infinity` are acceptable.
+ * Use when you need config input to accept JavaScript's full number domain,
+ * including NaN and infinities, rather than reject non-finite values.
  *
  * **Details**
  *
@@ -1307,7 +1306,7 @@ export function int(name?: string) {
  * @category constructors
  * @since 2.0.0
  */
-export function literal<L extends AST.LiteralValue>(literal: L, name?: string) {
+export function literal<L extends SchemaAST.LiteralValue>(literal: L, name?: string) {
   return schema(Schema.Literal(literal), name)
 }
 
@@ -1335,7 +1334,7 @@ export function literal<L extends AST.LiteralValue>(literal: L, name?: string) {
  * @category constructors
  * @since 4.0.0
  */
-export function literals<const L extends ReadonlyArray<AST.LiteralValue>>(literals: L, name?: string) {
+export function literals<const L extends ReadonlyArray<SchemaAST.LiteralValue>>(literals: L, name?: string) {
   return schema(Schema.Literals(literals), name)
 }
 
@@ -1662,9 +1661,7 @@ export function date(name?: string) {
  *
  * **When to use**
  *
- * Use when grouping related config keys under a common namespace (e.g.
- *   `"database"`, `"redis"`).
- * - Building reusable config fragments that callers nest at different paths.
+ * Use when you need to group related config keys under a common namespace.
  *
  * **Details**
  *
@@ -1717,9 +1714,7 @@ export const nested: {
    *
    * **When to use**
    *
-   * Use when grouping related config keys under a common namespace (e.g.
-   *   `"database"`, `"redis"`).
-   * - Building reusable config fragments that callers nest at different paths.
+   * Use when you need to group related config keys under a common namespace.
    *
    * **Details**
    *
@@ -1772,9 +1767,7 @@ export const nested: {
    *
    * **When to use**
    *
-   * Use when grouping related config keys under a common namespace (e.g.
-   *   `"database"`, `"redis"`).
-   * - Building reusable config fragments that callers nest at different paths.
+   * Use when you need to group related config keys under a common namespace.
    *
    * **Details**
    *

package/src/ConfigProvider.ts

@@ -173,7 +173,7 @@ export function makeValue(value: string): Node {
  *
  * **When to use**
  *
- * Use when describing a directory or JSON object inside a custom
+ * Use when you need to describe a directory or JSON object inside a custom
  * provider.
  *
  * **Details**
@@ -207,8 +207,8 @@ export function makeRecord(keys: ReadonlySet<string>, value?: string): Node {
  *
  * **When to use**
  *
- * Use when describing a JSON array or a set of numerically-indexed env
- * vars inside a custom provider.
+ * Use when you need to describe a JSON array or numerically indexed env vars
+ * inside a custom provider.
  *
  * **Details**
  *
@@ -239,9 +239,8 @@ export function makeArray(length: number, value?: string): Node {
  *
  * **When to use**
  *
- * 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.
+ * Use when you need to report that a custom provider's underlying store is
+ * unreachable or produced an I/O error while reading configuration data.
  *
  * **Gotchas**
  *
@@ -367,10 +366,8 @@ export interface ConfigProvider extends Pipeable {
  *
  * **When to use**
  *
- * 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`.
+ * Use to override the active raw configuration provider for an entire program,
+ * or retrieve the current provider inside an Effect.
  *
  * **Example** (Providing a custom provider)
  *
@@ -473,8 +470,8 @@ export function make(
  *
  * **When to use**
  *
- * 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.
+ * Use to layer multiple config sources, such as env vars plus a defaults file,
+ * or provide partial overrides on top of a base config.
  *
  * **Details**
  *
@@ -510,8 +507,8 @@ export const orElse: {
    *
    * **When to use**
    *
-   * 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.
+   * Use to layer multiple config sources, such as env vars plus a defaults file,
+   * or provide partial overrides on top of a base config.
    *
    * **Details**
    *
@@ -547,8 +544,8 @@ export const orElse: {
    *
    * **When to use**
    *
-   * 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.
+   * Use to layer multiple config sources, such as env vars plus a defaults file,
+   * or provide partial overrides on top of a base config.
    *
    * **Details**
    *
@@ -589,9 +586,8 @@ export const orElse: {
  *
  * **When to use**
  *
- * 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.
+ * Use when you need to rename, re-case, or otherwise transform config path
+ * segments before lookup.
  *
  * **Details**
  *
@@ -628,9 +624,8 @@ export const mapInput: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need to rename, re-case, or otherwise transform config path
+   * segments before lookup.
    *
    * **Details**
    *
@@ -667,9 +662,8 @@ export const mapInput: {
    *
    * **When to use**
    *
-   * 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.
+   * Use when you need to rename, re-case, or otherwise transform config path
+   * segments before lookup.
    *
    * **Details**
    *
@@ -749,7 +743,7 @@ export const constantCase: (self: ConfigProvider) => ConfigProvider = mapInput((
  * **When to use**
  *
  * Use to namespace config under a prefix like `"app"` or `"database"`, or
- * to reuse the same provider shape for multiple sub-configs.
+ * reuse the same provider shape for multiple sub-configs.
  *
  * **Details**
  *
@@ -788,7 +782,7 @@ export const nested: {
    * **When to use**
    *
    * Use to namespace config under a prefix like `"app"` or `"database"`, or
-   * to reuse the same provider shape for multiple sub-configs.
+   * reuse the same provider shape for multiple sub-configs.
    *
    * **Details**
    *
@@ -827,7 +821,7 @@ export const nested: {
    * **When to use**
    *
    * Use to namespace config under a prefix like `"app"` or `"database"`, or
-   * to reuse the same provider shape for multiple sub-configs.
+   * reuse the same provider shape for multiple sub-configs.
    *
    * **Details**
    *
@@ -913,9 +907,9 @@ export const layer = <E = never, R = never>(
  *
  * **When to use**
  *
- * 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`.
+ * Use to add defaults that should only apply when the primary provider has no
+ * value for a path, or override specific keys while keeping the rest from the
+ * existing provider by setting `asPrimary: true`.
  *
  * **Details**
  *
@@ -963,9 +957,8 @@ export const layerAdd = <E = never, R = never>(
  *
  * **When to use**
  *
- * 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.
+ * Use when you need deterministic config from an in-memory JavaScript value,
+ * such as in tests, embedded config, or parsed JSON.
  *
  * **Details**
  *
@@ -1050,8 +1043,8 @@ function describeUnknown(u: unknown): Node | undefined {
  *
  * **When to use**
  *
- * 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
+ * Use to read configuration from `process.env`, which is the default when no
+ * provider is explicitly set, or pass a custom env record for testing or
  * non-Node runtimes.
  *
  * **Details**
@@ -1170,9 +1163,8 @@ function trieNodeAt(root: EnvTrieNode, path: Path): EnvTrieNode | undefined {
  *
  * **When to use**
  *
- * 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.
+ * Use when you already have the `.env` contents as a string, such as contents
+ * fetched from a remote store or embedded in a test.
  *
  * **Details**
  *
@@ -1312,9 +1304,7 @@ function searchLast(str: string, rgx: RegExp): number {
  *
  * **When to use**
  *
- * 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.
+ * Use to load environment config from a `.env` file at application startup.
  *
  * **Details**
  *
@@ -1358,8 +1348,8 @@ export const fromDotEnv: (options?: {
  *
  * **When to use**
  *
- * 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.
+ * Use when you expose each config key as a file under a directory, such as
+ * Kubernetes ConfigMap or Secret volume mounts.
  *
  * **Details**
  *

package/src/Console.ts

@@ -113,8 +113,8 @@ export interface Console {
  *
  * **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.
+ * Use when you need an effect to run against a provided console implementation,
+ * such as tests or alternate runtimes, rather than the default console.
  *
  * **Details**
  *