Add support for loading env values

.gitignore

@@ -1,3 +1,5 @@
+.vscode
+
 # Logs
 logs
 *.log

README.md

@@ -71,8 +71,8 @@ Autocomplete and Strongly Typed Keys are your new best friend! Using `simple-env
 | Autocomplete                       |      ✅      |    ❌    |    ❌     |
 | Strongly Typed Keys                |      ✅      |    ❌    |    ❌     |
 | Single Location Refactor           |      ✅      |    ❌    |    ❌     |
+| Loads .env                         |      ✅      |    ✅    |    ❌     |
 | Return Type Helpers                |      🔜      |    ❌    |    ✅     |
-| Loads .env                         |      🔜      |    ✅    |    ❌     |
 
 Let's see how some of the features above look in code:
 
@@ -161,6 +161,55 @@ export const env = setEnv({
 
 > **NOTE**: if you choose to assign `optional` and `required` env vars individually, `setEnv` should only be done _once_ for each or you will overwrite your previously defined values.
 
+### Loading DotEnv Files
+
+You can give `simple-env` a path to a `.env` file, and it will parse the file and import the contents into the environment!
+
+If you don't specify a path, `simple-env` WILL NOT import anything!
+
+```typescript
+// src/env.ts
+import setEnv from '@americanairlines/simple-env';
+
+export const env = setEnv({
+  required: {
+    nodeEnv: 'NODE_ENV',
+    someRequiredSecret: 'SOME_REQUIRED_SECRET',
+  },
+  options: {
+    envPath: "./.env"
+  }
+});
+```
+Each variable needs to be declared on a separate line.
+
+Comments must be on their own line, inline comments will be read in as part of the value to the variable!
+
+If `simple-env` finds something that it doesn't know how to parse, it just skips it and moves on to the next thing!
+
+Here's a sample `.env` file that will make us all happy :^)
+```
+# Comments like this will be ignored
+// These will be ignored too :^)
+
+# All of these vars are gonna work just fine!
+NODE_ENV=development
+SOME_REQUIRED_SECRET='Single quotes are fine!'
+ANOTHER_SECRET="Double quotes are fine too, we don't discriminate :^)"
+lowercase=no problem
+    SECRET_2_ELECTRIC_BOOGALOO   =   "We don't mind whitespace between the equal signs, or before the var definition"
+```
+
+Here's a sample `.env` file that will make us all sad :^(
+```
+# Uh-oh, these ones are invalid, so we'll have to skip them
+1BAD_VAR="Variables can't begin with numbers"
+ANOTHER BAD VAR="no whitespace allowed in var names"
+KEBAB-CASE="can't do it"
+VAR_WITHOUT_EQUAL_IS_SKIPPED
+loose text like this will also get skipped
+```
+
 # Contributing
 
 Interested in contributing to the project? Check out our [Contributing Guidelines](./.github/CONTRIBUTING.md).

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@americanairlines/simple-env",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "An intuitive, strongly typed, and scalable way to retrieve environment variables",
   "keywords": [
     "env",

src/index.ts

@@ -45,7 +45,7 @@ export default function setEnv<T extends UndefinedEnvVars, V extends UndefinedEn
     ...options,
   };
 
-  if (_options.options.loadDotEnv) {
+  if (_options.options.envPath) {
     parseEnvFile(_options.options);
   }
 

src/parser.ts

@@ -23,7 +23,7 @@ function parseLine(line: string): Record<string, string> {
 }
 
 export function parseEnvFile(options: ConfigOptions = {}): void {
-  const fullPath = options.envFile || join(process.cwd(), '.env');
+  const fullPath = options.envPath || join(process.cwd(), '.env');
 
   if (!fs.existsSync(fullPath)) {
     return;

src/test/index.test.ts

@@ -1,7 +1,6 @@
 import 'jest';
 import fs from 'fs';
 import setEnvDefault from '..';
-import parseEnvFile from '../parser';
 
 describe('simple-env', () => {
   // Fresh setEnv for each test
@@ -105,11 +104,11 @@ describe('simple-env', () => {
       expect(Object.getOwnPropertyDescriptors(env)).toHaveProperty('somethingElse');
     });
 
-    it('will invoke the parser is loadDotEnv is true', () => {
+    it('will invoke the parser if envPath is set', () => {
       existsSyncSpy.mockReturnValue(true);
       readFileSpy.mockImplementation(() => Buffer.from('TEST=test'));
 
-      setEnv({ optional: { something: 'SOMETHING' }, options: { loadDotEnv: true } });
+      setEnv({ optional: { something: 'SOMETHING' }, options: { envPath: './a/.env' } });
 
       expect(process.env).toHaveProperty('TEST');
     });
@@ -123,77 +122,4 @@ describe('simple-env', () => {
       expect(process.env).not.toHaveProperty('TEST');
     });
   });
-
-  describe('parser', () => {
-    beforeEach(() => {
-      process.env = {};
-    });
-
-    afterEach(() => {
-      jest.resetModules();
-    });
-
-    it('will not overwrite vars that already exist', () => {
-      const originalValue = 'I already exist';
-      const newValue = 'I should not';
-      process.env = { TEST: originalValue };
-
-      readFileSpy.mockImplementation(() => Buffer.from(`TEST=${newValue}`));
-      existsSyncSpy.mockReturnValue(true);
-
-      parseEnvFile();
-
-      expect(process.env.TEST).toEqual(originalValue);
-    });
-
-    it('will reject malformed lines', () => {
-      const fakeFile = `
-      bad
-      good=this
-      4=bad
-      good2='this'
-      good3="this"
-      `;
-      readFileSpy.mockImplementation(() => Buffer.from(fakeFile));
-      existsSyncSpy.mockReturnValue(true);
-
-      parseEnvFile();
-
-      expect(process.env.good).toEqual('this');
-      expect(process.env.good2).toEqual('this');
-      expect(process.env.good3).toEqual('this');
-    });
-
-    it('will ignore comments in the file', () => {
-      const fakeFile = `
-      #comment\n
-      //comment\n
-      TEST=test
-      `;
-      readFileSpy.mockImplementation(() => Buffer.from(fakeFile));
-      existsSyncSpy.mockReturnValue(true);
-
-      parseEnvFile();
-
-      expect(process.env.TEST).toEqual('test');
-    });
-
-    it('will not do anything if the .env file does not exist', () => {
-      readFileSpy.mockImplementation(() => Buffer.from('TEST=test'));
-      existsSyncSpy.mockReturnValue(false);
-
-      parseEnvFile();
-
-      expect(process.env.TEST).toBeUndefined();
-    });
-
-    it('will read an env variable from a .env file into process.env', () => {
-      readFileSpy.mockImplementation(() => Buffer.from('TEST=test'));
-      existsSyncSpy.mockReturnValue(true);
-
-      parseEnvFile();
-
-      expect(process.env.TEST).toEqual('test');
-    });
-  });
 });

src/test/parser.test.ts

@@ -0,0 +1,79 @@
+import fs from 'fs';
+import parseEnvFile from '../parser';
+
+describe('parser', () => {
+  const readFileSpy = jest.spyOn(fs, 'readFileSync');
+  const existsSyncSpy = jest.spyOn(fs, 'existsSync');
+
+  beforeEach(async () => {
+    jest.resetModules();
+    process.env = {};
+  });
+
+  afterEach(() => {
+    jest.resetModules();
+  });
+
+  it('will not overwrite vars that already exist', () => {
+    const originalValue = 'I already exist';
+    const newValue = 'I should not';
+    process.env = { TEST: originalValue };
+
+    readFileSpy.mockImplementation(() => Buffer.from(`TEST=${newValue}`));
+    existsSyncSpy.mockReturnValue(true);
+
+    parseEnvFile();
+
+    expect(process.env.TEST).toEqual(originalValue);
+  });
+
+  it('will reject malformed lines', () => {
+    const fakeFile = `
+      bad
+      good=this
+      4=bad
+      good2='this'
+      good3="this"
+      `;
+    readFileSpy.mockImplementation(() => Buffer.from(fakeFile));
+    existsSyncSpy.mockReturnValue(true);
+
+    parseEnvFile();
+
+    expect(process.env.good).toEqual('this');
+    expect(process.env.good2).toEqual('this');
+    expect(process.env.good3).toEqual('this');
+  });
+
+  it('will ignore comments in the file', () => {
+    const fakeFile = `
+      #comment\n
+      //comment\n
+      TEST=test
+      `;
+    readFileSpy.mockImplementation(() => Buffer.from(fakeFile));
+    existsSyncSpy.mockReturnValue(true);
+
+    parseEnvFile();
+
+    expect(process.env.TEST).toEqual('test');
+  });
+
+  it('will not do anything if the .env file does not exist', () => {
+    readFileSpy.mockImplementation(() => Buffer.from('TEST=test'));
+    existsSyncSpy.mockReturnValue(false);
+
+    parseEnvFile();
+
+    expect(process.env.TEST).toBeUndefined();
+  });
+
+  it('will read an env variable from a .env file into process.env', () => {
+    readFileSpy.mockImplementation(() => Buffer.from('TEST=test'));
+    existsSyncSpy.mockReturnValue(true);
+
+    parseEnvFile();
+
+    expect(process.env.TEST).toEqual('test');
+  });
+});

src/types/Options.ts

@@ -2,8 +2,7 @@ import { DefaultEnvVars, UndefinedEnvVars } from './EnvVars';
 import { RemoveKeys } from './helpers';
 
 export interface ConfigOptions {
-  envFile?: string;
-  loadDotEnv?: boolean;
+  envPath?: string;
 }
 
 export interface Options<Required extends UndefinedEnvVars = DefaultEnvVars, Optional extends UndefinedEnvVars = DefaultEnvVars> {