@funboxteam/chronos
    TypeScript icon, indicating that this package has built-in type declarations

    3.3.0 • Public • Published
    Chronos avatar: white-on-black gloomy antique half-human half-clock face

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

    Features

    Chronos picture: gloomy antique half-human half-clock carved in stone face

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

    Table of Contents

    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, 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);

    Important notes

    When adding months to date in JS one should mind the amount of days in the current and the result month.

    E.g. adding 1 month to 31.01.2020 leads to getting 02.03.2020, not 29.02.2020, because there can't be 31.02.2020.

    subtractMinutes, subtractHours, subtractDays, subtractMonths, 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, 1, 29), 1); // == new Date(2020, 0, 29);

    Important notes

    When subtracting months to date in JS one should mind the amount of days in the current and the result month.

    E.g. subtracting 1 month to 29.02.2020 leads to getting 29.01.2020, not 31.01.2020.

    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, getWeek, 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

    Important notes

    getWeek returns number of the week starting from the beginning of the year.

    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, getDiffInMonths, getDiffInYears

    (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.

    Sponsored by FunBox

    Keywords

    none

    Install

    npm i @funboxteam/chronos

    DownloadsWeekly Downloads

    33

    Version

    3.3.0

    License

    MIT

    Unpacked Size

    140 kB

    Total Files

    171

    Last publish

    Collaborators

    • funbox
    • egor.baranov
    • m.mamontenko
    • igoradamenko