@maroonedsoftware/appconfig 1.5.1 → 1.7.0

package/README.md

@@ -6,9 +6,10 @@ A flexible, type-safe configuration management library with support for multiple
 
 - **Type-safe access** - Full TypeScript support with generics
 - **Multiple sources** - Load configuration from JSON files, YAML files, `.env` files, and more
-- **Value transformation** - Resolve environment variables and GCP secrets in configuration values
+- **Value transformation** - Resolve environment variables, GCP secrets, and AWS secrets in configuration values
 - **Deep merging** - Combine configurations from multiple sources with predictable override behavior
 - **Flat key grouping** - Collapse `KEY__sub=val` dotenv entries into nested objects automatically
+- **Live reload** - Rebuild config on demand (e.g. when a secret rotates) and push the latest values into singletons via an `IOptions`-style accessor trio
 - **Extensible** - Create custom sources and providers for your specific needs
 
 ## Installation
@@ -127,6 +128,39 @@ const config = await new AppConfigBuilder()
 
 > **Note:** The GCP secrets provider requires valid GCP credentials. It uses Application Default Credentials (ADC), so ensure you have authenticated via `gcloud auth application-default login` or have set up a service account.
 
+### AWS Secrets Manager Integration
+
+Use `${aws:SECRET_ID}` syntax to resolve secrets from AWS Secrets Manager. The secret id may be a secret name or a full ARN:
+
+**config.json:**
+
+```json
+{
+  "database": {
+    "password": "${aws:DB_PASSWORD}",
+    "connectionString": "${aws:DATABASE_CONNECTION_STRING}"
+  },
+  "api": {
+    "key": "${aws:API_SECRET_KEY}"
+  }
+}
+```
+
+**app.ts:**
+
+```typescript
+import { AppConfigBuilder, AppConfigSourceJson, AppConfigProviderAwsSecrets } from '@maroonedsoftware/appconfig';
+
+const config = await new AppConfigBuilder()
+  .addSource(new AppConfigSourceJson('./config.json'))
+  .addProvider(new AppConfigProviderAwsSecrets('us-east-1'))
+  .build();
+
+// Secrets are fetched from AWS Secrets Manager (latest version)
+```
+
+> **Note:** The AWS secrets provider requires valid AWS credentials. Credentials and the region are resolved from the standard AWS provider chain (environment variables such as `AWS_ACCESS_KEY_ID`/`AWS_REGION`, shared config/credentials files, or instance/task IAM roles). The `region` argument is optional and overrides the chain when provided.
+
 ## API
 
 ### AppConfig
@@ -322,6 +356,120 @@ The provider:
 - Requires valid GCP credentials (uses Application Default Credentials)
 - Is decorated with `@Injectable()` for dependency injection support
 
