Security News
Oracle Drags Its Feet in the JavaScript Trademark Dispute
Oracle seeks to dismiss fraud claims in the JavaScript trademark dispute, delaying the case and avoiding questions about its right to the name.
@funboxteam/chronos
Advanced tools
Date
and Intl
under the hood.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.
Add the package into deps:
npm install --save @funboxteam/chronos
Import functions:
import { addYears } from '@funboxteam/chronos';
The library exports several types that may be used elsewhere, but the most important that they used inside the lib to guarantee type safety.
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).
declare type Duration = {
days: number;
hours: number;
minutes: number;
seconds: number;
};
Type describing return value of functions that work with time intervals.
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.
(value: ChronosDate, quantity: number) => Date;
value
, date value;quantity
, number of units to add.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);
(value: ChronosDate, quantity: number) => Date;
value
, date value;quantity
, number of units to subtract.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);
(value: ChronosDate, format: string) => string;
value
, date value;format
, desired format.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 |
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)
Only Russian locale is supported for now!
(value: string, valueFormat: string, format: string) => string;
value
, time string;valueFormat
, template describing value
format;format
, desired format.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 |
formatTimeString('22:00', 'HH:mm', 'HH:mm:ss'); // '22:00:00'
(value: ChronosDate) => number;
value
, date value.getDay(new Date(2020, 0, 1)); // 1;
// 1577836800 is 2020-01-01T00:00:00.000Z
getYear(1577836800); // 2020
(value: ChronosDate, format?: string) => string;
value
, date value;format
, format of the returned string. 'long'
(by default) or 'short'
.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'); // 'янв'
(seconds: number) => Duration;
seconds
, interval value in seconds.getDuration(1000000); // { days: 11, hours: 13, minutes: 46, seconds: 40 }
(firstValue: ChronosDate, secondValue: ChronosDate) => boolean;
firstValue
, date value;secondValue
, date value.// 1577750400 is 2019-12-31T00:00:00.000Z
// 1577836800 is 2020-01-01T00:00:00.000Z
isSameYear(1577750400, 1577836800); // false
(firstValue: ChronosDate, secondValue: ChronosDate) => number;
firstValue
, date value;secondValue
, date value.// 1577750400 is 2019-12-31T00:00:00.000Z
// 1577836800 is 2020-01-01T00:00:00.000Z
getDiffInDays(1577750400, 1577836800); // -1
(value: ChronosDate, diff?: number) => Date;
value
, date value;diff
, number of units to add to the result date. 0
by default.// 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)
(value: ChronosDate, diff?: number) => Date;
value
, date value;diff
, number of units to add to the result date. 0
by default.// 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)
(value: ChronosDate) => string;
value
, date value.getRelativeDate(1577081613); // '2 месяца' (for 07.02.2020)
getRelativeDate(new Date()); // 'меньше минуты'
(value: ChronosDate) => number;
value
, date value.getUtcOffset(new Date(2020, 0, 1)); // 3 (for GMT+3)
(date?: Date) => number;
date
, Date instance. new Date()
by default.// 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)
() => string;
getTimezoneName(); // 'Europe/Moscow' (for any GMT+3 timezone in IE11 and for MSK in modern browsers)
In case of lack of Intl API support returns nearest to the user timezone which has integer hours offset.
(value: string, format: string) => boolean;
value
, time string;format
, format string that should be used for validation.isTimeValid('22:30', 'HH:mm'); // true
(value: string, format: string) => Date;
value
, date string;format
, format string that should be used for parsing.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 |
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)
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.
Project's pictures were made by Igor Garybaldi.
5.0.3 (23.05.2023)
Fixed the content of the package.
Previous release introduced an additional layer of subdirectories, which ruined all the imports on users' projects.
FAQs
One library to rule the time
We found that @funboxteam/chronos demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Oracle seeks to dismiss fraud claims in the JavaScript trademark dispute, delaying the case and avoiding questions about its right to the name.
Security News
The Linux Foundation is warning open source developers that compliance with global sanctions is mandatory, highlighting legal risks and restrictions on contributions.
Security News
Maven Central now validates Sigstore signatures, making it easier for developers to verify the provenance of Java packages.