nestjs-env-getter 0.0.0-beta2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Ivan Baha
+
+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,2 @@
+# nestjs-env-getter
+The Nestjs Module for getting environment variables at app start

package/dist/env-getter/env-getter.module.d.ts

@@ -0,0 +1,2 @@
+export declare class EnvGetterModule {
+}

package/dist/env-getter/env-getter.module.js

@@ -0,0 +1,20 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvGetterModule = void 0;
+const common_1 = require("@nestjs/common");
+const env_getter_service_1 = require("./env-getter.service");
+let EnvGetterModule = class EnvGetterModule {
+};
+exports.EnvGetterModule = EnvGetterModule;
+exports.EnvGetterModule = EnvGetterModule = __decorate([
+    (0, common_1.Module)({
+        providers: [env_getter_service_1.EnvGetterService],
+        exports: [env_getter_service_1.EnvGetterService],
+    })
+], EnvGetterModule);

package/dist/env-getter/env-getter.service.d.ts

@@ -0,0 +1,226 @@
+import { type ClassConstructor, type TimeMarker } from "../shared";
+import { type ArrayValidatorType } from "./types";
+export declare class EnvGetterService {
+    constructor();
+    /**
+     * Logs an error message in red and terminates the process.
+     * @param message - The error message to display before exiting.
+     * @throws Never returns; always exits the process.
+     * @private
+     */
+    private stopProcess;
+    /**
+     * Checks if an environment variable exists.
+     * - If the variable is missing, the process is terminated.
+     * - If the variable exists, returns `true`.
+     * @param envName - The name of the environment variable to check.
+     * @returns `true` if the environment variable exists.
+     * @throws Terminates the process if the variable is missing.
+     * @private
+     */
+    private checkEnvExisting;
+    /**
+     * Validates whether an environment variable contains an allowed value.
+     * - If the variable's value is not in the allowed list, the process is terminated.
+     * @param envName - The name of the environment variable.
+     * @param envVal - The current value of the environment variable.
+     * @param allowedValues - An array of allowed values for the variable.
+     * @throws Terminates the process if `envVal` is not in the allowed list.
+     * @private
+     */
+    private checkIfEnvHasAllowedValue;
+    /**
+     * Checks whether an environment variable is set.
+     * @param envName - The name of the environment variable.
+     * @returns `true` if the environment variable exists, otherwise `false`.
+     */
+    isEnvSet(envName: string): boolean;
+    /**
+     * Retrieves the value of a required environment variable.
+     * - Ensures that the variable exists; otherwise, the process is terminated.
+     * - If `allowedValues` is provided, checks whether the variable contains an allowed value.
+     * @param envName - The name of the required environment variable.
+     * @param allowedValues - (Optional) A list of allowed values for validation.
+     * @returns The environment variable value as a string.
+     * @throws Terminates the process if the variable is missing or contains an invalid value.
+     */
+    getRequiredEnv(envName: string): string;
+    getRequiredEnv(envName: string, allowedValues: string[]): string;
+    /**
+     * Retrieves the value of an optional environment variable.
+     * - If the variable is set, returns its value.
+     * - If `defaultValue` is provided and the variable is not set, returns the default value.
+     * - If `allowedValues` is provided, validates that the variable (or default value) is within the allowed list.
+     * @param envName - The name of the environment variable.
+     * @param defaultValue - (Optional) The default value to return if the environment variable is not set.
+     * @param allowedValues - (Optional) An array of allowed values for validation.
+     * @returns The environment variable value, the default value, or `undefined` if not set.
+     * @throws Terminates the process if the value is not in `allowedValues` (if provided).
+     */
+    getOptionalEnv(envName: string): string | undefined;
+    getOptionalEnv(envName: string, defaultValue: string): string;
+    getOptionalEnv(envName: string, allowedValues: string[]): string | undefined;
+    getOptionalEnv(envName: string, defaultValue: string, allowedValues: string[]): string | undefined;
+    /**
+     * Retrieves and validates a required numeric environment variable.
+     * - Ensures the variable is set and contains only numeric characters (or underscores).
+     * - Converts the value to a number.
+     * - Terminates the process if the value is not numeric.
+     * @param envName - The name of the environment variable.
+     * @returns The numeric value of the environment variable.
+     * @throws Terminates the process if the variable is missing or not numeric.
+     */
+    getRequiredNumericEnv(envName: string): number;
+    /**
+     * Retrieves an optional numeric environment variable.
+     * - If the variable is set and numeric, returns its numeric value.
+     * - If `defaultValue` is provided and the variable is not set or invalid, returns the default value.
+     * @param envName - The name of the environment variable.
+     * @param defaultValue - (Optional) The default numeric value to return if the variable is not set.
+     * @returns The numeric value of the environment variable or the default value.
+     */
+    getOptionalNumericEnv(envName: string): number | undefined;
+    getOptionalNumericEnv(envName: string, defaultValue: number): number;
+    /**
+     * Retrieves and validates a required boolean environment variable.
+     * - Ensures the variable is set and contains either `"true"` or `"false"`.
+     * - Converts the value to a boolean.
+     * - Terminates the process if the value is not a valid boolean.
+     * @param envName - The name of the environment variable.
+     * @returns The boolean value of the environment variable.
+     * @throws Terminates the process if the variable is missing or not `"true"`/`"false"`.
+     */
+    getRequiredBooleanEnv(envName: string): boolean;
+    /**
+     * Retrieves an optional boolean environment variable.
+     * - If the variable is set, returns `true` for `"true"` and `false` for `"false"`.
+     * - If `defaultValue` is provided and the variable is not set, returns the default value.
+     * @param envName - The name of the environment variable.
+     * @param defaultValue - (Optional) The default boolean value if the variable is not set.
+     * @returns The boolean value of the environment variable or the default value.
+     */
+    getOptionalBooleanEnv(envName: string): boolean | undefined;
+    getOptionalBooleanEnv(envName: string, defaultValue: boolean): boolean;
+    /**
+     * Retrieves and validates a required environment variable as a URL.
+     * - Ensures the variable is set and contains a valid URL.
+     * - Terminates the process if the value is not a valid URL.
+     * @param envName - The name of the environment variable.
+     * @returns A `URL` object representing the value of the environment variable.
+     * @throws Terminates the process if the variable is missing or not a valid URL.
+     */
+    getRequiredURL(envName: string): URL;
+    /**
+     * Retrieves an optional environment variable as a URL.
+     * - If the variable is set and a valid URL, returns a `URL` object.
+     * - If `defaultValue` is provided and the variable is not set, returns the default `URL`.
+     * - Terminates the process if the variable is set but not a valid URL.
+     * @param envName - The name of the environment variable.
+     * @param defaultValue - (Optional) The default URL value to return if the variable is not set.
+     * @returns A `URL` object representing the value of the environment variable or the default value.
+     * @throws Terminates the process if the variable is set but not a valid URL.
+     */
+    getOptionalURL(envName: string): URL | undefined;
+    getOptionalURL(envName: string, defaultValue: URL): URL;
+    /**
+     * Retrieves and parses a required time period from an environment variable.
+     * - Ensures the environment variable is set and retrieves its value.
+     * - Validates that the value follows the format: `<number><"ms"|"s"|"m"|"h"|"d">`.
+     * - Converts the value to the specified time format.
+     * - Terminates the process if the value is missing or invalid.
+     * @param envName - The name of the required environment variable.
+     * @param resultIn - The desired time unit for the result (default is `"ms"`).
+     * @returns The parsed time period converted to the specified unit.
+     * @throws Will stop the process if the environment variable is missing or has an invalid format.
+     */
+    getRequiredTimePeriod(envName: string, resultIn?: TimeMarker): number;
+    /**
+     * Retrieves and parses an optional time period from an environment variable.
+     * - If the environment variable is not set, it falls back to the provided default value.
+     * - Validates that the value is in the acceptable format: `<number><"ms"|"s"|"m"|"h"|"d">`.
+     * - Converts the value to the specified time format.
+     * - Terminates the process if the value is invalid.
+     * @param envName - The name of the environment variable to retrieve.
+     * @param defaultValue - The default time period to use if the environment variable is not set.
+     * @param resultIn - The desired time unit for the result (default is `"ms"`).
+     * @returns The parsed time period converted to the specified unit.
+     * @throws Will stop the process if the environment variable or default value is invalid.
+     */
+    getOptionalTimePeriod(envName: string, defaultValue: string, resultIn?: TimeMarker): number;
+    /**
+     * Retrieves and parses a required environment variable as an object.
+     * - Ensures the environment variable is set.
+     * - Parses the value from a JSON string into an object.
+     * - Optionally validates and instantiates the object using a provided class.
+     * - Terminates the process if parsing fails or if instantiation using the class fails.
+     * @template R - The expected type of the parsed object.
+     * @param envName - The name of the environment variable.
+     * @param cls - (Optional) A class constructor to validate and instantiate the parsed object.
+     * @returns The parsed object, optionally instantiated as an instance of `cls`.
+     * @throws Terminates the process if the environment variable is missing, cannot be parsed, or fails validation.
+     * @example
+     * // Define a class for validation
+     * class Config {
+     *   apiKey: string;
+     *   timeout: number;
+     *
+     *   constructor(data: { apiKey: string; timeout: number }) {
+     *     if (!data.apiKey) throw new Error("apiKey is required");
+     *     if (typeof data.timeout !== "number") throw new Error("timeout must be a number");
+     *     this.apiKey = data.apiKey;
+     *     this.timeout = data.timeout;
+     *   }
+     * }
+     *
+     * // Set the environment variable (e.g., process.env.CONFIG = '{"apiKey": "123", "timeout": 5000"}')
+     * const config = getRequiredObject<Config>("CONFIG", Config);
+     * console.log(config.apiKey); // "123"
+     * console.log(config.timeout); // 5000
+     */
+    getRequiredObject<R = any, C extends ClassConstructor<any> | undefined = undefined>(envName: string, cls?: C): C extends ClassConstructor<infer T> ? T : R;
+    /**
+     * Retrieves and parses an environment variable as an array.
+     * @template R - The expected type of array elements.
+     * @param envName - The name of the environment variable to retrieve.
+     * @param validationOptions - Optional validation settings.
+     * @param validationOptions.optional - If `true`, allows the environment variable to be absent.
+     * @param validationOptions.validate - A function to validate each array element.
+     * @returns The parsed array or `undefined` if optional.
+     * @throws If the environment variable is missing, cannot be parsed, is not an array, or fails validation.
+     * @example
+     * this.forwardHeaders = this.envService.parseArrayFromEnv<string>('FORWARD_HEADERS');
+     * @example
+     * this.forwardHeaders = this.envService.parseArrayFromEnv<string>('FORWARD_HEADERS', {
+     *   optional: true,
+     *   validate: (el) => typeof el === 'string'
+     * });
+     * @example
+     * this.forwardHeaders = this.envService.parseArrayFromEnv<[string, number]>('FORWARD_HEADERS', {
+     *   optional: true,
+     *   validate: (el, i, arr) => {
+     *     if (arr?.length !== 2) return 'FORWARD_HEADERS must be an array of 2 valid items';
+     *     if (i === 0 && typeof el === 'string') return true;
+     *     if (i === 1 && typeof el === 'number') return true;
+     *     return false;
+     *   }
+     * });
+     * @example
+     * this.forwardHeaders = this.envService.parseArrayFromEnv<[string, number]>('FORWARD_HEADERS', {
+     *   optional: true,
+     *   validate: (el, i) => {
+     *     if (i === 0 && typeof el !== 'string') return 'FORWARD_HEADERS[0] must be a string';
+     *     if (i === 1 && typeof el !== 'number') return 'FORWARD_HEADERS[1] must be a number';
+     *     return true;
+     *   }
+     * });
+     */
+    getRequiredArray<R = any>(envName: string): R extends any[] ? R : R[];
+    getRequiredArray<R = any>(envName: string, validationOptions: {
+        optional: true;
+        validate?: ArrayValidatorType<R>;
+    }): (R extends any[] ? R : R[]) | undefined;
+    getRequiredArray<R = any>(envName: string, validationOptions: {
+        optional?: false | undefined;
+        validate?: ArrayValidatorType<R>;
+    }): R extends any[] ? R : R[];
+}

