@maroonedsoftware/appconfig 1.0.0

package/dist/object.visitor.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Metadata about a value's location within an object structure.
+ */
+export type ObjectVisitorMeta = {
+    /** The full path to the value (e.g., "database.host" or "items[0]"). */
+    path: string;
+    /** The object that owns this property. */
+    owner: object;
+    /** The property name or array index path (e.g., "host" or "items[0]"). */
+    propertyPath: string;
+    /** The type of the property value. */
+    propertyType: 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function';
+    /** The array index if the value is in an array, undefined otherwise. */
+    arrayIndex?: number;
+};
+/**
+ * Callback function invoked for each primitive value found during object traversal.
+ *
+ * @param value - The primitive value found.
+ * @param meta - Metadata about the value's location in the object structure.
+ */
+export type ObjectVisitorCallback = (value: unknown, meta: ObjectVisitorMeta) => void;
+/**
+ * Traverses an object structure and invokes a callback for each primitive value found.
+ *
+ * The visitor recursively traverses objects and arrays, calling the callback for each
+ * primitive value (string, number, boolean, bigint) encountered. It skips functions,
+ * symbols, null, and undefined values.
+ *
+ * @param obj - The object to traverse. Can be any value.
+ * @param callback - The callback function to invoke for each primitive value.
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   database: { host: 'localhost', port: 5432 },
+ *   items: ['a', 'b', 'c']
+ * };
+ *
+ * objectVisitor(config, (value, meta) => {
+ *   console.log(`${meta.path} = ${value}`);
+ * });
+ * // Output:
+ * // database.host = localhost
+ * // database.port = 5432
+ * // items[0] = a
+ * // items[1] = b
+ * // items[2] = c
+ * ```
+ */
+export declare const objectVisitor: (obj: unknown, callback: ObjectVisitorCallback) => void;
+//# sourceMappingURL=object.visitor.d.ts.map

package/dist/object.visitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object.visitor.d.ts","sourceRoot":"","sources":["../src/object.visitor.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,YAAY,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;IAC1G,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAEtF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,OAAO,EAAE,UAAU,qBAAqB,KAAG,IA2C7E,CAAC"}

package/dist/providers/app.config.provider.dotenv.d.ts

@@ -0,0 +1,81 @@
+import { AppConfigProvider } from '../app.config.provider.js';
+import { ObjectVisitorMeta } from '../object.visitor.js';
+/**
+ * Provider that resolves environment variable references in configuration values.
+ *
+ * This provider matches string values using a regex pattern and replaces them with
+ * values from `process.env`. The default pattern matches `${env:KEY}` and extracts
+ * the key part to look up in the environment.
+ *
+ * After replacement, the result is attempted to be parsed as JSON. If parsing succeeds,
+ * the parsed value is used; otherwise, the string value is used.
+ *
+ * @example
+ * ```typescript
+ * // With default pattern /\$\{env:(.+)\}/g
+ * // Value: "${env:DATABASE_URL}"
+ * // Looks up: process.env.DATABASE_URL
+ *
+ * // Custom pattern
+ * const provider = new AppConfigProviderDotenv(/\$\{([^}]+)\}/g);
+ * // Value: "${DATABASE_URL}"
+ * // Looks up: process.env.DATABASE_URL
+ * ```
+ */
+export declare class AppConfigProviderDotenv implements AppConfigProvider {
+    private readonly prefix;
+    /**
+     * Creates a new AppConfigProviderDotenv instance.
+     *
+     * @param prefix - A regex pattern or string to match environment variable 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 environment variable key.
+     *   Defaults to `/\$\{env:(.+)\}/g` which matches `${env:KEY}` patterns.
+     *
+     * @example
+     * ```typescript
+     * // Default pattern
+     * const provider1 = new AppConfigProviderDotenv();
+     *
+     * // Custom regex pattern
+     * const provider2 = new AppConfigProviderDotenv(/\$\{([^}]+)\}/g);
+     *
+     * // String pattern (converted to RegExp)
+     * const provider3 = new AppConfigProviderDotenv('env:');
+     * ```
+     */
+    constructor(prefix?: string | RegExp);
+    /**
+     * 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: string): boolean;
+    /**
+     * Parses the value by replacing environment variable references with actual values.
+     *
+     * The method:
+     * 1. Finds all matches of the regex pattern in the value
+     * 2. Replaces each match with the corresponding value from `process.env`
+     * 3. Attempts to parse the result as JSON
+     * 4. Updates the configuration object with the final value
+     *
+     * @param value - The string value containing environment variable references.
+     * @param meta - Metadata about the value's location in the configuration object.
+     * @returns A promise that resolves when the transformation is complete.
+     *
+     * @example
+     * ```typescript
+     * // If process.env.DATABASE_URL = "postgres://localhost/db"
+     * // Value: "${env:DATABASE_URL}"
+     * // Result: "postgres://localhost/db"
+     *
+     * // If process.env.PORT = "3000"
+     * // Value: "${env:PORT}"
+     * // Result: 3000 (parsed as JSON number)
+     * ```
+     */
+    parse(value: string, meta: ObjectVisitorMeta): Promise<void>;
+}
+//# sourceMappingURL=app.config.provider.dotenv.d.ts.map

