@map-colonies/config 1.0.0

package/README.md

@@ -0,0 +1,291 @@
+# Config
+This package provide a solution for handling the configuration for NodeJs applications.
+The package supports both working as a standalone solution and online using [config-server](https://github.com/MapColonies/config-server).
+
+The configs are defined in the [schemas](https://github.com/MapColonies/schemas) package. It is used for validation, defining environment variable override, and for generating typescript types.
+
+# Installation
+In order to use the package you need to install both the package itself, and the schemas package that handles all the config schemas.
+```sh
+npm install @map-colonies/schemas @map-colonies/config
+```
+
+# Usage
+```typescript
+import { config } from '@map-colonies/config';
+import { commonBoilerplateV4 } from '@map-colonies/schemas';
+
+const configInstance = await config({
+  configName: 'boiler-config',
+  configServerUrl: 'http://localhost:8080',
+  schema: commonBoilerplateV4,
+  version: 'latest',
+  offlineMode: false
+});
+
+const port = configInstance.get('server.port');
+```
+
+## API Documentation
+
+This section describes the API provided by the package for interacting with the configuration.
+
+### `ConfigInstance<T>`
+
+The `ConfigInstance` interface represents the your way to interact with the configuration. It provides methods to retrieve configuration values and parts.
+`T` is the typescript type associated with the chosen schema. it can be imported from the `@map-colonies/schemas` package.
+
+#### Methods
+
+##### `get<TPath extends string>(path: TPath): _.GetFieldType<T, TPath>`
+
+- **Description**: Retrieves the value at the specified path from the configuration object. Note that the type of returned object is based on the path in the schema.
+- **Parameters**:
+  - `path` (`TPath`): The path to the desired value.
+- **Returns**: The value at the specified path.
+
+##### `getAll(): T`
+
+- **Description**: Retrieves the entire configuration object.
+- **Returns**: The entire configuration object.
+
+##### `getConfigParts(): { localConfig: object; config: object; envConfig: object }`
+
+- **Description**: Retrieves different parts of the configuration object before being merged and validated. Useful for debugging.
+- **Returns**: An object containing the `localConfig`, `config`, and `envConfig` parts of the configuration.
+  - `localConfig`: The local configuration object.
+  - `config`: The remote configuration object.
+  - `envConfig`: The environment configuration object.
+
+##### `getResolvedOptions(): BaseOptions`
+
+- **Description**: Retrieves the resolved options from the configuration object. Useful for debugging.
+- **Returns**: The resolved options, which are an instance of `BaseOptions`.
+
+
+# Configuration Options
+
+This package allows you to configure various options for loading and managing configurations. Below are the available options and their descriptions.
+
+## Options
+
+### `schema`
+- **Type**: `T extends SchemaWithType`
+- **Description**: The schema of the configuration object.
+
+### `configName`
+- **Type**: `string`
+- **Description**: The name of the remote configuration.
+- **Environment Variable**: `CONFIG_NAME`
+
+### `version`
+- **Type**: `'latest' | number`
+- **Description**: The version of the remote configuration. It can be either `'latest'` or a number.
+- **Environment Variable**: `CONFIG_VERSION`
+
+### `configServerUrl`
+- **Type**: `string`
+- **Description**: The URL of the configuration server.
+- **Environment Variable**: `CONFIG_SERVER_URL`
+
+### `offlineMode`
+- **Type**: `boolean`
+- **Optional**: `true`
+- **Description**: Indicates whether the configuration should be loaded in offline mode.
+- **Environment Variable**: `CONFIG_OFFLINE_MODE`
+
+### `ignoreServerIsOlderVersionError`
+- **Type**: `boolean`
+- **Optional**: `true`
+- **Description**: Indicates whether to ignore the error when the server version is older than the requested version.
+- **Environment Variable**: `CONFIG_IGNORE_SERVER_IS_OLDER_VERSION_ERROR`
+
+### `localConfigPath`
+- **Type**: `string`
+- **Default**: `./config`
+- **Description**: The path to the local configuration folder.
+
+## JSON Schema
+
+The options are validated against the following JSON schema:
+
+```json
+{
+  "required": ["configName", "configServerUrl", "version"],
+  "additionalProperties": false,
+  "type": "object",
+  "properties": {
+    "configName": { "type": "string" },
+    "version": {
+      "oneOf": [
+        { "type": "string", "const": "latest" },
+        { "type": "integer", "minimum": 1 }
+      ]
+    },
+    "configServerUrl": { "type": "string" },
+    "offlineMode": { "type": "boolean", "nullable": true },
+    "ignoreServerIsOlderVersionError": { "type": "boolean", "nullable": true },
+    "localConfigPath": { "type": "string", "default": "./config" }
+  }
+}
+```
+
+## Environment Variable Configuration
+
+The following environment variables can be used to configure the options:
+
+- `CONFIG_NAME`: Sets the `configName` option.
+- `CONFIG_VERSION`: Sets the `version` option.
+- `CONFIG_SERVER_URL`: Sets the `configServerUrl` option.
+- `CONFIG_OFFLINE_MODE`: Sets the `offlineMode` option.
+- `CONFIG_IGNORE_SERVER_IS_OLDER_VERSION_ERROR`: Sets the `ignoreServerIsOlderVersionError` option.
+
+## Configuration Merging and Validation
+
+The package supports merging configurations from multiple sources (local, remote, and environment variables) and then validates the merged configuration against the schema.
+
+### Local Configuration
+
+1. The local configuration is loaded from the path specified by the `localConfigPath` option. The default path is `./config`.
+
+### Remote Configuration
+
+1. The remote configuration is fetched from the server specified by the `configServerUrl` option.
+2. If the `version` is set to `'latest'`, the latest version of the configuration is fetched. Otherwise, the specified version is fetched.
+
+### Environment Variables
+
+Configuration options can be overridden by setting the corresponding environment variables as described in schema using the `x-env-value` key.
+
+### Merging Configurations
+
+1. The configurations are merged in the following order of precedence:
+   - Environment variables
+   - Remote configuration
+   - Local configuration
+
+2. If a configuration option is specified in multiple sources, the value from the source with higher precedence (as listed above) is used.
+
+### Validation
+
+1. After merging, the final configuration is validated against the defined schema using ajv.
+2. The validation ensures that all required properties are present, and the types and values of properties conform to the schema.
+3. Any default value according to the schema is added to the final object.
+4. If the validation fails, an error is thrown, indicating the invalid properties and their issues.
+
+
+# Error handling
+
+This section describes the possible errors that can occur when using the package, along with their codes and payload structures.
+
+## Identifying errors
+The package exposes a helper function called `isConfigError` to assert what is the error that was thrown and handle it as needed.
+```typescript
+import { config, isConfigError } from '@map-colonies/config';
+
+try {
+  const configInstance = await config({
+    configName: 'boiler-config',
+    configServerUrl: 'http://localhost:8080',
+    schema: commonBoilerplateV4,
+    version: 'latest',
+    offlineMode: false
+  });
+  
+} catch (error) {
+  if (isConfigError(error, 'configValidationError')) {
+    console.error('Config validation error:', error.payload);
+  }
+}
+```
+
+## Errors
+### `optionValidationError`
+- **Code**: `1`
+- **Payload**: `ValidationError[]`
+- **Description**: This error occurs when there is a validation error with one of the configuration options.
+
+### `configValidationError`
+- **Code**: `2`
+- **Payload**: `ValidationError[]`
+- **Description**: This error occurs when the configuration as a whole fails validation.
+
+### `httpResponseError`
+- **Code**: `3`
+- **Payload**: 
+  ```typescript
+  {
+    headers: Record<string, string>;
+    statusCode: number;
+    body: string;
+  }
+  ```
+- **Description**: This error occurs when an HTTP request results in an error response. The payload includes the response headers, status code and body.
+
+### `httpGeneralError`
+- **Code**: `4`
+- **Payload**: `Error`
+- **Description**: This error occurs when there is a general HTTP error. The payload contains the error object.
+
+### `schemaNotFoundError`
+- **Code**: `5`
+- **Payload**: 
+  ```typescript
+  {
+    schemaPath: string;
+  }
+  ```
+- **Description**: This error occurs when the specified schema cannot be found. The payload includes the path of the missing schema.
+
+### `schemasPackageVersionMismatchError`
+- **Code**: `6`
+- **Payload**: 
+  ```typescript
+  {
+    remotePackageVersion: string;
+    localPackageVersion: string;
+  }
+  ```
+- **Description**: This error occurs when there is a version mismatch between the remote and local schema packages. The payload includes the versions of both the remote and local packages.
+
+### `schemaVersionMismatchError`
+- **Code**: `7`
+- **Payload**: 
+  ```typescript
+  {
+    remoteSchemaVersion: string;
+    localSchemaVersion: string;
+  }
+  ```
+- **Description**: This error occurs when there is a version mismatch between the remote and local schemas. The payload includes the versions of both the remote and local schemas.
+
+# Debugging
+If for some reason you want to debug the package you can either use the `getConfigParts` or the `getResolvedOptions` functions described in the API or use the more powerful debug logger.
+
+The package debug logger is implemented using the [`debug`](https://www.npmjs.com/package/debug) npm package and is configured using the `DEBUG` Environment variable.
+
+The following are the values you can configure to use the debug option.
+
+### `DEBUG=*`
+Enables all the logs. Note that setting this option might enable debug logging of other packages.
+
+### `DEBUG=@map-colonies/config*`
+Enables all the logs available in this package.
+
+### `DEBUG=@map-colonies/config:config`
+Enables only the logs related to the main logic of the package.
+
+### `DEBUG=@map-colonies/config:env`
+Enables only the logs related to parsing environment variables from schemas, and retrieving them for use in the configuration.
+
+### `DEBUG=@map-colonies/config:http`
+Enables only the logs related to http requests to the `config-server`.
+
+### `DEBUG=@map-colonies/config:options`
+Enables only the logs related to parsing and validation of the package initialization options.
+
+### `DEBUG=@map-colonies/config:schemas`
+Enables only the logs related to the retrieving of schemas.
+
+### `DEBUG=@map-colonies/config:validator`
+Enables only the logs related to the validation of configurations.

package/dist/avi.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=avi.d.ts.map

package/dist/avi.d.ts.map

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

package/dist/avi.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const schemas_1 = require("@map-colonies/schemas");
+const config_1 = require("./config");
+(async () => {
+    const c = await (0, config_1.config)({
+        schema: schemas_1.threeDFileSyncerV1,
+        configName: 'threeDFileSyncerV1',
+        configServerUrl: 'http://localhost:3000',
+        version: 1,
+        offlineMode: true,
+    });
+    const a = c.get('telemetry.logger');
+    console.log(a);
+})().catch(console.error);
+//# sourceMappingURL=avi.js.map

package/dist/avi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"avi.js","sourceRoot":"","sources":["../src/avi.ts"],"names":[],"mappings":";;AAAA,mDAA2D;AAC3D,qCAAkC;AAElC,CAAC,KAAK,IAAI,EAAE;IACV,MAAM,CAAC,GAAG,MAAM,IAAA,eAAM,EAAC;QACrB,MAAM,EAAE,4BAAkB;QAC1B,UAAU,EAAE,oBAAoB;QAChC,eAAe,EAAE,uBAAuB;QACxC,OAAO,EAAE,CAAC;QACV,WAAW,EAAE,IAAI;KAClB,CAAC,CAAC;IAEH,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACpC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACjB,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+import { typeSymbol } from '@map-colonies/schemas/build/schemas/symbol';
+import { ConfigOptions, ConfigInstance } from './types';
+/**
+ * Retrieves the configuration based on the provided options.
+ *
+ * @template T - The type of the configuration schema.
+ * @param {ConfigOptions<T>} options - The options for retrieving the configuration.
+ * @returns {Promise<ConfigInstance<T>>} - A promise that resolves to the configuration object.
+ */
+export declare function config<T extends {
+    [typeSymbol]: unknown;
+    $id: string;
+}>(options: ConfigOptions<T>): Promise<ConfigInstance<T[typeof typeSymbol]>>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,4CAA4C,CAAC;AAKxE,OAAO,EAAe,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAcrE;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,CAAC,SAAS;IAAE,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAC3E,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAmG/C"}

package/dist/config.js

@@ -0,0 +1,102 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+const deepmerge_1 = __importDefault(require("deepmerge"));
+const symbol_1 = require("@map-colonies/schemas/build/schemas/symbol");
+const config_1 = __importDefault(require("config"));
+const semver_1 = __importDefault(require("semver"));
+const lodash_1 = __importDefault(require("lodash"));
+const env_1 = require("./env");
+const schemas_1 = require("./schemas");
+const options_1 = require("./options");
+const httpClient_1 = require("./httpClient");
+const validator_1 = require("./validator");
+const debug_1 = require("./utils/debug");
+const constants_1 = require("./constants");
+const errors_1 = require("./errors");
+const debug = (0, debug_1.createDebug)('config');
+// eslint-disable-next-line @typescript-eslint/no-unsafe-return
+const arrayMerge = (destinationArray, sourceArray) => sourceArray;
+/**
+ * Retrieves the configuration based on the provided options.
+ *
+ * @template T - The type of the configuration schema.
+ * @param {ConfigOptions<T>} options - The options for retrieving the configuration.
+ * @returns {Promise<ConfigInstance<T>>} - A promise that resolves to the configuration object.
+ */
+async function config(options) {
+    // handle package options
+    debug('config called with options: %j', { ...options, schema: options.schema.$id });
+    const { schema: baseSchema, ...unvalidatedOptions } = options;
+    const { configName, offlineMode, version, ignoreServerIsOlderVersionError } = (0, options_1.initializeOptions)(unvalidatedOptions);
+    let remoteConfig = {};
+    // handle remote config
+    if (offlineMode !== true) {
+        debug('handling fetching remote data');
+        // check if the server is using an older version of the schemas package
+        const capabilitiesResponse = await (0, httpClient_1.getServerCapabilities)();
+        if (ignoreServerIsOlderVersionError !== true && semver_1.default.gt(constants_1.LOCAL_SCHEMAS_PACKAGE_VERSION, capabilitiesResponse.schemasPackageVersion)) {
+            debug('server is using an older version of the schemas package. local: %s, remote: %s', constants_1.LOCAL_SCHEMAS_PACKAGE_VERSION, capabilitiesResponse.schemasPackageVersion);
+            throw (0, errors_1.createConfigError)('schemasPackageVersionMismatchError', 'The server is using an older version of the schemas package. Please update the server to the latest version or ignore this error by setting the CONFIG_IGNORE_SERVER_IS_OLDER_VERSION_ERROR environment variable.', {
+                localPackageVersion: constants_1.LOCAL_SCHEMAS_PACKAGE_VERSION,
+                remotePackageVersion: capabilitiesResponse.schemasPackageVersion,
+            });
+        }
+        // get the remote config
+        const serverConfigResponse = await (0, httpClient_1.getRemoteConfig)(configName, version);
+        if (serverConfigResponse.schemaId !== baseSchema.$id) {
+            debug('schema version mismatch. local: %s, remote: %s', baseSchema.$id, serverConfigResponse.schemaId);
+            throw (0, errors_1.createConfigError)('schemaVersionMismatchError', 'The schema version of the remote config does not match the schema version of the local config', {
+                localSchemaVersion: baseSchema.$id,
+                remoteSchemaVersion: serverConfigResponse.schemaId,
+            });
+        }
+        remoteConfig = serverConfigResponse.config;
+    }
+    debug('remote config: %j', remoteConfig);
+    const dereferencedSchema = await (0, schemas_1.loadSchema)(baseSchema);
+    const localConfig = config_1.default.util.loadFileConfigs(options.localConfigPath);
+    debug('local config: %j', localConfig);
+    const envConfig = (0, env_1.getEnvValues)(dereferencedSchema);
+    debug('env config: %j', envConfig);
+    // merge all the configs into one object with the following priority: localConfig < remoteConfig < envConfig
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    const mergedConfig = deepmerge_1.default.all([localConfig, remoteConfig, envConfig], { arrayMerge });
+    debug('merged config: %j', mergedConfig);
+    // validate the merged config
+    const [errors, validatedConfig] = (0, validator_1.validate)(validator_1.ajvConfigValidator, dereferencedSchema, mergedConfig);
+    if (errors) {
+        debug('config validation error: %j', errors);
+        throw (0, errors_1.createConfigError)('configValidationError', 'Config validation error', errors);
+    }
+    debug('freezing validated config');
+    // freeze the merged config so it can't be modified by the package user
+    Object.freeze(validatedConfig);
+    function get(path) {
+        debug('get called with path: %s', path);
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return lodash_1.default.get(validatedConfig, path);
+    }
+    function getAll() {
+        debug('getAll called');
+        return validatedConfig;
+    }
+    function getConfigParts() {
+        debug('getConfigParts called');
+        return {
+            localConfig,
+            config: remoteConfig,
+            envConfig,
+        };
+    }
+    function getResolvedOptions() {
+        debug('getResolvedOptions called');
+        return (0, options_1.getOptions)();
+    }
+    return { get, getAll, getConfigParts, getResolvedOptions };
+}
+exports.config = config;
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const LOCAL_SCHEMAS_PACKAGE_VERSION: string;
+export declare const SCHEMA_DOMAIN = "https://mapcolonies.com/";
+export declare const SCHEMAS_PACKAGE_RESOLVED_PATH: string;
+export declare const SCHEMA_BASE_PATH: string;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,6BAA6B,QAAgG,CAAC;AAE3I,eAAO,MAAM,aAAa,6BAA6B,CAAC;AAExD,eAAO,MAAM,6BAA6B,QAA2C,CAAC;AACtF,eAAO,MAAM,gBAAgB,QAA6F,CAAC"}

package/dist/constants.js

@@ -0,0 +1,14 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEMA_BASE_PATH = exports.SCHEMAS_PACKAGE_RESOLVED_PATH = exports.SCHEMA_DOMAIN = exports.LOCAL_SCHEMAS_PACKAGE_VERSION = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const read_pkg_1 = require("@map-colonies/read-pkg");
+const schemasPackagePathBuildPath = require.resolve('@map-colonies/schemas').substring(0, require.resolve('@map-colonies/schemas').indexOf('build'));
+exports.LOCAL_SCHEMAS_PACKAGE_VERSION = (0, read_pkg_1.readPackageJsonSync)(node_path_1.default.join(schemasPackagePathBuildPath, 'package.json')).version;
+exports.SCHEMA_DOMAIN = 'https://mapcolonies.com/';
+exports.SCHEMAS_PACKAGE_RESOLVED_PATH = require.resolve('@map-colonies/schemas');
+exports.SCHEMA_BASE_PATH = exports.SCHEMAS_PACKAGE_RESOLVED_PATH.substring(0, exports.SCHEMAS_PACKAGE_RESOLVED_PATH.lastIndexOf('/'));
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAC7B,qDAA6D;AAE7D,MAAM,2BAA2B,GAAG,OAAO,CAAC,OAAO,CAAC,uBAAuB,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,uBAAuB,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;AACxI,QAAA,6BAA6B,GAAG,IAAA,8BAAmB,EAAC,mBAAI,CAAC,IAAI,CAAC,2BAA2B,EAAE,cAAc,CAAC,CAAC,CAAC,OAAiB,CAAC;AAE9H,QAAA,aAAa,GAAG,0BAA0B,CAAC;AAE3C,QAAA,6BAA6B,GAAG,OAAO,CAAC,OAAO,CAAC,uBAAuB,CAAC,CAAC;AACzE,QAAA,gBAAgB,GAAG,qCAA6B,CAAC,SAAS,CAAC,CAAC,EAAE,qCAA6B,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC"}

package/dist/env.d.ts

@@ -0,0 +1,3 @@
+import { JSONSchema } from '@apidevtools/json-schema-ref-parser';
+export declare function getEnvValues(schema: JSONSchema): object;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAkEjE,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAgCvD"}

package/dist/env.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getEnvValues = void 0;
+const lodash_1 = __importDefault(require("lodash"));
+const debug_1 = require("./utils/debug");
+const debug = (0, debug_1.createDebug)('env');
+const schemaCompositionKeys = ['oneOf', 'anyOf', 'allOf'];
+function parseSchemaEnv(schema) {
+    debug('parsing schema for env values');
+    const fromEnv = {};
+    function handlePrimitive(schema, type, path) {
+        debug('handling primitive %s at path %s', type, path);
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        const xFrom = schema['x-env-value'];
+        debug('value of xFrom: %s as path %s', xFrom, path);
+        if (xFrom !== undefined) {
+            fromEnv[xFrom] = {
+                type,
+                path,
+            };
+        }
+    }
+    function iterateOverSchemaObject(schema, path) {
+        debug('iterating over schema object at path %s', path);
+        const type = schema.type;
+        if (type === 'number' || type === 'string' || type === 'boolean' || type === 'integer' || type === 'null') {
+            return handlePrimitive(schema, type, path);
+        }
+        if (type === 'array' || type === 'any') {
+            debug('array or any type at path %s', path);
+            return;
+        }
+        schemaCompositionKeys.forEach((key) => {
+            const compositionObj = schema[key];
+            if (compositionObj !== undefined) {
+                debug('going over composition object %s at path %s', key, path);
+                for (const subSchema of compositionObj) {
+                    if (typeof subSchema !== 'boolean') {
+                        iterateOverSchemaObject(subSchema, path);
+                    }
+                }
+            }
+        });
+        if (type === 'object') {
+            for (const key in schema.properties) {
+                debug('going over object properties at path %s', key, path);
+                const subSchema = schema.properties[key];
+                if (typeof subSchema !== 'boolean') {
+                    iterateOverSchemaObject(subSchema, path === '' ? key : `${path}.${key}`);
+                }
+            }
+        }
+    }
+    iterateOverSchemaObject(schema, '');
+    return fromEnv;
+}
+function getEnvValues(schema) {
+    const res = {};
+    const envMap = parseSchemaEnv(schema);
+    for (const [key, details] of Object.entries(envMap)) {
+        const unparsedValue = process.env[key];
+        if (unparsedValue !== undefined) {
+            debug('found env value for key %s with type %s', key, details.type);
+            let value;
+            switch (details.type) {
+                case 'boolean':
+                    value = unparsedValue.toLowerCase() === 'true';
+                    break;
+                case 'integer':
+                    value = parseInt(unparsedValue);
+                    break;
+                case 'number':
+                    value = parseFloat(unparsedValue);
+                    break;
+                case 'null':
+                    value = null;
+                    break;
+                default:
+                    value = unparsedValue;
+            }
+            lodash_1.default.set(res, details.path, value);
+        }
+    }
+    return res;
+}
+exports.getEnvValues = getEnvValues;
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":";;;;;;AACA,oDAA4B;AAE5B,yCAA4C;AAE5C,MAAM,KAAK,GAAG,IAAA,mBAAW,EAAC,KAAK,CAAC,CAAC;AAEjC,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAU,CAAC;AAEnE,SAAS,cAAc,CAAC,MAAkB;IACxC,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACvC,MAAM,OAAO,GAAW,EAAE,CAAC;IAE3B,SAAS,eAAe,CAAC,MAAkB,EAAE,IAAa,EAAE,IAAY;QACtE,KAAK,CAAC,kCAAkC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACtD,gEAAgE;QAChE,MAAM,KAAK,GAAI,MAAqC,CAAC,aAAa,CAAC,CAAC;QACpE,KAAK,CAAC,+BAA+B,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QACpD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,CAAC,KAAK,CAAC,GAAG;gBACf,IAAI;gBACJ,IAAI;aACL,CAAC;QACJ,CAAC;IACH,CAAC;IAED,SAAS,uBAAuB,CAAC,MAAkB,EAAE,IAAY;QAC/D,KAAK,CAAC,yCAAyC,EAAE,IAAI,CAAC,CAAC;QACvD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACzB,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;YAC1G,OAAO,eAAe,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QAC7C,CAAC;QAED,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;YACvC,KAAK,CAAC,8BAA8B,EAAE,IAAI,CAAC,CAAC;YAC5C,OAAO;QACT,CAAC;QAED,qBAAqB,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;YACpC,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YACnC,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;gBACjC,KAAK,CAAC,6CAA6C,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;gBAChE,KAAK,MAAM,SAAS,IAAI,cAAc,EAAE,CAAC;oBACvC,IAAI,OAAO,SAAS,KAAK,SAAS,EAAE,CAAC;wBACnC,uBAAuB,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;oBAC3C,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;gBACpC,KAAK,CAAC,yCAAyC,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;gBAC5D,MAAM,SAAS,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;gBAEzC,IAAI,OAAO,SAAS,KAAK,SAAS,EAAE,CAAC;oBACnC,uBAAuB,CAAC,SAAS,EAAE,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,GAAG,EAAE,CAAC,CAAC;gBAC3E,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,uBAAuB,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACpC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAgB,YAAY,CAAC,MAAkB;IAC7C,MAAM,GAAG,GAAG,EAAE,CAAC;IAEf,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IACtC,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACpD,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;YAChC,KAAK,CAAC,yCAAyC,EAAE,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;YACpE,IAAI,KAAc,CAAC;YAEnB,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;gBACrB,KAAK,SAAS;oBACZ,KAAK,GAAG,aAAa,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC;oBAC/C,MAAM;gBACR,KAAK,SAAS;oBACZ,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;oBAChC,MAAM;gBACR,KAAK,QAAQ;oBACX,KAAK,GAAG,UAAU,CAAC,aAAa,CAAC,CAAC;oBAClC,MAAM;gBACR,KAAK,MAAM;oBACT,KAAK,GAAG,IAAI,CAAC;oBACb,MAAM;gBACR;oBACE,KAAK,GAAG,aAAa,CAAC;YAC1B,CAAC;YAED,gBAAM,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAhCD,oCAgCC"}

package/dist/errors.d.ts

@@ -0,0 +1,74 @@
+import { ValidationError } from '@apideck/better-ajv-errors';
+import { Dispatcher } from 'undici';
+declare const configErrors: {
+    readonly optionValidationError: {
+        readonly code: 1;
+        readonly payload: ValidationError[];
+    };
+    readonly configValidationError: {
+        readonly code: 2;
+        readonly payload: ValidationError[];
+    };
+    readonly httpResponseError: {
+        readonly code: 3;
+        readonly payload: Pick<Dispatcher.ResponseData, "headers" | "statusCode"> & {
+            body: string;
+        };
+    };
+    readonly httpGeneralError: {
+        readonly code: 4;
+        readonly payload: Error;
+    };
+    readonly schemaNotFoundError: {
+        readonly code: 5;
+        readonly payload: {
+            schemaPath: string;
+        };
+    };
+    readonly schemasPackageVersionMismatchError: {
+        readonly code: 6;
+        readonly payload: {
+            remotePackageVersion: string;
+            localPackageVersion: string;
+        };
+    };
+    readonly schemaVersionMismatchError: {
+        readonly code: 7;
+        readonly payload: {
+            remoteSchemaVersion: string;
+            localSchemaVersion: string;
+        };
+    };
+};
+/**
+ * Represents the configuration errors.
+ */
+export type ConfigErrors = typeof configErrors;
+/**
+ * Represents an error specific to the configuration module.
+ *
+ * @template ErrorName - The name of the error.
+ * @template Payload - The payload type associated with the error.
+ */
+export declare class ConfigError<ErrorName extends keyof ConfigErrors, Payload = ConfigErrors[ErrorName]['payload']> extends Error {
+    readonly payload: Payload | undefined;
+    readonly code: ConfigErrors[ErrorName]['code'];
+    /**
+     * Creates a new instance of the ConfigError class.
+     *
+     * @param name - The name of the error.
+     * @param message - The error message.
+     * @param payload - The payload associated with the error.
+     */
+    constructor(name: ErrorName, message: string, payload: Payload | undefined);
+}
+export declare function createConfigError<ErrorName extends keyof ConfigErrors, Payload extends ConfigErrors[ErrorName]['payload']>(name: ErrorName, message: string, payload: Payload): ConfigError<ErrorName, Payload>;
+/**
+ * Checks if the given error is an instance of `ConfigError` with the specified error type.
+ * @param error - The error to check.
+ * @param errorName - The name of the error to check against.
+ * @returns `true` if the error is an instance of `ConfigError` with the specified error name, `false` otherwise.
+ */
+export declare function isConfigError<ErrorName extends keyof ConfigErrors>(error: unknown, errorName: ErrorName): error is ConfigError<ErrorName>;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC,QAAA,MAAM,YAAY;;;;;;;;;;;;kBAG+F,MAAM;;;;;;;;;;wBAExD,MAAM;;;;;;kCACmB,MAAM;iCAAuB,MAAM;;;;;;iCAC5C,MAAM;gCAAsB,MAAM;;;CAE9C,CAAC;AAEpE;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC;AAE/C;;;;;GAKG;AACH,qBAAa,WAAW,CAAC,SAAS,SAAS,MAAM,YAAY,EAAE,OAAO,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAE,SAAQ,KAAK;aAUnD,OAAO,EAAE,OAAO,GAAG,SAAS;IATjG,SAAgB,IAAI,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;IAEtD;;;;;;OAMG;gBACgB,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAkB,OAAO,EAAE,OAAO,GAAG,SAAS;CAKlG;AAED,wBAAgB,iBAAiB,CAAC,SAAS,SAAS,MAAM,YAAY,EAAE,OAAO,SAAS,YAAY,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,EACxH,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,GACf,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CAEjC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,SAAS,MAAM,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,GAAG,KAAK,IAAI,WAAW,CAAC,SAAS,CAAC,CAMzI"}