Skip to content

Pamblam/protodate

Repository files navigation

Protodate Logo

npm version build coverage v3.0.8

Better Javascript Dates.

Contents

Intro

ProtoDate is a very fast and lightweight solution for building, parsing, manipulating and formatting Javascript Dates. ProtoDate extends the native JS Date object (without modifying the original prototype) for ease of use and to keep the library light. By leveraging native, low-level code ProtoDate is able to achieve unprecedented speeds.

Compare ProtoDate to Moment.js:

ProtoDate Moment.js
Parses Dates more than 2x faster Slower
Calculates elapsed time nearly 20x faster Much slower
Base lib minified @ 9.6kb (1/5th the size) Minified @ 50.43kb
100% code coverage only 94.6% code coverage
Timezone support from 1835-2500 (665yr Range) Timezone support from 2012-2022 (10yr Range)

Check out the benchmarks.

Also, if you happened to be a PHP developer, you're in luck because ProtoDate uses the same date formatting as PHP's native date function.

Choose Your File

ProtoDate has 6 different versions so you only have to download what you need.

Here's a helpful flow chart to help you choose which file best fits your needs:

Protodate file chooser flowchart

Usage

Browsers:

Download and include the js file that best fits your needs and include it in your markup.

<script src='protodate.min.js'></script>

Node

Install the library with npm install protodate and require the file that best fits your needs in your script.

const ProtoDate = require('protodate.js');

Formatting Dates

Use the format(formatStr) method to format dates as strings. Use the Formatting Characters Table to build your format string.

Example: new ProtoDate().format("m/d/y g:i a")

Parsing Dates

Use the parse(dateStr[, formatStr]) method to create a ProtoDate object from a string. If you provide a format string to the method, parsing will be much faster, but ProtoDate is smart enough to guess just about any format without it. Use any of the parsable formatting characters to create a format string.

Example: Protodate.parse("January 3rd 2007 @ 4 o'clock")

Manipulating Dates

Use the plus(quantity, period) and minus(quantity, period) methods to add and subtract time from a Date instance.

The period parameter is the unit of time to add or subtract, and the quantity parameter is how many of them to add or subtract. Specify the period parameter with using one of the 6 Date Period Constants, (ie, ProtoDate.MILLISECOND, ProtoDate.SECOND, ProtoDate.MINUTE, ProtoDate.HOUR, ProtoDate.DAY, ProtoDate.YEAR).

Example: new ProtoDate().add(3, ProtoDate.DAY) // 3 days from now

Converting Timezones

This functionality is only available in the protodate.tz.* files

You can convert dates to other timezones with the setTimezone(timezone) method.

Example: new ProtoDate().setTimezone('Asia/Hong_Kong').toString() // Current time in Hong Kong

Type Conversion

Generally, you should never need to convert a ProtoDate object to a native Date object since ProtoDate extends Date - it has all the same methods, but these functions are provided as a convenience.

Converting ProtoDate to native Date

Example: const date = protodate.toDate();

Converting Date to ProtoDate

Example: const protodate = ProtoDate.fromDate(date);

Formatting Characters

Each character represents part of a date format string. Characters listed as Parsable are understood by the parse method. All other characters, as well as characters escaped with a \ in the format string will be printed as-is.

