Merge pull request #46 from recursivefunk/jra/get-ip

feat: getIp()

Author: recursivefunk

README.md

@@ -159,6 +159,15 @@ const {
 } = env.getAWS({ region: 'region' });
 ```
 
+Fetch an IP Address
+
+```javascript
+const validIP = env.getIp('MY_IP', '127.0.0.1');
+console.log(validIp); // 192.168.1.60
+const invalidIP = env.getIp('INVALID_IP');
+console.log(invalidIp); // null
+```
+
 Fetch `URL` objects from url strings
 
 ```javascript
@@ -216,6 +225,7 @@ Why would one use `env.getUrl()` if one just wishes to grab the url string value
 
 As of now, `http`, `redis` and `postgresql` are the only supported protocols. Other protocols will return `null`. I'm not against adding new protocol support, but these are the ones that seemed most obvious to me. If you want other protocols supported, I'd recommend making a PR. You may create an issue, but I can't guarantee when I'll get around to implementation.
 
+
 ## Shortcut Methods
 
 ```javascript

package.json

@@ -1,6 +1,6 @@
 {
   "name": "good-env",
-  "version": "7.1.4",
+  "version": "7.2.0",
   "description": "Better environment variable handling for Twelve-Factor node apps",
   "main": "src/index.js",
   "scripts": {

src/index.d.ts

@@ -1,4 +1,14 @@
 declare module "good-env" {
+  /**
+   * @description Fetches an IP address from the environment. If the value found under the specified key is not a valid IPv4
+   * or IPv6 IP and there's no default value, null is returned. If a default value is provided and it is a valid IPv4 or IPv6
+   * IP, the default value is retruned. If the default value is not valid, null is returned. This function won't return a value
+   * that is not a valid IP address.
+   * @param {string} key - A unique key that points to the IP address
+   * @param {string} defaultVal - The default IP address to be used if the key isn't found
+   * @returns 
+   */
+  export const getIP: (key: string, defaultVal?: string) => any;
   /**
    * @description Fetches three commonly used AWS environment variables - access key id, secret access key and region.
    * Note: You can only pass in a default region. No defaults for access key id or access key will be honored. This also

src/index.js

@@ -1,5 +1,5 @@
 'use strict';
-
+const { isIP } = require('node:net');
 const { URL } = require('node:url');
 const { makeGoodUrl } = require('./lib/url-types');
 const ok = x => !!x;
@@ -16,6 +16,30 @@ const validType = item => ['number', 'boolean', 'string'].includes(item);
 
 module.exports = Object
   .create({
+    /**
+     * @description Fetches an IP address from the environment. If the value found under the specified key is not a valid IPv4
+     * or IPv6 IP and there's no default value, null is returned. If a default value is provided and it is a valid IPv4 or IPv6
+     * IP, the default value is retruned. If the default value is not valid, null is returned. This function won't return a value
+     * that is not a valid IP address.
+     * @param {string} key - A unique key that points to the IP address
+     * @param {string} defaultVal - The default IP address to be used if the key isn't found
+     * @returns
+     */
+    getIP (key, defaultVal) {
+      const strIP = this.get(key);
+
+      if (!strIP) {
+        if (!isIP(defaultVal)) {
+          return null;
+        } else {
+          return defaultVal;
+        }
+      }
+
+      if (isIP(strIP)) return strIP;
+      if (isIP(defaultVal)) return defaultVal;
+      return null;
+    },
     /**
      * @description Fetches three commonly used AWS environment variables - access key id, secret access key and region.
      * Note: You can only pass in a default region. No defaults for access key id or access key will be honored. This also

test/test.env

@@ -16,3 +16,5 @@ UNSUPPORTED_URL=beep://baz.bop
 AWS_ACCESS_KEY_ID=exampleaccesskeyid
 AWS_SECRET_ACCESS_KEY=examplesecretaccesskey
 AWS_REGION=us-east-1
+VALID_IP=192.168.1.60
+INVALID_IP=nope

test/test.js

@@ -5,6 +5,42 @@ require('dotenv').config({ path: 'test/test.env' });
 const test = require('tape');
 const env = require('../src/index');
 
+test('it gets an IP address', (t) => {
+  const ip = env.getIP('VALID_IP');
+  t.equals(ip, '192.168.1.60');
+  t.end();
+});
+
+test('it gets a default IP address', (t) => {
+  const ip = env.getIP('NO_IP_HERE', '127.0.0.1');
+  t.equals(ip, '127.0.0.1');
+  t.end();
+});
+
+test('it does not return an invalid IP', (t) => {
+  const ip = env.getIP('INVALID_IP');
+  t.notOk(ip);
+  t.end();
+});
+
+test('it returns a valid default with an invalid key', (t) => {
+  const ip = env.getIP('INVALID_IP', '127.0.0.1');
+  t.equals(ip, '127.0.0.1');
+  t.end();
+});
+
+test('it does not return a non-existing IP value', (t) => {
+  const ip = env.getIP('NO_IP_HERE');
+  t.notOk(ip);
+  t.end();
+});
+
+test('it does not return an invalid default IP', (t) => {
+  const ip = env.getIP('NO_IP_HERE', 'bleep');
+  t.notOk(ip);
+  t.end();
+});
+
 test('it gets AWS creds', (t) => {
   const {
     awsKeyId,