@effected/config-file 0.19.1 → 0.20.0

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
 [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-Composable config file loading for Effect. Declare a resolver chain — an explicit path, an upward walk from the cwd, the workspace or git root, `/etc` — decode every discovered file through an Effect `Schema`, and combine the results with a merge strategy. JSON, JSONC, YAML and TOML all decode with no extra install. Codecs, resolvers and merge strategies are pluggable seams, and failures arrive as tagged errors carrying structured payloads rather than prose, so "no config anywhere" is routable separately from "the config I found is broken".
+Composable config file loading for Effect. Declare a resolver chain — an explicit path, an upward walk from the cwd, the workspace or git root, `/etc` — decode every discovered file through an Effect `Schema`, and combine the results with a merge strategy. JSON decodes out of the box; JSONC, YAML and TOML each take one optional engine package. Codecs, resolvers and merge strategies are pluggable seams, and failures arrive as tagged errors carrying structured payloads rather than prose, so "no config anywhere" is routable separately from "the config I found is broken".
 
 > **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
 > Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
@@ -33,11 +33,17 @@ npm install @effected/config-file effect @effect/platform-node
 pnpm add @effected/config-file effect @effect/platform-node
 ```
 
-Requires Node.js >=24.11.0. Every format is covered by that one install; there is no separate package to add for YAML or TOML.
+Requires Node.js >=24.11.0. That install covers JSON. To read JSONC, YAML or TOML, add the matching engine:
+
+```bash
+pnpm add @effected/jsonc   # for @effected/config-file/jsonc
+pnpm add @effected/yaml    # for @effected/config-file/yaml
+pnpm add @effected/toml    # for @effected/config-file/toml
+```
 
 All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module.
 
-`effect` v4 is a peer dependency, and so are `@effected/jsonc`, `@effected/toml`, `@effected/walker` and `@effected/yaml` — the first-party engines behind the JSONC, YAML and TOML codecs, plus the traversal primitive the `upwardWalk`, `workspaceRoot` and `gitRoot` resolvers are built on. Package managers that install peers automatically will pull them in; add them to your manifest explicitly if yours does not. The package declares no runtime dependencies of its own, so nothing it drags into your tree comes from outside `effect` and `@effected/*`.
+`effect` v4 is a peer dependency, and so are `@effected/walker` and `@effected/glob` — the traversal primitive the `upwardWalk`, `workspaceRoot` and `gitRoot` resolvers are built on, and the matcher it peers on. Package managers that install peers automatically will pull them in; add them to your manifest explicitly if yours does not. `@effected/jsonc`, `@effected/yaml` and `@effected/toml` are **optional** peers: only the `./jsonc`, `./yaml` and `./toml` subpaths load them, and the package root never does, so a JSON-only program installs and loads none of them. The package declares no runtime dependencies of its own, so nothing it drags into your tree comes from outside `effect` and `@effected/*`.
 
 Reading and writing files needs a `FileSystem` and a `Path` implementation, provided once at the edge — from `@effect/platform-node` on Node.
 
@@ -80,7 +86,8 @@ Effect.runPromise(program.pipe(Effect.provide(AppConfigLive), Effect.provide(Pla
 Resolvers are consulted in priority order, highest first. `MergeStrategy.firstMatch` takes the winner; `MergeStrategy.layeredMerge` deep-merges every source that matched, with higher-priority keys overwriting lower ones:
 
 ```ts
-import { ConfigFile, ConfigResolver, MergeStrategy, YamlCodec } from "@effected/config-file";
+import { ConfigFile, ConfigResolver, MergeStrategy } from "@effected/config-file";
+import { YamlCodec } from "@effected/config-file/yaml";
 import { Schema } from "effect";
 
 class Settings extends Schema.Class<Settings>("Settings")({ port: Schema.Number }) {}
@@ -176,16 +183,16 @@ export const loadOrFallback = (config: ConfigFileShape<AppShape>) =>
 
 ## Codecs
 
-Four codecs ship in the package, each a free-standing named export:
+Four codecs ship in the package, each a free-standing named export. `JsonCodec` comes from the package root; the other three each have their own subpath and an optional engine peer to install beside it:
 
-| Codec | Format | Engine |
-| ----- | ------ | ------ |
-| `JsonCodec` | JSON | the host `JSON` global, no parser at all |
-| `JsoncCodec` | JSONC | `@effected/jsonc` |
-| `YamlCodec` | YAML | `@effected/yaml` |
-| `TomlCodec` | TOML | `@effected/toml` |
+| Codec | Format | Import from | Engine |
+| ----- | ------ | ----------- | ------ |
+| `JsonCodec` | JSON | `@effected/config-file` | the host `JSON` global, no parser at all |
+| `JsoncCodec` | JSONC | `@effected/config-file/jsonc` | `@effected/jsonc` |
+| `YamlCodec` | YAML | `@effected/config-file/yaml` | `@effected/yaml` |
+| `TomlCodec` | TOML | `@effected/config-file/toml` | `@effected/toml` |
 
-One install covers every format, and you still pay only for the parser you name. The codecs are free-standing exports rather than properties of a namespace object, so importing `TomlCodec` never references the YAML or JSONC bindings, their parsing engines are unreachable from your entrypoint and a bundler drops them. A JSON-only application ships no parser at all.
+You install and load only the parser you name. The root never reaches a subpath, so a JSON-only application installs no parser and ships none. Each subpath reaches only its own engine, and the codecs are never collected into a namespace object, so importing `TomlCodec` never references the YAML or JSONC bindings.
 
 Codecs compose. `EncryptedCodec` wraps any codec with AES-GCM, and `ConfigMigration.make` wraps any codec so parsed content is brought up to the latest version. Each *widens* the error channel rather than flattening its failures into the inner codec's error, and a decorated codec plugs into `ConfigFile.layer`, `ConfigFile.testLayer` and `ConfigFile.read` like any other: their error unions widen with it. A service key names the widened error as its third type argument:
 
@@ -242,7 +249,7 @@ Leave the third type argument off and the `ConfigFile.layer` call is a compile e
 - `encode` / `write` / `save` / `update` — the write path. `encode(value, options?)` returns the serialized text a `write` would put on disk without writing, emitting an event or naming a path in its errors: the primitive behind a `--dry-run` flag. `write` takes an explicit path the caller vouches for; `save` and `update` resolve the layer's `defaultPath` and create its parent directory. `encode` and `write` accept `{ header }`, text prepended verbatim above the document with exactly one newline between — a `#:schema https://…` directive atop a TOML file, say. The caller owns its validity in the target format; JSON has no comment syntax, so a header on `JsonCodec` yields an unparseable file by construction.
 - `ConfigResolver` — `explicitPath`, `staticDir`, `upwardWalk`, `workspaceRoot`, `gitRoot` and `systemEtc`. A resolver's error channel is `never` by contract: every filesystem failure becomes `Option.none()`, so one unreadable tier never aborts the chain.
 - `MergeStrategy` — `firstMatch` and `layeredMerge`, combining discovered sources in priority order.
-- `JsonCodec`, `JsoncCodec`, `YamlCodec`, `TomlCodec` — JSON, JSONC, YAML and TOML in the box, exported free-standing so an unused format's engine is tree-shaken away.
+- `JsonCodec` (root), `JsoncCodec` (`./jsonc`), `YamlCodec` (`./yaml`), `TomlCodec` (`./toml`) — JSON, JSONC, YAML and TOML, exported free-standing and split by subpath so an unused format's engine is neither installed nor loaded.
 - `ConfigCodec` / `EncryptedCodec` / `ConfigMigration` — a pluggable codec seam, generic in its error type so decorators widen rather than flatten. `ConfigCodec` is the interface: bring your own format by satisfying it.
 - `ConfigEvents` — an opt-in `PubSub` of `ConfigEvent`, honestly zero-cost when omitted: no `events` option means no context lookup at all. Failure events carry the structured typed error, never a `reason` string.
 - `asConfigProvider` / `layerConfigProvider` — expose a loaded, validated document as a v4 `ConfigProvider`, layered beneath the ambient one so an environment variable overrides the file it was deployed with.

package/index.d.ts

@@ -48,13 +48,14 @@ export declare class ConfigCodecError extends ConfigCodecError_base {
  * decorator codecs such as `EncryptedCodec` and `ConfigMigration.make` widen it
  * rather than flattening their own failures into a string.
  *
- * The four built-in codecs — `JsonCodec`, `JsoncCodec`, `YamlCodec` and
- * `TomlCodec` — are free-standing named exports, one per module, and are
- * deliberately never collected into a namespace object. Collecting them would
- * make this module a dispatch table: referencing it at all would reach every
- * codec, and every codec would reach its parsing engine, so importing the JSON
- * codec alone would drag the JSONC, YAML and TOML engines into the bundle.
- * Name the one codec you use and a bundler drops the rest.
+ * The four built-in codecs are free-standing named exports, one per module,
+ * and are deliberately never collected into a namespace object. `JsonCodec`
+ * ships from the package root; `JsoncCodec`, `YamlCodec` and `TomlCodec` ship
+ * from the `./jsonc`, `./yaml` and `./toml` subpaths, whose engines are
+ * optional peers the root never reaches. Collecting them would make this module
+ * a dispatch table: referencing it at all would reach every codec, and every
+ * codec would reach its parsing engine, so importing the JSON codec alone would
+ * drag the JSONC, YAML and TOML engines into the bundle.
  *
  * @public
  */
@@ -1464,53 +1465,5 @@ export declare function EncryptedCodec<E>(inner: ConfigCodec<E>, keySource: Encr
  * @public
  */
 export declare const JsonCodec: ConfigCodec;
-/**
- * A `ConfigCodec` backed by `@effected/jsonc`: JSON with comments and
- * trailing commas.
- *
- * @remarks
- * `@effected/jsonc` does not expose a `stringify` — its schema layer's encode
- * direction is `JSON.stringify` (comments never survive a round-trip encode;
- * see `Jsonc.fromString`'s remarks), so `stringify` here calls `JSON.stringify`
- * directly and wraps a thrown defect the same way `JsonCodec` does.
- * Both directions preserve the underlying failure structurally in `cause` —
- * never stringified.
- *
- * @public
- */
-export declare const JsoncCodec: ConfigCodec;
-/**
- * A `ConfigCodec` backed by `@effected/toml`.
- *
- * @remarks
- * `@effected/toml`'s input hardening — a nesting-depth cap on arrays and
- * inline tables, enforced independently on both the parse and stringify
- * sides — fails through the typed error channel, so a hostile config file
- * surfaces as a `ConfigCodecError` rather than crashing the process. Both
- * directions preserve the underlying failure structurally in `cause` —
- * never stringified.
- *
- * Stringify is genuinely fallible beyond hostile input: TOML has no null,
- * so a document carrying `null` (or any other unrepresentable value, an
- * out-of-int64-range `bigint`, a circular reference) fails with a
- * `ConfigCodecError` whose `cause` is the structured `TomlStringifyError`.
- *
- * @public
- */
-export declare const TomlCodec: ConfigCodec;
-/**
- * A `ConfigCodec` backed by `@effected/yaml`.
- *
- * @remarks
- * `@effected/yaml`'s input hardening — an alias-expansion budget guarding
- * against "billion laughs" alias bombs, and a collection-nesting depth cap —
- * fails through the typed error channel, so a hostile config file surfaces
- * as a `ConfigCodecError` rather than crashing the process. Both directions
- * preserve the underlying failure structurally in `cause` — never
- * stringified.
- *
- * @public
- */
-export declare const YamlCodec: ConfigCodec;
 export type { ConfigCodec, ConfigEncodeError, ConfigEncodeOptions, ConfigEventsShape, ConfigFileMigration, ConfigFileOptions, ConfigFileShape, ConfigFileTestOptions, ConfigLoadError, ConfigMatch, ConfigMigrationOptions, ConfigProbe, ConfigReadError, ConfigReadOptions, ConfigSaveError, ConfigSource, ConfigUpdateError, ConfigWriteError, LayerConfigProviderOptions, NonEmptySources, UpwardWalkOptions };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -6,9 +6,6 @@ import { ConfigMigration, ConfigMigrationError, VersionAccess } from "./ConfigMi
 import { asConfigProvider, layerConfigProvider } from "./ConfigProvider.js";
 import { ConfigEncryptionError, EncryptedCodec, EncryptedCodecKey } from "./EncryptedCodec.js";
 import { JsonCodec } from "./JsonCodec.js";
-import { JsoncCodec } from "./JsoncCodec.js";
 import { MergeStrategy } from "./MergeStrategy.js";
-import { TomlCodec } from "./TomlCodec.js";
-import { YamlCodec } from "./YamlCodec.js";
 
-export { ConfigCodecError, ConfigDefaultPathMissingError, ConfigEncryptionError, ConfigEvent, ConfigEventPayload, ConfigEvents, ConfigFile, ConfigFileNotFoundError, ConfigFileReadError, ConfigFileWriteError, ConfigMigration, ConfigMigrationError, ConfigResolver, ConfigSourceRef, ConfigValidationError, EncryptedCodec, EncryptedCodecKey, JsonCodec, JsoncCodec, MergeStrategy, TomlCodec, VersionAccess, YamlCodec, asConfigProvider, layerConfigProvider };
+export { ConfigCodecError, ConfigDefaultPathMissingError, ConfigEncryptionError, ConfigEvent, ConfigEventPayload, ConfigEvents, ConfigFile, ConfigFileNotFoundError, ConfigFileReadError, ConfigFileWriteError, ConfigMigration, ConfigMigrationError, ConfigResolver, ConfigSourceRef, ConfigValidationError, EncryptedCodec, EncryptedCodecKey, JsonCodec, MergeStrategy, VersionAccess, asConfigProvider, layerConfigProvider };

package/jsonc.d.ts

@@ -0,0 +1,17 @@
+import { ConfigCodec } from "@effected/config-file";
+/**
+ * A `ConfigCodec` backed by `@effected/jsonc`: JSON with comments and
+ * trailing commas.
+ *
+ * @remarks
+ * `@effected/jsonc` does not expose a `stringify` — its schema layer's encode
+ * direction is `JSON.stringify` (comments never survive a round-trip encode;
+ * see `Jsonc.fromString`'s remarks), so `stringify` here calls `JSON.stringify`
+ * directly and wraps a thrown defect the same way `JsonCodec` does.
+ * Both directions preserve the underlying failure structurally in `cause` —
+ * never stringified.
+ *
+ * @public
+ */
+export declare const JsoncCodec: ConfigCodec;
+//# sourceMappingURL=jsonc.d.ts.map

package/jsonc.js

@@ -0,0 +1,3 @@
+import { JsoncCodec } from "./JsoncCodec.js";
+
+export { JsoncCodec };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/config-file",
-	"version": "0.19.1",
+	"version": "0.20.0",
 	"private": false,
 	"description": "Composable config file loading for Effect: JSON, JSONC, YAML and TOML codecs, resolution strategies, and merge behaviors.",
 	"keywords": [
@@ -40,16 +40,42 @@
 			"import": "./index.js",
 			"default": "./index.js"
 		},
+		"./jsonc": {
+			"types": "./jsonc.d.ts",
+			"import": "./jsonc.js",
+			"default": "./jsonc.js"
+		},
+		"./toml": {
+			"types": "./toml.d.ts",
+			"import": "./toml.js",
+			"default": "./toml.js"
+		},
+		"./yaml": {
+			"types": "./yaml.d.ts",
+			"import": "./yaml.js",
+			"default": "./yaml.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
 		"@effected/glob": "^0.14.0",
 		"@effected/jsonc": "^0.20.0",
 		"@effected/toml": "^0.16.0",
-		"@effected/walker": "^0.19.0",
-		"@effected/yaml": "^0.25.0",
+		"@effected/walker": "^0.20.0",
+		"@effected/yaml": "^0.25.1",
 		"effect": "^4.0.0"
 	},
+	"peerDependenciesMeta": {
+		"@effected/jsonc": {
+			"optional": true
+		},
+		"@effected/toml": {
+			"optional": true
+		},
+		"@effected/yaml": {
+			"optional": true
+		}
+	},
 	"engines": {
 		"node": ">=24.11.0"
 	}

package/toml.d.ts

@@ -0,0 +1,21 @@
+import { ConfigCodec } from "@effected/config-file";
+/**
+ * A `ConfigCodec` backed by `@effected/toml`.
+ *
+ * @remarks
+ * `@effected/toml`'s input hardening — a nesting-depth cap on arrays and
+ * inline tables, enforced independently on both the parse and stringify
+ * sides — fails through the typed error channel, so a hostile config file
+ * surfaces as a `ConfigCodecError` rather than crashing the process. Both
+ * directions preserve the underlying failure structurally in `cause` —
+ * never stringified.
+ *
+ * Stringify is genuinely fallible beyond hostile input: TOML has no null,
+ * so a document carrying `null` (or any other unrepresentable value, an
+ * out-of-int64-range `bigint`, a circular reference) fails with a
+ * `ConfigCodecError` whose `cause` is the structured `TomlStringifyError`.
+ *
+ * @public
+ */
+export declare const TomlCodec: ConfigCodec;
+//# sourceMappingURL=toml.d.ts.map

package/toml.js

@@ -0,0 +1,3 @@
+import { TomlCodec } from "./TomlCodec.js";
+
+export { TomlCodec };

package/yaml.d.ts

@@ -0,0 +1,16 @@
+import { ConfigCodec } from "@effected/config-file";
+/**
+ * A `ConfigCodec` backed by `@effected/yaml`.
+ *
+ * @remarks
+ * `@effected/yaml`'s input hardening — an alias-expansion budget guarding
+ * against "billion laughs" alias bombs, and a collection-nesting depth cap —
+ * fails through the typed error channel, so a hostile config file surfaces
+ * as a `ConfigCodecError` rather than crashing the process. Both directions
+ * preserve the underlying failure structurally in `cause` — never
+ * stringified.
+ *
+ * @public
+ */
+export declare const YamlCodec: ConfigCodec;
+//# sourceMappingURL=yaml.d.ts.map

package/yaml.js

@@ -0,0 +1,3 @@
+import { YamlCodec } from "./YamlCodec.js";
+
+export { YamlCodec };