@effected/config-file 0.8.0 → 0.9.0

package/ConfigFile.js

@@ -120,6 +120,13 @@ const withCodecPath = (error, target) => error instanceof ConfigCodecError && er
 	cause: error.cause,
 	path: target
 }) : error;
+/**
+* Put `header` in front of `document`, separated by exactly one newline.
+*
+* A header that already ends in a newline is not given another — a caller who
+* built the line with a trailing `"\n"` and one who did not get the same file.
+*/
+const prependHeader = (document, header) => header === void 0 ? document : header.endsWith("\n") ? `${header}${document}` : `${header}\n${document}`;
 const makeImpl = (options, fs, path, resolverEnv) => {
 	/**
 	* Publish one event, or nothing at all.
@@ -252,24 +259,46 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 		return yield* runValidate(decoded);
 	});
 	/**
-	* Shared by `write` and `save`. Not an `Effect.fn`: it is internal, and the
-	* public boundaries that call it already open a span.
+	* Schema-encode, stringify, and prepend the header. Shared by `encode`,
+	* `write` and `save`. Not an `Effect.fn`: it is internal, and the public
+	* boundaries that call it already open a span.
+	*
+	* `target` is the file this text is destined for, when there is one. It is
+	* only ever used to NAME the file in an error — `encode` passes `none` and
+	* its errors honestly carry no path.
 	*/
-	const encodeAndWrite = (value, target) => Effect.gen(function* () {
+	const encodeTo = (value, target, encodeOptions) => Effect.gen(function* () {
 		const encoded = yield* Schema.encodeEffect(options.schema)(value).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new ConfigValidationError({
-			path: Option.some(target),
+			path: target,
 			issue: error.issue
 		}))));
-		const serialized = yield* options.codec.stringify(encoded).pipe(Effect.mapError((error) => withCodecPath(error, target)), Effect.tapError((error) => emit({
+		const serialized = yield* options.codec.stringify(encoded).pipe(Effect.mapError((error) => Option.match(target, {
+			onNone: () => error,
+			onSome: (file) => withCodecPath(error, file)
+		})));
+		return prependHeader(serialized, encodeOptions?.header);
+	});
+	/**
+	* `encodeTo` a known file, then write it. Shared by `write` and `save`.
+	*
+	* `StringifyFailed` is emitted HERE, not in `encodeTo`: it is a write-path
+	* event, and `encode` promises to publish nothing. A subscriber counting
+	* failed writes must not see a dry run's codec failure.
+	*/
+	const encodeAndWrite = (value, target, encodeOptions) => Effect.gen(function* () {
+		const serialized = yield* encodeTo(value, Option.some(target), encodeOptions).pipe(Effect.tapError((error) => error._tag === "ConfigCodecError" ? emit({
 			_tag: "StringifyFailed",
 			codec: options.codec.name,
 			error
-		})));
+		}) : Effect.void));
 		yield* fs.writeFileString(target, serialized).pipe(Effect.mapError((cause) => new ConfigFileWriteError({
 			path: target,
 			cause
 		})));
 	});
+	const encode = Effect.fn("ConfigFile.encode")(function* (value, encodeOptions) {
+		return yield* encodeTo(value, Option.none(), encodeOptions);
+	});
 	/**
 	* Resolve `defaultPath`, `mkdir -p` its parent and write. Shared by `save`
 	* and `update`, and — crucially — emits nothing.
@@ -290,8 +319,8 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 		yield* encodeAndWrite(value, target);
 		return target;
 	});
-	const write = Effect.fn("ConfigFile.write")(function* (value, target) {
-		yield* encodeAndWrite(value, target);
+	const write = Effect.fn("ConfigFile.write")(function* (value, target, encodeOptions) {
+		yield* encodeAndWrite(value, target, encodeOptions);
 		yield* emit({
 			_tag: "Written",
 			path: target
@@ -335,6 +364,7 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 		discover: discover(),
 		loadOrDefault,
 		validate,
+		encode,
 		write,
 		save,
 		update

package/README.md

@@ -158,7 +158,7 @@ Every failure is a tagged error you route on with `Effect.catchTag`. The tags ex
 | `ConfigMigrationError` | A versioned migration failed. Carries `version`, `name`, `phase` and the structural `cause`. | Report which step failed; the config on disk is left untouched. |
 | `ConfigEncryptionError` | An encrypt, decrypt, key-derivation or base64 step failed. Carries `phase` and the structural `cause`. | A wrong passphrase and a corrupt envelope both land here; inspect `phase`. |
 
-`ConfigLoadError`, `ConfigReadError`, `ConfigWriteError`, `ConfigSaveError` and `ConfigUpdateError` are exported unions naming exactly the failures each method can produce. Catching one tag narrows the union, leaving the rest to propagate:
+`ConfigLoadError`, `ConfigReadError`, `ConfigEncodeError`, `ConfigWriteError`, `ConfigSaveError` and `ConfigUpdateError` are exported unions naming exactly the failures each method can produce — `ConfigEncodeError` is `ConfigWriteError` minus `ConfigFileWriteError`, because `encode` never touches the disk. Catching one tag narrows the union, leaving the rest to propagate:
 
 ```ts
 import type { ConfigFileShape } from "@effected/config-file";
@@ -213,6 +213,7 @@ export const secret = EncryptedCodec(migrating, EncryptedCodecKey.fromPassphrase
 - `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.
+- `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.

package/index.d.ts

@@ -600,6 +600,38 @@ type ConfigReadError = ConfigFileReadError | ConfigCodecError | ConfigValidation
  * @public
  */
 type ConfigWriteError = ConfigFileWriteError | ConfigCodecError | ConfigValidationError;
