@effected/config-file 0.1.9 → 0.2.0

package/ConfigFile.js

@@ -100,16 +100,6 @@ var ConfigValidationError = class extends Schema.TaggedErrorClass()("ConfigValid
 		})}`;
 	}
 };
-/**
-* Create a uniquely-keyed service class for one config schema.
-*
-* @example
-* ```ts
-* class AppConfig extends ConfigFile.Service<AppConfig, AppShape>()("app/Config") {}
-* ```
-*
-* @public
-*/
 const Service = () => (id) => Context.Service()(id);
 const makeImpl = (options, fs, path, resolverEnv) => {
 	/**
@@ -329,60 +319,12 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 		update
 	};
 };
-/**
-* Build the live layer for a config service class.
-*
-* @remarks
-* Resolver requirements flow into the layer's `R` type. v3 cast them away with
-* `as Effect.Effect<Option<string>>`, making `Layer<Service, never, FileSystem>`
-* a claim rather than a proof.
-*
-* `ConfigFile.layer` is a layer-RETURNING function, not a layer: calling it
-* twice builds two independent service instances. Bind its result to a const
-* and provide that const, per the memoization discipline — do not call
-* `ConfigFile.layer(...)` inline at each provide site.
-*
-* @public
-*/
 const layer = (tag, options) => Layer.effect(tag, Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const resolverEnv = yield* Effect.context();
 	return makeImpl(options, fs, path, resolverEnv);
 }));
-/**
-* A scoped layer that seeds `files` into a temp directory, wires the **real**
-* live implementation over them, and removes the directory when the scope
-* closes.
-*
-* @remarks
-* Deliberately not a mock. It delegates to the very same `makeImpl` that
-* {@link ConfigFile.layer} uses, so tests exercise the actual codec, resolver
-* and merge pipeline rather than a parallel implementation that can drift from
-* it. A stubbed test layer would make every downstream test a claim about the
-* stub instead of about the code under test.
-*
-* Platform-agnostic: the consumer supplies the `FileSystem` layer, and the temp
-* directory is created through `FileSystem.makeTempDirectory` rather than
-* `node:fs`.
-*
-* `Layer.scoped` does not exist in v4. `Layer.effect` types its layer as
-* `Layer<I, E, Exclude<R, Scope>>`, so an `Effect.addFinalizer` inside it binds
-* to the layer's own scope and runs on release without surfacing `Scope` in the
-* layer's requirements.
-*
-* @example
-* ```ts
-* const TestConfig = ConfigFile.testLayer(AppConfig, {
-* 	schema: AppShape,
-* 	codec: JsonCodec,
-* 	strategy: MergeStrategy.firstMatch<AppShape>(),
-* 	files: { ".apprc": `{"port":4242}` },
-* }).pipe(Layer.provide(NodeServices.layer));
-* ```
-*
-* @public
-*/
 const testLayer = (tag, options) => Layer.effect(tag, Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
@@ -406,15 +348,111 @@ const testLayer = (tag, options) => Layer.effect(tag, Effect.gen(function* () {
 		...options.validate !== void 0 && { validate: options.validate }
 	}, fs, path, resolverEnv);
 }));
+const read = (path, options) => Effect.gen(function* () {
+	const raw = yield* (yield* FileSystem.FileSystem).readFileString(path).pipe(Effect.mapError((cause) => new ConfigFileReadError({
+		path,
+		cause
+	})));
+	const parsed = yield* options.codec.parse(raw);
+	return yield* Schema.decodeUnknownEffect(options.schema)(parsed).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new ConfigValidationError({
+		path: Option.some(path),
+		issue: error.issue
+	}))));
+}).pipe(Effect.withSpan("ConfigFile.read", { attributes: { path } }));
 /**
-* The config file service: a per-schema service factory and its layers.
+* The config file service: a per-schema service factory, its layers, and the
+* one-shot {@link ConfigFile.read}.
 *
 * @public
 */
-const ConfigFile = {
-	Service,
-	layer,
-	testLayer
+var ConfigFile = class {
+	constructor() {}
+	/**
+	* Create a uniquely-keyed service class for one config schema.
+	*
+	* @example
+	* ```ts
+	* class AppConfig extends ConfigFile.Service<AppConfig, AppShape>()("app/Config") {}
+	* ```
+	*/
+	static Service = Service;
+	/**
+	* Build the live layer for a config service class.
+	*
+	* @remarks
+	* Resolver requirements flow into the layer's `R` type. v3 cast them away with
+	* `as Effect.Effect<Option<string>>`, making `Layer<Service, never, FileSystem>`
+	* a claim rather than a proof.
+	*
+	* `ConfigFile.layer` is a layer-RETURNING function, not a layer: calling it
+	* twice builds two independent service instances. Bind its result to a const
+	* and provide that const, per the memoization discipline — do not call
+	* `ConfigFile.layer(...)` inline at each provide site.
+	*/
+	static layer = layer;
+	/**
+	* A scoped layer that seeds `files` into a temp directory, wires the **real**
+	* live implementation over them, and removes the directory when the scope
+	* closes.
+	*
+	* @remarks
+	* Deliberately not a mock. It delegates to the very same `makeImpl` that
+	* {@link ConfigFile.layer} uses, so tests exercise the actual codec, resolver
+	* and merge pipeline rather than a parallel implementation that can drift from
+	* it. A stubbed test layer would make every downstream test a claim about the
+	* stub instead of about the code under test.
+	*
+	* Platform-agnostic: the consumer supplies the `FileSystem` layer, and the temp
+	* directory is created through `FileSystem.makeTempDirectory` rather than
+	* `node:fs`.
+	*
+	* `Layer.scoped` does not exist in v4. `Layer.effect` types its layer as
+	* `Layer<I, E, Exclude<R, Scope>>`, so an `Effect.addFinalizer` inside it binds
+	* to the layer's own scope and runs on release without surfacing `Scope` in the
+	* layer's requirements.
+	*
+	* @example
+	* ```ts
+	* const TestConfig = ConfigFile.testLayer(AppConfig, {
+	* 	schema: AppShape,
+	* 	codec: JsonCodec,
+	* 	strategy: MergeStrategy.firstMatch<AppShape>(),
+	* 	files: { ".apprc": `{"port":4242}` },
+	* }).pipe(Layer.provide(NodeServices.layer));
+	* ```
+	*/
+	static testLayer = testLayer;
+	/**
+	* Read, decode and validate one explicit path — no service, no layer, no tag.
+	*
+	* @remarks
+	* The one-shot form. {@link ConfigFile.layer} binds schema and codec at layer
+	* construction, which is the right model for a config file an application
+	* *has* — several candidate locations, `save`/`update`, migrations, events —
+	* and heavy for a call site that decodes one known path once, where it costs a
+	* service subclass, a layer bound to a const and a provide at the boundary.
+	* Unlike the service, `read` takes its schema per call, so one call site can
+	* read several unrelated files without a service class each.
+	*
+	* It is deliberately read-only and discovery-free: there is no resolver chain
+	* and no write path. Reach for {@link ConfigFile.layer} the moment either is
+	* wanted, rather than growing this.
+	*
+	* The error channel is `ConfigReadError` — the same narrowed union
+	* {@link ConfigFileShape.loadFrom} carries, with causes and schema issues held
+	* structurally rather than flattened into a message.
+	*
+	* @example
+	* ```ts
+	* import { ConfigFile, JsonCodec } from "@effected/config-file";
+	*
+	* const config = yield* ConfigFile.read(inputs.configFile, {
+	*   schema: MyConfig,
+	*   codec: JsonCodec,
+	* });
+	* ```
+	*/
+	static read = read;
 };
 
 //#endregion

package/ConfigMigration.js

@@ -61,17 +61,6 @@ const runPhase = (phase, version, name, run) => Effect.suspend(run).pipe(Effect.
 	phase,
 	cause
 })));
-/**
-* Wrap a codec so that parsed content is brought up to the latest version.
-*
-* @remarks
-* The returned codec's error channel **widens** to include
-* {@link ConfigMigrationError} rather than flattening migration failures into
-* the inner codec's error — the reason the {@link (ConfigCodec:interface)} seam is generic
-* in its error type.
-*
-* @public
-*/
 const make = (options) => {
 	const access = options.versionAccess ?? VersionAccess.default;
 	const sorted = [...options.migrations].sort((a, b) => a.version - b.version);
@@ -91,7 +80,19 @@ const make = (options) => {
 	};
 };
 /** Versioned migration support for config codecs. @public */
-const ConfigMigration = { make };
+var ConfigMigration = class {
+	constructor() {}
+	/**
+	* Wrap a codec so that parsed content is brought up to the latest version.
+	*
+	* @remarks
+	* The returned codec's error channel **widens** to include
+	* {@link ConfigMigrationError} rather than flattening migration failures into
+	* the inner codec's error — the reason the {@link (ConfigCodec:interface)} seam is generic
+	* in its error type.
+	*/
+	static make = make;
+};
 
 //#endregion
 export { ConfigMigration, ConfigMigrationError, VersionAccess };

package/ConfigResolver.js

@@ -82,13 +82,34 @@ const systemEtc = (options) => ({
 *
 * @public
 */
-const ConfigResolver = {
-	explicitPath,
-	staticDir,
-	upwardWalk,
-	workspaceRoot,
-	gitRoot,
-	systemEtc
+var ConfigResolver = class {
+	constructor() {}
+	/** Resolves to `target` when it exists on disk, or `Option.none()` when it does not — no walking, no filename convention. */
+	static explicitPath = explicitPath;
+	/** Resolves `path.join(dir, filename)` when it exists on disk, or `Option.none()` when it does not. */
+	static staticDir = staticDir;
+	/**
+	* Ascends from `cwd` (or the process cwd) toward `stopAt`, resolving the
+	* first `subpaths/filename` combination found at each level.
+	*/
+	static upwardWalk = upwardWalk;
+	/**
+	* Ascends from `cwd` to the nearest workspace root — a directory with a
+	* `pnpm-workspace.yaml`, or a `package.json` carrying a `workspaces` field —
+	* then resolves the first `subpaths/filename` combination found under it.
+	*/
+	static workspaceRoot = workspaceRoot;
+	/**
+	* Ascends from `cwd` to the nearest git root — a directory containing a
+	* `.git` entry, directory or file (the latter for a worktree) — then
+	* resolves the first `subpaths/filename` combination found under it.
+	*/
+	static gitRoot = gitRoot;
+	/**
+	* Resolves `<dir>/<app>/<filename>` under the system config root (`/etc` by
+	* default). Always `Option.none()` on Windows, where `/etc` has no meaning.
+	*/
+	static systemEtc = systemEtc;
 };
 
 //#endregion

package/index.d.ts

@@ -248,29 +248,50 @@ interface ConfigResolver<R = never> {
  *
  * @public
  */
-declare const ConfigResolver: {
-  readonly explicitPath: (target: string) => ConfigResolver<FileSystem.FileSystem | Path.Path>;
-  readonly staticDir: (options: {
+declare class ConfigResolver {
+  private constructor();
+  /** Resolves to `target` when it exists on disk, or `Option.none()` when it does not — no walking, no filename convention. */
+  static readonly explicitPath: (target: string) => ConfigResolver<FileSystem.FileSystem | Path.Path>;
+  /** Resolves `path.join(dir, filename)` when it exists on disk, or `Option.none()` when it does not. */
+  static readonly staticDir: (options: {
     readonly dir: string;
     readonly filename: string;
   }) => ConfigResolver<FileSystem.FileSystem | Path.Path>;
-  readonly upwardWalk: (options: {
+  /**
+   * Ascends from `cwd` (or the process cwd) toward `stopAt`, resolving the
+   * first `subpaths/filename` combination found at each level.
+   */
+  static readonly upwardWalk: (options: {
     readonly filename: string;
     readonly cwd?: string;
     readonly stopAt?: string;
     readonly subpaths?: ReadonlyArray<string>;
   }) => ConfigResolver<FileSystem.FileSystem | Path.Path>;
-  readonly workspaceRoot: (options: {
+  /**
+   * Ascends from `cwd` to the nearest workspace root — a directory with a
+   * `pnpm-workspace.yaml`, or a `package.json` carrying a `workspaces` field —
+   * then resolves the first `subpaths/filename` combination found under it.
+   */
+  static readonly workspaceRoot: (options: {
     readonly filename: string;
     readonly cwd?: string;
     readonly subpaths?: ReadonlyArray<string>;
   }) => ConfigResolver<FileSystem.FileSystem | Path.Path>;
-  readonly gitRoot: (options: {
+  /**
+   * Ascends from `cwd` to the nearest git root — a directory containing a
+   * `.git` entry, directory or file (the latter for a worktree) — then
+   * resolves the first `subpaths/filename` combination found under it.
+   */
+  static readonly gitRoot: (options: {
     readonly filename: string;
     readonly cwd?: string;
     readonly subpaths?: ReadonlyArray<string>;
   }) => ConfigResolver<FileSystem.FileSystem | Path.Path>;
-  readonly systemEtc: (options: {
+  /**
+   * Resolves `<dir>/<app>/<filename>` under the system config root (`/etc` by
+   * default). Always `Option.none()` on Windows, where `/etc` has no meaning.
+   */
+  static readonly systemEtc: (options: {
     readonly app: string;
     readonly filename: string;
     /**
@@ -280,7 +301,7 @@ declare const ConfigResolver: {
      */
     readonly dir?: string;
   }) => ConfigResolver<FileSystem.FileSystem | Path.Path>;
-};
+}
 //#endregion
 //#region src/MergeStrategy.d.ts
 /**
@@ -571,7 +592,7 @@ interface ConfigFileOptions<A, I, RR> {
  *
  * @remarks
  * Deliberately has no `resolvers`: `testLayer` synthesizes one
- * {@link (ConfigResolver:variable).staticDir} per seeded file, in `files`
+ * {@link (ConfigResolver:class).staticDir} per seeded file, in `files`
  * insertion order, so the first key wins under
  * {@link (MergeStrategy:variable).firstMatch}.
  *
@@ -601,15 +622,120 @@ interface ConfigFileTestOptions<A, I> {
   readonly validate?: (value: A) => Effect.Effect<A, ConfigValidationError>;
 }
 /**
- * The config file service: a per-schema service factory and its layers.
+ * Options for {@link ConfigFile.read}.
  *
  * @public
  */
-declare const ConfigFile: {
-  readonly Service: <Self, A>() => <const Id extends string>(id: Id) => Context.ServiceClass<Self, Id, ConfigFileShape<A>>;
-  readonly layer: <Self, A, I, RR = never>(tag: Context.Key<Self, ConfigFileShape<A>>, options: ConfigFileOptions<A, I, RR>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path | RR>;
-  readonly testLayer: <Self, A, I>(tag: Context.Key<Self, ConfigFileShape<A>>, options: ConfigFileTestOptions<A, I>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path>;
-};
+interface ConfigReadOptions<A, I> {
+  /** The schema the document is decoded through. */
+  readonly schema: Schema.Codec<A, I>;
+  /**
+   * How file content becomes an unknown document.
+   *
+   * @remarks
+   * An explicit argument, never inferred from the file extension or defaulted
+   * to JSON. Naming the codec at the call site is what keeps the
+   * free-standing-codec tree-shaking guarantee: a consumer that only ever
+   * passes `JsonCodec` never references the JSONC, YAML or TOML modules, so
+   * their engines stay out of the bundle.
+   */
+  readonly codec: ConfigCodec;
+}
+/**
+ * The config file service: a per-schema service factory, its layers, and the
+ * one-shot {@link ConfigFile.read}.
+ *
+ * @public
+ */
+declare class ConfigFile {
+  private constructor();
+  /**
+   * Create a uniquely-keyed service class for one config schema.
+   *
+   * @example
+   * ```ts
+   * class AppConfig extends ConfigFile.Service<AppConfig, AppShape>()("app/Config") {}
+   * ```
+   */
+  static readonly Service: <Self, A>() => <const Id extends string>(id: Id) => Context.ServiceClass<Self, Id, ConfigFileShape<A>>;
+  /**
+   * Build the live layer for a config service class.
+   *
+   * @remarks
+   * Resolver requirements flow into the layer's `R` type. v3 cast them away with
+   * `as Effect.Effect<Option<string>>`, making `Layer<Service, never, FileSystem>`
+   * a claim rather than a proof.
+   *
+   * `ConfigFile.layer` is a layer-RETURNING function, not a layer: calling it
+   * twice builds two independent service instances. Bind its result to a const
+   * and provide that const, per the memoization discipline — do not call
+   * `ConfigFile.layer(...)` inline at each provide site.
+   */
+  static readonly layer: <Self, A, I, RR = never>(tag: Context.Key<Self, ConfigFileShape<A>>, options: ConfigFileOptions<A, I, RR>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path | RR>;
+  /**
+   * A scoped layer that seeds `files` into a temp directory, wires the **real**
+   * live implementation over them, and removes the directory when the scope
+   * closes.
+   *
+   * @remarks
+   * Deliberately not a mock. It delegates to the very same `makeImpl` that
+   * {@link ConfigFile.layer} uses, so tests exercise the actual codec, resolver
+   * and merge pipeline rather than a parallel implementation that can drift from
+   * it. A stubbed test layer would make every downstream test a claim about the
+   * stub instead of about the code under test.
+   *
+   * Platform-agnostic: the consumer supplies the `FileSystem` layer, and the temp
+   * directory is created through `FileSystem.makeTempDirectory` rather than
+   * `node:fs`.
+   *
+   * `Layer.scoped` does not exist in v4. `Layer.effect` types its layer as
+   * `Layer<I, E, Exclude<R, Scope>>`, so an `Effect.addFinalizer` inside it binds
+   * to the layer's own scope and runs on release without surfacing `Scope` in the
+   * layer's requirements.
+   *
+   * @example
+   * ```ts
+   * const TestConfig = ConfigFile.testLayer(AppConfig, {
+   * 	schema: AppShape,
+   * 	codec: JsonCodec,
+   * 	strategy: MergeStrategy.firstMatch<AppShape>(),
+   * 	files: { ".apprc": `{"port":4242}` },
+   * }).pipe(Layer.provide(NodeServices.layer));
+   * ```
+   */
+  static readonly testLayer: <Self, A, I>(tag: Context.Key<Self, ConfigFileShape<A>>, options: ConfigFileTestOptions<A, I>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path>;
+  /**
+   * Read, decode and validate one explicit path — no service, no layer, no tag.
+   *
+   * @remarks
+   * The one-shot form. {@link ConfigFile.layer} binds schema and codec at layer
+   * construction, which is the right model for a config file an application
+   * *has* — several candidate locations, `save`/`update`, migrations, events —
+   * and heavy for a call site that decodes one known path once, where it costs a
+   * service subclass, a layer bound to a const and a provide at the boundary.
+   * Unlike the service, `read` takes its schema per call, so one call site can
+   * read several unrelated files without a service class each.
+   *
+   * It is deliberately read-only and discovery-free: there is no resolver chain
+   * and no write path. Reach for {@link ConfigFile.layer} the moment either is
+   * wanted, rather than growing this.
+   *
+   * The error channel is `ConfigReadError` — the same narrowed union
+   * {@link ConfigFileShape.loadFrom} carries, with causes and schema issues held
+   * structurally rather than flattened into a message.
+   *
+   * @example
+   * ```ts
+   * import { ConfigFile, JsonCodec } from "@effected/config-file";
+   *
+   * const config = yield* ConfigFile.read(inputs.configFile, {
+   *   schema: MyConfig,
+   *   codec: JsonCodec,
+   * });
+   * ```
+   */
+  static readonly read: <A, I>(path: string, options: ConfigReadOptions<A, I>) => Effect.Effect<A, ConfigReadError, FileSystem.FileSystem>;
+}
 //#endregion
 //#region src/ConfigMigration.d.ts
 declare const ConfigMigrationError_base: Schema.Class<ConfigMigrationError, Schema.TaggedStruct<"ConfigMigrationError", {
@@ -670,9 +796,19 @@ interface ConfigMigrationOptions {
   readonly versionAccess?: VersionAccess;
 }
 /** Versioned migration support for config codecs. @public */
-declare const ConfigMigration: {
-  readonly make: (options: ConfigMigrationOptions) => ConfigCodec<ConfigCodecError | ConfigMigrationError>;
-};
+declare class ConfigMigration {
+  private constructor();
+  /**
+   * Wrap a codec so that parsed content is brought up to the latest version.
+   *
+   * @remarks
+   * The returned codec's error channel **widens** to include
+   * {@link ConfigMigrationError} rather than flattening migration failures into
+   * the inner codec's error — the reason the {@link (ConfigCodec:interface)} seam is generic
+   * in its error type.
+   */
+  static readonly make: (options: ConfigMigrationOptions) => ConfigCodec<ConfigCodecError | ConfigMigrationError>;
+}
 //#endregion
 //#region src/ConfigProvider.d.ts
 /**
@@ -928,5 +1064,5 @@ declare const TomlCodec: ConfigCodec;
  */
 declare const YamlCodec: ConfigCodec;
 //#endregion
-export { type ConfigCodec, ConfigCodecError, ConfigDefaultPathMissingError, ConfigEncryptionError, ConfigEvent, ConfigEventPayload, ConfigEvents, type ConfigEventsShape, ConfigFile, type ConfigFileMigration, ConfigFileNotFoundError, type ConfigFileOptions, ConfigFileReadError, type ConfigFileShape, type ConfigFileTestOptions, ConfigFileWriteError, type ConfigLoadError, ConfigMigration, ConfigMigrationError, type ConfigMigrationOptions, type ConfigReadError, ConfigResolver, type ConfigSaveError, type ConfigSource, ConfigSourceRef, type ConfigUpdateError, ConfigValidationError, type ConfigWriteError, EncryptedCodec, EncryptedCodecKey, JsonCodec, JsoncCodec, type LayerConfigProviderOptions, MergeStrategy, type NonEmptySources, TomlCodec, VersionAccess, YamlCodec, asConfigProvider, layerConfigProvider };
+export { type ConfigCodec, ConfigCodecError, ConfigDefaultPathMissingError, ConfigEncryptionError, ConfigEvent, ConfigEventPayload, ConfigEvents, type ConfigEventsShape, ConfigFile, type ConfigFileMigration, ConfigFileNotFoundError, type ConfigFileOptions, ConfigFileReadError, type ConfigFileShape, type ConfigFileTestOptions, ConfigFileWriteError, type ConfigLoadError, ConfigMigration, ConfigMigrationError, type ConfigMigrationOptions, type ConfigReadError, type ConfigReadOptions, ConfigResolver, type ConfigSaveError, type ConfigSource, ConfigSourceRef, type ConfigUpdateError, ConfigValidationError, type ConfigWriteError, EncryptedCodec, EncryptedCodecKey, JsonCodec, JsoncCodec, type LayerConfigProviderOptions, MergeStrategy, type NonEmptySources, TomlCodec, VersionAccess, YamlCodec, asConfigProvider, layerConfigProvider };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/config-file",
-	"version": "0.1.9",
+	"version": "0.2.0",
 	"private": false,
 	"description": "Composable config file loading for Effect: JSON, JSONC, YAML and TOML codecs, resolution strategies, and merge behaviors.",
 	"keywords": [
@@ -45,7 +45,7 @@
 	"peerDependencies": {
 		"@effected/jsonc": "~0.5.1",
 		"@effected/toml": "~0.3.1",
-		"@effected/walker": "~0.3.2",
+		"@effected/walker": "~0.3.3",
 		"@effected/yaml": "~0.6.0",
 		"effect": "4.0.0-beta.101"
 	},