GitHub - funbox/chronos: One library to rule the time

Chronos is a tiny, immutable, typed date manipulation library which does not bloat your JS bundle,
but does everything you need.

Features

Immutable & pure function per file. Every function does not have side effects, nor mutates the params. If you use a function, only this function is added to your bundle, not the whole lib.
ESM & CommonJS. Works in Node.js and browser. Setup the target browsers for transpiling ES6 by your own in your bundler.
TypeScript. Every function is typed and the typings are bundled with the package.
Native API. Uses Date and Intl under the hood.
Russian locale only. And it has docs in Russian.

Rationale

When we started to develop our projects, we picked the most popular date library that existed back then. We had used only two methods it provided, but got all the bundled ones, with all the possible locales.

OK, we set up our bundler configs to remove those locales, but still that library was the biggest that we used, but the profit wasn't so huge. We decided to look around for the date library that we need, but all of them had a lot of features that we didn't want to use.

So we replaced it with small and lightweight functions that just worked. Step by step those functions have evolved into Chronos—simple yet useful date manipulation library that works in every our project.

Getting Started

Add the package into deps:

npm install --save @funboxteam/chronos

Import functions:

import { addYears } from '@funboxteam/chronos';

Types

The library exports several types that may be used elsewhere, but the most important that they used inside the lib to guarantee type safety.

ChronosDate

declare type ChronosDate = Date | number | string;

Every function that accepts date as a first param expects to get an instance of Date, or a timestamp as number or string.

The timestamp may be present as seconds or milliseconds (e.g. 1596803254000 and 1596803254 is the same value).

Duration

declare type Duration = {
  days: number;
  hours: number;
  minutes: number;
  seconds: number;
};

Type describing return value of functions that work with time intervals.

Functions

Every function is immutable and those which accept Date instances and return Date instance always return new Date instance and do not mutate the passed one.

addMinutes, addHours, addDays, addMonths, addCalendarMonths, addYears

(value: ChronosDate, quantity: number) => Date;

Params

value, date value;
quantity, number of units to add.

Example

addDays(new Date('2020-01-01T00:00:00.000Z'), 1); // 2020-01-02T00:00:00.000Z

// 1577836800 is 2020-01-01T00:00:00.000Z
addYears(1577836800, 1); // 2021-01-01T00:00:00.000Z

addMonths(new Date(2020, 0, 1), 1); // == new Date(2020, 1, 1);
addMonths(new Date(2020, 0, 31), 1); // == new Date(2020, 2, 2);

addCalendarMonths(new Date(2020, 0, 1), 1); // == new Date(2020, 1, 1);
addCalendarMonths(new Date(2020, 0, 31), 1); // == new Date(2020, 1, 29);

subtractMinutes, subtractHours, subtractDays, subtractMonths, subtractCalendarMonths, subtractYears

(value: ChronosDate, quantity: number) => Date;

Params

value, date value;
quantity, number of units to subtract.

Example

subtractDays(new Date('2020-01-01T00:00:00.000Z'), 1); // 2019-12-31T00:00:00.000Z

// 1577836800 is 2020-01-01T00:00:00.000Z
subtractYears(1577836800, 1); // 2019-01-01T00:00:00.000Z

subtractMonths(new Date(2020, 0, 1), 1); // == new Date(2019, 11, 1);
subtractMonths(new Date(2020, 2, 31), 1); // == new Date(2020, 2, 2);

subtractCalendarMonths(new Date(2020, 0, 1), 1); // == new Date(2019, 11, 1);
subtractCalendarMonths(new Date(2020, 2, 31), 1); // == new Date(2020, 1, 29);

formatDate

(value: ChronosDate, format: string) => string;

Params

value, date value;
format, desired format.

Available format tokens

Type	Token	Value
Second	`ss`	00, 01, 02, ..., 57, 58, 59
Minute	`mm`	00, 01, 02, ..., 57, 58, 59
Hour	`HH`	00, 01, 02, ..., 21, 22, 23
Day of Week	`dddd`	понедельник, вторник, ..., суббота, воскресенье
Day of Month	`DD`	01, 02, 03, ..., 29, 30, 31
	`D`	1, 2, 3, ..., 29, 30, 31
Month	`MMMM`	январь, февраль, ..., ноябрь, декабрь
	`MMM`	янв, фев, ..., ноя, дек
	`MM`	01, 02, 03, ..., 10, 11, 12