+#### AppConfigProviderAwsSecrets
+
+Resolves AWS Secrets Manager references in configuration values.
+
+```typescript
+// Default pattern: ${aws:SECRET_ID}, region from the AWS provider chain
+const provider = new AppConfigProviderAwsSecrets();
+
+// Explicit region
+const provider = new AppConfigProviderAwsSecrets('us-east-1');
+
+// Custom regex pattern
+const provider = new AppConfigProviderAwsSecrets('us-east-1', /\$\{secret:([^}]+)\}/g);
+```
+
+| Parameter | Type               | Description                                                                                       |
+| --------- | ------------------ | ------------------------------------------------------------------------------------------------ |
+| `region`  | `string`           | Optional AWS region. Resolved from the AWS provider chain when omitted                            |
+| `prefix`  | `string \| RegExp` | Optional pattern to match secret references. Default: `/\$\{aws:(.+)\}/g` (matches `${aws:ID}`)   |
+
+The provider:
+
+- Fetches secrets from AWS Secrets Manager using the latest version (`AWSCURRENT`)
+- Supports both `SecretString` and `SecretBinary` (binary is decoded as UTF-8)
+- Automatically attempts to parse secret values as JSON
+- Requires valid AWS credentials (uses the standard AWS provider chain)
+- Is decorated with `@Injectable()` for dependency injection support
+
+## Live configuration
+
+`AppConfigBuilder.build()` resolves everything once and returns an immutable `AppConfig`. When a
+value can change at runtime — most often a secret rotated in GCP/AWS Secret Manager — you can rebuild
+the config and have running singletons observe the new value, mirroring C#'s `IOptions` /
+`IOptionsSnapshot` / `IOptionsMonitor`.
+
+### AppConfigStore
+
+Holds the current `AppConfig` and rebuilds it on demand. `reload()` re-runs the full builder pipeline
+(re-reading sources and re-resolving providers); it swaps in the new config **only on success**, so a
+failed rebuild leaves the process on its last-good values and rethrows for the caller to log.
+
+```typescript
+const builder = new AppConfigBuilder().addSource(jsonSource).addProvider(awsSecrets);
+const store = new AppConfigStore(builder, await builder.build<RootConfig>());
+
+// Driven by your own trigger — a timer, a GCP Pub-Sub message, an AWS EventBridge event, etc.
+await store.reload().catch(err => logger.error('config reload failed', err));
+```
+
+The store delivers the `reload()` primitive only; deciding _when_ to reload is left to the application.
+
+### The options trio
+
+| Accessor                      | Lifetime  | Value                      | Use it for                                          |
+| ----------------------------- | --------- | -------------------------- | --------------------------------------------------- |
+| `AppConfigOptions<T>`         | singleton | `.value` (boot snapshot)   | values that never change at runtime                 |
+| `AppConfigOptionsSnapshot<T>` | scoped    | `.value` (stable per request) | request-stable values that may differ between requests |
+| `AppConfigOptionsMonitor<T>`  | singleton | `.current` + `onChange`    | live values; react to changes (rebuild a pool, etc.) |
+
+Each is an abstract `@Injectable()` class, so a configuration section mints its own DI token by
+subclassing — the same one-class-per-section shape used by `SlackConfig` and `Logger`:
+
+```typescript
+@Injectable() export abstract class SlackOptionsMonitor extends AppConfigOptionsMonitor<SlackConfig> {}
+@Injectable() export abstract class SlackOptionsSnapshot extends AppConfigOptionsSnapshot<SlackConfig> {}
+```
+
+### Wiring with AppConfigOptionsManager
+
+`AppConfigOptionsManager` owns the live monitors and keeps them in sync with the store. At bootstrap,
+register the tiers a section needs with `registerAppConfigOptions`:
+
+```typescript
+const store = new AppConfigStore(builder, await builder.build<RootConfig>());
+const manager = new AppConfigOptionsManager(store, logger); // logger: @maroonedsoftware/logger
+
+registerAppConfigOptions(registry, store, manager, 'slack', {
+  monitor: SlackOptionsMonitor,
+  snapshot: SlackOptionsSnapshot,
+});
+```
+
+Consumers inject the token like any other service:
+
+```typescript
+@Injectable()
+class SlackClient {
+  constructor(private readonly options: SlackOptionsMonitor) {}
+
+  send() {
+    // Read at use-time — never cache `current` in a field, or you lose live updates.
+    postWebhook(this.options.current.incomingWebhookUrl);
+  }
+}
+
+@Injectable()
+class DbPool {
+  private pool = createPool(this.options.current);
+
+  constructor(private readonly options: DbOptionsMonitor) {
+    // Rebuild the pool when a credential rotates.
+    this.options.onChange(async cfg => {
+      const previous = this.pool;
+      this.pool = createPool(cfg);
+      await previous.end();
+    });
+  }
+}
+```
+
+`onChange` fires only when a reload produces a structurally different value (a re-fetched but identical
+secret is ignored), the listener may be async, and a throwing/rejecting listener is reported via the
+manager's logger without affecting the swap or other listeners. The returned function unsubscribes.
+
 ## Utilities
 
 ### nestKeys

package/dist/helpers.d.ts

@@ -5,6 +5,23 @@
  * @returns The parsed JSON value, or the original text if parsing fails.
  */
 export declare function tryParseJson(text: string): unknown;
