@holistics/date-parser NPM

`@holistics/date-parser`

Holistics (relative) date parser

Usage (v3.x)

API

export const parse = (str, ref, {
  timezoneRegion = 'Etc/UTC',
  output = OUTPUT_TYPES.parsed_component,
  weekStartDay = WEEKDAYS.Monday,
  parserVersion = 3,
} = {})

Note

Use parserVersion = 3 to use the new date parser that supports timezone region
To use the old API of v2.x, please read the below section of v2.x
This parserVersion flag is to help you gradually migrating to v3.x

Output types:

date: 2021-12-01 (wallclock time, timezone is implicit)
timestamp: E.g. 2021-12-02 00:00:00+08:00. The offset here is determined by the timezone region input
timestamp_utc: same as timestamp but the result is converted to UTC, e.g. 2021-12-02 16:00:00+00:00
raw: return the Result class, mostly for internal debugging
luxon: return a Luxon instance

Examples

let res = nil

res = parse('last 2 days', new Date('2019-12-26T02:14:05Z'), { parserVersion: 2, output: 'date', timezoneRegion: 'America/Chicago' });
expect(res.start).toEqual('2019-12-23');
expect(res.end).toEqual('2019-12-25');

res = parse('last 2 days', new Date('2019-12-26T02:14:05Z'), { parserVersion: 2, output: 'timestamp', timezoneRegion: 'America/Chicago' });
expect(res.start).toEqual('2019-12-23T00:00:00.000-06:00');
expect(res.end).toEqual('2019-12-25T00:00:00.000-06:00');

res = parse('last 2 days', new Date('2019-12-26T02:14:05Z'), { parserVersion: 2, output: 'timestamp_utc', timezoneRegion: 'America/Chicago' });
expect(res.start).toEqual('2019-12-23T06:00:00.000+00:00');
expect(res.end).toEqual('2019-12-25T06:00:00.000+00:00');

res = parse('last 2 days', new Date('2019-12-26T02:14:05Z'), { parserVersion: 2, output: 'luxon', timezoneRegion: 'America/Chicago' });
expect(res.start.toISO()).toEqual('2019-12-23T00:00:00.000-06:00');

res = parse('last 2 days', new Date('2019-12-26T02:14:05Z'), { parserVersion: 2, timezoneRegion: 'America/Chicago' });
expect(res.start).toEqual('2019-12-23T00:00:00.000-06:00');

Usage (v2.x)

Note: v2.x is still applicable but it will be deprecated. No further changes will be made on the v2.x

import { parse, OUTPUT_TYPES, WEEKDAYS } from '@holistics/date-parser';

const referenceDate = new Date();

// Using default options
console.log(parse('yesterday'), referenceDate);

const { text, ref, start, end } = parse('monday last week', '2019-01-03T03:14:29Z');
console.log(start.moment().format('YYYY/MM/DD'));
console.log(start.date().toUTCString());

// Change the output format
console.log(parse('last week begin'), referenceDate, { output: OUTPUT_TYPES.date });
console.log(parse('last week end'), referenceDate, { output: OUTPUT_TYPES.timestamp });

// Set timezoneOffset (timezoneOffset is 0 by default)
const timezoneOffset = -(new Date().getTimezoneOffset); // should use the actual offset, not the Javascript's reversed offset
console.log(parse('3 days from now'), referenceDate, { timezoneOffset });
// the following examples demonstrate why timezoneOffset is important
let res;
res = parse('yesterday', '2019-04-11T22:00:00+00:00', { output: OUTPUT_TYPES.date });
console.log(res.start) // 2019-04-10
console.log(res.end) // 2019-04-11
res = parse('yesterday', '2019-04-12T06:00:00+08:00', { output: OUTPUT_TYPES.date });
console.log(res.start) // 2019-04-10
console.log(res.end) // 2019-04-11
res = parse('yesterday', '2019-04-11T22:00:00+00:00', { timezoneOffset: 540, output: OUTPUT_TYPES.date });
console.log(res.start) // 2019-04-11
console.log(res.end) // 2019-04-12

// Set weekStartDay (weekStartDay is Monday by default)
res = parse('last week begin', '2021-05-10T22:14:05Z', { weekStartDay: WEEKDAYS.Tuesday, output: OUTPUT_TYPES.date });
console.log(res.start) // 2021-04-27