Skip to content

Commit 5287b24

Browse files
authored
Refine ConfigProvider interface (#6788)
1 parent 9263ba3 commit 5287b24

8 files changed

Lines changed: 611 additions & 425 deletions

File tree

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
"effect": patch
3+
---
4+
5+
Refine the `ConfigProvider` interface so lookup absence is explicit and path
6+
transformation is provider behavior.
7+
8+
`ConfigProvider.load` and the lookup function accepted by
9+
`ConfigProvider.make` now return `Option<Node>`. Use `Option.none()` when a path
10+
does not exist and `Option.some(node)` when it does.
11+
12+
`ConfigProvider` now exposes `mapInput` as a capability. The exported
13+
`ConfigProvider.mapInput` combinator delegates to it, preserving transformation
14+
order and composition through `orElse` without requiring provider
15+
representation state.

‎migration/v3-to-v4.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9059,7 +9059,7 @@ Schema.toArbitraryLazy(schema)
90599059

90609060
### `effect/ConfigProvider`
90619061

9062-
- `ConfigProvider.ConfigProvider` -> `ConfigProvider.ConfigProvider`: The model remains but now exposes load(path), returning a raw Node or undefined, and has one unified provider representation.
9062+
- `ConfigProvider.ConfigProvider` -> `ConfigProvider.ConfigProvider`: The model remains but now exposes `load(path)`, returning `Effect<Option<Node>, SourceError>`, and `mapInput(f)` for provider-owned path transformation. `Option.none()` means the path is missing; `Option.some(node)` means it exists.
90639063

90649064
- `ConfigProvider.ConfigProvider.Flat` -> `ConfigProvider.ConfigProvider`: Flat providers were removed; implement the unified path-based provider with ConfigProvider.make.
90659065

@@ -9081,7 +9081,7 @@ Schema.toArbitraryLazy(schema)
90819081

90829082
- `ConfigProvider.fromEnv` -> `ConfigProvider.fromEnv`: The constructor remains; pass env and preserveEmptyStrings options. Paths use underscore semantics, while sequence separators belong on Config schemas.
90839083

9084-
- `ConfigProvider.fromFlat` -> `ConfigProvider.make`: Flat providers were unified with ConfigProvider; implement load by returning Value, Record, or Array nodes for each path.
9084+
- `ConfigProvider.fromFlat` -> `ConfigProvider.make`: Flat providers were unified with ConfigProvider; implement lookup by returning `Option.some(node)` for a found `Value`, `Record`, or `Array` node, or `Option.none()` when missing.
90859085

90869086
- `ConfigProvider.fromJson` -> `ConfigProvider.fromUnknown`: Renamed to reflect support for any in-memory JavaScript value.
90879087

@@ -9091,9 +9091,9 @@ Schema.toArbitraryLazy(schema)
90919091

90929092
- `ConfigProvider.lowerCase` -> `ConfigProvider.mapInput((path) => path.map((part) => typeof part === "string" ? part.toLowerCase() : part))`: Transform string path segments explicitly with mapInput.
90939093

9094-
- `ConfigProvider.make` -> `ConfigProvider.make`: The constructor now takes a path lookup returning Effect\<Node | undefined, SourceError\>, rather than a full Config loader and flattened provider.
9094+
- `ConfigProvider.make` -> `ConfigProvider.make`: The constructor now takes a path lookup returning `Effect<Option<Node>, SourceError>`, rather than a full Config loader and flattened provider. Use `Option.none()` for a missing path and `Option.some(node)` for a found node.
90959095

9096-
- `ConfigProvider.makeFlat` -> `ConfigProvider.make`: The flat-provider constructor was removed; return Value, Record, or Array nodes from the unified path lookup.
9096+
- `ConfigProvider.makeFlat` -> `ConfigProvider.make`: The flat-provider constructor was removed; return `Option.some(node)` for a found `Value`, `Record`, or `Array` node, or `Option.none()` when missing.
90979097

90989098
- `ConfigProvider.mapInputPath` -> `ConfigProvider.mapInput`: Renamed and generalized: the callback receives and returns the complete Path, including numeric array indexes.
90999099

‎packages/effect/CONFIG.md‎

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -242,6 +242,16 @@ For reusable codecs you can pass directly to `Config.schema`:
242242

243243
The concrete built-in source providers `fromEnv`, `fromDotEnvContents`, `fromDotEnv`, `fromUnknown`, and `fromDir` treat literal empty strings as missing values by default when they are loaded as values. Container discovery still reflects the source structure, so a key or file can appear in a `Record` or `Array` node and then load as missing. Pass `{ preserveEmptyStrings: true }` to preserve empty strings as explicit values.
244244

245+
At the raw provider interface, `load(path)` succeeds with an `Option<Node>`:
246+
`Option.some(node)` means the path exists, while `Option.none()` means it does
247+
not. A `SourceError` represents a failure to read the source and remains in the
248+
Effect error channel.
249+
250+
This lookup-level `Option` is distinct from the `value` field of a found
251+
`Record` or `Array` node. Such a container can exist while
252+
`node.value === undefined`, which means that it has children but no co-located
253+
scalar value.
254+
245255
### `ConfigProvider.fromEnv` — Environment Variables (Default)
246256

247257
This is the default provider. Path segments are joined with `_` for lookup.
@@ -360,14 +370,14 @@ const program = Effect.gen(function*() {
360370

361371
Requires `Path` and `FileSystem` in the Effect context.
362372

363-
Missing files and directories return `undefined`, so fallback providers can handle the path. Empty files also return `undefined` by default after trimming their contents, while directory listings still report the file names present on disk; pass `{ preserveEmptyStrings: true }` to preserve them as `Value("")`. Other file-system failures are reported as `SourceError`.
373+
Missing files and directories return `Option.none()`, so fallback providers can handle the path. Empty files also return `Option.none()` by default after trimming their contents, while directory listings still report the file names present on disk; pass `{ preserveEmptyStrings: true }` to preserve them as `Value("")`. Other file-system failures are reported as `SourceError`.
364374

365375
### `ConfigProvider.make` — Custom Sources
366376

367377
Build a provider from any backing store:
368378

369379
```ts
370-
import { ConfigProvider, Effect } from "effect"
380+
import { ConfigProvider, Effect, Option } from "effect"
371381

372382
const data: Record<string, string> = {
373383
host: "localhost",
@@ -378,18 +388,23 @@ const provider = ConfigProvider.make((path) => {
378388
const key = path.join(".")
379389
const value = data[key]
380390
return Effect.succeed(
381-
value !== undefined ? ConfigProvider.makeValue(value) : undefined
391+
value !== undefined
392+
? Option.some(ConfigProvider.makeValue(value))
393+
: Option.none()
382394
)
383395
})
384396
```
385397

386-
Return `undefined` for "not found". Only fail with `SourceError` for actual I/O errors.
398+
Return `Option.none()` for "not found" and `Option.some(node)` for a node that
399+
exists. Only fail with `SourceError` when the source itself cannot be read.
400+
Providers created with `make` automatically support the path-transformation
401+
behavior used by `mapInput`, `constantCase`, and `nested`.
387402

388403
## ConfigProvider Combinators
389404

390405
### `ConfigProvider.orElse` — Fallback Sources
391406

392-
Falls back to a second provider when the first returns `undefined` (path not found). Does **not** catch `SourceError`.
407+
Falls back to a second provider when the first returns `Option.none()` (path not found). Does **not** catch `SourceError`.
393408

394409
```ts
395410
import { ConfigProvider } from "effect"
@@ -512,6 +527,14 @@ const upper = ConfigProvider.mapInput(
512527
)
513528
```
514529

530+
Path transformation is a capability of the `ConfigProvider` interface. The
531+
exported `ConfigProvider.mapInput` combinator delegates to that capability,
532+
rather than passing an extra transformation argument to `load`. This keeps
533+
ordinary lookup fixed as `load(path)` and allows composite providers to
534+
preserve their own behavior without exposing representation state. Custom
535+
source providers should normally be constructed with `ConfigProvider.make`,
536+
which implements this capability automatically.
537+
515538
`mapInput` runs after earlier provider transformations, so it sees the full path produced so far:
516539

517540
```ts

‎packages/effect/src/Config.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -499,7 +499,7 @@ const dump: (
499499
provider,
500500
path
501501
) {
502-
const stat = yield* provider.load(path)
502+
const stat = Option.getOrUndefined(yield* provider.load(path))
503503
if (stat === undefined) return undefined
504504
switch (stat._tag) {
505505
case "Value":
@@ -532,7 +532,7 @@ const recur: (
532532
function*(ast, provider, path) {
533533
switch (ast._tag) {
534534
case "Objects": {
535-
const stat = yield* provider.load(path)
535+
const stat = Option.getOrUndefined(yield* provider.load(path))
536536
if (stat === undefined && path.length > 0) return undefined
537537
const out: Record<string, Schema.StringTree> = {}
538538
for (const ps of ast.propertySignatures) {
@@ -558,7 +558,7 @@ const recur: (
558558
return out
559559
}
560560
case "Arrays": {
561-
const stat = yield* provider.load(path)
561+
const stat = Option.getOrUndefined(yield* provider.load(path))
562562
if (stat === undefined) return undefined
563563
if (stat && stat._tag === "Value") return stat.value === "" ? [] : stat.value.split(",")
564564
if (stat && stat._tag === "Array" && stat.value !== undefined) {
@@ -581,7 +581,7 @@ const recur: (
581581
return yield* recur(ast.thunk(), provider, path)
582582
default: {
583583
// Base primitives / string-like encoded nodes.
584-
const stat = yield* provider.load(path)
584+
const stat = Option.getOrUndefined(yield* provider.load(path))
585585
if (stat === undefined) return undefined
586586
if (stat._tag === "Value") return stat.value
587587
if (stat._tag === "Record" && stat.value !== undefined) return stat.value

0 commit comments

Comments
 (0)