@rsdk/env 6.0.0-next.0

package/dist/environment.class.d.ts

@@ -0,0 +1,92 @@
+import type { PropertyParser } from '@rsdk/common';
+export type EnvVariable<T> = {
+    /** The parsed value of the environment variable */
+    value: T;
+    /** The actual environment variable key that was used to retrieve the value */
+    key: string;
+};
+/**
+ * Class for managing environment variables with optional application name prefix.
+ * Provides methods to access both required and optional environment variables,
+ * with support for type conversion through parsers.
+ *
+ * Environment variables can be accessed either with or without an application name prefix.
+ * For example, if appName is "myapp" and the variable name is "port":
+ * - Will check MYAPP_PORT first
+ * - Will fall back to PORT if MYAPP_PORT is not set
+ */
+export declare class Env {
+    private readonly appName?;
+    constructor(appName?: string | undefined);
+    /**
+     * Gets an optional environment variable. If the variable doesn't exist,
+     * returns undefined instead of throwing an error.
+     *
+     * @param variableName Name of the environment variable to look up
+     * @param parser Optional parser to convert the environment variable value to the desired type
+     * @returns EnvVariable instance if the variable exists, undefined otherwise
+     *
+     * @example
+     * // Get optional string value
+     * env.optional('DATABASE_URL')
+     *
+     * @example
+     * // Get optional number value
+     * env.optional('PORT', new NumberParser())
+     */
+    optional(variableName: string): EnvVariable<string> | undefined;
+    optional<T>(variableName: string, parser: PropertyParser<T>): EnvVariable<T> | undefined;
+    /**
+     * Gets a required environment variable. Throws an error if the variable
+     * doesn't exist in any form (neither prefixed nor unprefixed).
+     *
+     * @param variableName Name of the environment variable to look up
+     * @param parser Optional parser to convert the environment variable value to the desired type
+     * @returns EnvVariable instance containing the value and the actual key used
+     * @throws Error if neither prefixed nor unprefixed variable exists
+     *
+     * @example
+     * // Get required string value
+     * env.required('API_KEY')
+     *
+     * @example
+     * // Get required boolean value
+     * env.required('DEBUG_MODE', new BooleanParser())
+     */
+    required(variableName: string): EnvVariable<string>;
+    required<T>(variableName: string, parser: PropertyParser<T>): EnvVariable<T>;
+    /**
+     * Checks if any of the environment variables for the given name are set.
+     * Considers both prefixed (with appName) and unprefixed versions.
+     *
+     * @param variableName Name of the environment variable to check
+     * @returns true if any of the environment variables are set, false otherwise
+     *
+     * @example
+     * if (env.isSet('DATABASE_URL')) {
+     *   // Handle database connection
+     * }
+     */
+    isSet(variableName: string): boolean;
+    /**
+     * Internal method to retrieve environment variable value.
+     * Handles both raw string values and parsed values using provided parser.
+     *
+     * @param keys Array of possible environment variable keys to check
+     * @param parser Optional parser to convert the environment variable value
+     * @returns EnvVariable instance if found, undefined otherwise
+     * @internal
+     */
+    private get;
+    /**
+     * Internal method to generate possible environment variable keys.
+     * Creates two versions of the key:
+     * 1. With app name prefix (if appName is provided)
+     * 2. Without prefix
+     *
+     * @param variableName Base name of the environment variable
+     * @returns Array of possible environment variable keys in UPPER_SNAKE_CASE
+     * @internal
+     */
+    private keys;
+}

