@louis.jln/extract-date 3.0.0

package/.flowconfig

@@ -0,0 +1,3 @@
+[ignore]
+.*/node_modules/.*/test/.*
+<PROJECT_ROOT>/dist/.*

package/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2018, Gajus Kuizinas (http://gajus.com/)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the Gajus Kuizinas (http://gajus.com/) nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL ANUARY BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,184 @@
+<a name="extract-date"></a>
+# extract-date 📅
+
+[![Travis build status](http://img.shields.io/travis/gajus/extract-date/master.svg?style=flat-square)](https://travis-ci.org/gajus/extract-date)
+[![Coveralls](https://img.shields.io/coveralls/gajus/extract-date.svg?style=flat-square)](https://coveralls.io/github/gajus/extract-date)
+[![NPM version](http://img.shields.io/npm/v/extract-date.svg?style=flat-square)](https://www.npmjs.org/package/extract-date)
+[![Canonical Code Style](https://img.shields.io/badge/code%20style-canonical-blue.svg?style=flat-square)](https://github.com/gajus/canonical)
+[![Twitter Follow](https://img.shields.io/twitter/follow/kuizinas.svg?style=social&label=Follow)](https://twitter.com/kuizinas)
+
+Extracts date from an arbitrary text input.
+
+* [extract-date 📅](#extract-date)
+    * [Features](#extract-date-features)
+    * [Motivation](#extract-date-motivation)
+    * [Use case](#extract-date-use-case)
+    * [Usage](#extract-date-usage)
+        * [Configuration](#extract-date-usage-configuration)
+    * [Resolution of ambiguous dates](#extract-date-resolution-of-ambiguous-dates)
+        * [Date resolution without year](#extract-date-resolution-of-ambiguous-dates-date-resolution-without-year)
+    * [Implementation](#extract-date-implementation)
+        * [Input tokenisation](#extract-date-implementation-input-tokenisation)
+        * [Format specification](#extract-date-implementation-format-specification)
+    * [Related projects](#extract-date-related-projects)
+
+
+<a name="extract-date-features"></a>
+## Features
+
+* Deterministic and unambiguous date parsing (input must include year; see [Date resolution without year](#date-resolution-without-year))
+* No date format configuration.
+* Recognises relative dates (yesterday, today, tomorrow).
+* Recognises weekdays (Monday, Tuesday, etc.).
+* Supports timezones (for relative date resolution) and locales.
+
+<a name="extract-date-motivation"></a>
+## Motivation
+
+I am creating a large scale data aggregation platform (https://applaudience.com/). I have observed that the date-matching patterns and site specific date validation logic is repeating and could be abstracted into a universal function as long as minimum information about the expected pattern is provided (such as the `direction` configuration). My motivation for creating such abstraction is to reduce the amount of repetitive logic that we use to extract dates from multiple sources.
+
+<a name="extract-date-use-case"></a>
+## Use case
+
+The intended use case is extracting date of future events from blobs of text that may contain auxiliary information, e.g. 'Event at 14:00 2019-01-01 (2D)'.
+
+The emphasis on the _future_ events is because resolving dates such 'today' (relative dates) and 'Wednesday' (weekday dates) requires knowing the offset date. If your input sources refer predominantly to future events, then the ambiguity can be resolved using the present date.
+
+<a name="extract-date-usage"></a>
+## Usage
+
+```js
+import extractDate from 'extract-date';
+
+extractDate('extracts date from anywhere within the input 2000-01-02');
+// [{date: '2000-01-02'}]
+
+extractDate('extracts multiple dates located anywhere within the input: 2000-01-02, 2000-01-03');
+// [{date: '2000-01-02'}, {date: '2000-01-03'}]
+
+extractDate('ignores ambiguous dates 02/01/2000');
+// []
+
+extractDate('uses `direction` to resolve ambiguous dates 02/01/2000', {direction: 'DMY'});
+// [{date: '2000-01-02'}]
+
+extractDate('uses `timezone` to resolve relative dates such as today or tomorrow', {timezone: 'Europe/London'});
+// [{date: '2000-01-02'}, {date: '2000-01-03'}] (assuming that today is 2000-01-02)
+
+extractDate('extracts dates using locales May 1, 2017', {locale: 'en'});
+// [{date: '2015-05-01'}]
+
+```
+
+<a name="extract-date-usage-configuration"></a>
+### Configuration
+
+|Name|Description|Default|
+|---|---|---|
+|`direction`|Token identifying the order of numeric date attributes within the string. Possible values: DM, DMY, DYM, MD, YDM, YMD. Used to resolve ambiguous dates, e.g. DD/MM/YYYY and MM/DD/YYYY.|N/A|
+|`locale`|Required when date includes localized names (e.g. month names)|N/A|
+|`maximumAge`|See [Date resolution without year](#date-resolution-without-year).|`Infinity`|
+|`minimumAge`|See [Date resolution without year](#date-resolution-without-year).|`Infinity`|
+|`timezone`|[TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Used to resolve relative dates ("Today", "Tomorrow").|N/A|
+
+<a name="extract-date-resolution-of-ambiguous-dates"></a>
+## Resolution of ambiguous dates
+
+<a name="extract-date-resolution-of-ambiguous-dates-date-resolution-without-year"></a>
+### Date resolution without year
+
+When year is not part of the input (e.g. March 2nd), then `minimumAge` and `maximumAge` configuration determines the year value.
+
+* If the difference between the current month and the parsed month is greater or equal to `minimumAge`, then the year value is equal to the current year +1.
+* If the difference between the current month and the parsed month is lower or equal to `maximumAge`, then the year value is equal to the current year -1.
+* If the difference is within those two ranges, then the current year value is used.
+
+Example:
+
+* If the current date is 2000-12-01 and the parsed date is 10-01, then the month difference is -2.
+  * If `minimumAge` is 2, then the final date is 2001-10-01.
+  * If `minimumAge` is 3, then the final date is 2000-10-01.
+
+* If the current date is 2000-01-01 and the input date is 10-01, then the month difference is 9.
+  * If `maximumAge` is 10, then the final date is 2000-10-01.
+  * If `maximumAge` is 9, then the final date is 1999-10-01.
+
+Note: `minimumAge` comparison is done using absolute difference value.
+
+<a name="extract-date-implementation"></a>
+## Implementation
+
+Note: This section of the documentation is included for contributors.
+
+* `extract-date` includes a collection of formats ([`./src/createFormats.js`](./src/createFormats.js)).
+* Individual formats define their expectations (see [Format specification](#format-specification)).
+* Formats are attempted in the order of their specificity, i.e. "YYYY-MM-DD" is attempted before "MM-DD".
+* Formats are attempted against a tokenised version of the input (see [Input tokenisation](#input-tokenisation)).
+* Matching date format advances further search past the matching date string.
+
+<a name="extract-date-implementation-input-tokenisation"></a>
+### Input tokenisation
+
+* Individual formats define how many words make up the date.
+* `extract-date` splits input string into a collection of slices pairing words into phrases of the required length.
+* Format is attempted against each resulting phrase.
+
+Example:
+
+Given input "foo bar baz qux" and format:
+
+```js
+{
+  direction: 'YMD',
+  localised: false,
+  dateFnsFormat: 'YYYY MM.DD',
+  wordCount: 2,
+  yearIsExplicit: true
+}
+
+```
+
+Input is broken down into:
+
+* "foo bar"
+* "bar baz"
+* "baz qux"
+
+collection and the format is attempted against each phrase until a match is found.
+
+<a name="extract-date-implementation-format-specification"></a>
+### Format specification
+
+|Field|Description|
+|---|---|
+|`direction`|Identifies the order of numeric date attributes within the string. Possible values: DMY, DYM, YDM, YMD. Used to resolve ambiguous dates, e.g. DD/MM/YYYY and MM/DD/YYYY.|
+|`localised`|Identifies if the date is localised, i.e. includes names of the week day or month. A format that is localised is used only when `locale` configuration is provided.|
+|`dateFnsFormat`|Identifies [`date-fns`](https://www.npmjs.org/package/date-fns) format used to attempt date extraction.|
+|`wordCount`|Identifies how many words make up the date format.|
+|`yearIsExplicit`|Identifies whether the date format includes year.|
+
+Example formats:
+
+```js
+{
+  direction: 'YMD',
+  localised: false,
+  dateFnsFormat: 'YYYY.MM.DD',
+  wordCount: 1,
+  yearIsExplicit: true
+},
+{
+  direction: 'DD MMMM',
+  localised: true,
+  dateFnsFormat: 'DD MMMM',
+  wordCount: 2,
+  yearIsExplicit: false
+},
+
+```
+
+<a name="extract-date-related-projects"></a>
+## Related projects
+
+* [`extract-price`](https://github.com/gajus/extract-price) – Extracts price from an arbitrary text input.
+* [`extract-time`](https://github.com/gajus/extract-time) – Extracts time from an arbitrary text input.