Skip to content

Commit 9710990

Browse files
leebyronleebyron
committed
Readme
1 parent 24d7c10 commit 9710990

File tree

1 file changed

+37
-25
lines changed

1 file changed

+37
-25
lines changed

‎README.md

+37-25
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,29 @@
1-
Immutable.js [![Build Status](https://travis-ci.org/facebook/immutable-js.svg)](https://travis-ci.org/facebook/immutable-js)
2-
============
1+
Immutable collections for JavaScript
2+
====================================
33

4-
Persistent immutable data collections for JavaScript.
4+
[![Build Status](https://travis-ci.org/facebook/immutable-js.svg)](https://travis-ci.org/facebook/immutable-js)
55

6-
**Converting to v3 from v2? Check out the [upgrade guide](https://github.com/facebook/immutable-js/wiki/Upgrading-to-Immutable-v3).**
7-
8-
Immutable data cannot be changed once created, leading to much simpler
6+
[Immutable][] data cannot be changed once created, leading to much simpler
97
application development, no defensive copying, and enabling advanced memoization
10-
techniques.
8+
and change detection techniques with simple logic. [Persistent][] data presents
9+
a mutative API which does not update the data in-place, but instead always
10+
yields new updated data.
1111

12-
`Immutable` provides `List`, `Stack`, `Map`, `OrderedMap`, `Record`
13-
and `Set` by using persistent [hash maps tries](http://en.wikipedia.org/wiki/Hash_array_mapped_trie)
14-
and [vector tries](http://hypirion.com/musings/understanding-persistent-vector-pt-1)
15-
as popularized by Clojure and Scala. They achieve efficiency on modern
16-
JavaScript VMs by using structural sharing and minimizing the need to copy or
17-
cache data.
12+
`Immutable` provides Persistent Immutable `List`, `Stack`, `Map`, `OrderedMap`,
13+
`Set`, `OrderedSet` and `Record`. They are highly efficient on modern JavaScript
14+
VMs by using structural sharing via [hash maps tries][] and
15+
[vector tries][] as popularized by Clojure and Scala,
16+
minimizing the need to copy or cache data.
1817

1918
`Immutable` also provides a lazy `Seq`, allowing efficient
2019
chaining of collection methods like `map` and `filter` without creating
2120
intermediate representations. Create some `Seq` with `Range` and `Repeat`.
2221

22+
[Persistent]: http://en.wikipedia.org/wiki/Persistent_data_structure
23+
[Immutable]: http://en.wikipedia.org/wiki/Immutable_object
24+
[hash maps tries]: (http://en.wikipedia.org/wiki/Hash_array_mapped_trie)
25+
[vector tries]: (http://hypirion.com/musings/understanding-persistent-vector-pt-1)
26+
2327

2428
Getting started
2529
---------------
@@ -101,8 +105,8 @@ due to easy to make programmer error. Since immutable data never changes,
101105
subscribing to changes throughout the model is a dead-end and new data can only
102106
ever be passed from above.
103107

104-
This model of data flow aligns well with the architecture of [React](http://facebook.github.io/react/)
105-
and especially well with an application designed using the ideas of [Flux](http://facebook.github.io/flux/docs/overview.html).
108+
This model of data flow aligns well with the architecture of [React][]
109+
and especially well with an application designed using the ideas of [Flux][].
106110

107111
When data is passed from above rather than being subscribed to, and you're only
108112
interested in doing work when something has changed, you can use equality.
@@ -126,16 +130,22 @@ var map1 = Immutable.Map({a:1, b:2, c:3});
126130
var clone = map1;
127131
```
128132

133+
[React]: http://facebook.github.io/react/
134+
[Flux]: http://facebook.github.io/flux/docs/overview.html
135+
129136

130137
JavaScript-first API
131138
--------------------
132139

133140
While `immutable` is inspired by Clojure, Scala, Haskell and other functional
134141
programming environments, it's designed to bring these powerful concepts to
135142
JavaScript, and therefore has an Object-Oriented API that closely mirrors that
136-
of ES6 [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array),
137-
[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), and
138-
[Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set).
143+
of [ES6][] [Array][], [Map][], and [Set][].
144+
145+
[ES6]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/New_in_JavaScript/ECMAScript_6_support_in_Mozilla
146+
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
147+
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
148+
[Set]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
139149

140150
The difference for the immutable collections is that methods which would mutate
141151
the collection, like `push`, `set`, `unshift` or `splice` instead return a new
@@ -154,8 +164,8 @@ assert(list4.size === 13);
154164
assert(list4.get(0) === 1);
155165
```
156166

157-
Almost all of the methods on `Array` will be found in similar form on
158-
`Immutable.List`, those of `Map` found on `Immutable.Map`, and those of `Set`
167+
Almost all of the methods on [Array][] will be found in similar form on
168+
`Immutable.List`, those of [Map][] found on `Immutable.Map`, and those of [Set][]
159169
found on `Immutable.Set`, including collection operations like `forEach()`
160170
and `map()`.
161171

@@ -210,9 +220,9 @@ JSON.stringify(deep) // '{"a":1,"b":2,"c":[3,4,5]}'
210220

211221
`Immutable` takes advantage of features added to JavaScript in [ES6][],
212222
the latest standard version of ECMAScript (JavaScript), including [Iterators][],
213-
[Arrow Functions][], and [Classes][]. It's also inspired by the Map and Set
214-
collections added to ES6. The library is "transpiled" to ES3 in order to support
215-
all modern browsers.
223+
[Arrow Functions][], [Classes][], and [Modules][]. It's also inspired by the
224+
[Map][] and [Set][] collections added to ES6. The library is "transpiled" to ES3
225+
in order to support all modern browsers.
216226

217227
All examples are presented in ES6. To run in all browsers, they need to be
218228
translated to ES3.
@@ -224,10 +234,10 @@ foo.map(x => x * x);
224234
foo.map(function (x) { return x * x; });
225235
```
226236

227-
[ES6]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/New_in_JavaScript/ECMAScript_6_support_in_Mozilla
228237
[Iterators]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/The_Iterator_protocol
229238
[Arrow Functions]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions
230239
[Classes]: http://wiki.ecmascript.org/doku.php?id=strawman:maximally_minimal_classes
240+
[Modules]: http://www.2ality.com/2014/09/es6-modules-final.html
231241

232242

233243
Nested Structures
@@ -323,10 +333,12 @@ assert(map1 !== map2);
323333
assert(Immutable.is(map1, map2) === true);
324334
```
325335

326-
`Immutable.is()` uses the same measure of equality as [Object.is](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
336+
`Immutable.is()` uses the same measure of equality as [Object.is][]
327337
including if both are immutable and all keys and values are equal
328338
using the same measure of equality.
329339

340+
[Object.is]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is
341+
330342

331343
Batching Mutations
332344
------------------

0 commit comments

Comments
 (0)