![\"H.A.M.T.\"](\"https://raw.githubusercontent.com/mattbierner/hamt/master/documentation/hamt-logo.png\"){kind=logo}
\n\nJavascript Hash Array Mapped Trie
\n\n[](https://travis-ci.org/mattbierner/hamt)\n\n### Overview\nThe [hash array mapped trie][hash-array-mapped-trie] is a [persistent][persistent] map data structure with good lookup and update performance. This library provides an immutable map with an API that resembles [ES6's `Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map).\n\n```javascript\nvar hamt = require('hamt');\n\n// Keys can be any string and the map can store any value.\nvar h = hamt.empty\n .set('key', 'value')\n .set('object', { prop: 1 })\n .set('falsy', null);\n\nh.size === 0\nh.has('key') === true\nh.has('falsy') === true\nh.get('key') === 'value'\n\n// Iteration\nfor (let [key, value] of h)\n console.log(key, value);\n\nArray.from(h.values()) === [{ prop: 1 }, 'value'], null];\n\n// The data structure is fully immutable\nvar h2 = h.delete('key');\nh2.get('key') === undefined\nh.get('key') === 'value'\n```\n\n[Benchmarks][benchmarks] show that this library performs well, even as the size of the map becomes very large. [Check out Hamt+][hamt_plus] if you want support for additional features such as custom key types and transient mutation.\n\n## Install\nSource code is in `hamt.js` and generated from `lib/hamt.js`. The library supports node, AMD, and use as a global.\n\n### Node\n``` sh\n$ npm install hamt\n```\n\n``` javascript\nvar hamt = require('hamt');\n\nvar h = hamt.empty.set('key', 'value');\n\n...\n```\n\n\n### AMD\n``` javascript\nrequirejs.config({\n paths: {\n 'hamt': 'path/to/hamt/lib/hamt'\n }\n});\n\nrequire(['hamt'], function(hamt) {\n var h = hamt.empty.set('key', 'value');\n ...\n});\n```\n\n\n# Usage\nHamt provides a method chaining interface and free functions for updating and querying the map. Both APIs provide identical functionality, but the free functions are designed for binding and composition, while the method chaining API is more legible and more Javascripty.\n\nHAMTs are is persistent, so operations always return a modified copy of the map instead of alterting the original.\n\n## Custom Hash Values\nMost update and lookup methods have two versions: one that takes a key and uses an internal hash function to compute its hash, and a version that takes a custom computed hash value.\n\n\n``` javascript\nvar h = hamt.empty.set('key', 'value');\nvar h2 = hamt.empty.setHash(5, 'key', 'value');\n\n\nh.get('key') === 'value'\nh2.getHash(5, 'key') === 'value'\n```\n\nIf using a custom hash, you must only use the `*Hash` variant of functions to interact with the map.\n\n\n``` javascript\n// Because the internally computed hash of `key` is not `5`, a direct\n// look will not work.\nh2.get('key') === undefined\n\n// You must use `getHash` with the same hash value originally passed in.\nh2.getHash(5, 'key') === 'value'\n```\n\n\n## API\n* [Basic](#basics) – Basic map operations.\n* [Lookup](#lookup) – Looking up values in a map.\n* [Modify](#modify) – Updating a map.\n* [Iteration](#iteration) – Looping and folding over a map.\n\n### Basics\n\n#### `hamt.empty`\nAn empty map.\n\n----\n\n#### `hamt.isMap(value)`\nIs `value` a map?\n\n----\n\n#### `hamt.isEmpty(map)`\n#### `map.isEmpty()`\nIs a map empty?\n\nThis is the correct method to check if a map is empty. Direct comparisons to `hamt.empty` will not work.\n\nReturns `false` if `map` is not a map.\n\n#### `hamt.count(map)`\n#### `map.count()`\n#### `map.size`\nGet number of elements in `map`.\n\n* `map` - Hamt map.\n\n\n``` javascript\nhamt.empty.count() === 0;\nhamt.empty.set('a', 3).count() === 1;\nhamt.empty.set('a', 3).set('b', 3).size === 2;\n```\n\n### Lookup\n\n#### `hamt.get(key, map)`\n#### `map.get(key)`\nLookup the value for `key` in `map`.\n\n* `key` - String key.\n* `map` - Hamt map.\n\n``` javascript\nvar h = hamt.empty.set('key', 'value');\n\nh.get('key') === 'value'\nhamt.get('key', k) === 'value'\n\nh.get('no such key') === undefined\n```\n\n----\n\n#### `hamt.getHash(hash, key, map)`\n#### `map.getHash(hash, key)`\nSame as `get` but uses a custom hash value.\n\n----\n\n#### `hamt.tryGet(alt, key, map)`\n#### `map.tryGet(alt, key)`\nSame as `get` but returns `alt` if no value for `key` exists.\n\n* `alt` - Value returned if no such key exists in the map.\n* `key` - String key.\n* `map` - Hamt map.\n\n----\n\n#### `hamt.has(key, map)`\n#### `map.has(key)`\nDoes an entry for `key` exist in `map`?\n\n* `key` - String key.\n* `map` - Hamt map.\n\n``` javascript\nvar h = hamt.empty.set('key', 'value');\n\nh.has('key') === true\nh.has('no such key') === false\n```\n\n----\n\n#### `hamt.tryGetHash(alt, hash, key, map)`\n#### `map.tryGetHash(alt, hash, key)`\nSame as `tryGet` but uses a custom hash value.\n\n----\n\n#### `hamt.set(key, value, map)`\n#### `map.set(key, value)`\nSet the value for `key` in `map`.\n\n* `value` - Value to store. Hamt supports all value types, including: literals, objects, falsy values, null, and undefined. Keep in mind that only the map data structure itself is guaranteed to be immutable. Using immutable values is recommended but not required.\n* `key` - String key.\n* `map` - Hamt map.\n\nReturns a new map with the value set. Does not alter the original.\n\n``` javascript\nvar h = hamt.empty\n .set('key', 'value');\n .set('key2', 'value2');\n\nvar h2 = h.set('key3', 'value3');\n\nh2.get('key') === 'value'\nh2.get('key2') === 'value2'\nh2.get('key3') === 'value3'\n\n// original `h` was not modified\nh.get('key') === 'value'\nh.get('key2') === 'value2'\nh.get('key3') === undefined\n```\n\n----\n\n#### `hamt.setHash(hash, key, value, map)`\n#### `map.setHash(hash, key, value)`\nSame as `set` but uses a custom hash value.\n\n### Modify\n\n#### `hamt.modify(f, key, map)`\n#### `map.modify(key, f)`\nUpdate the value stored for `key` in `map`.\n\n* `f` - Function mapping current value to new value. If no current value exists, `f` is invoked with no arguments.\n* `key` - String key.\n* `map` - Hamt map.\n\nReturns a new map with the modified value. Does not alter the original.\n\n``` javascript\nvar h = hamt.empty\n .set('i', 2);\n\nvar h2 = h.modify('i', x => x * x);\n\nh2.get('i') === 4\nh.get('i') === 2\nh2.count() === 1\nh.count() === 1\n\n// Operate on value that does not exist\nvar h3 = h.modify('new', x => {\n if (x === undefined) {\n return 10;\n }\n return -x;\n});\n\nh3.get('new') === 10\nh3.count() === 2\n```\n\n----\n\n#### `hamt.modifyHash(f, hash, key, map)`\n#### `map.modifyHash(hash, key, f)`\nSame as `modify` but uses a custom hash value.\n\n----\n\n#### `hamt.modifyValue(f, defaultValue, key, map)`\n#### `map.modifyValue(key, f, defaultValue)`\nSimilar to `modify`, but invokes `f` with `defaultValue` if no value exists in `map` for `key`.\n\n----\n\n#### `hamt.modifyValueHash(f, defaultValue, hash, key, map)`\n#### `map.modifyValueHash(hash, key, f, defaultValue)`\nSame as `modifyValue` but uses a custom hash value.\n\n----\n\n#### `hamt.remove(key, map)`\n#### `map.remove(key)`\n#### `map.delete(key)`\nRemove `key` from `map`.\n\n* `key` - String key.\n* `map` - Hamt map.\n\nReturns a new map with the value removed. Does not alter the original.\n\n``` javascript\nvar h = hamt.empty\n .set('a', 1)\n .set('b', 2)\n .set('c', 3);\n\nvar h2 = h.remove('b');\n\nh2.count() === 2;\nh2.get('a') === 1\nh2.get('b') === undefined\nh2.get('c') === 3\n```\n\n----\n\n#### `hamt.removeHash(hash, key, map)`\n#### `map.removeHash(hash, key)`\n#### `map.deleteHash(hash, key)`\nSame as `remove` but uses a custom hash value.\n\n----\n\n### Iteration\n\n#### `hamt.fold(f, z, map)`\n#### `map.fold(f, z)`\nFold over the map, accumulating result value.\n\n* `f` - Function invoked with accumulated value, current value, and current key.\n* `z` - Initial value.\n* `map` - Hamt map.\n\nOrder is not guaranteed.\n\n``` javascript\nvar max = hamt.fold.bind(null,\n (acc, value, key) => Math.max(acc, value),\n 0);\n\nmax(hamt.empty.set('key', 3).set('key', 4)) === 4;\n```\n\n----\n\n#### `hamt.entries(map)`\n#### `map.entries()`\nGet a Javascript iterator to all key value pairs in `map`.\n\n* `map` - Hamt map.\n\nOrder is not guaranteed.\n\n``` javascript\nArray.from(hamt.empty.entries()) === [];\nArray.from(hamt.empty.set('a', 3).entries()) === [['a', 3]];\nArray.from(hamt.empty.set('a', 3).set('b', 3).entries()) === [['a', 3], ['b', 3]];\n```\n\nYou can also iterated directly over a map with ES6:\n\n```javascript\nconst h = hamt.empty.set('a', 3).set('b', 3);\n\nfor (let [key, value] of h)\n ...\n\nArray.from(h) === [['a', 3], ['b', 3]];\n```\n\n----\n\n#### `hamt.key(map)`\n#### `map.keys()`\nGet a Javascript iterator to all keys in `map`.\n\n* `map` - Hamt map.\n\nOrder is not guaranteed.\n\n``` javascript\nArray.from(hamt.empty.keys()) === [];\nArray.from(hamt.empty.set('a', 3).keys()) === ['a'];\nArray.from(hamt.empty.set('a', 3).set('b', 3).keys()) === ['a', 'b'];\n```\n\n----\n\n#### `hamt.values(map)`\n#### `map.values()`\nGet a Javascript iterator to all values in `map`.\n\n* `map` - Hamt map.\n\nOrder is not guaranteed. Duplicate entries may exist.\n\n``` javascript\nArray.from(hamt.empty.values()) === [];\nArray.from(hamt.empty.set('a', 3).values()) === [3];\nArray.from(hamt.empty.set('a', 3).values('b', 3).values()) === [3, 3];\n```\n\n----\n\n#### `hamt.forEach(f, map)`\n#### `map.forEach(f)`\nInvoke function `f` for each value in the map.\n\n* `f` - Function invoked with `(value, key, map)`.\n* `map` - Hamt map.\n\nOrder is not guaranteed.\n\n\n## Development\nAny contributions to Hamt are welcome. Feel free to open an [issue](https://github.com/mattbierner/hamt/issues) if you run into problems or have a suggested improvement.\n\nTo develop Hamt, fork the repo and install the development node packages:\n\n```bash\ncd hamt\n$ npm install\n```\n\nThe source is written in ES6 and lives in `lib/hamt.js`. Gulp and Bable are used to translate the ES6 code to an ES5 distribution found in `hamt.js`. To start the compiler:\n\n```bash\n$ gulp default\n```\n\nTests are written in Mocha and found in `tests\\*`. To run the tests:\n\n```js\n$ mocha tests\n```\n\n## Credits\nCode originally based on [exclipy's Haskell port][pdata].\n\n[hamt_plus]: https://github.com/mattbierner/hamt_plus\n[hashtrie]: https://github.com/mattbierner/hashtrie\n[benchmarks]: http://github.com/mattbierner/js-hashtrie-benchmark\n[pdata]: https://github.com/exclipy/pdata\n[hash-array-mapped-trie]: http://en.wikipedia.org/wiki/Hash_array_mapped_trie\n[persistent]: http://en.wikipedia.org/wiki/Persistent_data_structure\n\n[mori]: https://github.com/swannodette/mori\n[persistent-hash-trie]: https://github.com/hughfdjackson/persistent-hash-trie\n","maintainers":[{"name":"mattbierner","email":"mattbierner@gmail.com"}],"time":{"modified":"2022-06-18T18:49:43.811Z","created":"2014-02-18T05:22:55.344Z","0.0.0":"2014-02-18T05:22:56.364Z","0.1.0":"2014-02-21T06:20:12.350Z","0.1.1":"2014-02-21T17:38:27.814Z","0.1.2":"2014-02-24T19:44:45.658Z","0.1.3":"2014-02-25T00:10:25.152Z","0.1.4":"2014-04-10T20:18:12.656Z","0.1.5":"2014-08-19T06:40:00.368Z","0.1.6":"2014-08-19T07:20:00.746Z","0.1.7":"2014-08-22T12:38:18.508Z","0.1.8":"2014-09-27T20:28:11.809Z","0.1.9":"2016-01-03T01:27:02.223Z","1.0.0":"2016-01-03T08:51:13.548Z","1.1.0":"2016-01-03T20:09:58.611Z","1.1.1":"2016-01-03T23:40:38.406Z","2.0.0":"2016-01-05T06:25:39.950Z","2.0.1":"2016-01-05T06:33:47.822Z","2.0.2":"2016-01-05T06:48:10.934Z","2.1.0":"2016-01-28T03:23:21.545Z","2.1.1":"2016-01-28T03:42:57.329Z","2.2.0":"2016-01-30T19:51:31.409Z","2.2.1":"2017-09-24T23:31:36.237Z","2.2.2":"2017-09-28T03:34:30.858Z"},"readmeFilename":"README.md","author":{"name":"Matt Bierner"},"repository":{"type":"git","url":"git+https://github.com/mattbierner/hamt.git"},"keywords":["trie","map","immutable","persistent","data structure","hash"],"bugs":{"url":"https://github.com/mattbierner/hamt/issues"},"license":"MIT","homepage":"https://github.com/mattbierner/hamt#readme"}