Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
* Add FP function generation * Modify build_index to build FP index * Add FP typings generator * Regenerate docs, indices, typings and FP * Add FP doc * Add FP CHANGELOG.md entry * Add lodash-fp example * Add FP examples * Remove unused phantomjs-prebuilt * Add FP tests * Fix style * Add ECMAScript Modules documentation article
- Loading branch information
Showing
579 changed files
with
30,917 additions
and
1,524 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,42 @@ | ||
# ECMAScript Modules | ||
|
||
|
||
**date-fns** v2.x provides support for | ||
[ECMAScript Modules](http://www.ecma-international.org/ecma-262/6.0/#sec-modules) | ||
via `'date-fns/esm'` subpackage. | ||
|
||
## Table of Contents | ||
|
||
- [Tree-shaking](#tree-shaking) | ||
|
||
- [Usage With TypeScript](#usage-with-typescript) | ||
|
||
## Tree-shaking | ||
|
||
ECMAScript Modules allow usage with bundlers that support tree-shaking, | ||
like [rollup.js](http://rollupjs.org) and [webpack](https://webpack.js.org): | ||
|
||
```javascript | ||
// Without tree-shaking: | ||
import format from 'date-fns/format' | ||
import parse from 'date-fns/parse' | ||
|
||
// With tree-shaking: | ||
import {format, parse} from 'date-fns/esm' | ||
``` | ||
|
||
**Important**: as at webpack 2.2.0, tree-shaking is not removing all unused imports. | ||
See [webpack issue #2867](https://github.com/webpack/webpack/issues/2867) | ||
|
||
## Usage With TypeScript | ||
|
||
Also, as `'date-fns/esm'` function submodules provide default export, | ||
they can be used with TypeScript to import functions in more idiomatic way: | ||
|
||
```typescript | ||
// In TypeScript, instead of importing regular function submodules: | ||
import * as format from 'date-fns/format' | ||
|
||
// you can use 'date-fns/esm' function submodules as a shortcut: | ||
import format from 'date-fns/esm/format' | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,84 @@ | ||
# FP Guide | ||
|
||
**date-fns** v2.x provides [functional programming](https://en.wikipedia.org/wiki/Functional_programming) (FP) | ||
friendly functions, like those in [lodash](https://github.com/lodash/lodash/wiki/FP-Guide), | ||
that support [currying](https://en.wikipedia.org/wiki/Currying). | ||
|
||
## Table of Contents | ||
|
||
- [Usage](#usage) | ||
|
||
- [Using Function Composition](#using-function-composition) | ||
|
||
- [ECMAScript Modules](#ecmascript-modules) | ||
|
||
## Usage | ||
|
||
FP functions are provided via `'date-fns/fp'` submodule. | ||
|
||
Each non-FP function has two FP counterparts: one that has [Options](docs/Options) object as its first argument | ||
and one that hasn't. The name of the former has `WithOptions` added to the end of its name. | ||
|
||
In **date-fns'** FP functions, the order of arguments is reversed. | ||
|
||
```javascript | ||
import addYears from 'date-fns/fp/addYears' | ||
import formatWithOptions from 'date-fns/fp/formatWithOptions' | ||
import eoLocale from 'date-fns/locale/eo' | ||
import toUpper from 'lodash/fp/toUpper' // 'date-fns/fp' is compatible with 'lodash/fp'! | ||
|
||
// If FP function has not recieved enough arguments, it returns another function | ||
const addFiveYears = addYears(5) | ||
|
||
// Several arguments can be curried at once | ||
const dateToString = formatWithOptions({locale: eoLocale}, 'D MMMM YYYY') | ||
|
||
const dates = [ | ||
new Date(2017, 0 /* Jan */, 1), | ||
new Date(2017, 1 /* Feb */, 11), | ||
new Date(2017, 6 /* Jul */, 2) | ||
] | ||
|
||
const formattedDates = dates.map(addFiveYears).map(dateToString).map(toUpper) | ||
//=> ['1 JANUARO 2022', '11 FEBRUARO 2022', '2 JULIO 2022'] | ||
``` | ||
|
||
## Using Function Composition | ||
|
||
The main advantage of FP functions is support of functional-style | ||
[function composing](https://medium.com/making-internets/why-using-chain-is-a-mistake-9bc1f80d51ba). | ||
|
||
In the example above, you can compose `addFiveYears`, `dateToString` and `toUpper` into a single function: | ||
|
||
```javascript | ||
const formattedDates = dates.map((date) => toUpper(dateToString(addFiveYears(date)))) | ||
``` | ||
|
||
Or you can use `compose` function provided by [lodash](https://lodash.com) to do the same in more idiomatic way: | ||
|
||
```javascript | ||
import compose from 'lodash/fp/compose' | ||
|
||
const formattedDates = dates.map(compose(toUpper, dateToString, addFiveYears)) | ||
``` | ||
|
||
Or if you prefer natural direction of composing (as opposed to the computationally correct order), | ||
you can use lodash' `flow` instead: | ||
|
||
```javascript | ||
import flow from 'lodash/fp/flow' | ||
|
||
const formattedDates = dates.map(flow(addFiveYears, dateToString, toUpper)) | ||
``` | ||
|
||
## ECMAScript Modules | ||
|
||
FP functions are also can be used with bundlers that support tree-shaking, | ||
like [rollup.js](http://rollupjs.org) and [webpack](https://webpack.js.org) | ||
via `'date-fns/esm/fp'` submodule: | ||
|
||
```javascript | ||
import {addYears, formatWithOptions} from 'date-fns/esm/fp' | ||
``` | ||
|
||
Read more in [ECMAScript Modules](docs/esm) article in the documentation. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
var addYears = require('date-fns/fp/addYears') | ||
var dateFns = require('date-fns/fp') | ||
var formatWithOptions = dateFns.formatWithOptions | ||
var eoLocale = require('date-fns/locale/eo') | ||
|
||
var addFiveYears = addYears(5) | ||
var dateToString = formatWithOptions({locale: eoLocale}, 'D MMMM YYYY') | ||
|
||
var dates = [ | ||
new Date(2017, 0 /* Jan */, 1), | ||
new Date(2017, 1 /* Feb */, 11), | ||
new Date(2017, 6 /* Jul */, 2) | ||
] | ||
|
||
var formattedDates = dates | ||
.map((date) => dateToString(addFiveYears(date))) | ||
.join(', ') | ||
|
||
console.log(formattedDates === '1 januaro 2022, 11 februaro 2022, 2 julio 2022') |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
var addYears = require('date-fns/fp/addYears') | ||
var dateFns = require('date-fns/fp') | ||
var formatWithOptions = dateFns.formatWithOptions | ||
var eoLocale = require('date-fns/locale/eo') | ||
|
||
const addFiveYears = addYears(5) | ||
const dateToString = formatWithOptions({locale: eoLocale}, 'D MMMM YYYY') | ||
|
||
const dates : Date[] = [ | ||
new Date(2017, 0 /* Jan */, 1), | ||
new Date(2017, 1 /* Feb */, 11), | ||
new Date(2017, 6 /* Jul */, 2) | ||
] | ||
|
||
const formattedDates : string = dates | ||
.map((date) => dateToString(addFiveYears(date))) | ||
.join(', ') | ||
|
||
console.log(formattedDates === '1 januaro 2022, 11 februaro 2022, 2 julio 2022') |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
{ | ||
"presets": ["es2015"] | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
# Usage With lodash FP | ||
|
||
See [example.js](./example.js) for source code example. | ||
|
||
See [package.json scripts](./package.json) for CLI usage. | ||
|
||
## Build Example | ||
|
||
```sh | ||
yarn | ||
yarn run build | ||
``` | ||
|
||
See ./dist for output. | ||
|
||
## Minimal Build Size | ||
|
||
You can see the build size: | ||
|
||
```sh | ||
gzip-size dist/example.min.js | pretty-bytes | ||
#=> 20.1 kB | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,16 @@ | ||
import addYears from 'date-fns/fp/addYears' | ||
import formatWithOptions from 'date-fns/fp/formatWithOptions' | ||
import eoLocale from 'date-fns/locale/eo' | ||
|
||
import compose from 'lodash/fp/compose' | ||
import toUpper from 'lodash/fp/toUpper' | ||
import isEqual from 'lodash/isEqual' | ||
|
||
const addFiveYears = addYears(5) | ||
const dateToString = formatWithOptions({locale: eoLocale}, 'D MMMM YYYY') | ||
|
||
const dates = ['2017-01-01', '2017-02-11', '2017-07-02'] | ||
|
||
const formattedDates = dates.map(compose(toUpper, dateToString, addFiveYears)) | ||
|
||
console.log(isEqual(formattedDates, ['1 JANUARO 2022', '11 FEBRUARO 2022', '2 JULIO 2022'])) |
Oops, something went wrong.