@effected/config-file 0.3.1 → 0.4.1

package/ConfigFile.js

@@ -133,7 +133,7 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 		path: s.path,
 		resolver: s.resolver
 	}));
-	const decode = (parsed, at) => Schema.decodeUnknownEffect(options.schema)(parsed).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new ConfigValidationError({
+	const decode = (parsed, at) => Schema.decodeUnknownEffect(options.schema)(parsed, options.parseOptions).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new ConfigValidationError({
 		path: at,
 		issue: error.issue
 	}))));
@@ -354,7 +354,7 @@ const read = (path, options) => Effect.gen(function* () {
 		cause
 	})));
 	const parsed = yield* options.codec.parse(raw);
-	return yield* Schema.decodeUnknownEffect(options.schema)(parsed).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new ConfigValidationError({
+	return yield* Schema.decodeUnknownEffect(options.schema)(parsed, options.parseOptions).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new ConfigValidationError({
 		path: Option.some(path),
 		issue: error.issue
 	}))));

package/README.md

@@ -117,6 +117,32 @@ Effect.runPromise(program.pipe(Effect.provide(NodeFileSystem.layer))).then(conso
 
 It is deliberately read-only and discovery-free — no resolver chain, no `save`/`update`. Reach for `ConfigFile.layer` the moment either is wanted.
 
+## Rejecting keys the schema does not know
+
+Effect's decoder ignores unknown keys by default, which for a config loader means a typo'd section is dropped in silence. The user gets no error, the setting they wrote has no effect, and nothing in the run says why. `parseOptions` threads decode options into every decode the loader performs, on `ConfigFile.layer` and `ConfigFile.read` alike:
+
+```ts
+import { ConfigFile, ConfigResolver, JsonCodec, MergeStrategy } from "@effected/config-file";
+import { Schema } from "effect";
+
+class Settings extends Schema.Class<Settings>("Settings")({ port: Schema.Number }) {}
+class SettingsConfig extends ConfigFile.Service<SettingsConfig, Settings>()("app/Settings") {}
+
+export const SettingsLive = ConfigFile.layer(SettingsConfig, {
+  schema: Settings,
+  codec: JsonCodec,
+  resolvers: [ConfigResolver.upwardWalk({ filename: ".apprc" })],
+  strategy: MergeStrategy.firstMatch<Settings>(),
+  parseOptions: { onExcessProperty: "error", errors: "all" },
+});
+// A file carrying `{ "port": 3000, "prot": 3001 }` now fails with a
+// ConfigValidationError whose issue tree names the offending path.
+```
+
+The `validate` option cannot stand in for this: it runs on the decoded value, by which point the excess keys are already gone. Pair `onExcessProperty: "error"` with `errors: "all"` — the decoder reports only the first problem otherwise, so a file with three typos costs the user three fix-and-rerun cycles. The extra work happens only on a document that is already failing.
+
+A schema that deliberately admits a pass-through section keeps working under `"error"` — but know why, because the shape suggests the opposite: a `Schema.StructWithRest` rest **switches excess checking off for that struct entirely**, not merely for the keys the rest covers. Structs without a rest stay strict independently, so strictness is decided per level rather than per key. Omitting `parseOptions` changes nothing, which makes turning this on a per-loader decision rather than a migration.
+
 ## Errors
 
 Every failure is a tagged error you route on with `Effect.catchTag`. The tags exist so that recovery can differ:
@@ -185,6 +211,7 @@ export const secret = EncryptedCodec(migrating, EncryptedCodecKey.fromPassphrase
 ## Features
 
 - `ConfigFile.Service` / `ConfigFile.layer` / `ConfigFile.testLayer` — a per-schema service class and its layers. `testLayer` seeds files into a temp directory and wires the *real* implementation over them, so tests exercise the actual pipeline rather than a stub that can drift from it.
+- `parseOptions` — decode options threaded into every decode, on the layer and on `read`. `onExcessProperty: "error"` is the only way to report a typo'd section or a field the schema deliberately removed.
 - `ConfigFile.read` — the one-shot escape from the service: read, decode and validate one explicit path, schema and codec named per call, with no resolver chain and no write path.
 - `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.

package/index.d.ts

@@ -1,4 +1,4 @@
-import { ConfigProvider, Context, Effect, FileSystem, Layer, Option, Path, PubSub, Schema } from "effect";
+import { ConfigProvider, Context, Effect, FileSystem, Layer, Option, Path, PubSub, Schema, SchemaAST } from "effect";
 //#region src/ConfigCodec.d.ts
 declare const ConfigCodecError_base: Schema.Class<ConfigCodecError, Schema.TaggedStruct<"ConfigCodecError", {
   /** The codec that failed, e.g. `"json"`. */
@@ -564,6 +564,31 @@ interface ConfigFileOptions<A, I, RR> {
   readonly strategy: MergeStrategy<A>;
   /** An optional caller-supplied check run after schema decoding. */
   readonly validate?: (value: A) => Effect.Effect<A, ConfigValidationError>;
+  /**
+   * Parse options threaded into every schema decode this performs.
+   *
+   * @remarks
+   * The field that matters here is `onExcessProperty`. It defaults to
+   * `"ignore"` in core, so a document's unknown keys are dropped silently and
+   * a loader cannot report a typo'd section — or enforce a field this schema
+   * deliberately removed. `{ onExcessProperty: "error" }` turns both into a
+   * {@link ConfigValidationError} whose issue names the offending path.
+   *
+   * It cannot be expressed with {@link ConfigFileOptions.validate}: that runs
+   * on the *decoded* value, by which point the excess keys are already gone.
+   *
+   * Keys covered by a `Schema.StructWithRest` rest are not excess, so a schema
+   * that deliberately admits a pass-through section keeps working under
+   * `"error"`.
+   *
+   * Absent, nothing changes: core's defaults apply.
+   *
+   * Pair it with `errors: "all"`. Core defaults to `"first"`, which for a
+   * *loader* means a file with three typos surfaces one per run — fix,
+   * re-run, discover the next. The extra work only happens on a document
+   * that is already failing.
+   */
+  readonly parseOptions?: SchemaAST.ParseOptions;
   /**
    * Where {@link ConfigFileShape.save} writes when given no explicit path.
    *
@@ -640,6 +665,14 @@ interface ConfigReadOptions<A, I> {
    * their engines stay out of the bundle.
    */
   readonly codec: ConfigCodec;
+  /**
+   * Parse options for the decode, chiefly `onExcessProperty`.
+   *
+   * @remarks
+   * See {@link ConfigFileOptions.parseOptions}; it means the same thing here.
+   * Absent, core's defaults apply and unknown keys are dropped silently.
+   */
+  readonly parseOptions?: SchemaAST.ParseOptions;
 }
 /**
  * The config file service: a per-schema service factory, its layers, and the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/config-file",
-	"version": "0.3.1",
+	"version": "0.4.1",
 	"private": false,
 	"description": "Composable config file loading for Effect: JSON, JSONC, YAML and TOML codecs, resolution strategies, and merge behaviors.",
 	"keywords": [