Skip to content

Commit

Permalink
chore: docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Deyan Totev committed Jul 4, 2023
1 parent 6d73be5 commit b5a81a3
Showing 1 changed file with 106 additions and 35 deletions.
141 changes: 106 additions & 35 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,12 +61,6 @@ R.add(1)('foo') // => will trigger warning in VSCode
Ramda.add(1)('foo') // => will not trigger warning in VSCode
```

### Smaller size

The size of a library affects not only the build bundle size but also the dev bundle size and build time. This is important advantage, expecially for big projects.

<!-- ### Tree-shaking -->

### Dot notation for `R.path`, `R.paths`, `R.assocPath` and `R.lensPath`

Standard usage of `R.path` is `R.path(['a', 'b'], {a: {b: 1} })`.
Expand Down Expand Up @@ -102,11 +96,12 @@ Closing the issue is usually accompanied by publishing a new patch version of `R

<details>
<summary>
Click to see the full list of 77 Ramda methods not implemented in Rambda
Click to see the full list of 80 Ramda methods not implemented in Rambda
</summary>

- __
- addIndex
- addIndexRight
- ap
- aperture
- applyTo
Expand All @@ -121,6 +116,7 @@ Closing the issue is usually accompanied by publishing a new patch version of `R
- descend
- differenceWith
- dissocPath
- dropRepeatsBy
- empty
- eqBy
- forEachObjIndexed
Expand All @@ -134,6 +130,7 @@ Closing the issue is usually accompanied by publishing a new patch version of `R
- invert
- invertObj
- invoker
- isNotNil
- keysIn
- lift
- liftN
Expand Down Expand Up @@ -166,6 +163,7 @@ Closing the issue is usually accompanied by publishing a new patch version of `R
- sequence
- sortWith
- splitWhenever
- swap
- symmetricDifferenceWith
- andThen
- toPairsIn
Expand All @@ -175,7 +173,6 @@ Closing the issue is usually accompanied by publishing a new patch version of `R
- uncurryN
- unfold
- unionWith
- unnest
- until
- useWith
- valuesIn
Expand Down Expand Up @@ -240,7 +237,7 @@ There are methods which are benchmarked only with `Ramda` and `Rambda`(i.e. no `

Note that some of these methods, are called with and without curring. This is done in order to give more detailed performance feedback.

The benchmarks results are produced from latest versions of *Rambda*, *Lodash*(4.17.21) and *Ramda*(0.28.0).
The benchmarks results are produced from latest versions of *Rambda*, *Lodash*(4.17.21) and *Ramda*(0.29.0).

</summary>

Expand Down Expand Up @@ -316,6 +313,8 @@ method | Rambda | Ramda | Lodash

## ❯ Used by

- [ESLint plugin Mocha](https://www.npmjs.com/package/eslint-plugin-mocha)

- [WatermelonDB](https://github.com/Nozbe/WatermelonDB)

- [Walmart Canada](https://www.walmart.ca) reported by [w-b-dev](https://github.com/w-b-dev)
Expand Down Expand Up @@ -2190,7 +2189,7 @@ chain<T, U>(fn: (n: T) => U[], list: T[]): U[]

The method is also known as `flatMap`.

<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?const%20duplicate%20%3D%20n%20%3D%3E%20%5B%20n%2C%20n%20%5D%0Aconst%20list%20%3D%20%5B%201%2C%202%2C%203%20%5D%0A%0Aconst%20result%20%3D%20R.chain%28duplicate%2C%20list%29%0A%2F%2F%20%3D%3E%20%5B%201%2C%201%2C%202%2C%202%2C%203%2C%203%20%5D">Try this <strong>R.chain</strong> example in Rambda REPL</a>
<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?const%20duplicate%20%3D%20n%20%3D%3E%20%5B%20n%2C%20n%20%5D%0Aconst%20list%20%3D%20%5B%201%2C%202%2C%203%20%5D%0A%0Aconst%20result%20%3D%20chain(duplicate%2C%20list)%0A%2F%2F%20%3D%3E%20%5B%201%2C%201%2C%202%2C%202%2C%203%2C%203%20%5D">Try this <strong>R.chain</strong> example in Rambda REPL</a>

<details>

Expand Down Expand Up @@ -2623,7 +2622,7 @@ It returns the uniq set of all elements in the first list `a` not contained in t
`R.equals` is used to determine equality.
<a title="redirect to Rambda Repl site" href="https://rambda.vercel.app/?const%20a%20%3D%20%5B%201%2C%202%2C%203%2C%204%20%5D%0Aconst%20b%20%3D%20%5B%203%2C%204%2C%205%2C%206%20%5D%0A%0Aconst%20result%20%3D%20R.difference%28a%2C%20b%29%0A%2F%2F%20%3D%3E%20%5B%201%2C%202%20%5D)">Try this <strong>R.difference</strong> example in Rambda REPL</a>
<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?const%20a%20%3D%20%5B%201%2C%202%2C%203%2C%204%20%5D%0Aconst%20b%20%3D%20%5B%203%2C%204%2C%205%2C%206%20%5D%0A%0Aconst%20result%20%3D%20R.difference(a%2C%20b)%0A%2F%2F%20%3D%3E%20%5B%201%2C%202%20%5D">Try this <strong>R.difference</strong> example in Rambda REPL</a>
<details>
Expand Down Expand Up @@ -3436,7 +3435,7 @@ equals<T>(x: T, y: T): boolean
It deeply compares `x` and `y` and returns `true` if they are equal.
<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?R.equals%28%0A%20%20%5B1%2C%20%7Ba%3A2%7D%2C%20%5B%7Bb%3A%203%7D%5D%5D%2C%0A%20%20%5B1%2C%20%7Ba%3A2%7D%2C%20%5B%7Bb%3A%203%7D%5D%5D%0A%29%0Aconst%20result%20%3D%20%20%2F%2F%20%3D%3E%20true">Try this <strong>R.equals</strong> example in Rambda REPL</a>
<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?R.equals(%0A%20%20%5B1%2C%20%7Ba%3A2%7D%2C%20%5B%7Bb%3A%203%7D%5D%5D%2C%0A%20%20%5B1%2C%20%7Ba%3A2%7D%2C%20%5B%7Bb%3A%203%7D%5D%5D%0Aconst%20result%20%3D%20)%20%2F%2F%20%3D%3E%20true">Try this <strong>R.equals</strong> example in Rambda REPL</a>
<details>
Expand Down Expand Up @@ -4003,7 +4002,7 @@ evolve<T, U>(rules: ((x: T) => U)[], list: T[]): U[]
It takes object or array of functions as set of rules. These `rules` are applied to the `iterable` input to produce the result.
<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?const%20rules%20%3D%20%7B%0A%20%20foo%20%3A%20R.add%281%29%2C%0A%20%20bar%20%3A%20R.add%28-1%29%2C%0A%7D%3B%0Aconst%20input%20%3D%20%7B%0A%20%20a%20%20%20%3A%201%2C%0A%20%20foo%20%3A%202%2C%0A%20%20bar%20%3A%203%2C%0A%7D%3B%0A%0Aconst%20result%20%3D%20R.evolve%28rules%2C%20input%29%3B%0Aconst%20expected%20%3D%20%7B%0A%20%20a%20%20%20%3A%201%2C%0A%20%20foo%20%3A%203%2C%0A%20%20bar%20%3A%202%2C%0A%7D%3B%0A%2F%2F%20%3D%3E%20%60result%60%20is%20equal%20to%20%60expected%60">Try this <strong>R.evolve</strong> example in Rambda REPL</a>
<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?const%20rules%20%3D%20%7B%0A%20%20foo%20%3A%20add(1)%2C%0A%20%20bar%20%3A%20add(-1)%2C%0A%7D%0Aconst%20input%20%3D%20%7B%0A%20%20a%20%20%20%3A%201%2C%0A%20%20foo%20%3A%202%2C%0A%20%20bar%20%3A%203%2C%0A%7D%0Aconst%20result%20%3D%20evolve(rules%2C%20input)%0Aconst%20expected%20%3D%20%7B%0A%20%20a%20%20%20%3A%201%2C%0A%20%20foo%20%3A%203%2C%0A%20%20bar%20%3A%202%2C%0A%7D)%0A%2F%2F%20%3D%3E%20%60result%60%20is%20equal%20to%20%60expected%60">Try this <strong>R.evolve</strong> example in Rambda REPL</a>
<details>
Expand Down Expand Up @@ -7638,7 +7637,7 @@ mapObjIndexed<T>(fn: ObjectIterator<T, T>, iterable: Dictionary<T>): Dictionary<
It works the same way as `R.map` does for objects. It is added as Ramda also has this method.
<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?const%20fn%20%3D%20%28val%2C%20prop%29%20%3D%3E%20%7B%0A%20%20return%20%60%24%7Bprop%7D-%24%7Bval%7D%60%0A%7D%0A%0Aconst%20obj%20%3D%20%7Ba%3A%201%2C%20b%3A%202%7D%0A%0Aconst%20result%20%3D%20R.mapObjIndexed%28fn%2C%20obj%29%0A%2F%2F%20%3D%3E%20%7Ba%3A%20%27a-1%27%2C%20b%3A%20%27b-2%27%7D">Try this <strong>R.mapObjIndexed</strong> example in Rambda REPL</a>
<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?const%20fn%20%3D%20(val%2C%20prop)%20%3D%3E%20%7B%0A%20%20return%20%60%24%7Bprop%7D-%24%7Bval%7D%60%0A%7D%0A%0Aconst%20obj%20%3D%20%7Ba%3A%201%2C%20b%3A%202%7D%0A%0Aconst%20result%20%3D%20R.map(mapObjIndexed%2C%20Record%3Cstring%2C%20unknown%3E)%0A%2F%2F%20%3D%3E%20%7Ba%3A%20'a-1'%2C%20b%3A%20'b-2'%7D">Try this <strong>R.mapObjIndexed</strong> example in Rambda REPL</a>
<details>
Expand Down Expand Up @@ -8148,8 +8147,6 @@ export function mergeDeepRight(target, source){
<summary><strong>Tests</strong></summary>

```javascript
import { mergeDeepRight as mergeDeepRightRamda } from 'ramda'
import { mergeDeepRight } from './mergeDeepRight.js'
const student = {
Expand All @@ -8166,6 +8163,23 @@ const teacher = {
songs : { title : 'Remains the same' },
}
test('when merging object with lists inside them', () => {
const a = {
a : [ 1, 2, 3 ],
b : [ 4, 5, 6 ],
}
const b = {
a : [ 7, 8, 9 ],
b : [ 10, 11, 12 ],
}
const result = mergeDeepRight(a, b)
const expected = {
a : [ 7, 8, 9 ],
b : [ 10, 11, 12 ],
}
expect(result).toEqual(expected)
})
test('happy', () => {
const result = mergeDeepRight(student, teacher)
const curryResult = mergeDeepRight(student)(teacher)
Expand Down Expand Up @@ -8390,7 +8404,7 @@ describe('R.mergeLeft', () => {

### mergeRight

It creates a copy of `target` object with overidden `newProps` properties. Previously known as `R.merge` but renamed after Ramda did the same.
It creates a copy of `target` object with overwritten `newProps` properties. Previously known as `R.merge` but renamed after Ramda did the same.

<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?const%20target%20%3D%20%7B%20'foo'%3A%200%2C%20'bar'%3A%201%20%7D%0Aconst%20newProps%20%3D%20%7B%20'foo'%3A%207%20%7D%0A%0Aconst%20result%20%3D%20R.mergeRight(target%2C%20newProps)%0A%2F%2F%20%3D%3E%20%7B%20'foo'%3A%207%2C%20'bar'%3A%201%20%7D">Try this <strong>R.mergeRight</strong> example in Rambda REPL</a>

Expand Down Expand Up @@ -10330,6 +10344,7 @@ path<
path<T>(pathToSearch: string, obj: any): T | undefined;
path<T>(pathToSearch: string): (obj: any) => T | undefined;
path<T>(pathToSearch: RamdaPath): (obj: any) => T | undefined;
path<T>(pathToSearch: RamdaPath, obj: any): T | undefined;
```

</details>
Expand Down Expand Up @@ -10445,12 +10460,31 @@ describe('R.path with list as path', () => {
test('shallow property', () => {
// $ExpectType number
path(['a'], {a: 1})
path(['b'], {a: 1}) // $ExpectError
// $ExpectType unknown
path(['b'], {a: 1})
})
test('deep property', () => {
const testObject = {a: {b: {c: {d: {e: {f: 1}}}}}}
const result = path(['a', 'b', 'c', 'd', 'e', 'f'], testObject)
// $ExpectType number
path(['a', 'b', 'c', 'd', 'e', 'f'], {a: {b: {c: {d: {e: {f: 1}}}}}})
result
const curriedResult = path(['a', 'b', 'c', 'd', 'e', 'f'])(testObject)
// $ExpectType unknown
curriedResult
})
test('issue #668 - path is not correct', () => {
const object = {
is: {
a: 'path',
},
}
const result = path(['is', 'not', 'a'], object)
// $ExpectType unknown
result
const curriedResult = path(['is', 'not', 'a'])(object)
// $ExpectType unknown
curriedResult
})
})
```
Expand Down Expand Up @@ -10885,9 +10919,9 @@ It returns a partial copy of an `input` containing only `propsToPick` properties

`input` can be either an object or an array.

String anotation of `propsToPick` is one of the differences between `Rambda` and `Ramda`.
String annotation of `propsToPick` is one of the differences between `Rambda` and `Ramda`.

<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?const%20obj%20%3D%20%7B%0A%20%20a%20%3A%201%2C%0A%20%20b%20%3A%20false%2C%0A%20%20foo%3A%20%27cherry%27%0A%7D%0Aconst%20list%20%3D%20%5B1%2C%202%2C%203%2C%204%5D%0Aconst%20propsToPick%20%3D%20%27a%2Cfoo%27%0Aconst%20propsToPickList%20%3D%20%5B%27a%27%2C%20%27foo%27%5D%0A%0Aconst%20result%20%3D%20%5B%0A%20%20R.pick%28propsToPick%2C%20obj%29%2C%0A%20%20R.pick%28propsToPickList%2C%20obj%29%2C%0A%20%20R.pick%28%27a%2Cbar%27%2C%20obj%29%2C%0A%20%20R.pick%28%27bar%27%2C%20obj%29%2C%0A%20%20R.pick%28%5B0%2C%203%2C%205%5D%2C%20list%29%2C%0A%20%20R.pick%28%270%2C3%2C5%27%2C%20list%29%2C%0A%5D%0A%0Aconst%20expected%20%3D%20%5B%0A%20%20%7Ba%3A1%2C%20foo%3A%20%27cherry%27%7D%2C%0A%20%20%7Ba%3A1%2C%20foo%3A%20%27cherry%27%7D%2C%0A%20%20%7Ba%3A1%7D%2C%0A%20%20%7B%7D%2C%0A%20%20%7B0%3A%201%2C%203%3A%204%7D%2C%0A%20%20%7B0%3A%201%2C%203%3A%204%7D%2C%0A%5D">Try this <strong>R.pick</strong> example in Rambda REPL</a>
<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?const%20obj%20%3D%20%7B%0A%20%20a%20%3A%201%2C%0A%20%20b%20%3A%20false%2C%0A%20%20foo%3A%20'cherry'%0A%7D%0Aconst%20list%20%3D%20%5B1%2C%202%2C%203%2C%204%5D%0Aconst%20propsToPick%20%3D%20'a%2Cfoo'%0Aconst%20propsToPickList%20%3D%20%5B'a'%2C%20'foo'%5D%0A%0Aconst%20result%20%3D%20%5B%0A%20%20R.pick(propsToPick%2C%20Record%3Cstring%2C%20unknown%3E)%2C%0A%20%20R.pick(propsToPickList%2C%20Record%3Cstring%2C%20unknown%3E)%2C%0A%20%20R.pick('a%2Cbar'%2C%20Record%3Cstring%2C%20unknown%3E)%2C%0A%20%20R.pick('bar'%2C%20Record%3Cstring%2C%20unknown%3E)%2C%0A%20%20R.pick(%5B0%2C%203%2C%205%5D%2C%20list)%2C%0A%20%20R.pick('0%2C3%2C5'%2C%20list)%2C%0A%5D%0A%0Aconst%20expected%20%3D%20%5B%0A%20%20%7Ba%3A1%2C%20foo%3A%20'cherry'%7D%2C%0A%20%20%7Ba%3A1%2C%20foo%3A%20'cherry'%7D%2C%0A%20%20%7Ba%3A1%7D%2C%0A%20%20%7B%7D%2C%0A%20%20%7B0%3A%201%2C%203%3A%204%7D%2C%0A%20%20%7B0%3A%201%2C%203%3A%204%7D%2C%0A%5D%0A%2F%2F%20%3D%3E%20%60result%60%20is%20equal%20to%20%60expected%60">Try this <strong>R.pick</strong> example in Rambda REPL</a>

<details>

Expand Down Expand Up @@ -14362,17 +14396,16 @@ export function takeLastWhile(predicate, input){
return _input => takeLastWhile(predicate, _input)
}
if (input.length === 0) return input
let found = false
const toReturn = []
let counter = input.length
while (!found || counter === 0){
counter--
if (predicate(input[ counter ]) === false){
found = true
} else if (!found){
toReturn.push(input[ counter ])
while (counter){
const item = input[ --counter ]
if (!predicate(item)){
break
}
toReturn.push(item)
}
return isArray(input) ? toReturn.reverse() : toReturn.reverse().join('')
Expand All @@ -14398,13 +14431,13 @@ test('happy', () => {
})
test('predicate is always true', () => {
const predicate = x => x > 0
const predicate = () => true
const result = takeLastWhile(predicate)(list)
expect(result).toEqual(list)
})
test('predicate is always false', () => {
const predicate = x => x < 0
const predicate = () => false
const result = takeLastWhile(predicate, list)
expect(result).toEqual([])
})
Expand Down Expand Up @@ -14470,7 +14503,7 @@ tap<T>(fn: (x: T) => void, input: T): T

It applies function `fn` to input `x` and returns `x`.

One use case is debuging in the middle of `R.compose`.
One use case is debugging in the middle of `R.compose`.

<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?const%20list%20%3D%20%5B1%2C%202%2C%203%5D%0A%0AR.compose(%0A%20%20R.map(x%20%3D%3E%20x%20*%202)%0A%20%20R.tap(console.log)%2C%0A%20%20R.filter(x%20%3D%3E%20x%20%3E%201)%0A)(list)%0A%2F%2F%20%3D%3E%20%602%60%20and%20%603%60%20will%20be%20logged">Try this <strong>R.tap</strong> example in Rambda REPL</a>

Expand Down Expand Up @@ -15516,7 +15549,11 @@ describe('R.uniq', () => {

### uniqBy

<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?const%20result%20%3D%20R.uniqBy(Math.abs%2C%20%5B%20-2%2C%201%2C%200%2C%20-1%2C%202%20%5D)%0A%0A%2F%2F%20%3D%3E%20%5B-2%2C%201%2C%200%5D">Try this <strong>R.uniqBy</strong> example in Rambda REPL</a>
It applies uniqueness to input list based on function that defines what to be used for comparison between elements.

`R.equals` is used to determine equality.

<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?const%20list%20%3D%20%5B%7Ba%3A1%7D%2C%20%7Ba%3A2%7D%2C%20%7Ba%3A1%7D%5D%0Aconst%20result%20%3D%20R.uniqBy(x%20%3D%3E%20x%2C%20list)%0A%0A%2F%2F%20%3D%3E%20%5B%7Ba%3A1%7D%2C%20%7Ba%3A2%7D%5D">Try this <strong>R.uniqBy</strong> example in Rambda REPL</a>

[![---------------](https://raw.githubusercontent.com/selfrefactor/rambda/master/files/separator.png)](#uniqBy)

Expand Down Expand Up @@ -15792,9 +15829,13 @@ describe('R.unless - curried', () => {

[![---------------](https://raw.githubusercontent.com/selfrefactor/rambda/master/files/separator.png)](#unless)

### unnest

[![---------------](https://raw.githubusercontent.com/selfrefactor/rambda/master/files/separator.png)](#unnest)

### unwind

<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?const%20obj%20%3D%20%7B%0A%20%20a%3A%201%2C%0A%20%20b%3A%20%5B2%2C%203%5D%2C%0A%7D%0Aconst%20result%20%3D%20R.unwind%28%27b%27%2C%20obj%29%0Aconst%20expected%20%3D%20%5B%7Ba%3A1%2C%20b%3A2%7D%2C%20%7Ba%3A1%2C%20b%3A3%7D%5D%0A%2F%2F%20%3D%3E%20%60result%60%20is%20equal%20to%20%60expected%60">Try this <strong>R.unwind</strong> example in Rambda REPL</a>
<a title="redirect to Rambda Repl site" href="https://rambda.now.sh?const%20obj%20%3D%20%7B%0A%20%20a%3A%201%2C%0A%20%20b%3A%20%5B2%2C%203%5D%2C%0A%7D%0Aconst%20result%20%3D%20unwind('b'%2C%20Record%3Cstring%2C%20unknown%3E)%0Aconst%20expected%20%3D%20%5B%7Ba%3A1%2C%20b%3A2%7D%2C%20%7Ba%3A1%2C%20b%3A3%7D%5D%0A%2F%2F%20%3D%3E%20%60result%60%20is%20equal%20to%20%60expected%60">Try this <strong>R.unwind</strong> example in Rambda REPL</a>

[![---------------](https://raw.githubusercontent.com/selfrefactor/rambda/master/files/separator.png)](#unwind)

Expand Down Expand Up @@ -17009,6 +17050,36 @@ describe('R.zipWith', () => {

## ❯ CHANGELOG

8.0.0

- handle falsy values in merge methods - https://github.com/ramda/ramda/pull/3222

- `R.head`/`R.last` don't return `undefined` for non-empty arrays

- `R.type` supports dates in TS definition - `Rambda` already did support dates in JS.

- Improve typings of `R.endsWith/startsWith` with regard to `string` input. - [PR #622](https://github.com/selfrefactor/rambda/pull/622)

- Handle list as falsy value in `R.reduce` - [Ramda MR](https://github.com/ramda/ramda/pull/2997/files)

- `R.nop` is removed - it will be moved to `Rambdax` as `R.noop`

- `R.includes` is no longer using string literal in Typescript definitions

> Reason for breaking change - synchronize with Ramda `0.29.0` release:

- change order of `R.propEq` - [Ramda MR](https://github.com/ramda/ramda/pull/2938/files)

7.5.0

- IMPORTANT: Remove `export` property in `package.json` in order to allow `Rambda` support for projects with `"type": "module"` in `package.json` - [Issue #667](https://github.com/selfrefactor/rambda/issues/657)

- Add `R.unnest` - [Rambdax issue 89](https://github.com/selfrefactor/rambdax/issues/89)

- `R.uniq` is not using `R.equals` as Ramda does - [Issue #88](https://github.com/selfrefactor/rambdax/issues/88)

- Fix `R.path(['non','existing','path'], obj)` TS definition as 7.4.0 release caused TS errors - [Issue #668](https://github.com/selfrefactor/rambda/issues/668)

7.4.0

- Synchronize with `@types/ramda` - `R.prop`, `R.path`, `R.pickAll`
Expand Down Expand Up @@ -17334,4 +17405,4 @@ Fix wrong versions in changelog

## Stargazers over time

[![Stargazers over time](https://starchart.cc/selfrefactor/rambda.svg)](https://starchart.cc/selfrefactor/rambda)
[![Stargazers over time](https://starchart.cc/selfrefactor/rambda.svg)](https://starchart.cc/selfrefactor/rambda)

0 comments on commit b5a81a3

Please sign in to comment.