+/**
+ * The failure modes of {@link ConfigFileShape.encode}: everything on the write
+ * path except the write itself.
+ *
+ * @remarks
+ * Deliberately excludes {@link ConfigFileWriteError} — nothing touches the
+ * filesystem — so a `--dry-run` caller's error channel is honest about that.
+ *
+ * @public
+ */
+type ConfigEncodeError = ConfigCodecError | ConfigValidationError;
+/**
+ * Options shared by {@link ConfigFileShape.encode} and {@link ConfigFileShape.write}.
+ *
+ * @public
+ */
+interface ConfigEncodeOptions {
+  /**
+   * Text emitted **verbatim** in front of the serialized document, separated
+   * from it by exactly one newline. If `header` already ends in `"\n"`, no
+   * further newline is added.
+   *
+   * @remarks
+   * The caller owns the header's validity in the target format: `#` comment
+   * lines for TOML and YAML, `//` for JSONC. JSON has no comment syntax, so a
+   * header on a JSON codec yields an unparseable file by construction — the
+   * service does not check. The motivating case is a schema directive such as
+   * `#:schema https://example.com/config.schema.json` at the top of a TOML
+   * file, which editors read for completion and validation.
+   */
+  readonly header?: string;
+}
 /**
  * The failure modes of {@link ConfigFileShape.save}.
  *
@@ -646,15 +678,27 @@ interface ConfigFileShape<A> {
   readonly loadOrDefault: (defaultValue: A) => Effect.Effect<A, ConfigReadError>;
   /** Decode and validate an in-memory value. */
   readonly validate: (value: unknown) => Effect.Effect<A, ConfigValidationError>;
+  /**
+   * Encode `value` to its serialized text without writing anything.
+   *
+   * @remarks
+   * Produces byte-for-byte what `write(value, path, options)` puts on disk —
+   * the primitive for `--dry-run` and "show me the file" callers. Emits no
+   * event, because nothing was written. A codec failure here carries no
+   * `path`, and a validation failure's `path` is `Option.none()`: there is no
+   * file to name.
+   */
+  readonly encode: (value: A, options?: ConfigEncodeOptions) => Effect.Effect<string, ConfigEncodeError>;
   /**
    * Encode `value` and write it to an explicit `path`.
    *
    * @remarks
    * Does **not** create the parent directory — that is
    * {@link ConfigFileShape.save}'s job, and the distinction is load-bearing:
-   * `write` targets a path the caller already vouched for.
+   * `write` targets a path the caller already vouched for. `options` are the
+   * same as {@link ConfigFileShape.encode}'s, so the two stay in lockstep.
    */
-  readonly write: (value: A, path: string) => Effect.Effect<void, ConfigWriteError>;
+  readonly write: (value: A, path: string, options?: ConfigEncodeOptions) => Effect.Effect<void, ConfigWriteError>;
   /**
    * Resolve `defaultPath`, `mkdir -p` its parent, encode `value` into it, and
    * return the path written.
@@ -1231,5 +1275,5 @@ export declare const TomlCodec: ConfigCodec;
  */
 export declare const YamlCodec: ConfigCodec;
 //#endregion
-export type { ConfigCodec, ConfigEventsShape, ConfigFileMigration, ConfigFileOptions, ConfigFileShape, ConfigFileTestOptions, ConfigLoadError, ConfigMatch, ConfigMigrationOptions, ConfigReadError, ConfigReadOptions, ConfigSaveError, ConfigSource, ConfigUpdateError, ConfigWriteError, LayerConfigProviderOptions, NonEmptySources, UpwardWalkOptions };
+export type { ConfigCodec, ConfigEncodeError, ConfigEncodeOptions, ConfigEventsShape, ConfigFileMigration, ConfigFileOptions, ConfigFileShape, ConfigFileTestOptions, ConfigLoadError, ConfigMatch, ConfigMigrationOptions, ConfigReadError, ConfigReadOptions, ConfigSaveError, ConfigSource, ConfigUpdateError, ConfigWriteError, LayerConfigProviderOptions, NonEmptySources, UpwardWalkOptions };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/config-file",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"private": false,
 	"description": "Composable config file loading for Effect: JSON, JSONC, YAML and TOML codecs, resolution strategies, and merge behaviors.",
 	"keywords": [
@@ -45,8 +45,8 @@
 	"peerDependencies": {
 		"@effected/jsonc": "^0.11.0",
 		"@effected/toml": "^0.7.0",
-		"@effected/walker": "^0.8.0",
-		"@effected/yaml": "^0.15.0",
+		"@effected/walker": "^0.9.0",
+		"@effected/yaml": "^0.15.1",
 		"effect": "4.0.0-rc.115"
 	},
 	"engines": {