@onereach/time-interpreter

Convert dates, durations and time to canonical format (dates -> ISO 8601, durations -> milliseconds).

Usage no npm install needed!

<script type="module">
  import onereachTimeInterpreter from 'https://cdn.skypack.dev/@onereach/time-interpreter';
</script>

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

Table of contents

Usage

const timeInterpreter = require("@onereach/time-interpreter");
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:00Z"
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
converter.formatDatetime(
  "2005-08-09T18:31:42/P3Y6M4DT12H30M17S",
  false,
  "+02:00"
);
/* {
        date: '2009-02-12T07:01:59+02:00',
        timezoneOffset: '+02:00',
        zoneName: '',
        offsetNum: 2
    } */

// Output additional timezone data 1.0.8+
converter.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+
converter.formatDatetime("11 August", true, "", "Europe/Kiev", 1999).date; // "1999-08-11"
converter.formatDatetime("September 23rd", false, "GMT+0", "").date; // "2021-09-23T00:00:00+00:00"
converter.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" (or "-06:00")
converter.formatTimezone("-0700"); // "-07:00"
converter.formatTimezone("-180"); // "-03:00"

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

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

Parse time

If the time zone name is used to indicate the input timezone, and this zone has winter and summer time, then the time offset for the input time value is determined to rely on the current date.

converter.formatTime("time 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": "+00:00"
    } */

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"
converter.formatTime("183142").time; // "18:31:42Z"
converter.formatTime("283142").time; // as unix time in ms
// "00:04:43Z"

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

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

Define value type and parse

If you don't know what type of an input value: date, date/time or time, you can use converter.parse(value, input timezone, output timezone, input year, input date). Input year (YYYY) is a default year and it will be applied if the input date/time doesn't include year. Input date (in format YYYY-MM-DD) will be applied if the input value type of time. Default year - current year, default date - null, default input timezone - GMT+0.

if input date is not indicated and the defined type of value is time, then the output timezone is ignored. If the defined type of value is date, then the time is set to 00:00:00 in input timezone (default GMT+0).

If the time zone name is used to indicate the input timezone, and this zone has winter and summer time, and if value is time, then the time offset is determined to rely on the current date (unless otherwise specified).

Method tries to defind first if the value is a date. If input value is a sequence of numbers (for example, 234567 or "6453673") it will be parsed as unix time in seconds. If the value looks like these: "12-30-00", "20 45 50", "16.50.00", - the method will try to parse it as a date (MM-DD-YY, YY-MM-DD etc.) and if it's invalid date the value will be parsed as a time (hh mm ss). Values where separator is "/" are parsed only as a date. Values where separator is ":" are parsed only as a time.

let parsed = converter.parse("Feb-1st-2021, 12:30:00am, America/Los_Angeles, Monday");

    /* {
        "time": {
            "hourMinute12": "12:30",
            "hourMinute24": "00:30",
            "hour12": 12,
            "hour24": 0,
            "amPm": "am",
            "minute": 30
        },
        "duration": 1612168200000,        // milliseconds
        "iso": "2021-02-01T00:30:00-08:00",
        "date": {
            "dayOfWeek": "Monday",
            "isWeekend": false,
            "day": 1,
            "month": 2,
            "monthName": "February",
            "year": 2021
        },
        "timezone": {
            "name": "America/Los_Angeles",
            "offsetNum": -8,
            "offsetText": "-08:00"
        }
    }*/

converter.parse("12.30.00Z+0200 may-twenty-second");
    /*{
        "time": {
            "hourMinute12": "12:30",
            "hourMinute24": "12:30",
            "hour12": 12,
            "hour24": 12,
            "amPm": "pm",
            "minute": 30
        },
        "duration": 1621679400000,
        "iso": "2021-05-22T12:30:00+02:00",
        "date": {
            "dayOfWeek": "Saturday",
            "isWeekend": true,
            "day": 22,
            "month": 5,
            "monthName": "May",
            "year": 2021
        },
        "timezone": {
            "name": "",
            "offsetNum": 2,
            "offsetText": "+02:00"
        }
    }*/

