@dotenvx/dotenvx 1.30.1 → 1.31.0

package/CHANGELOG.md

@@ -2,7 +2,14 @@
 
 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.30.1...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v1.31.0...main)
+
+## [1.31.0](https://github.com/dotenvx/dotenvx/compare/v1.30.1...v1.31.0)
+
+### Added
+
+* expose `main.set` function ([#492](https://github.com/dotenvx/dotenvx/pull/492))
+* add missing types for `main.config` ([#491](https://github.com/dotenvx/dotenvx/pull/491))
 
 ## [1.30.1](https://github.com/dotenvx/dotenvx/compare/v1.30.0...v1.30.1)
 

package/README.md

@@ -2081,6 +2081,17 @@ More examples
   Hello World
   ```
   </details>
+* <details><summary>`set(KEY, value)`</summary><br>
+
+  Programatically set an environment variable. 
+
+  ```js
+  // index.js
+  const dotenvx = require('@dotenvx/dotenvx')
+  dotenvx.set('HELLO', 'World', { path: '.env' })
+  ```
+
+  </details>
 
 &nbsp;
 

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.30.1",
+  "version": "1.31.0",
   "name": "@dotenvx/dotenvx",
   "description": "a better dotenv–from the creator of `dotenv`",
   "author": "@motdotla",
@@ -28,7 +28,6 @@
     "standard:fix": "standard --fix",
     "test": "tap run --allow-empty-coverage --disable-coverage --timeout=60000",
     "test-coverage": "tap run --show-full-coverage --timeout=60000",
-    "test-single": "tap run --coverage-report=none tests/cli/actions/decrypt.test.js",
     "testshell": "bash shellspec",
     "prerelease": "npm test && npm run testshell",
     "release": "standard-version"

package/src/lib/helpers/buildEnvs.js

@@ -0,0 +1,33 @@
+const path = require('path')
+
+const conventions = require('./conventions')
+const dotenvOptionPaths = require('./dotenvOptionPaths')
+const DeprecationNotice = require('./deprecationNotice')
+
+function buildEnvs (options, DOTENV_KEY = undefined) {
+  // build envs using user set option.path
+  const optionPaths = dotenvOptionPaths(options) // [ '.env' ]
+
+  let envs = []
+  if (options.convention) { // handle shorthand conventions
+    envs = conventions(options.convention).concat(envs)
+  }
+
+  new DeprecationNotice({ DOTENV_KEY }).dotenvKey() // DEPRECATION NOTICE
+
+  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')
+      })
+    } else {
+      envs.push({ type: 'envFile', value: optionPath })
+    }
+  }
+
+  return envs
+}
+
+module.exports = buildEnvs

package/src/lib/main.d.ts

@@ -41,7 +41,7 @@ export interface DotenvParseOutput {
  *
  * @see https://dotenvx.com/docs
  * @param src - contents to be parsed. example: `'DB_HOST=localhost'`
- * @param options - additional options. example: `{ prcoessEnv: {}, privateKey: '<privateKey>', overload: false }`
+ * @param options - additional options. example: `{ processEnv: {}, privateKey: '<privateKey>', overload: false }`
  * @returns an object with keys and values based on `src`. example: `{ DB_HOST : 'localhost' }`
  */
 export function parse<T extends DotenvParseOutput = DotenvParseOutput>(
@@ -82,6 +82,21 @@ export interface DotenvConfigOptions {
    */
   override?: boolean;
 
+  /**
+   * Throw immediately if an error is encountered - like a missing .env file.
+   * @default false
+   * @example require('@dotenvx/dotenvx').config({ strict: true })
+   */
+  strict?: boolean;
+
+  /**
+   * Suppress specific errors like MISSING_ENV_FILE. The error keys can be found
+   * in src/lib/helpers/errors.js
+   * @default []
+   * @example require('@dotenvx/dotenvx').config({ ignore: ['MISSING_ENV_FILE'] })
+   */
+  ignore?: string[];
+
   /**
    * Specify an object to write your secrets to. Defaults to process.env environment variables.
    *
@@ -90,6 +105,13 @@ export interface DotenvConfigOptions {
    */
   processEnv?: DotenvPopulateInput;
 
+  /**
+   * Customize the path to your .env.keys file. This is useful with monorepos.
+   * @default []
+   * @example require('@dotenvx/dotenvx').config({ envKeysFile: '../../.env.keys'} })
+   */
+  envKeysFile?: string;
+
   /**
    * 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.
    *
@@ -158,6 +180,59 @@ export interface DotenvPopulateInput {
  */
 export function config(options?: DotenvConfigOptions): DotenvConfigOutput;
 
+export interface SetOptions {
+  /**
+   * 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').set(key, value, { path: '/custom/path/to/.env' })
+   * @example require('@dotenvx/dotenvx').set(key, value, { path: ['/path/to/first.env', '/path/to/second.env'] })
+   */
+  path?: string | string[] | URL;
+
+  /**
+   * Customize the path to your .env.keys file. This is useful with monorepos.
+   * @default []
+   * @example require('@dotenvx/dotenvx').config(key, value, { envKeysFile: '../../.env.keys'} })
+   */
+  envKeysFile?: string;
+
+  /**
+   * Set a .env convention (available conventions: 'nextjs')
+   */
+  convention?: string;
+}
+
+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 a single environment variable.
+ *
+ * @see https://dotenvx.com/docs
+ * @param key - KEY 
+ * @param value - value
+ * @param options - additional options. example: `{ encrypt: false }`
+ */
+export function set(
+  key: string,
+  value: string,
+  options?: SetOptions
+): SetOutput;
+
 /**
  * List all env files in the current working directory
  *

package/src/lib/main.js

@@ -8,14 +8,13 @@ const { getColor, bold } = require('./../shared/colors')
 // services
 const Ls = require('./services/ls')
 const Run = require('./services/run')
+const Sets = require('./services/sets')
 const Keypair = require('./services/keypair')
 const Genexample = require('./services/genexample')
 
 // helpers
-const conventions = require('./helpers/conventions')
-const dotenvOptionPaths = require('./helpers/dotenvOptionPaths')
+const buildEnvs = require('./helpers/buildEnvs')
 const Parse = require('./helpers/parse')
-const DeprecationNotice = require('./helpers/deprecationNotice')
 
 /** @type {import('./main').config} */
 const config = function (options = {}) {
@@ -45,30 +44,8 @@ const config = function (options = {}) {
 
   if (options) setLogLevel(options)
 
-  // build envs using user set option.path
-  const optionPaths = dotenvOptionPaths(options) // [ '.env' ]
-
   try {
-    let envs = []
-    // handle shorthand conventions - like --convention=nextjs
-    if (options.convention) {
-      envs = conventions(options.convention).concat(envs)
-    }
-
-    new DeprecationNotice({ DOTENV_KEY }).dotenvKey() // DEPRECATION NOTICE
-
-    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')
-        })
-      } else {
-        envs.push({ type: 'envFile', value: optionPath })
-      }
-    }
-
+    const envs = buildEnvs(options, DOTENV_KEY)
     const {
       processedEnvs,
       readableFilepaths,
@@ -182,6 +159,25 @@ const parse = function (src, options = {}) {
   return parsed
 }
 
+/* @type {import('./main').set} */
+const set = function (key, value, options = {}) {
+  // encrypt
+  let encrypt = true
+  if (options.plain) {
+    encrypt = false
+  } else if (options.encrypt === false) {
+    encrypt = false
+  }
+
+  // envKeysFile
+  const envKeysFile = options.envKeysFile
+
+  // envs
+  const envs = buildEnvs(options)
+
+  return new Sets(key, value, envs, encrypt, envKeysFile).run()
+}
+
 /** @type {import('./main').ls} */
 const ls = function (directory, envFile, excludeEnvFile) {
   return new Ls(directory, envFile, excludeEnvFile).run()
@@ -207,6 +203,7 @@ module.exports = {
   config,
   parse,
   // actions related
+  set,
   ls,
   keypair,
   genexample,