www.aleph1.co.uk Git - yaffs-website/blob - node_modules/pseudomap/README.md

   1 # pseudomap
   2
   3 A thing that is a lot like ES6 `Map`, but without iterators, for use
   4 in environments where `for..of` syntax and `Map` are not available.
   5
   6 If you need iterators, or just in general a more faithful polyfill to
   7 ES6 Maps, check out [es6-map](http://npm.im/es6-map).
   8
   9 If you are in an environment where `Map` is supported, then that will
  10 be returned instead, unless `process.env.TEST_PSEUDOMAP` is set.
  11
  12 You can use any value as keys, and any value as data.  Setting again
  13 with the identical key will overwrite the previous value.
  14
  15 Internally, data is stored on an `Object.create(null)` style object.
  16 The key is coerced to a string to generate the key on the internal
  17 data-bag object.  The original key used is stored along with the data.
  18
  19 In the event of a stringified-key collision, a new key is generated by
  20 appending an increasing number to the stringified-key until finding
  21 either the intended key or an empty spot.
  22
  23 Note that because object traversal order of plain objects is not
  24 guaranteed to be identical to insertion order, the insertion order
  25 guarantee of `Map.prototype.forEach` is not guaranteed in this
  26 implementation.  However, in all versions of Node.js and V8 where this
  27 module works, `forEach` does traverse data in insertion order.
  28
  29 ## API
  30
  31 Most of the [Map
  32 API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map),
  33 with the following exceptions:
  34
  35 1. A `Map` object is not an iterator.
  36 2. `values`, `keys`, and `entries` methods are not implemented,
  37    because they return iterators.
  38 3. The argument to the constructor can be an Array of `[key, value]`
  39    pairs, or a `Map` or `PseudoMap` object.  But, since iterators
  40    aren't used, passing any plain-old iterator won't initialize the
  41    map properly.
  42
  43 ## USAGE
  44
  45 Use just like a regular ES6 Map.
  46
  47 ```javascript
  48 var PseudoMap = require('pseudomap')
  49
  50 // optionally provide a pseudomap, or an array of [key,value] pairs
  51 // as the argument to initialize the map with
  52 var myMap = new PseudoMap()
  53
  54 myMap.set(1, 'number 1')
  55 myMap.set('1', 'string 1')
  56 var akey = {}
  57 var bkey = {}
  58 myMap.set(akey, { some: 'data' })
  59 myMap.set(bkey, { some: 'other data' })
  60 ```