converter.parse("Feb-1st 12:30");
    /*{
        "time": {
            "hourMinute12": "12:30",
            "hourMinute24": "12:30",
            "hour12": 12,
            "hour24": 12,
            "amPm": "pm",
            "minute": 30
        },
        "duration": 1612182600000,        // milliseconds
        "iso": "2021-02-01T12:30:00+00:00",
        "date": {
            "dayOfWeek": "Monday",
            "isWeekend": false,
            "day": 1,
            "month": 2,
            "monthName": "February",
            "year": 2021
        },
        "timezone": {
            "name": "GMT+0",
            "offsetNum": 0,
            "offsetText": "+00:00"
        }
    }*/

converter.parse("twenty-one/Apr 10 30 00pm", "GMT+0", "Europe/Kiev", 2004, "2020-22-10");
    /*{
        "time": {
            "hourMinute12": "01:30",
            "hourMinute24": "01:30",
            "hour12": 1,
            "hour24": 1,
            "amPm": "am",
            "minute": 30
        },
        "duration": 1082586600000,        // milliseconds
        "iso": "2004-04-22T01:30:00+03:00",
        "date": {
            "dayOfWeek": "Thursday",
            "isWeekend": false,
            "day": 22,
            "month": 4,
            "monthName": "April",
            "year": 2004
        },
        "timezone": {
            "name": "Europe/Kiev",
            "offsetNum": 3,
            "offsetText": "+03:00"
        }
    }*/

converter.parse("093042 PM");
    /*{
        "time": {
            "hourMinute12": "09:30",
            "hourMinute24": "21:30",
            "hour12": 9,
            "hour24": 21,
            "amPm": "pm",
            "minute": 30
        },
        "duration": 77442000,        // milliseconds
        "iso": "21:30:42+00:00",
        "date": null,
        "timezone": {
            "name": "GMT+0",
            "offsetNum": 0,
            "offsetText": "+00:00"
        }
    }*/

converter.parse("093042 PM", "Europe/Kiev", "GMT+0", 2004, "2020-10-22");
    /*{
      "time": {
        "hourMinute12": "06:30",
        "hourMinute24": "18:30",
        "hour12": 6,
        "hour24": 18,
        "amPm": "pm",
        "minute": 30
      },
      "duration": 1603391442000,       // milliseconds
      "iso": "2020-10-22T18:30:42+00:00",
      "date": {
        "dayOfWeek": "Thursday",
        "isWeekend": false,
        "day": 22,
        "month": 10,
        "monthName": "October",
        "year": 2020
      },
      "timezone": {
        "name": "GMT+0",
        "offsetNum": 0,
        "offsetText": "+00:00"
      }
    }*/

converter.parse("093042 PM", "America/Denver");
    /*{
        "time": {
            "hourMinute12": "09:30",
            "hourMinute24": "21:30",
            "hour12": 9,
            "hour24": 21,
            "amPm": "pm",
            "minute": 30
        },
        "duration": 77442000,       // milliseconds
        "iso": "21:30:42-07:00",
        "date": null,
        "timezone": {
            "name": "America/Denver",
            "offsetNum": -7,
            "offsetText": "-07:00"
        }
    }*/

converter.parse(34567890, "America/Denver");
    /*{
        "time": {
            "hourMinute12": "02:11",
            "hourMinute24": "02:11",
            "hour12": 2,
            "hour24": 2,
            "amPm": "am",
            "minute": 11
        },
        "duration": 34593090000,
        "iso": "1971-02-05T02:11:30-07:00",
        "date": {
            "dayOfWeek": "Friday",
            "isWeekend": false,
            "day": 5,
            "month": 2,
            "monthName": "February",
            "year": 1971
        },
        "timezone": {
            "name": "America/Denver",
            "offsetNum": -7,
            "offsetText": "-07:00"
        }
    }*/

converter.parse({ days: 2, months: "2", years: "1999" }, "America/Denver");
    /*{
        "time": {
          hourMinute12: '12:00',
          hourMinute24: '00:00',
          hour12: 12,
          hour24: 0,
          amPm: 'am',
          minute: 0
        },
        "duration": 63087811200000,
        "iso": "1999-03-02",
        "date": {
            "dayOfWeek": "Tuesday",
            "isWeekend": false,
            "day": 2,
            "month": 3,
            "monthName": "March",
            "year": 1999
        }
    }*/
        
