@dotenvx/dotenvx 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -2,7 +2,19 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-## [Unreleased](https://github.com/dotenvx/dotenvx/compare/v1.0.0...main)
+## [Unreleased](https://github.com/dotenvx/dotenvx/compare/v1.1.0...main)
+
+## 1.1.0
+
+### Added
+
+* Add TypeScript type definitions ([#272](https://github.com/dotenvx/dotenvx/pull/272))
+
+## 1.0.1
+
+### Changed
+
+* 🐞 Fix expansion when preset on `process.env` and/or with `--overload` ([#271](https://github.com/dotenvx/dotenvx/pull/271))
 
 ## 1.0.0 
 
@@ -34,6 +46,8 @@ All notable changes to this project will be documented in this file. See [standa
 
 This is a BIG release that sets the tone for `dotenvx`'s core offering and features while maintaining room for growth. Thank you everyone for your support and usage of `dotenvx` 🙏.
 
+[blog post: "From dotenv to dotenvx: Next Generation Config Management"](https://dotenvx.com/blog/2024/06/24/dotenvx-next-generation-config-management.html)
+
 ## 0.45.0
 
 ### Changed

package/README.md

@@ -9,7 +9,7 @@
  
 
 
-### Quickstart [![npm version](https://img.shields.io/npm/v/@dotenvx/dotenvx.svg)](https://www.npmjs.com/package/@dotenvx/dotenvx) [![npm installs](https://img.shields.io/npm/dm/@dotenvx/dotenvx)](https://www.npmjs.com/package/@dotenvx/dotenvx)
+### Quickstart [![npm version](https://img.shields.io/npm/v/@dotenvx/dotenvx.svg)](https://www.npmjs.com/package/@dotenvx/dotenvx) [![test count](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/motdotenv/bb76445765a9731e7d824a6efdf53524/raw/dotenvxTestCount.json)](https://github.com/dotenvx/dotenvx/tree/main/tests) [![npm installs](https://img.shields.io/npm/dm/@dotenvx/dotenvx)](https://www.npmjs.com/package/@dotenvx/dotenvx)
 
 Install and use it in code just like `dotenv`.
 
@@ -233,6 +233,17 @@ More examples
   Hello World
   ```
 
+  </details>
+* <details><summary>Clojure 🌿</summary><br>
+
+  ```sh
+  $ echo "HELLO=World" > .env
+  $ echo '(println "Hello" (System/getenv "HELLO"))' > index.clj
+
+  $ dotenvx run -- clojure -M index.clj
+  Hello World
+  ```
+
   </details>
 * <details><summary>.NET 🔵</summary><br>
 
@@ -659,188 +670,10 @@ More examples
 
 &nbsp;
 
-## More
-
-> Go deeper with [extensions](#extensions-), [advaned usage](#advanced-usage-), and [guides](#guides-).
-
-### Extensions 🔌
-
-* <details><summary>`ext ls`</summary><br>
-
-  Print all `.env` files in a tree structure.
-
-  ```sh
-  $ touch .env
-  $ touch .env.production
-  $ mkdir -p apps/backend
-  $ touch apps/backend/.env
-
-  $ dotenvx ext ls
-  ├─ .env.production
-  ├─ .env
-  └─ apps
-     └─ backend
-        └─ .env
-  ```
-
-  </details>
-* <details><summary>`ext ls directory`</summary><br>
-
-  Print all `.env` files inside a specified path to a directory.
-
-  ```sh
-  $ touch .env
-  $ touch .env.production
-  $ mkdir -p apps/backend
-  $ touch apps/backend/.env
-
-  $ dotenvx ext ls apps/backend
-  └─ .env
-  ```
-
-  </details>
-* <details><summary>`ext ls -f`</summary><br>
-
-  Glob `.env` filenames matching a wildcard.
-
-  ```sh
-  $ touch .env
-  $ touch .env.production
-  $ mkdir -p apps/backend
-  $ touch apps/backend/.env
-  $ touch apps/backend/.env.prod
-
-  $ dotenvx ext ls -f **/.env.prod*
-  ├─ .env.production
-  └─ apps
-     └─ backend
-        └─ .env.prod
-  ```
-
-  </details>
-* <details><summary>`ext genexample`</summary><br>
-
-  In one command, generate a `.env.example` file from your current `.env` file contents.
-
-  ```sh
-  $ echo "HELLO=World" > .env
-
-  $ dotenvx ext genexample
-  ✔ updated .env.example (1)
-  ```
-
-  ```ini
-  # .env.example
-  HELLO=""
-  ```
-
-  </details>
-* <details><summary>`ext genexample -f`</summary><br>
-
-  Pass multiple `.env` files to generate your `.env.example` file from the combination of their contents.
-
-  ```sh
-  $ echo "HELLO=World" > .env
-  $ echo "DB_HOST=example.com" > .env.production
-
-  $ dotenvx ext genexample -f .env -f .env.production
-  ✔ updated .env.example (2)
-  ```
-
-  ```ini
-  # .env.example
-  HELLO=""
-  DB_HOST=""
-  ```
-
-  </details>
-* <details><summary>`ext genexample directory`</summary><br>
-
-  Generate a `.env.example` file inside the specified directory. Useful for monorepos.
-
-  ```sh
-  $ echo "HELLO=World" > .env
-  $ mkdir -p apps/backend
-  $ echo "HELLO=Backend" > apps/backend/.env
-
-  $ dotenvx ext genexample apps/backend
-  ✔ updated .env.example (1)
-  ```
-
-  ```ini
-  # apps/backend/.env.example
-  HELLO=""
-  ```
-
-  </details>
-* <details><summary>`ext gitignore`</summary><br>
+## Advanced
 
-  Gitignore your `.env` files.
-
-  ```sh
-  $ dotenvx ext gitignore
-  creating .gitignore
-  appending .env* to .gitignore
-  done
-  ```
-
-  </details>
-* <details><summary>`ext precommit`</summary><br>
-
-  Prevent `.env` files from being committed to code.
-
-  ```sh
-  $ dotenvx ext precommit
-  [dotenvx][precommit] success
-  ```
-
-  </details>
-* <details><summary>`ext precommit --install`</summary><br>
-
-  Install a shell script to `.git/hooks/pre-commit` to prevent accidentally committing any `.env` files to source control.
-
-  ```sh
-  $ dotenvx ext precommit --install
-  [dotenvx][precommit] dotenvx precommit installed [.git/hooks/pre-commit]
-  ```
-
-  </details>
-* <details><summary>`ext prebuild`</summary><br>
-
-  Prevent `.env` files from being built into your docker containers.
-
-  Add it to your `Dockerfile`.
-
-  ```sh
-  RUN curl -fsS https://dotenvx.sh | sh
-
-  ...
-
-  RUN dotenvx ext prebuild
-  CMD ["dotenvx", "run", "--", "node", "index.js"]
-  ```
-
-  </details>
-* <details><summary>`ext scan`</summary><br>
-
-  Use [gitleaks](https://gitleaks.io) under the hood to scan for possible secrets in your code.
-
-  ```sh
-  $ dotenvx ext scan
-
-      ○
-      │╲
-      │ ○
-      ○ ░
-      ░    gitleaks
-
-  100 commits scanned.
-  no leaks found
-  ```
-
-  </details>
-
-### Advanced usage 🎓
+> Become a `dotenvx` power user.
+>
 
 * <details><summary>`run` - Variable Expansion</summary><br>
 
@@ -1355,18 +1188,208 @@ More examples
 
   </details>
 
-### Guides 📖
+### Extensions 🔌
+
+* <details><summary>`ext ls`</summary><br>
+
+  Print all `.env` files in a tree structure.
+
+  ```sh
+  $ touch .env
+  $ touch .env.production
+  $ mkdir -p apps/backend
+  $ touch apps/backend/.env
+
+  $ dotenvx ext ls
+  ├─ .env.production
+  ├─ .env
+  └─ apps
+     └─ backend
+        └─ .env
+  ```
+
+  </details>
+* <details><summary>`ext ls directory`</summary><br>
+
+  Print all `.env` files inside a specified path to a directory.
+
+  ```sh
+  $ touch .env
+  $ touch .env.production
+  $ mkdir -p apps/backend
+  $ touch apps/backend/.env
 
-* [quickstart guides](https://dotenvx.com/docs/quickstart)
-  * [run anywhere](https://dotenvx.com/docs/quickstart/run)
-  * [multi-environment](https://dotenvx.com/docs/quickstart/environments)
-  * [encrypted envs](https://dotenvx.com/docs/quickstart/encryption)
-* [dotenvx/docs](https://dotenvx.com/docs)
-  * [languages](https://dotenvx.com/docs#languages)
-  * [frameworks](https://dotenvx.com/docs#frameworks)
-  * [platforms](https://dotenvx.com/docs#platforms)
-  * [ci/cd](https://dotenvx.com/docs#cis)
+  $ dotenvx ext ls apps/backend
+  └─ .env
+  ```
+
+  </details>
+* <details><summary>`ext ls -f`</summary><br>
+
+  Glob `.env` filenames matching a wildcard.
+
+  ```sh
+  $ touch .env
+  $ touch .env.production
+  $ mkdir -p apps/backend
+  $ touch apps/backend/.env
+  $ touch apps/backend/.env.prod
+
+  $ dotenvx ext ls -f **/.env.prod*
+  ├─ .env.production
+  └─ apps
+     └─ backend
+        └─ .env.prod
+  ```
+
+  </details>
+* <details><summary>`ext genexample`</summary><br>
+
+  In one command, generate a `.env.example` file from your current `.env` file contents.
+
+  ```sh
+  $ echo "HELLO=World" > .env
+
+  $ dotenvx ext genexample
+  ✔ updated .env.example (1)
+  ```
+
+  ```ini
+  # .env.example
+  HELLO=""
+  ```
+
+  </details>
+* <details><summary>`ext genexample -f`</summary><br>
+
+  Pass multiple `.env` files to generate your `.env.example` file from the combination of their contents.
+
+  ```sh
+  $ echo "HELLO=World" > .env
+  $ echo "DB_HOST=example.com" > .env.production
+
+  $ dotenvx ext genexample -f .env -f .env.production
+  ✔ updated .env.example (2)
+  ```
+
+  ```ini
+  # .env.example
+  HELLO=""
+  DB_HOST=""
+  ```
+
+  </details>
+* <details><summary>`ext genexample directory`</summary><br>
+
+  Generate a `.env.example` file inside the specified directory. Useful for monorepos.
+
+  ```sh
+  $ echo "HELLO=World" > .env
+  $ mkdir -p apps/backend
+  $ echo "HELLO=Backend" > apps/backend/.env
+
+  $ dotenvx ext genexample apps/backend
+  ✔ updated .env.example (1)
+  ```
+
+  ```ini
+  # apps/backend/.env.example
+  HELLO=""
+  ```
+
+  </details>
+* <details><summary>`ext gitignore`</summary><br>
+
+  Gitignore your `.env` files.
+
+  ```sh
+  $ dotenvx ext gitignore
+  creating .gitignore
+  appending .env* to .gitignore
+  done
+  ```
+
+  </details>
+* <details><summary>`ext precommit`</summary><br>
+
+  Prevent `.env` files from being committed to code.
+
+  ```sh
+  $ dotenvx ext precommit
+  [dotenvx][precommit] success
+  ```
+
+  </details>
+* <details><summary>`ext precommit --install`</summary><br>
+
+  Install a shell script to `.git/hooks/pre-commit` to prevent accidentally committing any `.env` files to source control.
+
+  ```sh
+  $ dotenvx ext precommit --install
+  [dotenvx][precommit] dotenvx precommit installed [.git/hooks/pre-commit]
+  ```
+
+  </details>
+* <details><summary>`ext prebuild`</summary><br>
+
+  Prevent `.env` files from being built into your docker containers.
+
+  Add it to your `Dockerfile`.
+
+  ```sh
+  RUN curl -fsS https://dotenvx.sh | sh
+
+  ...
+
+  RUN dotenvx ext prebuild
+  CMD ["dotenvx", "run", "--", "node", "index.js"]
+  ```
+
+  </details>
+* <details><summary>`ext scan`</summary><br>
+
+  Use [gitleaks](https://gitleaks.io) under the hood to scan for possible secrets in your code.
+
+  ```sh
+  $ dotenvx ext scan
+
+      ○
+      │╲
+      │ ○
+      ○ ░
+      ░    gitleaks
+
+  100 commits scanned.
+  no leaks found
+  ```
+
+  </details>
+
+&nbsp;
 
+## Guides
+
+> Go deeper into using `dotenvx` with detailed framework and platform guides.
+>
+
+* <a href="https://dotenvx.com/docs/platforms/digital-ocean">Digital Ocean <img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/digitalocean.svg" alt="Digital Ocean Logo" width="20" height="20" style="fill:#0080FF;"></a>
+* <a href="https://dotenvx.com/docs/platforms/docker">Docker <img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/docker.svg" alt="Docker Logo" width="20" height="20" style="fill:#2496ED;"></a>
+* <a href="https://dotenvx.com/docs/platforms/fly">Fly.io</a>
+* <a href="https://dotenvx.com/docs/cis/github-actions">GitHub Actions <img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/github.svg" alt="GitHub Logo" width="20" height="20" style="fill:#181717;"></a>
+* <a href="https://dotenvx.com/docs/platforms/heroku">Heroku <img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/heroku.svg" alt="Heroku Logo" width="20" height="20" style="fill:#430098;"></a>
+* <a href="https://dotenvx.com/docs/platforms/netlify">Netlify <img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/netlify.svg" alt="Netlify Logo" width="20" height="20" style="fill:#00C7B7;"></a>
+* <a href="https://dotenvx.com/docs/package-managers/npm">NPM <img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/npm.svg" alt="NPM Logo" width="20" height="20" style="fill:#CB3837;"></a>
+* <a href="https://dotenvx.com/docs/monorepos/nx">Nx <img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/nx.svg" alt="Nx Logo" width="20" height="20" style="fill:#143055;"></a>
+* <a href="https://dotenvx.com/docs/platforms/render">Render <img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/render.svg" alt="Render Logo" width="20" height="20" style="fill:#000000;"></a>
+* <a href="https://dotenvx.com/docs/platforms/railway">Railway <img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/railway.svg" alt="Railway Logo" width="20" height="20" style="fill:#0B0D0E;"></a>
+* <a href="https://dotenvx.com/docs/monorepos/turborepo">Turborepo <img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/turborepo.svg" alt="Turborepo Logo" width="20" height="20" style="fill:#EF4444;"></a>
+* <a href="https://dotenvx.com/docs/platforms/vercel">Vercel <img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/vercel.svg" alt="Vercel Logo" width="20" height="20" style="fill:#000000;"></a>
+* [more](https://dotenvx.com/docs/guides)
+  * <a href="https://dotenvx.com/docs/guides#node-js">Node.js <img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/nodejs.svg" alt="Node.js Logo" width="20" height="20" style="fill:#5FA04E;"></a>
+  * <a href="https://dotenvx.com/docs/guides#python">Python <img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/python.svg" alt="Python Logo" width="20" height="20" style="fill:#3776AB;"></a>
+  * <a href="https://dotenvx.com/docs/guides#php">PHP <img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/php.svg" alt="PHP Logo" width="20" height="20" style="fill:#777BB4;"></a>
+  * <a href="https://dotenvx.com/docs/guides#ruby">Ruby <img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/ruby.svg" alt="Ruby Logo" width="20" height="20" style="fill:#CC342D;"></a>
+  * <a href="https://dotenvx.com/docs/guides#rust">Rust <img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/rust.svg" alt="Rust Logo" width="20" height="20" style="fill:#000000;"></a>
 
 &nbsp;
 

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0",
+  "version": "1.1.0",
   "name": "@dotenvx/dotenvx",
   "description": "a better dotenv–from the creator of `dotenv`",
   "author": "@motdotla",
@@ -15,6 +15,7 @@
     "CHANGELOG.md"
   ],
   "main": "src/lib/main.js",
+  "types": "src/lib/main.d.ts",
   "bin": {
     "dotenvx": "./src/cli/dotenvx.js",
     "git-dotenvx": "./src/cli/dotenvx.js"
@@ -36,7 +37,6 @@
     "conf": "^10.2.0",
     "diff": "^5.2.0",
     "dotenv": "^16.4.5",
-    "dotenv-expand": "^11.0.6",
     "eciesjs": "^0.4.6",
     "execa": "^5.1.1",
     "glob": "^10.3.10",

package/src/lib/helpers/dotenvExpand.js

@@ -0,0 +1,81 @@
+// * /
+// *   (\\)?            # is it escaped with a backslash?
+// *   (\$)             # literal $
+// *   (?!\()           # shouldnt be followed by parenthesis
+// *   (\{?)            # first brace wrap opening
+// *   ([\w.]+)         # key
+// *   (?::-((?:\$\{(?:\$\{(?:\$\{[^}]*\}|[^}])*}|[^}])*}|[^}])+))? # optional default nested 3 times
+// *   (\}?)            # last brace warp closing
+// * /xi
+
+const DOTENV_SUBSTITUTION_REGEX = /(\\)?(\$)(?!\()(\{?)([\w.]+)(?::?-((?:\$\{(?:\$\{(?:\$\{[^}]*\}|[^}])*}|[^}])*}|[^}])+))?(\}?)/gi
+
+function _resolveEscapeSequences (value) {
+  return value.replace(/\\\$/g, '$')
+}
+
+function interpolate (value, lookups) {
+  return value.replace(DOTENV_SUBSTITUTION_REGEX, (match, escaped, dollarSign, openBrace, key, defaultValue, closeBrace) => {
+    if (escaped === '\\') {
+      return match.slice(1)
+    } else {
+      if (lookups[key]) {
+        // avoid recursion from EXPAND_SELF=$EXPAND_SELF
+        if (lookups[key] === value) {
+          return lookups[key]
+        } else {
+          return interpolate(lookups[key], lookups)
+        }
+      }
+
+      if (defaultValue) {
+        if (defaultValue.startsWith('$')) {
+          return interpolate(defaultValue, lookups)
+        } else {
+          return defaultValue
+        }
+      }
+
+      return ''
+    }
+  })
+}
+
+function expand (options) {
+  let processEnv = process.env
+  if (options && options.processEnv != null) {
+    processEnv = options.processEnv
+  }
+
+  const combined = { ...processEnv, ...options.parsed }
+  const combinedReversed = { ...options.parsed, ...processEnv }
+
+  for (const key in options.parsed) {
+    const value = options.parsed[key]
+
+    // interpolate using both file and processEnv (file interpolation wins. used for --overload later)
+    const fileValue = _resolveEscapeSequences(interpolate(value, combined))
+    options.parsed[key] = fileValue
+
+    if (fileValue === _resolveEscapeSequences(value)) {
+      continue // no change means no expansion, move on
+    }
+
+    if (processEnv[key]) {
+      continue // already has a value in process.env, move on
+    }
+
+    // interpolate with processEnv only (used for default no overload)
+    const processEnvValue = interpolate(value, combinedReversed) // could be empty string ''
+    if (processEnvValue) {
+      processEnv[key] = _resolveEscapeSequences(processEnvValue) // set it
+    }
+  }
+
+  return {
+    parsed: options.parsed,
+    processEnv
+  }
+}
+
+module.exports.expand = expand

package/src/lib/helpers/parseDecryptEvalExpand.js

@@ -1,9 +1,9 @@
 const dotenv = require('dotenv')
-const dotenvExpand = require('dotenv-expand')
 const dotenvEval = require('./dotenvEval')
+const dotenvExpand = require('./dotenvExpand')
 const decryptValue = require('./decryptValue')
 
-function parseDecryptEvalExpand (src, privateKey = null) {
+function parseDecryptEvalExpand (src, privateKey = null, processEnv = process.env) {
   // parse
   const parsed = dotenv.parse(src)
 
@@ -22,19 +22,20 @@ function parseDecryptEvalExpand (src, privateKey = null) {
   }
   const evaled = dotenvEval.eval(inputParsed).parsed
 
-  const expandPlease = {
-    processEnv: {},
-    parsed: { ...process.env, ...evaled } // always treat as overload, then later in the code the inject method takes care of actually setting on process.env via overload or not. this functions job is just to determine what the value would be
+  // expanded
+  const inputEvaled = {
+    processEnv,
+    parsed: evaled
   }
-  const expanded = dotenvExpand.expand(expandPlease).parsed
+  const expanded = dotenvExpand.expand(inputEvaled)
 
-  // but then for logging only log the original keys existing in parsed. this feels unnecessarily complex - like dotenv-expand should support the ability to inject additional `process.env` or objects as it sees fit to the object it wants to expand
+  // for logging only log the original keys existing in parsed. this feels unnecessarily complex - like dotenv-expand should support the ability to inject additional `process.env` or objects as it sees fit to the object it wants to expand
   const result = {}
   for (const key in parsed) {
-    result[key] = expanded[key]
+    result[key] = expanded.parsed[key]
   }
 
-  return result
+  return { parsed: result, processEnv }
 }
 
 module.exports = parseDecryptEvalExpand

package/src/lib/main.d.ts

@@ -0,0 +1,284 @@
+import type { URL } from 'url';
+import type { Change } from 'diff';
+
+export interface DotenvParseOutput {
+  [name: string]: string;
+}
+
+/**
+ * Parses a string or buffer in the .env file format into an object.
+ *
+ * @see https://dotenvx.com/docs
+ * @param src - contents to be parsed. example: `'DB_HOST=localhost'`
+ * @returns an object with keys and values based on `src`. example: `{ DB_HOST : 'localhost' }`
+ */
+export function parse<T extends DotenvParseOutput = DotenvParseOutput>(
+  src: string | Buffer
+): T;
+
+export interface DotenvConfigOptions {
+  /**   *
+   * Specify a custom path if your file containing environment variables is located elsewhere.
+   * Can also be an array of strings, specifying multiple paths.
+   *
+   * @default require('path').resolve(process.cwd(), '.env')
+   * @example require('@dotenvx/dotenvx').config({ path: '/custom/path/to/.env' })
+   * @example require('@dotenvx/dotenvx').config({ path: ['/path/to/first.env', '/path/to/second.env'] })
+   */
+  path?: string | string[] | URL;
+
+  /**
+   * Specify the encoding of your file containing environment variables.
+   *
+   * @default 'utf8'
+   * @example require('@dotenvx/dotenvx').config({ encoding: 'latin1' })
+   */
+  encoding?: string;
+
+  /**
+   * Turn on logging to help debug why certain keys or values are not being set as you expect.
+   *
+   * @default false
+   * @example require('@dotenvx/dotenvx').config({ debug: process.env.DEBUG })
+   */
+  debug?: boolean;
+
+  /**
+   * Override any environment variables that have already been set on your machine with values from your .env file.
+   * @default false
+   * @example require('@dotenvx/dotenvx').config({ override: true })
+   * @alias overload
+   */
+  override?: boolean;
+
+  /**
+   * @default false
+   * @alias override
+   */
+  overload?: boolean;
+
+  /**
+   * Specify an object to write your secrets to. Defaults to process.env environment variables.
+   *
+   * @default process.env
+   * @example const processEnv = {}; require('@dotenvx/dotenvx').config({ processEnv: processEnv })
+   */
+  processEnv?: DotenvPopulateInput;
+
+  /**
+   * Pass the DOTENV_KEY directly to config options. Defaults to looking for process.env.DOTENV_KEY environment variable. Note this only applies to decrypting .env.vault files. If passed as null or undefined, or not passed at all, dotenv falls back to its traditional job of parsing a .env file.
+   *
+   * @default undefined
+   * @example require('@dotenvx/dotenvx').config({ DOTENV_KEY: 'dotenv://:key_1234…@dotenvx.com/vault/.env.vault?environment=production' })
+   */
+  DOTENV_KEY?: string;
+
+  /**
+   * Do not warn for missing .env files
+   */
+  convention?: string;
+}
+
+export interface DotenvConfigOutput {
+  error?: Error;
+  parsed?: DotenvParseOutput;
+}
+
+export interface DotenvPopulateInput {
+  [name: string]: string;
+}
+
+/**
+ * Loads `.env` file contents into process.env by default. If `DOTENV_KEY` is present, it smartly attempts to load encrypted `.env.vault` file contents into process.env.
+ *
+ * @see https://dotenvx.com/docs
+ *
+ * @param options - additional options. example: `{ path: './custom/path', encoding: 'latin1', debug: true, override: false }`
+ * @returns an object with a `parsed` key if successful or `error` key if an error occurred. example: { parsed: { KEY: 'value' } }
+ *
+ */
+export function config(options?: DotenvConfigOptions): DotenvConfigOutput;
+
+/**
+ * Loads `.env` file contents into process.env.
+ *
+ * @see https://dotenvx.com/docs
+ *
+ * @param options - additional options. example: `{ path: './custom/path', encoding: 'latin1', debug: true, override: false }`
+ * @returns an object with a `parsed` key if successful or `error` key if an error occurred. example: { parsed: { KEY: 'value' } }
+ *
+ */
+export function configDotenv(options?: DotenvConfigOptions): DotenvConfigOutput;
+
+/**
+ * Decrypt ciphertext
+ *
+ * @see https://dotenvx.com/docs
+ *
+ * @param encrypted - the encrypted ciphertext string
+ * @param keyStr - the decryption key string
+ */
+export function decrypt(encrypted: string, keyStr: string): string;
+
+export type EncryptRowOutput = {
+  keys: string[];
+  filepath: string;
+  envFilepath: string;
+  publicKey: string;
+  privateKey: string;
+  privateKeyName: string;
+  privateKeyAdded: boolean;
+  envSrc: string;
+  changed: boolean;
+  error?: Error;
+};
+
+export type EncryptOutput = {
+  processedEnvFiles: EncryptRowOutput[];
+  changedFilepaths: string[];
+  unchangedFilepaths: string[];
+};
+
+/**
+ * Encrypt plaintext
+ *
+ * @see https://dotenvx.com/docs
+ * @param envFile - path to the .env file
+ */
+export function encrypt(envFile: string): EncryptOutput;
+
+export type VaultEncryptOutput = {
+  dotenvKeys: Record<string, string>;
+  dotenvKeysFile: string;
+  addedKeys: string[];
+  existingKeys: string[];
+  dotenvVaultFile: string;
+  addedVaults: string[];
+  existingVaults: string[];
+  addedDotenvFilenames: string[];
+  envFile: string | string[];
+};
+
+/**
+ * Encrypt plaintext
+ *
+ * @see https://dotenvx.com/docs
+ * @param directory - current working directory
+ * @param envFile - path to the .env file(s)
+ */
+export function vaultEncrypt(
+  directory: string,
+  envFile: string | string[]
+): VaultEncryptOutput;
+
+/**
+ * List all env files in the current working directory
+ *
+ * @param directory - current working directory
+ * @param envFile - glob pattern to match env files
+ */
+export function ls(directory: string, envFile: string): string[];
+
+/**
+ * Get the value of a key from the .env file
+ *
+ * @param [key] - the key to get the value of
+ * @param [envs] - the environment(s) to get the value from
+ * @param [overload] - whether to overload the value from the .env file
+ * @param [DOTENV_KEY] - the decryption key string
+ * @param [all] - whether to return all values
+ */
+export function get(
+  key?: string,
+  envs: string[] = [],
+  overload = false,
+  DOTENV_KEY = '',
+  all = false
+): Record<string, string | undefined> | string | undefined;
+
+export type SetOutput = {
+  key: string;
+  value: string;
+  filepath: string;
+  envFilepath: string;
+  envSrc: string;
+  changed: boolean;
+  encryptedValue?: string;
+  publicKey?: string;
+  privateKey?: string;
+  privateKeyAdded?: boolean;
+  privateKeyName?: string;
+  error?: Error;
+};
+
+/**
+ * Set the value of a key in the .env file
+ *
+ * @param key - the key to set the value of
+ * @param value - the value to set
+ * @param envFile - the path to the .env file
+ * @param [encrypt] - whether to encrypt the value
+ */
+export function set(
+  key: string,
+  value: string,
+  envFile: string | string,
+  encrypt?: boolean
+): EncryptOutput;
+
+type StatusRow = {
+  filename: string;
+  filepath: string;
+  environment: string;
+  raw: string;
+  decrypted: any;
+  differences: Change[];
+};
+
+export type StatusOutput = {
+  changes: StatusRow[];
+  nochanges: StatusRow[];
+  untracked: StatusRow[];
+};
+
+/**
+ * Check the differences between the .env file and the decrypted values
+ *
+ * @param directory - current working directory
+ */
+export function status(directory: string): StatusOutput;
+
+export type GenExampleOutput = {
+  envExampleFile: string;
+  envFile: string | string[];
+  exampleFilepath: string;
+  addedKeys: string[];
+  injected: Record<string, string>;
+  preExisted: Record<string, string>;
+};
+
+/**
+ * Generate an example .env file
+ *
+ * @param directory - current working directory
+ * @param envFile - path to the .env file(s)
+ */
+export function genexample(
+  directory: string,
+  envFile: string
+): GenExampleOutput;
+
+export type Settings = {
+  DOTENVX_SETTINGS_FILEPATH: string;
+};
+
+type KeyOfSettings = Extract<keyof Settings, string>;
+
+/**
+ * Get the dotenvx settings
+ *
+ * @param [key] - the key to get the value of
+ */
+export function settings(
+  key: KeyOfSettings | undefined | null = null
+): Settings;

package/src/lib/main.js

@@ -1,3 +1,4 @@
+// @ts-check
 const path = require('path')
 const { logger } = require('./../shared/logger')
 const dotenv = require('dotenv')
@@ -18,6 +19,8 @@ const dotenvOptionPaths = require('./helpers/dotenvOptionPaths')
 const { setLogLevel } = require('../shared/logger')
 
 // proxies to dotenv
+
+/** @type {import('./main').config} */
 const config = function (options = {}) {
   // allow user to set processEnv to write to
   let processEnv = process.env
@@ -44,29 +47,46 @@ const config = function (options = {}) {
     for (const optionPath of optionPaths) {
       // if DOTENV_KEY is set then assume we are checking envVaultFile
       if (DOTENV_KEY) {
-        envs.push({ type: 'envVaultFile', value: path.join(path.dirname(optionPath), '.env.vault') })
+        envs.push({
+          type: 'envVaultFile',
+          value: path.join(path.dirname(optionPath), '.env.vault')
+        })
       } else {
         envs.push({ type: 'envFile', value: optionPath })
       }
     }
 
-    const {
-      processedEnvs,
-      readableFilepaths,
-      uniqueInjectedKeys
-    } = new Run(envs, overload, DOTENV_KEY, processEnv).run()
+    const { processedEnvs, readableFilepaths, uniqueInjectedKeys } = new Run(
+      envs,
+      overload,
+      DOTENV_KEY,
+      processEnv
+    ).run()
 
     let lastError
+    /** @type {Record<string, string>} */
     const parsedAll = {}
 
     for (const processedEnv of processedEnvs) {
       if (processedEnv.type === 'envVaultFile') {
-        logger.verbose(`loading env from encrypted ${processedEnv.filepath} (${path.resolve(processedEnv.filepath)})`)
-        logger.debug(`decrypting encrypted env from ${processedEnv.filepath} (${path.resolve(processedEnv.filepath)})`)
+        logger.verbose(
+          `loading env from encrypted ${processedEnv.filepath} (${path.resolve(
+            processedEnv.filepath
+          )})`
+        )
+        logger.debug(
+          `decrypting encrypted env from ${
+            processedEnv.filepath
+          } (${path.resolve(processedEnv.filepath)})`
+        )
       }
 
       if (processedEnv.type === 'envFile') {
-        logger.verbose(`loading env from ${processedEnv.filepath} (${path.resolve(processedEnv.filepath)})`)
+        logger.verbose(
+          `loading env from ${processedEnv.filepath} (${path.resolve(
+            processedEnv.filepath
+          )})`
+        )
       }
 
       if (processedEnv.error) {
@@ -76,7 +96,9 @@ const config = function (options = {}) {
           // do not warn for conventions (too noisy)
           if (!options.convention) {
             logger.warnv(processedEnv.error)
-            logger.help(`? add one with [echo "HELLO=World" > ${processedEnv.filepath}] and re-run [dotenvx run -- yourcommand]`)
+            logger.help(
+              `? add one with [echo "HELLO=World" > ${processedEnv.filepath}] and re-run [dotenvx run -- yourcommand]`
+            )
           }
         } else {
           logger.warnv(processedEnv.error)
@@ -99,8 +121,12 @@ const config = function (options = {}) {
         // verbose/debug preExisted key/value
         const preExisted = processedEnv.preExisted
         for (const [key, value] of Object.entries(preExisted)) {
-          logger.verbose(`${key} pre-exists (protip: use --overload to override)`)
-          logger.debug(`${key} pre-exists as ${value} (protip: use --overload to override)`)
+          logger.verbose(
+            `${key} pre-exists (protip: use --overload to override)`
+          )
+          logger.debug(
+            `${key} pre-exists as ${value} (protip: use --overload to override)`
+          )
         }
       }
     }
@@ -126,47 +152,66 @@ const config = function (options = {}) {
   }
 }
 
+/** @type {import('./main').configDotenv} */
 const configDotenv = function (options) {
   return dotenv.configDotenv(options)
 }
 
+/** @type {import('./main').parse} */
 const parse = function (src) {
   return dotenv.parse(src)
 }
 
+/** @type {import('./main').vaultEncrypt} */
 const vaultEncrypt = function (directory, envFile) {
   return new VaultEncrypt(directory, envFile).run()
 }
 
+/** @type {import('./main').ls} */
 const ls = function (directory, envFile) {
   return new Ls(directory, envFile).run()
 }
 
+/** @type {import('./main').genexample} */
 const genexample = function (directory, envFile) {
   return new Genexample(directory, envFile).run()
 }
 
-const get = function (key, envs = [], overload = false, DOTENV_KEY = '', all = false) {
+/** @type {import('./main').get} */
+const get = function (
+  key,
+  envs = [],
+  overload = false,
+  DOTENV_KEY = '',
+  all = false
+) {
   return new Get(key, envs, overload, DOTENV_KEY, all).run()
 }
 
+/** @type {import('./main').set} */
 const set = function (key, value, envFile, encrypt) {
   return new Sets(key, value, envFile, encrypt).run()
 }
 
+/** @type {import('./main').encrypt} */
 const encrypt = function (envFile) {
   return new Encrypt(envFile).run()
 }
 
+/** @type {import('./main').status} */
 const status = function (directory) {
   return new Status(directory).run()
 }
 
+/** @type {import('./main').settings} */
 const settings = function (key = null) {
+  // @ts-ignore
   return new Settings(key).run()
 }
 
 // misc/cleanup
+
+/** @type {import('./main').decrypt} */
 const decrypt = function (encrypted, keyStr) {
   try {
     return dotenv.decrypt(encrypted, keyStr)
@@ -174,9 +219,15 @@ const decrypt = function (encrypted, keyStr) {
     switch (e.code) {
       case 'DECRYPTION_FAILED':
         // more helpful error when decryption fails
-        logger.error('[DECRYPTION_FAILED] Unable to decrypt .env.vault with DOTENV_KEY.')
-        logger.help('[DECRYPTION_FAILED] Run with debug flag [dotenvx run --debug -- yourcommand] or manually run [echo $DOTENV_KEY] to compare it to the one in .env.keys.')
-        logger.debug(`[DECRYPTION_FAILED] DOTENV_KEY is ${process.env.DOTENV_KEY}`)
+        logger.error(
+          '[DECRYPTION_FAILED] Unable to decrypt .env.vault with DOTENV_KEY.'
+        )
+        logger.help(
+          '[DECRYPTION_FAILED] Run with debug flag [dotenvx run --debug -- yourcommand] or manually run [echo $DOTENV_KEY] to compare it to the one in .env.keys.'
+        )
+        logger.debug(
+          `[DECRYPTION_FAILED] DOTENV_KEY is ${process.env.DOTENV_KEY}`
+        )
         process.exit(1)
         break
       default:

package/src/lib/services/genexample.js

@@ -57,7 +57,9 @@ class Genexample {
     }
 
     const currentEnvExample = dotenv.configDotenv({ path: exampleFilepath }).parsed
+    /** @type {Record<string, string>} */
     const injected = {}
+    /** @type {Record<string, string>} */
     const preExisted = {}
 
     for (const key of [...keys]) {

package/src/lib/services/get.js

@@ -21,6 +21,7 @@ class Get {
 
       // typical scenario - return only envs that were identified in the .env file
       // iterate over all processedEnvs.parsed and grab from processEnv
+      /** @type {Record<string, string>} */
       const result = {}
       for (const processedEnv of processedEnvs) {
         // parsed means we saw the key in a file or --env flag. this effectively filters out any preset machine envs - while still respecting complex evaluating, expansion, and overload. in other words, the value might be the machine value because the key was displayed in a .env file

package/src/lib/services/run.js

@@ -63,7 +63,8 @@ class Run {
     row.string = env
 
     try {
-      const parsed = parseDecryptEvalExpand(env)
+      const { parsed } = parseDecryptEvalExpand(env, null, this.processEnv)
+
       row.parsed = parsed
       this.readableStrings.add(env)
 
@@ -93,7 +94,7 @@ class Run {
 
       // if DOTENV_PRIVATE_KEY_* already set in process.env then use it
       const privateKey = smartDotenvPrivateKey(envFilepath)
-      const parsed = parseDecryptEvalExpand(src, privateKey)
+      const { parsed } = parseDecryptEvalExpand(src, privateKey, this.processEnv)
       row.parsed = parsed
 
       const { injected, preExisted } = this._inject(this.processEnv, parsed, this.overload)
@@ -162,7 +163,7 @@ class Run {
 
     try {
       // parse this. it's the equivalent of the .env file
-      const parsed = parseDecryptEvalExpand(decrypted)
+      const { parsed } = parseDecryptEvalExpand(decrypted, null, this.processEnv)
       row.parsed = parsed
 
       const { injected, preExisted } = this._inject(this.processEnv, parsed, this.overload)