initial commit

LICENSE.md

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Jonathan Clem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,93 @@
+# SteelToe
+
+Don't shoot yourself in the foot while traversing JavaScript objects.
+
+## Get It
+
+It's a single JavaScript file—link to the raw code [here](https://raw.github.com/jclem/steeltoe/master/public/javascripts/steeltoe.js).
+
+## Usage
+
+SteelToe is a tiny JavaScript function that makes it safe to traipse about objects without worrying about whether keys may or may not exist, and whether it's safe to try and look inside of them. It also provides basic [autovivification](http://en.wikipedia.org/wiki/Autovivification) of objects through the `set` function.
+
+### Getting Values
+
+#### Method #1
+```javascript
+var object = { info: { name: { first: 'Jonathan', last: 'Clem' } } }
+
+steelToe(object)('info')('name')('last')();           // 'Clem'
+steelToe(object)('info')('features')('hairColor')();  // undefined
+```
+
+#### Method #2
+```javascript
+var object = { info: { name: { first: 'Jonathan', last: 'Clem' } } }
+
+steelToe(object).get('info.name.last');          // 'Clem'
+steelToe(object).get('info.features.hairColor'); // undefined
+```
+
+### Setting Values
+
+```javascript
+var jonathan = { info: { name: { first: 'Jonathan', last: 'Clem' } } },
+
+steelToe(jonathan).set('info.name.middle', 'Tyler');
+steelToe(jonathan).set('info.favorites.movie', 'Harold & Maude');
+
+jonathan.info.name.middle; // Tyler
+jonathan.info.favorites.movie; // Harold & Maude
+````
+
+## Details
+
+Let's say you've got some deeply nested data in JavaScript objects that you've just parsed from a JSON API response. For each result, you need to do something if there's some sort of data present:
+
+```javascript
+var fatherFirstNames = [];
+
+for (var i = 0; i < families.length; i ++) {
+  var first = families[i].father.info.name.first;
+
+  if (first) {
+    fatherFirstNames.push(first);
+  }
+}
+
+// TypeError: 'undefined' is not an object (evaluating 'family.father.info.name.first')
+```
+
+Whoops! You shot yourself in the foot. You got a `TypeError` because you had no guarantee that the family had a father, or that the father had info present, or that his name was returned! You fix it by writing this monstrosity:
+
+```javascript
+var farherFirstNames = [];
+
+for (var i = 0; i < families.length; i++) {
+  var father = families[i].father;
+
+  if (father && father.info && father.info.name && father.info.name.first) {
+    fatherFirstNames.push(father.info.name.first);
+  }
+}
+```
+
+Or, you could use SteelToe and write this:
+
+```javascript
+var fatherFirstNames = [];
+
+for (var i = 0; i < families.length; i++) {
+  var name = steelToe(families[i]).get('father.info.name.first');
+
+  if (name) {
+    fatherFirstNames.push(name);
+  }
+}
+
+fatherFirstNames; // ["Hank", "Dale", "Bill"]
+```
+
+## The End
+
+SteelToe was made when a coworker of mine said that he wished someone would write a JavaScript library that would allow him to traverse objects without shooting himself in the foot, and that the library was called SteelToe.

index.js

@@ -0,0 +1,47 @@
+module.exports = steelToe;
+
+function steelToe (object) {
+  function _steelToe (property) {
+    if (object && property) {
+      return steelToe(object[property]);
+    } else {
+      return property ? steelToe() : object;
+    }
+  }
+
+  _steelToe.set = function (traversalChain, value) {
+    var keys = traversalChain.split('.'),
+        object = _steelToe;
+
+    for (var i = 0; i < keys.length; i ++) {
+      if (!object()[keys[i]]) {
+        object()[keys[i]] = {};
+      }
+
+      if (i == keys.length - 1) {
+        object()[keys[i]] = value;
+      }
+
+      object = object(keys[i]);
+    }
+
+    return value;
+  }
+
+  _steelToe.get = function (traversalChain) {
+    if (traversalChain) {
+      var keys = traversalChain.split('.'),
+          returnObject = _steelToe, i;
+
+      for (i = 0; i < keys.length; i += 1) {
+        returnObject = returnObject(keys[i])
+      }
+
+      return returnObject();
+    } else {
+      return _steelToe();
+    }
+  };
+
+  return _steelToe;
+};

package.json

@@ -0,0 +1,27 @@
+{
+  "name": "steeltoe",
+  "version": "1.0.0",
+  "description": "Don't shoot yourself in the foot while traversing JavaScript objects.",
+  "main": "index.js",
+  "scripts": {
+    "test": "node_modules/jasmine-node/bin/jasmine-node spec/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jclem/steeltoe"
+  },
+  "keywords": [
+    "objects",
+    "traversal",
+    "autovivification"
+  ],
+  "author": "Jonathan Clem",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jclem/steeltoe/issues"
+  },
+  "homepage": "https://github.com/jclem/steeltoe",
+  "devDependencies": {
+    "jasmine-node": "~1.13.1"
+  }
+}

spec/steelToeSpec.js

@@ -0,0 +1,121 @@
+var steelToe = require('../index');
+
+describe("steelToe", function () {
+  var object, toe;
+
+  beforeEach(function () {
+    object = { name: { first: 'Jonathan', last: 'Clem' } };
+    toe = steelToe(object);
+  });
+
+  describe("getting values", function () {
+    it("can return its original object", function () {
+      expect(toe()).toEqual(object);
+    });
+
+    it("can access root-level keys", function () {
+      expect(toe('name')()).toEqual({ first: 'Jonathan', last: 'Clem' })
+    });
+
+    it("returns undefined for root-level keys that are undefined", function () {
+      expect(toe('nope')()).not.toBeDefined();
+    });
+
+    it("returns undefined for undefined keys nested in defined keys", function () {
+      expect(toe('name')('middleName')()).not.toBeDefined();
+    });
+
+    it("returns undefined for undefined keys nested in undefined keys", function () {
+      expect(toe('nope')('noWay')()).not.toBeDefined();
+    });
+
+    describe("#get", function () {
+      describe("with no traversal chain", function () {
+        it("returns its object", function () {
+          expect(toe.get()).toEqual(object);
+        });
+      });
+
+      describe("with a traversal chain", function () {
+        it("splits a string of keys and walks through the object", function () {
+          expect(toe.get('name.first')).toEqual(toe('name')('first')());
+        });
+
+        it("returns undefined properties properly", function () {
+          expect(toe.get('this.is.bad')).not.toBeDefined();
+        });
+      });
+    });
+  });
+
+  describe("setting values", function () {
+    describe("for a root-level key", function () {
+      beforeEach(function () {
+        toe.set('key', 'value');
+      });
+
+      it("should set the key to the given value", function () {
+        expect(toe('key')()).toEqual('value');
+      });
+    });
+
+    describe("for an existing key nested in an existing object", function () {
+      beforeEach(function () {
+        toe.set('name.first', 'New Name');
+      });
+
+      it("should set the key to the given value", function () {
+        expect(toe('name')('first')()).toEqual('New Name');
+      });
+    });
+
+    describe("for a non-existent key nested in an existing object", function () {
+      beforeEach(function () {
+        toe.set('name.middle', 'New Name');
+      });
+
+      it("should set the key to the given value", function () {
+        expect(toe('name')('middle')()).toEqual('New Name');
+      });
+    });
+
+    describe("for a non-existent key nested in a non-existent object", function () {
+      beforeEach(function () {
+        toe.set('info.age', 26);
+      });
+
+      it("should create the non-existent object", function () {
+        expect(toe('info')()).toEqual({ age: 26 });
+      });
+
+      it("should set the key to the given value", function () {
+        expect(toe('info')('age')()).toEqual(26);
+      });
+    });
+
+    describe("setting multiple values", function () {
+      beforeEach(function () {
+        toe.set('info.name.first', 'George');
+        toe.set('info.name.last', 'Washington');
+      });
+
+      it("should set both values", function () {
+        expect(toe.get('info.name')).toEqual({ first: 'George', last: 'Washington' });
+      });
+    });
+
+    describe("for a non-existent key nested multiple levels into in a non-existent object", function () {
+      beforeEach(function () {
+        toe.set('info.birthplace.city', 'Indianapolis');
+      });
+
+      it("creates the non-existent objects", function () {
+        expect(toe('info')()).toEqual({ birthplace: { city: 'Indianapolis' } });
+      });
+
+      it("should set the key to the given value", function () {
+        expect(toe('info')('birthplace')('city')()).toEqual('Indianapolis');
+      });
+    });
+  });
+});