package/dist/environment.class.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Env = void 0;
+const common_1 = require("@rsdk/common");
+/**
+ * Class for managing environment variables with optional application name prefix.
+ * Provides methods to access both required and optional environment variables,
+ * with support for type conversion through parsers.
+ *
+ * Environment variables can be accessed either with or without an application name prefix.
+ * For example, if appName is "myapp" and the variable name is "port":
+ * - Will check MYAPP_PORT first
+ * - Will fall back to PORT if MYAPP_PORT is not set
+ */
+class Env {
+    appName;
+    constructor(appName) {
+        this.appName = appName;
+    }
+    optional(variableName, parser) {
+        return parser
+            ? this.get(this.keys(variableName), parser)
+            : this.get(this.keys(variableName));
+    }
+    required(variableName, parser) {
+        const keys = this.keys(variableName);
+        const variable = parser ? this.get(keys, parser) : this.get(keys);
+        if (!variable) {
+            throw new Error((0, common_1.text) `
+        Please provide one of the following environment variables:
+        ${keys.join(', ')}`);
+        }
+        return variable;
+    }
+    /**
+     * Checks if any of the environment variables for the given name are set.
+     * Considers both prefixed (with appName) and unprefixed versions.
+     *
+     * @param variableName Name of the environment variable to check
+     * @returns true if any of the environment variables are set, false otherwise
+     *
+     * @example
+     * if (env.isSet('DATABASE_URL')) {
+     *   // Handle database connection
+     * }
+     */
+    isSet(variableName) {
+        return this.keys(variableName).some((x) => x in process.env);
+    }
+    get(keys, parser) {
+        for (const key of keys) {
+            if (key in process.env) {
+                const value = parser
+                    ? parser.parse(process.env[key])
+                    : process.env[key];
+                return { key, value };
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Internal method to generate possible environment variable keys.
+     * Creates two versions of the key:
+     * 1. With app name prefix (if appName is provided)
+     * 2. Without prefix
+     *
+     * @param variableName Base name of the environment variable
+     * @returns Array of possible environment variable keys in UPPER_SNAKE_CASE
+     * @internal
+     */
+    keys(variableName) {
+        const keys = [common_1.Case.toUpperSnake(variableName)];
+        if (this.appName) {
+            keys.unshift(common_1.Case.toUpperSnake(`${this.appName}_${variableName}`));
+        }
+        return keys;
+    }
+}
+exports.Env = Env;
+//# sourceMappingURL=environment.class.js.map

package/dist/environment.class.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.class.js","sourceRoot":"","sources":["../src/environment.class.ts"],"names":[],"mappings":";;;AACA,yCAA0C;AAU1C;;;;;;;;;GASG;AACH,MAAa,GAAG;IACe;IAA7B,YAA6B,OAAgB;QAAhB,YAAO,GAAP,OAAO,CAAS;IAAG,CAAC;IAuBjD,QAAQ,CACN,YAAoB,EACpB,MAA0B;QAE1B,OAAO,MAAM;YACX,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;YAC3C,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;IACxC,CAAC;IAqBD,QAAQ,CACN,YAAoB,EACpB,MAA0B;QAE1B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAElE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,IAAA,aAAI,EAAA;;UAEhB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACzB,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,YAAoB;QACxB,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/D,CAAC;IAgBO,GAAG,CACT,IAAc,EACd,MAA0B;QAE1B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;gBACvB,MAAM,KAAK,GAAG,MAAM;oBAClB,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC;oBACjC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC;gBAEtB,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;YACxB,CAAC;QACH,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;;;;;;OASG;IACK,IAAI,CAAC,YAAoB;QAC/B,MAAM,IAAI,GAAG,CAAC,aAAI,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC;QAE/C,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,OAAO,CAAC,aAAI,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,OAAO,IAAI,YAAY,EAAE,CAAC,CAAC,CAAC;QACrE,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAtID,kBAsIC"}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './environment.class';

package/dist/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("./environment.class"), exports);
+//# 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,sDAAoC"}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@rsdk/env",
+  "version": "6.0.0-next.0",
+  "description": "Tools for working with environment variables",
+  "license": "Apache License 2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "url": "https://github.com/R-Vision/rsdk"
+  },
+  "main": "dist/index.js",
+  "peerDependencies": {
+    "@rsdk/common": "*"
+  },
+  "gitHead": "215cccea23d95118dd8b6af3ce11c6a35ce19c30"
+}

package/src/environment.class.ts

