@adonisjs/env 4.2.0-1 → 4.2.0-3

package/src/loader.ts

@@ -0,0 +1,149 @@
+/*
+ * @adonisjs/env
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { fileURLToPath } from 'node:url'
+import { readFile } from 'node:fs/promises'
+import { isAbsolute, join } from 'node:path'
+
+import debug from './debug.js'
+
+/**
+ * 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
+ * ```
+ */
+export class EnvLoader {
+  #appRoot: string
+  #loadExampleFile: boolean
+
+  constructor(appRoot: string | URL, loadExampleFile: boolean = false) {
+    this.#appRoot = typeof appRoot === 'string' ? appRoot : fileURLToPath(appRoot)
+    this.#loadExampleFile = loadExampleFile
+  }
+
+  /**
+   * Optionally read a file from the disk
+   */
+  async #loadFile(filePath: string | URL): Promise<{ fileExists: boolean; contents: string }> {
+    try {
+      const contents = await readFile(filePath, 'utf-8')
+      return { contents, fileExists: true }
+    } catch (error) {
+      /* c8 ignore next 3 */
+      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(): Promise<{ contents: string; path: string; fileExists: boolean }[]> {
+    const ENV_PATH = process.env.ENV_PATH
+    const NODE_ENV = process.env.NODE_ENV
+    const envFiles: { path: string; contents: string; fileExists: boolean }[] = []
+
+    if (debug.enabled) {
+      debug('ENV_PATH variable is %s', ENV_PATH ? 'set' : 'not set')
+      debug('NODE_ENV variable is %s', NODE_ENV ? 'set' : 'not set')
+    }
+
+    /**
+     * Base path to load .env files from
+     */
+    const baseEnvPath = ENV_PATH
+      ? isAbsolute(ENV_PATH)
+        ? ENV_PATH
+        : join(this.#appRoot, ENV_PATH)
+      : this.#appRoot
+
+    if (debug.enabled) {
+      debug('dot-env files base path "%s"', baseEnvPath)
+    }
+
+    /**
+     * 1st
+     * The top most priority is given to the ".env.[NODE_ENV].local" file
+     */
+    if (NODE_ENV) {
+      const nodeEnvLocalFile = join(baseEnvPath, `.env.${NODE_ENV}.local`)
+      envFiles.push({
+        path: nodeEnvLocalFile,
+        ...(await this.#loadFile(nodeEnvLocalFile)),
+      })
+    }
+
+    /**
+     * 2nd
+     * Next, we give priority to the ".env.local" file
+     */
+    if (!NODE_ENV || !['test', 'testing'].includes(NODE_ENV)) {
+      const envLocalFile = join(baseEnvPath, '.env.local')
+      envFiles.push({
+        path: envLocalFile,
+        ...(await this.#loadFile(envLocalFile)),
+      })
+    }
+
+    /**
+     * 3rd
+     * Next, we give priority to the ".env.[NODE_ENV]" file
+     */
+    if (NODE_ENV) {
+      const nodeEnvFile = join(baseEnvPath, `.env.${NODE_ENV}`)
+      envFiles.push({
+        path: nodeEnvFile,
+        ...(await this.#loadFile(nodeEnvFile)),
+      })
+    }
+
+    /**
+     * Finally, we push the contents of the ".env" file.
+     */
+    const envFile = join(baseEnvPath, '.env')
+    envFiles.push({
+      path: envFile,
+      ...(await this.#loadFile(envFile)),
+    })
+
+    /**
+     * Load example file
+     */
+    if (this.#loadExampleFile) {
+      const envExampleFile = join(baseEnvPath, '.env.example')
+      envFiles.push({
+        path: envExampleFile,
+        ...(await this.#loadFile(envExampleFile)),
+      })
+    }
+
+    return envFiles
+  }
+}

package/src/parser.ts

@@ -0,0 +1,185 @@
+/*
+ * @adonisjs/env
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import dotenv, { DotenvParseOutput } from 'dotenv'
+
+/**
+ * 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
+ * ```
+ */
+export class EnvParser {
+  #envContents: string
+  #preferProcessEnv: boolean = true
+
+  constructor(envContents: string, options?: { ignoreProcessEnv: boolean }) {
+    if (options?.ignoreProcessEnv) {
+      this.#preferProcessEnv = false
+    }
+
+    this.#envContents = envContents
+  }
+
+  /**
+   * Returns the value from the parsed object
+   */
+  #getValue(key: string, parsed: DotenvParseOutput): string {
+    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: string, parsed: DotenvParseOutput) {
+    /**
+     * Finding the closing brace. If closing brace is missing, we
+     * consider the block as a normal string
+     */
+    const closingBrace = token.indexOf('}')
+    if (closingBrace === -1) {
+      return token
+    }
+
+    /**
+     * Then we pull everything until the closing brace, except
+     * the opening brace and trim off all white spaces.
+     */
+    const varReference = token.slice(1, closingBrace).trim()
+
+    /**
+     * Getting the value of the reference inside the braces
+     */
+    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: string, parsed: any) {
+    return token.replace(/[a-zA-Z0-9_]+/, (key) => {
+      return this.#getValue(key, parsed)
+    })
+  }
+
+  /**
+   * Interpolates the referenced values
+   */
+  #interpolate(value: string, parsed: DotenvParseOutput): string {
+    const tokens = value.split('$')
+
+    let newValue = ''
+    let skipNextToken = true
+
+    tokens.forEach((token) => {
+      /**
+       * If the value is an escaped sequence, then we replace it
+       * with a `$` and then skip the next token.
+       */
+      if (token === '\\') {
+        newValue += '$'
+        skipNextToken = true
+        return
+      }
+
+      /**
+       * Use the value as it is when "skipNextToken" is set to true.
+       */
+      if (skipNextToken) {
+        /**
+         * Replace the ending escape sequence with a $
+         */
+        newValue += token.replace(/\\$/, '$')
+        /**
+         *  and then skip the next token if it ends with escape sequence
+         */
+        if (token.endsWith('\\')) {
+          return
+        }
+      } else {
+        /**
+         * Handle mustache block
+         */
+        if (token.startsWith('{')) {
+          newValue += this.#interpolateMustache(token, parsed)
+          return
+        }
+
+        /**
+         * Process all words as variable
+         */
+        newValue += this.#interpolateVariable(token, parsed)
+      }
+
+      /**
+       * Process next token
+       */
+      skipNextToken = false
+    })
+
+    return newValue
+  }
+
+  /**
+   * Parse the env string to an object of environment variables.
+   */
+  parse(): DotenvParseOutput {
+    const envCollection = dotenv.parse(this.#envContents.trim())
+
+    return Object.keys(envCollection).reduce<DotenvParseOutput>((result, key) => {
+      result[key] = this.#getValue(key, envCollection)
+      return result
+    }, {})
+  }
+}

package/src/processor.ts

@@ -0,0 +1,83 @@
+/*
+ * @adonisjs/application
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import debug from './debug.js'
+import { EnvParser } from './parser.js'
+import { EnvLoader } from './loader.js'
+
+/**
+ * Env processors loads, parses and process environment variables.
+ */
+export class EnvProcessor {
+  /**
+   * App root is needed to load files
+   */
+  #appRoot: URL
+
+  constructor(appRoot: URL) {
+    this.#appRoot = appRoot
+  }
+
+  /**
+   * Parse env variables from raw contents
+   */
+  #processContents(envContents: string, store: Record<string, any>) {
+    /**
+     * Collected env variables
+     */
+    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.enabled) {
+      debug(
+        'processing .env files (priority from top to bottom) %O',
+        envFiles.map((file) => file.path)
+      )
+    }
+
+    /**
+     * Collected env variables
+     */
+    const envValues: Record<string, any> = {}
+    envFiles.forEach(({ contents }) => this.#processContents(contents, envValues))
+    return envValues
+  }
+
+  /**
+   * Process env variables
+   */
+  async process() {
+    return this.#loadAndProcessDotFiles()
+  }
+}

package/src/validator.ts

@@ -0,0 +1,63 @@
+/*
+ * @adonisjs/env
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import type { Exception } from '@poppinss/utils'
+import { ValidateFn } from '@poppinss/validator-lite'
+
+import { E_INVALID_ENV_VARIABLES } from './exceptions.js'
+
+/**
+ * Exposes the API to validate environment variables against a
+ * pre-defined schema.
+ *
+ * The class is not exported in the main API and used internally.
+ */
+export class EnvValidator<Schema extends { [key: string]: ValidateFn<unknown> }> {
+  #schema: Schema
+  #error: Exception
+
+  constructor(schema: 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: { [K: string]: string | undefined }): {
+    [K in keyof Schema]: ReturnType<Schema[K]>
+  } {
+    const help: string[] = []
+
+    const validated = Object.keys(this.#schema).reduce(
+      (result, key) => {
+        const value = process.env[key] || values[key]
+
+        try {
+          result[key] = this.#schema[key](key, value) as any
+        } catch (error) {
+          help.push(`- ${error.message}`)
+        }
+        return result
+      },
+      { ...values }
+    ) as { [K in keyof Schema]: ReturnType<Schema[K]> }
+
+    if (help.length) {
+      this.#error.help = help.join('\n')
+      throw this.#error
+    }
+
+    return validated
+  }
+}