Skip to content
This repository was archived by the owner on Jan 6, 2025. It is now read-only.

Commit 285a03f

Browse files
frinyvonnickfrinyvonnick
authored
📝 Add a getting started in documentation (#182)
* 🎉 Set up getting started architecture * 📝 Fill getting started first section * 📝 Fill Setting nested properties section * 📝 Fill basic array operations section * 📝 Fill grouping multiple operations section * 🎉 End first draft and take care of @nlepage review * 📝 Finish getting started
1 parent a59f486 commit 285a03f

File tree

5 files changed

+282
-2
lines changed

5 files changed

+282
-2
lines changed

‎.github/CODE_OF_CONDUCT.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
![immutadot logo](https://raw.githubusercontent.com/Zenika/immutadot/master/misc/otter.svg?sanitize=true)
2+
===
3+
14
# Contributor Covenant Code of Conduct
25

36
## Our Pledge

‎.github/CONTRIBUTING.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
![immutadot logo](https://raw.githubusercontent.com/Zenika/immutadot/master/misc/otter.svg?sanitize=true)
2+
===
3+
14
# Contributing to immutad●t
25
First of all thank you for expressing interest in immutad●t! :+1:<br />
36
We are very happy to welcome new contributors. :tada:

‎README.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
![immutadot logo](https://raw.githubusercontent.com/Zenika/immutadot/master/misc/otter.svg?sanitize=true)
2-
=================
2+
===
33

44
A JavaScript library to deal with nested immutable structures.
55

@@ -220,7 +220,13 @@ Update large todos list (100000 items):
220220

221221
## Documentation
222222

223-
Latest API documentation for our different packages are available here:
223+
### Getting started
224+
225+
A fast overview of immutad●t's features is available in the [Getting started](https://github.com/Zenika/immutadot/blob/master/docs/GETTING_STARTED.md) guide.
226+
227+
### API
228+
229+
The detailed API documentations of the different packages are available here:
224230
- [immutadot](https://zenika.github.io/immutadot/immutadot)
225231
- [immutadot-lodash](https://zenika.github.io/immutadot/immutadot-lodash/)
226232

‎docs/GETTING_STARTED.md‎

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
![immutadot logo](https://raw.githubusercontent.com/Zenika/immutadot/master/misc/otter.svg?sanitize=true)
2+
===
3+
4+
# Getting started
5+
6+
This guide will give you an overview of immutad●t features.
7+
8+
Feel free to try the following examples with [runkit](https://npm.runkit.com/immutadot).
9+
10+
## Installation
11+
12+
immutad●t is available on [npm repository](https://www.npmjs.com/package/immutadot).
13+
14+
using yarn:
15+
16+
```shell
17+
$ yarn add immutadot
18+
```
19+
20+
using npm:
21+
22+
```shell
23+
$ npm install immutadot
24+
```
25+
26+
or you can directly download [sources](https://github.com/Zenika/immutadot/releases).
27+
28+
## Setting nested properties
29+
30+
[ES2015+ destructuring](https://mdn.io/destructuring) provides you all necessary tools to keep nested structures immutable. The [spread operator](https://mdn.io/Spread_operator) is a succinct syntax to create new arrays and objects using existing ones.
31+
32+
```js
33+
const lutraLutra = {
34+
commonNames: ['eurasian otter'],
35+
}
36+
37+
const newLutraLutra = {
38+
...lutraLutra,
39+
name: 'Lutra lutra',
40+
}
41+
```
42+
43+
With nested structures this syntax becomes more tedious to write, and harder to read:
44+
45+
```js
46+
const animals = {
47+
weasels: {
48+
lutraLutra: {
49+
commonNames: ['eurasian otter'],
50+
}
51+
}
52+
}
53+
54+
const newAnimals = {
55+
...animals,
56+
weasels: {
57+
...animals.weasels,
58+
lutraLutra: {
59+
...animals.weasels.otter,
60+
name: 'Lutra lutra',
61+
}
62+
}
63+
}
64+
```
65+
66+
This can be done nicely with [`set()`](https://zenika.github.io/immutadot/immutadot/1.0/core.html#.set):
67+
68+
```js
69+
import { set } from 'immutadot'
70+
71+
const animals = {
72+
weasels: {
73+
lutraLutra: {
74+
commonNames: ['eurasian otter'],
75+
}
76+
}
77+
}
78+
79+
const newAnimals = set(animals, 'weasels.lutraLutra.name', 'Lutrinae')
80+
```
81+
82+
Deleting a nested property can be done with [`unset()`](https://zenika.github.io/immutadot/immutadot/1.0/core.html#.unset).
83+
84+
## Basic array operations
85+
86+
Values can be added in a nested array with [`push()`](https://zenika.github.io/immutadot/immutadot/1.0/array.html#.push):
87+
88+
```js
89+
import { push } from 'immutadot'
90+
91+
const animals = {
92+
weasels: {
93+
lutraLutra: {
94+
name: 'Lutra lutra',
95+
commonNames: ['eurasian otter'],
96+
},
97+
// Some more weasels...
98+
},
99+
}
100+
101+
const newAnimals = push(animals, 'weasels.lutraLutra.commonNames', 'european otter', 'common otter')
102+
```
103+
104+
## Updating properties
105+
106+
[immutad●t's API](https://zenika.github.io/immutadot/immutadot/) offers basic functions to work with primitive types.
107+
108+
It is possible to perform custom updates with [`update()`](https://zenika.github.io/immutadot/immutadot/1.0/core.html#.update):
109+
110+
```js
111+
import { update } from 'immutadot'
112+
113+
const animals = {
114+
weasels: {
115+
lutraLutra: {
116+
name: 'Lutra lutra',
117+
commonNames: ['eurasian otter', 'european otter', 'common otter'],
118+
},
119+
// Some more weasels...
120+
},
121+
}
122+
123+
const newAnimals = update(animals, 'weasels.lutraLutra', lutraLutra => {
124+
return {
125+
scientificName: lutraLutra.name, // Rename property name to scientificName
126+
commonNames: lutraLutra.commonNames,
127+
}
128+
})
129+
```
130+
131+
immutadot includes all common functions of Array's prototype, see [documentation's array section](https://zenika.github.io/immutadot/immutadot/1.0/array.html).
132+
133+
## Batch operations
134+
135+
### Arrays
136+
137+
Operations can be applied on several elements of an array with the slice notation:
138+
139+
```js
140+
import { capitalize } from 'immutadot-lodash' // capitalize uses lodash
141+
142+
const animals = {
143+
weasels: {
144+
lutraLutra: {
145+
scientificName: 'Lutra lutra',
146+
commonNames: ['eurasian otter', 'european otter', 'common otter'],
147+
},
148+
// Some more weasels...
149+
},
150+
}
151+
152+
const newAnimals = capitalize(animals, 'weasels.lutraLutra.commonNames[:]')
153+
```
154+
155+
The slice notation follows the syntax `[start:end]`, `start` and `end` are both optional, `start` defaults to `0` and `end` to `Array.length`.
156+
157+
### Objects
158+
159+
Batch operations are also possible on properties of an object with the list notation:
160+
161+
```js
162+
import { set } from 'immutadot'
163+
164+
const animals = {
165+
weasels: {
166+
lutraLutra: {
167+
scientificName: 'Lutra lutra',
168+
commonNames: ['Eurasian otter', 'European otter', 'Common otter'],
169+
},
170+
pteronuraBrasiliensis: {
171+
scientificName: 'Pteronura brasiliensis',
172+
commonNames: ['Giant otter', 'Giant river otter'],
173+
},
174+
// Some more weasels...
175+
},
176+
}
177+
178+
const newAnimals = set(animals, 'weasels.{*}.family', 'Mustelidae')
179+
```
180+
181+
The list notation follows the syntax `{*}` to iterate over all the properties of an object.
182+
It is also possible to pick specific properties with the syntax `{prop1,prop2}`.
183+
184+
### Path notation
185+
186+
For more information on the path notation of immutad●t, see the [path notation documentation](./PATH_NOTATION.md).
187+
188+
## Grouping modifications
189+
190+
Different operations can be grouped with [`flow()`](https://zenika.github.io/immutadot/immutadot/1.0/flow.html#.flow):
191+
192+
```js
193+
import { flow, push, set } from 'immutadot'
194+
import { capitalize } from 'immutadot-lodash'
195+
196+
const animals = {
197+
weasels: {
198+
lutraLutra: {
199+
commonNames: ['eurasian otter'],
200+
},
201+
pteronuraBrasiliensis: {
202+
scientificName: 'Pteronura brasiliensis',
203+
commonNames: ['Giant otter', 'Giant river otter'],
204+
},
205+
// Some more weasels...
206+
},
207+
}
208+
209+
const newAnimals = flow(
210+
set('weasels.lutraLutra.scientificName', 'Lutrinae'),
211+
push('weasels.lutraLutra.commonNames', 'european otter', 'common otter'),
212+
capitalize('weasels.lutraLutra.commonNames[:]'),
213+
set('weasels.{*}.family', 'Mustelidae'),
214+
)(animals)
215+
```
216+
217+
All immutad●t functions support currying the first parameter and can be used without `flow`:
218+
219+
```js
220+
import { set } from 'immutadot'
221+
222+
const animals = {
223+
weasels: {
224+
lutraLutra: {
225+
commonNames: ['eurasian otter'],
226+
}
227+
}
228+
}
229+
230+
const newAnimals = set('weasels.lutraLutra.scientificName', 'Lutrinae')(animals)
231+
```
232+
233+
## Reusing custom updates
234+
235+
New immutad●t functions can be created with [`convert()`](https://zenika.github.io/immutadot/immutadot/1.0/core.html#.convert):
236+
237+
```js
238+
import { convert } from 'immutadot'
239+
240+
const renameProp = convert((obj, prop, newProp) => {
241+
const { [prop]: val, ...rest } = obj
242+
return {
243+
...rest,
244+
[newProp]: val,
245+
}
246+
})
247+
248+
const animals = {
249+
weasels: {
250+
lutraLutra: {
251+
name: 'Lutra lutra',
252+
commonNames: ['eurasian otter', 'european otter', 'common otter'],
253+
},
254+
// Some more weasels...
255+
},
256+
}
257+
258+
const newAnimals = renameProp(animals, 'weasels.lutraLutra', 'name', 'scientificName')
259+
```

‎docs/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
![immutadot logo](https://raw.githubusercontent.com/Zenika/immutadot/master/misc/otter.svg?sanitize=true)
2+
===
3+
4+
# Documentation
5+
16
Latest API documentations for our different packages are available here:
27
- [immutadot](https://zenika.github.io/immutadot/immutadot)
38
- [immutadot-lodash](https://zenika.github.io/immutadot/immutadot-lodash/)
@@ -6,3 +11,7 @@ Older API documentations :
611
- [immutadot 0.3](https://zenika.github.io/immutadot/immutadot/0.3)
712
- [immutadot 0.2](https://zenika.github.io/immutadot/immutadot/0.2)
813
- [immutadot 0.1](https://zenika.github.io/immutadot/immutadot/0.1)
14+
15+
Other ressources:
16+
- [Getting started](./GETTING_STARTED)
17+
- [Migration guide to 1.0](./MIGRATING_TO_1.0)

0 commit comments

Comments
 (0)