package/dist/providers/app.config.provider.dotenv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.config.provider.dotenv.d.ts","sourceRoot":"","sources":["../../src/providers/app.config.provider.dotenv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGzD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC;;;;;;;;;;;;;;;;;;;OAmBG;gBACS,MAAM,GAAE,MAAM,GAAG,MAA0B;IAIvD;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIhC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAcnE"}

package/dist/providers/app.config.provider.gcp.secrets.d.ts

@@ -0,0 +1,95 @@
+import { AppConfigProvider } from '../app.config.provider.js';
+import { ObjectVisitorMeta } from '../object.visitor.js';
+/**
+ * Provider that resolves Google Cloud Platform Secret Manager references in configuration values.
+ *
+ * This provider matches string values using a regex pattern and replaces them with
+ * secrets fetched from GCP Secret Manager. The default pattern matches `${gcp:SECRET_NAME}`
+ * and extracts the secret name to look up in Secret Manager.
+ *
+ * After retrieval, the secret value is attempted to be parsed as JSON. If parsing succeeds,
+ * the parsed value is used; otherwise, the string value is used.
+ *
+ * @remarks
+ * This provider requires valid GCP credentials to be configured. It uses the
+ * `@google-cloud/secret-manager` package and will use Application Default Credentials (ADC).
+ *
+ * @example
+ * ```typescript
+ * // With default pattern /\$\{gcp:(.+)\}/g
+ * // Value: "${gcp:DATABASE_PASSWORD}"
+ * // Fetches: projects/{projectId}/secrets/DATABASE_PASSWORD/versions/latest
+ *
+ * const config = await new AppConfigBuilder()
+ *   .addSource(new AppConfigSourceJson('./config.json'))
+ *   .addProvider(new AppConfigProviderGcpSecrets('my-gcp-project'))
+ *   .build();
+ * ```
+ */
+export declare class AppConfigProviderGcpSecrets implements AppConfigProvider {
+    private readonly projectId;
+    private readonly secretmanagerClient;
+    private readonly prefix;
+    /**
+     * Creates a new AppConfigProviderGcpSecrets instance.
+     *
+     * @param projectId - The GCP project ID where secrets are stored.
+     * @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 name.
+     *   Defaults to `/\$\{gcp:(.+)\}/g` which matches `${gcp:SECRET_NAME}` patterns.
+     *
+     * @example
+     * ```typescript
+     * // Default pattern
+     * const provider1 = new AppConfigProviderGcpSecrets('my-project');
+     *
+     * // Custom regex pattern
+     * const provider2 = new AppConfigProviderGcpSecrets('my-project', /\$\{secret:([^}]+)\}/g);
+     * ```
+     */
+    constructor(projectId: string, prefix?: string | RegExp);
+    /**
+     * 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: string): boolean;
+    /**
+     * Fetches a secret from GCP Secret Manager.
+     *
+     * @param secretId - The name of the secret to fetch.
+     * @returns A promise that resolves to the secret value, or an empty string if the secret
+     *   couldn't be fetched.
+     * @internal
+     */
+    private getSecret;
+    /**
+     * Parses the value by replacing GCP secret references with actual secret values.
+     *
+     * The method:
+     * 1. Finds all matches of the regex pattern in the value
+     * 2. Fetches each secret from GCP Secret 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 GCP 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.
+     *
+     * @example
+     * ```typescript
+     * // If GCP secret "API_KEY" contains "sk-abc123"
+     * // Value: "${gcp:API_KEY}"
+     * // Result: "sk-abc123"
+     *
+     * // If GCP secret "CONFIG" contains '{"retries": 3}'
+     * // Value: "${gcp:CONFIG}"
+     * // Result: { retries: 3 } (parsed as JSON object)
+     * ```
+     */
+    parse(value: string, meta: ObjectVisitorMeta): Promise<void>;
+}
+//# sourceMappingURL=app.config.provider.gcp.secrets.d.ts.map

