@pawells/config-provider-json 3.0.0-rc1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phillip Aaron Wells
+
+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,290 @@
+# @pawells/config-provider-json
+
+[![CI](https://github.com/PhillipAWells/config/actions/workflows/ci.yml/badge.svg)](https://github.com/PhillipAWells/config/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@pawells/config-provider-json)](https://www.npmjs.com/package/@pawells/config-provider-json)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+
+## Description
+
+`@pawells/config-provider-json` is an async configuration provider for `@pawells/config` that reads values from a JSON file and writes configuration snapshots or templates back to disk.
+
+The file must contain a JSON object at the top level. Nested objects are flattened one level deep using `_` as the separator, so a key registered as `KEYCLOAK_HOST` is found at `{ "KEYCLOAK": { "HOST": "..." } }`. Top-level non-object values are kept at their own key unchanged. Native JSON types (numbers, booleans, arrays, `null`) are passed directly to Zod schema validation without string pre-processing.
+
+The provider enforces a 10 MB file-size limit and rejects symlinks and path-traversal sequences (`..`) for security.
+
+See the [workspace README](../../README.md) for an end-to-end quick start. See [CHANGELOG.md](../../CHANGELOG.md) for version history.
+
+## Requirements
+
+- Node.js `>=22.0.0`
+- `@pawells/config` (peer dependency, installed as a direct dependency via `workspace:*` in the monorepo)
+
+## Installation
+
+```sh
+yarn add @pawells/config-provider-json @pawells/config
+```
+
+All packages are ESM-only (`"type": "module"`).
+
+## Quick Start
+
+```typescript
+import { ConfigManager, RegisterConfigSchema, Secret } from '@pawells/config';
+import { ConfigJSONProvider } from '@pawells/config-provider-json';
+import { z } from 'zod';
+
+// Register providers BEFORE importing any schema modules.
+const jsonProvider = await ConfigJSONProvider.Register({
+    name: 'json',
+    path: './config.json',
+    required: false  // OK if the file does not exist yet
+});
+
+// config.json: { "APP": { "HOST": "localhost", "PORT": 3000 } }
+// Flattens to: APP_HOST='localhost', APP_PORT=3000
+
+const AppConfig = RegisterConfigSchema('App', z.object({
+    HOST: z.string().min(1).default('localhost'),
+    PORT: z.coerce.number().int().positive().default(3000),
+    SECRET_KEY: Secret(z.string().min(32)).default(''),
+}));
+
+const host = AppConfig.Get('HOST'); // string
+const port = AppConfig.Get('PORT'); // number
+
+// Generate config.example.json — defaults; secrets written as null.
+await ConfigManager.Save(jsonProvider, { path: './config.example.json' });
+
+// Snapshot current runtime values.
+await ConfigManager.Save(jsonProvider, {
+    path: './config.snapshot.json',
+    useCurrentValues: true
+});
+```
+
+### JSON file format
+
+Nested objects are flattened one level deep:
+
+```json
+{
+    "APP": {
+        "HOST": "localhost",
+        "PORT": 3000,
+        "DEBUG": false
+    },
+    "KEYCLOAK": {
+        "HOST": "keycloak.example.com",
+        "PORT": 8080
+    }
+}
+```
+
+Produces the configuration keys: `APP_HOST`, `APP_PORT`, `APP_DEBUG`, `KEYCLOAK_HOST`, `KEYCLOAK_PORT`.
+
+Only one level of nesting is flattened. Deeper objects are skipped. Top-level non-object values (strings, numbers, booleans, arrays, `null`) are kept at their own key:
+
+```json
+{ "TOP_LEVEL_KEY": "value" }
+```
+
+Produces `TOP_LEVEL_KEY='value'`.
+
+## API Reference
+
+### `ConfigJSONProvider`
+
+An async configuration provider that extends `ConfigProvider` from `@pawells/config`.
+
+#### `static Register(options?)`
+
+Convenience factory: creates a `ConfigJSONProvider` instance, registers it with `ConfigManager`, and returns it.
+
+```typescript
+static async Register(
+    options?: Partial<TConfigJSONProviderOptions>
+): Promise<ConfigJSONProvider>
+```
+
+Unspecified options use schema defaults (`path: <cwd>/config.json`, `required: false`). Note: `name` has no default and must be supplied.
+
+```typescript
+// Register with a specific path
+const provider = await ConfigJSONProvider.Register({
+    name: 'json',
+    path: './config.json',
+    required: false
+});
+
+// Register an optional local override file
+const localProvider = await ConfigJSONProvider.Register({
+    name: 'json-local',
+    path: './config.local.json',
+    required: false
+});
+```
+
+#### Constructor
+
+```typescript
+new ConfigJSONProvider(options: TConfigJSONProviderOptions)
+```
+
+After constructing, pass the instance to `ConfigManager.RegisterProvider` manually if you need the instance before registration:
+
+```typescript
+import { ConfigManager } from '@pawells/config';
+import { ConfigJSONProvider } from '@pawells/config-provider-json';
+
+const provider = new ConfigJSONProvider({
+    name: 'json',
+    path: './config.json',
+    required: true
+});
+await ConfigManager.RegisterProvider(provider);
+```
+
+**Throws** `ConfigError` if `options` fail schema validation (e.g. the path contains `..`).
+
+#### `Load()`
+
+```typescript
+async Load(): Promise<Record<string, unknown>>
+```
+
+Reads and flattens the JSON configuration file:
+
+1. The parent directory of `options.path` is canonicalized via `fs.realpath` to detect symlinked ancestor directories.
+2. The file is opened with `O_NOFOLLOW` to atomically reject a symlinked final path component.
+3. Content is read and the size is checked against the 10 MB limit.
+4. The JSON is parsed; malformed JSON throws `ConfigError`.
+5. Top-level properties are flattened one level deep (see format above).
+6. Prototype-pollution keys (`__proto__`, `constructor`, `prototype`) are silently skipped.
+
+If the file is absent (`ENOENT`) and `required` is `false`, returns `{}`. If `required` is `true`, throws `ConfigError`.
+
+```typescript
+// config.json: { "APP": { "HOST": "localhost", "PORT": 3000, "DEBUG": false } }
+const values = await provider.Load();
+// → { APP_HOST: 'localhost', APP_PORT: 3000, APP_DEBUG: false }
+```
+
+**Throws:**
+- `ConfigError` — The file is a symlink (final component or parent directory).
+- `ConfigError` — The file cannot be read and `required` is `true`.
+- `ConfigError` — The file exceeds 10 MB.
+- `ConfigError` — The file content is not valid JSON.
+
+#### `Save(entries, options?)`
+
+```typescript
+async Save(
+    entries: readonly ConfigSaveEntry[],
+    options?: TConfigJSONProviderSaveOptions
+): Promise<void>
+```
+
+Writes configuration entries to a nested JSON file. Call via `ConfigManager.Save` rather than directly.
+
+**Template mode** (`useCurrentValues: false`, the default):
+- Each entry is written using its registered default value.
+- Entries where `entry.isSecret` is `true` are written as `null`, indicating that a value is required but intentionally absent.
+- This is suitable for generating `config.example.json` files safe to commit.
+
+**Current-values mode** (`useCurrentValues: true`):
+- All entries including secrets are written with their live resolved values.
+
+The output structure mirrors the input structure that `Load()` flattens: entries with a section (registered via a namespace) are nested under their section key. Entries without a section are written at the top level.
+
+Output is pretty-printed with tab indentation.
+
+**Options:**
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `path` | `string` (optional) | `this.options.path` | Output file path; overrides the constructor path if provided. `..` sequences are rejected. |
+| `useCurrentValues` | `boolean` (optional) | `false` | `false` = registered defaults, secrets as `null`; `true` = live resolved values. |
+
+---
+
+### Options types
+
+#### `TConfigJSONProviderOptions`
+
+```typescript
+type TConfigJSONProviderOptions = {
+    name: string       // Required; unique identifier for diagnostics
+    path: string       // Default: <cwd>/config.json; '..' sequences are rejected
+    required: boolean  // Default: false; when true, missing file throws ConfigError
+}
+```
+
+Validated by `CONFIG_JSON_PROVIDER_OPTIONS_SCHEMA`.
+
+#### `TConfigJSONProviderSaveOptions`
+
+```typescript
+type TConfigJSONProviderSaveOptions = {
+    path?: string             // Overrides constructor path if provided; '..' sequences are rejected
+    useCurrentValues?: boolean  // Default: false
+}
+```
+
+Validated by `CONFIG_JSON_PROVIDER_SAVE_OPTIONS_SCHEMA`.
+
+---
+
+### Assertion and validation utilities
+
+| Export | Description |
+|---|---|
+| `CONFIG_JSON_PROVIDER_OPTIONS_SCHEMA` | Zod schema for `TConfigJSONProviderOptions` |
+| `AssertConfigJSONProviderOptions(options)` | Asserts conformance; throws `ZodError` otherwise |
+| `ValidateConfigJSONProviderOptions(options)` | Returns `true` if valid; `false` otherwise |
+| `CONFIG_JSON_PROVIDER_SAVE_OPTIONS_SCHEMA` | Zod schema for `TConfigJSONProviderSaveOptions` |
+| `AssertConfigJSONProviderSaveOptions(options)` | Asserts conformance; throws `ZodError` otherwise |
+| `ValidateConfigJSONProviderSaveOptions(options)` | Returns `true` if valid; `false` otherwise |
+| `CONFIG_JSON_PROVIDER_PATH_SCHEMA` | Zod schema for an individual path value |
+
+---
+
+### Error handling
+
+```typescript
+import { ConfigError } from '@pawells/config';
+import { ConfigJSONProvider } from '@pawells/config-provider-json';
+
+try {
+    const provider = new ConfigJSONProvider({
+        name: 'json',
+        path: './config.json',
+        required: true
+    });
+    await ConfigManager.RegisterProvider(provider);
+} catch (error) {
+    if (error instanceof ConfigError) {
+        // Symlink detected, path traversal, JSON parse failure, file not found (required),
+        // or size limit exceeded
+        console.error('Configuration error:', error.message);
+    } else {
+        // File system permission error or other I/O error
+        console.error('I/O error:', error);
+    }
+}
+```
+
+---
+
+### Security
+
+- **Symlink rejection** — The final path component is opened with `O_NOFOLLOW`. Parent directories are canonicalized via `fs.realpath`. Either form of symlink throws `ConfigError`.
+- **Path-traversal protection** — Any path containing `..` is rejected by the options schema at construction time and at save time.
+- **Prototype-pollution protection** — Keys `__proto__`, `constructor`, and `prototype` are silently skipped in both `Load()` and `Save()`.
+- **Size limit** — Files larger than 10 MB (byte-accurate) throw `ConfigError` before parsing.
+- **No string coercion** — Native JSON types are passed directly to Zod; no implicit string-to-number conversion occurs.
+
+## License
+
+MIT — See [LICENSE](../../LICENSE) for details.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './json-provider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './json-provider.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/dist/json-provider.d.ts

@@ -0,0 +1,212 @@
+import { z } from 'zod/v4';
+import { ConfigProvider, type ConfigSaveEntry } from '@pawells/config';
+/**
+ * Zod schema for validating JSON provider file paths.
+ *
+ * Enforces non-empty string with no path traversal sequences ("..").
+ * Defaults to `./config.json` in the current working directory.
+ */
+export declare const CONFIG_JSON_PROVIDER_PATH_SCHEMA: z.ZodDefault<z.ZodString>;
+/**
+ * Zod schema for validating ConfigJSONProvider constructor options.
+ *
+ * Extends the base provider options with path and required flag.
+ */
+export declare const CONFIG_JSON_PROVIDER_OPTIONS_SCHEMA: z.ZodObject<{
+    name: z.ZodString;
+    path: z.ZodDefault<z.ZodString>;
+    required: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+/**
+ * Type-safe representation of ConfigJSONProvider options.
+ */
+export type TConfigJSONProviderOptions = z.infer<typeof CONFIG_JSON_PROVIDER_OPTIONS_SCHEMA>;
+/**
+ * Assert that a value conforms to TConfigJSONProviderOptions.
+ *
+ * @param options - The value to validate.
+ * @throws {ZodError} If validation fails.
+ */
+export declare function AssertConfigJSONProviderOptions(options: unknown): asserts options is TConfigJSONProviderOptions;
+/**
+ * Validate whether a value conforms to TConfigJSONProviderOptions.
+ *
+ * @param options - The value to validate.
+ * @returns `true` if validation succeeds; `false` otherwise.
+ */
+export declare function ValidateConfigJSONProviderOptions(options: unknown): boolean;
+/**
+ * Zod schema for validating ConfigJSONProvider Save options.
+ *
+ * Allows optional path override and value-selection mode.
+ */
+export declare const CONFIG_JSON_PROVIDER_SAVE_OPTIONS_SCHEMA: z.ZodObject<{
+    useCurrentValues: z.ZodOptional<z.ZodBoolean>;
+    path: z.ZodOptional<z.ZodDefault<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Type-safe representation of ConfigJSONProvider Save options.
+ */
+export type TConfigJSONProviderSaveOptions = z.infer<typeof CONFIG_JSON_PROVIDER_SAVE_OPTIONS_SCHEMA>;
+/**
+ * Assert that a value conforms to TConfigJSONProviderSaveOptions.
+ *
+ * @param options - The value to validate.
+ * @throws {ZodError} If validation fails.
+ */
+export declare function AssertConfigJSONProviderSaveOptions(options: unknown): asserts options is TConfigJSONProviderSaveOptions;
+/**
+ * Validate whether a value conforms to TConfigJSONProviderSaveOptions.
+ *
+ * @param options - The value to validate.
+ * @returns `true` if validation succeeds; `false` otherwise.
+ */
+export declare function ValidateConfigJSONProviderSaveOptions(options: unknown): boolean;
+/**
+ * Configuration provider that reads values from a JSON file.
+ *
+ * The file must contain a JSON object at the top level. Nested objects are
+ * flattened using the pattern `SECTION_FIELD` so that a config registered
+ * as `KEYCLOAK_HOST` is found under `{ "KEYCLOAK": { "HOST": "..." } }`.
+ * Top-level non-object values are kept under their own key unchanged.
+ * Only one level of nesting is flattened; deeper nesting is skipped.
+ *
+ * Native JSON types (numbers, booleans, arrays, `null`) are passed directly
+ * to Zod schema validation without any string pre-processing.
+ *
+ * @example
+ * ```typescript
+ * // config.json: { "KEYCLOAK": { "HOST": "localhost", "PORT": 8080 } }
+ * const provider = new ConfigJSONProvider({
+ *   name: 'json',
+ *   path: './config.json',
+ *   required: true
+ * });
+ * await ConfigManager.RegisterProvider(provider);
+ * // Registers: KEYCLOAK_HOST='localhost', KEYCLOAK_PORT=8080
+ *
+ * // Optional file — no throw if missing
+ * const optProvider = new ConfigJSONProvider({
+ *   name: 'json-local',
+ *   path: './config.local.json',
+ *   required: false
+ * });
+ * await ConfigManager.RegisterProvider(optProvider);
+ * ```
+ */
+export declare class ConfigJSONProvider extends ConfigProvider<TConfigJSONProviderOptions, Record<string, unknown>, TConfigJSONProviderSaveOptions> {
+    /**
+     * Construct a JSON configuration provider.
+     *
+     * @param options - Provider configuration options.
+     * @param options.name - Unique name identifying this provider instance (used for diagnostics).
+     * @param options.path - Path to the JSON configuration file; defaults to `./config.json`.
+     * @param options.required - When `true` (default `false`), a missing or unreadable file throws an error; when `false`, returns `{}`.
+     * @throws {ConfigError} If options fail schema validation or path contains path traversal sequences (..).
+     */
+    constructor(options: TConfigJSONProviderOptions);
+    /**
+     * Load and flatten the JSON configuration file asynchronously.
+     *
+     * Reads the file at `options.path` asynchronously, parses it as JSON, and flattens
+     * nested objects (one level deep) into fully-qualified keys using `_` as the separator.
+     * If the file cannot be read and `options.required` is `false`, returns `{}`.
+     *
+     * Symlink paths are not permitted and will throw a ConfigError. Both the final path
+     * component and parent directories are validated: the final component is checked via
+     * O_NOFOLLOW, and parent directories are canonicalized via realpath to reject symlinked
+     * ancestor directories.
+     *
+     * Input size (and thus practical nesting depth) is bounded by the existing 10 MB file-size limit.
+     *
+     * @returns A flat record of fully-qualified config key names to their native-typed values.
+     * @throws {ConfigError} If the file is a symlink (final component or parent directory).
+     * @throws {ConfigError} If the file cannot be read and `options.required` is `true`.
+     * @throws {ConfigError} When the config file exceeds 10MB.
+     * @throws {ConfigError} If the loaded JSON fails to parse.
+     *
+     * @example
+     * ```typescript
+     * // config.json:
+     * // { "APP": { "HOST": "localhost", "PORT": 3000, "DEBUG": false } }
+     * const provider = new ConfigJSONProvider({
+     *   name: 'json',
+     *   path: './config.json',
+     *   required: true
+     * });
+     * const values = await provider.Load();
+     * // → { APP_HOST: 'localhost', APP_PORT: 3000, APP_DEBUG: false }
+     * ```
+     */
+    Load(): Promise<Record<string, unknown>>;
+    /**
+     * Save configuration values to a nested JSON file asynchronously.
+     *
+     * Entries that belong to a registered namespace (i.e. `entry.section` is
+     * non-empty) are grouped under their section key, reproducing the nested
+     * structure that {@link Load} flattens on read:
+     * `KEYCLOAK_HOST` → `{ "KEYCLOAK": { "HOST": "..." } }`.
+     *
+     * Entries with no section (registered directly with {@link ConfigManager.Register}
+     * rather than via {@link ConfigManager.RegisterNamespace}) are written as top-level keys.
+     *
+     * In template mode (`useCurrentValues: false`, the default), secret fields
+     * (`entry.isSecret === true`) are written as `null`, clearly indicating that
+     * a value is required but intentionally absent — suitable for committed
+     * `config.example.json` template files.
+     *
+     * In current-values mode (`useCurrentValues: true`), all values including
+     * secrets are written as-is, capturing the current live state.
+     *
+     * The output file is pretty-printed with tab indentation.
+     *
+     * @param entries - All registered config entries supplied by {@link ConfigManager.Save}.
+     * @param options - Save options including output file path and value-selection mode.
+     * @param options.path - Output file path; defaults to `this.options.path` if not provided.
+     * @param options.useCurrentValues - When `true`, write current live values; when `false` (default), write defaults and `null` for secrets.
+     * @throws {ConfigError} If options validation fails, JSON serialization fails, or file write fails.
+     *
+     * @example
+     * ```typescript
+     * // Generate config.example.json (secrets as null, for committing)
+     * const provider = new ConfigJSONProvider({
+     *   name: 'json',
+     *   path: './config.json'
+     * });
+     * await provider.Save(entries, { path: './config.example.json' });
+     *
+     * // Snapshot current runtime config (with live secrets)
+     * await provider.Save(entries, {
+     *   path: './config.snapshot.json',
+     *   useCurrentValues: true
+     * });
+     * ```
+     */
+    Save(entries: readonly ConfigSaveEntry[], options?: TConfigJSONProviderSaveOptions): Promise<void>;
+    /**
+     * Create and register a ConfigJSONProvider with {@link ConfigManager}.
+     *
+     * A convenience factory that combines construction and registration.
+     * The provider is immediately registered with the global ConfigManager
+     * and returned for optional use.
+     *
+     * @param options - Partial provider options; missing fields use schema defaults.
+     * @returns A promise that resolves to the created and registered provider instance.
+     * @throws {ZodError} If options fail schema validation.
+     *
+     * @example
+     * ```typescript
+     * // Register with defaults (./config.json, required: false)
+     * await ConfigJSONProvider.Register({ name: 'json' });
+     *
+     * // Register with custom path
+     * const provider = await ConfigJSONProvider.Register({
+     *   name: 'json-local',
+     *   path: './config.local.json',
+     *   required: false
+     * });
+     * ```
+     */
+    static Register(options?: Partial<TConfigJSONProviderOptions>): Promise<ConfigJSONProvider>;
+}
+//# sourceMappingURL=json-provider.d.ts.map

package/dist/json-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-provider.d.ts","sourceRoot":"","sources":["../src/json-provider.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAC3B,OAAO,EAAmG,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAUxK;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,2BAI1C,CAAC;AAEJ;;;;GAIG;AACH,eAAO,MAAM,mCAAmC;;;;iBAG9C,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAE7F;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,0BAA0B,CAE/G;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAQ3E;AAED;;;;GAIG;AACH,eAAO,MAAM,wCAAwC;;;iBAEnD,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wCAAwC,CAAC,CAAC;AAEtG;;;;;GAKG;AACH,wBAAgB,mCAAmC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,8BAA8B,CAEvH;AAED;;;;;GAKG;AACH,wBAAgB,qCAAqC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAQ/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,kBAAmB,SAAQ,cAAc,CACrD,0BAA0B,EAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvB,8BAA8B,CAC9B;IACA;;;;;;;;OAQG;gBACS,OAAO,EAAE,0BAA0B;IAK/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACU,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAsFrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACU,IAAI,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,EAAE,OAAO,CAAC,EAAE,8BAA8B,GAAG,OAAO,CAAC,IAAI,CAAC;IAkD/G;;;;;;;;;;;;;;;;;;;;;;;OAuBG;WACiB,QAAQ,CAAC,OAAO,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAK5G"}

package/dist/json-provider.js

@@ -0,0 +1,357 @@
+import * as fs from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import * as path from 'node:path';
+import { z } from 'zod/v4';
+import { CONFIG_PROVIDER_OPTIONS_SCHEMA, CONFIG_PROVIDER_SAVE_OPTIONS_SCHEMA, ConfigError, ConfigManager, ConfigProvider } from '@pawells/config';
+import { GetErrorMessage } from '@pawells/typescript-common';
+/**
+ * Set of keys that pose prototype pollution risks and must be filtered.
+ *
+ * @internal
+ */
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/**
+ * Zod schema for validating JSON provider file paths.
+ *
+ * Enforces non-empty string with no path traversal sequences ("..").
+ * Defaults to `./config.json` in the current working directory.
+ */
+export const CONFIG_JSON_PROVIDER_PATH_SCHEMA = z.string().min(1)
+    .default(path.join(process.cwd(), 'config.json'))
+    .refine((filePath) => !path.normalize(filePath).includes('..'), {
+    message: 'Path traversal sequences ("..") are not permitted.'
+});
+/**
+ * Zod schema for validating ConfigJSONProvider constructor options.
+ *
+ * Extends the base provider options with path and required flag.
+ */
+export const CONFIG_JSON_PROVIDER_OPTIONS_SCHEMA = CONFIG_PROVIDER_OPTIONS_SCHEMA.extend({
+    path: CONFIG_JSON_PROVIDER_PATH_SCHEMA,
+    required: z.boolean().optional().default(false)
+});
+/**
+ * Assert that a value conforms to TConfigJSONProviderOptions.
+ *
+ * @param options - The value to validate.
+ * @throws {ZodError} If validation fails.
+ */
+export function AssertConfigJSONProviderOptions(options) {
+    CONFIG_JSON_PROVIDER_OPTIONS_SCHEMA.parse(options);
+}
+/**
+ * Validate whether a value conforms to TConfigJSONProviderOptions.
+ *
+ * @param options - The value to validate.
+ * @returns `true` if validation succeeds; `false` otherwise.
+ */
+export function ValidateConfigJSONProviderOptions(options) {
+    try {
+        CONFIG_JSON_PROVIDER_OPTIONS_SCHEMA.parse(options);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Zod schema for validating ConfigJSONProvider Save options.
+ *
+ * Allows optional path override and value-selection mode.
+ */
+export const CONFIG_JSON_PROVIDER_SAVE_OPTIONS_SCHEMA = CONFIG_PROVIDER_SAVE_OPTIONS_SCHEMA.extend({
+    path: CONFIG_JSON_PROVIDER_PATH_SCHEMA.optional()
+});
+/**
+ * Assert that a value conforms to TConfigJSONProviderSaveOptions.
+ *
+ * @param options - The value to validate.
+ * @throws {ZodError} If validation fails.
+ */
+export function AssertConfigJSONProviderSaveOptions(options) {
+    CONFIG_JSON_PROVIDER_SAVE_OPTIONS_SCHEMA.parse(options);
+}
+/**
+ * Validate whether a value conforms to TConfigJSONProviderSaveOptions.
+ *
+ * @param options - The value to validate.
+ * @returns `true` if validation succeeds; `false` otherwise.
+ */
+export function ValidateConfigJSONProviderSaveOptions(options) {
+    try {
+        CONFIG_JSON_PROVIDER_SAVE_OPTIONS_SCHEMA.parse(options);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Configuration provider that reads values from a JSON file.
+ *
+ * The file must contain a JSON object at the top level. Nested objects are
+ * flattened using the pattern `SECTION_FIELD` so that a config registered
+ * as `KEYCLOAK_HOST` is found under `{ "KEYCLOAK": { "HOST": "..." } }`.
+ * Top-level non-object values are kept under their own key unchanged.
+ * Only one level of nesting is flattened; deeper nesting is skipped.
+ *
+ * Native JSON types (numbers, booleans, arrays, `null`) are passed directly
+ * to Zod schema validation without any string pre-processing.
+ *
+ * @example
+ * ```typescript
+ * // config.json: { "KEYCLOAK": { "HOST": "localhost", "PORT": 8080 } }
+ * const provider = new ConfigJSONProvider({
+ *   name: 'json',
+ *   path: './config.json',
+ *   required: true
+ * });
+ * await ConfigManager.RegisterProvider(provider);
+ * // Registers: KEYCLOAK_HOST='localhost', KEYCLOAK_PORT=8080
+ *
+ * // Optional file — no throw if missing
+ * const optProvider = new ConfigJSONProvider({
+ *   name: 'json-local',
+ *   path: './config.local.json',
+ *   required: false
+ * });
+ * await ConfigManager.RegisterProvider(optProvider);
+ * ```
+ */
+export class ConfigJSONProvider extends ConfigProvider {
+    /**
+     * Construct a JSON configuration provider.
+     *
+     * @param options - Provider configuration options.
+     * @param options.name - Unique name identifying this provider instance (used for diagnostics).
+     * @param options.path - Path to the JSON configuration file; defaults to `./config.json`.
+     * @param options.required - When `true` (default `false`), a missing or unreadable file throws an error; when `false`, returns `{}`.
+     * @throws {ConfigError} If options fail schema validation or path contains path traversal sequences (..).
+     */
+    constructor(options) {
+        AssertConfigJSONProviderOptions(options);
+        super(options);
+    }
+    /**
+     * Load and flatten the JSON configuration file asynchronously.
+     *
+     * Reads the file at `options.path` asynchronously, parses it as JSON, and flattens
+     * nested objects (one level deep) into fully-qualified keys using `_` as the separator.
+     * If the file cannot be read and `options.required` is `false`, returns `{}`.
+     *
+     * Symlink paths are not permitted and will throw a ConfigError. Both the final path
+     * component and parent directories are validated: the final component is checked via
+     * O_NOFOLLOW, and parent directories are canonicalized via realpath to reject symlinked
+     * ancestor directories.
+     *
+     * Input size (and thus practical nesting depth) is bounded by the existing 10 MB file-size limit.
+     *
+     * @returns A flat record of fully-qualified config key names to their native-typed values.
+     * @throws {ConfigError} If the file is a symlink (final component or parent directory).
+     * @throws {ConfigError} If the file cannot be read and `options.required` is `true`.
+     * @throws {ConfigError} When the config file exceeds 10MB.
+     * @throws {ConfigError} If the loaded JSON fails to parse.
+     *
+     * @example
+     * ```typescript
+     * // config.json:
+     * // { "APP": { "HOST": "localhost", "PORT": 3000, "DEBUG": false } }
+     * const provider = new ConfigJSONProvider({
+     *   name: 'json',
+     *   path: './config.json',
+     *   required: true
+     * });
+     * const values = await provider.Load();
+     * // → { APP_HOST: 'localhost', APP_PORT: 3000, APP_DEBUG: false }
+     * ```
+     */
+    async Load() {
+        try {
+            // Canonicalize parent directory to detect symlinked ancestors
+            const realParentDir = await fs.realpath(path.dirname(this.options.path));
+            const fileName = path.basename(this.options.path);
+            const resolvedPath = path.join(realParentDir, fileName);
+            // Open file with O_NOFOLLOW to reject symlink final component atomically
+            const filehandle = await fs.open(resolvedPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+            let buffer;
+            try {
+                buffer = await filehandle.readFile();
+            }
+            finally {
+                await filehandle.close();
+            }
+            // Use byte-accurate size check: 10 MB = 10 * 1024 * 1024 bytes
+            if (buffer.byteLength > 10 * 1024 * 1024) {
+                throw new ConfigError('Config file exceeds 10MB limit');
+            }
+            const content = buffer.toString('utf-8');
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch (error) {
+                throw new ConfigError('Failed to parse JSON config file: ' + (error instanceof Error ? error.message : String(error)), {
+                    cause: error instanceof Error ? error : undefined
+                });
+            }
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+                return {};
+            const result = {};
+            for (const [topKey, value] of Object.entries(parsed)) {
+                if (DANGEROUS_KEYS.has(topKey))
+                    continue;
+                if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+                    for (const [fieldKey, fieldValue] of Object.entries(value)) {
+                        if (DANGEROUS_KEYS.has(fieldKey))
+                            continue;
+                        result[`${topKey}_${fieldKey}`] = fieldValue;
+                    }
+                }
+                else {
+                    result[topKey] = value;
+                }
+            }
+            return result;
+        }
+        catch (error) {
+            // If it's already a ConfigError, rethrow it
+            if (error instanceof ConfigError) {
+                throw error;
+            }
+            // Check error codes from fs.open and realpath
+            const errorCode = error instanceof Error ? error.code : undefined;
+            // ELOOP (Linux) or ENOTDIR (macOS) indicate symlink in final component
+            if (errorCode === 'ELOOP' || errorCode === 'ENOTDIR') {
+                throw new ConfigError('Symlink paths are not permitted.');
+            }
+            // Check if it's ENOENT (file not found) or parent directory not found
+            const isNotFound = errorCode === 'ENOENT';
+            // If file is missing and not required, return empty config
+            if (isNotFound && !this.options.required) {
+                return {};
+            }
+            // If file is missing and required, wrap error in ConfigError (sanitize message)
+            if (isNotFound && this.options.required) {
+                throw new ConfigError('Config file not found.', {
+                    cause: error instanceof Error ? error : undefined
+                });
+            }
+            // All other errors (permission, etc.) are rethrown
+            throw error;
+        }
+    }
+    /**
+     * Save configuration values to a nested JSON file asynchronously.
+     *
+     * Entries that belong to a registered namespace (i.e. `entry.section` is
+     * non-empty) are grouped under their section key, reproducing the nested
+     * structure that {@link Load} flattens on read:
+     * `KEYCLOAK_HOST` → `{ "KEYCLOAK": { "HOST": "..." } }`.
+     *
+     * Entries with no section (registered directly with {@link ConfigManager.Register}
+     * rather than via {@link ConfigManager.RegisterNamespace}) are written as top-level keys.
+     *
+     * In template mode (`useCurrentValues: false`, the default), secret fields
+     * (`entry.isSecret === true`) are written as `null`, clearly indicating that
+     * a value is required but intentionally absent — suitable for committed
+     * `config.example.json` template files.
+     *
+     * In current-values mode (`useCurrentValues: true`), all values including
+     * secrets are written as-is, capturing the current live state.
+     *
+     * The output file is pretty-printed with tab indentation.
+     *
+     * @param entries - All registered config entries supplied by {@link ConfigManager.Save}.
+     * @param options - Save options including output file path and value-selection mode.
+     * @param options.path - Output file path; defaults to `this.options.path` if not provided.
+     * @param options.useCurrentValues - When `true`, write current live values; when `false` (default), write defaults and `null` for secrets.
+     * @throws {ConfigError} If options validation fails, JSON serialization fails, or file write fails.
+     *
+     * @example
+     * ```typescript
+     * // Generate config.example.json (secrets as null, for committing)
+     * const provider = new ConfigJSONProvider({
+     *   name: 'json',
+     *   path: './config.json'
+     * });
+     * await provider.Save(entries, { path: './config.example.json' });
+     *
+     * // Snapshot current runtime config (with live secrets)
+     * await provider.Save(entries, {
+     *   path: './config.snapshot.json',
+     *   useCurrentValues: true
+     * });
+     * ```
+     */
+    async Save(entries, options) {
+        // Validate options and wrap ZodError in ConfigError
+        try {
+            AssertConfigJSONProviderSaveOptions(options);
+        }
+        catch (error) {
+            throw new ConfigError('Invalid save options.', {
+                cause: error instanceof Error ? error : undefined
+            });
+        }
+        const filePath = options.path ?? this.options.path;
+        const useCurrentValues = options.useCurrentValues ?? false;
+        const result = {};
+        for (const entry of entries) {
+            const value = (!useCurrentValues && entry.isSecret) ? null : entry.value;
+            if (DANGEROUS_KEYS.has(entry.section) || DANGEROUS_KEYS.has(entry.field)) {
+                continue; // Skip prototype-pollution-risk keys
+            }
+            if (entry.section !== '') {
+                // Guard against clobbering primitives with objects
+                if (result[entry.section] !== undefined && (typeof result[entry.section] !== 'object' || result[entry.section] === null)) {
+                    continue; // Skip this entry to avoid clobbering
+                }
+                if (typeof result[entry.section] !== 'object' || result[entry.section] === null) {
+                    result[entry.section] = {};
+                }
+                result[entry.section][entry.field] = value;
+            }
+            else {
+                result[entry.field] = value;
+            }
+        }
+        let jsonOutput;
+        try {
+            jsonOutput = JSON.stringify(result, null, '\t');
+        }
+        catch (error) {
+            throw new ConfigError(`Failed to serialize configuration to JSON: ${GetErrorMessage(error)}`, { cause: error instanceof Error ? error : undefined });
+        }
+        await fs.writeFile(filePath, jsonOutput, 'utf-8');
+    }
+    /**
+     * Create and register a ConfigJSONProvider with {@link ConfigManager}.
+     *
+     * A convenience factory that combines construction and registration.
+     * The provider is immediately registered with the global ConfigManager
+     * and returned for optional use.
+     *
+     * @param options - Partial provider options; missing fields use schema defaults.
+     * @returns A promise that resolves to the created and registered provider instance.
+     * @throws {ZodError} If options fail schema validation.
+     *
+     * @example
+     * ```typescript
+     * // Register with defaults (./config.json, required: false)
+     * await ConfigJSONProvider.Register({ name: 'json' });
+     *
+     * // Register with custom path
+     * const provider = await ConfigJSONProvider.Register({
+     *   name: 'json-local',
+     *   path: './config.local.json',
+     *   required: false
+     * });
+     * ```
+     */
+    static async Register(options = {}) {
+        const provider = new ConfigJSONProvider(CONFIG_JSON_PROVIDER_OPTIONS_SCHEMA.parse(options));
+        await ConfigManager.RegisterProvider(provider);
+        return provider;
+    }
+}
+//# sourceMappingURL=json-provider.js.map

package/dist/json-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-provider.js","sourceRoot":"","sources":["../src/json-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,EAAE,SAAS,IAAI,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAC3B,OAAO,EAAE,8BAA8B,EAAE,mCAAmC,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAwB,MAAM,iBAAiB,CAAC;AACxK,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE7D;;;;GAIG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;KAC/D,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,CAAC,CAAC;KAChD,MAAM,CAAC,CAAC,QAAgB,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE;IACvE,OAAO,EAAE,oDAAoD;CAC7D,CAAC,CAAC;AAEJ;;;;GAIG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,8BAA8B,CAAC,MAAM,CAAC;IACxF,IAAI,EAAE,gCAAgC;IACtC,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;CAC/C,CAAC,CAAC;AAOH;;;;;GAKG;AACH,MAAM,UAAU,+BAA+B,CAAC,OAAgB;IAC/D,mCAAmC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iCAAiC,CAAC,OAAgB;IACjE,IAAI,CAAC;QACJ,mCAAmC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC;IACb,CAAC;IACD,MAAM,CAAC;QACN,OAAO,KAAK,CAAC;IACd,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,wCAAwC,GAAG,mCAAmC,CAAC,MAAM,CAAC;IAClG,IAAI,EAAE,gCAAgC,CAAC,QAAQ,EAAE;CACjD,CAAC,CAAC;AAOH;;;;;GAKG;AACH,MAAM,UAAU,mCAAmC,CAAC,OAAgB;IACnE,wCAAwC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qCAAqC,CAAC,OAAgB;IACrE,IAAI,CAAC;QACJ,wCAAwC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACxD,OAAO,IAAI,CAAC;IACb,CAAC;IACD,MAAM,CAAC;QACN,OAAO,KAAK,CAAC;IACd,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,OAAO,kBAAmB,SAAQ,cAIvC;IACA;;;;;;;;OAQG;IACH,YAAY,OAAmC;QAC9C,+BAA+B,CAAC,OAAO,CAAC,CAAC;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;IAChB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACI,KAAK,CAAC,IAAI;QAChB,IAAI,CAAC;YACJ,8DAA8D;YAC9D,MAAM,aAAa,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YACzE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAClD,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;YAExD,yEAAyE;YACzE,MAAM,UAAU,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,QAAQ,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;YAC9F,IAAI,MAAc,CAAC;YACnB,IAAI,CAAC;gBACJ,MAAM,GAAG,MAAM,UAAU,CAAC,QAAQ,EAAE,CAAC;YACtC,CAAC;oBACO,CAAC;gBACR,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC;YAC1B,CAAC;YAED,+DAA+D;YAC/D,IAAI,MAAM,CAAC,UAAU,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;gBAC1C,MAAM,IAAI,WAAW,CAAC,gCAAgC,CAAC,CAAC;YACzD,CAAC;YAED,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YACzC,IAAI,MAAe,CAAC;YACpB,IAAI,CAAC;gBACJ,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC9B,CAAC;YACD,OAAO,KAAc,EAAE,CAAC;gBACvB,MAAM,IAAI,WAAW,CAAC,oCAAoC,GAAG,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE;oBACtH,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;iBACjD,CAAC,CAAC;YACJ,CAAC;YAED,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;gBAAE,OAAO,EAAE,CAAC;YAEtF,MAAM,MAAM,GAA4B,EAAE,CAAC;YAE3C,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAiC,CAAC,EAAE,CAAC;gBACjF,IAAI,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC;oBAAE,SAAS;gBACzC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC1E,KAAK,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;wBACvF,IAAI,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC;4BAAE,SAAS;wBAC3C,MAAM,CAAC,GAAG,MAAM,IAAI,QAAQ,EAAE,CAAC,GAAG,UAAU,CAAC;oBAC9C,CAAC;gBACF,CAAC;qBACI,CAAC;oBACL,MAAM,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;gBACxB,CAAC;YACF,CAAC;YAED,OAAO,MAAM,CAAC;QACf,CAAC;QACD,OAAO,KAAc,EAAE,CAAC;YACvB,4CAA4C;YAC5C,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;gBAClC,MAAM,KAAK,CAAC;YACb,CAAC;YAED,8CAA8C;YAC9C,MAAM,SAAS,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAE,KAA+B,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;YAE7F,uEAAuE;YACvE,IAAI,SAAS,KAAK,OAAO,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBACtD,MAAM,IAAI,WAAW,CAAC,kCAAkC,CAAC,CAAC;YAC3D,CAAC;YAED,sEAAsE;YACtE,MAAM,UAAU,GAAG,SAAS,KAAK,QAAQ,CAAC;YAE1C,2DAA2D;YAC3D,IAAI,UAAU,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;gBAC1C,OAAO,EAAE,CAAC;YACX,CAAC;YAED,gFAAgF;YAChF,IAAI,UAAU,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;gBACzC,MAAM,IAAI,WAAW,CAAC,wBAAwB,EAAE;oBAC/C,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;iBACjD,CAAC,CAAC;YACJ,CAAC;YAED,mDAAmD;YACnD,MAAM,KAAK,CAAC;QACb,CAAC;IACF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACI,KAAK,CAAC,IAAI,CAAC,OAAmC,EAAE,OAAwC;QAC9F,oDAAoD;QACpD,IAAI,CAAC;YACJ,mCAAmC,CAAC,OAAO,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,KAAc,EAAE,CAAC;YACvB,MAAM,IAAI,WAAW,CAAC,uBAAuB,EAAE;gBAC9C,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;aACjD,CAAC,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;QACnD,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,KAAK,CAAC;QAC3D,MAAM,MAAM,GAA4B,EAAE,CAAC;QAE3C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,CAAC,CAAC,gBAAgB,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC;YAEzE,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC1E,SAAS,CAAC,qCAAqC;YAChD,CAAC;YAED,IAAI,KAAK,CAAC,OAAO,KAAK,EAAE,EAAE,CAAC;gBAC1B,mDAAmD;gBACnD,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,OAAO,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;oBAC1H,SAAS,CAAC,sCAAsC;gBACjD,CAAC;gBACD,IAAI,OAAO,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;oBACjF,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;gBAC5B,CAAC;gBACA,MAAM,CAAC,KAAK,CAAC,OAAO,CAA6B,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;YACzE,CAAC;iBACI,CAAC;gBACL,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;YAC7B,CAAC;QACF,CAAC;QAED,IAAI,UAAkB,CAAC;QACvB,IAAI,CAAC;YACJ,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,KAAc,EAAE,CAAC;YACvB,MAAM,IAAI,WAAW,CACpB,8CAA8C,eAAe,CAAC,KAAK,CAAC,EAAE,EACtE,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,EAAE,CACrD,CAAC;QACH,CAAC;QACD,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACI,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,UAA+C,EAAE;QAC7E,MAAM,QAAQ,GAAG,IAAI,kBAAkB,CAAC,mCAAmC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAC5F,MAAM,aAAa,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAC/C,OAAO,QAAQ,CAAC;IACjB,CAAC;CACD"}

package/package.json

@@ -0,0 +1,64 @@
+{
+	"name": "@pawells/config-provider-json",
+	"displayName": "Config JSON Provider",
+	"version": "3.0.0-rc1",
+	"description": "JSON file configuration provider for @pawells/config",
+	"keywords": [
+		"config",
+		"configuration",
+		"json",
+		"file",
+		"typescript",
+		"nodejs"
+	],
+	"license": "MIT",
+	"author": {
+		"name": "Phillip Aaron Wells",
+		"email": "69355326+PhillipAWells@users.noreply.github.com"
+	},
+	"homepage": "https://github.com/PhillipAWells/config",
+	"bugs": {
+		"url": "https://github.com/PhillipAWells/config/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/PhillipAWells/config.git",
+		"directory": "packages/config-provider-json"
+	},
+	"funding": {
+		"type": "github",
+		"url": "https://github.com/sponsors/PhillipAWells"
+	},
+	"engines": {
+		"node": ">=22.0.0"
+	},
+	"type": "module",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		"./package.json": "./package.json",
+		".": {
+			"local": "./src/index.ts",
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"!**/*.tsbuildinfo",
+		"LICENSE"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"test:coverage": "yarn nx test config-provider-json -- --coverage"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@pawells/config": "workspace:*",
+		"@pawells/typescript-common": "^3.0.5",
+		"tslib": "^2.8.1",
+		"zod": "^4.4.3"
+	}
+}