Tick is an open-source multi-calendar, lightweight and rich JavaScript library for parsing, validating, manipulating, formatting, and displaying date and time for all the Javascript runtime environments (NodeJS, browser, ...). It supports many calendars and you can easily convert DateTime between different calendars and time zones.
Multi-Calendar
Tick currently supports multiple calendars. Gregorian, Hijri and Persian calendars have already been implemented. you can easily implement your own calendars.
DateTime object is independent of the calendars
Extensible
With 4 Pre-implemented calendars
Note:
Gregorian2, Hijri, and Persian calendars have a standalone solution that operates independently of the JavaScript Date object. It offers its unique calculations and functionalities, providing a comprehensive and reliable approach to managing date.
Accurate
Wide date range support
Localization support
Timezone support
Immutable
Treeshakable
Lightweight
NodeJS and browser support
npm install @soft-libs/tick
Import the calendars you need in your project, instantiate and add them to Calendars collection. You must add at least one calendar to Calendars collection.
Add the following code at the starting point of your application:
import { DateTime, Calendars } from '@soft-libs/tick';
import { GregorianCalendar } from '@soft-libs/tick/calendars/gregorian';
import { HijriCalendar } from '@soft-libs/tick/calendars/hijri';
import { PersianCalendar } from '@soft-libs/tick/calendars/persian';
import { GregorianCalendar2 } from '@soft-libs/tick/calendars/gregorian2';
// Add the calendars you need in your project
Calendars.add(new GregorianCalendar('gregorian'));
Calendars.add(new HijriCalendar('hijri',0));
Calendars.add(new PersianCalendar('persian'));
Calendars.add(new GregorianCalendar2('gregorian'));
const { DateTime, Calendars } = require("@soft-libs/tick");
const { GregorianCalendar } = require("@soft-libs/tick/calendars/gregorian");
const { HijriCalendar } = require("@soft-libs/tick/calendars/hijri");
const { PersianCalendar } = require("@soft-libs/tick/calendars/persian");
const { GregorianCalendar2 } = require("@soft-libs/tick/calendars/gregorian2");
// Add the calendars you need in your project
Calendars.add(new GregorianCalendar('gregorian'));
Calendars.add(new HijriCalendar('hijri',0));
Calendars.add(new PersianCalendar('persian'));
Calendars.add(new GregorianCalendar2('gregorian2'));
Note:
the first calendar you add to Calendars collection is set as the default calendar. You can change the default Calendar of your project at any time.
DateTime object is the main object of Tick library. It stores date and time values. While creating DateTime object, you should provide following parameters:
Note:
If you don't provide above parameters to the DateTime constructor, default values will be used:
- Default calendar: The first calendar you add to Calendars collection.
- Default Locale: System locale.
- Default Zone: local time-zone.
Create the date with the given components in the local time zone and default calendar. Only the first two arguments are obligatory.
Following examples show you how to create DateTime objects with different Calendars, Locales and zones. In all examples of this documentation, we suppose that you have added following calendars to your project:
Calendars.add(new GregorianCalendar('gregorian'));
Calendars.add(new HijriCalendar('hijri',0));
Calendars.add(new PersianCalendar('persian'));
Create a DateTime with default Calendar, Zone and Locale
//
const d = new DateTime(); // now
Create DateTime objects by specifying a calendar:
import { DateTime, Calendars } from '@soft-libs/tick';
const d1 = new DateTime({calendar: 'gregorian'});
const d2 = new DateTime({calendar: 'hijri'});
const d3 = new DateTime({calendar: Calendars.find('persian')});
console.log(d1.year, d1.month, d1.day);
console.log(d2.year, d2.month, d2.day);
console.log(d3.year, d3.month, d3.day);
// output (something like this):
2022 01 13
1443 06 10
1400 10 23
Create a DateTime by specifying date and time units (by using default calendar, zone and locale):
const d1 = new DateTime(2021, 10);
// year: 2021,
// month: 10,
// day: 1,
// hour = minute = second = ms: 0
const d2 = new DateTime(2021, 10, 28, 14, 56, 45, 122);
// year: 2021,
// month: 10,
// day: 28,
// hour: 14,
// minute: 56
// second: 45,
// ms (millisecond): 122
Create DateTimes by specifying date/time units and a calendar:
const d1 = new DateTime(2021, 10, 28, 14, 56, 45, 122, {calendar: 'gregorian'});
// year: 2021,
// month: 10,
// ...
// ms (millisecond): 122,
// calendar: [a calendar in Calendars collection with id 'gregorian']
// If you don't want to set all date-time units and also you want to set some options(calendar, zone, locale), pass options as first argument:
const d2 = new DateTime({calendar: 'gregorian'} , 2021, 10);
// year: 2021,
// month: 10,
// day: 1,
// hour = minute = second = ms: 0
Create a DateTime by specifying calendar, locale and time-zones:
const d1 = new DateTime({zone: Zones.utc}, 2021, 10);
// year: 2021, month: 10, day: 1
// hour = minute = second = ms: 0
// calendar: default calendar
// zone: UTC
// locale: default locale
const d2 = new DateTime(1400, 10, 23, {
calendar: 'persian'
zone: Zones.local,
});
// year: 2021, month: 10, day: 23
// hour = minute = second = ms: 0
// calendar: a calendar with id 'persian'
// zone: local time zone (an instance of LocalZone object)
// locale: default locale
const d3 = new DateTime({
calendar: Calendars.find('hijri'),
zone: Zones.iana('Asia/Dubai'),
}, 1443, 06, 10);
// year: 1443, month: 06, day: 10
// hour = minute = second = ms: 0
// calendar: a calendar with id 'hijri'
// zone: Asia/Dubai IANA time-zone (a RuntimeIANAZone object)
// locale: default locale
const d4 = new DateTime({
calendar: 'gregorian2'
zone: Zones.iana('Asia/Dubai'),
locale: 'ar'
}, 2022, 1, 10);
// year: 2021, month: 1, day: 10
// hour = minute = second = ms: 0
// calendar: a calendar with id 'gregorian2'
// zone: Asia/Dubai IANA time-zone (a RuntimeIANAZone object)
// locale: ar (arabic) locale
Note:
DateTime object is immutable.
After creating a DateTime object, you cannot change it. In other words, you cannot change it's date-time units, calendar, zone or locale.
A Calendar is an object that does date-time calculations in a specific calendaring system, DateTime object is not aware of calculations, it just delegate calendaring calculations to its Calendar object.
Currently four calendars have been implemented:
You can easily implement your own Calendar by extending Calendar class and implementing abstract methods.
If you create a DateTime object and don't provide a value for the calendar parameter, the default calendar of application is used as the calendar of that DateTime object.
You can set the default calendar of the project at runtime:
import { Calendars } from '@soft-libs/tick';
const hc = Calendars.find('hijri');
Calendars.default = hc;
With Tick library you can easily convert the calendar of a DateTime object:
// Create a Gregorian date
const d1 = new DateTime({calendar: 'gregorian'}, 2021, 10, 26);
console.log(d1.year, d1.month, d1.day) //-> 2021, 10, 26
// Convert Gregorian to Persian date
const d2 = gregorianDate.to('persian');
console.log(d2.year, d2.month, d2.day) //-> 1400, 8, 4
// Convert Persian to Hijri date
const d3 = d2.to('hijri');
console.log(d3.year, d3.month, d3.day) //-> 1443, 3, 19
A time zone is a region of the Earth that has adopted the same standard time, usually referred to as the local time. Most adjacent time zones are exactly one hour apart, and by convention compute their local time as an offset from Greenwich Mean Time (see also UTC). The Zones object is responsible for creating Zone objects. Generally there are 3 different Zone objects in Tick library:
You can create Zone objects by using static methods of Zones class:
import { Calendars } from '@soft-libs/tick';
// Create a FixedZone (name: 'my_zone', offset: +03:30)
zone1 = Zones.fixed('my_zone', 3, 30);
// UTC zone (a FixedZone with zero offset)
zone2 = Zones.utc;
// LocalZone
zone3 = Zones.local;
// Create an IANAZone
zone4 = Zones.iana('Asia/Istanbul');
// Create a DateTime with a specific zone
const d = new DateTime({ zone: zone4 });
It's easy to convert(change) the time-zone of DateTime objects:
const d = new DateTime({ zone: Zones.utc }, 2022, 1, 1, 12);
console.log(d.hour, d1.minute, d.second); // output: 12, 0, 0
const d2 = d.toZone('Asia/Tehran');
console.log(d2.hour, d2.minute, d2.second); // output: 3, 30, 0
const d3 = d.toZone('Europe/Luxembourg');
console.log(d3.hour, d3.minute, d3.second); // output: 1, 0, 0
Note that toZone() method returns a new DateTime object and doesn't change the zone of the object.
DateTime constructor has several overloads:
DateTime();
DateTime(opts);
DateTime(year, month, day?, hour?, minute?, second?, ms?, opts?);
DateTime(opts, year, month, day?, hour?, minute?, second?, ms?);
DateTime(timestamp, opts?);
// Parameters with a question mark(?) are optional.
options ("opts" parameter) is an object with three optional properties:
const dt = new DateTime( { calendar: 'gregorian' }, 2020,1,1);
const dt2 = dt.add({ day: 1 });
console.log(dt2.year, dt2.month, dt2.day); //-> 2020, 1, 2
const dt = new DateTime({ calendar: 'persian'}, 1400,1,1 );
const dt2 = dt.subtract({ day: 1 });
console.log(dt2.year, dt2.month, dt2.day); //-> 1399, 12, 30
You can parse strings by using parse plugin:
import { parse } from '@soft-libs/tick/plugins/parse';
const d1 = parse('2012/2/6', 'Y/M/d');
console.log(d1.year, d1.month, d1.day) // output: 2012, 2, 6
const dt = parse("1400-10-23", "YYYY-MM-dd", {calendar: 'persian'});
console.log(dt.year, dt.month, dt.day) // output: 1400, 10, 23
For more information, see parse plugin documentation.
You can format dates by using format plugin:
import { format } from '@soft-libs/tick/plugins/format';
const d1 = new DateTime(2001, 9, 8);
console.log(format(d1,'dd/MM/YYYY')) // output: '08/09/2001'
DateTime object is immutable. An immutable object means that the state of the object cannot change after its creation. In other words you cannot change date-time units, calendar, zone or locale.
const d1 = new DateTime();
const d2 = d1.add({ hour: 1});
d1.valueOf() === d2.valueOf(); // false
In this case, the add() method returns a new instance, leaving d1 unmodified.
Generated using TypeDoc