Update documentation to reflect the new organization and new features #172

frinyvonnick · 2017-12-15T14:50:23Z

Prerequisites

I have read the Contributing guidelines
I have read the Code of conduct and I agree with it

Description

Update documentation to reflect the new organization and new features

Issue : #78

codecov-io · 2017-12-15T14:52:10Z

Codecov Report

Merging #172 into master will not change coverage.
The diff coverage is n/a.

@@          Coverage Diff          @@
##           master   #172   +/-   ##
=====================================
  Coverage     100%   100%           
=====================================
  Files          98     98           
  Lines         353    350    -3     
=====================================
- Hits          353    350    -3

Impacted Files	Coverage Δ
packages/immutadot/src/util/protect.js	`100% <0%> (ø)`	⬆️
packages/immutadot/src/path/consts.js	`100% <0%> (ø)`	⬆️
packages/immutadot/src/path/apply.js	`100% <0%> (ø)`	⬆️
packages/immutadot/src/seq/ChainWrapper.js	`100% <0%> (ø)`	⬆️
packages/immutadot/src/core/unset.js	`100% <0%> (ø)`	⬆️
packages/immutadot/src/core/set.js	`100% <0%> (ø)`	⬆️
packages/immutadot/src/path/toPath.js	`100% <0%> (ø)`	⬆️
packages/immutadot/src/core/update.js	`100% <0%> (ø)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f383dd7...56e903f. Read the comment docs.

hgwood · 2017-12-15T15:37:24Z

.github/CONTRIBUTING.md

@@ -22,8 +22,11 @@ Once you have cloned the project, run `yarn` to install all the dependencies.
 If you encounter trouble in the post-install phase involving `node-sass`, make sure you are building with VC++ 2013: `yarn config set msvs_version 2013`.

 #### Architecture :house:
-We have only one peer dependency on [lodash](https://lodash.com/) and we intend to keep it that way.<br />
-immutad●t is organized in namespaces (array, collection, lang, etc.), a lot like lodash, please try to respect this organization; if you are not sure where to put your code, ask for the right place in your issue or PR.
+immutad●t is managed as [monorepo](https://medium.com/netscape/the-case-for-monorepos-907c1361708a) using [lerna](https://lernajs.io/)


as a monorepo

hgwood · 2017-12-15T15:39:00Z

.github/CONTRIBUTING.md

-immutad●t is organized in namespaces (array, collection, lang, etc.), a lot like lodash, please try to respect this organization; if you are not sure where to put your code, ask for the right place in your issue or PR.
+immutad●t is managed as [monorepo](https://medium.com/netscape/the-case-for-monorepos-907c1361708a) using [lerna](https://lernajs.io/)
+
+The main package have no peer dependency and we intend to keep it that way.


hgwood · 2017-12-15T15:39:34Z

.github/CONTRIBUTING.md

-immutad●t is organized in namespaces (array, collection, lang, etc.), a lot like lodash, please try to respect this organization; if you are not sure where to put your code, ask for the right place in your issue or PR.
+immutad●t is managed as [monorepo](https://medium.com/netscape/the-case-for-monorepos-907c1361708a) using [lerna](https://lernajs.io/)
+
+The main package have no peer dependency and we intend to keep it that way.


Most packages have no peer dependencies. Did you mean dependencies?

Yes the best pratice when developping libraries is to put your dependencies as peer dependencies so you let host library or application choose the right version of your dependencies in case he also need them. Am i clear ?

OK but when you say "it has no peer dependencies", I understand that it may have "classic" dependencies, while I guess you mean to say it has no dependencies at all, right? If you say "it has no dependencies" then I understand it has neither dependencies nor peer dependencies.

hgwood · 2017-12-15T15:41:21Z

.github/CONTRIBUTING.md

+
+The main package have no peer dependency and we intend to keep it that way.
+
+Each package of immutad●t is organized in namespaces (array, collection, lang, etc.), a lot like lodash, please try to respect this organization; if you are not sure where to put your code, ask for the right place in your issue or PR.


I would put a period between lodash and please, and another one instead of the semi-colon.

hgwood · 2017-12-15T15:41:55Z

README.md

@@ -44,11 +44,11 @@ immutad●t uses plain JavaScript objects so you can access your data using stan

 ### Exhaustive and yet extensible

-immutad●t comes with a large set of built-in utilities, mostly based on [lodash](https://lodash.com/). You haven't found what you're looking for? Do it yourself with the `convert` feature.
+immutad●t comes with a large set of built-in utilities, mostly based on [ES2015+](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux). You can also found a package called [immutadot-lodash](https://github.com/Zenika/immutadot/tree/master/packages/immutadot-lodash) with some of [lodash](https://lodash.com/)'s utilities. You haven't found what you're looking for? Do it yourself with the `convert` feature.


You can also find

hgwood · 2017-12-15T15:43:33Z

README.md

+The list notation let you go trough each keys of objects used as collection or map to apply operations.
+
+```js
+toggle({ nested: { prop: { 1: { active: true }, 2: { active: false } } } }, 'nested.prop{*}.active')