Year	`YYYY`	Full year, e.g.: 1885, 1955, 1985, 2015
	`YY`	00, 01, 02, ..., 97, 98, 99
UTC time offset	`ZZ`	-1200, -1100, ..., +1300, +1400
	`Z`	-12:00, -11:00, ..., +13:00, +14:00

Example

formatDate(new Date(2020, 0, 1), 'YYYY-MM-DDTHH:mm:ssZ'); // '2020-01-01T00:00:00+03:00' (for GMT+3)

// 1577836800 is 2020-01-01T00:00:00.000Z
formatDate(1577836800, 'HH:mm:ss'); // '03:00:00' (for GMT+3)

Important notes

Only Russian locale is supported for now!

formatTimeString

(value: string, valueFormat: string, format: string) => string;

Params

value, time string;
valueFormat, template describing value format;
format, desired format.

Available format tokens

Type	Token	Value
Second	`ss`	00, 01, 02, ..., 57, 58, 59
Minute	`mm`	00, 01, 02, ..., 57, 58, 59
Hour	`HH`	00, 01, 02, ..., 21, 22, 23
	`H`	0, 1, 2, ..., 21, 22, 23

Example

formatTimeString('22:00', 'HH:mm', 'HH:mm:ss'); // '22:00:00'

getMinutes, getHours, getDay, getMonth, getYear

(value: ChronosDate) => number;

Params

value, date value.

Example

getDay(new Date(2020, 0, 1)); // 1;

// 1577836800 is 2020-01-01T00:00:00.000Z
getYear(1577836800); // 2020

getWeekdayName, getMonthName

(value: ChronosDate, format?: string) => string;

Params

value, date value;
format, format of the returned string. 'long' (by default) or 'short'.

Example

getWeekdayName(new Date(2020, 11, 30)); // 'среда' (11th month in JS is December)
getWeekdayName(new Date(2020, 11, 30), 'short'); // 'ср'
getMonthName(new Date(2020, 0, 1)); // 'январь'
getMonthName(new Date(2020, 0, 1), 'short'); // 'янв'

getDuration

(seconds: number) => Duration;

Params

seconds, interval value in seconds.

Example

getDuration(1000000); // { days: 11, hours: 13, minutes: 46, seconds: 40 }

isSameMinute, isSameHour, isSameDay, isSameMonth, isSameYear

(firstValue: ChronosDate, secondValue: ChronosDate) => boolean;

Params

firstValue, date value;
secondValue, date value.

Example

// 1577750400 is 2019-12-31T00:00:00.000Z
// 1577836800 is 2020-01-01T00:00:00.000Z
isSameYear(1577750400, 1577836800); // false

getDiffInMinutes, getDiffInHours, getDiffInDays, getDiffInCalendarDays, getDiffInMonths, getDiffInCalendarMonths, getDiffInYears, getDiffInCalendarYears

(firstValue: ChronosDate, secondValue: ChronosDate) => number;

Params

firstValue, date value;
secondValue, date value.

Example

// 1577750400 is 2019-12-31T00:00:00.000Z
// 1577836800 is 2020-01-01T00:00:00.000Z
getDiffInDays(1577750400, 1577836800); // -1

getStartOfMinutes, getStartOfHours, getStartOfDay, getStartOfWeek, getStartOfMonth, getStartOfYear, getStartOfDecade

(value: ChronosDate, diff?: number) => Date;

Params

value, date value;
diff, number of units to add to the result date. 0 by default.

Example

// 1577836800 is 2020-01-01T00:00:00.000Z
getStartOfDay(1577836800); // 2019-12-31T21:00:00.000Z (for GMT+3)
getStartOfDay(1577836800, 1); // 2020-01-01T21:00:00.000Z (for GMT+3)
getStartOfDay(1577836800, -1); // 2019-12-30T21:00:00.000Z (for GMT+3)

getEndOfMinutes, getEndOfHours, getEndOfDay, getEndOfWeek, getEndOfMonth, getEndOfYear, getEndOfDecade

(value: ChronosDate, diff?: number) => Date;

Params

value, date value;
diff, number of units to add to the result date. 0 by default.

Example

