10000 documentation · ui-frontend/immutable-js@50578f0 · GitHub
[go: up one dir, main page]
Skip to content

Commit 50578f0

Browse files
leebyronleebyron
committed
documentation
1 parent 1eebf01 commit 50578f0

File tree

1 file changed

+107
-42
lines changed

1 file changed

+107
-42
lines changed

‎README.md

Lines changed: 107 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Immutable data cannot be changed once created, leading to much simpler
55
application development and enabling techniques from functional programming such
66
as lazy evaluation. This provides a lazy `Sequence`, allowing efficient chaining
77
of sequence methods like `map` and `filter` without creating intermediate
8-
represenations.
8+
representations.
99

1010
`immutable-data` implements a sparse `Vector`, `Map`, `OrderedMap`, `Set` and
1111
`Range` by using lazy sequences and hash maps tries. They achieve acceptable
@@ -30,7 +30,13 @@ var map = Immutable.Map({a:1, b:2, c:3});
3030

3131
To use `immutable-data` from a browser, try [Browserify](http://browserify.org/).
3232

33-
To use `immutable-data` from a [TypeScript](http://www.typescriptlang.org/) program.
33+
34+
Use these Immutable collections and sequences as you would use native
35+
collections in your [TypeScript](typescriptlang.org) programs while still taking
36+
advantage of type generics, error detection, and auto-complete in your IDE.
37+
38+
(Because of TypeScript 1.0's issue with NodeJS module resolution, you must
39+
require the full file path)
3440

3541
```javascript
3642
import Immutable = require('./node_modules/immutable-data/dist/Immutable');
@@ -68,11 +74,100 @@ assert(map1 === map2);
6874
```
6975

7076

77+
JavaScript-first API
78+
--------------------
79+
80+
While `immutable-data` is inspired by Clojure, Haskell and other functional
81+
programming environments, it's designed to bring these powerful concepts to
82+
JavaScript, and therefore has an Object-Oriented API that closely mirrors that
83+
of [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array),
84+
[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), and
85+
[Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set).
86+
87+
The only difference is that every method that would mutate the collection
88+
instead returns a new collection.
89+
90+
```javascript
91+
var vect1 = Immutable.Vector(1, 2);
92+
var vect2 = vect1.push(3, 4, 5);
93+
var vect3 = vect2.slice(1, -1);
94+
var vect4 = vect1.concat(vect2, vect3, vect4);
95+
assert(vect1.length === 2);
96+
assert(vect2.length === 5);
97+
assert(vect3.length === 3);
98+
assert(vect4.length === 10);
99+
```
100+
101+
Almost all of the methods on `Array` will be found in similar form on
102+
`Immutable.Vector`, those of `Map` found on `Immutable.Map`, and those of `Set`
103+
found on `Immutable.Set`, including sequence operations like `forEach` and `map`.
104+
105+
```javascript
106+
> var alpha = Immutable.Map({a:1, b:2, c:3, d:4});
107+
> alpha.map((v, k) => k.toUpperCase()).forEach(k => console.log(k));
108+
A
109+
B
110+
C
111+
D
112+
```
113+
114+
Designed to inter-operate with your existing JavaScript, `immutable-data`
115+
accepts plain JavaScript Array and Objects anywhere a method expects a
116+
`Sequence` with no performance penalty.
117+
118+
```javascript
119+
var map1 = Immutable.Map({a:1, b:2, c:3, d:4});
120+
var map2 = Immutable.Map({c:10, a:20, t:30});
121+
var obj = {d:100, o:200, g:300};
122+
var map3 = map1.merge(map2, obj);
123+
// Map { a: 20, b: 2, c: 10, d: 1000, t: 30, o: 2000, g: 300 }
124+
```
125+
126+
All `immutable-data` Sequences can be converted to plain JavaScript Arrays and
127+
Objects shallowly with `toArray()` and `toObject()` or deeply with `toJSON()`,
128+
allowing `JSON.stringify` to work automatically.
129+
130+
```javascript
131+
var deep = Immutable.Map({a:1, b:2, c:Immutable.Vector(3,4,5)});
132+
deep.toObject() // { a: 1, b: 2, c: Vector [ 3, 4, 5 ] }
133+
deep.toArray() // [ 1, 2, Vector [ 3, 4, 5 ] ]
134+
deep.toJSON() // { a: 1, b: 2, c: [ 3, 4, 5 ] }
135+
JSON.stringify(deep) // '{"a":1,"b":2,"c":[3,4,5]}'
136+
```
137+
138+
139+
Nested Structures
140+
-----------------
141+
142+
The collections in `immutable-data` are intended to be nested, allowing for deep
143+
trees of data, similar to JSON.
144+
145+
```javascript
146+
var nested = Immutable.fromJSON({a:{b:{c:[3,4,5]}}});
147+
// Map { a: Map { b: Map { c: Vector [ 3, 4, 5 ] } } }
148+
```
149+
150+
A few power-tools allow for reading and operating on nested data. The
151+
most useful are `mergeDeep`, `getIn` and `updateIn`, found on `Vector`, `Map`
152+
and `OrderedMap`.
153+
154+
```javascript
155+
var nested2 = nested.mergeDeep({a:{b:{d:6}}});
156+
// Map { a: Map { b: Map { c: Vector [ 3, 4, 5 ], d: 6 } } }
157+
```
158+
159+
```javascript
160+
nested2.getIn(['a', 'b', 'd']); // 6
161+
var nested3 = nested2.updateIn(['a', 'b', 'd'], value => value + 1);
162+
// Map { a: Map { b: Map { c: Vector [ 3, 4, 5 ], d: 7 } } }
163+
```
164+
165+
71166
Lazy Sequences
72167
--------------
73168

74-
`immutable-data` provides a lazy `Sequence`, which is the base class for all of
75-
its collections. This allows for efficient chaining of sequence operations like
169+
The lazy `Sequence`, which is the base class for all collections in
170+
`immutable-data`. This allows for efficient chaining of sequence operations like
76171
`map` and `filter` as well as allowing for defining logic that is otherwise very
77172
difficult to express.
78173

@@ -83,7 +178,7 @@ console.log(map2); // Map { A: 1, B: 1, C: 1 }
83178
```
84179

85180

86-
Equality treats Collections as data
181+
Equality treats Collections as Data
87182
-----------------------------------
88183

89184
`immutable-data` provides equality which treats immutable data structures as
@@ -96,42 +191,12 @@ assert(map1 !== map2);
96191
assert(Immutable.is(map1, map2) === true);
97192
```
98193

99-
`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) however adds:
100-
101-
* if both are immutable sequences and all keys and values are equal using the
102-
same measure of equality.
103-
104-
105-
JavaScript-first API
106-
--------------------
107-
108-
While `immutable-data` is inspired by Clojure, Haskell and other functional
109-
programming environments, it's designed to bring these powerful concepts to
110-
JavaScript, and therefore has an Object-Oriented API that closely mirrors that
111-
of [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array),
112-
[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), and
113-
[Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set).
114-
115-
The only difference is that every method that would mutate the collection
116-
instead returns a new collection.
117-
118-
```javascript
119-
var vect1 = Immutable.Vector(1,2);
120-
var vect2 = vect1.push(3,4,5);
121-
var vect3 = vect2.slice(1, -1).toVector();
122-
var vect4 = vect1.concat(vect2, vect3, vect4);
123-
assert(vect1.length === 2);
124-
assert(vect2.length === 5);
125-
assert(vect3.length === 3);
126-
assert(vect4.length === 10);
127-
```
128-
129-
Almost all of the methods on `Array` will be found in similar form on
130-
`Immutable.Vector`, those of `Map` found on `Immutable.Map`, and those of `Set`
131-
found on `Immutable.Set`, including sequence operations.
194+
`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)
195+
including if both are immutable sequences and all keys and values are equal
196+
using the same measure of equality.
132197

133198

134-
Batching mutations
199+
Batching Mutations
135200
------------------
136201

137202
> If a tree falls in the woods, does it make a sound?
@@ -160,10 +225,10 @@ assert(vect2.length === 6);
160225
```
161226

162227

163-
API
164-
---
228+
API Documentation
229+
-----------------
165230

166-
Reference: [Immutable.d.ts](./type-definitions/Immutable.d.ts)
231+
All documentation is contained within the type definition file, [Immutable.d.ts](./type-definitions/Immutable.d.ts).
167232

168233

169234
Contribution

0 commit comments

Comments
 (0)
0