@dotenvx/dotenvx 1.25.2 → 1.26.1

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.25.2...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v1.26.1...main)
+
+## [1.26.1](https://github.com/dotenvx/dotenvx/compare/v1.26.0...v1.26.1)
+
+### Added
+
+* add typescript type definitions for `main.parse` method ([#475](https://github.com/dotenvx/dotenvx/pull/475))
+
+## [1.26.0](https://github.com/dotenvx/dotenvx/compare/v1.25.2...v1.26.0)
+
+### Added
+
+* add `privateKey` option to `main.parse` method ([#474](https://github.com/dotenvx/dotenvx/pull/474))
 
 ## [1.25.2](https://github.com/dotenvx/dotenvx/compare/v1.25.1...v1.25.2)
 

package/README.md

@@ -1859,8 +1859,59 @@ More examples
   ```
 
   </details>
+* <details><summary>`parse(src)`</summary><br>
 
+  Parse a `.env` string directly in node.js code.
 
+  ```js
+  // index.js
+  const dotenvx = require('@dotenvx/dotenvx')
+  const src = 'HELLO=World'
+  const parsed = dotenvx.parse(src)
+  console.log(`Hello ${parsed.HELLO}`)
+  ```
+
+  ```sh
+  $ node index.js
+  Hello World
+  ```
+
+  </details>
+* <details><summary>`parse(src, {processEnv:})`</summary><br>
+
+  Sometimes, you want to run `parse` without it accessing `process.env`. (You can pass a fake processEnv this way as well - sometimes useful.)
+
+  ```js
+  // index.js
+  const dotenvx = require('@dotenvx/dotenvx')
+  const src = 'USER=Me'
+  const parsed = dotenvx.parse(src, { processEnv: {} })
+  console.log(`Hello ${parsed.USER}`)
+  ```
+
+  ```sh
+  $ node index.js
+  Hello Me
+  ```
+
+  </details>
+* <details><summary>`parse(src, {privateKey:})`</summary><br>
+
+  Decrypt an encrypted `.env` string with `privateKey`.
+
+  ```js
+  // index.js
+  const dotenvx = require('@dotenvx/dotenvx')
+  const src = 'HELLO="encrypted:BE9Y7LKANx77X1pv1HnEoil93fPa5c9rpL/1ps48uaRT9zM8VR6mHx9yM+HktKdsPGIZELuZ7rr2mn1gScsmWitppAgE/1lVprNYBCqiYeaTcKXjDUXU5LfsEsflnAsDhT/kWG1l"'
+  const parsed = dotenvx.parse(src, { privateKey: 'a4547dcd9d3429615a3649bb79e87edb62ee6a74b007075e9141ae44f5fb412c' })
+  console.log(`Hello ${parsed.HELLO}`)
+  ```
+
+  ```sh
+  $ node index.js
+  Hello World
+  ```
+  </details>
 
 &nbsp;
 

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.25.2",
+  "version": "1.26.1",
   "name": "@dotenvx/dotenvx",
   "description": "a better dotenv–from the creator of `dotenv`",
   "author": "@motdotla",

package/src/lib/main.d.ts

@@ -1,5 +1,37 @@
 import type { URL } from 'url';
 
+export interface DotenvParseOptions {
+  /**
+   * 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({ overload: true })
+   * @alias overload
+   */
+  overload?: boolean;
+
+  /**
+   * @default false
+   * @alias override
+   */
+  override?: boolean;
+
+  /**
+   * Specify an object to read existing environment variables from. Defaults to process.env environment variables.
+   *
+   * @default process.env
+   * @example const processEnv = {}; require('@dotenvx/dotenvx').parse('HELLO=World', { processEnv: processEnv })
+   */
+  processEnv?: DotenvPopulateInput;
+
+  /**
+   * Specify a privateKey to decrypt any encrypted contents with.
+   *
+   * @default undefined
+   * @example require('@dotenvx/dotenvx').parse('HELLO="encrypted:BE9Y7LKANx77X1pv1HnEoil93fPa5c9rpL/1ps48uaRT9zM8VR6mHx9yM+HktKdsPGIZELuZ7rr2mn1gScsmWitppAgE/1lVprNYBCqiYeaTcKXjDUXU5LfsEsflnAsDhT/kWG1l"', { privateKey: 'a4547dcd9d3429615a3649bb79e87edb62ee6a74b007075e9141ae44f5fb412c' })
+   */
+  privateKey?: string;
+}
+
 export interface DotenvParseOutput {
   [name: string]: string;
 }
@@ -9,14 +41,16 @@ 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 }`
  * @returns an object with keys and values based on `src`. example: `{ DB_HOST : 'localhost' }`
  */
 export function parse<T extends DotenvParseOutput = DotenvParseOutput>(
-  src: string | Buffer
+  src: string | Buffer,
+  options?: DotenvParseOptions
 ): 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.
    *
@@ -37,16 +71,16 @@ export interface DotenvConfigOptions {
   /**
    * 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 })
+   * @example require('@dotenvx/dotenvx').config({ overload: true })
    * @alias overload
    */
-  override?: boolean;
+  overload?: boolean;
 
   /**
    * @default false
    * @alias override
    */
-  overload?: boolean;
+  override?: boolean;
 
   /**
    * Specify an object to write your secrets to. Defaults to process.env environment variables.
@@ -118,7 +152,7 @@ export interface DotenvPopulateInput {
  *
  * @see https://dotenvx.com/docs
  *
- * @param options - additional options. example: `{ path: './custom/path', encoding: 'latin1', debug: true, override: false }`
+ * @param options - additional options. example: `{ path: './custom/path', encoding: 'latin1', debug: true, overload: false }`
  * @returns an object with a `parsed` key if successful or `error` key if an error occurred. example: { parsed: { KEY: 'value' } }
  *
  */

package/src/lib/main.js

@@ -154,12 +154,20 @@ const parse = function (src, options = {}) {
   }
 
   // private decryption key
-  const privateKey = null // implement later
+  const privateKey = options.privateKey || null
 
   // overload
   const overload = options.overload || options.override
 
-  const { parsed } = new Parse(src, privateKey, processEnv, overload).run()
+  const { parsed, errors } = new Parse(src, privateKey, processEnv, overload).run()
+
+  // display any errors
+  for (const error of errors) {
+    console.error(error.message)
+    if (error.help) {
+      console.error(error.help)
+    }
+  }
 
   return parsed
 }