package/dist/env-getter/env-getter.service.js

@@ -0,0 +1,272 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvGetterService = void 0;
+const common_1 = require("@nestjs/common");
+const dotenv_1 = require("dotenv");
+const shared_1 = require("../shared");
+let EnvGetterService = class EnvGetterService {
+    constructor() {
+        (0, dotenv_1.config)();
+    }
+    /**
+     * Logs an error message in red and terminates the process.
+     * @param message - The error message to display before exiting.
+     * @throws Never returns; always exits the process.
+     * @private
+     */
+    stopProcess(message) {
+        // eslint-disable-next-line no-console
+        console.log("\x1b[31m%s\x1b[0m", message);
+        process.exit(1);
+    }
+    /**
+     * Checks if an environment variable exists.
+     * - If the variable is missing, the process is terminated.
+     * - If the variable exists, returns `true`.
+     * @param envName - The name of the environment variable to check.
+     * @returns `true` if the environment variable exists.
+     * @throws Terminates the process if the variable is missing.
+     * @private
+     */
+    checkEnvExisting(envName) {
+        if (!process.env.hasOwnProperty(envName))
+            this.stopProcess(`Missing '${envName}' environment variable`);
+        return true;
+    }
+    /**
+     * Validates whether an environment variable contains an allowed value.
+     * - If the variable's value is not in the allowed list, the process is terminated.
+     * @param envName - The name of the environment variable.
+     * @param envVal - The current value of the environment variable.
+     * @param allowedValues - An array of allowed values for the variable.
+     * @throws Terminates the process if `envVal` is not in the allowed list.
+     * @private
+     */
+    checkIfEnvHasAllowedValue(envName, envVal, allowedValues) {
+        if (!envVal || !allowedValues.includes(envVal))
+            this.stopProcess(`Variable '${envName}' can be only one of: [${allowedValues}], but received '${envVal}'`);
+    }
+    /**
+     * Checks whether an environment variable is set.
+     * @param envName - The name of the environment variable.
+     * @returns `true` if the environment variable exists, otherwise `false`.
+     */
+    isEnvSet(envName) {
+        return process.env.hasOwnProperty(envName);
+    }
+    getRequiredEnv(envName, allowedValues) {
+        var _a;
+        this.checkEnvExisting(envName);
+        if (allowedValues === null || allowedValues === void 0 ? void 0 : allowedValues.length)
+            this.checkIfEnvHasAllowedValue(envName, (_a = process.env[envName]) !== null && _a !== void 0 ? _a : null, allowedValues);
+        return String(process.env[envName]);
+    }
+    getOptionalEnv(envName, defaultValueOrAllowedValues, allowedValues) {
+        if (Array.isArray(defaultValueOrAllowedValues)) {
+            const envValue = process.env[envName];
+            this.checkIfEnvHasAllowedValue(envName, envValue !== null && envValue !== void 0 ? envValue : null, defaultValueOrAllowedValues);
+            return envValue;
+        }
+        else {
+            const envValue = process.env[envName] || defaultValueOrAllowedValues;
+            if (allowedValues === null || allowedValues === void 0 ? void 0 : allowedValues.length)
+                this.checkIfEnvHasAllowedValue(envName, envValue !== null && envValue !== void 0 ? envValue : null, allowedValues);
+            return envValue;
+        }
+    }
+    /**
+     * Retrieves and validates a required numeric environment variable.
+     * - Ensures the variable is set and contains only numeric characters (or underscores).
+     * - Converts the value to a number.
+     * - Terminates the process if the value is not numeric.
+     * @param envName - The name of the environment variable.
+     * @returns The numeric value of the environment variable.
+     * @throws Terminates the process if the variable is missing or not numeric.
+     */
+    getRequiredNumericEnv(envName) {
+        const envVal = this.getRequiredEnv(envName);
+        if (!/^[0-9_]+$/.test(envVal))
+            this.stopProcess(`Variable '${envName}' is not of number type.`);
+        return Number(envVal.replace(/_/g, ""));
+    }
+    getOptionalNumericEnv(envName, defaultValue) {
+        const envVal = String(process.env[envName]);
+        return /^[0-9_]+$/.test(envVal) ? Number(envVal.replace(/_/g, "")) : defaultValue;
+    }
+    /**
+     * Retrieves and validates a required boolean environment variable.
+     * - Ensures the variable is set and contains either `"true"` or `"false"`.
+     * - Converts the value to a boolean.
+     * - Terminates the process if the value is not a valid boolean.
+     * @param envName - The name of the environment variable.
+     * @returns The boolean value of the environment variable.
+     * @throws Terminates the process if the variable is missing or not `"true"`/`"false"`.
+     */
+    getRequiredBooleanEnv(envName) {
+        const envVal = this.getRequiredEnv(envName);
+        if (!/true|false/.test(envVal))
+            this.stopProcess(`Variable '${envName}' is not of boolean type.`);
+        return envVal === "true";
+    }
+    getOptionalBooleanEnv(envName, defaultValue) {
+        return process.env[envName] ? process.env[envName] === "true" : defaultValue;
+    }
+    /**
+     * Retrieves and validates a required environment variable as a URL.
+     * - Ensures the variable is set and contains a valid URL.
+     * - Terminates the process if the value is not a valid URL.
+     * @param envName - The name of the environment variable.
+     * @returns A `URL` object representing the value of the environment variable.
+     * @throws Terminates the process if the variable is missing or not a valid URL.
+     */
+    getRequiredURL(envName) {
+        const envVal = this.getRequiredEnv(envName);
+        try {
+            return new URL(envVal);
+        }
+        catch (err) {
+            this.stopProcess(`Variable '${envName}' must be a valid URL. Error: ${err instanceof Error ? err.message : JSON.stringify(err)}`);
+        }
+    }
+    getOptionalURL(envName, defaultValue) {
+        const envVal = this.getOptionalEnv(envName);
+        try {
+            return envVal ? new URL(envVal) : defaultValue;
+        }
+        catch (err) {
+            this.stopProcess(`Variable '${envName}' must be a valid URL. Error: ${err instanceof Error ? err.message : JSON.stringify(err)}`);
+        }
+    }
+    /**
+     * Retrieves and parses a required time period from an environment variable.
+     * - Ensures the environment variable is set and retrieves its value.
+     * - Validates that the value follows the format: `<number><"ms"|"s"|"m"|"h"|"d">`.
+     * - Converts the value to the specified time format.
+     * - Terminates the process if the value is missing or invalid.
+     * @param envName - The name of the required environment variable.
+     * @param resultIn - The desired time unit for the result (default is `"ms"`).
+     * @returns The parsed time period converted to the specified unit.
+     * @throws Will stop the process if the environment variable is missing or has an invalid format.
+     */
+    getRequiredTimePeriod(envName, resultIn = "ms") {
+        const envVal = this.getRequiredEnv(envName);
+        // validating the ENV value
+        if (!(0, shared_1.isTimePeriod)(envVal))
+            this.stopProcess(`Variable '${envName}' is not in the acceptable format. It must be: <number><"ms"|"s"|"m"|"h"|"d">. Ex.: '12h', '2d', '2D', '2 d'`);
+        return (0, shared_1.parseTimePeriod)(envVal, resultIn);
+    }
+    /**
+     * Retrieves and parses an optional time period from an environment variable.
+     * - If the environment variable is not set, it falls back to the provided default value.
+     * - Validates that the value is in the acceptable format: `<number><"ms"|"s"|"m"|"h"|"d">`.
+     * - Converts the value to the specified time format.
+     * - Terminates the process if the value is invalid.
+     * @param envName - The name of the environment variable to retrieve.
+     * @param defaultValue - The default time period to use if the environment variable is not set.
+     * @param resultIn - The desired time unit for the result (default is `"ms"`).
+     * @returns The parsed time period converted to the specified unit.
+     * @throws Will stop the process if the environment variable or default value is invalid.
+     */
+    getOptionalTimePeriod(envName, defaultValue, resultIn = "ms") {
+        const baseErrorMessage = `'${envName}' is not in the acceptable format. It must be: <number><"ms"|"s"|"m"|"h"|"d">. Ex.: '12h', '2d', '2D', '2 d'`;
+        // validating the default value
+        if (!(0, shared_1.isTimePeriod)(defaultValue))
+            this.stopProcess(`The default value for the environment variable ${baseErrorMessage}`);
+        const envVal = process.env[envName];
+        // validating the ENV value
+        if (envVal && !(0, shared_1.isTimePeriod)(envVal))
+            this.stopProcess(`Variable ${baseErrorMessage}`);
+        return (0, shared_1.parseTimePeriod)(envVal !== null && envVal !== void 0 ? envVal : defaultValue, resultIn);
+    }
+    /**
+     * Retrieves and parses a required environment variable as an object.
+     * - Ensures the environment variable is set.
+     * - Parses the value from a JSON string into an object.
+     * - Optionally validates and instantiates the object using a provided class.
+     * - Terminates the process if parsing fails or if instantiation using the class fails.
+     * @template R - The expected type of the parsed object.
+     * @param envName - The name of the environment variable.
+     * @param cls - (Optional) A class constructor to validate and instantiate the parsed object.
+     * @returns The parsed object, optionally instantiated as an instance of `cls`.
+     * @throws Terminates the process if the environment variable is missing, cannot be parsed, or fails validation.
+     * @example
+     * // Define a class for validation
+     * class Config {
+     *   apiKey: string;
+     *   timeout: number;
+     *
+     *   constructor(data: { apiKey: string; timeout: number }) {
+     *     if (!data.apiKey) throw new Error("apiKey is required");
+     *     if (typeof data.timeout !== "number") throw new Error("timeout must be a number");
+     *     this.apiKey = data.apiKey;
+     *     this.timeout = data.timeout;
+     *   }
+     * }
+     *
+     * // Set the environment variable (e.g., process.env.CONFIG = '{"apiKey": "123", "timeout": 5000"}')
+     * const config = getRequiredObject<Config>("CONFIG", Config);
+     * console.log(config.apiKey); // "123"
+     * console.log(config.timeout); // 5000
+     */
+    getRequiredObject(envName, cls) {
+        const envVal = this.getRequiredEnv(envName);
+        const baseErrorMessage = `Cannot parse object from variable '${envName}'. Error:`;
+        let parsedObj;
+        try {
+            parsedObj = JSON.parse(envVal);
+        }
+        catch (error) {
+            this.stopProcess(`${baseErrorMessage} ${error.message}`);
+        }
+        if (!cls)
+            return parsedObj;
+        try {
+            return new cls(parsedObj);
+        }
+        catch (error) {
+            this.stopProcess(`${baseErrorMessage} ${error.message}`);
+        }
+    }
+    getRequiredArray(envName, validationOptions) {
+        if ((validationOptions === null || validationOptions === void 0 ? void 0 : validationOptions.optional) && !this.isEnvSet(envName))
+            return;
+        const envVal = this.getRequiredEnv(envName);
+        const baseErrorMessage = `Cannot parse object from variable '${envName}'. Error:`;
+        let parsedArray;
+        try {
+            parsedArray = JSON.parse(envVal);
+        }
+        catch (error) {
+            this.stopProcess(`${baseErrorMessage} ${error.message}`);
+        }
+        if (!Array.isArray(parsedArray))
+            this.stopProcess(`'${envName}' must be a stringified array`);
+        if (typeof (validationOptions === null || validationOptions === void 0 ? void 0 : validationOptions.validate) === "function") {
+            // validate each element of parsed array
+            parsedArray.forEach((el, i) => {
+                const result = validationOptions.validate(el, i, parsedArray);
+                // check if validator works correct
+                if (!["boolean", "string"].includes(typeof result) || result === "")
+                    this.stopProcess(`The validation func of EnvGetterService.getRequiredArray('${envName}') must return either boolean or string\nTrace ${new Error().stack}`);
+                // validate element
+                if (result === false || (typeof result === "string" && result))
+                    this.stopProcess(typeof result === "string" ? result : `'${envName}[${i}]' failed validation`);
+            });
+        }
+        return parsedArray;
+    }
+};
+exports.EnvGetterService = EnvGetterService;
+exports.EnvGetterService = EnvGetterService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [])
+], EnvGetterService);

