Package Exports

@onereach/time-interpreter

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@onereach/time-interpreter) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

timeInterpreter

Parse a human readable time string into a canonical format:

date     -> ISO8601: 2020-11-11T00:00:00+00:00, 2020-11-11T00:00:00Z,
datetime -> ISO8601: 2020-11-11T09:36:27+00:00, 2020-11-11T09:36:27Z,
time     -> HH:mm:ssZ,
duration -> milliseconds
timezone -> time offset - +00:00

Installation

Usage

const timeInterpreter = require('timeInterpreter');
const converter = new timeInterpreter();

Parse date

converter.formatDatetime( "date string", false /*ignore time*/, "input timezone", "output timezone"); // optional: set timezones by name or time offset, default `Z`
// Input timezone is a default (assumed) timezone and it will be applied if the input date/time doesn't include timezone data

let result = converter.formatDatetime('1995-02-04 10:00', false, 'Europe/Kiev');
    /* {
        "date": "1995-02-04T10:00:00+02:00", // ISO8601 string
        "timezoneOffset": "+02:00"           // time offset
    } */

converter.formatDatetime('12-12-2020 10:20+06:00', false, 'Europe/Kiev');
    /* {
        "date": "12-12-2020T10:20:00+06:00", // ISO8601 string
        "timezoneOffset": "+06:00"           // time offset
    } */

converter.formatDatetime('1995-02-04 10:00', false, 'Europe/Kiev', '-03:00');
    /* {
        "date": "1995-02-04T05:00:00-03:00",
        "timezoneOffset": "-03:00"
    } */

converter.formatDatetime('1995-02-04 10:00', true).date; // "1995-02-04T10:00:00.000Z"
converter.formatDatetime('28OCT1990').date;              // "1990-10-28T00:00:00Z"

// ISO8601 duration
converter.formatDatetime('PT444037H35M28S').date;        // "2020-08-27T13:35:28Z"

converter.formatDatetime({  year: 2010,
                            month: 3,
                            day: 5,
                            hour: 15,
                            minute: 10,
                            second: 3,
                            millisecond: 123
                         }, false, 'UTC')                 // "2010-04-05T15:10:03+00:00"

// Unix time
converter.formatDatetime(1318874398);                    // "2011-10-17T17:59:58.000Z"
converter.formatDatetime(1560211200000);                 // "2019-06-11T00:00:00.000Z"

// Particular format: time span of 3 years 6 months 4 days 12 hours 30 minutes and 17 seconds, starting from August 9, 2005 18 hours 31 minutes 42 seconds
interpreter.formatDatetime("2005-08-09T18:31:42/P3Y6M4DT12H30M17S", false, "+02:00");
    /* {
        date: '2009-02-12T07:01:59+02:00',
        timezoneOffset: '+02:00',
        zoneName: '',
        offsetNum: 2
    } */

// Invalid date or timezone value 1.0.8+
interpreter.formatDatetime("1995-22-24", false, "Europe/Kiev"); // null
interpreter.formatDatetime("1995-02-24 10:00", false, "+4");    // null

// Output additional timezone data 1.0.8+
interpreter.formatDatetime('1995-02-04 10:00', false, "Europe/Kiev");   
    /* {
        "date": "1995-02-04T10:00:00+02:00",
        "timezoneOffset": "+02:00",
        "zoneName": "Europe/Kiev",
        "offsetNum": 2
    } */

// Specify default year. It is used if the original date does not include year (default year current). 1.0.8+
interpreter.formatDatetime('11 August', true, '', 'Europe/Kiev', 1999).date;                // "1999-08-11T00:00:00Z"
interpreter.formatDatetime('September 23rd', false, 'GMT+0', '').date;                      // "2021-09-23T00:00:00+00:00"
interpreter.formatDatetime('sixteenth December', false, 'Europe/Kiev', 'GMT+0', 2020).date; // "2020-12-15T22:00:00+00:00"

Parse timezone

let timeOffset = converter.formatTimezone('+1'); // "+01:00"
converter.formatTimezone('America/Denver');      // "-07:00"
converter.formatTimezone('-0700');               // "-07"00"
converter.formatTimezone('-180');                // "-03:00"

// Specify 'true' as second param to output timezone object 1.0.8+
interpreter.formatTimezone("America/Denver", true);   
    /* {
        "name":       "America/Denver",  
          "offsetNum":  -7,        
        "offsetText": "-07:00"
    } */

// Invalid value 1.0.8+
interpreter.formatTimezone("30");   // null
interpreter.formatTimezone("Ukraine"); // null

