{"dist":{"shasum":"4091852c57f56c7c41138ada2ed785044878e726","tarball":"https://registry.npmjs.org/harmony-collections/-/harmony-collections-0.3.4.tgz","integrity":"sha512-+qGdhZmtgq0uE8stdrxtxW2Nv//lBTfeCmvgC2rd8h6xyq/qAtfzKdmxzsgimVbvJDnR1Q1IlJpZERxuxUfReA==","signatures":[{"sig":"MEUCIQDHOeaVuM0dqG3UtaHWSsjHyPYVyFqMb+pXKed/6P/5gwIgDcH0xOERkccNB7zCjiQMaJ0Ct5cAxAxB9bak3GhI/J8=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}]},"main":"harmony-collections.js","name":"harmony-collections","author":{"name":"Brandon Benvie","email":"http://bbenvie.com"},"readme":"# Harmony Collections Shim\n\nUse the new __Map__, __Set__, and __WeakMap__ from the upcoming ES6 standard right now! This shim provides full functionality for these collections and delivers the benefits of using them.\n\n## Compatability\n\nWorks with IE9+, Chrome, Firefox, Safari, untested in Opera. __IE8 support has been recently added but is experimental.__\n\n## Install/Use\n\nIf using node, install via:\n\n    npm install harmony-collections\n\nIn the browser, include __harmony-collection.js__ or __harmony-collections.min.js__ and Map, WeakMap, Set, and HashMap will be exposed on the window. (you can also define `window.exports` which will cause them to end up there).\n\n## Overview\n\nES6 Collections provide a new core weapon to your JS arsenal: objects as keys. This allows you to do the following awesome things: store private data \"on\" public objects, private properties, secretly \"tag\" objects, namespace properties, access controlled properties, check object uniqueness in __O(1)__ time complexity.\n\n### WeakMap Garbage Collection Semantics\n\nThe benefit of using WeakMaps is enhanced garbage collection. In a WeakMap, the only reference created is key -> value, so it's possible for a key/value in a WeakMap to be garbage collected while the WeakMap they're in still exists! Compare this to an Array, where all items in the Array will not be garbage collected as long as the Array isn't. This forces either explicitly management of the object lifespans, or more commonly is simply a memory leak.\n\nFor example, data stored using jQuery.data can never be garbage collected unless explicitly nulled out, because it is stored in a container that strongly references it. Using a WeakMap, it's possible to associate data with an element and have the data destroyed when the element is without memory leaking the element, i.e. `weakmap.set(element, { myData: 'gc safe!' })`. jQuery.data (every library has similar functionality) prevent the element from memory leaking by using a numeric id, but this does nothing for the __data__ that is stored.\n\n## Detailed Examples\n\n### Map/WeakMap\nRetire jQuery.data and similar, consider it replaced with prejudice.\n\n```javascript\n// reusable storage creator for making as many separate stores as needed\nfunction createStorage(){\n  var store = new WeakMap;\n  return function(o){\n    var v = store.get(o);\n    if (!v) store.set(o, v = {});\n    return v;\n  };\n}\n\n// now we can create private/namespaced properties associated with objects\nvar _ = createStorage();\n\nfunctioon Wrapper(element){\n  var _element = _(element);\n  if (_element.wrapper)\n    return _element.wrapper;\n\n  _element.wrapper = this;\n  _(this).element = element;\n}\n\nWrapper.prototype = {\n  get classes(){\n    return [].slice.call(_(this).element);\n  },\n  set classes(v){\n    _(this).element.className = [].concat(v).join(' ');\n  }\n};\n```\n\n### Set\nA Set is similar to an Array in what it stores, but different in how. A Set is unordered and its values are unique. Determining whether an item is in a Set is __O(1)__ but __O(n)__ for an Array. An example of where this is useful is in implementing `Array.prototype.unique`.\n\n```javascript\nfunction uniqueUsingIndexOf(array){\n  return array.filter(function(item, index){\n    return array.lastIndexOf(item) > index;\n  });\n}\n\nfunction uniqueUsingSet(array){\n  var seen = new Set;\n  return array.filter(function(item){\n    if (!seen.has(item)) {\n      seen.add(item);\n      return true;\n    }\n  });\n}\n```\n\nBoth will output the same result, however the version using the set is __O(n)__ and the one using indexOf is __O(n^2)__. For an array taking 30 seconds using the set, an __*hour*__ is required for indexOf.\n\n## API Reference\n\n### WeakMap\n\nWeakMaps require the use of objects as keys; primitives are not valid keys. Keys are unique per WeakMap; setting the same key will overwrite the old value. WeakMaps have no way to enumerate their keys or values. Because of this, the only way to retrieve a value from a WeakMap is to have access to both the WeakMap itself as well as the object used as the key.\n\n* __set__ `weakmap.set(key, value)`. Key is any value including objects. Only non-primitives can be used as keys. Returns undefined.\n* __get__ `weakmap.get(key)`. Returns the value that key corresponds to the key or undefined.\n* __has__ `weakmap.has(key)`. Returns boolean.\n* __delete__ `weakmap.delete(key)`. Removes value from the collection if found. Returns true.\n\nWeakMaps allow for some interesting use cases like anonymous communication channels where neither side can identify the other, and no one else can eavesdrop. By using using a target object as its own key to retrieve a hidden seceret value no information about the origin can be obtained.\n\n__Non-primitives__ are valid keys. Objects, functions, DOM nodes, etc.\n\n\n### HashMap\n\nThough not part of ES6, HashMap is also exported. This has the same API as a Map except it only accepts primitive keys. This is needed to implement Map so as a bonus it's exported as well.\n\n* __set__ `hashmap.set(key, value)`. Key must be primitive. Returns undefined.\n* __get__ `hashmap.get(key)`. Returns the value that key corresponds to or undefined.\n* __has__ `hashmap.has(key)`. Returns boolean.\n* __delete__ `hashmap.delete(key)`. Removes value from the collection if found. Returns true.\n* __forEach__ `hashmap.forEach(callback, context)`. Loop through the collection raising callback for each.\n* __map__ `hashmap.map(callback, context)`. Loop through the collection adding the return value for each to an array and returns it.\n\n__Primitives__ are valid keys. Exact value is used, so `500` is different from `\"500\"`, `-0` is different from `0`, ``\"false\"` isn't `false`, etc. NaN does equal itself when used as a key (as opposed to everywhere else in JS).\n\n\n### Map\n\nMaps are much the same as WeakMaps but they can be iterated and thus their contents can be inspected. Many use cases have no requirement for anonymity or special garbage collection, but can benefit from using objects as keys and also not having the storage contained in the Map itself.\n\n* __set__ `map.set(key, value)`. Key is any value including objects. Returns undefined.\n* __get__ `map.get(key)`. Returns the value that key corresponds to or undefined.\n* __has__ `map.has(key)`. Returns boolean.\n* __delete__ `map.delete(key)`. Removes value from the collection if found. Returns true.\n* __forEach__ `map.forEach(callback, context)`. Loop through the collection raising callback for each.\n* __map__ `map.map(callback, context)`. Loop through the collection adding the return value for each to an array and returns it.\n\n__All possible values__ are valid keys, including -0, undefined, null, and NaN. Uses a HashMap and WeakMap together to cover primitives and non-primitives.\n\n\n\n### Set\n\nSets are similar to arrays but enforce uniqueness of values and are unordered. Adding the same value twice will only result in one being added to the set.\n\n* __add__ `set.add(value)`. Inserts a value of any type into the set if it's not already in the set.\n* __has__ `set.has(value)`. Returns boolean.\n* __delete__ `set.delete(value)`. Removes value from the collection if found. Returns true.\n* __forEach__ `set.forEach(callback, context)`. Loop through the collection raising callback for each.\n* __map__ `set.map(callback, context)`. Loop through the collection adding the return value for each to an array and returns it.\n\n\n\n\n## License\n\n(The MIT License)\nCopyright (c) 2012 Brandon Benvie <http://bbenvie.com>\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files\n(the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge,\npublish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,\nsubject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included with all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE\nFOR ANY  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH\nTHE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","license":"MIT","_npmUser":{"name":"benvie","email":"brandon@bbenvie.com"},"homepage":"http://benvie.github.com/harmony-collections","keywords":["harmony","collection","weakmap","map","set","ecmascript","es6","shim","garbage collection","gc"],"repository":{"url":"https://github.com/Benvie/harmony-collections","type":"git"},"_npmVersion":"1.1.61","description":"Shim to provide Map, Set, and WeakMap if they're not available, with non-leaky O(1) lookup WeakMaps","maintainers":[{"name":"benvie","email":"brandon@bbenvie.com"}],"dependencies":{},"devDependencies":{"tap":"*"},"_id":"harmony-collections@0.3.4","version":"0.3.4"}