npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

extract-date

v2.8.2

Published

Extracts date from an arbitrary text input.

Downloads

7,612

Readme

extract-date 📅

Travis build status Coveralls NPM version Canonical Code Style Twitter Follow

Extracts date from an arbitrary text input.

Features

  • Deterministic and unambiguous date parsing (input must include year; see 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.

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.

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.

Usage

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'}]

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.|Infinity| |minimumAge|See Date resolution without year.|Infinity| |timezone|TZ database name. Used to resolve relative dates ("Today", "Tomorrow").|N/A|

Resolution of ambiguous dates

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.

Implementation

Note: This section of the documentation is included for contributors.

  • extract-date includes a collection of formats (./src/createFormats.js).
  • Individual formats define their expectations (see 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).
  • Matching date format advances further search past the matching date string.

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:

{
  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.

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 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:

{
  direction: 'YMD',
  localised: false,
  dateFnsFormat: 'YYYY.MM.DD',
  wordCount: 1,
  yearIsExplicit: true
},
{
  direction: 'DD MMMM',
  localised: true,
  dateFnsFormat: 'DD MMMM',
  wordCount: 2,
  yearIsExplicit: false
},

Related projects