@galaxus/chabis-application-config 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Digitec Galaxus AG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,243 @@
+# @galaxus/chabis-application-config
+
+Type-safe application configuration for Node and TypeScript. Describe your config
+shape with a **zod** or **valibot** schema and get back one fully typed object,
+merged from layered YAML/TOML files and cloud secrets and validated against that
+schema
+
+It implements the Chabis `application-config` contract: the same file layering,
+merge semantics, and secret resolution as the Python `chabis-application-config`
+library, so a service keeps one config layout across stacks
+
+What you get:
+
+- Layered `settings`, `settings.{env}`, and `.secrets` files in YAML or TOML,
+  deep-merged in a fixed priority order
+- Secrets from Google Cloud Parameter Manager or Azure Key Vault, filling
+  placeholders left in those files
+- GPM versions resolve to the latest automatically, no version pin to bump
+- Environment-variable overrides derived from your schema, no magic prefix
+- A single typed object validated against your schema, or a thrown error
+
+## Install
+
+```sh
+pnpm add @galaxus/chabis-application-config
+```
+
+Bring a schema library as a peer dependency, zod or valibot:
+
+```sh
+pnpm add zod
+# or
+pnpm add valibot @valibot/to-json-schema
+```
+
+Google Cloud Parameter Manager is included out of the box. Azure Key Vault is
+optional, install its SDKs only if you use an `AzureKeyVault` provider instead:
+
+```sh
+pnpm add @azure/identity @azure/keyvault-secrets
+```
+
+## Usage
+
+```ts
+import { z } from "zod";
+import { loadConfig } from "@galaxus/chabis-application-config";
+
+const Schema = z.object({
+  LogLevel: 
+    z.string().default("INFO"),
+  Database: 
+    z.object({ Url: z.string() }),
+  Auth: 
+    z.object({ ClientId: z.string(), TenantId: z.string(), Secret: z.string() }),
+});
+
+export const config = await loadConfig(Schema, {
+  // directory holding the settings.*.{yaml,toml} files, defaults to process.cwd()
+  settingsDir: "./configs",
+  // selects settings.{env}.*, defaults to process.env.ENV ?? "dev"
+  env: process.env.ENV ?? "dev",
+});
+// config is fully typed: config.Auth.Secret, config.Database.Url
+```
+
+Typesafe:
+
+<img width="1268" height="635" alt="VSCode Typescript Tooltip" src="https://github.com/user-attachments/assets/0bc6b786-bd8c-48a3-aaf7-f9c31cda94a2" />
+
+
+`loadConfig` is async (secret fetches are async) and memoized by
+`(schema, settingsDir, env)`. Pass `{ fresh: true }` to bypass the cache, or call
+`resetConfigCache()`
+
+## Options
+
+`loadConfig(schema, opts)` takes an optional second argument:
+
+| Field | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `settingsDir` | `string` | `process.cwd()` | Directory holding the `settings.*.{yaml,toml}` files |
+| `env` | `string` | `process.env.ENV ?? "dev"` | Selects the `settings.{env}.*` layer |
+| `overrides` | `Record<string, unknown>` | `{}` | Highest-priority layer, deep-merged on top of everything |
+| `envNestingDelimiter` | `string` | `"__"` | Separator between schema leaf segments in env-var names |
+| `fresh` | `boolean` | `false` | Bypass the memoized result and force a fresh load |
+
+`overrides` and environment variables are two different layers (tiers 1 and 2)
+with two different shapes:
+
+- `overrides` is a **nested object** passed in code, `{ Database: { Url: "…" } }`.
+  It is the `process.env`-free way to force a value, e.g. in tests
+- Env vars are **flat, `__`-delimited strings**, `Database__Url=…`. See
+  [Environment-variable overrides](#environment-variable-overrides)
+
+## Files
+
+`loadConfig` reads, for a given `settingsDir` and `env`, any of these that exist:
+
+| Base name | Purpose |
+| --- | --- |
+| `settings.{toml,yaml}` | Base configuration (lowest priority) |
+| `settings.{env}.{toml,yaml}` | Environment-specific overrides |
+| `.secrets.{toml,yaml}` | Local secrets, highest-priority file layer |
+
+## How it resolves a value (priority, highest to lowest)
+
+The order is 1:1 with the Python `settings_customise_sources`:
+
+```
+1. opts.overrides
+2. env vars (schema leaf)    Database__Url -> { Database: { Url } }
+3. Azure Key Vault secrets   (when configured)
+4. Google Parameter Manager secrets
+5. .secrets.{toml,yaml}
+6. settings.{env}.{toml,yaml}
+7. settings.{toml,yaml}
+```
+
+Within the file tiers every TOML file outranks every YAML file
+(`*toml_sources` before `*yaml_sources`), and base-name order is
+`.secrets` > `settings.{env}` > `settings`, so the full file priority, high to low:
+
+```
+.secrets.toml > settings.{env}.toml > settings.toml >
+.secrets.yaml > settings.{env}.yaml > settings.yaml
+```
+
+The secret tiers (3 to 4) outrank every settings file (5 to 7), so a
+`"<Configured-in-GoogleParameterManager>"` placeholder written in
+`settings.dev.yaml` is replaced by the real secret payload
+
+### Merge semantics
+
+Applied lowest to highest (pydantic-settings `deep_update`):
+
+- Plain objects deep-merge recursively
+- Every other value, **including arrays**, is replaced wholesale by the
+  higher-priority layer, no array concatenation
+
+## Environment-variable overrides
+
+Selection is schema-driven: the loader walks your schema's leaf paths and looks up
+the env var named by joining each path with the nesting delimiter (`__`). A
+`Database.Url` leaf is overridden by `Database__Url`, mapped back to
+`{ Database: { Url } }`. Matching is case-sensitive against your verbatim keys, so
+there is no prefix and ambient vars like `PATH` never leak in
+
+```sh
+Database__Url=postgres://… node app.js
+```
+
+Values stay raw strings, coercion to number or bool is the schema's job
+(`z.coerce.number()`). Change the delimiter per call:
+
+```ts
+await loadConfig(Schema, { envNestingDelimiter: "." }); // Database.Url=…
+```
+
+Only leaves declared in the schema are overridable, and only zod and valibot
+schemas can be introspected. For any other vendor, env overrides quietly do not
+apply rather than failing the load
+
+`ENV` selects the environment and is **not** itself an override. To force a value
+from code without touching `process.env`, pass a nested object to
+[`overrides`](#options) instead (tier 1, outranks env vars)
+
+## The `Secrets` block
+
+Any settings file may carry a top-level `Secrets` array. It is metadata, stripped
+before validation, and drives the providers. If more than one file declares it the
+last in execution order wins (TOML before YAML); in practice exactly one file does
+
+```yaml
+Secrets:
+  - Provider: GoogleParameterManager
+    GCPProject: my-project-dev
+    GCPParameterName: my-app-config
+    # GCPParameterVersion: v5   # OPTIONAL, omit for auto-latest
+```
+
+- Auth via Application Default Credentials
+- Without `GCPParameterVersion` the provider lists all versions and picks the
+  newest `createTime`
+- The payload is parsed JSON-first, YAML-fallback, deep-merged whole at tier 4
+- Any failure (no versions, list/fetch error, unparseable payload) **throws**
+
+Azure:
+
+```yaml
+Secrets:
+  - Provider: AzureKeyVault
+    AzureKeyVault: my-vault
+    Mode: per-leaf        # default, one GET per schema leaf, Auth.Secret -> Auth--Secret
+    # Mode: single-blob   # one secret holding a JSON/YAML blob
+    # SecretName: config  # single-blob secret name (default "config")
+```
+
+- `per-leaf` (default): introspect the schema's leaf paths, GET one secret per leaf
+  with `.` → `--`, reassemble nested. Missing secrets are skipped (fall through to
+  a lower layer)
+- `single-blob`: GET one secret whose payload is a JSON/YAML blob (any vendor)
+- Auth via `DefaultAzureCredential`. SDKs are loaded only when Azure is configured
+
+`SecretFiles` is reserved, declaring it throws `NotImplementedProviderError`
+
+## Validation
+
+Validation runs through the [Standard Schema](https://standardschema.dev)
+interface, so zod, valibot, and arktype all work. On issues a
+`ConfigValidationError` lists each `path: message`, on success the typed
+`result.value` is returned
+
+Unknown-key handling is your schema's call: zod strips unknown keys unless you use
+`z.looseObject({...})` or `.loose()`, and any key you want kept must be declared or
+it is stripped
+
+Azure `per-leaf` mode reads your schema's leaf paths to derive secret names, which
+works on zod and valibot only (via their JSON Schema emitters). Any other vendor
+must use `Mode: single-blob`
+
+## Errors
+
+Everything surfaces fast as a thrown subclass of `ChabisConfigError`. The library
+logs nothing
+
+| Error | When |
+| --- | --- |
+| `SecretsConfigError` | Malformed `Secrets` block |
+| `ProviderError` | GPM/Azure auth/list/fetch/parse failure (wraps the cause) |
+| `IntrospectionError` | Azure `per-leaf` with a vendor that has no JSON-Schema emitter |
+| `ConfigValidationError` | Standard Schema validation issues |
+| `NotImplementedProviderError` | `SecretFiles` provider requested |
+| `PlaceholderError` | `assertNoPlaceholders` found an unresolved placeholder |
+
+`assertNoPlaceholders(config)` is an opt-in helper that throws if any leaf string
+still starts with `"<Configured-in-"`, guarding against a provider key that never
+matched a field
+
+## More
+
+See [`examples/zod`](examples/zod) and [`examples/valibot`](examples/valibot) for
+runnable setups

package/dist/index.d.ts

@@ -0,0 +1,297 @@
+/** The Standard Typed interface. This is a base type extended by other specs. */
+interface StandardTypedV1<Input = unknown, Output = Input> {
+    /** The Standard properties. */
+    readonly "~standard": StandardTypedV1.Props<Input, Output>;
+}
+declare namespace StandardTypedV1 {
+    /** The Standard Typed properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The Standard Typed types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Typed. */
+    type InferInput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+    /** Infers the output type of a Standard Typed. */
+    type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** A falsy value for `issues` indicates success. */
+        readonly issues?: undefined;
+    }
+    interface Options {
+        /** Explicit support for additional vendor-specific parameters, if needed. */
+        readonly libraryOptions?: Record<string, unknown> | undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard types interface. */
+    interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {
+    }
+    /** Infers the input type of a Standard. */
+    type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+    /** Infers the output type of a Standard. */
+    type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}
+
+/**
+ * Orchestration: gather every layer in priority order, deep-merge, validate
+ * against the Standard Schema, and memoize the result.
+ *
+ * Priority chain (HIGHEST to lowest), 1:1 with the Python source order:
+ *   overrides, env vars, Azure secrets, GPM secrets, settings files (TOML > YAML).
+ * The secrets tier outranks every settings file, which is why
+ * `"<Configured-in-…>"` placeholders get replaced by the real secret payload
+ */
+
+/**
+ * Recursively optional version of `T`: every nested object field may be
+ * omitted, so `overrides` can target a single leaf without restating its
+ * siblings. Arrays replace wholesale in the merge (decision #12), so their
+ * element type is kept intact rather than made partial
+ */
+type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+interface LoadConfigOptions<S extends StandardSchemaV1 = StandardSchemaV1> {
+    /** Directory containing the `settings.*.{yaml,toml}` files. Default `process.cwd()` */
+    settingsDir?: string;
+    /** Environment selecting the `settings.{env}.*` layer. Default `process.env.ENV ?? "dev"` */
+    env?: string;
+    /**
+     * Highest-priority overrides, deep-merged on top of everything (parity with
+     * `init_settings`). Typed as a deep partial of the schema's input since
+     * overrides feed the merge before validation and may target any subset
+     */
+    overrides?: DeepPartial<StandardSchemaV1.InferInput<S>>;
+    /** Delimiter separating schema leaf segments in env-var names. Default `"__"` (`Database__Url`) */
+    envNestingDelimiter?: string;
+    /** Skip the memoized singleton and force a fresh load. Default `false` */
+    fresh?: boolean;
+}
+/**
+ * Load, merge, validate, and return the typed config. Throws on any provider
+ * error, validation failure, or missing-required field. The override-independent
+ * base is memoized by `(schema, settingsDir, env)` unless `opts.fresh`, and
+ * `overrides` are applied on top of that cached base on every call
+ */
+declare function loadConfig<S extends StandardSchemaV1>(schema: S, opts?: LoadConfigOptions<S>): Promise<StandardSchemaV1.InferOutput<S>>;
+/** Clear the singleton cache, mainly for tests */
+declare function resetConfigCache(): void;
+
+/**
+ * Secret-provider contract plus the shared JSON-first-then-YAML payload parser
+ * used by GPM and Azure single-blob mode (parity with the Python lib and the
+ * current `instrumentation.ts`)
+ */
+/** A secret source that returns a nested object to deep-merge at the secrets tier */
+interface SecretProvider {
+    /** Resolve secrets into a nested plain object, already shaped like the config */
+    load(): Promise<Record<string, unknown>>;
+}
+
+/**
+ * Parser for the top-level `Secrets` block. This is metadata, not part of the
+ * caller's config schema, so a tiny hand-written validator mirroring the Python
+ * `SecretsConfig` model handles it, never the consumer's schema
+ */
+interface GpmSecretsConfig {
+    Provider: "GoogleParameterManager";
+    GCPProject: string;
+    GCPParameterName: string;
+    /** Omit for auto-latest resolution */
+    GCPParameterVersion?: string;
+}
+interface AzureSecretsConfig {
+    Provider: "AzureKeyVault";
+    AzureKeyVault: string;
+    /** Defaults to `per-leaf` (Python parity). `single-blob` works with any vendor */
+    Mode?: "per-leaf" | "single-blob";
+    /** Secret holding the whole config blob in `single-blob` mode, default `config` */
+    SecretName?: string;
+}
+interface SecretFilesConfig {
+    Provider: "SecretFiles";
+    SecretFilePath: string;
+}
+type SecretsConfig = GpmSecretsConfig | AzureSecretsConfig | SecretFilesConfig;
+
+/**
+ * Google Parameter Manager provider, mirrors `DgGoogleParameterSecretsSource`.
+ *
+ * When `GCPParameterVersion` is omitted it lists all versions and picks the
+ * newest by `createTime`, replacing the hardcoded `/versions/v5` of the current
+ * `instrumentation.ts`. Any failure throws (decision #10), GPM errors are never
+ * swallowed
+ */
+
+/** Minimal slice of the `@google-cloud/parametermanager` client we rely on */
+interface ParameterVersion {
+    name?: string | null;
+    createTime?: {
+        seconds?: number | string | null;
+        nanos?: number | null;
+    } | null;
+    payload?: {
+        data?: Uint8Array | string | null;
+    } | null;
+}
+interface ParameterManagerClient {
+    parameterPath(project: string, location: string, parameter: string): string;
+    listParameterVersions(request: {
+        parent: string;
+    }): Promise<[ParameterVersion[], unknown, unknown]>;
+    getParameterVersion(request: {
+        name: string;
+    }): Promise<[ParameterVersion, unknown, unknown]>;
+}
+/** Factory for the SDK client, overridable so tests can inject a fake */
+type GpmClientFactory = () => Promise<ParameterManagerClient>;
+declare class GoogleParameterManagerProvider implements SecretProvider {
+    private readonly config;
+    private readonly clientFactory;
+    constructor(config: GpmSecretsConfig, clientFactory?: GpmClientFactory);
+    load(): Promise<Record<string, unknown>>;
+    private resolveLatestVersion;
+}
+
+/**
+ * Azure Key Vault provider, mirrors `DgAzureKeyvaultSecretsSource`.
+ *
+ * `per-leaf` (default, Python parity): introspect the schema to enumerate leaf
+ * paths, then one GET per leaf mapping `.` to `--` (`Auth.Secret` becomes
+ * `Auth--Secret`), reassembling a nested object. Missing secrets are skipped so
+ * the field falls through to a lower-priority layer.
+ *
+ * `single-blob`: fetch one secret whose payload is JSON/YAML (same shape as GPM)
+ * and deep-merge it. No introspection, works with any vendor.
+ *
+ * The Azure SDKs are dynamically imported so GPM-only consumers never load them
+ */
+
+/** Minimal slice of `@azure/keyvault-secrets`' `SecretClient` */
+interface AzureSecretClient {
+    getSecret(name: string): Promise<{
+        value?: string | null;
+    }>;
+}
+/** Factory for the vault client, overridable so tests can inject a fake */
+type AzureClientFactory = (vaultName: string) => Promise<AzureSecretClient>;
+declare class AzureKeyVaultProvider implements SecretProvider {
+    private readonly config;
+    private readonly schema;
+    private readonly clientFactory;
+    constructor(config: AzureSecretsConfig, schema: StandardSchemaV1, clientFactory?: AzureClientFactory);
+    load(): Promise<Record<string, unknown>>;
+    private buildClient;
+    private loadPerLeaf;
+    private loadSingleBlob;
+    /** GET one secret, return undefined when missing (parity: swallow + skip) */
+    private tryGetSecret;
+}
+
+/**
+ * Error hierarchy. Every failure mode throws (decision #10) so a misconfigured
+ * deploy fails fast at boot instead of running on placeholder strings where
+ * real secrets should be
+ */
+/** Base class for every error this library throws */
+declare class ChabisConfigError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Malformed `Secrets` block: missing required provider fields, unknown provider */
+declare class SecretsConfigError extends ChabisConfigError {
+}
+/** A secret provider (GPM/Azure) failed to authenticate, list, fetch, or parse */
+declare class ProviderError extends ChabisConfigError {
+}
+/**
+ * Azure `per-leaf` mode requested with a schema whose vendor has no registered
+ * JSON-Schema introspector, so leaf paths can't be enumerated
+ */
+declare class IntrospectionError extends ChabisConfigError {
+}
+/** The merged config failed Standard Schema validation */
+declare class ConfigValidationError extends ChabisConfigError {
+}
+/** Provider declared in the spec but not yet implemented (`SecretFiles`) */
+declare class NotImplementedProviderError extends ChabisConfigError {
+}
+
+/**
+ * Opt-in placeholder guard (SPEC §10). A GPM/Azure key that matched no field
+ * path leaves its `"<Configured-in-…>"` placeholder untouched. Not run
+ * automatically: the consumer calls it after `loadConfig` if they want the check
+ */
+
+/** Thrown when an unresolved placeholder remains */
+declare class PlaceholderError extends ChabisConfigError {
+}
+/** Throw if any leaf string in `obj` still starts with `marker`, meaning a secret never resolved */
+declare function assertNoPlaceholders(obj: unknown, marker?: string): void;
+
+/**
+ * Vendor-detected JSON-Schema introspection (decision #9 / SPEC §9a).
+ *
+ * Standard Schema's `validate` does not expose fields, but the schema library
+ * can: zod v4 and valibot each emit a JSON Schema whose `properties` we recurse
+ * to recover the same leaf paths the Python Azure provider gets from
+ * `model_cls.model_fields`. The right emitter is picked from
+ * `schema["~standard"].vendor`, not by feature-detecting a method, because
+ * `z.toJSONSchema(schema)` and valibot's `toJsonSchema(schema)` are module-level
+ * functions, not methods on the schema object
+ */
+
+/** Vendors that can be introspected for Azure `per-leaf` mode */
+declare function supportedIntrospectionVendors(): string[];
+/**
+ * Enumerate every leaf path of a schema (`[["Auth","Secret"], ["Database","Url"], …]`)
+ * via its vendor's JSON-Schema emitter. Throws `IntrospectionError` when the
+ * vendor has no registered introspector
+ */
+declare function introspectLeafPaths(schema: StandardSchemaV1): Promise<string[][]>;
+
+export { AzureKeyVaultProvider, type AzureSecretsConfig, ChabisConfigError, ConfigValidationError, type DeepPartial, GoogleParameterManagerProvider, type GpmSecretsConfig, IntrospectionError, type LoadConfigOptions, NotImplementedProviderError, PlaceholderError, ProviderError, type SecretFilesConfig, type SecretProvider, type SecretsConfig, SecretsConfigError, assertNoPlaceholders, introspectLeafPaths, loadConfig, resetConfigCache, supportedIntrospectionVendors };