@adonisjs/env 4.2.0-4 → 4.2.0-6

package/README.md

@@ -110,7 +110,7 @@ env.get('NODE_ENV') // is unknown, hence a string or undefined
 The Env editor can be used to edit dot-env files and persist changes on disk. Only the `.env` and `.env.example` files are updated (if exists).
 
 ```ts
-import { EnvEditor } from '@adonisjs/env'
+import { EnvEditor } from '@adonisjs/env/editor'
 
 const editor = await EnvEditor.create(new URL('./', import.meta.url))
 editor.add('PORT', 3000)

package/build/chunk-NSHYMAZE.js

@@ -0,0 +1,95 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/loader.ts
+import { fileURLToPath } from "node:url";
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+
+// src/debug.ts
+import { debuglog } from "node:util";
+var debug_default = debuglog("adonisjs:env");
+
+// src/loader.ts
+var EnvLoader = class {
+  #appRoot;
+  #loadExampleFile;
+  constructor(appRoot, loadExampleFile = false) {
+    this.#appRoot = typeof appRoot === "string" ? appRoot : fileURLToPath(appRoot);
+    this.#loadExampleFile = loadExampleFile;
+  }
+  /**
+   * Optionally read a file from the disk
+   */
+  async #loadFile(filePath) {
+    try {
+      const contents = await readFile(filePath, "utf-8");
+      return { contents, fileExists: true };
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+      return { contents: "", fileExists: false };
+    }
+  }
+  /**
+   * Load contents of the main dot-env file and the current
+   * environment dot-env file
+   */
+  async load() {
+    const ENV_PATH = process.env.ENV_PATH;
+    const NODE_ENV = process.env.NODE_ENV;
+    const envFiles = [];
+    if (debug_default.enabled) {
+      debug_default("ENV_PATH variable is %s", ENV_PATH ? "set" : "not set");
+      debug_default("NODE_ENV variable is %s", NODE_ENV ? "set" : "not set");
+    }
+    const baseEnvPath = ENV_PATH ? isAbsolute(ENV_PATH) ? ENV_PATH : join(this.#appRoot, ENV_PATH) : this.#appRoot;
+    if (debug_default.enabled) {
+      debug_default('dot-env files base path "%s"', baseEnvPath);
+    }
+    if (NODE_ENV) {
+      const nodeEnvLocalFile = join(baseEnvPath, `.env.${NODE_ENV}.local`);
+      envFiles.push({
+        path: nodeEnvLocalFile,
+        ...await this.#loadFile(nodeEnvLocalFile)
+      });
+    }
+    if (!NODE_ENV || !["test", "testing"].includes(NODE_ENV)) {
+      const envLocalFile = join(baseEnvPath, ".env.local");
+      envFiles.push({
+        path: envLocalFile,
+        ...await this.#loadFile(envLocalFile)
+      });
+    }
+    if (NODE_ENV) {
+      const nodeEnvFile = join(baseEnvPath, `.env.${NODE_ENV}`);
+      envFiles.push({
+        path: nodeEnvFile,
+        ...await this.#loadFile(nodeEnvFile)
+      });
+    }
+    const envFile = join(baseEnvPath, ".env");
+    envFiles.push({
+      path: envFile,
+      ...await this.#loadFile(envFile)
+    });
+    if (this.#loadExampleFile) {
+      const envExampleFile = join(baseEnvPath, ".env.example");
+      envFiles.push({
+        path: envExampleFile,
+        ...await this.#loadFile(envExampleFile)
+      });
+    }
+    return envFiles;
+  }
+};
+
+export {
+  __export,
+  debug_default,
+  EnvLoader
+};

package/build/index.d.ts

@@ -1,5 +1,247 @@
-export { Env } from './src/env.js';
-export { EnvParser } from './src/parser.js';
-export { EnvLoader } from './src/loader.js';
-export * as errors from './src/exceptions.js';
-export { EnvProcessor } from './src/processor.js';
+import * as _poppinss_validator_lite_build_src_schema_oneOf_js from '@poppinss/validator-lite/build/src/schema/oneOf.js';
+import * as _poppinss_validator_lite_build_src_schema_boolean_js from '@poppinss/validator-lite/build/src/schema/boolean.js';
+import * as _poppinss_validator_lite_build_src_schema_string_js from '@poppinss/validator-lite/build/src/schema/string.js';
+import * as _poppinss_validator_lite_build_src_schema_number_js from '@poppinss/validator-lite/build/src/schema/number.js';
+import { ValidateFn } from '@poppinss/validator-lite';
+import { DotenvParseOutput } from 'dotenv';
+
+/**
+ * Exposes the API to validate environment variables against a
+ * pre-defined schema.
+ *
+ * The class is not exported in the main API and used internally.
+ */
+declare class EnvValidator<Schema extends {
+    [key: string]: ValidateFn<unknown>;
+}> {
+    #private;
+    constructor(schema: Schema);
+    /**
+     * Accepts an object of values to validate against the pre-defined
+     * schema.
+     *
+     * The return value is a merged copy of the original object and the
+     * values mutated by the schema validator.
+     */
+    validate(values: {
+        [K: string]: string | undefined;
+    }): {
+        [K in keyof Schema]: ReturnType<Schema[K]>;
+    };
+}
+
+/**
+ * A wrapper over "process.env" with types information.
+ *
+ * ```ts
+ * const validate = Env.rules({
+ *   PORT: Env.schema.number()
+ * })
+ *
+ * const validatedEnvVars = validate(process.env)
+ *
+ * const env = new EnvValues(validatedEnvVars)
+ * env.get('PORT') // type === number
+ * ```
+ */
+declare class Env<EnvValues extends Record<string, any>> {
+    #private;
+    constructor(values: EnvValues);
+    /**
+     * Create an instance of the env class by validating the
+     * environment variables. Also, the `.env` files are
+     * loaded from the appRoot
+     */
+    static create<Schema extends {
+        [key: string]: ValidateFn<unknown>;
+    }>(appRoot: URL, schema: Schema): Promise<Env<{
+        [K in keyof Schema]: ReturnType<Schema[K]>;
+    }>>;
+    /**
+     * The schema builder for defining validation rules
+     */
+    static schema: {
+        number: typeof _poppinss_validator_lite_build_src_schema_number_js.number;
+        string: typeof _poppinss_validator_lite_build_src_schema_string_js.string;
+        boolean: typeof _poppinss_validator_lite_build_src_schema_boolean_js.boolean;
+        enum: typeof _poppinss_validator_lite_build_src_schema_oneOf_js.oneOf;
+    };
+    /**
+     * Define the validation rules for validating environment
+     * variables. The return value is an instance of the
+     * env validator
+     */
+    static rules<T extends {
+        [key: string]: ValidateFn<unknown>;
+    }>(schema: T): EnvValidator<T>;
+    /**
+     * Get the value of an environment variable by key. The values are
+     * lookedup inside the validated environment and "process.env"
+     * is used as a fallback.
+     *
+     * The second param is the default value, which is returned when
+     * the environment variable does not exist.
+     *
+     * ```ts
+     * Env.get('PORT')
+     *
+     * // With default value
+     * Env.get('PORT', 3000)
+     * ```
+     */
+    get<K extends keyof EnvValues>(key: K): EnvValues[K];
+    get<K extends keyof EnvValues>(key: K, defaultValue: Exclude<EnvValues[K], undefined>): Exclude<EnvValues[K], undefined>;
+    get(key: string): string | undefined;
+    get(key: string, defaultValue: string): string;
+    /**
+     * Update/set value of an environment variable.
+     *
+     * The value is not casted/validated using the validator, so make sure
+     * to set the correct data type.
+     *
+     * ```ts
+     * Env.set('PORT', 3000)
+     *
+     * Env.get('PORT') === 3000 // true
+     * process.env.PORT === '3000' // true
+     * ```
+     */
+    set<K extends keyof EnvValues>(key: K, value: EnvValues[K]): void;
+    set(key: string, value: string): void;
+}
+
+/**
+ * Env parser parses the environment variables from a string formatted
+ * as a key-value pair seperated using an `=`. For example:
+ *
+ * ```dotenv
+ * PORT=3333
+ * HOST=127.0.0.1
+ * ```
+ *
+ * The variables can reference other environment variables as well using `$`.
+ * For example:
+ *
+ * ```dotenv
+ * PORT=3333
+ * REDIS_PORT=$PORT
+ * ```
+ *
+ * The variables using characters other than letters can wrap variable
+ * named inside a curly brace.
+ *
+ * ```dotenv
+ * APP-PORT=3333
+ * REDIS_PORT=${APP-PORT}
+ * ```
+ *
+ * You can escape the `$` sign with a backtick.
+ *
+ * ```dotenv
+ * REDIS_PASSWORD=foo\$123
+ * ```
+ *
+ * ## Usage
+ *
+ * ```ts
+ * const parser = new EnvParser(envContents)
+ * const output = parser.parse()
+ *
+ * // The output is a key-value pair
+ * ```
+ */
+declare class EnvParser {
+    #private;
+    constructor(envContents: string, options?: {
+        ignoreProcessEnv: boolean;
+    });
+    /**
+     * Parse the env string to an object of environment variables.
+     */
+    parse(): DotenvParseOutput;
+}
+
+/**
+ * Read the contents of one or more dot-env files. Following is how the files
+ * are read.
+ *
+ * - Load file from the "ENV_PATH" environment file.
+ *    (Raise error if file is missing)
+ *
+ * - If "ENV_PATH" is not defined, then find ".env" file in the app root.
+ *    (Ignore if file is missing)
+ *
+ * - Find ".env.[NODE_ENV]" file in the app root.
+ *    (Ignore if file is missing)
+ *
+ * ```ts
+ * const loader = new EnvLoader(new URL('./', import.meta.url))
+ *
+ * const { envContents, currentEnvContents } = await loader.load()
+ *
+ * // envContents: Contents of .env or file specified via ENV_PATH
+ * // currentEnvContents: Contents of .env.[NODE_ENV] file
+ * ```
+ */
+declare class EnvLoader {
+    #private;
+    constructor(appRoot: string | URL, loadExampleFile?: boolean);
+    /**
+     * Load contents of the main dot-env file and the current
+     * environment dot-env file
+     */
+    load(): Promise<{
+        contents: string;
+        path: string;
+        fileExists: boolean;
+    }[]>;
+}
+
+/**
+ * Exception raised when one or more env variables
+ * are invalid
+ */
+declare const E_INVALID_ENV_VARIABLES: {
+    new (message?: string | undefined, options?: (ErrorOptions & {
+        code?: string | undefined;
+        status?: number | undefined;
+    }) | undefined): {
+        help: string;
+        name: string;
+        code?: string | undefined;
+        status: number;
+        toString(): string;
+        readonly [Symbol.toStringTag]: string;
+        message: string;
+        stack?: string | undefined;
+        cause?: unknown;
+    };
+    message: string;
+    code: string;
+    help?: string | undefined;
+    status?: number | undefined;
+    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};
+
+declare const errors_E_INVALID_ENV_VARIABLES: typeof E_INVALID_ENV_VARIABLES;
+declare namespace errors {
+  export {
+    errors_E_INVALID_ENV_VARIABLES as E_INVALID_ENV_VARIABLES,
+  };
+}
+
+/**
+ * Env processors loads, parses and process environment variables.
+ */
+declare class EnvProcessor {
+    #private;
+    constructor(appRoot: URL);
+    /**
+     * Process env variables
+     */
+    process(): Promise<Record<string, any>>;
+}
+
+export { Env, EnvLoader, EnvParser, EnvProcessor, errors };

package/build/index.js

@@ -1,13 +1,251 @@
-/*
- * @adonisjs/env
- *
- * (c) AdonisJS
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-export { Env } from './src/env.js';
-export { EnvParser } from './src/parser.js';
-export { EnvLoader } from './src/loader.js';
-export * as errors from './src/exceptions.js';
-export { EnvProcessor } from './src/processor.js';
+import {
+  EnvLoader,
+  __export,
+  debug_default
+} from "./chunk-NSHYMAZE.js";
+
+// src/env.ts
+import { schema as envSchema } from "@poppinss/validator-lite";
+
+// src/errors.ts
+var errors_exports = {};
+__export(errors_exports, {
+  E_INVALID_ENV_VARIABLES: () => E_INVALID_ENV_VARIABLES
+});
+import { Exception } from "@poppinss/utils";
+var E_INVALID_ENV_VARIABLES = class EnvValidationException extends Exception {
+  static message = "Validation failed for one or more environment variables";
+  static code = "E_INVALID_ENV_VARIABLES";
+  help = "";
+};
+
+// src/validator.ts
+var EnvValidator = class {
+  #schema;
+  #error;
+  constructor(schema) {
+    this.#schema = schema;
+    this.#error = new E_INVALID_ENV_VARIABLES();
+  }
+  /**
+   * Accepts an object of values to validate against the pre-defined
+   * schema.
+   *
+   * The return value is a merged copy of the original object and the
+   * values mutated by the schema validator.
+   */
+  validate(values) {
+    const help = [];
+    const validated = Object.keys(this.#schema).reduce(
+      (result, key) => {
+        const value = process.env[key] || values[key];
+        try {
+          result[key] = this.#schema[key](key, value);
+        } catch (error) {
+          help.push(`- ${error.message}`);
+        }
+        return result;
+      },
+      { ...values }
+    );
+    if (help.length) {
+      this.#error.help = help.join("\n");
+      throw this.#error;
+    }
+    return validated;
+  }
+};
+
+// src/parser.ts
+import dotenv from "dotenv";
+var EnvParser = class {
+  #envContents;
+  #preferProcessEnv = true;
+  constructor(envContents, options) {
+    if (options?.ignoreProcessEnv) {
+      this.#preferProcessEnv = false;
+    }
+    this.#envContents = envContents;
+  }
+  /**
+   * Returns the value from the parsed object
+   */
+  #getValue(key, parsed) {
+    if (this.#preferProcessEnv && process.env[key]) {
+      return process.env[key];
+    }
+    if (parsed[key]) {
+      return this.#interpolate(parsed[key], parsed);
+    }
+    return process.env[key] || "";
+  }
+  /**
+   * Interpolating the token wrapped inside the mustache braces.
+   */
+  #interpolateMustache(token, parsed) {
+    const closingBrace = token.indexOf("}");
+    if (closingBrace === -1) {
+      return token;
+    }
+    const varReference = token.slice(1, closingBrace).trim();
+    return `${this.#getValue(varReference, parsed)}${token.slice(closingBrace + 1)}`;
+  }
+  /**
+   * Interpolating the variable reference starting with a
+   * `$`. We only capture numbers,letter and underscore.
+   * For other characters, one can use the mustache
+   * braces.
+   */
+  #interpolateVariable(token, parsed) {
+    return token.replace(/[a-zA-Z0-9_]+/, (key) => {
+      return this.#getValue(key, parsed);
+    });
+  }
+  /**
+   * Interpolates the referenced values
+   */
+  #interpolate(value, parsed) {
+    const tokens = value.split("$");
+    let newValue = "";
+    let skipNextToken = true;
+    tokens.forEach((token) => {
+      if (token === "\\") {
+        newValue += "$";
+        skipNextToken = true;
+        return;
+      }
+      if (skipNextToken) {
+        newValue += token.replace(/\\$/, "$");
+        if (token.endsWith("\\")) {
+          return;
+        }
+      } else {
+        if (token.startsWith("{")) {
+          newValue += this.#interpolateMustache(token, parsed);
+          return;
+        }
+        newValue += this.#interpolateVariable(token, parsed);
+      }
+      skipNextToken = false;
+    });
+    return newValue;
+  }
+  /**
+   * Parse the env string to an object of environment variables.
+   */
+  parse() {
+    const envCollection = dotenv.parse(this.#envContents.trim());
+    return Object.keys(envCollection).reduce((result, key) => {
+      result[key] = this.#getValue(key, envCollection);
+      return result;
+    }, {});
+  }
+};
+
+// src/processor.ts
+var EnvProcessor = class {
+  /**
+   * App root is needed to load files
+   */
+  #appRoot;
+  constructor(appRoot) {
+    this.#appRoot = appRoot;
+  }
+  /**
+   * Parse env variables from raw contents
+   */
+  #processContents(envContents, store) {
+    if (!envContents.trim()) {
+      return store;
+    }
+    const values = new EnvParser(envContents).parse();
+    Object.keys(values).forEach((key) => {
+      let value = process.env[key];
+      if (!value) {
+        value = values[key];
+        process.env[key] = values[key];
+      }
+      if (!store[key]) {
+        store[key] = value;
+      }
+    });
+    return store;
+  }
+  /**
+   * Parse env variables by loading dot files.
+   */
+  async #loadAndProcessDotFiles() {
+    const loader = new EnvLoader(this.#appRoot);
+    const envFiles = await loader.load();
+    if (debug_default.enabled) {
+      debug_default(
+        "processing .env files (priority from top to bottom) %O",
+        envFiles.map((file) => file.path)
+      );
+    }
+    const envValues = {};
+    envFiles.forEach(({ contents }) => this.#processContents(contents, envValues));
+    return envValues;
+  }
+  /**
+   * Process env variables
+   */
+  async process() {
+    return this.#loadAndProcessDotFiles();
+  }
+};
+
+// src/env.ts
+var Env = class _Env {
+  /**
+   * A cache of env values
+   */
+  #values;
+  constructor(values) {
+    this.#values = values;
+  }
+  /**
+   * Create an instance of the env class by validating the
+   * environment variables. Also, the `.env` files are
+   * loaded from the appRoot
+   */
+  static async create(appRoot, schema) {
+    const values = await new EnvProcessor(appRoot).process();
+    const validator = this.rules(schema);
+    return new _Env(validator.validate(values));
+  }
+  /**
+   * The schema builder for defining validation rules
+   */
+  static schema = envSchema;
+  /**
+   * Define the validation rules for validating environment
+   * variables. The return value is an instance of the
+   * env validator
+   */
+  static rules(schema) {
+    const validator = new EnvValidator(schema);
+    return validator;
+  }
+  get(key, defaultValue) {
+    if (this.#values[key] !== void 0) {
+      return this.#values[key];
+    }
+    const envValue = process.env[key];
+    if (envValue) {
+      return envValue;
+    }
+    return defaultValue;
+  }
+  set(key, value) {
+    this.#values[key] = value;
+    process.env[key] = value;
+  }
+};
+export {
+  Env,
+  EnvLoader,
+  EnvParser,
+  EnvProcessor,
+  errors_exports as errors
+};

package/build/src/editor.d.ts

@@ -1,5 +1,4 @@
-/// <reference types="@types/node" resolution-mode="require"/>
-export declare class EnvEditor {
+declare class EnvEditor {
     #private;
     /**
      * Creates an instance of env editor and loads .env files
@@ -25,3 +24,5 @@ export declare class EnvEditor {
      */
     save(): Promise<void>;
 }
+
+export { EnvEditor };