@effected/xdg 0.8.1 → 0.9.0

package/AppDirs.js

@@ -23,8 +23,7 @@ const AppDirKind = Schema.Literals([
 * layer construction, from an environment that is already resolved — so this
 * error means exactly one thing: the `mkdir -p` did not work. `directory` says
 * which kind, `path` says where, and `cause` carries the underlying
-* `PlatformError` structurally. v3 carried `reason: String(e)` and a `directory`
-* that could also be the string `"all"`.
+* `PlatformError` structurally.
 *
 * @public
 */
@@ -69,8 +68,8 @@ var ResolvedAppDirs = class extends Schema.Class("ResolvedAppDirs")({
 	*
 	* @remarks
 	* The app's own config directory, then each `$XDG_CONFIG_DIRS` entry
-	* namespaced. This is the half of the XDG spec v3 ignored entirely, and it is
-	* what makes {@link XdgConfig.resolver} a real search rather than a single stat.
+	* namespaced. It is what makes {@link XdgConfig.resolver} a real search
+	* rather than a single stat.
 	*/
 	configSearchPath: Schema.Array(Schema.String),
 	/** Where to look for data files, in priority order. */
@@ -86,9 +85,8 @@ var ResolvedAppDirs = class extends Schema.Class("ResolvedAppDirs")({
 * 5. `$HOME/.<namespace>`.
 *
 * Rungs 4 and 5 are deliberately **not** the XDG spec's per-kind defaults
-* (`~/.config`, `~/.local/share`, …). This is inherited v3 behaviour and is kept:
-* a CLI wanting spec defaults passes them as `dirs` overrides. The deviation is
-* documented rather than left for a reader to discover.
+* (`~/.config`, `~/.local/share`, …): a CLI wanting spec defaults passes them as
+* `dirs` overrides.
 */
 const resolveDir = (input) => {
 	const { override, xdgHome, native, options, home, path } = input;
@@ -150,8 +148,18 @@ const badNamespace = (namespace) => {
 *
 * @example
 * ```ts
-* const AppDirsLayer = AppDirs.layer({ namespace: "myapp", native: true });
-* const XdgLayer = Layer.mergeAll(Xdg.layer, AppDirsLayer.pipe(Layer.provide(Xdg.layer)));
+* import { AppDirs, Xdg } from "@effected/xdg";
+* import { Effect, Layer } from "effect";
+*
+* // Bound once to a const, with the ambient `Xdg` environment provided and kept.
+* const AppDirsLive = Layer.provideMerge(AppDirs.layer({ namespace: "myapp", native: true }), Xdg.layer);
+*
+* const program = Effect.gen(function* () {
+* 	const appDirs = yield* AppDirs;
+* 	const configDir = yield* appDirs.ensureConfig;
+* 	console.log(configDir);
+* });
+* // Requires `FileSystem` and `Path` from the platform layer.
 * ```
 *
 * @public
@@ -164,8 +172,7 @@ var AppDirs = class AppDirs extends Context.Service()("@effected/xdg/AppDirs") {
 	* @remarks
 	* The error channel is `never`. The one failure that could happen during
 	* resolution — an unset `HOME` — surfaces on {@link Xdg.layer} as an
-	* `XdgEnvError`, before an `AppDirs` exists at all. v3 laundered it into an
-	* `AppDirsError({ directory: "all" })`.
+	* `XdgEnvError`, before an `AppDirs` exists at all.
 	*/
 	static layer(options) {
 		return Layer.effect(AppDirs, Effect.gen(function* () {

package/NativeDirs.js

@@ -28,8 +28,7 @@ var NativeDirs = class NativeDirs extends Schema.Class("NativeDirs")({
 	* **Pure**: no filesystem, no environment, no `process.platform`. Every input
 	* is a parameter, which is what makes the whole platform matrix testable
 	* without any platform IO. Paths are joined through the supplied `Path`, so a
-	* win32 `Path` layer yields win32 separators — v3 interpolated `/` on every
-	* platform.
+	* win32 `Path` layer yields win32 separators.
 	*
 	* - **darwin** — `config`/`data`/`state` under `~/Library/Application Support/<ns>`;
 	*   `cache` under `~/Library/Caches/<ns>`.

package/README.md

@@ -7,10 +7,10 @@
 
 XDG Base Directory resolution for Effect. `Xdg` reads the environment — `$HOME`, the four `*_HOME` variables, `$XDG_RUNTIME_DIR`, and the `$XDG_CONFIG_DIRS` / `$XDG_DATA_DIRS` search paths — once, at layer construction. `AppDirs` turns that into the config, data, cache, state and runtime directories for one application namespace, with on-demand creation. `NativeDirs` supplies the macOS and Windows conventions for applications that want them, and `XdgConfig` plugs the whole thing into [`@effected/config-file`](../config-file) as a resolver chain and a save target.
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered
@@ -128,6 +128,34 @@ Order matters: put `resolver` before `nativeResolver` so an existing `~/.config/
 
 A namespace that is empty, or contains a path separator, or is exactly `.` or `..`, is a **defect** at layer construction rather than a typed error. It can only come from code, and `namespace: "../.."` would resolve the application's directories outside `$HOME` entirely.
 
+## Testing
+
+`@effected/memfs` virtualizes the filesystem, not the platform. `AppDirs` and `XdgConfig` read the platform through the `CurrentPlatform` reference, which defaults to the host's `process.platform`, so a test that only swaps the filesystem still takes the host's darwin, linux or win32 branch. Pin the platform as well:
+
+```ts
+import { MemoryFileSystem } from "@effected/memfs";
+import { AppDirs, CurrentPlatform, Xdg, XdgPaths } from "@effected/xdg";
+import { Effect, Layer, Path } from "effect";
+
+const TestEnv = Layer.mergeAll(
+  Xdg.layerFrom(XdgPaths.make({ home: "/home/ada", configDirs: ["/etc/xdg"], dataDirs: ["/usr/share"] })),
+  MemoryFileSystem.layer,
+  Path.layer,
+);
+
+const config = Effect.gen(function* () {
+  const appDirs = yield* AppDirs;
+  return appDirs.dirs.config;
+}).pipe(
+  Effect.provide(AppDirs.layer({ namespace: "myapp", native: true }).pipe(Layer.provide(TestEnv))),
+  Effect.provideService(CurrentPlatform, "linux"),
+);
+// "/home/ada/.myapp" on every host; pin "darwin" and the same program answers
+// "/home/ada/Library/Application Support/myapp"
+```
+
+`Layer.succeed(CurrentPlatform, "win32")` is the equivalent layer form, for composing the pin into a test layer graph.
+
 ## Features
 
 - `Xdg` / `XdgPaths` — the resolved XDG environment as a value, including the `$XDG_CONFIG_DIRS` and `$XDG_DATA_DIRS` search paths, split and defaulted per the spec. `Xdg.layerFrom` serves fixed paths for tests.

package/Xdg.js

@@ -32,7 +32,7 @@ const detectPlatform = () => {
 * The platform every native-directory decision is taken against.
 *
 * @remarks
-* A {@link https://effect.website | Context.Reference}, not a global read. It
+* A `Context.Reference`, not a global read. It
 * defaults to `process.platform`, so production behaviour is what you expect;
 * a test pins macOS or Windows semantics with
 * `Layer.succeed(CurrentPlatform, "win32")` and exercises the whole native-path
@@ -47,7 +47,7 @@ const CurrentPlatform = Context.Reference("@effected/xdg/CurrentPlatform", { def
 * @remarks
 * Raised only for `HOME`: every other XDG variable is optional by construction,
 * and its absence is a resolved default rather than a failure. `cause` carries
-* the underlying `ConfigError` structurally — v3 flattened it to a string.
+* the underlying `ConfigError` structurally.
 *
 * @public
 */
@@ -67,8 +67,7 @@ var XdgEnvError = class extends Schema.TaggedError()("XdgEnvError", {
 * @remarks
 * Every field but `home` is optional because the corresponding variable is:
 * `Schema.optionalKey`, so an unset variable is an **absent key** and the read
-* is `paths.configHome ?? fallback`. v3 modeled these as `Option`, which forced
-* `Option.some(...)` into the construction API of everything downstream.
+* is `paths.configHome ?? fallback`.
 *
 * `configDirs` and `dataDirs` are the colon-separated system search paths, split
 * and defaulted per the spec (`/etc/xdg` and `/usr/local/share:/usr/share`).
@@ -116,11 +115,9 @@ const splitDirs = (raw, fallback) => {
 *
 * @remarks
 * The service's shape **is** {@link XdgPaths}: the environment is read once, at
-* layer construction, and the service is the resolved value. v3 exposed nine
-* `Effect`s that each re-read the environment on every access, which is why
-* every path downstream of it was fallible. Here `yield* Xdg` gives you a record
-* of strings, and the only failure — an unset `HOME` — happens once, where the
-* layer is built.
+* layer construction, and the service is the resolved value. `yield* Xdg` gives
+* you a record of strings, and the only failure — an unset `HOME` — happens
+* once, where the layer is built.
 *
 * @public
 */
@@ -177,8 +174,21 @@ var Xdg = class Xdg extends Context.Service()("@effected/xdg/Xdg") {
 	*
 	* @remarks
 	* The test layer, and the escape hatch for an application that resolves its
-	* environment some other way. It needs no filesystem — v3's test layer reached
-	* past the platform abstraction for a `node:fs` temp directory.
+	* environment some other way. It needs no filesystem.
+	*
+	* @example
+	* ```ts
+	* import { Xdg, XdgPaths } from "@effected/xdg";
+	*
+	* const TestXdg = Xdg.layerFrom(
+	* 	XdgPaths.make({
+	* 		home: "/home/test",
+	* 		configHome: "/home/test/.config",
+	* 		configDirs: ["/etc/xdg"],
+	* 		dataDirs: ["/usr/local/share", "/usr/share"],
+	* 	}),
+	* );
+	* ```
 	*/
 	static layerFrom(paths) {
 		return Layer.succeed(Xdg, paths);

package/XdgConfig.js

@@ -48,16 +48,13 @@ var XdgConfig = class {
 	*
 	* @remarks
 	* Probes the app's own config directory first, then each `$XDG_CONFIG_DIRS`
-	* entry namespaced — `~/.config/myapp/rc`, then `/etc/xdg/myapp/rc`. v3 probed
-	* only the first of those; the system search path is half the XDG spec and it
-	* was missing.
+	* entry namespaced — `~/.config/myapp/rc`, then `/etc/xdg/myapp/rc`.
 	*
 	* The scan runs through `Walker.firstMatch`, so a failure on one candidate means
-	* "this candidate did not match" and the search continues to the next. That is a
-	* bug fixed, not a refactor: v3 wrapped the whole resolver in a single
-	* `catchAll`, so an unreadable `/etc/xdg` aborted the probe and hid a perfectly
-	* readable `~/.config`. Not-found and cannot-look stay indistinguishable to the
-	* caller, which is the resolver contract — `resolve`'s error channel is `never`.
+	* "this candidate did not match" and the search continues to the next: an unreadable
+	* `/etc/xdg` never hides a readable `~/.config`. Not-found and cannot-look stay
+	* indistinguishable to the caller, which is the resolver contract —
+	* `resolve`'s error channel is `never`.
 	*
 	* Place it **before** {@link XdgConfig.nativeResolver} in a chain, so an
 	* existing `~/.config/<app>` still wins over the OS-native directory.
@@ -86,14 +83,17 @@ var XdgConfig = class {
 	* @remarks
 	* Drops straight into `ConfigFileOptions.defaultPath`, whose slot is typed
 	* `Effect<string, never, RR>`. That infallible channel is the whole reason
-	* {@link AppDirs} resolves at layer-construction time: with v3's per-access
-	* resolution this could fail, and a consumer had to `orDie` it into the slot.
+	* {@link AppDirs} resolves at layer-construction time, so no `orDie` is needed
+	* to fit the slot.
 	*
 	* It does **not** create the directory — `ConfigFile.save` already `mkdir -p`s
 	* the parent of whatever path it is given.
 	*
 	* @example
 	* ```ts
+	* import { XdgConfig } from "@effected/xdg";
+	* import { ConfigFile, JsonCodec, MergeStrategy } from "@effected/config-file";
+	*
 	* const layer = ConfigFile.layer(AppConfig, {
 	* 	schema: AppShape,
 	* 	codec: JsonCodec,

package/index.d.ts

@@ -22,7 +22,7 @@ export type XdgPlatform = typeof XdgPlatform.Type;
  * The platform every native-directory decision is taken against.
  *
  * @remarks
- * A {@link https://effect.website | Context.Reference}, not a global read. It
+ * A `Context.Reference`, not a global read. It
  * defaults to `process.platform`, so production behaviour is what you expect;
  * a test pins macOS or Windows semantics with
  * `Layer.succeed(CurrentPlatform, "win32")` and exercises the whole native-path
@@ -43,7 +43,7 @@ declare const XdgEnvError_base: Schema.Class<XdgEnvError, Schema.TaggedStruct<"X
  * @remarks
  * Raised only for `HOME`: every other XDG variable is optional by construction,
  * and its absence is a resolved default rather than a failure. `cause` carries
- * the underlying `ConfigError` structurally — v3 flattened it to a string.
+ * the underlying `ConfigError` structurally.
  *
  * @public
  */
@@ -78,8 +78,7 @@ declare const XdgPaths_base: Schema.Class<XdgPaths, Schema.Struct<{
  * @remarks
  * Every field but `home` is optional because the corresponding variable is:
  * `Schema.optionalKey`, so an unset variable is an **absent key** and the read
- * is `paths.configHome ?? fallback`. v3 modeled these as `Option`, which forced
- * `Option.some(...)` into the construction API of everything downstream.
+ * is `paths.configHome ?? fallback`.
  *
  * `configDirs` and `dataDirs` are the colon-separated system search paths, split
  * and defaulted per the spec (`/etc/xdg` and `/usr/local/share:/usr/share`).
@@ -95,11 +94,9 @@ declare const Xdg_base: Context.ServiceClass<Xdg, "@effected/xdg/Xdg", XdgPaths>
  *
  * @remarks
  * The service's shape **is** {@link XdgPaths}: the environment is read once, at
- * layer construction, and the service is the resolved value. v3 exposed nine
- * `Effect`s that each re-read the environment on every access, which is why
- * every path downstream of it was fallible. Here `yield* Xdg` gives you a record
- * of strings, and the only failure — an unset `HOME` — happens once, where the
- * layer is built.
+ * layer construction, and the service is the resolved value. `yield* Xdg` gives
+ * you a record of strings, and the only failure — an unset `HOME` — happens
+ * once, where the layer is built.
  *
  * @public
  */
@@ -118,8 +115,21 @@ export declare class Xdg extends Xdg_base {
    *
    * @remarks
    * The test layer, and the escape hatch for an application that resolves its
-   * environment some other way. It needs no filesystem — v3's test layer reached
-   * past the platform abstraction for a `node:fs` temp directory.
+   * environment some other way. It needs no filesystem.
+   *
+   * @example
+   * ```ts
+   * import { Xdg, XdgPaths } from "@effected/xdg";
+   *
+   * const TestXdg = Xdg.layerFrom(
+   * 	XdgPaths.make({
+   * 		home: "/home/test",
+   * 		configHome: "/home/test/.config",
+   * 		configDirs: ["/etc/xdg"],
+   * 		dataDirs: ["/usr/local/share", "/usr/share"],
+   * 	}),
+   * );
+   * ```
    */
   static layerFrom(paths: XdgPaths): Layer.Layer<Xdg>;
 }
@@ -153,8 +163,7 @@ declare const AppDirsError_base: Schema.Class<AppDirsError, Schema.TaggedStruct<
  * layer construction, from an environment that is already resolved — so this
  * error means exactly one thing: the `mkdir -p` did not work. `directory` says
  * which kind, `path` says where, and `cause` carries the underlying
- * `PlatformError` structurally. v3 carried `reason: String(e)` and a `directory`
- * that could also be the string `"all"`.
+ * `PlatformError` structurally.
  *
  * @public
  */
@@ -185,8 +194,8 @@ declare const ResolvedAppDirs_base: Schema.Class<ResolvedAppDirs, Schema.Struct<
    *
    * @remarks
    * The app's own config directory, then each `$XDG_CONFIG_DIRS` entry
-   * namespaced. This is the half of the XDG spec v3 ignored entirely, and it is
-   * what makes {@link XdgConfig.resolver} a real search rather than a single stat.
+   * namespaced. It is what makes {@link XdgConfig.resolver} a real search
+   * rather than a single stat.
    */
   readonly configSearchPath: Schema.$Array<Schema.String>;
   /** Where to look for data files, in priority order. */
@@ -219,9 +228,9 @@ interface AppDirOverrides {
  * Options for {@link AppDirs.layer}.
  *
  * @remarks
- * Plain optional fields, not `Option`s: v3 made callers write
- * `fallbackDir: Option.some(".myapp"), dirs: Option.none()`. `Option` is an
- * internal representation, not an input format.
+ * Plain optional fields, not `Option`s: `Option` is an internal
+ * representation, not an input format, so write `fallbackDir: ".myapp"` and
+ * omit `dirs` when unused.
  *
  * @public
  */
@@ -300,8 +309,18 @@ declare const AppDirs_base: Context.ServiceClass<AppDirs, "@effected/xdg/AppDirs
  *
  * @example
  * ```ts
- * const AppDirsLayer = AppDirs.layer({ namespace: "myapp", native: true });
- * const XdgLayer = Layer.mergeAll(Xdg.layer, AppDirsLayer.pipe(Layer.provide(Xdg.layer)));
+ * import { AppDirs, Xdg } from "@effected/xdg";
+ * import { Effect, Layer } from "effect";
+ *
+ * // Bound once to a const, with the ambient `Xdg` environment provided and kept.
+ * const AppDirsLive = Layer.provideMerge(AppDirs.layer({ namespace: "myapp", native: true }), Xdg.layer);
+ *
+ * const program = Effect.gen(function* () {
+ * 	const appDirs = yield* AppDirs;
+ * 	const configDir = yield* appDirs.ensureConfig;
+ * 	console.log(configDir);
+ * });
+ * // Requires `FileSystem` and `Path` from the platform layer.
  * ```
  *
  * @public
@@ -314,8 +333,7 @@ export declare class AppDirs extends AppDirs_base {
    * @remarks
    * The error channel is `never`. The one failure that could happen during
    * resolution — an unset `HOME` — surfaces on {@link Xdg.layer} as an
-   * `XdgEnvError`, before an `AppDirs` exists at all. v3 laundered it into an
-   * `AppDirsError({ directory: "all" })`.
+   * `XdgEnvError`, before an `AppDirs` exists at all.
    */
   static layer(options: AppDirsOptions): Layer.Layer<AppDirs, never, Xdg | FileSystem.FileSystem | Path.Path>;
 }
@@ -349,8 +367,7 @@ export declare class NativeDirs extends NativeDirs_base {
    * **Pure**: no filesystem, no environment, no `process.platform`. Every input
    * is a parameter, which is what makes the whole platform matrix testable
    * without any platform IO. Paths are joined through the supplied `Path`, so a
-   * win32 `Path` layer yields win32 separators — v3 interpolated `/` on every
-   * platform.
+   * win32 `Path` layer yields win32 separators.
    *
    * - **darwin** — `config`/`data`/`state` under `~/Library/Application Support/<ns>`;
    *   `cache` under `~/Library/Caches/<ns>`.
@@ -384,16 +401,13 @@ export declare class XdgConfig {
    *
    * @remarks
    * Probes the app's own config directory first, then each `$XDG_CONFIG_DIRS`
-   * entry namespaced — `~/.config/myapp/rc`, then `/etc/xdg/myapp/rc`. v3 probed
-   * only the first of those; the system search path is half the XDG spec and it
-   * was missing.
+   * entry namespaced — `~/.config/myapp/rc`, then `/etc/xdg/myapp/rc`.
    *
    * The scan runs through `Walker.firstMatch`, so a failure on one candidate means
-   * "this candidate did not match" and the search continues to the next. That is a
-   * bug fixed, not a refactor: v3 wrapped the whole resolver in a single
-   * `catchAll`, so an unreadable `/etc/xdg` aborted the probe and hid a perfectly
-   * readable `~/.config`. Not-found and cannot-look stay indistinguishable to the
-   * caller, which is the resolver contract — `resolve`'s error channel is `never`.
+   * "this candidate did not match" and the search continues to the next: an unreadable
+   * `/etc/xdg` never hides a readable `~/.config`. Not-found and cannot-look stay
+   * indistinguishable to the caller, which is the resolver contract —
+   * `resolve`'s error channel is `never`.
    *
    * Place it **before** {@link XdgConfig.nativeResolver} in a chain, so an
    * existing `~/.config/<app>` still wins over the OS-native directory.
@@ -427,14 +441,17 @@ export declare class XdgConfig {
    * @remarks
    * Drops straight into `ConfigFileOptions.defaultPath`, whose slot is typed
    * `Effect<string, never, RR>`. That infallible channel is the whole reason
-   * {@link AppDirs} resolves at layer-construction time: with v3's per-access
-   * resolution this could fail, and a consumer had to `orDie` it into the slot.
+   * {@link AppDirs} resolves at layer-construction time, so no `orDie` is needed
+   * to fit the slot.
    *
    * It does **not** create the directory — `ConfigFile.save` already `mkdir -p`s
    * the parent of whatever path it is given.
    *
    * @example
    * ```ts
+   * import { XdgConfig } from "@effected/xdg";
+   * import { ConfigFile, JsonCodec, MergeStrategy } from "@effected/config-file";
+   *
    * const layer = ConfigFile.layer(AppConfig, {
    * 	schema: AppShape,
    * 	codec: JsonCodec,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/xdg",
-	"version": "0.8.1",
+	"version": "0.9.0",
 	"private": false,
 	"description": "XDG Base Directory resolution for Effect: environment paths, app-namespaced directories, native OS conventions and config-file resolvers.",
 	"keywords": [
@@ -38,9 +38,13 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/config-file": "^0.13.1",
-		"@effected/walker": "^0.14.0",
-		"effect": "4.0.0-rc.118"
+		"@effected/config-file": "^0.14.0",
+		"@effected/glob": "^0.10.0",
+		"@effected/jsonc": "^0.15.0",
+		"@effected/toml": "^0.11.0",
+		"@effected/walker": "^0.15.0",
+		"@effected/yaml": "^0.19.0",
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"