format character Description Example returned values Parsable
Day -- -- --
d Day of the month, 2 digits with leading zeros 01 to 31
D A textual representation of a day, three letters Mon through Sun
j Day of the month without leading zeros 1 to 31
l (lowercase 'L') A full textual representation of the day of the week Sunday through Saturday
N ISO-8601 numeric representation of the day of the week 1 (for Monday) through 7 (for Sunday)
S English ordinal suffix for the day of the month, 2 characters st, nd, rd or th. Works well with j
w Numeric representation of the day of the week 0 (for Sunday) through 6 (for Saturday)
z The day of the year (starting from 0) 0 through 365
Week -- -- --
W ISO-8601 week number of year, weeks starting on Monday Example: 42 (the 42nd week in the year)
Month -- -- --
F A full textual representation of a month, such as January or March January through December
m Numeric representation of a month, with leading zeros 01 through 12
M A short textual representation of a month, three letters Jan through Dec
n Numeric representation of a month, without leading zeros 1 through 12
t Number of days in the given month 28 through 31
Year -- -- --
L Whether it's a leap year 1 if it is a leap year, 0 otherwise.
o ISO-8601 week-numbering year. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead. Examples: 1999 or 2003
Y A full numeric representation of a year, 4 digits Examples: 1999 or 2003
y A two digit representation of a year Examples: 99 or 03
Time -- -- --
a Lowercase Ante meridiem and Post meridiem am or pm
A Uppercase Ante meridiem and Post meridiem AM or PM
B Swatch Internet time 000 through 999
g 12-hour format of an hour without leading zeros 1 through 12
G 24-hour format of an hour without leading zeros 0 through 23
h 12-hour format of an hour with leading zeros 01 through 12
H 24-hour format of an hour with leading zeros 00 through 23
i Minutes with leading zeros 00 to 59
s Seconds, with leading zeros 00 through 59
v Milliseconds with leading zeros - 3 Digits. Example: 654
Timezone -- -- --
Z Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive. -43200 through 50400
Full Date/Time -- -- --
c ISO 8601 date 2004-02-12T15:19:21.990Z
U Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT) 1533566318
Other -- -- --
J Count of days since since noon Universal Time on January 1, 4713 BC on the Julian calendar 123412.5
P Moon Phase Waning Crescent

Timezone Reference

A list of timezones and their corresponding countries:

