Immutable.js

Much of what makes application development difficult is tracking mutation and maintaining state. Developing with immutable data encourages you to think differently about how data flows through your application.

「对 Immutable 对象的任何修改或添加删除操作都会返回一个新的 Immutable 对象」。

These data structures are highly efficient on modern JavaScript VMs by using structural sharing via hash maps tries and vector tries as popularized by Clojure and Scala, minimizing the need to copy or cache data.

Immutable 实现的原理是 Persistent Data Structure（持久化数据结构），也就是使用旧数据创建新数据时，要保证旧数据同时可用且不变。同时为了避免 deepCopy 把所有节点都复制一遍带来的性能损耗，Immutable 使用了 Structural Sharing（结构共享），即如果对象树中一个节点发生变化，只修改这个节点和受它影响的父节点，其它节点则进行共享。

特点：

  • 降低了 Mutable 所带来的复杂度。
  • 使用了 Structure Sharing 而尽量复用内存，无引用的对象会被垃圾回收。
  • 时间旅行。
  • 并发安全，并不需要并发锁这种东西的存在了。
  • 拥抱 Functional Programming。

代价：

  • 新的 API 学习成本、增加资源文件大小，容易和原生对象混淆。
  1. // Create
  2. var Immutable = require('immutable');
  3. var map1 = Immutable.Map({a:1, b:2, c:3});
  4. var map2 = map1.set('b', 50);
  5. map1.get('b'); // 2
  6. map2.get('b'); // 50
  8. // Nested Structures
  9. var nested = Immutable.fromJS({a:{b:{c:[3,4,5]}}});
  10. // Map { a: Map { b: Map { c: List [ 3, 4, 5 ] } } }
  11. var nested2 = nested.mergeDeep({a:{b:{c:[3,4,5]}}});
  12. // Map { a: Map { b: Map { c: List [ 3, 4, 5 ], d: 6 } } }
  13. nested2.getIn(['a', 'b', 'd']); // 6
  14. var nested3 = nested2.updateIn(['a', 'b', 'd'], value => value + 1);
  15. // Map { a: Map { b: Map { c: List [ 3, 4, 5 ], d: 7 } } }
  16. var nested4 = nested3.updateIn(['a', 'b', 'c'], list => list.push(6));
  17. // Map { a: Map { b: Map { c: List [ 3, 4, 5, 6 ], d: 7 } } }
  19. // Compare
  20. var map1 = Immutable.Map({a:1, b:2, c:3});
  21. var map2 = map1.set('b', 2);
  22. assert(map1.equals(map2) === true);
  24. var map1 = Immutable.Map({a:1, b:1, c:1});
  25. var map2 = Immutable.Map({a:1, b:1, c:1});
  26. assert(map1 !== map2);
  27. assert(Object.is(map1, map2) === false);
  28. assert(Immutable.is(map1, map2) === true);
  30. // Merge
  31. var map1 = Immutable.Map({a:1, b:2, c:3, d:4});
  32. var map2 = Immutable.Map({c:10, a:20, t:30});
  33. var obj = {d:100, o:200, g:300};
  34. var map3 = map1.merge(map2, obj);
  35. // Map { a: 20, b: 2, c: 10, d: 100, t: 30, o: 200, g: 300 }
  37. // Convert Back
  38. var deep = Immutable.Map({ a: 1, b: 2, c: Immutable.List.of(3, 4, 5) });
  39. deep.toObject() // { a: 1, b: 2, c: List [ 3, 4, 5 ] }
  40. deep.toArray() // [ 1, 2, List [ 3, 4, 5 ] ]
  41. deep.toJS() // { a: 1, b: 2, c: [ 3, 4, 5 ] }
  42. JSON.stringify(deep) // '{"a":1,"b":2,"c":[3,4,5]}'
  44. // Helpers
  45. Immutable.Range(10, 30, 5); // [10, 15, 20, 25, 30]
  46. Immutable.Repeat('bar',4); // ['bar','bar','bar','bar']

List, Set and Ordered Set

  • Set: A Collection of unique values with O(log32 N) adds and has.
  1. List.isList()
  2. List.of(values)
  3. Set.fromKeys(object)
  5. list.set(index, value)
  6. list.delete(index)
  7. list.insert(index, value)
  8. list.clear()
  9. list.push(v)
  10. list.pop()
  11. list.shift()
  12. list.unshift(v)
  13. list.update(index, updater)
  14. list.merge() / mergeWith() / mergeDeep() / mergeDeepWith()
  15. list.setSize(size)
  17. list.setIn(path, value)
  18. list.deleteIn(path)
  19. list.updateIn()
  20. list.mergeIn()
  21. list.mergeDeepIn()
  23. set.add()
  24. set.union()
  25. set.intersect()
  26. set.subtract()

Map, Ordered Map

