chainflow 0.1.9 → 5.0.3

package/README.md

@@ -1,599 +1,633 @@
-<h1 align="center" style="border-bottom: none;">🌊hainflow</h1>
-<h3 align="center">An Open Source library to create dynamic and composable API call workflows in TypeScript.</h3>
-<div align="center">
-  
-[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/edwinlzs/chainflow/blob/main/LICENSE)
-&nbsp;
-[![NPM version](https://img.shields.io/npm/v/chainflow.svg?style=flat-square)](https://www.npmjs.com/package/chainflow)
-&nbsp;
-[![GitHub Actions](https://img.shields.io/github/actions/workflow/status/edwinlzs/chainflow/ci.yml?style=flat-square&branch=main)](https://github.com/edwinlzs/chainflow/actions)
-&nbsp;
-[![codecov](https://img.shields.io/codecov/c/gh/edwinlzs/chainflow?token=O55JNRTCM5&style=flat-square&color=23a133)](https://codecov.io/gh/edwinlzs/chainflow)
-</div>
-
-## 📖 Documentation
-
-### Read the guides over at [Chainflow Docs](https://edwinlzs.github.io/chainflow-docs/) to get started!
-
-## ⚠️ (Important!) Note
-
-Chainflow is my first and somewhat experimental open-source project which I started to assist my own dev work. It's similar to [Postman Flows](https://learning.postman.com/docs/postman-flows/gs/flows-overview/), but done in code so us engineers have more control to weave logic in between API endpoint calls (+ the ease of writing simple scripts with Chainflow to be run in your CLI or as pipeline jobs etc.).
-
-I am still finding and ironing out pain points in using the library and releases should be considered unstable while I improve the library's usability. It is far from perfect in its current state, but I will continue to improve upon it if I or others find potential in its use. Therefore, your feedback and ideas are very important to me. I welcome thoughts on just about anything - useful dev tools to manage this project, QoL features to support easier coding patterns when using this library or even thoughts on the future direction of this project.
-
-Drop them as a [Github issue](https://github.com/edwinlzs/chainflow/issues) or email me at <edwinlzscode@gmail.com>!
-
-## 💭 When might Chainflow be useful?
-
-1. **_Setting up demo data_**
-
-   Say you have an app that you're developing new features for and you'd like to demo those features. You need your app to be in a certain context and your database in a specific state - perhaps that context requires that a user has logged in with certain permissions, has created a "group" in the app and has added other users to that group. To create that context, you could manually click through your app to log in as a user and set everything up, but that could be tedious. Alternatively, you may use raw SQL or other DB scripts to directly manipulate the DB and insert users, roles, etc. However, those scripts could miss out on important side effects relevant to the business context of your app - side effects that tend to be triggered by services exposed by your backend server.
-
-   Instead, you can setup the context in your app by calling the relevant service endpoints you have built (`POST /user`, `POST /role`, etc.) and triggering their business logic to make your data setup adhere closely to the way your app truly behaves - as if a user was _really_ logging in and doing everything. Chainflow helps you do this by providing tools to compose API call workflows. You can then avoid manual setups and minimize your use of database scripts to just data that is not configurable with existing endpoints!
-
-2. **_Speeding up development_**
-
-   Similar to setting up demo data, while coding new features you may often want to test out how they behave in your app, and again you may want your app to be in a specific state locally for that. You can write API call workflow scripts built with Chainflow to help move your app into those states quickly.
-
-3. **_Testing your endpoints_**
-
-   An API call workflow could behave as if it were a frontend client calling the backend. In that way, you can run UI-agnostic end-to-end testing of backend endpoints by using API call workflows to simulate how a frontend would interact with the backend.
-
-## Basic Usage
-
-_Note: Chainflow may not be compatible with Node versions past end-of-life (v16.x and below)._
-
-```console
-npm install --save-dev chainflow
-```
-
-`origin` creates a template on which you define your API endpoints by calling the endpoint's HTTP method verb (e.g. `post`, `patch`) as methods.
-
-```typescript
-import { origin } from chainflow;
-
-const backend = origin('127.0.0.1:5000');
-
-const createUser = backend.post('/user').body({
-  name: 'Tom',
-  details: {
-    age: 40,
-  },
-});
-
-const createRole = backend.post('/role').body({
-  type: 'Engineer',
-  userId: createUser.resp.body.id,
-});
-
-const getUser = backend.get('/user').query({
-  roleType: createRole.resp.body.type,
-});
-```
-
-Use a `chainflow` to define a sequence of endpoint calls that take advantage of the values and links provided above.
-
-```typescript
-import { chainflow } from Chainflow;
-
-const flow = chainflow()
-  .call(createUser)
-  .call(createRole)
-  .call(getUser);
-
-flow.run();
-```
-
----
-
-\
-The above setup will result in the following endpoint calls:
-
-1. `POST` Request to `/user` with body:
-
-   ```json
-   {
-     "name": "Tom",
-     "details": {
-       "age": 40
-     }
-   }
-   ```
-
-2. `POST` Request to `/role` with body:
-
-   ```json
-   {
-     "type": "Engineer",
-     "userId": "['userId' from response to step 1]"
-   }
-   ```
-
-3. `GET` Request to `/user?roleType=['type' from response to step 2]`
-
-&nbsp;
-
-## More Features
-
-### Query params
-
-Define query params with the `query` method on an endpoint.
-
-```typescript
-const getUsersInGroup = backend.get('/user').query({ groupId: 'some-id' });
-```
-
-### Path params
-
-Define path params by wrapping a param name with `{}` in the endpoint path.
-
-```typescript
-const getGroupsWithUser = backend.get('/groups/{userId}');
-```
-
-You can specify values for your path params by calling `pathParams`. Note that path params which do not actually exist in the path will be discarded.
-
-```typescript
-const getGroupsWithUser = backend.get('/groups/{userId}').pathParams({
-  userId: 'user123',
-});
-```
-
-### Headers
-
-Specify headers with `headers` method on endpoints.
-
-```typescript
-const getInfo = backend.get('/info').headers({ token: 'some-token' });
-```
-
-You can also use `headers` on an `Origin` to have all endpoints made for that origin bear those headers.
-
-```typescript
-const backend = origin('127.0.0.1:3001').headers({ token: 'some-token' });
-
-const getInfo = backend.get('/info'); // getInfo endpoint will have the headers defined above
-```
-
-### Default headers
-
-Chainflow attaches default headers to all requests made by any endpoint with the value:
-
-```typescript
-'content-type': 'application/json',
-'User-Agent': 'Chainflow/[major.minor version number]',
-```
-
-If you'd like to change this, pass your default headers to the `defaultHeaders` util.
-
-```typescript
-import { defaultHeaders } from 'chainflow';
-
-defaultHeaders({ 'content-type': 'application/xml' });
-```
-
-Pass in `true` as the second argument if you want to replace the entire set of default headers. Otherwise, the example above only overwrites the `content-type` default header and keeps `User-Agent`.
-
-### Initializing Values
-
-The request payloads under `Basic Usage` are defined with only _default_ values - i.e. the values which a Chainflow use if there are no response values from other endpoint calls linked to it.
-
-However, you can also use the following features to more flexibly define the values used in a request.
-
-### `required`
-
-Marks a value as required but without a default. The chainflow will expect this value to be sourced from another node. If no such source is available, the endpoint call will throw an error.
-
-```typescript
-const createUser = backend.post('/user').body({
-  name: required(),
-});
-```
-
-### `gen`
-
-Provide a callback that generates values for building requests.
-
-```typescript
-const randAge = () => Math.floor(Math.random() * 100);
-
-const createUser = backend.post('/user').body({
-  name: 'Tom',
-  details: {
-    age: gen(randAge),
-  },
-});
-```
-
-### `link`
-
-You can use the `link` function to specify a callback to transform the response value before it is passed to the input node.
-
-```typescript
-const addGreeting = (name: string) => `Hello ${name}`;
-
-const createMessage = backend.post('message').body({
-  msg: link(getUser.resp.body.name, addGreeting);
-});
-```
-
-### `set`
-
-The `link` has another function signature.
-
-You can use the `set` method on an endpoint to expose its input nodes, then use the 2nd function signature of `link` as shown below: pass in the input node first (`msg`), then the source node second and optionally a callback third.
-
-```typescript
-createMessage.set(({ body: { msg } }) => {
-  link(msg, getUser.resp.body.name);
-  link(msg, createUser.resp.body.name);
-});
-```
-
-With a callback:
-
-```typescript
-createMessage.set(({ body: { msg } }) => {
-  link(msg, getUser.resp.body.name, addGreeting);
-  link(msg, createUser.resp.body.name, addGreeting);
-});
-```
-
-### `linkMerge`
-
-Link multiple response values to a single request node with an optional callback to merge the values into a single input value. This has 4 function signatures:
-
-For the argument containing the source nodes, you can either pass an _array_ of SourceNodes:
-
-```typescript
-// note the callback has an array parameter
-const mergeValues = ([name, favAnimal]: [string, string]) =>
-  `${name} likes ${favAnimal}.`;
-
-const createMessage = backend.post('message').body({
-  msg: linkMerge(
-    // array of source nodes
-    [getUser.resp.body.name, getFavAnimal.resp.body.favAnimal],
-    mergeValues,
-  );
-});
-```
-
-or you can pass an _object_ with SourceNodes as the values:
-
-```typescript
-// note the callback has an object parameter
-const mergeValues = ({
-  userName,
-  favAnimal,
-}: {
-  userName: string;
-  favAnimal: string;
-}) => `${userName} likes ${favAnimal}.`;
-
-
-const createMessage = backend.post('message').body({
-  msg: linkMerge(
-    // object of source nodes
-    {
-      userName: getUser.resp.body.name,
-      favAnimal: getFavAnimal.resp.body.favAnimal,
-    },
-    mergeValues,
-  );
-});
-```
-
-alternatively, you can use the `set` method in addition with the other function signature of `linkMerge` (similar to how `link` above has overloads to work with `set`).
-
-with array:
-
-```typescript
-createMessage.set(({ body: { msg } }) => {
-  linkMerge(
-    msg, // the input node
-    [getUser.resp.body.name, getFavAnimal.resp.body.favAnimal],
-    mergeValues,
-  );
-});
-```
-
-with object:
-
-```typescript
-createMessage.set(({ body: { msg } }) => {
-  linkMerge(
-    msg, // the input node
-    {
-      userName: getUser.resp.body.name,
-      favAnimal: getFavAnimal.resp.body.favAnimal,
-    },
-    mergeValues,
-  );
-});
-```
-
-Note that the merging link created by this method will only be used if ALL the source nodes specified are available i.e. if either one of `getUser.resp.body.name` or `getFavAnimal.resp.body.favAnimal` does not have a value, this link will not be used at all.
-
-### Call Options
-
-You can declare manual values for an endpoint call in the chainflow itself, should you need to do so, by passing in a Call Options object as a second argument in the `call` method.
-
-`body`, `pathParams`, `query` and `headers` can be set this way.
-
-```typescript
-const createUser = backend.post('/user').body({
-  name: 'Tom',
-});
-
-chainflow()
-  .call(createUser, { body: { name: 'Harry' } })
-  .run();
-```
-
-### `seed`
-
-You can specify request nodes to take values from the chainflow 'seed' by importing the `seed` object and linking nodes to it. Provide actual seed values by calling the `seed` method on a chainflow before you `run` it, like below.
-
-```typescript
-import { chainflow, link seed, } from 'chainflow';
-
-const createUser = backend.post('/user').body({
-  name: required(),
-});
-
-createUser.set(({ body: { name }}) => {
-  link(name, seed.username);
-});
-
-chainflow()
-  .call()
-  .seed({ username: 'Tom' })
-  .run();
-```
-
-### Allow Undefined Sources Values
-
-By default, an input node will reject and skip a source node's value if it is unavailable or `undefined`. However, you can change this by passing a source node into the `config` utility function and passing an options object as the second parameter like below. This informs an input node to use the source node's value regardless of whether the value is `undefined` or not.
-
-```typescript
-import { config } from 'chainflow';
-
-createUser.set(({ body: { name } }) => {
-  link(name, config(seed.username, { allowUndefined: true }));
-});
-```
-
-This has important implications - it means that as long as the source (e.g. a response from an endpoint call) is available, then the linked source node's value will be taken and used (even if that value is unavailable, which would be taken as `undefined`). Therefore, any other linked sources will not be used UNLESS 1. they have a higher priority or 2. the source providing the linked node that allows `undefined` is unavailable.
-
-&nbsp;
-
-### `clone`
-
-You can create chainflow "templates" with the use of `clone` to create a copy of a chainflow and its endpoint callqueue. The clone can have endpoint calls added to it without modifying the initial flow.
-
-```typescript
-const initialFlow = chainflow().call(endpoint1).call(endpoint2);
-
-const clonedFlow = initialFlow.clone();
-
-clonedFlow.call(endpoint3).run(); // calls endpoint 1, 2 and 3
-initialFlow.call(endpoint4).run(); // calls endpoint 1, 2 and 4
-```
-
-### `extend`
-
-You can connect multiple different chainflows together into a longer chainflow using `extend`.
-
-```typescript
-const flow1 = chainflow().call(endpoint1).call(endpoint2);
-const flow2 = chainflow().call(endpoint3);
-
-flow1.extend(flow2).run(); // calls endpoint 1, 2 and 3
-```
-
-### `config`
-
-`respParser`  
-By default, a chainflow parses response bodies as JSON objects UNLESS the status code is `204` or the `content-type` header does not contain `application/json` (to avoid errors when parsing an empty body), upon which they will instead parse it as text.
-
-To set a specific parsing format, you can call `.config` to change that configuration on an `endpoint` (or on an `Origin`, to apply it to all endpoints created from it) like so:
-
-```typescript
-import { RESP_PARSER } from 'chainflow';
-
-const getUser = backend.get('/user').config({
-  respParser: RESP_PARSER.TEXT,
-});
-```
-
-or with camelcase in JavaScript:
-
-```javascript
-const getUser = backend.get('/user').config({
-  respParser: 'text',
-});
-```
-
-There are 4 supported ways to parse response bodies (provided by the underlying HTTP client `undici`): `arrayBuffer`, `blob`, `json` and `text`.
-
-`respValidator`  
-Another configuration option is how to validate the response to an endpoint. By default, Chainflow rejects responses that have HTTP status code 400 and above and throws an error. You can pass in a custom `respValidator` to change when a response is rejected.
-
-```typescript
-const getUser = backend.get('/user').config({
-  respValidator: (resp) => {
-    if (resp.statusCode !== 201) return { valid: false, msg: 'Failed to retrieve users.' };
-    if (!Object.keys(resp.body as Record<string, unknown>).includes('id'))
-      return { valid: false, msg: 'Response did not provide user ID.' };
-    return { valid: true };
-  },
-});
-```
-
-Your custom validator callback should have a return type:
-
-```typescript
-{
-  valid: boolean; // false if response should be rejected
-  msg?: string; // error message
-}
-```
-
-### `store`
-
-Instead of direct links between endpoints, you can use a central store to keep values from some endpoints and have other endpoints take from it via the special `store` object.
-
-```typescript
-import { store } from 'chainflow';
-
-const createUser = backend
-  .post('/user')
-  .body({
-    name: 'Tom',
-  })
-  .store((resp) => ({
-    // this endpoint will store `id` from a response to `userId` in the store
-    userId: resp.body.id,
-  }));
-
-const addRole = backend.post('/role').body({
-  // this endpoint will take `userId` from the store, if available
-  userId: store.userId,
-  role: 'Engineer',
-});
-
-chainflow().call(createUser).call(addRole).run();
-```
-
-This is usually useful when you have endpoints that could take a value from any one of many other endpoints for the same input node. Having a store to centralise these many-to-many relationships (like an API Gateway) can improve the developer experience.
-
-### `continuesFrom` - transferring Chainflow states
-
-Say we have 2 endpoints, `login` and `createGroup`. We want to login as a user once, then proceed to proceed 3 groups as that same user without having to login 3 times.
-
-```typescript
-const createGroup = backend
-  .post('/group')
-  .headers({
-    Authorization: login.resp.body.authToken,
-  })
-  .body({
-    groupName: seed.groupName,
-  });
-
-// loggedInFlow will contain a response from the `login` endpoint
-const loggedInFlow = chainflow().call(login).run();
-
-// createGroupFlow will take the response that
-// loggedInFlow received and carry on from there
-const createGroupFlow = chainflow().call(createGroup).continuesFrom(loggedInFlow);
-
-const groupNames = ['RapGPT', 'Averageexpedition', 'Shaky Osmosis'];
-for (const groupName in groupNames) {
-  createGroupFlow.seed({ groupName }).run();
-}
-```
-
-We run a chainflow that calls `login` first to get a response from the login endpoint.
-
-Using the `continuesFrom` method, `createGroupFlow` will copy the state of source values (i.e. responses) from `loggedInFlow`. This means `createGroupFlow` will now have the logged in user's `authToken` received from calling `login`, and will use it when calling `createGroup` thrice for each group name in the `groupNames` array.
-
-### `events`
-
-After running a chainflow, you can retrieve the request and response event data from endpoint calls executed during that run via the `events` property on that chainflow.
-
-```typescript
-const flow = chainflow().run(createUser).run(getRoles);
-
-const events = flow.events;
-```
-
-The events will look something like:
-
-```typescript
-[
-  {
-    details: '[POST] /user', // identifies the endpoint called
-    req: {
-      method: 'POST',
-      url: ...,
-      body: ...,
-      headers: ...,
-      respParser: ..., // the format used to parse the response body
-    },
-    resp: {
-      statusCode: 200,
-      body: ...,
-      headers: ...,
-      ...
-    }
-  },
-  {
-    details: '[GET] /roles',
-    req: ...,
-    resp: ...
-  }
-]
-```
-
-The responses in the array follow the order in which the respective endpoints are called.
-
-### `logging`
-
-Log requests/responses in your console by setting `ENABLE_CHAINFLOW_LOGS=true` in your environment variables, or by simply importing and calling the `enableLogs` function.
-
-```typescript
-import { enableLogs } from 'chainflow';
-
-enableLogs();
-```
-
-### Misc Behaviors
-
-- If you have multiple endpoint calls to the same endpoint on one chainflow and they are linked to other endpoints' input nodes further down the flow, the latest endpoint call's values will be used.
-
-For example:
-
-```typescript
-chainflow()
-  .call(getUser) // 1st call
-  .call(addRole)
-  .call(getUser) // 2nd call
-  .call(createGroup);
-```
-
-If an input node on `createGroup` requires a value from a response to `getUser`, then `createGroup` will take that value from the latest call to `getUser` (i.e. from the response to the 2nd call to `getUser` _after_ the call to `addRole`).
-
-## Future Updates
-
-Below features are currently not yet supported but are planned in future releases.
-
-1. More flexibility to log and return responses
-2. Conditional calls - execute an endpoint call only if some condition is met
-3. (Exploratory) API performance measurement
-4. (Exploratory) Possibly some sort of UI/diagram generation
-
-## Development
-
-### Areas that could be better (non-exhaustive)
-
-#### _Encoding endpoint IDs_
-
-- Currently assumes that URLs of endpoints do not contain unencoded `|` and `[]` characters. `[]` used to wrap around HTTP method in the encoded ID. Linkmerge uses `|` to separate different encoded IDs.
-- Current implementation also leads to ID collision if multiple endpoints with the same method and path are created (but perhaps with different configuration) and are called on the same chainflow.
-- Idea: Have a centralized service to issue unique IDs to deconflict endpoints - but still somehow encode the method/path info of an endpoint into it.
-
-#### _Logging_
-
-- Should further explore appropriate degree of detail for logging
-- Truncation of requests/responses with extremely large payloads
-
-#### _Proxy performance_
-
-- Creating proxies recursively when defining `SourceNode` paths could hit performance - not rigorously tested yet, so not 100% sure of how significant it is
-
-### Trivia
-
-- You probably noticed that I enjoy using the Builder pattern for its clarity.
-- I'm praying the wave 🌊 emoji remains sufficiently shaped like a "C" to avoid confusion. Please let me know if there is some system where it does not!
+<div align="center">
+
+<p>
+  <sup>
+    <a href="https://github.com/sponsors/motdotla">Dotenv is supported by the community.</a>
+  </sup>
+</p>
+<sup>Special thanks to:</sup>
+<br>
+<br>
+<a href="https://www.warp.dev/?utm_source=github&utm_medium=referral&utm_campaign=dotenv_p_20220831">
+  <div>
+    <img src="https://res.cloudinary.com/dotenv-org/image/upload/v1661980709/warp_hi8oqj.png" width="230" alt="Warp">
+  </div>
+  <b>Warp is a blazingly fast, Rust-based terminal reimagined to work like a modern app.</b>
+  <div>
+    <sup>Get more done in the CLI with real text editing, block-based output, and AI command search.</sup>
+  </div>
+</a>
+<br>
+<a href="https://retool.com/?utm_source=sponsor&utm_campaign=dotenv">
+  <div>
+    <img src="https://res.cloudinary.com/dotenv-org/image/upload/c_scale,w_300/v1664466968/logo-full-black_vidfqf.png" width="270" alt="Retool">
+  </div>
+  <b>Retool helps developers build custom internal software, like CRUD apps and admin panels, really fast.</b>
+  <div>
+    <sup>Build UIs visually with flexible components, connect to any data source, and write business logic in JavaScript.</sup>
+  </div>
+</a>
+<br>
+<a href="https://workos.com/?utm_campaign=github_repo&utm_medium=referral&utm_content=dotenv&utm_source=github">
+  <div>
+    <img src="https://res.cloudinary.com/dotenv-org/image/upload/c_scale,w_400/v1665605496/68747470733a2f2f73696e647265736f726875732e636f6d2f6173736574732f7468616e6b732f776f726b6f732d6c6f676f2d77686974652d62672e737667_zdmsbu.svg" width="270" alt="WorkOS">
+  </div>
+  <b>Your App, Enterprise Ready.</b>
+  <div>
+    <sup>Add Single Sign-On, Multi-Factor Auth, and more, in minutes instead of months.</sup>
+  </div>
+</a>
+<hr>
+</div>
+
+# dotenv [![NPM version](https://img.shields.io/npm/v/dotenv.svg?style=flat-square)](https://www.npmjs.com/package/dotenv)
+
+<img src="https://raw.githubusercontent.com/motdotla/dotenv/master/dotenv.svg" alt="dotenv" align="right" width="200" />
+
+Dotenv is a zero-dependency module that loads environment variables from a `.env` file into [`process.env`](https://nodejs.org/docs/latest/api/process.html#process_process_env). Storing configuration in the environment separate from code is based on [The Twelve-Factor App](https://12factor.net/config) methodology.
+
+[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard)
+[![LICENSE](https://img.shields.io/github/license/motdotla/dotenv.svg)](LICENSE)
+[![dotenv-vault](https://badge.dotenv.org/works-with.svg?r=1)](https://www.dotenv.org/r/github.com/dotenv-org/dotenv-vault?r=1) 
+
+* [🌱 Install](#-install)
+* [🏗️ Usage (.env)](#%EF%B8%8F-usage)
+* [🚀 Deploying (.env.vault) 🆕](#-deploying)
+* [🌴 Multiple Environments 🆕](#-manage-multiple-environments)
+* [📚 Examples](#-examples)
+* [📖 Docs](#-documentation)
+* [❓ FAQ](#-faq)
+* [⏱️ Changelog](./CHANGELOG.md)
+
+## 🌱 Install
+
+```bash
+# install locally (recommended)
+npm install dotenv --save
+```
+
+Or installing with yarn? `yarn add dotenv`
+
+## 🏗️ Usage
+
+<a href="https://www.youtube.com/watch?v=YtkZR0NFd1g">
+<div align="right">
+<img src="https://img.youtube.com/vi/YtkZR0NFd1g/hqdefault.jpg" alt="how to use dotenv video tutorial" align="right" width="330" />
+<img src="https://simpleicons.vercel.app/youtube/ff0000" alt="youtube/@dotenvorg" align="right" width="24" />
+</div>
+</a>
+
+Create a `.env` file in the root of your project:
+
+```dosini
+S3_BUCKET="YOURS3BUCKET"
+SECRET_KEY="YOURSECRETKEYGOESHERE"
+```
+
+As early as possible in your application, import and configure dotenv:
+
+```javascript
+require('dotenv').config()
+console.log(process.env) // remove this after you've confirmed it is working
+```
+
+.. [or using ES6?](#how-do-i-use-dotenv-with-import)
+
+```javascript
+import 'dotenv/config'
+```
+
+That's it. `process.env` now has the keys and values you defined in your `.env` file:
+
+```javascript
+require('dotenv').config()
+
+...
+
+s3.getBucketCors({Bucket: process.env.S3_BUCKET}, function(err, data) {})
+```
+
+### Multiline values
+
+If you need multiline variables, for example private keys, those are now supported (`>= v15.0.0`) with line breaks:
+
+```dosini
+PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
+...
+Kh9NV...
+...
+-----END RSA PRIVATE KEY-----"
+```
+
+Alternatively, you can double quote strings and use the `\n` character:
+
+```dosini
+PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nKh9NV...\n-----END RSA PRIVATE KEY-----\n"
+```
+
+### Comments
+
+Comments may be added to your file on their own line or inline:
+
+```dosini
+# This is a comment
+SECRET_KEY=YOURSECRETKEYGOESHERE # comment
+SECRET_HASH="something-with-a-#-hash"
+```
+
+Comments begin where a `#` exists, so if your value contains a `#` please wrap it in quotes. This is a breaking change from `>= v15.0.0` and on.
+
+### Parsing
+
+The engine which parses the contents of your file containing environment variables is available to use. It accepts a String or Buffer and will return an Object with the parsed keys and values.
+
+```javascript
+const dotenv = require('dotenv')
+const buf = Buffer.from('BASIC=basic')
+const config = dotenv.parse(buf) // will return an object
+console.log(typeof config, config) // object { BASIC : 'basic' }
+```
+
+### Preload
+
+You can use the `--require` (`-r`) [command line option](https://nodejs.org/api/cli.html#-r---require-module) to preload dotenv. By doing this, you do not need to require and load dotenv in your application code.
+
+```bash
+$ node -r dotenv/config your_script.js
+```
+
+The configuration options below are supported as command line arguments in the format `dotenv_config_<option>=value`
+
+```bash
+$ node -r dotenv/config your_script.js dotenv_config_path=/custom/path/to/.env dotenv_config_debug=true
+```
+
+Additionally, you can use environment variables to set configuration options. Command line arguments will precede these.
+
+```bash
+$ DOTENV_CONFIG_<OPTION>=value node -r dotenv/config your_script.js
+```
+
+```bash
+$ DOTENV_CONFIG_ENCODING=latin1 DOTENV_CONFIG_DEBUG=true node -r dotenv/config your_script.js dotenv_config_path=/custom/path/to/.env
+```
+
+### Variable Expansion
+
+You need to add the value of another variable in one of your variables? Use [dotenv-expand](https://github.com/motdotla/dotenv-expand).
+
+### Syncing
+
+You need to keep `.env` files in sync between machines, environments, or team members? Use [dotenv-vault](https://github.com/dotenv-org/dotenv-vault).
+
+### Deploying
+
+You need to deploy your secrets in a cloud-agnostic manner? Use a `.env.vault` file.
+
+### Multiple Environments
+
+You need to manage your secrets across different environments and apply them as needed? Use a `.env.vault` file with a `DOTENV_KEY`.
+
+## 🚀 Deploying
+
+*Note: Requires dotenv >= 16.1.0*
+
+Encrypt your `.env.vault` file.
+
+```bash
+$ npx dotenv-vault build
+```
+
+Fetch your production `DOTENV_KEY`.
+
+```bash
+$ npx dotenv-vault keys production
+```
+
+Set `DOTENV_KEY` on your server.
+
+```bash
+# heroku example
+heroku config:set DOTENV_KEY=dotenv://:key_1234…@dotenv.org/vault/.env.vault?environment=production
+```
+
+That's it! On deploy, your `.env.vault` file will be decrypted and its secrets injected as environment variables – just in time.
+
+*ℹ️ A note from [Mot](https://github.com/motdotla): Until recently, we did not have an opinion on how and where to store your secrets in production. We now strongly recommend generating a `.env.vault` file. It's the best way to prevent your secrets from being scattered across multiple servers and cloud providers – protecting you from breaches like the [CircleCI breach](https://techcrunch.com/2023/01/05/circleci-breach/). Also it unlocks interoperability WITHOUT native third-party integrations. Third-party integrations are [increasingly risky](https://coderpad.io/blog/development/heroku-github-breach/) to our industry. They may be the 'du jour' of today, but we imagine a better future.*
+
+<a href="https://github.com/dotenv-org/dotenv-vault#-deploying">Learn more at dotenv-vault: Deploying</a>
+
+## 🌴 Manage Multiple Environments
+
+Edit your production environment variables.
+
+```bash
+$ npx dotenv-vault open production
+```
+
+Regenerate your `.env.vault` file.
+
+```bash
+$ npx dotenv-vault build
+```
+
+*ℹ️  🔐 Vault Managed vs 💻 Locally Managed: The above example, for brevity's sake, used the 🔐 Vault Managed solution to manage your `.env.vault` file. You can instead use the 💻 Locally Managed solution. [Read more here](https://github.com/dotenv-org/dotenv-vault#how-do-i-use--locally-managed-dotenv-vault). Our vision is that other platforms and orchestration tools adopt the `.env.vault` standard as they did the `.env` standard. We don't expect to be the only ones providing tooling to manage and generate `.env.vault` files.*
+
+<a href="https://github.com/dotenv-org/dotenv-vault#-manage-multiple-environments">Learn more at dotenv-vault: Manage Multiple Environments</a>
+
+## 📚 Examples
+
+See [examples](https://github.com/dotenv-org/examples) of using dotenv with various frameworks, languages, and configurations.
+
+* [nodejs](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-nodejs)
+* [nodejs (debug on)](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-nodejs-debug)
+* [nodejs (override on)](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-nodejs-override)
+* [nodejs (processEnv override)](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-custom-target)
+* [nodejs (DOTENV_KEY override)](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-vault-custom-target)
+* [esm](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-esm)
+* [esm (preload)](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-esm-preload)
+* [typescript](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-typescript)
+* [typescript parse](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-typescript-parse)
+* [typescript config](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-typescript-config)
+* [webpack](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-webpack)
+* [webpack (plugin)](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-webpack2)
+* [react](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-react)
+* [react (typescript)](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-react-typescript)
+* [express](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-express)
+* [nestjs](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-nestjs)
+* [fastify](https://github.com/dotenv-org/examples/tree/master/usage/dotenv-fastify)
+
+## 📖 Documentation
+
+Dotenv exposes four functions:
+
+* `config`
+* `parse`
+* `populate`
+* `decrypt`
+
+### Config
+
+`config` will read your `.env` file, parse the contents, assign it to
+[`process.env`](https://nodejs.org/docs/latest/api/process.html#process_process_env),
+and return an Object with a `parsed` key containing the loaded content or an `error` key if it failed.
+
+```js
+const result = dotenv.config()
+
+if (result.error) {
+  throw result.error
+}
+
+console.log(result.parsed)
+```
+
+You can additionally, pass options to `config`.
+
+#### Options
+
+##### path
+
+Default: `path.resolve(process.cwd(), '.env')`
+
+Specify a custom path if your file containing environment variables is located elsewhere.
+
+```js
+require('dotenv').config({ path: '/custom/path/to/.env' })
+```
+
+##### encoding
+
+Default: `utf8`
+
+Specify the encoding of your file containing environment variables.
+
+```js
+require('dotenv').config({ encoding: 'latin1' })
+```
+
+##### debug
+
+Default: `false`
+
+Turn on logging to help debug why certain keys or values are not being set as you expect.
+
+```js
+require('dotenv').config({ debug: process.env.DEBUG })
+```
+
+##### override
+
+Default: `false`
+
+Override any environment variables that have already been set on your machine with values from your .env file.
+
+```js
+require('dotenv').config({ override: true })
+```
+
+##### processEnv
+
+Default: `process.env`
+
+Specify an object to write your secrets to. Defaults to `process.env` environment variables.
+
+```js
+const myObject = {}
+require('dotenv').config({ processEnv: myObject })
+
+console.log(myObject) // values from .env or .env.vault live here now.
+console.log(process.env) // this was not changed or written to
+```
+
+##### DOTENV_KEY
+
+Default: `process.env.DOTENV_KEY`
+
+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.
+
+```js
+require('dotenv').config({ DOTENV_KEY: 'dotenv://:key_1234…@dotenv.org/vault/.env.vault?environment=production' })
+```
+
+### Parse
+
+The engine which parses the contents of your file containing environment
+variables is available to use. It accepts a String or Buffer and will return
+an Object with the parsed keys and values.
+
+```js
+const dotenv = require('dotenv')
+const buf = Buffer.from('BASIC=basic')
+const config = dotenv.parse(buf) // will return an object
+console.log(typeof config, config) // object { BASIC : 'basic' }
+```
+
+#### Options
+
+##### debug
+
+Default: `false`
+
+Turn on logging to help debug why certain keys or values are not being set as you expect.
+
+```js
+const dotenv = require('dotenv')
+const buf = Buffer.from('hello world')
+const opt = { debug: true }
+const config = dotenv.parse(buf, opt)
+// expect a debug message because the buffer is not in KEY=VAL form
+```
+
+### Populate
+
+The engine which populates the contents of your .env file to `process.env` is available for use. It accepts a target, a source, and options. This is useful for power users who want to supply their own objects.
+
+For example, customizing the source:
+
+```js
+const dotenv = require('dotenv')
+const parsed = { HELLO: 'world' }
+
+dotenv.populate(process.env, parsed)
+
+console.log(process.env.HELLO) // world
+```
+
+For example, customizing the source AND target:
+
+```js
+const dotenv = require('dotenv')
+const parsed = { HELLO: 'universe' }
+const target = { HELLO: 'world' } // empty object
+
+dotenv.populate(target, parsed, { override: true, debug: true })
+
+console.log(target) // { HELLO: 'universe' }
+```
+
+#### options
+
+##### Debug
+
+Default: `false`
+
+Turn on logging to help debug why certain keys or values are not being populated as you expect.
+
+##### override
+
+Default: `false`
+
+Override any environment variables that have already been set.
+
+### Decrypt
+
+The engine which decrypts the ciphertext contents of your .env.vault file is available for use. It accepts a ciphertext and a decryption key. It uses AES-256-GCM encryption.
+
+For example, decrypting a simple ciphertext:
+
+```js
+const dotenv = require('dotenv')
+const ciphertext = 's7NYXa809k/bVSPwIAmJhPJmEGTtU0hG58hOZy7I0ix6y5HP8LsHBsZCYC/gw5DDFy5DgOcyd18R'
+const decryptionKey = 'ddcaa26504cd70a6fef9801901c3981538563a1767c297cb8416e8a38c62fe00'
+
+const decrypted = dotenv.decrypt(ciphertext, decryptionKey)
+
+console.log(decrypted) // # development@v6\nALPHA="zeta"
+```
+
+## ❓ FAQ
+
+### Why is the `.env` file not loading my environment variables successfully?
+
+Most likely your `.env` file is not in the correct place. [See this stack overflow](https://stackoverflow.com/questions/42335016/dotenv-file-is-not-loading-environment-variables).
+
+Turn on debug mode and try again..
+
+```js
+require('dotenv').config({ debug: true })
+```
+
+You will receive a helpful error outputted to your console.
+
+### Should I commit my `.env` file?
+
+No. We **strongly** recommend against committing your `.env` file to version
+control. It should only include environment-specific values such as database
+passwords or API keys. Your production database should have a different
+password than your development database.
+
+### Should I have multiple `.env` files?
+
+No. We **strongly** recommend against having a "main" `.env` file and an "environment" `.env` file like `.env.test`. Your config should vary between deploys, and you should not be sharing values between environments.
+
+> In a twelve-factor app, env vars are granular controls, each fully orthogonal to other env vars. They are never grouped together as “environments”, but instead are independently managed for each deploy. This is a model that scales up smoothly as the app naturally expands into more deploys over its lifetime.
+>
+> – [The Twelve-Factor App](http://12factor.net/config)
+
+### What rules does the parsing engine follow?
+
+The parsing engine currently supports the following rules:
+
+- `BASIC=basic` becomes `{BASIC: 'basic'}`
+- empty lines are skipped
+- lines beginning with `#` are treated as comments
+- `#` marks the beginning of a comment (unless when the value is wrapped in quotes)
+- empty values become empty strings (`EMPTY=` becomes `{EMPTY: ''}`)
+- inner quotes are maintained (think JSON) (`JSON={"foo": "bar"}` becomes `{JSON:"{\"foo\": \"bar\"}"`)
+- whitespace is removed from both ends of unquoted values (see more on [`trim`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/Trim)) (`FOO=  some value  ` becomes `{FOO: 'some value'}`)
+- single and double quoted values are escaped (`SINGLE_QUOTE='quoted'` becomes `{SINGLE_QUOTE: "quoted"}`)
+- single and double quoted values maintain whitespace from both ends (`FOO="  some value  "` becomes `{FOO: '  some value  '}`)
+- double quoted values expand new lines (`MULTILINE="new\nline"` becomes
+
+```
+{MULTILINE: 'new
+line'}
+```
+
+- backticks are supported (`` BACKTICK_KEY=`This has 'single' and "double" quotes inside of it.` ``)
+
+### What happens to environment variables that were already set?
+
+By default, we will never modify any environment variables that have already been set. In particular, if there is a variable in your `.env` file which collides with one that already exists in your environment, then that variable will be skipped.
+
+If instead, you want to override `process.env` use the `override` option.
+
+```javascript
+require('dotenv').config({ override: true })
+```
+
+### How come my environment variables are not showing up for React?
+
+Your React code is run in Webpack, where the `fs` module or even the `process` global itself are not accessible out-of-the-box. `process.env` can only be injected through Webpack configuration.
+
+If you are using [`react-scripts`](https://www.npmjs.com/package/react-scripts), which is distributed through [`create-react-app`](https://create-react-app.dev/), it has dotenv built in but with a quirk. Preface your environment variables with `REACT_APP_`. See [this stack overflow](https://stackoverflow.com/questions/42182577/is-it-possible-to-use-dotenv-in-a-react-project) for more details.
+
+If you are using other frameworks (e.g. Next.js, Gatsby...), you need to consult their documentation for how to inject environment variables into the client.
+
+### Can I customize/write plugins for dotenv?
+
+Yes! `dotenv.config()` returns an object representing the parsed `.env` file. This gives you everything you need to continue setting values on `process.env`. For example:
+
+```js
+const dotenv = require('dotenv')
+const variableExpansion = require('dotenv-expand')
+const myEnv = dotenv.config()
+variableExpansion(myEnv)
+```
+
+### How do I use dotenv with `import`?
+
+Simply..
+
+```javascript
+// index.mjs (ESM)
+import 'dotenv/config' // see https://github.com/motdotla/dotenv#how-do-i-use-dotenv-with-import
+import express from 'express'
+```
+
+A little background..
+
+> When you run a module containing an `import` declaration, the modules it imports are loaded first, then each module body is executed in a depth-first traversal of the dependency graph, avoiding cycles by skipping anything already executed.
+>
+> – [ES6 In Depth: Modules](https://hacks.mozilla.org/2015/08/es6-in-depth-modules/)
+
+What does this mean in plain language? It means you would think the following would work but it won't.
+
+`errorReporter.mjs`:
+```js
+import { Client } from 'best-error-reporting-service'
+
+export default new Client(process.env.API_KEY)
+```
+`index.mjs`:
+```js
+// Note: this is INCORRECT and will not work
+import * as dotenv from 'dotenv'
+dotenv.config()
+
+import errorReporter from './errorReporter.mjs'
+errorReporter.report(new Error('documented example'))
+```
+
+`process.env.API_KEY` will be blank.
+
+Instead, `index.mjs` should be written as..
+
+```js
+import 'dotenv/config'
+
+import errorReporter from './errorReporter.mjs'
+errorReporter.report(new Error('documented example'))
+```
+
+Does that make sense? It's a bit unintuitive, but it is how importing of ES6 modules work. Here is a [working example of this pitfall](https://github.com/dotenv-org/examples/tree/master/dotenv-es6-import-pitfall).
+
+There are two alternatives to this approach:
+
+1. Preload dotenv: `node --require dotenv/config index.js` (_Note: you do not need to `import` dotenv with this approach_)
+2. Create a separate file that will execute `config` first as outlined in [this comment on #133](https://github.com/motdotla/dotenv/issues/133#issuecomment-255298822)
+
+### Why am I getting the error `Module not found: Error: Can't resolve 'crypto|os|path'`?
+
+You are using dotenv on the front-end and have not included a polyfill. Webpack < 5 used to include these for you. Do the following:
+
+```bash
+npm install node-polyfill-webpack-plugin
+```
+
+Configure your `webpack.config.js` to something like the following.
+
+```js
+require('dotenv').config()
+
+const path = require('path');
+const webpack = require('webpack')
+
+const NodePolyfillPlugin = require('node-polyfill-webpack-plugin')
+
+module.exports = {
+  mode: 'development',
+  entry: './src/index.ts',
+  output: {
+    filename: 'bundle.js',
+    path: path.resolve(__dirname, 'dist'),
+  },
+  plugins: [
+    new NodePolyfillPlugin(),
+    new webpack.DefinePlugin({
+      'process.env': {
+        HELLO: JSON.stringify(process.env.HELLO)
+      }
+    }),
+  ]
+};
+```
+
+Alternatively, just use [dotenv-webpack](https://github.com/mrsteele/dotenv-webpack) which does this and more behind the scenes for you.
+
+### What about variable expansion?
+
+Try [dotenv-expand](https://github.com/motdotla/dotenv-expand)
+
+### What about syncing and securing .env files?
+
+Use [dotenv-vault](https://github.com/dotenv-org/dotenv-vault)
+
+### What is a `.env.vault` file?
+
+A `.env.vault` file is an encrypted version of your development (and ci, staging, production, etc) environment variables. It is paired with a `DOTENV_KEY` to deploy your secrets more securely than scattering them across multiple platforms and tools. Use [dotenv-vault](https://github.com/dotenv-org/dotenv-vault) to manage and generate them.
+
+## Contributing Guide
+
+See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## CHANGELOG
+
+See [CHANGELOG.md](CHANGELOG.md)
+
+## Who's using dotenv?
+
+[These npm modules depend on it.](https://www.npmjs.com/browse/depended/dotenv)
+
+Projects that expand it often use the [keyword "dotenv" on npm](https://www.npmjs.com/search?q=keywords:dotenv).