chrono-utils 🕰️ 🥷 ⌚

chrono-utils collects a number of helpful date and time utilities for TypeScript/Javascript.

These utility functions are particularly useful when building applications that need to use Unix timestamps and convert between human-readable and query-optimized (Unix) times.

Usage

Installation

Run npm install chrono-utils. Exchange npm with your chosen package manager if needed.

Basic importing and usage

// ES5 format
const { convertDateToUnixTimestamp } = require('chrono-utils');
// ES6 format
import { convertDateToUnixTimestamp } from 'chrono-utils';

convertDateToUnixTimestamp('2021-12-31T10:01:37Z');

Overview of functions

The below explains each of the functions in chrono-utils and shows examples of their output.

convertDateToUnixTimestamp

Converts a regular date to (JS) Unix timestamp.

import { convertDateToUnixTimestamp } from 'chrono-utils';

convertDateToUnixTimestamp('2021-12-31T10:01:37Z'); // '1640944897000'
convertDateToUnixTimestamp('2022-01-10T08:42:43+00:00'); // '1641804163000'

datesWithinMaximumRange

Checks if two date objects are within a accepted maximum day range.

import { datesWithinMaximumRange } from 'chrono-utils';

const startDate = new Date('2022-11-30');
const endDate = new Date('2022-12-01');
const response = datesWithinMaximumRange(startDate, endDate); // true

getDateFromTimestamp

Takes a timestamp and returns the current date in YYYYMMDD format.

import { getDateFromTimestamp } from 'chrono-utils';

getDateFromTimestamp('1664928000'); // '20221005'

getCurrentDate

Returns the current date in YYYY-MM-DD format.

The noDashes option will strip any dashes between days, months, etc.

import { getCurrentDate } from 'chrono-utils';

const withDashes = getCurrentDate(); // '2022-11-20'
const withoutDashes = getCurrentDate(true); // '20221120'

getDateYesterday

Return the date of the day before today in YYYY-MM-DD format.

The noDashes option will strip any dashes between days, months, etc.

import { getDateYesterday } from 'chrono-utils';

const withDashes = getDateYesterday(); // '2022-11-20'
const withoutDashes = getDateYesterday(true); // '20221120'

getDiffInSeconds

Get the difference in seconds between two moments in time (i.e. Unix timestamps).

import { getDiffInSeconds } from 'chrono-utils';

getDiffInSeconds('1670873500000', '1670873600000'); // 100

getFirstDateInCurrentMonth

Returns the first date in the current month in YYYY-MM-DD format.

import { getFirstDateInCurrentMonth } from 'chrono-utils';

getFirstDateInCurrentMonth(); // '2022-12-01'

getLastDateInCurrentMonth

Returns the last date in the current month in YYYY-MM-DD format.

import { getLastDateInCurrentMonth } from 'chrono-utils';

getLastDateInCurrentMonth(); // '2022-12-31'

getMaxTimestampFromDate

Get maximum historical/past timestamp at midnight X number of days ago.

import { getMaxTimestampFromDate } from 'chrono-utils';

getMaxTimestampFromDate(10, 0); // 10 days, 0 offset - '1672790400'
getMaxTimestampFromDate(6, 6); // 6 days, +6 hours offset - '1673157600'
getMaxTimestampFromDate(4, -2); // 4 days, -2 hours offset - '1673301600'

getMillisecondsForDays

Returns the number of milliseconds for a count of days.

import { getMillisecondsForDays } from 'chrono-utils';

getMillisecondsForDays(); // 259200000

getTimestampForInputDate

Gets a corresponding Unix timestamp for a YYYYMMDD date.

import { getTimestampForInputDate } from 'chrono-utils';

getTimestampForInputDate('20230101'); // '1672531200'
getTimestampForInputDate('20230101', 4); // +4 hours offset - '1672545600'
getTimestampForInputDate('20230101', -11); // -11 hours offset - '1672491600'

getTimestampsForPeriod

Calculates from and to timestamps for a provided period in days.

Using lastNumDays means getting specified range excluding current day.

import { getTimestampsForPeriod } from 'chrono-utils';

getTimestampsForPeriod(1); // 1 day, zero offset - { "from": "1673568000", "to": "1673654399" }
getTimestampsForPeriod(5, -3); // 5 days, -3 hours offset - { "from": "1673211600", "to": "1673643599" }
getTimestampsForPeriod(14, 7); // 14 days, +7 hours offset - { "from": "1672470000", "to": "1673679599" }

isUnitTimestamp

Check if the input matching a 10 or 13 digit Unix timestamp.

import { isUnixTimestamp } from 'chrono-utils';

isUnixTimestamp(1234567890); // true
isUnixTimestamp('1234567890123'); // true
isUnixTimestamp('123456789'); // false
isUnixTimestamp('12345678901234'); // false
isUnixTimestamp('2024-06-06'); // false

makeTwoDigitDate

Add leading zero if date (day, month) is under 10.

import { makeTwoDigitDate } from 'chrono-utils';

makeTwoDigitDate(1, 'day'); // '01'
makeTwoDigitDate(11, 'month'); // '11'
makeTwoDigitDate(new Date('2022-12-05'), 'day'); // '05'
makeTwoDigitDate(new Date('2022-07-05'), 'month'); // '07'

prettifyTime

Returns a prettified time format (DD:HH:MM:SS) from a count of seconds.

import { prettifyTime } from 'chrono-utils';

prettifyTime(60); // '00:00:01:00';
prettifyTime(123456); // '01:10:17:36';

prettyTimeToSeconds

Converts a prettified time to a numberic count of seconds to represent the same value.

import { prettyTimeToSeconds } from 'chrono-utils';

prettyTimeToSeconds('00:09:28:24'); // 34104

zuluToUnix

Converts Zulu time (UTC/GMT +0) to Unix timestamp.

import { zuluToUnix } from 'chrono-utils';

zuluToUnix('2022-11-21T10:41:57Z'); // 1669027317000