converter.parse("Friday 7 MAY 2021", "America/Denver");        
    /*{
        "time": {
          hourMinute12: '12:00',
          hourMinute24: '00:00',
          hour12: 12,
          hour24: 0,
          amPm: 'am',
          minute: 0
        },
        "duration": 1620345600000,
        "iso": "2021-05-07",
        "date": {
            "dayOfWeek": "Friday",
            "isWeekend": false,
            "day": 7,
            "month": 5,
            "monthName": "May",
            "year": 2021
        }
    }*/

Defined parsable formats

date

  • date objects (time units: "y", "M", "d", "h", "m", "s", "ms","year","month","day","hour","minute","second","millisecond", "years","months","days","date","hours","minutes","seconds","milliseconds")
  {
    day: 2,
    month: '5'
  },
  {
    day: 2,
    month: '5',
    year: 2020
  }
  • number timestamp (as unix time in seconds -> in milliseconds)
  • string date (the detailed description below)

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

  • "2020 6 oct", "2020 6th oct", "Wed Jun 10 2020", "Friday, October 14, 1983" (week day: 'wed', 'wednesday'; month: 'oct', 'October')
  • "Apr/10/20" (handle as 'MMMM-DD-YY')
  • "10-13-sep" (handle as 'YY-DD-MMMM')
  • "10.sep.13" (handle as 'YY-MMMM-DD' -> 'DD-MMMM-YY')
  • "16.10.2020", "16/10/2020", "16-10-2020", "16 10 2020" (handle as 'DD-MM-YYYY' -> 'MM-DD-YYYY')
  • "2020-16-10", "2020.16.10", "2020/16/10", "2020 16 10" (handle as 'YYYY-MM-DD' -> 'YYYY-DD-MM')
  • "10/06/20", "10.6.20" (handle as 'MM-DD-YY' -> 'DD-MM-YY' -> 'YY-MM-DD' -> 'YY-DD-MM')
  • "10-2020", "10 2020", "10/2020", "10.2020", "2020-10" "2020 10" "2020.10" "2020/10" (as 1st October 2020)

1.0.8+

day + month (case insensitive), without year

  • "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"

1.0.9+

These formats can be parsable with converter.formatDatetime() and converter.parse(). Case insensitive permutations of day, month and year (separated with '-', '.', '/', ' ' (space) ):

day:

  • "1", "01", "1st", "one", "first"
  • "3", "03", "3rd", "three", "third", "thirteen", "thirteenth"
  • "20", "20th", "twenty", "twentieth", "twenty one", "twenty first", "twenty-one", "twenty-first"

month:

  • "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"
  • "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"

year in format of 4 digits: "2021"

Examples:

  • "twenty-one-Apr-2020", "September-twenty-one-2020", "twenty-one.Apr.2020", "September.twenty-one.2020", "twenty-one/Apr/2020", "September/twenty-one/2020", "twenty-one Apr 2020", "September twenty-one 2020", "2020-twenty-one-Apr", "2020-September-twenty-one", "2020.twenty-one.Apr", "2020.September.twenty-one", "2020/twenty-one/Apr", "2020/September/twenty-one", "2020 twenty-one Apr", "2020 September twenty-one", etc.
  • "three-february-2021", "three.february.2021", "three/february/2021", "three february 2021", etc.
  • "Feb-1st-2021", "2021-1st-Feb", "Feb.1st.2021", "2021.1st.Feb", "Feb/1st/2021", "2021/1st/Feb", "Feb 1st 2021", "2021 1st Feb", etc.
  • "2021-2-Mar", "may-5-2021", "2021.2.Mar", "may.5.2021", "2021/2/Mar", "may/5/2021", "2021 2 Mar", "may 5 2021", etc.
  • "2021-March-twenty-second", "March.twenty-second.2021", "2021/twenty-second/March", "twenty-second March 2021", etc.

Date part combinated with weekday (case insensitive), time (case insensitive) and timezone (case sensitive). If the value contains both - time offset and timezone name, at the same time, then the timezone name is preferred.

weekday:

  • "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"
  • "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"

