Merge branch 'billneff79-Issue-2-DefaultWhenNotFound'

Author: developit

README.md

@@ -1,15 +1,13 @@
 # `dlv(obj, keypath)` [![NPM](https://img.shields.io/npm/v/dlv.svg)](https://npmjs.com/package/dlv) [![Build](https://travis-ci.org/developit/dlv.svg?branch=master)](https://travis-ci.org/developit/dlv)
 
-> Safely get a dot-notated path within a nested object.
+> Safely get a dot-notated path within a nested object, with ability to return a default if the full key path does not exist or the value is undefined
 
 ### Why?
 
-Smallest possible implementation: only **120 bytes.**
+Smallest possible implementation: only **165 bytes.**
 
 You could write this yourself, but then you'd have to write [tests].
 
-Implementation is ripped directly from [preact].
-
 Supports ES Modules, CommonJS and globals.
 
 ### Installation
@@ -19,22 +17,45 @@ Supports ES Modules, CommonJS and globals.
 
 ### Usage
 
+`delve(object, keypath, [default])`
+
 ```js
 import delve from 'dlv';
 
 let obj = {
 	a: {
 		b: {
 			c: 1
+			d: undefined
+			e: null
 		}
 	}
 };
 
+//use string dot notation for keys
 delve(obj, 'a.b.c') === 1;
 
+//or use an array key
+delve(obj, ['a', 'b', 'c']) === 1;
+
 delve(obj, 'a.b') === obj.a.b;
 
-delve(obj, 'a.b.c.d') === undefined;
+//returns undefined if the full key path does not exist and no default is specified
+delve(obj, 'a.b.c.f') === undefined;
+
+//optional third parameter for default if the full key in path is missing
+delve(obj, 'a.b.c.f', 'foo') === 'foo';
+
+//or if the key exists but the value is undefined
+delve(obj, 'a.b.c.d', 'foo') === 'foo';
+
+//Non-truthy defined values are still returned if they exist at the full keypath
+delve(obj, 'a.b.c.e', 'foo') === null;
+
+//undefined obj or key returns undefined, unless a default is supplied
+delve(undefined, 'a.b.c') === undefined;
+delve(undefined, 'a.b.c', 'foo') === 'foo';
+delve(obj, undefined, 'foo') === 'foo';
 ```
 
 ### License

index.js

@@ -1,5 +1,6 @@
-export default function dlv(obj, key) {
-	if (key.split) key = key.split('.');
-	for (var i=0; i<key.length && obj; i++) obj = obj[key[i]];
-	return obj;
-}
+export default function dlv(obj, key, def, p) {
+	p = 0;
+	key = key.split ? key.split('.') : key;
+	while (obj && p<key.length) obj = obj[key[p++]];
+	return obj===undefined ? def : obj;
+}

test.js

@@ -2,7 +2,10 @@ var assert = require('assert');
 var delve = require('.');
 
 var obj = {
+	undef: undefined,
+	zero: 0,
 	one: 1,
+	n: null,
 	a: {
 		two: 2,
 		b: {
@@ -15,15 +18,22 @@ var obj = {
 };
 
 // assert equality of a given path, as dot notation and array.
-function check(path, value) {
-	assert.equal(delve(obj, path), value);
-	console.log(' ✓ delve(obj, "'+path+'")');
+//optional third argument is for default when object is not found
+function check(path, value, def) {
 
-	var arr = path.split('.');
-	assert.equal(delve(obj, arr), value);
-	console.log(' ✓ delve(obj, '+JSON.stringify(arr)+')');
+	var out = delve(obj, path, def);
+	assert.strictEqual(out, value, 'delve(obj, "'+path+'") should be '+value+', got '+out);
+	console.log(' ✓ delve(obj, "'+path+'"'+ (def ? ', "'+def+'"' : '') + ')');
+
+	if (path) {
+		var arr = path.split('.');
+		assert.strictEqual(delve(obj, arr, def), value);
+		console.log(' ✓ delve(obj, ' + JSON.stringify(arr) + (def ? ', "'+def+'"' : '') + ')');
+		console.log(' ✓ delve(obj, '+JSON.stringify(arr)+')');
+	}
 }
 
+console.log("> No Defaults");
 check('', undefined);
 check('one', obj.one);
 check('one.two', undefined);
@@ -34,5 +44,26 @@ check('a.b.three', obj.a.b.three);
 check('a.b.c', obj.a.b.c);
 check('a.b.c.four', obj.a.b.c.four);
 
+//test defaults
+console.log("\n> With Defaults");
+check('', 'foo', 'foo');
+check('undef', 'foo', 'foo');
+check('n', null, 'foo');
+check('zero', 0, 'foo');
+check('a.badkey', 'foo', 'foo');
+check('a.badkey.anotherbadkey', 'foo', 'foo');
+
+//check undefined key throws an error
+assert.throws(delve.bind(this, obj, undefined));
+assert.throws(delve.bind(this, obj, undefined, 'foo'));
+
+//check undefined obj doesn't throw errors and uses default
+var backupObj = obj;
+obj = undefined;
+check('one', undefined);
+check('one', 'foo', 'foo');
+obj = backupObj;
+
+
 console.log('✅ Success!');
 process.exit(0);