Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 50578f0

Browse filesBrowse files
leebyronleebyron
committed
documentation
1 parent 1eebf01 commit 50578f0
Copy full SHA for 50578f0

File tree

1 file changed

+107
-42
lines changed
Filter options

1 file changed

+107
-42
lines changed

‎README.md

Copy file name to clipboardExpand all lines: README.md
+107-42Lines 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)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.