@effected/app 0.9.1 → 0.10.0

package/App.js

@@ -53,6 +53,12 @@ var App = class {
 	* reuse that binding. Calling it inline at two provide sites opens two
 	* databases — two connections onto one file, two migration ledgers, and two
 	* independent `CacheEvent` PubSubs whose subscribers each see half the events.
+	*
+	* Testing cache expiry against this layer has one ordering rule: provide
+	* `TestClock.layer()` **outside** the `Effect.provide` that supplies this
+	* layer, never beneath it. Underneath, the test body has no `TestClock` in
+	* its own context and `TestClock.adjust` dies as a defect — so the entries
+	* under test carry real timestamps and nothing ever expires.
 	*/
 	static layer = layer;
 	/**

package/AppConfig.js

@@ -8,10 +8,14 @@ const layer = (tag, options) => Layer.unwrap(Effect.gen(function* () {
 	const invalid = badFilename("AppConfig.layer", options.filename);
 	if (invalid !== void 0) return yield* Effect.die(invalid);
 	const appDirs = yield* AppDirs;
-	const resolvers = options.native === false ? [XdgConfig.resolver({ filename: options.filename })] : [XdgConfig.resolver({ filename: options.filename }), XdgConfig.nativeResolver({
-		namespace: appDirs.namespace,
-		filename: options.filename
-	})];
+	const resolvers = [
+		...options.resolvers ?? [],
+		XdgConfig.resolver({ filename: options.filename }),
+		...options.native === false ? [] : [XdgConfig.nativeResolver({
+			namespace: appDirs.namespace,
+			filename: options.filename
+		})]
+	];
 	return ConfigFile.layer(tag, {
 		schema: options.schema,
 		codec: options.codec,
@@ -19,6 +23,7 @@ const layer = (tag, options) => Layer.unwrap(Effect.gen(function* () {
 		resolvers,
 		defaultPath: XdgConfig.savePath(options.filename),
 		...options.validate !== void 0 && { validate: options.validate },
+		...options.parseOptions !== void 0 && { parseOptions: options.parseOptions },
 		...options.events !== void 0 && { events: options.events }
 	});
 }));
@@ -47,6 +52,15 @@ var AppConfig = class {
 	* config-file's infallible `defaultPath` slot without an `orDie` because xdg
 	* resolves at layer-construction time.
 	*
+	* `options.resolvers` prepends to that chain, which covers the case this
+	* preset otherwise could not: a CLI whose `--config` flag must outrank the
+	* app's XDG search path. What it deliberately does not cover is a chain that
+	* needs the XDG resolvers somewhere other than last, or no XDG resolvers at
+	* all — an app wanting that composes `ConfigFile.layer` from
+	* `@effected/config-file` directly and orders the whole chain itself, which
+	* costs it only the `defaultPath` and ambient-namespace wiring this preset
+	* does for free.
+	*
 	* **The namespace is never a parameter.** It is read from the ambient
 	* `AppDirs` service at layer build time, so it is typed exactly once, in
 	* `App.layer` — the two-strings drift where an app passes `"myapp"` to

package/README.md

@@ -121,6 +121,59 @@ What it does take is a **codec, required**, never inferred from the filename's e
 
 `AppConfig` lives in its own module and reaches `@effected/xdg` and `@effected/config-file` **only** — never `@effected/store`. An application that wants XDG-placed config files and no database imports `AppConfig` alone, and no SQLite driver enters its graph. `App`, `AppStore` and `AppCache` are the exports that reach a database, and keeping the two graphs apart is why there is no `App = { … }` namespace object here.
 
+## A `--config` flag, without leaving the preset
+
+Most CLIs have one, and it has to outrank the app's own search path. Pass `resolvers` and it does:
+
+```ts
+import { AppConfig } from "@effected/app";
+import { ConfigResolver, TomlCodec } from "@effected/config-file";
+
+const ConfigLive = AppConfig.layer(SettingsFile, {
+ filename: "settings.toml",
+ schema: Settings,
+ codec: TomlCodec,
+ // Composed AHEAD of the XDG chain, in the order given.
+ resolvers: flag === undefined ? [] : [ConfigResolver.explicitPath(flag)],
+});
+```
+
+The XDG search path and the native probe stay behind whatever you prepend, so absent the flag nothing changes. `ConfigResolver.staticDir` covers a `--config` naming a directory, and `ConfigResolver.upwardWalk` a project-local file found by walking up from the cwd.
+
+Two properties to be deliberate about. **A resolver that finds nothing falls through**: every `ConfigResolver`'s error channel is `never` by contract, so a `--config` pointing at a file that does not exist quietly loads the XDG config instead. If that must be an error, check the path before you build the layer — discovery cannot make that distinction for you. And **the save path is unaffected**: `save` still writes to the app's own config directory, so writing back to the file a flag named is `write(value, path)`, which takes the path explicitly.
+
+### Wiring the flag to the layer
+
+A layer is built before a CLI parses anything, so the parsed `--config` has to reach `AppConfig.layer` somehow. `effect/unstable/cli` has two ways, and neither needs an `Effect.provide` inside the handler.
+
+For a single command, `Command.provide` takes **a function of the parsed input**, not just a finished layer:
+
+```ts
+Command.make("validate", { config: Flag.string("config").pipe(Flag.optional) }, () =>
+ Effect.gen(function* () {
+  const settings = yield* (yield* SettingsFile).load; // just requires the service
+ }),
+).pipe(Command.provide(({ config }) => makeConfigLive(Option.getOrUndefined(config))));
+```
+
+For several subcommands sharing one `--config`, make the flag a **global setting** — `GlobalFlag.setting` returns a `Context.Service`, so the parsed value can sit in the layer's `R` and the layer attaches once at the root:
+
+```ts
+const ConfigFlag = GlobalFlag.setting("config")({ flag: Flag.string("config").pipe(Flag.optional) });
+
+const ConfigLive = Layer.unwrap(Effect.map(ConfigFlag, (f) => makeConfigLive(Option.getOrUndefined(f))));
+
+const root = Command.make("myapp", {}, () => Effect.void).pipe(
+ Command.withSubcommands([validate, sync]),
+ Command.provide(ConfigLive), // one call site, every subcommand
+ Command.withGlobalFlags([ConfigFlag]),
+);
+```
+
+The flag is then accepted on either side of the subcommand name.
+
+A chain that needs the XDG resolvers somewhere other than last — or not at all — has outgrown the preset. Compose `ConfigFile.layer` from [`@effected/config-file`](../config-file) directly and order the whole chain yourself; it costs you only the `defaultPath` and ambient-namespace wiring this preset does for free.
+
 Its `native` option defaults to **`true`** — the opposite of `AppDirsOptions.native`, and the asymmetry is deliberate. *Creating* a native directory commits an application to a location, so it is opt-in; *probing* one for a config file the user already put there costs a `stat` that finds nothing, so it is opt-out. Reading `~/Library/Application Support` is a courtesy; writing there uninvited is not.
 
 ## Ensure before open

package/index.d.ts

@@ -1,7 +1,7 @@
 import { Cache, CacheError, CacheOptions, Store, StoreError, StoreMigrationError, StoreOptions } from "@effected/store";
 import { AppDirs, AppDirsError, AppDirsOptions, Xdg, XdgEnvError, XdgPaths } from "@effected/xdg";
-import { Context, Effect, FileSystem, Layer, Path, Schema } from "effect";
-import { ConfigCodec, ConfigEvents, ConfigEventsShape, ConfigFileShape, ConfigValidationError, MergeStrategy } from "@effected/config-file";
+import { Context, Effect, FileSystem, Layer, Path, Schema, SchemaAST } from "effect";
+import { ConfigCodec, ConfigEvents, ConfigEventsShape, ConfigFileShape, ConfigResolver, ConfigValidationError, MergeStrategy } from "@effected/config-file";
 //#region src/AppCache.d.ts
 /**
  * Options for {@link AppCache.layer}.
@@ -162,6 +162,12 @@ declare class App {
    * reuse that binding. Calling it inline at two provide sites opens two
    * databases — two connections onto one file, two migration ledgers, and two
    * independent `CacheEvent` PubSubs whose subscribers each see half the events.
+   *
+   * Testing cache expiry against this layer has one ordering rule: provide
+   * `TestClock.layer()` **outside** the `Effect.provide` that supplies this
+   * layer, never beneath it. Underneath, the test body has no `TestClock` in
+   * its own context and `TestClock.adjust` dies as a defect — so the entries
+   * under test carry real timestamps and nothing ever expires.
    */
   static readonly layer: (options: AppOptions) => Layer.Layer<Xdg | AppDirs | Store | Cache, AppError, FileSystem.FileSystem | Path.Path>;
   /**
@@ -187,9 +193,14 @@ declare class App {
 /**
  * Options for {@link AppConfig.layer}.
  *
+ * @remarks
+ * `RR` is the requirements of any caller-supplied `resolvers`; it defaults to
+ * `never`, so a chain of built-in resolvers — whose requirements are already in
+ * this layer's `R` — never has to be named.
+ *
  * @public
  */
-interface AppConfigOptions<A, I> {
+interface AppConfigOptions<A, I, RR = never> {
   /**
    * The config file's name within the app's config directory.
    *
@@ -216,8 +227,64 @@ interface AppConfigOptions<A, I> {
   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, chiefly
+   * `onExcessProperty`.
+   *
+   * @remarks
+   * Defaults to core's `"ignore"`, so a config file's unknown keys are dropped
+   * silently — which means a typo'd section cannot be reported, and a field
+   * this schema deliberately removed cannot be flagged in a user's older file.
+   * `{ onExcessProperty: "error" }` turns both into a `ConfigValidationError`
+   * naming the offending path.
+   *
+   * `validate` cannot do this: it runs on the decoded value, after the excess
+   * keys are gone. Keys covered by a `Schema.StructWithRest` rest are not
+   * excess, so a deliberate pass-through section still works under `"error"`.
+   *
+   * 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;
   /** The opt-in event hook. Pass the `ConfigEvents` class itself. */
   readonly events?: Context.Key<ConfigEvents, ConfigEventsShape>;
+  /**
+   * Resolvers composed **ahead** of the XDG chain, in priority order.
+   *
+   * @remarks
+   * The case this exists for is a CLI's `--config` flag: pass
+   * `ConfigResolver.explicitPath` for a file, or `ConfigResolver.staticDir` for
+   * a directory, and the flag wins — with the app's XDG search path, and the
+   * native probe, still behind it as the fallback. `ConfigResolver.upwardWalk`
+   * for a project-local file goes here too.
+   *
+   * Absent, the chain is exactly what it always was, so the default is
+   * unchanged: `XdgConfig.resolver`, then `XdgConfig.nativeResolver`.
+   *
+   * A layer is built before a CLI parses anything, so getting the parsed flag
+   * here is the one wiring question this option raises. `effect/unstable/cli`
+   * answers it twice, and neither answer needs an `Effect.provide` inside the
+   * handler: `Command.provide` accepts a **function of the parsed input**, and
+   * for several subcommands sharing one flag, `GlobalFlag.setting` makes the
+   * parsed value a `Context.Service` so the layer can take it in `R` and attach
+   * once at the root. The README shows both.
+   *
+   * Two properties to be deliberate about:
+   *
+   * - **A resolver that finds nothing falls through.** `explicitPath` resolves
+   *   `Option.none()` for a path that does not exist — every `ConfigResolver`'s
+   *   error channel is `never` by contract — so a `--config` pointing at a
+   *   missing file silently loads the XDG config instead. If the flag must be
+   *   an error when it names nothing, check the path before building the layer;
+   *   discovery cannot make that distinction for you.
+   * - **The save path is unaffected.** `save` still writes to
+   *   `XdgConfig.savePath(filename)`, not to whatever a prepended resolver
+   *   discovered. Loading from `--config` and writing back to that same file is
+   *   `write(value, path)`, which takes the path explicitly.
+   */
+  readonly resolvers?: ReadonlyArray<ConfigResolver<RR>>;
   /**
    * Probe the OS-native config directory as a fallback. Defaults to `true`.
    *
@@ -253,6 +320,15 @@ declare class AppConfig {
    * config-file's infallible `defaultPath` slot without an `orDie` because xdg
    * resolves at layer-construction time.
    *
+   * `options.resolvers` prepends to that chain, which covers the case this
+   * preset otherwise could not: a CLI whose `--config` flag must outrank the
+   * app's XDG search path. What it deliberately does not cover is a chain that
+   * needs the XDG resolvers somewhere other than last, or no XDG resolvers at
+   * all — an app wanting that composes `ConfigFile.layer` from
+   * `@effected/config-file` directly and orders the whole chain itself, which
+   * costs it only the `defaultPath` and ambient-namespace wiring this preset
+   * does for free.
+   *
    * **The namespace is never a parameter.** It is read from the ambient
    * `AppDirs` service at layer build time, so it is typed exactly once, in
    * `App.layer` — the two-strings drift where an app passes `"myapp"` to
@@ -261,7 +337,7 @@ declare class AppConfig {
    * This is a layer-returning function: bind the result to a `const` and reuse
    * that binding, or two provide sites mint two independent service instances.
    */
-  static readonly layer: <Self, A, I>(tag: Context.Key<Self, ConfigFileShape<A>>, options: AppConfigOptions<A, I>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path | AppDirs | Xdg>;
+  static readonly layer: <Self, A, I, RR = never>(tag: Context.Key<Self, ConfigFileShape<A>>, options: AppConfigOptions<A, I, RR>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path | AppDirs | Xdg | RR>;
 }
 //#endregion
 export { App, AppCache, type AppCacheOptions, AppConfig, type AppConfigOptions, type AppError, type AppOptions, AppStore, type AppStoreOptions, type AppTestOptions };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/app",
-	"version": "0.9.1",
+	"version": "0.10.0",
 	"private": false,
 	"description": "The application control plane for Effect: one layer wiring XDG-namespaced directories, a migrated SQLite store, a TTL cache and a config file to the same place.",
 	"keywords": [
@@ -39,9 +39,9 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/config-file": "^0.3.0",
-		"@effected/store": "^0.2.0",
-		"@effected/xdg": "^0.2.0",
+		"@effected/config-file": "^0.4.0",
+		"@effected/store": "^0.3.0",
+		"@effected/xdg": "^0.2.1",
 		"effect": "4.0.0-beta.107"
 	},
 	"engines": {