Parse time

converter.formatTime("date string", "input timezone"); // optional: set timezones by name or time offset, default `Z`

let time = converter.formatTime('12:30:10 am', 'Europe/Kiev');
    /* {
        "time": "00:30:10+02:00",
        "timezoneOffset": "+02:00"
    } */

converter.formatTime('2020-11-06T06:30:00Z', 'Europe/Kiev');
    /* {
        "time": "06:30:00Z",
        "timezoneOffset": "Z"
    } */

converter.formatTime({ seconds: 2, minutes: 2, hours: 2 }, 'Europe/Kiev');
    /* {
        "time": "02:02:02+02:00",
        "timezoneOffset": "+02:00"
    } */

converter.formatTime('12-30-10').time; // "12:30:10+00:00"
converter.formatTime('183142').time;   // "18:31:42+00:00"
converter.formatTime('283142').time;   // as unix time
    // "00:04:43+00:00"

// Output additional timezone data 1.0.8+
interpreter.formatTime("12-30-10");
    /* { 
        "time": '12:30:10Z', 
        "timezoneOffset": 'Z', 
        "zoneName": '', 
        "offsetNum": 0 
    } */

// Invalid time ot timezone value returns 'null' 1.0.8+
interpreter.formatTime("18:er:03");            // null
interpreter.formatTime("18:00:03", "Ukraine"); // null

Parse duration

let duration = converter.formatDuration('10.2019'); // number of days in October
    // 2678400000

converter.formatDuration('2w 1d5h'); // 1314000000

// ISO8601 duration
converter.formatDuration('P2Y2M16DT2H2M2S'); // 69732122000

// Invalid 
converter.formatDuration('month'); // NaN

Defined parsable formats

date/datetime

All permutations, case insensitive match with separators ('-', '/', ' ', '.'):

"2020 6 oct", "2020 6th oct", "Wed Jun 10 2020", "Friday, October 14, 1983" (week day: 'wed', 'wednesday'; month: 'oct', 'October')
"16.10.2020"
"10/06/20" (handle as 'MM-DD-YY' -> 'DD-MM-YY' -> 'YY-MM-DD' -> 'YY-DD-MM')
"10-2020" (as 1st October 2020)

Can include time part and timezone (case sensitive) or time offset:

"2020 oct 6th 10-30-10PM"
"20-10-06 1:30:10 PM"
"06-10-2020 1:30am"
"1995-02-04 10:00 UTC+7"
"Tue, 6 Oct 2020 13:30:00+0400"
"Fri, Oct 14, 1983 Indian/Kerguelen"
"Friday, October 14, 1983, 1:30 PM UTC"
"23:16, Tuesday, 9 April 2019"
"Wed September 2 2020 6pm"
"20050809T183142", "20150930 212421 -0400", "20050809T183142 -0330", "20150930 212421-0400", "20050809T183142-0330"

day + month (case insensitive), without year 1.0.8+

"11 August", "September 24th"
"sixteenth December", "october tenth", "january twenty one", "thirty July", "twentieth august", "june twenty-second"
"sixteenth Dec", "oct tenth", "jan twenty one", "thirty Jul", "twentieth aug", "11 Aug", "Sep 24th"
"oct-tenth", "jan, twenty one", "twentieth-aug", "11.Aug", "Sep, 24th"

Invalid date:

"16.13.2020", "30/16/20", "13-2020", "34 December"

time

Case insensitive match with separators (':', '-', ' ', '.'):

"183142"
"1:02:14 pm"
"13:02:14.171447"
"5hours 30 minutes"
"1831"
"093042PM"

Invalid time:

"1:68:14 pm", "1:48-14 pm"

duration

Case sensitive:

string: "2d", "2 weeks 1 days 5hours", "2w 1d5h"
object:

    {   seconds: 2,
        minutes: 2,
        hours: 2,
        days: 2,
        weeks: 2,
        months: '2',
        years: '2'
    }

duration of month: "10.2019"
milliseconds
ISO8601 duration: "PT2H35M28S"
time: "04:30:59", "4 23:59:59"

Invalid duration string:

"2D", "2 Weeks 1 Days 5hours"

timezone

Case sensitive:

timezone name: "America/Denver"
timezone abbreviation: "MST"
time offset: "UTC+7", "+01:00", "-0700", "−2:30", "+01", "-7"
time offset in minutes: "-180", "+390"

Invalid values:

"+960", "-16" (out of time offset range)

Library Integrations

moment-timezone.js - dates and timezones parsing library.