package/dist/env-getter/types/array-validator.type.d.ts

@@ -0,0 +1 @@
+export type ArrayValidatorType<R = any> = (el: unknown, index?: number, array?: R extends any[] ? R : R[]) => boolean | string;

package/dist/env-getter/types/array-validator.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/env-getter/types/index.d.ts

@@ -0,0 +1 @@
+export { ArrayValidatorType } from "./array-validator.type";

package/dist/env-getter/types/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { EnvGetterModule } from "./env-getter/env-getter.module";
+export { EnvGetterService } from "./env-getter/env-getter.service";
+export * from "./shared/types";

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvGetterService = exports.EnvGetterModule = void 0;
+var env_getter_module_1 = require("./env-getter/env-getter.module");
+Object.defineProperty(exports, "EnvGetterModule", { enumerable: true, get: function () { return env_getter_module_1.EnvGetterModule; } });
+var env_getter_service_1 = require("./env-getter/env-getter.service");
+Object.defineProperty(exports, "EnvGetterService", { enumerable: true, get: function () { return env_getter_service_1.EnvGetterService; } });
+__exportStar(require("./shared/types"), exports);

package/dist/shared/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export * from "./utils";

package/dist/shared/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./utils"), exports);

package/dist/shared/types/class-constructor.type.d.ts