package/dist/providers/app.config.provider.gcp.secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.config.provider.gcp.secrets.d.ts","sourceRoot":"","sources":["../../src/providers/app.config.provider.gcp.secrets.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAIzD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBACa,2BAA4B,YAAW,iBAAiB;IAuBjE,OAAO,CAAC,QAAQ,CAAC,SAAS;IAtB5B,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAoC;IACxE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC;;;;;;;;;;;;;;;;;OAiBG;gBAEgB,SAAS,EAAE,MAAM,EAClC,MAAM,GAAE,MAAM,GAAG,MAA0B;IAK7C;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIhC;;;;;;;OAOG;YACW,SAAS;IAYvB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAiBnE"}

package/dist/sources/app.config.source.dotenv.d.ts

@@ -0,0 +1,40 @@
+import { AppConfigSource } from '../app.config.source.js';
+/**
+ * Configuration source that loads environment variables from a `.env` file.
+ *
+ * This source uses the `dotenv` package to load environment variables from a `.env` file.
+ * If no file path is provided, it will look for a `.env` file in the current working directory.
+ * All values are strings as provided by the environment file.
+ *
+ * @example
+ * ```typescript
+ * // Load from default .env file
+ * const source1 = new AppConfigSourceDotenv();
+ * const config1 = await source1.load();
+ *
+ * // Load from custom path
+ * const source2 = new AppConfigSourceDotenv('./config/.env.local');
+ * const config2 = await source2.load();
+ * ```
+ */
+export declare class AppConfigSourceDotenv implements AppConfigSource {
+    private readonly filePath?;
+    /**
+     * Creates a new AppConfigSourceDotenv instance.
+     *
+     * @param filePath - Optional path to the `.env` file. If not provided, `dotenv` will
+     *   look for a `.env` file in the current working directory.
+     */
+    constructor(filePath?: string | undefined);
+    /**
+     * Loads environment variables from the `.env` file.
+     *
+     * Uses `dotenv.config()` to parse the file and load variables into the returned object.
+     * If the file doesn't exist or there's an error, an error will be thrown.
+     *
+     * @returns A promise that resolves to an object containing the parsed environment variables.
+     * @throws {Error} If there's an error reading or parsing the `.env` file.
+     */
+    load(): Promise<Record<string, unknown>>;
+}
+//# sourceMappingURL=app.config.source.dotenv.d.ts.map

package/dist/sources/app.config.source.dotenv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.config.source.dotenv.d.ts","sourceRoot":"","sources":["../../src/sources/app.config.source.dotenv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG1D;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IAO/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IANtC;;;;;OAKG;gBAC0B,QAAQ,CAAC,EAAE,MAAM,YAAA;IAE9C;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAO/C"}

package/dist/sources/app.config.source.json.d.ts

@@ -0,0 +1,47 @@
+import { AppConfigSource } from '../app.config.source.js';
+import { AppConfigSourceFileOptions } from '../app.config.source.options.js';
+/**
+ * Configuration source that loads configuration from a JSON file.
+ *
+ * This source reads a JSON file from the filesystem and parses it as a configuration object.
+ * By default, it will return an empty object if the file doesn't exist instead of throwing an error.
+ *
+ * @example
+ * ```typescript
+ * // Load from JSON file, ignore if missing
+ * const source1 = new AppConfigSourceJson('./config.json');
+ *
+ * // Load from JSON file, throw error if missing
+ * const source2 = new AppConfigSourceJson('./config.json', {
+ *   ignoreMissingFile: false
+ * });
+ *
+ * // Load with custom encoding
+ * const source3 = new AppConfigSourceJson('./config.json', {
+ *   encoding: 'utf16le'
+ * });
+ * ```
+ */
+export declare class AppConfigSourceJson implements AppConfigSource {
+    private readonly filePath;
+    private readonly options;
+    /**
+     * Creates a new AppConfigSourceJson instance.
+     *
+     * @param filePath - The path to the JSON file to load.
+     * @param options - Optional configuration for the source behavior.
+     */
+    constructor(filePath: string, options?: AppConfigSourceFileOptions);
+    /**
+     * Loads configuration from the JSON file.
+     *
+     * If the file doesn't exist and `ignoreMissingFile` is `true`, returns an empty object.
+     * Otherwise, reads and parses the JSON file.
+     *
+     * @returns A promise that resolves to the parsed JSON configuration object.
+     * @throws {Error} If the file doesn't exist and `ignoreMissingFile` is `false`,
+     *   or if the file contains invalid JSON.
+     */
+    load(): Promise<Record<string, unknown>>;
+}
+//# sourceMappingURL=app.config.source.json.d.ts.map