Examples:

  • "twenty-one-Apr-2020 Tuesday", "Tue twenty-one.Apr.2020", "twenty-one/Apr/2020 Tuesday", "Tuesday 2020 twenty-one Apr", "Tue April.twenty-one.2020", "2020/April/twenty-one Tue", etc.
  • "three-february-2021 Wednesday", "Wednesday three.february.2021", "Wed three/february/2021", "three february 2021 Wed", etc.
  • "Feb-1st-2021 Monday", "2021-1st-Feb Mon", "Monday Feb.1st.2021", "Mon 2021.1st.Feb", "Feb/1st/2021 Mon", "2021/1st/Feb Mon", "Feb 1st 2021 Monday", "Monday 2021 1st Feb", etc.
  • "Tuesday 2021-2-Mar", "may-2-2021 Sun", "Tue 2021.2.Mar", "may.2.2021 Sunday", "2021/2/Mar Tuesday", "may/2/2021 sun", "Tuesday 2021 2 Mar", "Sun may 2 2021", etc.
  • "Saturday 2021-may-twenty-second", "may.twenty-second.2021 Sat", "Sat 2021/twenty-second/may", "Sat twenty-second may 2021", etc.
  • weekday can be separated with comma:
    • "may.twenty-second.2021, Sat", "Wednesday, three.february.2021", "twenty-one-Apr-2020,Tuesday", "Feb 1st 2021, Monday", "Mon,2021.1st.Feb", etc.

datetime

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

1.0.0+

  • "2020 oct 6th 10-30-10PM" (date+time)
  • "20-10-06 1:30:10 PM", "20/10/06 1:30:10 PM", "20.10.06 1:30:10 PM" (date+time)
  • "06-10-2020 1:30am", "06/10/2020 1:30am", "06.10.2020 1:30am" (date+time)
  • "1995-02-04 10:00 UTC+7" (date+time)
  • "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"

1.0.9+

Date + time or time + date (may include weekday or timezone name between these parts), where date is:

  • full year + month name + day (simple number/ordered/as words) separated with '-', '.', '/', ' ' (space): "2nd oct 2021"
  • month name + day (simple number/ordered/as words) without year separated with '-', '.', '/', ' ' (space): "2nd oct", "first september"
  • "16.10.2020", "16/10/2020", "16-10-2020", "2020-16-10", "2020.16.10", "2020/16/10"

and where time part is:

  • "7pm", "7 am", "07pm", "07 am"
  • "123000" (hhmmss)
  • "123000pm"
  • hours + minutes ( + seconds) separated with ':', '-', '.', ' ' (space) :
    • "12 30 am", "12-30 am", "12.30 am", "12:30 am", "12 30am", "12-30am", "12.30am", "12:30am", "7:45pm", "7.45 am"
    • "12 30 00 am", "12 30 00am", "12-30-00 am", "12-30-00am", "12.30.00 am", "12.30.00am", "12:30:00 am", "12:30:00am"
    • "12 30 00", "12 30", "12-30-00", "12-30", "12.30.00", "12.30", "12:30:00", "12:30"
    • "12 30 00+0200", "12 45 00-03:00", "12.30.00+0200", "12.45.00-03:00", "12.30.00+0200", "12.45.00-03:00", "12:30:00+0200", "12:45:00-03:00"
    • "12 30 00Z+0200", "12 45 00Z-03:00", "12.30.00Z+0200", "12.45.00Z-03:00", "12.30.00Z+0200", "12.45.00Z-03:00", "12:30:00Z+0200", "12:45:00Z-03:00"
    • "12 30+0200", "12 45-03:00", "12-30+0200", "12-45-03:00", "12.30+0200", "12.45-03:00", "12:30+0200", "12:45-03:00"
    • "12 30 00Z", "12-30-00Z", "12.30.00Z", "12:30:00Z"
    • "12 30 00.000Z", "12-30-00.000Z", "12.30.00.1236Z", "12:30:00.000Z"

