@adonisjs/env 4.2.0-3 → 4.2.0-4

package/build/index.d.ts

@@ -1,6 +1,5 @@
 export { Env } from './src/env.js';
 export { EnvParser } from './src/parser.js';
 export { EnvLoader } from './src/loader.js';
-export { EnvEditor } from './src/editor.js';
 export * as errors from './src/exceptions.js';
 export { EnvProcessor } from './src/processor.js';

package/build/index.js

@@ -9,6 +9,5 @@
 export { Env } from './src/env.js';
 export { EnvParser } from './src/parser.js';
 export { EnvLoader } from './src/loader.js';
-export { EnvEditor } from './src/editor.js';
 export * as errors from './src/exceptions.js';
 export { EnvProcessor } from './src/processor.js';

package/package.json

@@ -1,19 +1,17 @@
 {
   "name": "@adonisjs/env",
-  "version": "4.2.0-3",
+  "version": "4.2.0-4",
   "description": "Environment variable manager for Node.js",
   "main": "build/index.js",
   "type": "module",
   "files": [
-    "src",
-    "index.ts",
     "build/src",
     "build/index.d.ts",
-    "build/index.d.ts.map",
     "build/index.js"
   ],
   "exports": {
-    ".": "./build/index.js"
+    ".": "./build/index.js",
+    "./editor": "./build/src/editor.js"
   },
   "engines": {
     "node": ">=18.16.0"
@@ -40,25 +38,25 @@
   "author": "virk,adonisjs",
   "license": "MIT",
   "devDependencies": {
-    "@adonisjs/eslint-config": "^1.1.7",
-    "@adonisjs/prettier-config": "^1.1.7",
-    "@adonisjs/tsconfig": "^1.1.7",
-    "@commitlint/cli": "^17.6.6",
-    "@commitlint/config-conventional": "^17.6.6",
+    "@adonisjs/eslint-config": "^1.1.8",
+    "@adonisjs/prettier-config": "^1.1.8",
+    "@adonisjs/tsconfig": "^1.1.8",
+    "@commitlint/cli": "^17.6.7",
+    "@commitlint/config-conventional": "^17.6.7",
     "@japa/assert": "^2.0.0-1",
     "@japa/expect-type": "^2.0.0-0",
     "@japa/file-system": "^2.0.0-1",
     "@japa/runner": "^3.0.0-3",
-    "@swc/core": "^1.3.67",
-    "@types/node": "^20.3.3",
-    "c8": "^8.0.0",
+    "@swc/core": "^1.3.71",
+    "@types/node": "^20.4.5",
+    "c8": "^8.0.1",
     "cross-env": "^7.0.3",
     "del-cli": "^5.0.0",
-    "eslint": "^8.44.0",
+    "eslint": "^8.45.0",
     "github-label-sync": "^2.3.1",
     "husky": "^8.0.3",
     "np": "^8.0.4",
-    "prettier": "^2.8.8",
+    "prettier": "^3.0.0",
     "ts-node": "^10.9.1",
     "typescript": "^5.1.6"
   },

package/index.ts

@@ -1,15 +0,0 @@
-/*
- * @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 { EnvEditor } from './src/editor.js'
-export * as errors from './src/exceptions.js'
-export { EnvProcessor } from './src/processor.js'

package/src/debug.ts

@@ -1,11 +0,0 @@
-/*
- * @adonisjs/env
- *
- * (c) AdonisJS
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-
-import { debuglog } from 'node:util'
-export default debuglog('adonisjs:env')

package/src/editor.ts

@@ -1,84 +0,0 @@
-/*
- * @adonisjs/env
- *
- * (c) AdonisJS
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-
-import splitLines from 'split-lines'
-import lodash from '@poppinss/utils/lodash'
-import { writeFile } from 'node:fs/promises'
-
-import { EnvLoader } from './loader.js'
-
-export class EnvEditor {
-  #appRoot: URL
-  #loader: EnvLoader
-  #files: { contents: string[]; path: string }[] = []
-
-  /**
-   * Creates an instance of env editor and loads .env files
-   * contents.
-   */
-  static async create(appRoot: URL) {
-    const editor = new EnvEditor(appRoot)
-    await editor.load()
-
-    return editor
-  }
-
-  constructor(appRoot: URL) {
-    this.#appRoot = appRoot
-    this.#loader = new EnvLoader(this.#appRoot, true)
-  }
-
-  /**
-   * Loads .env files for editing. Only ".env" and ".env.example"
-   * files are picked for editing.
-   */
-  async load() {
-    const envFiles = await this.#loader.load()
-
-    this.#files = envFiles
-      .filter(
-        (envFile) =>
-          envFile.fileExists &&
-          (envFile.path.endsWith('.env') || envFile.path.endsWith('.env.example'))
-      )
-      .map((envFile) => {
-        return {
-          contents: splitLines(envFile.contents.trim()),
-          path: envFile.path,
-        }
-      })
-  }
-
-  /**
-   * Add key-value pair to the dot-env files.
-   */
-  add(key: string, value: string | number | boolean) {
-    this.#files.forEach((file) => {
-      let entryIndex = file.contents.findIndex((line) => line.startsWith(`${key}=`))
-
-      entryIndex = entryIndex === -1 ? file.contents.length : entryIndex
-      lodash.set(file.contents, entryIndex, `${key}=${String(value)}`)
-    })
-  }
-
-  toJSON() {
-    return this.#files
-  }
-
-  /**
-   * Save changes to the disk
-   */
-  async save() {
-    await Promise.all(
-      this.#files.map((file) => {
-        return writeFile(file.path, file.contents.join('\n'))
-      })
-    )
-  }
-}