// 1577836800 is 2020-01-01T00:00:00.000Z
getEndOfDay(1577836800); // 2020-01-01T20:59:59.999Z (for GMT+3)
getEndOfDay(1577836800, 1); // 2020-01-02T20:59:59.999Z (for GMT+3)
getEndOfDay(1577836800, -1); // 2019-12-31T20:59:59.999Z (for GMT+3)

getRelativeDate

(value: ChronosDate) => string;

Params

value, date value.

Example

getRelativeDate(1577081613); // '2 месяца' (for 07.02.2020)
getRelativeDate(new Date()); // 'меньше минуты'

getUtcOffset

(value: ChronosDate) => number;

Params

value, date value.

Example

getUtcOffset(new Date(2020, 0, 1)); // 3 (for GMT+3)

getUnixTimestamp

(date?: Date) => number;

Params

date, Date instance. new Date() by default.

Example

// now is 2020-02-07T08:26:59.422Z
getUnixTimestamp(); // 1581064019 (unix timestamp for new Date())

getUnixTimestamp(new Date(2020, 0, 1)); // 1577826000 (for GMT+3)

getTimezoneName

() => string;

Example

getTimezoneName(); // 'Europe/Moscow' (for any GMT+3 timezone in IE11 and for MSK in modern browsers)

Important notes

In case of lack of Intl API support returns nearest to the user timezone which has integer hours offset.

isTimeValid

(value: string, format: string) => boolean;

Params

value, time string;
format, format string that should be used for validation.

Example

isTimeValid('22:30', 'HH:mm'); // true

parseDate

(value: string, format: string) => Date;

Params

value, date string;
format, format string that should be used for parsing.

Available format tokens

Type	Token	Recognized values
Day of Month	`DD`	01, 02, 03, ..., 29, 30, 31
	`D`	1, 2, 3, ..., 29, 30, 31
Month	`MM`	01, 02, 03, ..., 10, 11, 12
Year	`YYYY`	Full year, e.g.: 1885, 1955, 1985, 2015
	`YY`	00, 01, 02, ..., 97, 98, 99

Example

parseDate('2000-01-21', 'YYYY-MM-DD'); // == new Date(2000, 0, 21)
parseDate('2020-01-01T00:00:00+03:00'); // == new Date(2020, 0, 1) (for GMT+3)

Important notes

If format is not passed it tries to parse value using native Date.parse. It should support ISO 8601 and RFC 2822. Other formats are not recommended to parse without explicit format set.

Credits

Project's pictures were made by Igor Garybaldi.

Name		Name	Last commit message	Last commit date
Latest commit History 311 Commits
.github/workflows		.github/workflows
images		images
lib		lib
tests		tests
.browserslistrc		.browserslistrc
.editorconfig		.editorconfig
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
MIGRATION.md		MIGRATION.md
README.md		README.md
README.ru.md		README.ru.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.eslint.json		tsconfig.eslint.json
tsconfig.json		tsconfig.json

License

funbox/chronos

Folders and files

Latest commit

History

Repository files navigation

Features

Rationale

Table of Contents

Getting Started

Types

ChronosDate

Duration

Functions

addMinutes, addHours, addDays, addMonths, addCalendarMonths, addYears

Params

Example

subtractMinutes, subtractHours, subtractDays, subtractMonths, subtractCalendarMonths, subtractYears

Params

Example

Params

Available format tokens

Example

Important notes

Params

Available format tokens

Example

getMinutes, getHours, getDay, getMonth, getYear

Params

Example

getWeekdayName, getMonthName

Params

Example

Params

Example

isSameMinute, isSameHour, isSameDay, isSameMonth, isSameYear

Params

Example

getDiffInMinutes, getDiffInHours, getDiffInDays, getDiffInCalendarDays, getDiffInMonths, getDiffInCalendarMonths, getDiffInYears, getDiffInCalendarYears

Params

Example

getStartOfMinutes, getStartOfHours, getStartOfDay, getStartOfWeek, getStartOfMonth, getStartOfYear, getStartOfDecade

Params

Example

getEndOfMinutes, getEndOfHours, getEndOfDay, getEndOfWeek, getEndOfMonth, getEndOfYear, getEndOfDecade

Params

Example

Params

Example

Params

Example

Params

Example

Example

Important notes

Params

Example

Params

Available format tokens

Example

Important notes

Credits

About

Topics

Resources

License

Stars

Watchers

Forks

Languages