Examples:

  • day-month-year + time:
    • "twenty-one-Apr-2020 12:30 am", "7pm twenty-one.Apr.2020", "twenty-one/Apr/2020 123000pm", "12-30-00 2020 twenty-one Apr", "12.30 am April.twenty-one.2020", "2020/April/twenty-one 12 30am",
    • "three-february-2021 12:45:00-03:00", "12:30:00 am three.february.2021", "12-30am three/february/2021", "three february 2021 7 am", etc.
    • "Feb-1st-2021 7 am", "2021-1st-Feb 12.30.00+0200", "12 30 00 Feb.1st.2021", "123000pm 2021.1st.Feb", "Feb/1st/2021 123000", "2021/1st/Feb 12 30 am", "Feb 1st 2021 12-30 am", "12.30am 2021 1st Feb", etc.
    • "12 30 00Z 2021-2-Mar", "may-5-2021 12-30-00Z", "12:45:00-03:00 2021.2.Mar", "may.5.2021 12-30-00", "2021/2/Mar 12-30", etc.
    • "12.30 2021-may-twenty-second", "may.twenty-second.2021 12.30.00am", "12:30 2021/twenty-second/may", "12 30 00am twenty-second may 2021", etc.
  • day-month-year + time + weekday:
    • "twenty-one-Apr-2020 Tuesday 12:30 am", "Tue 7pm twenty-one.Apr.2020", "12.30.00am 2020/April/twenty-one Tue", etc.
    • "three-february-2021 12 30 am Wednesday", "Wednesday 12-30am three.february.2021", "Wed three/february/2021 12 30 30Z", "12:45:00Z-03:00 three february 2021 Wed", etc.
    • "Feb-1st-2021 12:30:00am Monday", "12:30:00 2021-1st-Feb Mon", "Monday 12:30 Feb.1st.2021", "12:30:00am Mon 2021.1st.Feb", etc.
  • day-month + time:
    • "twenty-one-Apr 12:30:00am", "12:30 twenty-one.Apr", "twenty-one/Apr 10 30 00pm", "7:30PM twenty-one Apr", "6 PM April.twenty-one", "16 30 three.february", "three/february 12:30pm", "Feb-1st 12:30", etc.
    • "12.30.00am 2-Mar", "may-5 7 am", "2.Mar 12-30-00Z", "may.5 12.30", "2/Mar 12-30", "may/5 123000am", "202100 2 Mar", "may 5 12.30", etc.
    • "12.30.00Z+0200 may-twenty-second", "may.twenty-second 12:30:00 am", "12.30 am twenty-second/may", "twenty-second may 12 30am", etc.
  • weekday can be separated with comma:
    • "twenty-one-Apr, 12:30:00am", "12:30, twenty-one.Apr", "twenty-one/Apr,10 30 00pm", "7:30PM,twenty-one Apr", "Feb-1st-2021, 12:30:00am, Monday", "12:30:00, 2021-1st-Feb Mon", "Monday 12:30, Feb.1st.2021", "12:30:00am Mon,2021.1st.Feb", "three-february-2021,12:45:00-03:00", "12:30:00 am, three.february.2021", "12-30am, three/february/2021", "three february 2021,7 am", etc.

Another date formats:

  • "10/06/20" (month number, day number, two digits of year, separated with '-', '.', '/') + time (separated with ":", may be am/pm time): "20/10/06 1:30:10 PM", "20.10.06 11:30:10", "1:30:10am 20-10-06", "1:30:10+03:00 20-10-06"
  • "sep/10/20", "sep.12.12", "sep-12-12" (month name, day number, two digits of year, separated with '-', '.', '/') + time (separated with ":", may be am/pm time): "20/Apr/06 1:30:10 PM", "20.10.August 11:30:10", "1:30:10am nov-10-06", "1:30:10+03:00 20-july-06"
  • time examples: "7 pm", "7pm", "123000am", "123000 am", "12:30 am", "12:30am", "12:30:00 am", "12:30:00am", "123000", "12:30+0200", "12:45-03:00", "2:30:00", "12:30:00", "12:30:00.123Z", "12:30:00Z", "12:30", "12:30:00+01:00", "12:30:00Z+01:00"

Timezone from the list that moment-timezone.js provides