@@ -0,0 +1,156 @@
+import type { PropertyParser } from '@rsdk/common';
+import { Case, text } from '@rsdk/common';
+
+export type EnvVariable<T> = {
+  /** The parsed value of the environment variable */
+  value: T;
+
+  /** The actual environment variable key that was used to retrieve the value */
+  key: string;
+};
+
+/**
+ * Class for managing environment variables with optional application name prefix.
+ * Provides methods to access both required and optional environment variables,
+ * with support for type conversion through parsers.
+ *
+ * Environment variables can be accessed either with or without an application name prefix.
+ * For example, if appName is "myapp" and the variable name is "port":
+ * - Will check MYAPP_PORT first
+ * - Will fall back to PORT if MYAPP_PORT is not set
+ */
+export class Env {
+  constructor(private readonly appName?: string) {}
+
+  /**
+   * Gets an optional environment variable. If the variable doesn't exist,
+   * returns undefined instead of throwing an error.
+   *
+   * @param variableName Name of the environment variable to look up
+   * @param parser Optional parser to convert the environment variable value to the desired type
+   * @returns EnvVariable instance if the variable exists, undefined otherwise
+   *
+   * @example
+   * // Get optional string value
+   * env.optional('DATABASE_URL')
+   *
+   * @example
+   * // Get optional number value
+   * env.optional('PORT', new NumberParser())
+   */
+  optional(variableName: string): EnvVariable<string> | undefined;
+  optional<T>(
+    variableName: string,
+    parser: PropertyParser<T>,
+  ): EnvVariable<T> | undefined;
+  optional<T>(
+    variableName: string,
+    parser?: PropertyParser<T>,
+  ): EnvVariable<string> | EnvVariable<T> | undefined {
+    return parser
+      ? this.get(this.keys(variableName), parser)
+      : this.get(this.keys(variableName));
+  }
+
+  /**
+   * Gets a required environment variable. Throws an error if the variable
+   * doesn't exist in any form (neither prefixed nor unprefixed).
+   *
+   * @param variableName Name of the environment variable to look up
+   * @param parser Optional parser to convert the environment variable value to the desired type
+   * @returns EnvVariable instance containing the value and the actual key used
+   * @throws Error if neither prefixed nor unprefixed variable exists
+   *
+   * @example
+   * // Get required string value
+   * env.required('API_KEY')
+   *
+   * @example
+   * // Get required boolean value
+   * env.required('DEBUG_MODE', new BooleanParser())
+   */
+  required(variableName: string): EnvVariable<string>;
+  required<T>(variableName: string, parser: PropertyParser<T>): EnvVariable<T>;
+  required<T>(
+    variableName: string,
+    parser?: PropertyParser<T>,
+  ): EnvVariable<string> | EnvVariable<T> {
+    const keys = this.keys(variableName);
+    const variable = parser ? this.get(keys, parser) : this.get(keys);
+
+    if (!variable) {
+      throw new Error(text`
+        Please provide one of the following environment variables:
+        ${keys.join(', ')}`);
+    }
+
+    return variable;
+  }
+
+  /**
+   * Checks if any of the environment variables for the given name are set.
+   * Considers both prefixed (with appName) and unprefixed versions.
+   *
+   * @param variableName Name of the environment variable to check
+   * @returns true if any of the environment variables are set, false otherwise
+   *
+   * @example
+   * if (env.isSet('DATABASE_URL')) {
+   *   // Handle database connection
+   * }
+   */
+  isSet(variableName: string): boolean {
+    return this.keys(variableName).some((x) => x in process.env);
+  }
+
+  /**
+   * Internal method to retrieve environment variable value.
+   * Handles both raw string values and parsed values using provided parser.
+   *
+   * @param keys Array of possible environment variable keys to check
+   * @param parser Optional parser to convert the environment variable value
+   * @returns EnvVariable instance if found, undefined otherwise
+   * @internal
+   */
+  private get(keys: string[]): EnvVariable<string> | undefined;
+  private get<T>(
+    keys: string[],
+    parser: PropertyParser<T>,
+  ): EnvVariable<T> | undefined;
+  private get<T>(
+    keys: string[],
+    parser?: PropertyParser<T>,
+  ): EnvVariable<string> | EnvVariable<T | string> | undefined {
+    for (const key of keys) {
+      if (key in process.env) {
+        const value = parser
+          ? parser.parse(process.env[key]!)
+          : process.env[key]!;
+
+        return { key, value };
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Internal method to generate possible environment variable keys.
+   * Creates two versions of the key:
+   * 1. With app name prefix (if appName is provided)
+   * 2. Without prefix
+   *
+   * @param variableName Base name of the environment variable
+   * @returns Array of possible environment variable keys in UPPER_SNAKE_CASE
+   * @internal
+   */
+  private keys(variableName: string): string[] {
+    const keys = [Case.toUpperSnake(variableName)];
+
+    if (this.appName) {
+      keys.unshift(Case.toUpperSnake(`${this.appName}_${variableName}`));
+    }
+
+    return keys;
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './environment.class';

package/tsconfig.build.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": [
+    "node_modules",
+    "dist",
+    "test",
+    "**/*.spec.ts",
+    "**/*.test.ts",
+    "**/*.test.e2e.ts",
+    "**/*.test.manual-e2e.ts",
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@rsdk/tsconfig/base.json",
+  "compilerOptions": {
+    "declaration": true,
+    "outDir": "dist"
+  }
+}