+/**
+ * Recursively compares two values for structural equality.
+ *
+ * Used to suppress no-op config-reload notifications: a secret re-fetched from a
+ * secret manager often produces a value that is structurally identical to the
+ * one already held, and reloading it should not bounce live consumers (e.g. a DB
+ * pool listening via `onChange`).
+ *
+ * Handles primitives, arrays, and plain objects by value. Two `NaN`s compare as
+ * unequal (matching `===` semantics); functions and other exotic values compare
+ * by reference. Key order is ignored for objects.
+ *
+ * @param a - The first value to compare.
+ * @param b - The second value to compare.
+ * @returns `true` if the values are structurally equal, `false` otherwise.
+ */
+export declare function structurallyEqual(a: unknown, b: unknown): boolean;
 /**
  * Transforms a flat key/value record into a nested object by splitting keys on a
  * separator string.

package/dist/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMlD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsBpG"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMlD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAuBjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsBpG"}

package/dist/index.d.ts

@@ -8,5 +8,12 @@ export { AppConfigSourceJson } from './sources/app.config.source.json.js';
 export { AppConfigSourceYaml } from './sources/app.config.source.yaml.js';
 export { AppConfigProviderDotenv } from './providers/app.config.provider.dotenv.js';
 export { AppConfigProviderGcpSecrets } from './providers/app.config.provider.gcp.secrets.js';
+export { AppConfigProviderAwsSecrets } from './providers/app.config.provider.aws.secrets.js';
 export { nestKeys } from './helpers.js';
+export { AppConfigOptions, AppConfigOptionsSnapshot, AppConfigOptionsMonitor } from './options/app.config.options.js';
+export { AppConfigStore } from './options/app.config.store.js';
+export type { AppConfigStoreListener } from './options/app.config.store.js';
+export { AppConfigOptionsManager } from './options/app.config.options.manager.js';
+export { registerAppConfigOptions } from './options/app.config.options.registration.js';
+export type { AppConfigOptionsTokens } from './options/app.config.options.registration.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,YAAY,EAAE,4BAA4B,EAAE,MAAM,uCAAuC,CAAC;AAC1F,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AACpF,OAAO,EAAE,2BAA2B,EAAE,MAAM,gDAAgD,CAAC;AAC7F,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,YAAY,EAAE,4BAA4B,EAAE,MAAM,uCAAuC,CAAC;AAC1F,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AACpF,OAAO,EAAE,2BAA2B,EAAE,MAAM,gDAAgD,CAAC;AAC7F,OAAO,EAAE,2BAA2B,EAAE,MAAM,gDAAgD,CAAC;AAC7F,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AACtH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,YAAY,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC5E,OAAO,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAClF,OAAO,EAAE,wBAAwB,EAAE,MAAM,8CAA8C,CAAC;AACxF,YAAY,EAAE,sBAAsB,EAAE,MAAM,8CAA8C,CAAC"}

package/dist/index.js

@@ -270,6 +270,29 @@ function tryParseJson(text) {
   }
 }
 __name(tryParseJson, "tryParseJson");
+function structurallyEqual(a, b) {
+  if (a === b) {
+    return true;
+  }
+  if (typeof a !== typeof b || a === null || b === null || typeof a !== "object") {
+    return false;
+  }
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+      return false;
+    }
+    return a.every((item, index) => structurallyEqual(item, b[index]));
+  }
+  const aRecord = a;
+  const bRecord = b;
+  const aKeys = Object.keys(aRecord);
+  const bKeys = Object.keys(bRecord);
+  if (aKeys.length !== bKeys.length) {
+    return false;
+  }
+  return aKeys.every((key) => Object.prototype.hasOwnProperty.call(bRecord, key) && structurallyEqual(aRecord[key], bRecord[key]));
+}
+__name(structurallyEqual, "structurallyEqual");
 function nestKeys(record, separator) {
   const result = {};
   for (const [key, value] of Object.entries(record)) {
@@ -632,14 +655,378 @@ AppConfigProviderGcpSecrets = _ts_decorate([
     Object
   ])
 ], AppConfigProviderGcpSecrets);
+
+// src/providers/app.config.provider.aws.secrets.ts
+import { Injectable as Injectable2 } from "injectkit";
+import { GetSecretValueCommand, SecretsManagerClient } from "@aws-sdk/client-secrets-manager";
+import { ServerkitError as ServerkitError2 } from "@maroonedsoftware/errors";
+function _ts_decorate2(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate2, "_ts_decorate");
+function _ts_metadata2(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata2, "_ts_metadata");
+var AppConfigProviderAwsSecrets = class {
+  static {
+    __name(this, "AppConfigProviderAwsSecrets");
+  }
+  region;
+  secretsManagerClient;
+  prefix;
+  /**
+  * Creates a new AppConfigProviderAwsSecrets instance.
+  *
+  * @param region - The AWS region where secrets are stored. If omitted, the region is
+  *   resolved from the standard AWS provider chain (e.g. `AWS_REGION`).
+  * @param prefix - A regex pattern or string to match secret references.
+  *   If a string is provided, it will be converted to a RegExp. The regex must have
+  *   at least one capture group that extracts the secret id.
+  *   Defaults to `/\$\{aws:(.+)\}/g` which matches `${aws:SECRET_ID}` patterns.
+  *
+  * @example
+  * ```typescript
+  * // Default pattern, region from the AWS provider chain
+  * const provider1 = new AppConfigProviderAwsSecrets();
+  *
+  * // Explicit region
+  * const provider2 = new AppConfigProviderAwsSecrets('us-east-1');
+  *
+  * // Custom regex pattern
+  * const provider3 = new AppConfigProviderAwsSecrets('us-east-1', /\$\{secret:([^}]+)\}/g);
+  * ```
+  */
+  constructor(region, prefix = /\$\{aws:(.+)\}/g) {
+    this.region = region;
+    this.secretsManagerClient = new SecretsManagerClient(region ? {
+      region
+    } : {});
+    this.prefix = typeof prefix === "string" ? new RegExp(prefix) : prefix;
+  }
+  /**
+  * Checks if this provider can parse the given value.
+  *
+  * @param value - The string value to check.
+  * @returns `true` if the value matches the provider's regex pattern, `false` otherwise.
+  */
+  canParse(value) {
+    this.prefix.lastIndex = 0;
+    return this.prefix.test(value);
+  }
+  /**
+  * Fetches a secret from AWS Secrets Manager.
+  *
+  * @param secretId - The id (name or ARN) of the secret to fetch.
+  * @returns A promise that resolves to the secret value.
+  * @throws {ServerkitError} When Secrets Manager rejects the access request (e.g. missing
+  *   secret, IAM denial, network failure). The original error is attached via `withCause`
+  *   and the failing `secretId` / `region` are recorded in `internalDetails`. Surfacing
+  *   the failure prevents callers booting with an empty password / API key.
+  * @internal
+  */
+  async getSecret(secretId) {
+    try {
+      const response = await this.secretsManagerClient.send(new GetSecretValueCommand({
+        SecretId: secretId
+      }));
+      if (response.SecretString !== void 0) {
+        return response.SecretString;
+      }
+      return response.SecretBinary ? Buffer.from(response.SecretBinary).toString("utf-8") : "";
+    } catch (error) {
+      throw new ServerkitError2(`AppConfigProviderAwsSecrets: failed to resolve secret "${secretId}" in region "${this.region ?? "default"}"`).withCause(error).withInternalDetails({
+        secretId,
+        region: this.region
+      });
+    }
+  }
+  /**
+  * Parses the value by replacing AWS secret references with actual secret values.
+  *
+  * The method:
+  * 1. Finds all matches of the regex pattern in the value
+  * 2. Fetches each secret from AWS Secrets Manager in parallel
+  * 3. Attempts to parse each result as JSON
+  * 4. Updates the configuration object with the final value
+  *
+  * @param value - The string value containing AWS secret references.
+  * @param meta - Metadata about the value's location in the configuration object.
+  * @returns A promise that resolves when all secrets have been fetched and the
+  *   transformation is complete.
+  * @throws {ServerkitError} Propagated from {@link getSecret} when any referenced secret
+  *   cannot be resolved. The build call site is expected to fail loud and stop boot.
+  *
+  * @example
+  * ```typescript
+  * // If AWS secret "API_KEY" contains "sk-abc123"
+  * // Value: "${aws:API_KEY}"
+  * // Result: "sk-abc123"
+  *
+  * // If AWS secret "CONFIG" contains '{"retries": 3}'
+  * // Value: "${aws:CONFIG}"
+  * // Result: { retries: 3 } (parsed as JSON object)
+  * ```
+  */
+  async parse(value, meta) {
+    const tasks = [];
+    const matches = value.matchAll(this.prefix);
+    for (const [, key] of matches) {
+      const task = this.getSecret(key).then((value2) => {
+        if (meta.arrayIndex !== void 0 && Array.isArray(meta.owner)) {
+          meta.owner[meta.arrayIndex] = tryParseJson(value2);
+        } else {
+          meta.owner[meta.propertyPath] = tryParseJson(value2);
+        }
+      });
+      tasks.push(task);
+    }
+    await Promise.all(tasks);
+  }
+};
+AppConfigProviderAwsSecrets = _ts_decorate2([
+  Injectable2(),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    String,
+    Object
+  ])
+], AppConfigProviderAwsSecrets);
+
+// src/options/app.config.options.ts
+import { Injectable as Injectable3 } from "injectkit";
+function _ts_decorate3(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate3, "_ts_decorate");
+var AppConfigOptions = class {
+  static {
+    __name(this, "AppConfigOptions");
+  }
+};
+AppConfigOptions = _ts_decorate3([
+  Injectable3()
+], AppConfigOptions);
+var AppConfigOptionsSnapshot = class {
+  static {
+    __name(this, "AppConfigOptionsSnapshot");
+  }
+};
+AppConfigOptionsSnapshot = _ts_decorate3([
+  Injectable3()
+], AppConfigOptionsSnapshot);
+var AppConfigOptionsMonitor = class {
+  static {
+    __name(this, "AppConfigOptionsMonitor");
+  }
+};
+AppConfigOptionsMonitor = _ts_decorate3([
+  Injectable3()
+], AppConfigOptionsMonitor);
+
+// src/options/app.config.store.ts
+var AppConfigStore = class {
+  static {
+    __name(this, "AppConfigStore");
+  }
+  builder;
+  config;
+  listeners = /* @__PURE__ */ new Set();
+  /**
+  * Creates a store seeded with an already-built config.
+  *
+  * @param builder - The builder used to rebuild the config on each `reload()`.
+  *   Pass the same builder instance that produced `initial`.
+  * @param initial - The config to serve until the first successful reload.
+  */
+  constructor(builder, initial) {
+    this.builder = builder;
+    this.config = initial;
+  }
+  /**
+  * The config currently in effect.
+  */
+  get current() {
+    return this.config;
+  }
+  /**
+  * Rebuilds the config and, on success, swaps it in and notifies subscribers.
+  *
+  * The new config is built fully before anything is swapped, so a failed
+  * rebuild (e.g. a secret that is momentarily unresolvable) leaves the current
+  * config untouched and the error is rethrown for the caller to log. This keeps
+  * a running process on its last-good values rather than crashing it — unlike
+  * boot, where a build failure is meant to stop startup.
+  *
+  * @returns A promise that resolves once the swap and notifications complete.
+  * @throws Propagates any error thrown while building the new config; the
+  *   current config is left in place.
+  */
+  async reload() {
+    const next = await this.builder.build();
+    this.config = next;
+    for (const listener of this.listeners) {
+      listener(next);
+    }
+  }
+  /**
+  * Subscribes to config swaps.
+  *
+  * @param listener - Called with the new config after each successful reload.
+  * @returns A function that removes the listener when called.
+  */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+};
+
+// src/options/app.config.options.monitor.ts
+var AppConfigOptionsMonitorImpl = class extends AppConfigOptionsMonitor {
+  static {
+    __name(this, "AppConfigOptionsMonitorImpl");
+  }
+  logger;
+  value;
+  listeners = /* @__PURE__ */ new Set();
+  /**
+  * @param initial - The value to serve until the first {@link AppConfigOptionsMonitorImpl.update}.
+  * @param logger - Used to report listener failures.
+  */
+  constructor(initial, logger) {
+    super(), this.logger = logger;
+    this.value = initial;
+  }
+  /**
+  * The latest value for this section.
+  */
+  get current() {
+    return this.value;
+  }
+  /**
+  * Subscribes to value changes. See {@link AppConfigOptionsMonitor.onChange}.
+  *
+  * @param listener - Called with the new value after each change.
+  * @returns A function that removes the listener when called.
+  */
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+  * Swaps in a new value and notifies listeners.
+  *
+  * A structurally-equal value is ignored so a secret re-fetched unchanged does
+  * not bounce live consumers. The value is swapped before listeners run, so a
+  * listener reading `current` sees the new value. Each listener is invoked in
+  * isolation: a throw or rejection is reported via the logger and does not stop
+  * the swap or the other listeners.
+  *
+  * @param next - The newly resolved value for this section.
+  */
+  update(next) {
+    if (structurallyEqual(this.value, next)) {
+      return;
+    }
+    this.value = next;
+    for (const listener of this.listeners) {
+      Promise.resolve().then(() => listener(next)).catch((err) => this.logger.error("AppConfigOptionsMonitor: onChange listener failed", err));
+    }
+  }
+};
+
+// src/options/app.config.options.manager.ts
+var AppConfigOptionsManager = class {
+  static {
+    __name(this, "AppConfigOptionsManager");
+  }
+  store;
+  logger;
+  monitors = /* @__PURE__ */ new Map();
+  /**
+  * @param store - The reloadable config store to track.
+  * @param logger - Passed to each monitor for listener-error reporting.
+  */
+  constructor(store, logger) {
+    this.store = store;
+    this.logger = logger;
+    this.store.subscribe((config) => {
+      for (const [key, monitor] of this.monitors) {
+        monitor.update(config.getAs(key));
+      }
+    });
+  }
+  /**
+  * Returns the live monitor for a section, creating it on first use.
+  *
+  * @param key - The configuration section key.
+  * @returns A monitor whose `current` tracks the latest value for `key`.
+  */
+  monitor(key) {
+    let monitor = this.monitors.get(key);
+    if (!monitor) {
+      monitor = new AppConfigOptionsMonitorImpl(this.store.current.getAs(key), this.logger);
+      this.monitors.set(key, monitor);
+    }
+    return monitor;
+  }
+  /**
+  * Returns a boot-snapshot accessor for a section.
+  *
+  * The value is read from the config current at call time and never updated —
+  * the static (`IOptions`) tier. Call this during registration so the captured
+  * value is the one in effect at container-build time.
+  *
+  * @param key - The configuration section key.
+  * @returns An {@link AppConfigOptions} holding the section's snapshot value.
+  */
+  options(key) {
+    return {
+      value: this.store.current.getAs(key)
+    };
+  }
+};
+
+// src/options/app.config.options.registration.ts
+function registerAppConfigOptions(registry, store, manager, key, tokens) {
+  if (tokens.options) {
+    registry.register(tokens.options).useInstance(manager.options(key));
+  }
+  if (tokens.monitor) {
+    registry.register(tokens.monitor).useInstance(manager.monitor(key));
+  }
+  if (tokens.snapshot) {
+    registry.register(tokens.snapshot).useFactory(() => ({
+      value: store.current.getAs(key)
+    })).asScoped();
+  }
+}
+__name(registerAppConfigOptions, "registerAppConfigOptions");
 export {
   AppConfig,
   AppConfigBuilder,
+  AppConfigOptions,
+  AppConfigOptionsManager,
+  AppConfigOptionsMonitor,
+  AppConfigOptionsSnapshot,
+  AppConfigProviderAwsSecrets,
   AppConfigProviderDotenv,
   AppConfigProviderGcpSecrets,
   AppConfigSourceDotenv,
   AppConfigSourceJson,
   AppConfigSourceYaml,
-  nestKeys
+  AppConfigStore,
+  nestKeys,
+  registerAppConfigOptions
 };
 //# sourceMappingURL=index.js.map