@@ -0,0 +1,3 @@
+export type ClassConstructor<T = unknown> = {
+    new (...args: any[]): T;
+};

package/dist/shared/types/class-constructor.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/shared/types/index.d.ts

@@ -0,0 +1,2 @@
+export { ClassConstructor } from "./class-constructor.type";
+export { TimeMarker } from "./time-marker.type";

package/dist/shared/types/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/shared/types/time-marker.type.d.ts

@@ -0,0 +1 @@
+export type TimeMarker = "ms" | "s" | "m" | "h" | "d";

package/dist/shared/types/time-marker.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/shared/utils/index.d.ts

@@ -0,0 +1 @@
+export { isTimePeriod, parseTimePeriod } from "./time-period.utils";

package/dist/shared/utils/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTimePeriod = exports.isTimePeriod = void 0;
+var time_period_utils_1 = require("./time-period.utils");
+Object.defineProperty(exports, "isTimePeriod", { enumerable: true, get: function () { return time_period_utils_1.isTimePeriod; } });
+Object.defineProperty(exports, "parseTimePeriod", { enumerable: true, get: function () { return time_period_utils_1.parseTimePeriod; } });

package/dist/shared/utils/time-period.utils.d.ts

@@ -0,0 +1,21 @@
+import { type TimeMarker } from "../types";
+/**
+ * Checks if the given value represents a valid time period.
+ *
+ * A valid time period can be:
+ * - A number (interpreted as milliseconds).
+ * - A string containing digits optionally followed by a time unit (`s`, `m`, `h`, or `d`).
+ * @param value - The value to check.
+ * @returns `true` if the value is a valid time period, otherwise `false`.
+ */
+export declare function isTimePeriod(value: string | number): boolean;
+/**
+ * Parses a time period value and converts it to the specified unit.
+ * - If the input is a number, it is returned as is.
+ * - If the input is a string, it extracts the numeric value and optional time unit (`s`, `m`, `h`, `d`).
+ * - Converts the extracted value to the desired unit using predefined multipliers.
+ * @param value - The time period to parse, either a number or a string with an optional time unit.
+ * @param resultIn - The unit to convert the result into, defaults to milliseconds.
+ * @returns The parsed time value converted to the specified unit, or `NaN` if the input is invalid.
+ */
+export declare function parseTimePeriod(value: string | number, resultIn?: TimeMarker): number;

