@effected/app 0.13.2 → 0.15.0

package/AppConfig.js

@@ -1,20 +1,29 @@
 import { badFilename } from "./internal/filename.js";
 import { AppDirs, XdgConfig } from "@effected/xdg";
 import { Effect, Layer } from "effect";
-import { ConfigFile, MergeStrategy } from "@effected/config-file";
+import { ConfigFile, ConfigResolver, MergeStrategy } from "@effected/config-file";
 
 //#region src/AppConfig.ts
 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 xdg = options.xdg !== false;
+	const systemEtc = options.systemEtc ?? false;
+	const systemEtcDir = typeof systemEtc === "object" ? systemEtc.dir : void 0;
 	const resolvers = [
 		...options.resolvers ?? [],
-		XdgConfig.resolver({ filename: options.filename }),
-		...options.native === false ? [] : [XdgConfig.nativeResolver({
+		...xdg ? [XdgConfig.resolver({ filename: options.filename })] : [],
+		...xdg && options.native !== false ? [XdgConfig.nativeResolver({
 			namespace: appDirs.namespace,
 			filename: options.filename
-		})]
+		})] : [],
+		...systemEtc === false ? [] : [ConfigResolver.systemEtc({
+			app: appDirs.namespace,
+			filename: options.filename,
+			...systemEtcDir !== void 0 && { dir: systemEtcDir }
+		})],
+		...options.resolversAfter ?? []
 	];
 	return ConfigFile.layer(tag, {
 		schema: options.schema,
@@ -52,14 +61,13 @@ 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 chain is caller-controlled at both ends: `options.resolvers` prepends,
+	* `options.resolversAfter` appends, `options.systemEtc` adds the `/etc`
+	* tier behind the XDG pair, and `options.xdg: false` removes the XDG pair
+	* altogether — at which point the chain is exactly the caller's own, and
+	* the preset is contributing the ambient namespace and `defaultPath` alone.
+	* Dropping to `ConfigFile.layer` directly is no longer the price of an
+	* unusual chain.
 	*
 	* **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

package/index.d.ts

@@ -25,7 +25,7 @@ interface AppCacheOptions extends CacheOptions {
  *
  * @public
  */
-declare class AppCache {
+export declare class AppCache {
   private constructor();
   /**
    * Build the cache-directory database layer: `AppDirs.ensureCache`, then
@@ -67,7 +67,7 @@ interface AppStoreOptions extends StoreOptions {
  *
  * @public
  */
-declare class AppStore {
+export declare class AppStore {
   private constructor();
   /**
    * Build the state-directory database layer: `AppDirs.ensureState`, then
@@ -141,7 +141,7 @@ interface AppTestOptions {
  *
  * @public
  */
-declare class App {
+export declare class App {
   private constructor();
   /**
    * Build the application control plane: namespaced directories, the state
@@ -292,8 +292,65 @@ interface AppConfigOptions<A, I, RR = never> {
    * The native probe sits **after** the XDG resolver, so an existing
    * `~/.config/<app>` still beats the native directory; on Linux it resolves
    * to nothing and never touches the filesystem. Pass `false` to drop it.
+   *
+   * Ignored when `xdg` is `false`: the native probe is the tail of the XDG
+   * fallback chain, not an independent tier.
    */
   readonly native?: boolean;
+  /**
+   * Probe the app's XDG config search path. Defaults to `true`.
+   *
+   * @remarks
+   * Pass `false` to build the chain from `resolvers` (and `resolversAfter`,
+   * and `systemEtc`) alone. The case it exists for is a CLI's
+   * `--config <path>` branch, where a search-path fallback defeats the flag's
+   * purpose: without it, a `--config` naming a file that fails to resolve
+   * silently loads the user's XDG config instead.
+   *
+   * It drops **both** XDG resolvers — `XdgConfig.resolver` and, since it is
+   * documented as sitting behind it, `XdgConfig.nativeResolver`. `native` has
+   * no effect while `xdg` is `false`.
+   *
+   * `defaultPath` is unaffected: `save` still writes to
+   * `XdgConfig.savePath(filename)`. Dropping the *discovery* tier is not a
+   * statement about where this app saves its config.
+   */
+  readonly xdg?: boolean;
+  /**
+   * Append the system tier — `<dir>/<namespace>/<filename>`, `/etc` by
+   * default — after the XDG chain. Defaults to absent (no system tier).
+   *
+   * @remarks
+   * `true` uses `/etc`; an object overrides the system config root, which is
+   * chiefly how a test points the tier at a writable directory. The app name
+   * is the ambient `AppDirs` namespace, never a parameter — the same rule the
+   * XDG resolvers follow, so the two cannot drift apart.
+   *
+   * It is appended **after** the XDG pair because a machine-wide default must
+   * lose to a user's own config, which is the whole convention. A chain that
+   * wants the system tier somewhere else passes
+   * `ConfigResolver.systemEtc` through `resolvers` or `resolversAfter`
+   * instead and leaves this absent.
+   */
+  readonly systemEtc?: boolean | {
+    readonly dir?: string;
+  };
+  /**
+   * Resolvers composed **after** every built-in tier, in priority order —
+   * the lowest-priority end of the chain.
+   *
+   * @remarks
+   * The counterpart to `resolvers`, which prepends. Together the two make the
+   * whole chain caller-controlled without giving up what this preset does for
+   * free (the ambient namespace and `defaultPath`): the built-ins can be
+   * surrounded, and with `xdg: false` they can be removed entirely, at which
+   * point the chain is exactly `[...resolvers, ...resolversAfter]`.
+   *
+   * These come last, after the system tier, so a caller who needs a different
+   * order around `systemEtc` leaves that option absent and passes
+   * `ConfigResolver.systemEtc` here in the position it wants.
+   */
+  readonly resolversAfter?: ReadonlyArray<ConfigResolver<RR>>;
 }
 /**
  * The xdg-flavored `ConfigFile` preset: discovery through the app's XDG
@@ -308,7 +365,7 @@ interface AppConfigOptions<A, I, RR = never> {
  *
  * @public
  */
-declare class AppConfig {
+export declare class AppConfig {
   private constructor();
   /**
    * Build the xdg-flavored config layer for a `ConfigFile.Service` class.
@@ -320,14 +377,13 @@ 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 chain is caller-controlled at both ends: `options.resolvers` prepends,
+   * `options.resolversAfter` appends, `options.systemEtc` adds the `/etc`
+   * tier behind the XDG pair, and `options.xdg: false` removes the XDG pair
+   * altogether — at which point the chain is exactly the caller's own, and
+   * the preset is contributing the ambient namespace and `defaultPath` alone.
+   * Dropping to `ConfigFile.layer` directly is no longer the price of an
+   * unusual chain.
    *
    * **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
@@ -340,5 +396,5 @@ declare class AppConfig {
   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 };
+export type { AppCacheOptions, AppConfigOptions, AppError, AppOptions, AppStoreOptions, AppTestOptions };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/app",
-	"version": "0.13.2",
+	"version": "0.15.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,10 +39,10 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/config-file": "^0.5.2",
-		"@effected/store": "^0.6.0",
-		"@effected/xdg": "^0.3.0",
-		"effect": "4.0.0-rc.109"
+		"@effected/config-file": "^0.7.0",
+		"@effected/store": "^0.7.0",
+		"@effected/xdg": "^0.4.1",
+		"effect": "4.0.0-rc.112"
 	},
 	"engines": {
 		"node": ">=24.11.0"