According to #170, this is not going to be supported right away.

hgwood · 2017-12-15T15:44:02Z

README.md

+
+### Performances
+
+When appling operations on a path we create the minimum of objects or arrays needed to guarantee your data structure to be immutable.


I would replace "we" with "immutadot".

frinyvonnick · 2017-12-15T16:00:26Z

Thanks for your review @hgwood 👍 !

hgwood · 2017-12-15T18:55:36Z

README.md

@@ -123,7 +123,7 @@ toLowerCase({ nested: { prop: { 1: { msg: 'Hello' }, 2: { msg: 'Hi' }, 3: { msg

 ### Performances

-When appling operations on a path we create the minimum of objects or arrays needed to guarantee your data structure to be immutable.
+When appling operations on a path immutad●t create the minimum of objects or arrays needed to guarantee your data structure to be immutable.


Ah then "create" becomes "creates". Sorry I didn't realize that before.

nlepage · 2017-12-19T14:35:44Z

.github/CONTRIBUTING.md

@@ -22,8 +22,11 @@ Once you have cloned the project, run `yarn` to install all the dependencies.
 If you encounter trouble in the post-install phase involving `node-sass`, make sure you are building with VC++ 2013: `yarn config set msvs_version 2013`.

 #### Architecture :house:
-We have only one peer dependency on [lodash](https://lodash.com/) and we intend to keep it that way.<br />
-immutad●t is organized in namespaces (array, collection, lang, etc.), a lot like lodash, please try to respect this organization; if you are not sure where to put your code, ask for the right place in your issue or PR.
+immutad●t is managed as a [monorepo](https://medium.com/netscape/the-case-for-monorepos-907c1361708a) using [lerna](https://lernajs.io/)


I would mention yarn workspaces with a link to https://yarnpkg.com/lang/en/docs/workspaces/ before lerna.

nlepage · 2017-12-19T14:38:33Z

README.md

@@ -44,11 +44,11 @@ immutad●t uses plain JavaScript objects so you can access your data using stan

 ### Exhaustive and yet extensible

-immutad●t comes with a large set of built-in utilities, mostly based on [lodash](https://lodash.com/). You haven't found what you're looking for? Do it yourself with the `convert` feature.
+immutad●t comes with a large set of built-in utilities, mostly based on [ES2015+](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux). You can also find a package called [immutadot-lodash](https://github.com/Zenika/immutadot/tree/master/packages/immutadot-lodash) with some of [lodash](https://lodash.com/)'s utilities. You haven't found what you're looking for? Do it yourself with the `convert` feature.


You can use MDN short links https://mdn.io/... which will redirect to a full URL in the user's language.
And I'd rather link to JavaScript reference instead of global objects : https://mdn.io/JavaScript/Reference

nlepage · 2017-12-19T14:42:38Z

README.md


 ### Learning curve

-If you are already familiar with [lodash](https://lodash.com/) and [ES2015+](https://github.com/tc39/ecma262#ecmascript) then you should be able to use immutad●t quickly.
+If you are already familiar with [ES2015+](https://github.com/tc39/ecma262#ecmascript) and [lodash](https://lodash.com/) then you should be able to use immutad●t quickly.


You are using two different links for the same name "ES2015+", this one doesn't seem really appropriate, maybe use the link to MDN ?
I'm having doubts, should we really mention lodash here ?

I guess we should mention lodash because we have some features in our main packages that are directly inspired from lodash like chain, toggle, set, get, ...

nlepage · 2017-12-19T15:17:22Z

README.md

+
+### Slice notation
+
+The slice notation let you go trough arrays to apply operations without having to map arrays at each level of imbrication.


I would prefer "The slice notation lets you iterate over arrays...", what do you think ?

nlepage · 2017-12-19T15:34:23Z

README.md

+
+### Performances
+
+When appling operations on a path immutad●t creates the minimum of objects or arrays needed to guarantee your data structure to be immutable.


appling -> applying
We have to be careful about that, immutadot doesn't actually create the minimum instances. It tries to do it, and further improvements are planned on this.
So maybe be more qualified about this ?

nlepage · 2017-12-19T15:40:47Z

README.md

+
+### List notation
+
+The list notation let you go trough each keys of objects used as collection or map to apply operations.


What about "The list notation lets you iterate over the keys..."
It's not necessarily each keys...

frinyvonnick · 2017-12-20T11:02:43Z

After a discussion with @nlepage i'll try to make our README more welcoming for newcomers.

My goals are:

Compare immutadot examples with ES2015+ ones
Use funnier data than obj.nested.prop
Keep examples simple by using only set and toggle to demonstrate features

frinyvonnick · 2017-12-20T12:12:25Z

@nlepage i tried to write a more welcoming example in my last commit. What do you think about it ? Maybe it's too friendly ?

nlepage · 2017-12-20T15:12:28Z

README.md

@@ -70,26 +70,113 @@ or you can directly download [sources](https://github.com/Zenika/immutadot/relea

 ## Usage

-in browser:
+ES modules:


nlepage · 2017-12-20T15:14:57Z

README.md

 ```

 Feel free to [try immutad●t on runkit](https://npm.runkit.com/immutadot).

+## Dot notation


Use "Path notation" instead of "Dot notation" ?

nlepage · 2017-12-20T15:16:49Z

packages/immutadot/src/index.js

+    }
+  ]
+}
+*/


nlepage

The example section is a good start 👍
I think we should rewrite the top examples, especially the one with pickBy which is too complex.
Also simplify or move the examples on the path notation.

nlepage · 2017-12-20T15:29:18Z

README.md

+    },
+    {
+      vernacularName: 'otter',
+      scientificName: ''


Completely remove this line

nlepage · 2017-12-20T15:29:45Z

README.md

+const animals = {
+  weasel: [
+    {
+      vernacularName: 'badger',


You forgot to capitalize the vernacular names in the input.
It may be the occasion to quickly show the slice notation and immutadot-lodash :

import { capitalize } from 'immutadot-lodash' const newAnimals = capitalize(animals, 'weasel[:].vernacularName')

vs

import { capitalize } from 'lodash' const newAnimals = { ...animals, weasels: animals.weasels.map(weasel => { return { ...weasel, vernacularName: capitalize(weasel.vernacularName), } }), }

nlepage · 2017-12-20T15:30:43Z

README.md

+set(animals, 'animals.weasel[1].scientificName', 'Lutrinae')
+```
+
+result:


I wouldn't even write the result...

nlepage · 2017-12-20T15:31:47Z

README.md

+using immutad●t:
+
+```js
+set(animals, 'animals.weasel[1].scientificName', 'Lutrinae')


To be consistent : const newAnimals = ...

nlepage · 2017-12-20T15:38:15Z

README.md


 ```js
-  const { push } = require('immutadot')
+const animals = {
+  weasel: [


Pluralize weasels ?

nlepage · 2017-12-20T15:43:04Z

README.md


-  push({ nested: { prop: [1, 2] } }, 'nested.prop', 3, 4)
-  // → { nested: { prop: [1, 2, 3, 4] } }
+We forgot to write down otter's scientific name. Let's set this property with the right name ```Lutrinae```.


What about : "Let's add the otter's scientific name without mutating the original object structure :"

nlepage · 2017-12-20T15:48:14Z

README.md

-  // → { nested: { prop: [1, 2, 3, 4] } }
+We forgot to write down otter's scientific name. Let's set this property with the right name ```Lutrinae```.
+
+using ES2015+:


Have you tried to have two columns with some CSS ?

I tried. It's impossible 😢

frinyvonnick · 2017-12-24T09:57:20Z

@nlepage have you an idea about List notation example to make it more meaningfull ?

nlepage · 2018-01-03T12:39:01Z

.github/CONTRIBUTING.md

-immutad●t is organized in namespaces (array, collection, lang, etc.), a lot like lodash, please try to respect this organization; if you are not sure where to put your code, ask for the right place in your issue or PR.
+immutad●t is managed as a [monorepo](https://medium.com/netscape/the-case-for-monorepos-907c1361708a) using [yarn workspaces](https://yarnpkg.com/lang/en/docs/workspaces/) and [lerna](https://lernajs.io/)
+
+The main package has no peer dependency and we intend to keep it that way.


Since I had to add a dependency on babel-runtime, we should either change this sentence or remove it.

nlepage · 2018-01-03T12:40:29Z

README.md

@@ -4,11 +4,11 @@
 A JavaScript library to deal with nested immutable structures.

 ```js
-push({ nested: { prop: [1, 2] } }, 'nested.prop', 3, 4)
-// → { nested: { prop: [1, 2, 3, 4] } }
+set({ english: { greeting: 'Hi' } }, 'nested.prop', 'Hello')


Replace 'nested.prop' by 'english.greeting'

nlepage · 2018-01-03T12:41:19Z

README.md


-pickBy({ nested: [{ a: 1, b: 2, c: 3, d: 4 }, { e: 6 }] }, 'nested.0', v => v < 3)
-// → { nested: [{ a: 1, b: 2 }, { e: 6 }] }
+push({ i18n: { languages: ['English', 'French'] } }, 'nested.prop', 'German', 'Spanish')


Replace 'nested.prop' by 'i18n.languages'

nlepage · 2018-01-03T12:47:19Z

README.md


 ### Interoperability

 immutad●t uses plain JavaScript objects so you can access your data using standard ways. Moreover, it lets you freely enjoy your favorite libraries.

 ### Exhaustive and yet extensible

-immutad●t comes with a large set of built-in utilities, mostly based on [lodash](https://lodash.com/). You haven't found what you're looking for? Do it yourself with the `convert` feature.
+immutad●t comes with a large set of built-in utilities, mostly based on [ES2015+](https://mdn.io/JavaScript/Reference). You can also find a package called [immutadot-lodash](https://github.com/Zenika/immutadot/tree/master/packages/immutadot-lodash) with some of [lodash](https://lodash.com/)'s utilities. You haven't found what you're looking for? Do it yourself with the `convert` feature.


Add a link to convert's documentation (maybe to be replaced to a link to a getting started section) : [`convert`](https://zenika.github.io/immutadot/immutadot/1.0/core.html#.convert)

nlepage · 2018-01-03T12:48:58Z

README.md

+using ES2015+:
+
+```js
+import { capitalize } from 'lodash'


Remove this line

lodash is used in example

nlepage · 2018-01-03T12:51:34Z

docs/README.md

-Latest documentation is available at [zenika.github.io/immutadot](https://zenika.github.io/immutadot).
+Latest documentation for our different packages are available at the following links:
+- [immutadot](https://zenika.github.io/immutadot)
+- [immutadot-lodash](https://zenika.github.io/immutadot-lodash)


The URL is https://zenika.github.io/immutadot/immutadot-lodash/

📝 Talk about immutadot-lodash

d3dd321

frinyvonnick requested a review from nlepage as a code owner December 15, 2017 14:50

frinyvonnick added 📝 documentation 🚧 WIP labels Dec 15, 2017

🚧 Introduce dot notation improvements

c8fd9b5

frinyvonnick self-assigned this Dec 15, 2017

frinyvonnick added 2 commits December 15, 2017 16:19

📝 Talk about monorepo organization in contributing guide

9d40880

📝 Improve docs README to reflect the new organization

2d1368a

frinyvonnick requested a review from hgwood December 15, 2017 15:30

hgwood reviewed Dec 15, 2017

View reviewed changes

👌 Take care of @hgwood review

6cd2f6a

hgwood reviewed Dec 15, 2017

View reviewed changes

👌 Take care of @hgwood review

985aed7

jlandure previously approved these changes Dec 19, 2017

View reviewed changes

nlepage requested changes Dec 19, 2017

View reviewed changes

frinyvonnick dismissed jlandure’s stale review via 17414a5 December 20, 2017 11:26

👌 Take care of @nlepage review

067e6b4

frinyvonnick force-pushed the enhance/doc branch from 17414a5 to 067e6b4 Compare December 20, 2017 11:28

🚧 Try to write a more welcoming example

aa07a0a

nlepage reviewed Dec 20, 2017

View reviewed changes

nlepage requested changes Dec 20, 2017

View reviewed changes

frinyvonnick added 3 commits December 24, 2017 10:37

👌 Take care of @nlepage review on first example

ed37ddb

📝 Make top examples simpler and more meaningfull

3a89961

📝 Take care of @nlepage review about slice notation example

cee1049

🔥 Remove copy paste in wrong file...

b302923

nlepage mentioned this pull request Dec 28, 2017

Update documentation to reflect the new organization #183

Closed

nlepage requested changes Jan 3, 2018

View reviewed changes

👌 Take care of @nlepage review

56e903f

vp-nlepage approved these changes Jan 3, 2018

View reviewed changes

nlepage approved these changes Jan 3, 2018

View reviewed changes

nlepage merged commit fd43609 into master Jan 3, 2018

nlepage deleted the enhance/doc branch January 3, 2018 16:06


		The main package have no peer dependency and we intend to keep it that way.

		Each package of immutad●t is organized in namespaces (array, collection, lang, etc.), a lot like lodash, please try to respect this organization; if you are not sure where to put your code, ask for the right place in your issue or PR.


		### Performances

		When appling operations on a path we create the minimum of objects or arrays needed to guarantee your data structure to be immutable.


		### Slice notation

		The slice notation let you go trough arrays to apply operations without having to map arrays at each level of imbrication.


		### Performances

		When appling operations on a path immutad●t creates the minimum of objects or arrays needed to guarantee your data structure to be immutable.


		### List notation

		The list notation let you go trough each keys of objects used as collection or map to apply operations.

Update documentation to reflect the new organization and new features #172

Update documentation to reflect the new organization and new features #172

Conversation

frinyvonnick commented Dec 15, 2017

Prerequisites

Description

codecov-io commented Dec 15, 2017 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hgwood Dec 20, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

frinyvonnick commented Dec 15, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

frinyvonnick Dec 20, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

frinyvonnick commented Dec 20, 2017

frinyvonnick commented Dec 20, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nlepage left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

frinyvonnick commented Dec 24, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov-io commented Dec 15, 2017 •

edited

Loading

hgwood Dec 20, 2017 •

edited

Loading

frinyvonnick Dec 20, 2017 •

edited

Loading