@dotenvx/dotenvx 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -2,7 +2,13 @@
 
 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.1...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
 

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>
 

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.1",
+  "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"

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