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

   1 # sigmund
   2
   3 Quick and dirty signatures for Objects.
   4
   5 This is like a much faster `deepEquals` comparison, which returns a
   6 string key suitable for caches and the like.
   7
   8 ## Usage
   9
  10 ```javascript
  11 function doSomething (someObj) {
  12   var key = sigmund(someObj, maxDepth) // max depth defaults to 10
  13   var cached = cache.get(key)
  14   if (cached) return cached
  15
  16   var result = expensiveCalculation(someObj)
  17   cache.set(key, result)
  18   return result
  19 }
  20 ```
  21
  22 The resulting key will be as unique and reproducible as calling
  23 `JSON.stringify` or `util.inspect` on the object, but is much faster.
  24 In order to achieve this speed, some differences are glossed over.
  25 For example, the object `{0:'foo'}` will be treated identically to the
  26 array `['foo']`.
  27
  28 Also, just as there is no way to summon the soul from the scribblings
  29 of a cocaine-addled psychoanalyst, there is no way to revive the object
  30 from the signature string that sigmund gives you.  In fact, it's
  31 barely even readable.
  32
  33 As with `util.inspect` and `JSON.stringify`, larger objects will
  34 produce larger signature strings.
  35
  36 Because sigmund is a bit less strict than the more thorough
  37 alternatives, the strings will be shorter, and also there is a
  38 slightly higher chance for collisions.  For example, these objects
  39 have the same signature:
  40
  41     var obj1 = {a:'b',c:/def/,g:['h','i',{j:'',k:'l'}]}
  42     var obj2 = {a:'b',c:'/def/',g:['h','i','{jkl']}
  43
  44 Like a good Freudian, sigmund is most effective when you already have
  45 some understanding of what you're looking for.  It can help you help
  46 yourself, but you must be willing to do some work as well.
  47
  48 Cycles are handled, and cyclical objects are silently omitted (though
  49 the key is included in the signature output.)
  50
  51 The second argument is the maximum depth, which defaults to 10,
  52 because that is the maximum object traversal depth covered by most
  53 insurance carriers.