@effected/app 0.19.0 → 0.20.0

package/App.js

@@ -59,6 +59,22 @@ var App = class {
 	* 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.
+	*
+	* @example
+	* ```ts
+	* import { App } from "@effected/app";
+	* import { NodeServices } from "@effect/platform-node";
+	* import { Layer } from "effect";
+	*
+	* const migrations = [
+	* 	{ id: 1, name: "runs", up: (sql) => sql`CREATE TABLE runs (id TEXT PRIMARY KEY)` },
+	* ];
+	*
+	* // Bound once, to a const: XDG dirs for "myapp", store.db and cache.db.
+	* const AppLive = App.layer({ namespace: "myapp", store: { migrations } }).pipe(
+	* 	Layer.provide(NodeServices.layer),
+	* );
+	* ```
 	*/
 	static layer = layer;
 	/**
@@ -73,9 +89,13 @@ var App = class {
 	*
 	* The documented limit: code paths that actually exercise `ensure*` **die**
 	* against `FileSystem.layerNoop` — it is a stub, not a working filesystem.
-	* `layerTest` is for testing logic that *uses* the control plane; a test of
-	* real directory behaviour uses {@link App.layer} with a temp-directory
-	* `HOME`.
+	* `layerTest` is for testing logic that *uses* the control plane. A test of
+	* real directory behaviour composes `AppDirs.layer` over `@effected/memfs`,
+	* whose `ensure*` members then create directories on an in-memory volume.
+	* The databases are the exception: `Store` and `Cache` open their SQLite
+	* files through the native binding, which never sees the `FileSystem`
+	* service, so a test of {@link App.layer} end to end still needs a
+	* temp-directory `HOME`.
 	*/
 	static layerTest = layerTest;
 };

package/AppConfig.js

@@ -65,9 +65,7 @@ var AppConfig = class {
 	* `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 preset contributes the ambient namespace and `defaultPath` alone.
 	*
 	* **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
@@ -76,6 +74,25 @@ var AppConfig = class {
 	*
 	* 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.
+	*
+	* @example
+	* ```ts
+	* import { AppConfig } from "@effected/app";
+	* import { ConfigFile, JsonCodec } from "@effected/config-file";
+	* import { Schema } from "effect";
+	*
+	* class Settings extends Schema.Class<Settings>("Settings")({
+	* 	registry: Schema.String,
+	* }) {}
+	* class SettingsFile extends ConfigFile.Service<SettingsFile, Settings>()("myapp/Settings") {}
+	*
+	* // The namespace comes from the ambient `AppDirs`, provided by `App.layer`.
+	* const ConfigLive = AppConfig.layer(SettingsFile, {
+	* 	filename: "config.json",
+	* 	schema: Settings,
+	* 	codec: JsonCodec,
+	* });
+	* ```
 	*/
 	static layer = layer;
 };

package/README.md

@@ -7,10 +7,10 @@
 
 The application control plane for Effect. `App.layer` gives an application its XDG-namespaced directories, a migrated SQLite state database, a TTL cache and — through `AppConfig.layer` — a config file, all pointed at the same place, with the namespace typed exactly once. It is a composition over [`@effected/xdg`](../xdg), [`@effected/store`](../store) and [`@effected/config-file`](../config-file), and nothing else.
 
-> **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

package/index.d.ts

@@ -168,6 +168,22 @@ export declare class App {
    * 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.
+   *
+   * @example
+   * ```ts
+   * import { App } from "@effected/app";
+   * import { NodeServices } from "@effect/platform-node";
+   * import { Layer } from "effect";
+   *
+   * const migrations = [
+   * 	{ id: 1, name: "runs", up: (sql) => sql`CREATE TABLE runs (id TEXT PRIMARY KEY)` },
+   * ];
+   *
+   * // Bound once, to a const: XDG dirs for "myapp", store.db and cache.db.
+   * const AppLive = App.layer({ namespace: "myapp", store: { migrations } }).pipe(
+   * 	Layer.provide(NodeServices.layer),
+   * );
+   * ```
    */
   static readonly layer: (options: AppOptions) => Layer.Layer<Xdg | AppDirs | Store | Cache, AppError, FileSystem.FileSystem | Path.Path>;
   /**
@@ -182,9 +198,13 @@ export declare class App {
    *
    * The documented limit: code paths that actually exercise `ensure*` **die**
    * against `FileSystem.layerNoop` — it is a stub, not a working filesystem.
-   * `layerTest` is for testing logic that *uses* the control plane; a test of
-   * real directory behaviour uses {@link App.layer} with a temp-directory
-   * `HOME`.
+   * `layerTest` is for testing logic that *uses* the control plane. A test of
+   * real directory behaviour composes `AppDirs.layer` over `@effected/memfs`,
+   * whose `ensure*` members then create directories on an in-memory volume.
+   * The databases are the exception: `Store` and `Cache` open their SQLite
+   * files through the native binding, which never sees the `FileSystem`
+   * service, so a test of {@link App.layer} end to end still needs a
+   * temp-directory `HOME`.
    */
   static readonly layerTest: (options: AppTestOptions) => Layer.Layer<Xdg | AppDirs | Store | Cache, AppError>;
 }
@@ -260,8 +280,7 @@ interface AppConfigOptions<A, I, RR = never> {
    * 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`.
+   * Absent, the chain is `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/cli`
@@ -381,9 +400,7 @@ export declare class AppConfig {
    * `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 preset contributes the ambient namespace and `defaultPath` alone.
    *
    * **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
@@ -392,6 +409,25 @@ export 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.
+   *
+   * @example
+   * ```ts
+   * import { AppConfig } from "@effected/app";
+   * import { ConfigFile, JsonCodec } from "@effected/config-file";
+   * import { Schema } from "effect";
+   *
+   * class Settings extends Schema.Class<Settings>("Settings")({
+   * 	registry: Schema.String,
+   * }) {}
+   * class SettingsFile extends ConfigFile.Service<SettingsFile, Settings>()("myapp/Settings") {}
+   *
+   * // The namespace comes from the ambient `AppDirs`, provided by `App.layer`.
+   * const ConfigLive = AppConfig.layer(SettingsFile, {
+   * 	filename: "config.json",
+   * 	schema: Settings,
+   * 	codec: JsonCodec,
+   * });
+   * ```
    */
   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>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/app",
-	"version": "0.19.0",
+	"version": "0.20.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,15 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/config-file": "^0.13.0",
-		"@effected/store": "^0.11.0",
-		"@effected/xdg": "^0.8.0",
-		"effect": "4.0.0-rc.118"
+		"@effected/config-file": "^0.14.0",
+		"@effected/glob": "^0.10.0",
+		"@effected/jsonc": "^0.15.0",
+		"@effected/store": "^0.12.0",
+		"@effected/toml": "^0.11.0",
+		"@effected/walker": "^0.15.0",
+		"@effected/xdg": "^0.9.0",
+		"@effected/yaml": "^0.19.0",
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"