Country Timezone
Afghanistan Asia/Kabul
Aland Islands Europe/Mariehamn
Albania Europe/Tirane
Algeria Africa/Algiers
American Samoa Pacific/Pago_Pago
Andorra Europe/Andorra
Angola Africa/Luanda
Anguilla America/Anguilla
Antarctica Antarctica/Casey
Antarctica Antarctica/Davis
Antarctica Antarctica/DumontDUrville
Antarctica Antarctica/Mawson
Antarctica Antarctica/McMurdo
Antarctica Antarctica/Palmer
Antarctica Antarctica/Rothera
Antarctica Antarctica/Syowa
Antarctica Antarctica/Troll
Antarctica Antarctica/Vostok
Antigua and Barbuda America/Antigua
Argentina America/Argentina/Buenos_Aires
Argentina America/Argentina/Catamarca
Argentina America/Argentina/Cordoba
Argentina America/Argentina/Jujuy
Argentina America/Argentina/La_Rioja
Argentina America/Argentina/Mendoza
Argentina America/Argentina/Rio_Gallegos
Argentina America/Argentina/Salta
Argentina America/Argentina/San_Juan
Argentina America/Argentina/San_Luis
Argentina America/Argentina/Tucuman
Argentina America/Argentina/Ushuaia
Armenia Asia/Yerevan
Aruba America/Aruba
Australia Antarctica/Macquarie
Australia Australia/Adelaide
Australia Australia/Brisbane
Australia Australia/Broken_Hill
Australia Australia/Currie
Australia Australia/Darwin
Australia Australia/Eucla
Australia Australia/Hobart
Australia Australia/Lindeman
Australia Australia/Lord_Howe
Australia Australia/Melbourne
Australia Australia/Perth
Australia Australia/Sydney
Austria Europe/Vienna
Azerbaijan Asia/Baku
Bahamas America/Nassau
Bahrain Asia/Bahrain
Bangladesh Asia/Dhaka
Barbados America/Barbados
Belarus Europe/Minsk
Belgium Europe/Brussels
Belize America/Belize
Benin Africa/Porto-Novo
Bermuda Atlantic/Bermuda
Bhutan Asia/Thimphu
Bolivia America/La_Paz
Bonaire, Saint Eustatius and Saba America/Kralendijk
Bosnia and Herzegovina Europe/Sarajevo
Botswana Africa/Gaborone
Brazil America/Araguaina
Brazil America/Bahia
Brazil America/Belem
Brazil America/Boa_Vista
Brazil America/Campo_Grande
Brazil America/Cuiaba
Brazil America/Eirunepe
Brazil America/Fortaleza
Brazil America/Maceio
Brazil America/Manaus
Brazil America/Noronha
Brazil America/Porto_Velho
Brazil America/Recife
Brazil America/Rio_Branco
Brazil America/Santarem
Brazil America/Sao_Paulo
British Indian Ocean Territory Indian/Chagos
British Virgin Islands America/Tortola
Brunei Asia/Brunei
Bulgaria Europe/Sofia
Burkina Faso Africa/Ouagadougou
Burundi Africa/Bujumbura
Cambodia Asia/Phnom_Penh
Cameroon Africa/Douala
Canada America/Atikokan
Canada America/Blanc-Sablon
Canada America/Cambridge_Bay
Canada America/Creston
Canada America/Dawson
Canada America/Dawson_Creek
Canada America/Edmonton
Canada America/Fort_Nelson
Canada America/Glace_Bay
Canada America/Goose_Bay
Canada America/Halifax
Canada America/Inuvik
Canada America/Iqaluit
Canada America/Moncton
Canada America/Nipigon
Canada America/Pangnirtung
Canada America/Rainy_River
Canada America/Rankin_Inlet
Canada America/Regina
Canada America/Resolute
Canada America/St_Johns
Canada America/Swift_Current
Canada America/Thunder_Bay
Canada America/Toronto
Canada America/Vancouver
Canada America/Whitehorse
Canada America/Winnipeg
Canada America/Yellowknife
Cape Verde Atlantic/Cape_Verde
Cayman Islands America/Cayman
Central African Republic Africa/Bangui
Chad Africa/Ndjamena
Chile America/Punta_Arenas
Chile America/Santiago
Chile Pacific/Easter
China Asia/Shanghai
China Asia/Urumqi
Christmas Island Indian/Christmas
Cocos Islands Indian/Cocos
Colombia America/Bogota
Comoros Indian/Comoro
Cook Islands Pacific/Rarotonga
Costa Rica America/Costa_Rica
Croatia Europe/Zagreb
Cuba America/Havana
Curaçao America/Curacao
Cyprus Asia/Famagusta
Cyprus Asia/Nicosia
Czech Republic Europe/Prague
Democratic Republic of the Congo Africa/Kinshasa
Democratic Republic of the Congo Africa/Lubumbashi
Denmark Europe/Copenhagen
Djibouti Africa/Djibouti
Dominica America/Dominica
Dominican Republic America/Santo_Domingo
East Timor Asia/Dili
Ecuador America/Guayaquil
Ecuador Pacific/Galapagos
Egypt Africa/Cairo
El Salvador America/El_Salvador
Equatorial Guinea Africa/Malabo
Eritrea Africa/Asmara
Estonia Europe/Tallinn
Ethiopia Africa/Addis_Ababa
Falkland Islands Atlantic/Stanley
Faroe Islands Atlantic/Faroe
Fiji Pacific/Fiji
Finland Europe/Helsinki
France Europe/Paris
French Guiana America/Cayenne
French Polynesia Pacific/Gambier
French Polynesia Pacific/Marquesas
French Polynesia Pacific/Tahiti
French Southern Territories Indian/Kerguelen
Gabon Africa/Libreville
Gambia Africa/Banjul
Georgia Asia/Tbilisi
Germany Europe/Berlin
Germany Europe/Busingen
Ghana Africa/Accra
Gibraltar Europe/Gibraltar
Greece Europe/Athens
Greenland America/Danmarkshavn
Greenland America/Godthab
Greenland America/Scoresbysund
Greenland America/Thule
Grenada America/Grenada
Guadeloupe America/Guadeloupe
Guam Pacific/Guam
Guatemala America/Guatemala
Guernsey Europe/Guernsey
Guinea Africa/Conakry
Guinea-Bissau Africa/Bissau
Guyana America/Guyana
Haiti America/Port-au-Prince
Honduras America/Tegucigalpa
Hong Kong Asia/Hong_Kong
Hungary Europe/Budapest
Iceland Atlantic/Reykjavik
India Asia/Kolkata
Indonesia Asia/Jakarta
Indonesia Asia/Jayapura
Indonesia Asia/Makassar
Indonesia Asia/Pontianak
Iran Asia/Tehran
Iraq Asia/Baghdad
Ireland Europe/Dublin
Isle of Man Europe/Isle_of_Man
Israel Asia/Jerusalem
Italy Europe/Rome
Ivory Coast Africa/Abidjan
Jamaica America/Jamaica
Japan Asia/Tokyo
Jersey Europe/Jersey
Jordan Asia/Amman
Kazakhstan Asia/Almaty
Kazakhstan Asia/Aqtau
Kazakhstan Asia/Aqtobe
Kazakhstan Asia/Atyrau
Kazakhstan Asia/Oral
Kazakhstan Asia/Qyzylorda
Kenya Africa/Nairobi
Kiribati Pacific/Enderbury
Kiribati Pacific/Kiritimati
Kiribati Pacific/Tarawa
Kuwait Asia/Kuwait
Kyrgyzstan Asia/Bishkek
Laos Asia/Vientiane
Latvia Europe/Riga
Lebanon Asia/Beirut
Lesotho Africa/Maseru
Liberia Africa/Monrovia
Libya Africa/Tripoli
Liechtenstein Europe/Vaduz
Lithuania Europe/Vilnius
Luxembourg Europe/Luxembourg
Macao Asia/Macau
Macedonia Europe/Skopje
Madagascar Indian/Antananarivo
Malawi Africa/Blantyre
Malaysia Asia/Kuala_Lumpur
Malaysia Asia/Kuching
Maldives Indian/Maldives
Mali Africa/Bamako
Malta Europe/Malta
Marshall Islands Pacific/Kwajalein
Marshall Islands Pacific/Majuro
Martinique America/Martinique
Mauritania Africa/Nouakchott
Mauritius Indian/Mauritius
Mayotte Indian/Mayotte
Mexico America/Bahia_Banderas
Mexico America/Cancun
Mexico America/Chihuahua
Mexico America/Hermosillo
Mexico America/Matamoros
Mexico America/Mazatlan
Mexico America/Merida
Mexico America/Mexico_City
Mexico America/Monterrey
Mexico America/Ojinaga
Mexico America/Tijuana
Micronesia Pacific/Chuuk
Micronesia Pacific/Kosrae
Micronesia Pacific/Pohnpei
Moldova Europe/Chisinau
Monaco Europe/Monaco
Mongolia Asia/Choibalsan
Mongolia Asia/Hovd
Mongolia Asia/Ulaanbaatar
Montenegro Europe/Podgorica
Montserrat America/Montserrat
Morocco Africa/Casablanca
Mozambique Africa/Maputo
Myanmar Asia/Yangon
Namibia Africa/Windhoek
Nauru Pacific/Nauru
Nepal Asia/Kathmandu
Netherlands Europe/Amsterdam
New Caledonia Pacific/Noumea
New Zealand Pacific/Auckland
New Zealand Pacific/Chatham
Nicaragua America/Managua
Niger Africa/Niamey
Nigeria Africa/Lagos
Niue Pacific/Niue
Norfolk Island Pacific/Norfolk
North Korea Asia/Pyongyang
Northern Mariana Islands Pacific/Saipan
Norway Europe/Oslo
Oman Asia/Muscat
Pakistan Asia/Karachi
Palau Pacific/Palau
Palestinian Territory Asia/Gaza
Palestinian Territory Asia/Hebron
Panama America/Panama
Papua New Guinea Pacific/Bougainville
Papua New Guinea Pacific/Port_Moresby
Paraguay America/Asuncion
Peru America/Lima
Philippines Asia/Manila
Pitcairn Pacific/Pitcairn
Poland Europe/Warsaw
Portugal Atlantic/Azores
Portugal Atlantic/Madeira
Portugal Europe/Lisbon
Puerto Rico America/Puerto_Rico
Qatar Asia/Qatar
Republic of the Congo Africa/Brazzaville
Reunion Indian/Reunion
Romania Europe/Bucharest
Russia Asia/Anadyr
Russia Asia/Barnaul
Russia Asia/Chita
Russia Asia/Irkutsk
Russia Asia/Kamchatka
Russia Asia/Khandyga
Russia Asia/Krasnoyarsk
Russia Asia/Magadan
Russia Asia/Novokuznetsk
Russia Asia/Novosibirsk
Russia Asia/Omsk
Russia Asia/Sakhalin
Russia Asia/Srednekolymsk
Russia Asia/Tomsk
Russia Asia/Ust-Nera
Russia Asia/Vladivostok
Russia Asia/Yakutsk
Russia Asia/Yekaterinburg
Russia Europe/Astrakhan
Russia Europe/Kaliningrad
Russia Europe/Kirov
Russia Europe/Moscow
Russia Europe/Samara
Russia Europe/Saratov
Russia Europe/Simferopol
Russia Europe/Ulyanovsk
Russia Europe/Volgograd
Rwanda Africa/Kigali
Saint Barthélemy America/St_Barthelemy
Saint Helena Atlantic/St_Helena
Saint Kitts and Nevis America/St_Kitts
Saint Lucia America/St_Lucia
Saint Martin America/Marigot
Saint Pierre and Miquelon America/Miquelon
Saint Vincent and the Grenadines America/St_Vincent
Samoa Pacific/Apia
San Marino Europe/San_Marino
Sao Tome and Principe Africa/Sao_Tome
Saudi Arabia Asia/Riyadh
Senegal Africa/Dakar
Serbia Europe/Belgrade
Seychelles Indian/Mahe
Sierra Leone Africa/Freetown
Singapore Asia/Singapore
Sint Maarten America/Lower_Princes
Slovakia Europe/Bratislava
Slovenia Europe/Ljubljana
Solomon Islands Pacific/Guadalcanal
Somalia Africa/Mogadishu
South Africa Africa/Johannesburg
South Georgia and the South Sandwich Islands Atlantic/South_Georgia
South Korea Asia/Seoul
South Sudan Africa/Juba
Spain Africa/Ceuta
Spain Atlantic/Canary
Spain Europe/Madrid
Sri Lanka Asia/Colombo
Sudan Africa/Khartoum
Suriname America/Paramaribo
Svalbard and Jan Mayen Arctic/Longyearbyen
Swaziland Africa/Mbabane
Sweden Europe/Stockholm
Switzerland Europe/Zurich
Syria Asia/Damascus
Taiwan Asia/Taipei
Tajikistan Asia/Dushanbe
Tanzania Africa/Dar_es_Salaam
Thailand Asia/Bangkok
Togo Africa/Lome
Tokelau Pacific/Fakaofo
Tonga Pacific/Tongatapu
Trinidad and Tobago America/Port_of_Spain
Tunisia Africa/Tunis
Turkey Europe/Istanbul
Turkmenistan Asia/Ashgabat
Turks and Caicos Islands America/Grand_Turk
Tuvalu Pacific/Funafuti
U.S. Virgin Islands America/St_Thomas
Uganda Africa/Kampala
Ukraine Europe/Kiev
Ukraine Europe/Uzhgorod
Ukraine Europe/Zaporozhye
United Arab Emirates Asia/Dubai
United Kingdom Europe/London
United States America/Adak
United States America/Anchorage
United States America/Boise
United States America/Chicago
United States America/Denver
United States America/Detroit
United States America/Indiana/Indianapolis
United States America/Indiana/Knox
United States America/Indiana/Marengo
United States America/Indiana/Petersburg
United States America/Indiana/Tell_City
United States America/Indiana/Vevay
United States America/Indiana/Vincennes
United States America/Indiana/Winamac
United States America/Juneau
United States America/Kentucky/Louisville
United States America/Kentucky/Monticello
United States America/Los_Angeles
United States America/Menominee
United States America/Metlakatla
United States America/New_York
United States America/Nome
United States America/North_Dakota/Beulah
United States America/North_Dakota/Center
United States America/North_Dakota/New_Salem
United States America/Phoenix
United States America/Sitka
United States America/Yakutat
United States Pacific/Honolulu
United States Minor Outlying Islands Pacific/Midway
United States Minor Outlying Islands Pacific/Wake
Uruguay America/Montevideo
Uzbekistan Asia/Samarkand
Uzbekistan Asia/Tashkent
Vanuatu Pacific/Efate
Vatican Europe/Vatican
Venezuela America/Caracas
Vietnam Asia/Ho_Chi_Minh
Wallis and Futuna Pacific/Wallis
Western Sahara Africa/El_Aaiun
Yemen Asia/Aden
Zambia Africa/Lusaka
Zimbabwe Africa/Harare

License

ProtoDate comes with an Apache 2.0 license. Read the license here.