They almost share the same API.

  • Ordered Map: A type of Map that has the additional guarantee that the iteration order of entries will be the order in which they were set().
  1. Map().set(List.of(1), 'listofone').get(List.of(1));
  2. // 'listofone'
  4. Map.isMap()
  5. Map.of()
  7. Map.set() | delete() | clear() | update() | merge()
  9. var x = Immutable.Map({a: 10, b: 20, c: 30});
  10. var y = Immutable.Map({b: 40, a: 50, d: 60});
  11. x.mergeWith((prev, next) => prev / next, y) // { a: 0.2, b: 0.5, c: 30, d: 60 }
  12. y.mergeWith((prev, next) => prev / next, x) // { b: 2, a: 5, d: 60, c: 30 }
  14. var x = Immutable.fromJS({a: { x: 10, y: 10 }, b: { x: 20, y: 50 } });
  15. var y = Immutable.fromJS({a: { x: 2 }, b: { y: 5 }, c: { z: 3 } });
  16. x.mergeDeepWith((prev, next) => prev / next, y)
  17. // {a: { x: 5, y: 10 }, b: { x: 20, y: 10 }, c: { z: 3 } }
  19. map.setIn()
  20. map.deleteIn()
  21. map.updateIn()
  22. map.mergeIn()
  23. map.mergeDeepIn()
  25. // Unique Features

Stack

Stacks are indexed collections which support very efficient O(1) addition and removal from the front using unshift(v) and shift().

  1. Stack.isStack()
  2. Stack.of()
  4. // Read Values
  5. stack.peek() === stack.first()
  7. stack.clear()
  8. stack.push()
  9. stack.pop()

Record

Creates a new Class which produces Record instances. A record is similar to a JS object, but enforce a specific set of allowed string keys, and have default values.

  1. var ABRecord = Record({a:1, b:2})
  2. var myRecord = new ABRecord({b:3})
  4. myRecord.size // 2
  5. myRecord.get('a') // 1
  6. myRecord.get('b') // 3
  7. myRecordWithoutB = myRecord.remove('b')
  8. myRecordWithoutB.get('b') // 2
  9. myRecordWithoutB.size // 2
  11. var myRecord = new ABRecord({b:3, x:10})
  12. myRecord.get('x') // undefined
  14. class ABRecord extends Record({a:1,b:2}) {
  15.   getAB() {
  16.     return this.a + this.b;
  17.   }
  18. }
  20. var myRecord = new ABRecord({b: 3})
  21. myRecord.getAB() // 4

Seq and Iterable

Represents a sequence of values, but may not be backed by a concrete data structure.

Seq describes a lazy operation, allowing them to efficiently chain use of all the Iterable methods (such as map and filter).

  • Seq is immutable — Once a Seq is created, it cannot be changed, appended to, rearranged or otherwise modified. Instead, any mutative method called on a Seq will return a new Seq.
  • Seq is lazy — Seq does as little work as necessary to respond to any method call. Values are often created during iteration, including implicit iteration when reducing or converting to a concrete data structure such as a List or JavaScript Array.

Seq allows for the efficient chaining of operations, allowing for the expression of logic that can otherwise be very tedious.

  1. var oddSquares = Immutable.Seq.of(1,2,3,4,5,6,7,8)
  2.   .filter(x => x % 2).map(x => x * x);
  3. // filter only called thirds and map only called once

Basic APIs

  1. Iterable.isIterable()
  2. Iterable.isKeyed()
  3. Iterable.isIndexed()
  4. Iterable.isAssociative()
  5. Iterable.isOrdered()
  7. Seq.isSeq()
  8. Seq.of()
  10. Seq.size
  12. // map will execute only 3 times
  13. var squares = Seq.of(1,2,3).map(x => x * x).cacheResult();
  14. squares.join() + squares.join();
  16. seq.get() | set() | has() | includes() | first() | last();
  17. seq.getIn() | hasIn()
  18. seq.toJS() | toArray() | toObject()
  19. seq.toMap() | toOrderedMap() | toSet() | toOrderedSet()
  20. seq.toList() | toStack()
  22. // Iterators
  23. seq.keys()
  24. seq.values()
  25. seq.entries()
  27. // Iterables Seq
  28. seq.keySeq()
  29. seq.valueSeq()
  30. seq.entrySeq()
  32. // Seq Algorithms
  33. seq.map()
  34. seq.filter()
  35. seq.filterNot()
  36. seq.reverse()
  37. seq.sort()
  38. seq.sortBy()
  39. seq.groupBy()
  41. // Subsets
  42. seq.slice(begin, end)
  43. seq.rest()
  44. seq.butLast()
  45. seq.skip(excludeAfter)
  46. seq.skipLast()
  47. seq.skipWhile()
  48. seq.skipUntil()
  49. seq.take()
  50. seq.takeLast()
  51. seq.taskWhile()
  52. seq.takeUntil()
  54. // Combination
  55. seq.concat()
  56. seq.flatten()
  57. seq.flatMap()
  59. // Reducing the Values
  60. seq.reduce()
  61. seq.reduceRight()
  62. seq.every()
  63. seq.some()
  64. seq.join()
  65. seq.count()
  66. seq.countBy()
  67. seq.isEmpty()
  69. // Search
  70. seq.find()
  71. seq.findLast()
  72. seq.findEntry()
  73. seq.findLastEntry()
  74. seq.max()
  75. seq.maxBy()
  76. seq.min()
  77. seq.minBy()
  79. // Comparison
  80. seq.isSubset()
  81. seq.isSuperset()

Ref