package/dist/shared/utils/time-period.utils.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTimePeriod = isTimePeriod;
+exports.parseTimePeriod = parseTimePeriod;
+const timeMarkersMapper = {
+    ms: 1,
+    s: 1000,
+    m: 60000,
+    h: 3600000,
+    d: 86400000,
+};
+const timePeriodStringRegex = /^(\d+)\s*(ms|s|m|h|d)?$/i;
+/**
+ * Checks if the given value represents a valid time period.
+ *
+ * A valid time period can be:
+ * - A number (interpreted as milliseconds).
+ * - A string containing digits optionally followed by a time unit (`s`, `m`, `h`, or `d`).
+ * @param value - The value to check.
+ * @returns `true` if the value is a valid time period, otherwise `false`.
+ */
+function isTimePeriod(value) {
+    if (typeof value === "number")
+        return true;
+    if (typeof value === "string")
+        return timePeriodStringRegex.test(value.replace(/_/g, ""));
+    return false;
+}
+/**
+ * Parses a time period value and converts it to the specified unit.
+ * - If the input is a number, it is returned as is.
+ * - If the input is a string, it extracts the numeric value and optional time unit (`s`, `m`, `h`, `d`).
+ * - Converts the extracted value to the desired unit using predefined multipliers.
+ * @param value - The time period to parse, either a number or a string with an optional time unit.
+ * @param resultIn - The unit to convert the result into, defaults to milliseconds.
+ * @returns The parsed time value converted to the specified unit, or `NaN` if the input is invalid.
+ */
+function parseTimePeriod(value, resultIn = "ms") {
+    var _a;
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "string") {
+        const [, numb, pointer] = (_a = timePeriodStringRegex.exec(value.replace(/_/g, ""))) !== null && _a !== void 0 ? _a : [];
+        const timePointer = ((pointer === null || pointer === void 0 ? void 0 : pointer.toLowerCase()) || "ms");
+        const multiplier = resultIn === timePointer ? 1 : timeMarkersMapper[timePointer] / timeMarkersMapper[resultIn];
+        return Math.ceil(Number(numb) * multiplier);
+    }
+    return NaN;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+    "name": "nestjs-env-getter",
+    "version": "0.0.0-beta2",
+    "description": "Environment variables getter for Nestjs applications",
+    "author": "Ivan Baha",
+    "private": false,
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Foboss6/nestjs-env-getter.git"
+    },
+    "license": "MIT",
+    "scripts": {
+        "prebuild": "rm -rf dist",
+        "build": "tsc --p tsconfig.build.json",
+        "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+        "lint": "eslint --fix",
+        "lint:report": "eslint",
+        "test": "jest",
+        "test:report": "jest --ci --coverage --runInBand",
+        "typecheck": "tsc --noEmit"
+    },
+    "peerDependencies": {
+        "@nestjs/common": ">=9"
+    },
+    "dependencies": {
+        "dotenv": "16.5.0"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.26.0",
+        "@nestjs/common": "11.1.0",
+        "@nestjs/core": "11.1.0",
+        "@nestjs/testing": "11.1.0",
+        "@types/jest": "^29.5.14",
+        "@types/node": "^22.15.16",
+        "eslint": "^9.26.0",
+        "eslint-config-prettier": "^10.0.3",
+        "eslint-plugin-jsdoc": "^50.6.11",
+        "eslint-plugin-prettier": "^5.4.0",
+        "globals": "^16.1.0",
+        "jest": "^29.7.0",
+        "prettier": "^3.5.3",
+        "reflect-metadata": "^0.2.2",
+        "rxjs": "^7.8.2",
+        "ts-jest": "^29.3.2",
+        "typescript": "^5.8.3",
+        "typescript-eslint": "^8.32.0"
+    }
+}