package/dist/sources/app.config.source.json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.config.source.json.d.ts","sourceRoot":"","sources":["../../src/sources/app.config.source.json.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IAUvD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAT3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAErD;;;;;OAKG;gBAEgB,QAAQ,EAAE,MAAM,EACjC,OAAO,CAAC,EAAE,0BAA0B;IAStC;;;;;;;;;OASG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAU/C"}

package/dist/sources/app.config.source.yaml.d.ts

@@ -0,0 +1,48 @@
+import { AppConfigSource } from '../app.config.source.js';
+import { AppConfigSourceFileOptions } from '../app.config.source.options.js';
+/**
+ * Configuration source that loads configuration from a YAML file.
+ *
+ * This source reads a YAML file from the filesystem and parses it as a configuration object.
+ * By default, it will return an empty object if the file doesn't exist instead of throwing an error.
+ * Supports both `.yaml` and `.yml` file extensions.
+ *
+ * @example
+ * ```typescript
+ * // Load from YAML file, ignore if missing
+ * const source1 = new AppConfigSourceYaml('./config.yaml');
+ *
+ * // Load from YAML file, throw error if missing
+ * const source2 = new AppConfigSourceYaml('./config.yaml', {
+ *   ignoreMissingFile: false
+ * });
+ *
+ * // Load with custom encoding
+ * const source3 = new AppConfigSourceYaml('./config.yaml', {
+ *   encoding: 'utf16le'
+ * });
+ * ```
+ */
+export declare class AppConfigSourceYaml implements AppConfigSource {
+    private readonly filePath;
+    private readonly options;
+    /**
+     * Creates a new AppConfigSourceYaml instance.
+     *
+     * @param filePath - The path to the YAML file to load.
+     * @param options - Optional configuration for the source behavior.
+     */
+    constructor(filePath: string, options?: AppConfigSourceFileOptions);
+    /**
+     * Loads configuration from the YAML file.
+     *
+     * If the file doesn't exist and `ignoreMissingFile` is `true`, returns an empty object.
+     * Otherwise, reads and parses the YAML file.
+     *
+     * @returns A promise that resolves to the parsed YAML configuration object.
+     * @throws {Error} If the file doesn't exist and `ignoreMissingFile` is `false`,
+     *   or if the file contains invalid YAML.
+     */
+    load(): Promise<Record<string, unknown>>;
+}
+//# sourceMappingURL=app.config.source.yaml.d.ts.map

package/dist/sources/app.config.source.yaml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.config.source.yaml.d.ts","sourceRoot":"","sources":["../../src/sources/app.config.source.yaml.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IAUvD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAT3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAErD;;;;;OAKG;gBAEgB,QAAQ,EAAE,MAAM,EACjC,OAAO,CAAC,EAAE,0BAA0B;IAStC;;;;;;;;;OASG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAU/C"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@maroonedsoftware/appconfig",
+  "version": "1.0.0",
+  "description": "A flexible, type-safe configuration management library with support for multiple sources and value transformation.",
+  "author": {
+    "name": "Marooned Software",
+    "url": "https://github.com/MaroonedSoftware/serverkit"
+  },
+  "bugs": {
+    "url": "https://github.com/MaroonedSoftware/serverkit/issues"
+  },
+  "homepage": "https://github.com/MaroonedSoftware/serverkit/packages/appconfig#readme",
+  "keywords": [
+    "backend",
+    "configuration",
+    "serverkit",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MaroonedSoftware/serverkit.git"
+  },
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "license": "MIT",
+  "files": [
+    "dist/**"
+  ],
+  "dependencies": {
+    "deepmerge-ts": "^7.1.5",
+    "dotenv": "^17.2.3",
+    "injectkit": "^1.0.3"
+  },
+  "devDependencies": {
+    "@google-cloud/secret-manager": "^6.1.1",
+    "yaml": "^2.8.2",
+    "@repo/config-eslint": "0.0.0",
+    "@repo/config-typescript": "0.0.0"
+  },
+  "peerDependencies": {
+    "@google-cloud/secret-manager": "^6.1.1",
+    "yaml": "^2.8.2"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --sourcemap --dts && tsc --emitDeclarationOnly --declaration",
+    "build:ci": "eslint --max-warnings=0 && pnpm run build",
+    "lint": "eslint --fix",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:ci": "vitest run --coverage"
+  }
+}