Examples:

  • day-month-year + time:
    • "twenty-one-Apr-2020 12:30 am America/Los_Angeles", "America/Los_Angeles 7pm twenty-one.Apr.2020", "twenty-one/Apr/2020 America/Los_Angeles 123000pm", "12-30am three/february/2021 America/Los_Angeles", "three february 2021 7 am America/Los_Angeles", "America/Los_Angeles Feb-1st-2021 7 am", "Feb/1st/2021 America/Los_Angeles 123000", "2021/1st/Feb 12 30 am America/Los_Angeles", "may.5.2021 America/Los_Angeles 12-30-00", "America/Los_Angeles 2021/2/Mar 12-30", "12 30 00am America/Los_Angeles twenty-second may 2021", etc.
  • day-month-year + time + weekday:
    • "twenty-one-Apr-2020 Tuesday 12:30 am America/Los_Angeles", "Tue 7pm twenty-one.Apr.2020 America/Los_Angeles", "three-february-2021 America/Los_Angeles 12 30 am Wednesday", "Wednesday America/Los_Angeles 12-30am three.february.2021", "Feb-1st-2021 America/Los_Angeles 12:30:00am Monday", "America/Los_Angeles 12:30:00 1st-Feb-2021 Mon", "Monday 12:30 America/Los_Angeles Feb.1st.2021", etc.
  • day-month + time:
    • "twenty-one-Apr 12:30:00am America/Los_Angeles", "12:30 America/Los_Angeles twenty-one.Apr", "America/Los_Angeles twenty-one/Apr 10 30 00pm", "7:30PM America/Los_Angeles twenty-one Apr", "may.5 12.30 America/Los_Angeles", "may.twenty-second 12:30:00 am America/Los_Angeles", "12.30 am America/Los_Angeles twenty-second/may", "America/Los_Angeles twenty-second may 12 30am", etc.
  • weekday can be separated with comma:
    • "twenty-one-Apr, 12:30:00am, America/Los_Angeles", "12:30 America/Los_Angeles, twenty-one.Apr", "twenty-one/Apr,10 30 00pm America/Los_Angeles", "7:30PM,America/Los_Angeles,twenty-one Apr", "Feb-1st-2021, 12:30:00am, America/Los_Angeles, Monday", "America/Los_Angeles,12:30:00, 1st-Feb-2021 Mon", "Monday 12:30, Feb.1st.2021, America/Los_Angeles", "12:30:00am Mon,2021.1st.Feb America/Los_Angeles", "America/Los_Angeles,three-february-2021,12:45:00-03:00", "12:30:00 am, three.february.2021, America/Los_Angeles", "America/Los_Angeles 12-30am, three/february/2021", "three february 2021,America/Los_Angeles, 7 am", etc.

time

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

  • 5422456 (as unix time in ms)
  • "13:02:14.171447"
  • "5hours 30 minutes", "6 h 45m", "13h 50 minutes" (time units: h, hours, m, minutes, s, seconds, ms, milliseconds)
  • "1831", "1334 America/Los_Angeles" (hhmm); "123000", "183142", "150000 America/Los_Angeles" (hhmmss). If the value is invalid time in these formats (hhmmss,hhmm) it'll be parsed as unix time.
  • "7pm", "7 am", "07pm", "07 am", "10PM America/Los_Angeles"
  • "123000pm", "093042PM", "093042 am", "093042PM America/Los_Angeles"
  • hours + minutes ( + seconds) separated with ':', '-', '.', ' ' (space) :
    • "12 30 am", "12-30 am", "12.30 am", "12:30 am", "12 30am", "12-30am", "12.30am", "12:30am", "7:45pm", "7.45 am"
    • "12 30 00 am", "12 30 00am", "12-30-00 am", "12-30-00am", "12.30.00 am", "12.30.00am", "12:30:00 am", "12:30:00am"
    • "12 30 00", "12 30", "12-30-00", "12-30", "12.30.00", "12.30", "12:30:00", "12:30"
    • "12 30 00+0200", "12 45 00-03:00", "12.30.00+0200", "12.45.00-03:00", "12.30.00+0200", "12.45.00-03:00", "12:30:00+0200", "12:45:00-03:00"
    • "12 30 00Z+0200", "12 45 00Z-03:00", "12.30.00Z+0200", "12.45.00Z-03:00", "12.30.00Z+0200", "12.45.00Z-03:00", "12:30:00Z+0200", "12:45:00Z-03:00"
    • "12 30+0200", "12 45-03:00", "12-30+0200", "12-45-03:00", "12.30+0200", "12.45-03:00", "12:30+0200", "12:45-03:00"
    • "12 30 00Z", "12-30-00Z", "12.30.00Z", "12:30:00Z"
    • "12 30 00.000Z", "12-30-00.000Z", "12.30.00.000Z", "12:30:00.000Z"
    • may include timezone name: "12:30 America/Los_Angeles", "10.30.15PM Europe/Kiev"

If the value contains both - time offset and timezone name, at the same time, then the timezone name is preferred.

Invalid time:

  • "1:68:14 pm", "1:48-14 pm"
  • non-space separator between time and am/pm: "12:30-pm", "10.40.pm", "10.40.AM Europe/Kiev"
  • am/pm time + time offset: "7pm +01:00", "10:30:15am +01:00", "10 40AM +01:00"
  • "5hours 30 minutes 3 h 15 m"

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.