package/src/env.ts

@@ -1,134 +0,0 @@
-/*
- * @adonisjs/env
- *
- * (c) AdonisJS
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-
-import { schema as envSchema, type ValidateFn } from '@poppinss/validator-lite'
-import { EnvValidator } from './validator.js'
-import { EnvProcessor } from './processor.js'
-
-/**
- * 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
- * ```
- */
-export class Env<EnvValues extends Record<string, any>> {
-  /**
-   * A cache of env values
-   */
-  #values: EnvValues
-
-  constructor(values: EnvValues) {
-    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<Schema extends { [key: string]: ValidateFn<unknown> }>(
-    appRoot: URL,
-    schema: Schema
-  ): Promise<
-    Env<{
-      [K in keyof Schema]: ReturnType<Schema[K]>
-    }>
-  > {
-    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<T extends { [key: string]: ValidateFn<unknown> }>(schema: T): EnvValidator<T> {
-    const validator = new EnvValidator<T>(schema)
-    return validator
-  }
-
-  /**
-   * 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
-  get(key: string, defaultValue?: any): any {
-    /**
-     * Return cached value
-     */
-    if (this.#values[key] !== undefined) {
-      return this.#values[key]
-    }
-
-    /**
-     * Get value from "process.env" and update the cache
-     */
-    const envValue = process.env[key]
-    if (envValue) {
-      return envValue
-    }
-
-    /**
-     * Return default value when unable to lookup any other value
-     */
-    return defaultValue
-  }
-
-  /**
-   * 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
-  set(key: string | keyof EnvValues, value: any): void {
-    this.#values[key] = value
-    process.env[key as string] = value
-  }
-}

package/src/exceptions.ts

@@ -1,20 +0,0 @@
-/*
- * @adonisjs/env
- *
- * (c) AdonisJS
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-
-import { Exception } from '@poppinss/utils'
-
-/**
- * Exception raised when one or more env variables
- * are invalid
- */
-export const 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: string = ''
-}

package/src/loader.ts

@@ -1,149 +0,0 @@
-/*
- * @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

@@ -1,185 +0,0 @@
-/*
- * @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

@@ -1,83 +0,0 @@
-/*
- * @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

@@ -1,63 +0,0 @@
-/*
- * @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
-  }
-}