Showing preview only (972K chars total). Download the full file or copy to clipboard to get everything.
Repository: knowledgecode/date-and-time
Branch: master
Commit: b505b94b0590
Files: 618
Total size: 833.5 KB
Directory structure:
gitextract_4dtccixv/
├── .editorconfig
├── .github/
│ └── workflows/
│ ├── deploy-docs.yml
│ └── test.yml
├── .gitignore
├── LICENSE
├── README.md
├── astro.config.mjs
├── docs/
│ ├── api/
│ │ ├── addDays.md
│ │ ├── addHours.md
│ │ ├── addMilliseconds.md
│ │ ├── addMinutes.md
│ │ ├── addMonths.md
│ │ ├── addSeconds.md
│ │ ├── addYears.md
│ │ ├── compile.md
│ │ ├── format.md
│ │ ├── index.md
│ │ ├── isValid.md
│ │ ├── parse.md
│ │ ├── preparse.md
│ │ ├── subtract.md
│ │ ├── transform.md
│ │ └── utils/
│ │ ├── getDaysInMonth.md
│ │ ├── getISOWeek.md
│ │ ├── getISOWeekYear.md
│ │ ├── isLeapYear.md
│ │ └── isSameDay.md
│ ├── content.config.ts
│ ├── env.d.ts
│ ├── guide/
│ │ ├── index.md
│ │ ├── installation.mdx
│ │ └── quick-start.md
│ ├── index.mdx
│ ├── locales.md
│ ├── migration.md
│ ├── plugins.md
│ ├── styles/
│ │ └── custom.css
│ ├── timezones.md
│ └── tsconfig.json
├── eslint.config.js
├── package.json
├── rollup.config.ts
├── src/
│ ├── addDays.ts
│ ├── addHours.ts
│ ├── addMilliseconds.ts
│ ├── addMinutes.ts
│ ├── addMonths.ts
│ ├── addSeconds.ts
│ ├── addYears.ts
│ ├── compile.ts
│ ├── datetime.ts
│ ├── dtf.ts
│ ├── duration.ts
│ ├── format.ts
│ ├── formatter.ts
│ ├── index.ts
│ ├── isValid.ts
│ ├── locale.ts
│ ├── locales/
│ │ ├── ar.ts
│ │ ├── az.ts
│ │ ├── bn.ts
│ │ ├── cs.ts
│ │ ├── da.ts
│ │ ├── de.ts
│ │ ├── el.ts
│ │ ├── en.ts
│ │ ├── es.ts
│ │ ├── fa.ts
│ │ ├── fi.ts
│ │ ├── fr.ts
│ │ ├── he.ts
│ │ ├── hi.ts
│ │ ├── hu.ts
│ │ ├── id.ts
│ │ ├── it.ts
│ │ ├── ja.ts
│ │ ├── ko.ts
│ │ ├── ms.ts
│ │ ├── my.ts
│ │ ├── nl.ts
│ │ ├── no.ts
│ │ ├── pl.ts
│ │ ├── pt-BR.ts
│ │ ├── pt-PT.ts
│ │ ├── ro.ts
│ │ ├── ru.ts
│ │ ├── rw.ts
│ │ ├── sr-Cyrl.ts
│ │ ├── sr-Latn.ts
│ │ ├── sv.ts
│ │ ├── ta.ts
│ │ ├── th.ts
│ │ ├── tr.ts
│ │ ├── uk.ts
│ │ ├── uz-Cyrl.ts
│ │ ├── uz-Latn.ts
│ │ ├── vi.ts
│ │ ├── zh-Hans.ts
│ │ └── zh-Hant.ts
│ ├── numeral.ts
│ ├── numerals/
│ │ ├── arab.ts
│ │ ├── arabext.ts
│ │ ├── beng.ts
│ │ ├── latn.ts
│ │ └── mymr.ts
│ ├── parse.ts
│ ├── parser.ts
│ ├── plugin.ts
│ ├── plugins/
│ │ ├── day-of-week.ts
│ │ ├── microsecond.ts
│ │ ├── nanosecond.ts
│ │ ├── ordinal.ts
│ │ ├── quarter.ts
│ │ ├── timestamp.ts
│ │ ├── two-digit-year.ts
│ │ ├── week.ts
│ │ └── zonename.ts
│ ├── preparse.ts
│ ├── subtract.ts
│ ├── timezone.ts
│ ├── timezones/
│ │ ├── Africa/
│ │ │ ├── Abidjan.ts
│ │ │ ├── Accra.ts
│ │ │ ├── Addis_Ababa.ts
│ │ │ ├── Algiers.ts
│ │ │ ├── Asmara.ts
│ │ │ ├── Bamako.ts
│ │ │ ├── Bangui.ts
│ │ │ ├── Banjul.ts
│ │ │ ├── Bissau.ts
│ │ │ ├── Blantyre.ts
│ │ │ ├── Brazzaville.ts
│ │ │ ├── Bujumbura.ts
│ │ │ ├── Cairo.ts
│ │ │ ├── Casablanca.ts
│ │ │ ├── Ceuta.ts
│ │ │ ├── Conakry.ts
│ │ │ ├── Dakar.ts
│ │ │ ├── Dar_es_Salaam.ts
│ │ │ ├── Djibouti.ts
│ │ │ ├── Douala.ts
│ │ │ ├── El_Aaiun.ts
│ │ │ ├── Freetown.ts
│ │ │ ├── Gaborone.ts
│ │ │ ├── Harare.ts
│ │ │ ├── Johannesburg.ts
│ │ │ ├── Juba.ts
│ │ │ ├── Kampala.ts
│ │ │ ├── Khartoum.ts
│ │ │ ├── Kigali.ts
│ │ │ ├── Kinshasa.ts
│ │ │ ├── Lagos.ts
│ │ │ ├── Libreville.ts
│ │ │ ├── Lome.ts
│ │ │ ├── Luanda.ts
│ │ │ ├── Lubumbashi.ts
│ │ │ ├── Lusaka.ts
│ │ │ ├── Malabo.ts
│ │ │ ├── Maputo.ts
│ │ │ ├── Maseru.ts
│ │ │ ├── Mbabane.ts
│ │ │ ├── Mogadishu.ts
│ │ │ ├── Monrovia.ts
│ │ │ ├── Nairobi.ts
│ │ │ ├── Ndjamena.ts
│ │ │ ├── Niamey.ts
│ │ │ ├── Nouakchott.ts
│ │ │ ├── Ouagadougou.ts
│ │ │ ├── Porto-Novo.ts
│ │ │ ├── Sao_Tome.ts
│ │ │ ├── Tripoli.ts
│ │ │ ├── Tunis.ts
│ │ │ └── Windhoek.ts
│ │ ├── America/
│ │ │ ├── Adak.ts
│ │ │ ├── Anchorage.ts
│ │ │ ├── Anguilla.ts
│ │ │ ├── Antigua.ts
│ │ │ ├── Araguaina.ts
│ │ │ ├── Argentina/
│ │ │ │ ├── Buenos_Aires.ts
│ │ │ │ ├── Catamarca.ts
│ │ │ │ ├── Cordoba.ts
│ │ │ │ ├── Jujuy.ts
│ │ │ │ ├── La_Rioja.ts
│ │ │ │ ├── Mendoza.ts
│ │ │ │ ├── Rio_Gallegos.ts
│ │ │ │ ├── Salta.ts
│ │ │ │ ├── San_Juan.ts
│ │ │ │ ├── San_Luis.ts
│ │ │ │ ├── Tucuman.ts
│ │ │ │ └── Ushuaia.ts
│ │ │ ├── Aruba.ts
│ │ │ ├── Asuncion.ts
│ │ │ ├── Atikokan.ts
│ │ │ ├── Bahia.ts
│ │ │ ├── Bahia_Banderas.ts
│ │ │ ├── Barbados.ts
│ │ │ ├── Belem.ts
│ │ │ ├── Belize.ts
│ │ │ ├── Blanc-Sablon.ts
│ │ │ ├── Boa_Vista.ts
│ │ │ ├── Bogota.ts
│ │ │ ├── Boise.ts
│ │ │ ├── Cambridge_Bay.ts
│ │ │ ├── Campo_Grande.ts
│ │ │ ├── Cancun.ts
│ │ │ ├── Caracas.ts
│ │ │ ├── Cayenne.ts
│ │ │ ├── Cayman.ts
│ │ │ ├── Chicago.ts
│ │ │ ├── Chihuahua.ts
│ │ │ ├── Ciudad_Juarez.ts
│ │ │ ├── Costa_Rica.ts
│ │ │ ├── Coyhaique.ts
│ │ │ ├── Creston.ts
│ │ │ ├── Cuiaba.ts
│ │ │ ├── Curacao.ts
│ │ │ ├── Danmarkshavn.ts
│ │ │ ├── Dawson.ts
│ │ │ ├── Dawson_Creek.ts
│ │ │ ├── Denver.ts
│ │ │ ├── Detroit.ts
│ │ │ ├── Dominica.ts
│ │ │ ├── Edmonton.ts
│ │ │ ├── Eirunepe.ts
│ │ │ ├── El_Salvador.ts
│ │ │ ├── Fort_Nelson.ts
│ │ │ ├── Fortaleza.ts
│ │ │ ├── Glace_Bay.ts
│ │ │ ├── Goose_Bay.ts
│ │ │ ├── Grand_Turk.ts
│ │ │ ├── Grenada.ts
│ │ │ ├── Guadeloupe.ts
│ │ │ ├── Guatemala.ts
│ │ │ ├── Guayaquil.ts
│ │ │ ├── Guyana.ts
│ │ │ ├── Halifax.ts
│ │ │ ├── Havana.ts
│ │ │ ├── Hermosillo.ts
│ │ │ ├── Indiana/
│ │ │ │ ├── Indianapolis.ts
│ │ │ │ ├── Knox.ts
│ │ │ │ ├── Marengo.ts
│ │ │ │ ├── Petersburg.ts
│ │ │ │ ├── Tell_City.ts
│ │ │ │ ├── Vevay.ts
│ │ │ │ ├── Vincennes.ts
│ │ │ │ └── Winamac.ts
│ │ │ ├── Inuvik.ts
│ │ │ ├── Iqaluit.ts
│ │ │ ├── Jamaica.ts
│ │ │ ├── Juneau.ts
│ │ │ ├── Kentucky/
│ │ │ │ ├── Louisville.ts
│ │ │ │ └── Monticello.ts
│ │ │ ├── Kralendijk.ts
│ │ │ ├── La_Paz.ts
│ │ │ ├── Lima.ts
│ │ │ ├── Los_Angeles.ts
│ │ │ ├── Lower_Princes.ts
│ │ │ ├── Maceio.ts
│ │ │ ├── Managua.ts
│ │ │ ├── Manaus.ts
│ │ │ ├── Marigot.ts
│ │ │ ├── Martinique.ts
│ │ │ ├── Matamoros.ts
│ │ │ ├── Mazatlan.ts
│ │ │ ├── Menominee.ts
│ │ │ ├── Merida.ts
│ │ │ ├── Metlakatla.ts
│ │ │ ├── Mexico_City.ts
│ │ │ ├── Miquelon.ts
│ │ │ ├── Moncton.ts
│ │ │ ├── Monterrey.ts
│ │ │ ├── Montevideo.ts
│ │ │ ├── Montserrat.ts
│ │ │ ├── Nassau.ts
│ │ │ ├── New_York.ts
│ │ │ ├── Nome.ts
│ │ │ ├── Noronha.ts
│ │ │ ├── North_Dakota/
│ │ │ │ ├── Beulah.ts
│ │ │ │ ├── Center.ts
│ │ │ │ └── New_Salem.ts
│ │ │ ├── Nuuk.ts
│ │ │ ├── Ojinaga.ts
│ │ │ ├── Panama.ts
│ │ │ ├── Paramaribo.ts
│ │ │ ├── Phoenix.ts
│ │ │ ├── Port-au-Prince.ts
│ │ │ ├── Port_of_Spain.ts
│ │ │ ├── Porto_Velho.ts
│ │ │ ├── Puerto_Rico.ts
│ │ │ ├── Punta_Arenas.ts
│ │ │ ├── Rankin_Inlet.ts
│ │ │ ├── Recife.ts
│ │ │ ├── Regina.ts
│ │ │ ├── Resolute.ts
│ │ │ ├── Rio_Branco.ts
│ │ │ ├── Santarem.ts
│ │ │ ├── Santiago.ts
│ │ │ ├── Santo_Domingo.ts
│ │ │ ├── Sao_Paulo.ts
│ │ │ ├── Scoresbysund.ts
│ │ │ ├── Sitka.ts
│ │ │ ├── St_Barthelemy.ts
│ │ │ ├── St_Johns.ts
│ │ │ ├── St_Kitts.ts
│ │ │ ├── St_Lucia.ts
│ │ │ ├── St_Thomas.ts
│ │ │ ├── St_Vincent.ts
│ │ │ ├── Swift_Current.ts
│ │ │ ├── Tegucigalpa.ts
│ │ │ ├── Thule.ts
│ │ │ ├── Tijuana.ts
│ │ │ ├── Toronto.ts
│ │ │ ├── Tortola.ts
│ │ │ ├── Vancouver.ts
│ │ │ ├── Whitehorse.ts
│ │ │ ├── Winnipeg.ts
│ │ │ └── Yakutat.ts
│ │ ├── Antarctica/
│ │ │ ├── Casey.ts
│ │ │ ├── Davis.ts
│ │ │ ├── DumontDUrville.ts
│ │ │ ├── Macquarie.ts
│ │ │ ├── Mawson.ts
│ │ │ ├── McMurdo.ts
│ │ │ ├── Palmer.ts
│ │ │ ├── Rothera.ts
│ │ │ ├── Syowa.ts
│ │ │ ├── Troll.ts
│ │ │ └── Vostok.ts
│ │ ├── Arctic/
│ │ │ └── Longyearbyen.ts
│ │ ├── Asia/
│ │ │ ├── Aden.ts
│ │ │ ├── Almaty.ts
│ │ │ ├── Amman.ts
│ │ │ ├── Anadyr.ts
│ │ │ ├── Aqtau.ts
│ │ │ ├── Aqtobe.ts
│ │ │ ├── Ashgabat.ts
│ │ │ ├── Atyrau.ts
│ │ │ ├── Baghdad.ts
│ │ │ ├── Bahrain.ts
│ │ │ ├── Baku.ts
│ │ │ ├── Bangkok.ts
│ │ │ ├── Barnaul.ts
│ │ │ ├── Beirut.ts
│ │ │ ├── Bishkek.ts
│ │ │ ├── Brunei.ts
│ │ │ ├── Chita.ts
│ │ │ ├── Colombo.ts
│ │ │ ├── Damascus.ts
│ │ │ ├── Dhaka.ts
│ │ │ ├── Dili.ts
│ │ │ ├── Dubai.ts
│ │ │ ├── Dushanbe.ts
│ │ │ ├── Famagusta.ts
│ │ │ ├── Gaza.ts
│ │ │ ├── Hebron.ts
│ │ │ ├── Ho_Chi_Minh.ts
│ │ │ ├── Hong_Kong.ts
│ │ │ ├── Hovd.ts
│ │ │ ├── Irkutsk.ts
│ │ │ ├── Jakarta.ts
│ │ │ ├── Jayapura.ts
│ │ │ ├── Jerusalem.ts
│ │ │ ├── Kabul.ts
│ │ │ ├── Kamchatka.ts
│ │ │ ├── Karachi.ts
│ │ │ ├── Kathmandu.ts
│ │ │ ├── Khandyga.ts
│ │ │ ├── Kolkata.ts
│ │ │ ├── Krasnoyarsk.ts
│ │ │ ├── Kuala_Lumpur.ts
│ │ │ ├── Kuching.ts
│ │ │ ├── Kuwait.ts
│ │ │ ├── Macau.ts
│ │ │ ├── Magadan.ts
│ │ │ ├── Makassar.ts
│ │ │ ├── Manila.ts
│ │ │ ├── Muscat.ts
│ │ │ ├── Nicosia.ts
│ │ │ ├── Novokuznetsk.ts
│ │ │ ├── Novosibirsk.ts
│ │ │ ├── Omsk.ts
│ │ │ ├── Oral.ts
│ │ │ ├── Phnom_Penh.ts
│ │ │ ├── Pontianak.ts
│ │ │ ├── Pyongyang.ts
│ │ │ ├── Qatar.ts
│ │ │ ├── Qostanay.ts
│ │ │ ├── Qyzylorda.ts
│ │ │ ├── Riyadh.ts
│ │ │ ├── Sakhalin.ts
│ │ │ ├── Samarkand.ts
│ │ │ ├── Seoul.ts
│ │ │ ├── Shanghai.ts
│ │ │ ├── Singapore.ts
│ │ │ ├── Srednekolymsk.ts
│ │ │ ├── Taipei.ts
│ │ │ ├── Tashkent.ts
│ │ │ ├── Tbilisi.ts
│ │ │ ├── Tehran.ts
│ │ │ ├── Thimphu.ts
│ │ │ ├── Tokyo.ts
│ │ │ ├── Tomsk.ts
│ │ │ ├── Ulaanbaatar.ts
│ │ │ ├── Urumqi.ts
│ │ │ ├── Ust-Nera.ts
│ │ │ ├── Vientiane.ts
│ │ │ ├── Vladivostok.ts
│ │ │ ├── Yakutsk.ts
│ │ │ ├── Yangon.ts
│ │ │ ├── Yekaterinburg.ts
│ │ │ └── Yerevan.ts
│ │ ├── Atlantic/
│ │ │ ├── Azores.ts
│ │ │ ├── Bermuda.ts
│ │ │ ├── Canary.ts
│ │ │ ├── Cape_Verde.ts
│ │ │ ├── Faroe.ts
│ │ │ ├── Madeira.ts
│ │ │ ├── Reykjavik.ts
│ │ │ ├── South_Georgia.ts
│ │ │ ├── St_Helena.ts
│ │ │ └── Stanley.ts
│ │ ├── Australia/
│ │ │ ├── Adelaide.ts
│ │ │ ├── Brisbane.ts
│ │ │ ├── Broken_Hill.ts
│ │ │ ├── Darwin.ts
│ │ │ ├── Eucla.ts
│ │ │ ├── Hobart.ts
│ │ │ ├── Lindeman.ts
│ │ │ ├── Lord_Howe.ts
│ │ │ ├── Melbourne.ts
│ │ │ ├── Perth.ts
│ │ │ └── Sydney.ts
│ │ ├── Europe/
│ │ │ ├── Amsterdam.ts
│ │ │ ├── Andorra.ts
│ │ │ ├── Astrakhan.ts
│ │ │ ├── Athens.ts
│ │ │ ├── Belgrade.ts
│ │ │ ├── Berlin.ts
│ │ │ ├── Bratislava.ts
│ │ │ ├── Brussels.ts
│ │ │ ├── Bucharest.ts
│ │ │ ├── Budapest.ts
│ │ │ ├── Busingen.ts
│ │ │ ├── Chisinau.ts
│ │ │ ├── Copenhagen.ts
│ │ │ ├── Dublin.ts
│ │ │ ├── Gibraltar.ts
│ │ │ ├── Guernsey.ts
│ │ │ ├── Helsinki.ts
│ │ │ ├── Isle_of_Man.ts
│ │ │ ├── Istanbul.ts
│ │ │ ├── Jersey.ts
│ │ │ ├── Kaliningrad.ts
│ │ │ ├── Kirov.ts
│ │ │ ├── Kyiv.ts
│ │ │ ├── Lisbon.ts
│ │ │ ├── Ljubljana.ts
│ │ │ ├── London.ts
│ │ │ ├── Luxembourg.ts
│ │ │ ├── Madrid.ts
│ │ │ ├── Malta.ts
│ │ │ ├── Mariehamn.ts
│ │ │ ├── Minsk.ts
│ │ │ ├── Monaco.ts
│ │ │ ├── Moscow.ts
│ │ │ ├── Oslo.ts
│ │ │ ├── Paris.ts
│ │ │ ├── Podgorica.ts
│ │ │ ├── Prague.ts
│ │ │ ├── Riga.ts
│ │ │ ├── Rome.ts
│ │ │ ├── Samara.ts
│ │ │ ├── San_Marino.ts
│ │ │ ├── Sarajevo.ts
│ │ │ ├── Saratov.ts
│ │ │ ├── Simferopol.ts
│ │ │ ├── Skopje.ts
│ │ │ ├── Sofia.ts
│ │ │ ├── Stockholm.ts
│ │ │ ├── Tallinn.ts
│ │ │ ├── Tirane.ts
│ │ │ ├── Ulyanovsk.ts
│ │ │ ├── Vaduz.ts
│ │ │ ├── Vatican.ts
│ │ │ ├── Vienna.ts
│ │ │ ├── Vilnius.ts
│ │ │ ├── Volgograd.ts
│ │ │ ├── Warsaw.ts
│ │ │ ├── Zagreb.ts
│ │ │ └── Zurich.ts
│ │ ├── Indian/
│ │ │ ├── Antananarivo.ts
│ │ │ ├── Chagos.ts
│ │ │ ├── Christmas.ts
│ │ │ ├── Cocos.ts
│ │ │ ├── Comoro.ts
│ │ │ ├── Kerguelen.ts
│ │ │ ├── Mahe.ts
│ │ │ ├── Maldives.ts
│ │ │ ├── Mauritius.ts
│ │ │ ├── Mayotte.ts
│ │ │ └── Reunion.ts
│ │ └── Pacific/
│ │ ├── Apia.ts
│ │ ├── Auckland.ts
│ │ ├── Bougainville.ts
│ │ ├── Chatham.ts
│ │ ├── Chuuk.ts
│ │ ├── Easter.ts
│ │ ├── Efate.ts
│ │ ├── Fakaofo.ts
│ │ ├── Fiji.ts
│ │ ├── Funafuti.ts
│ │ ├── Galapagos.ts
│ │ ├── Gambier.ts
│ │ ├── Guadalcanal.ts
│ │ ├── Guam.ts
│ │ ├── Honolulu.ts
│ │ ├── Kanton.ts
│ │ ├── Kiritimati.ts
│ │ ├── Kosrae.ts
│ │ ├── Kwajalein.ts
│ │ ├── Majuro.ts
│ │ ├── Marquesas.ts
│ │ ├── Midway.ts
│ │ ├── Nauru.ts
│ │ ├── Niue.ts
│ │ ├── Norfolk.ts
│ │ ├── Noumea.ts
│ │ ├── Pago_Pago.ts
│ │ ├── Palau.ts
│ │ ├── Pitcairn.ts
│ │ ├── Pohnpei.ts
│ │ ├── Port_Moresby.ts
│ │ ├── Rarotonga.ts
│ │ ├── Saipan.ts
│ │ ├── Tahiti.ts
│ │ ├── Tarawa.ts
│ │ ├── Tongatapu.ts
│ │ ├── Wake.ts
│ │ └── Wallis.ts
│ ├── transform.ts
│ ├── utils.ts
│ ├── zone.ts
│ └── zonenames.ts
├── tests/
│ ├── addDays.spec.ts
│ ├── addHours.spec.ts
│ ├── addMilliseconds.spec.ts
│ ├── addMinutes.spec.ts
│ ├── addMonths.spec.ts
│ ├── addSeconds.spec.ts
│ ├── addYears.spec.ts
│ ├── compile.spec.ts
│ ├── duration.spec.ts
│ ├── format.spec.ts
│ ├── isValid.spec.ts
│ ├── locales/
│ │ ├── ar.spec.ts
│ │ ├── az.spec.ts
│ │ ├── bn.spec.ts
│ │ ├── cs.spec.ts
│ │ ├── da.spec.ts
│ │ ├── de.spec.ts
│ │ ├── el.spec.ts
│ │ ├── en.spec.ts
│ │ ├── es.spec.ts
│ │ ├── fa.spec.ts
│ │ ├── fi.spec.ts
│ │ ├── fr.spec.ts
│ │ ├── he.spec.ts
│ │ ├── hi.spec.ts
│ │ ├── hu.spec.ts
│ │ ├── id.spec.ts
│ │ ├── it.spec.ts
│ │ ├── ja.spec.ts
│ │ ├── ko.spec.ts
│ │ ├── ms.spec.ts
│ │ ├── my.spec.ts
│ │ ├── nl.spec.ts
│ │ ├── no.spec.ts
│ │ ├── pl.spec.ts
│ │ ├── pt-BR.spec.ts
│ │ ├── pt-PT.spec.ts
│ │ ├── ro.spec.ts
│ │ ├── ru.spec.ts
│ │ ├── rw.spec.ts
│ │ ├── sr-Cyrl.spec.ts
│ │ ├── sr-Latn.spec.ts
│ │ ├── sv.spec.ts
│ │ ├── ta.spec.ts
│ │ ├── th.spec.ts
│ │ ├── tr.spec.ts
│ │ ├── uk.spec.ts
│ │ ├── uz-Cyrl.spec.ts
│ │ ├── uz-Latn.spec.ts
│ │ ├── vi.spec.ts
│ │ ├── zh-Hans.spec.ts
│ │ └── zh-Hant.spec.ts
│ ├── numerals/
│ │ ├── arab.spec.ts
│ │ ├── arabext.spec.ts
│ │ ├── beng.spec.ts
│ │ ├── latn.spec.ts
│ │ └── mymr.spec.ts
│ ├── parse.spec.ts
│ ├── plugins/
│ │ ├── microsecond.spec.ts
│ │ ├── nanosecond.spec.ts
│ │ ├── ordinal.spec.ts
│ │ ├── quarter.spec.ts
│ │ ├── timestamp.spec.ts
│ │ ├── two-digit-year.spec.ts
│ │ ├── week.spec.ts
│ │ └── zonename.spec.ts
│ ├── preparse.spec.ts
│ ├── subtract.spec.ts
│ ├── timezones/
│ │ └── timezones.spec.ts
│ ├── transform.spec.ts
│ └── utils.spec.ts
├── tools/
│ ├── locale.ts
│ ├── timezone.ts
│ └── zonename.ts
├── tsconfig.json
└── vitest.config.ts
================================================
FILE CONTENTS
================================================
================================================
FILE: .editorconfig
================================================
root = true
[*.{js,ts}]
charset = utf-8
indent_size = 2
indent_style = space
trim_trailing_whitespace = true
================================================
FILE: .github/workflows/deploy-docs.yml
================================================
name: Deploy Starlight site to GitHub Pages
on:
push:
branches:
- master
paths:
- 'docs/**'
- 'astro.config.mjs'
- '.github/workflows/deploy-docs.yml'
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 'lts/*'
cache: npm
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Install dependencies
run: npm ci
- name: Build with Astro
run: npm run docs:build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: pages
deploy:
needs: build
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
================================================
FILE: .github/workflows/test.yml
================================================
name: CI
on:
push:
branches: [ master, develop ]
pull_request:
branches: [ master, develop ]
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 'lts/*'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run linter
run: npm run lint
- name: Run tests
run: npm test
coverage:
runs-on: ubuntu-latest
if: github.event_name == 'push'
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 'lts/*'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run tests with coverage
run: npm run test:coverage
- name: Read coverage summary
id: coverage
run: |
echo "pct=$(jq '.total.lines.pct' coverage/coverage-summary.json)" >> $GITHUB_OUTPUT
- name: Create badges directory
run: mkdir -p .github/badges
- name: Generate coverage badge
uses: emibcn/badge-action@v2.0.3
with:
label: 'coverage'
status: ${{ steps.coverage.outputs.pct }}%
color: ${{ fromJSON(steps.coverage.outputs.pct) >= 80 && 'green' || fromJSON(steps.coverage.outputs.pct) >= 60 && 'yellow' || 'red' }}
path: .github/badges/coverage.svg
- name: Commit coverage badge
run: |
git config --local user.email "action@github.com"
git config --local user.name "GitHub Action"
git add .github/badges/coverage.svg
git diff --staged --quiet || git commit -m "Update coverage badge"
git push
- name: Upload coverage reports
uses: actions/upload-artifact@v4
with:
name: coverage-report
path: coverage/
================================================
FILE: .gitignore
================================================
.DS_Store
.vscode/
cache/
coverage/
dist/
pages/
node_modules/
# Astro
.astro/
================================================
FILE: LICENSE
================================================
The MIT License (MIT)
Copyright (c) 2015 KNOWLEDGECODE
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================
FILE: README.md
================================================
# date-and-time
<div align="center">
<img src="https://raw.githubusercontent.com/knowledgecode/date-and-time/refs/heads/master/logo.png" alt="date-and-time" width="256">
</div>
<div align="center">
[](https://github.com/knowledgecode/date-and-time/actions/workflows/test.yml)
[](https://github.com/knowledgecode/date-and-time/actions/workflows/test.yml)
[](https://www.npmjs.com/package/date-and-time)
</div>
The simplest, most intuitive date and time library.
## Installation
```shell
npm install date-and-time
```
### ES Modules (Recommended)
```typescript
import { format } from 'date-and-time';
format(new Date(), 'ddd, MMM DD YYYY');
// => Wed, Jul 09 2025
```
### CommonJS
```typescript
const { format } = require('date-and-time');
format(new Date(), 'ddd, MMM DD YYYY');
// => Wed, Jul 09 2025
```
## CDN Usage
### Via jsDelivr
```html
<script type="module">
import { format } from 'https://cdn.jsdelivr.net/npm/date-and-time/dist/index.js';
console.log(format(new Date(), 'YYYY/MM/DD'));
</script>
```
### Via unpkg
```html
<script type="module">
import { format } from 'https://unpkg.com/date-and-time/dist/index.js';
console.log(format(new Date(), 'YYYY/MM/DD'));
</script>
```
## Migration
Version `4.x` has been completely rewritten in TypeScript and some features from `3.x` are no longer compatible. The main changes are as follows:
- The `timezone` and `timespan` plugins have been integrated into the main library
- Tree shaking is now supported
- Supports `ES2021` and no longer supports older browsers
For details, please refer to [migration.md](https://github.com/knowledgecode/date-and-time/blob/master/docs/migration.md).
## API
For comprehensive documentation and examples, visit: **[GitHub Pages](https://knowledgecode.github.io/date-and-time/)**
## License
MIT
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
================================================
FILE: astro.config.mjs
================================================
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
outDir: './pages',
srcDir: './docs',
site: 'https://knowledgecode.github.io',
base: '/date-and-time',
trailingSlash: 'never',
devToolbar: {
enabled: false,
},
markdown: {
shikiConfig: {
themes: {
light: 'github-light',
dark: 'github-dark',
},
},
},
integrations: [
starlight({
customCss: [
'./docs/styles/custom.css',
],
title: 'date-and-time',
description: 'The simplest, most intuitive date and time library',
logo: {
src: './docs/assets/logo.png',
alt: 'date-and-time',
},
social: [
{ icon: 'github', label: 'GitHub', href: 'https://github.com/knowledgecode/date-and-time' },
{ icon: 'npm', label: 'npm', href: 'https://www.npmjs.com/package/date-and-time' },
],
sidebar: [
{
label: 'Getting Started',
items: [
{ label: 'Introduction', link: '/guide' },
{ label: 'Installation', link: '/guide/installation' },
{ label: 'Quick Start', link: '/guide/quick-start' },
],
},
{
label: 'API Reference',
collapsed: true,
items: [
{ label: 'Overview', link: '/api' },
{
label: 'Core Functions',
items: [
{ label: 'format()', link: '/api/format' },
{ label: 'parse()', link: '/api/parse' },
{ label: 'compile()', link: '/api/compile' },
{ label: 'preparse()', link: '/api/preparse' },
{ label: 'isValid()', link: '/api/isvalid' },
{ label: 'transform()', link: '/api/transform' },
{ label: 'addYears()', link: '/api/addyears' },
{ label: 'addMonths()', link: '/api/addmonths' },
{ label: 'addDays()', link: '/api/adddays' },
{ label: 'addHours()', link: '/api/addhours' },
{ label: 'addMinutes()', link: '/api/addminutes' },
{ label: 'addSeconds()', link: '/api/addseconds' },
{ label: 'addMilliseconds()', link: '/api/addmilliseconds' },
{ label: 'subtract()', link: '/api/subtract' },
],
},
{
label: 'Utility Functions',
items: [
{ label: 'isLeapYear()', link: '/api/utils/isleapyear' },
{ label: 'isSameDay()', link: '/api/utils/issameday' },
{ label: 'getDaysInMonth()', link: '/api/utils/getdaysinmonth' },
{ label: 'getISOWeekYear()', link: '/api/utils/getisoweekyear' },
{ label: 'getISOWeek()', link: '/api/utils/getisoweek' },
],
},
],
},
{ label: 'Locales', link: '/locales' },
{ label: 'Timezones', link: '/timezones' },
{ label: 'Plugins', link: '/plugins' },
{ label: 'Migration Guide', link: '/migration' },
],
}),
],
});
================================================
FILE: docs/api/addDays.md
================================================
---
title: addDays()
---
Adds or subtracts days from a Date object. Handles month boundaries, leap years, and daylight saving time transitions properly.
## Syntax
```typescript
addDays(dateObj, days[, timeZone])
```
### Parameters
| Parameter | Type | Required | Description |
|------------|----------------------|----------|---------------------------------------------------------|
| `dateObj` | `Date` | Yes | The base Date object |
| `days` | `number` | Yes | Number of days to add (positive) or subtract (negative) |
| `timeZone` | `TimeZone \| string` | No | Timezone for the calculation |
### Returns
`Date` - A new Date object with the specified number of days added or subtracted
## Basic Examples
### Adding and Subtracting Days
```typescript
import { addDays } from 'date-and-time';
const date = new Date(2024, 7, 15); // August 15, 2024
// Add days
const future = addDays(date, 10);
console.log(future); // August 25, 2024
// Subtract days
const past = addDays(date, -5);
console.log(past); // August 10, 2024
```
### Daylight Saving Time Aware Calculations
```typescript
import { addDays } from 'date-and-time';
// Working with specific timezones
const nyDate = new Date('2024-03-10T05:00:00Z'); // March 10, 2024 05:00 UTC (DST transition day)
// Add 30 days in New York timezone
const futureNY = addDays(nyDate, 30, 'America/New_York');
console.log(futureNY); // April 9, 2024 04:00 UTC (EDT, DST adjusted)
// UTC calculation for comparison
const futureUTC = addDays(nyDate, 30, 'UTC');
console.log(futureUTC); // April 9, 2024 05:00 UTC (same time, no DST adjustment)
```
## Use Cases
### Work Day Calculations
```typescript
function addBusinessDays(date: Date, businessDays: number): Date {
let result = new Date(date);
let daysToAdd = businessDays;
while (daysToAdd > 0) {
result = addDays(result, 1);
const dayOfWeek = result.getDay();
// Skip weekends (0 = Sunday, 6 = Saturday)
if (dayOfWeek !== 0 && dayOfWeek !== 6) {
daysToAdd--;
}
}
return result;
}
const friday = new Date(2024, 7, 23); // August 23, 2024 (Friday)
const nextBusinessDay = addBusinessDays(friday, 1);
console.log(nextBusinessDay); // August 26, 2024 (Monday)
```
### Date Range Generation
```typescript
function generateDateRange(startDate: Date, endDate: Date): Date[] {
const dates: Date[] = [];
let currentDate = new Date(startDate);
while (currentDate <= endDate) {
dates.push(new Date(currentDate));
currentDate = addDays(currentDate, 1);
}
return dates;
}
const start = new Date(2024, 7, 28); // August 28, 2024
const end = new Date(2024, 8, 3); // September 3, 2024
const dateRange = generateDateRange(start, end);
console.log(dateRange);
// [Aug 28, Aug 29, Aug 30, Aug 31, Sep 1, Sep 2, Sep 3]
```
## Immutability
`addDays()` does not modify the original Date object:
```typescript
const originalDate = new Date(2024, 7, 15);
const modifiedDate = addDays(originalDate, 10);
console.log(originalDate); // August 15, 2024 (unchanged)
console.log(modifiedDate); // August 25, 2024 (new object)
```
## See Also
- [`addYears()`](./addYears) - Add/subtract years
- [`addMonths()`](./addMonths) - Add/subtract months
- [`addHours()`](./addHours) - Add/subtract hours
- [`addMinutes()`](./addMinutes) - Add/subtract minutes
- [`addSeconds()`](./addSeconds) - Add/subtract seconds
- [`addMilliseconds()`](./addMilliseconds) - Add/subtract milliseconds
- [`subtract()`](./subtract) - Calculate differences with Duration objects
================================================
FILE: docs/api/addHours.md
================================================
---
title: addHours()
---
Adds or subtracts hours from a Date object.
## Syntax
```typescript
addHours(dateObj, hours)
```
### Parameters
| Parameter | Type | Required | Description |
|-----------|----------|----------|----------------------------------------------------------|
| `dateObj` | `Date` | Yes | The base Date object |
| `hours` | `number` | Yes | Number of hours to add (positive) or subtract (negative) |
### Returns
`Date` - A new Date object with the specified number of hours added or subtracted
## Basic Examples
### Adding and Subtracting Hours
```typescript
import { addHours } from 'date-and-time';
const date = new Date(2024, 7, 15, 14, 30, 45); // August 15, 2024 14:30:45
// Add hours
const future = addHours(date, 6);
console.log(future); // August 15, 2024 20:30:45
// Subtract hours
const past = addHours(date, -3);
console.log(past); // August 15, 2024 11:30:45
```
## Use Cases
### Work Hours Calculation
```typescript
function addWorkingHours(startDate: Date, workHours: number): Date {
// Assuming 8-hour work days, 5 days a week
const hoursPerDay = 8;
const result = new Date(startDate);
let remainingHours = workHours;
while (remainingHours > 0) {
const dayOfWeek = result.getDay();
// Skip weekends
if (dayOfWeek === 0 || dayOfWeek === 6) {
result.setDate(result.getDate() + 1);
continue;
}
const hoursToAdd = Math.min(remainingHours, hoursPerDay);
const newTime = addHours(result, hoursToAdd);
result.setTime(newTime.getTime());
remainingHours -= hoursToAdd;
if (remainingHours > 0) {
// Move to next day, reset to start of work day
result.setDate(result.getDate() + 1);
result.setHours(9, 0, 0, 0); // 9 AM start
}
}
return result;
}
const projectStart = new Date(2024, 7, 15, 9, 0); // August 15, 2024 09:00
const completion = addWorkingHours(projectStart, 24); // 24 working hours
console.log(completion);
```
### Shift Scheduling
```typescript
function generateShiftSchedule(startDate: Date, shiftHours: number, numberOfShifts: number): Date[] {
const shifts: Date[] = [];
let currentStart = new Date(startDate);
for (let i = 0; i < numberOfShifts; i++) {
shifts.push(new Date(currentStart));
currentStart = addHours(currentStart, shiftHours);
}
return shifts;
}
const firstShift = new Date(2024, 7, 15, 6, 0); // August 15, 2024 06:00
const schedule = generateShiftSchedule(firstShift, 8, 5); // 5 shifts of 8 hours each
console.log(schedule);
// [
// August 15, 2024 06:00, // Shift 1
// August 15, 2024 14:00, // Shift 2
// August 15, 2024 22:00, // Shift 3
// August 16, 2024 06:00, // Shift 4
// August 16, 2024 14:00 // Shift 5
// ]
```
## Immutability
`addHours()` does not modify the original Date object:
```typescript
const originalDate = new Date(2024, 7, 15, 14, 30);
const modifiedDate = addHours(originalDate, 5);
console.log(originalDate); // August 15, 2024 14:30:00 (unchanged)
console.log(modifiedDate); // August 15, 2024 19:30:00 (new object)
```
## See Also
- [`addYears()`](./addYears) - Add/subtract years
- [`addMonths()`](./addMonths) - Add/subtract months
- [`addDays()`](./addDays) - Add/subtract days
- [`addMinutes()`](./addMinutes) - Add/subtract minutes
- [`addSeconds()`](./addSeconds) - Add/subtract seconds
- [`addMilliseconds()`](./addMilliseconds) - Add/subtract milliseconds
- [`subtract()`](./subtract) - Calculate differences with Duration objects
================================================
FILE: docs/api/addMilliseconds.md
================================================
---
title: addMilliseconds()
---
Adds or subtracts milliseconds from a Date object.
## Syntax
```typescript
addMilliseconds(dateObj, milliseconds)
```
### Parameters
| Parameter | Type | Required | Description |
|----------------|----------|----------|-----------------------------------------------------------------|
| `dateObj` | `Date` | Yes | The base Date object |
| `milliseconds` | `number` | Yes | Number of milliseconds to add (positive) or subtract (negative) |
### Returns
`Date` - A new Date object with the specified number of milliseconds added or subtracted
## Basic Examples
### Adding and Subtracting Milliseconds
```typescript
import { addMilliseconds } from 'date-and-time';
const date = new Date(2024, 7, 15, 14, 30, 45, 123); // August 15, 2024 14:30:45.123
// Add milliseconds
const future = addMilliseconds(date, 500);
console.log(future); // August 15, 2024 14:30:45.623
// Subtract milliseconds
const past = addMilliseconds(date, -200);
console.log(past); // August 15, 2024 14:30:44.923
```
## Use Cases
### High-Precision Timing
```typescript
class PrecisionTimer {
private startTime: Date
start(): void {
this.startTime = new Date();
}
elapsedMs(): number {
if (!this.startTime) {
return 0;
}
return Date.now() - this.startTime.getTime();
}
addPreciseDelay(baseTime: Date, delayMs: number): Date {
return addMilliseconds(baseTime, delayMs);
}
scheduleNextExecution(intervalMs: number): Date {
return addMilliseconds(new Date(), intervalMs);
}
}
const timer = new PrecisionTimer();
timer.start();
// ... perform operations ...
console.log(`Operation took: ${timer.elapsedMs()}ms`);
const nextRun = timer.scheduleNextExecution(150); // Schedule 150ms from now
console.log(`Next execution at: ${nextRun.toISOString()}`);
```
### Animation Frame Scheduling
```typescript
function createAnimationSchedule(startTime: Date, frameRate: number, duration: number) {
const frameInterval = 1000 / frameRate; // ms per frame
const totalFrames = Math.floor((duration * 1000) / frameInterval);
const schedule: { frame: number, time: Date }[] = [];
for (let frame = 0; frame < totalFrames; frame++) {
const frameTime = addMilliseconds(startTime, frame * frameInterval);
schedule.push({ frame, time: frameTime });
}
return schedule;
}
const animationStart = new Date(); // Animation starts now
const frames = createAnimationSchedule(animationStart, 60, 2); // 60 FPS for 2 seconds
console.log(`Animation has ${frames.length} frames`);
console.log('First 5 frames:');
frames.slice(0, 5).forEach(f => {
console.log(`Frame ${f.frame}: ${f.time.toISOString()}`);
});
```
## Immutability
`addMilliseconds()` does not modify the original Date object:
```typescript
const originalDate = new Date(2024, 7, 15, 14, 30, 45, 123);
const modifiedDate = addMilliseconds(originalDate, 500);
console.log(originalDate); // August 15, 2024 14:30:45.123 (unchanged)
console.log(modifiedDate); // August 15, 2024 14:30:45.623 (new object)
```
## See Also
- [`addYears()`](./addYears) - Add/subtract years
- [`addMonths()`](./addMonths) - Add/subtract months
- [`addDays()`](./addDays) - Add/subtract days
- [`addHours()`](./addHours) - Add/subtract hours
- [`addMinutes()`](./addMinutes) - Add/subtract minutes
- [`addSeconds()`](./addSeconds) - Add/subtract seconds
- [`subtract()`](./subtract) - Calculate differences with Duration objects
================================================
FILE: docs/api/addMinutes.md
================================================
---
title: addMinutes()
---
Adds or subtracts minutes from a Date object.
## Syntax
```typescript
addMinutes(dateObj, minutes)
```
### Parameters
| Parameter | Type | Required | Description |
|-----------|----------|----------|------------------------------------------------------------|
| `dateObj` | `Date` | Yes | The base Date object |
| `minutes` | `number` | Yes | Number of minutes to add (positive) or subtract (negative) |
### Returns
`Date` - A new Date object with the specified number of minutes added or subtracted
## Basic Examples
### Adding and Subtracting Minutes
```typescript
import { addMinutes } from 'date-and-time';
const date = new Date(2024, 7, 15, 14, 30, 45); // August 15, 2024 14:30:45
// Add minutes
const future = addMinutes(date, 25);
console.log(future); // August 15, 2024 14:55:45
// Subtract minutes
const past = addMinutes(date, -15);
console.log(past); // August 15, 2024 14:15:45
```
## Use Cases
### Appointment Scheduling
```typescript
function scheduleAppointments(startTime: Date, appointmentLength: number, count: number): Date[] {
const appointments: Date[] = [];
let currentTime = new Date(startTime);
for (let i = 0; i < count; i++) {
appointments.push(new Date(currentTime));
currentTime = addMinutes(currentTime, appointmentLength);
}
return appointments;
}
const firstAppointment = new Date(2024, 7, 15, 9, 0); // August 15, 2024 09:00
const schedule = scheduleAppointments(firstAppointment, 30, 6); // 6 appointments, 30 min each
console.log(schedule);
// [
// August 15, 2024 09:00,
// August 15, 2024 09:30,
// August 15, 2024 10:00,
// August 15, 2024 10:30,
// August 15, 2024 11:00,
// August 15, 2024 11:30
// ]
```
### Pomodoro Timer
```typescript
class PomodoroTimer {
private workMinutes = 25;
private shortBreakMinutes = 5;
private longBreakMinutes = 15;
createSession(startTime: Date, cycles: number = 4) {
const schedule: { type: string, start: Date, end: Date }[] = [];
let currentTime = new Date(startTime);
for (let i = 0; i < cycles; i++) {
// Work session
const workEnd = addMinutes(currentTime, this.workMinutes);
schedule.push({
type: 'work',
start: new Date(currentTime),
end: workEnd
});
currentTime = workEnd;
// Break session
const breakMinutes = (i === cycles - 1) ? this.longBreakMinutes : this.shortBreakMinutes;
const breakEnd = addMinutes(currentTime, breakMinutes);
schedule.push({
type: i === cycles - 1 ? 'long-break' : 'short-break',
start: new Date(currentTime),
end: breakEnd
});
currentTime = breakEnd;
}
return schedule;
}
}
const pomodoro = new PomodoroTimer();
const session = pomodoro.createSession(new Date(2024, 7, 15, 9, 0));
console.log(session);
```
## Immutability
`addMinutes()` does not modify the original Date object:
```typescript
const originalDate = new Date(2024, 7, 15, 14, 30);
const modifiedDate = addMinutes(originalDate, 45);
console.log(originalDate); // August 15, 2024 14:30:00 (unchanged)
console.log(modifiedDate); // August 15, 2024 15:15:00 (new object)
```
## See Also
- [`addYears()`](./addYears) - Add/subtract years
- [`addMonths()`](./addMonths) - Add/subtract months
- [`addDays()`](./addDays) - Add/subtract days
- [`addHours()`](./addHours) - Add/subtract hours
- [`addSeconds()`](./addSeconds) - Add/subtract seconds
- [`addMilliseconds()`](./addMilliseconds) - Add/subtract milliseconds
- [`subtract()`](./subtract) - Calculate differences with Duration objects
================================================
FILE: docs/api/addMonths.md
================================================
---
title: addMonths()
---
Adds or subtracts months from a Date object. Handles month boundaries, leap years, and varying month lengths appropriately.
## Syntax
```typescript
addMonths(dateObj, months[, timeZone])
```
### Parameters
| Parameter | Type | Required | Description |
|------------|----------------------|----------|-----------------------------------------------------------|
| `dateObj` | `Date` | Yes | The base Date object |
| `months` | `number` | Yes | Number of months to add (positive) or subtract (negative) |
| `timeZone` | `TimeZone \| string` | No | Timezone for the calculation |
### Returns
`Date` - A new Date object with the specified number of months added or subtracted
## Basic Examples
### Adding and Subtracting Months
```typescript
import { addMonths } from 'date-and-time';
const date = new Date(2024, 0, 15); // January 15, 2024
// Add months
const future = addMonths(date, 6);
console.log(future); // July 15, 2024
// Subtract months
const past = addMonths(date, -3);
console.log(past); // October 15, 2023
```
### Daylight Saving Time Aware Calculations
```typescript
import { addMonths } from 'date-and-time';
// Working with specific timezones
const nyDate = new Date('2024-03-10T05:00:00Z'); // March 10, 2024 05:00 UTC (DST transition day)
// Add 6 months in New York timezone
const futureNY = addMonths(nyDate, 6, 'America/New_York');
console.log(futureNY); // September 10, 2024 04:00 UTC (EDT, DST adjusted)
// UTC calculation for comparison
const futureUTC = addMonths(nyDate, 6, 'UTC');
console.log(futureUTC); // September 10, 2024 05:00 UTC (same time, no DST adjustment)
```
## Use Cases
### Payment Due Dates
```typescript
function calculatePaymentSchedule(startDate: Date, months: number): Date[] {
const schedule: Date[] = [];
for (let i = 1; i <= months; i++) {
schedule.push(addMonths(startDate, i));
}
return schedule;
}
const loanStart = new Date(2024, 0, 15); // January 15, 2024
const payments = calculatePaymentSchedule(loanStart, 12);
console.log(payments);
// [February 15, March 15, April 15, ..., January 15]
```
### Quarterly Reports
```typescript
function getQuarterlyDates(year: number): Date[] {
const q1 = new Date(year, 0, 1); // January 1
return [
q1, // Q1
addMonths(q1, 3), // Q2 - April 1
addMonths(q1, 6), // Q3 - July 1
addMonths(q1, 9) // Q4 - October 1
];
}
const quarters2024 = getQuarterlyDates(2024);
console.log(quarters2024);
```
## Edge Cases and Behavior
### End-of-Month Dates
```typescript
const endOfMonth = new Date(2024, 0, 31); // January 31, 2024
console.log(addMonths(endOfMonth, 1)); // February 29, 2024 (Feb has 29 days)
console.log(addMonths(endOfMonth, 2)); // March 31, 2024 (back to 31st)
console.log(addMonths(endOfMonth, 3)); // April 30, 2024 (April has 30 days)
```
### February Edge Cases
```typescript
// February 28 in non-leap year
const feb28 = new Date(2025, 1, 28); // February 28, 2025
console.log(addMonths(feb28, 12)); // February 28, 2026
console.log(addMonths(feb28, -12)); // February 28, 2024 (leap year, but stays at 28)
// February 29 in leap year
const feb29 = new Date(2024, 1, 29); // February 29, 2024
console.log(addMonths(feb29, 1)); // March 29, 2024
console.log(addMonths(feb29, -1)); // January 29, 2024
```
## Immutability
`addMonths()` does not modify the original Date object:
```typescript
const originalDate = new Date(2024, 0, 15);
const modifiedDate = addMonths(originalDate, 6);
console.log(originalDate); // January 15, 2024 (unchanged)
console.log(modifiedDate); // July 15, 2024 (new object)
```
## See Also
- [`addYears()`](./addYears) - Add/subtract years
- [`addDays()`](./addDays) - Add/subtract days
- [`addHours()`](./addHours) - Add/subtract hours
- [`addMinutes()`](./addMinutes) - Add/subtract minutes
- [`addSeconds()`](./addSeconds) - Add/subtract seconds
- [`addMilliseconds()`](./addMilliseconds) - Add/subtract milliseconds
- [`subtract()`](./subtract) - Calculate differences with Duration objects
================================================
FILE: docs/api/addSeconds.md
================================================
---
title: addSeconds()
---
Adds or subtracts seconds from a Date object.
## Syntax
```typescript
addSeconds(dateObj, seconds)
```
### Parameters
| Parameter | Type | Required | Description |
|-----------|----------|----------|------------------------------------------------------------|
| `dateObj` | `Date` | Yes | The base Date object |
| `seconds` | `number` | Yes | Number of seconds to add (positive) or subtract (negative) |
### Returns
`Date` - A new Date object with the specified number of seconds added or subtracted
## Basic Examples
### Adding and Subtracting Seconds
```typescript
import { addSeconds } from 'date-and-time';
const date = new Date(2024, 7, 15, 14, 30, 45, 123); // August 15, 2024 14:30:45.123
// Add seconds
const future = addSeconds(date, 30);
console.log(future); // August 15, 2024 14:31:15.123
// Subtract seconds
const past = addSeconds(date, -20);
console.log(past); // August 15, 2024 14:30:25.123
```
## Use Cases
### Countdown Timers
```typescript
function createCountdown(duration: number): { start: Date, end: Date, remaining: () => number } {
const start = new Date();
const end = addSeconds(start, duration);
return {
start,
end,
remaining: () => Math.max(0, Math.floor((end.getTime() - Date.now()) / 1000))
};
}
const countdown = createCountdown(300); // 5 minute countdown
console.log(`Countdown ends at: ${countdown.end.toLocaleTimeString()}`);
console.log(`Time remaining: ${countdown.remaining()} seconds`);
// Use in a timer
const updateCountdown = () => {
const remaining = countdown.remaining();
if (remaining > 0) {
console.log(`${remaining} seconds left`);
setTimeout(updateCountdown, 1000);
} else {
console.log('Time up!');
}
};
updateCountdown();
```
### Precise Time Intervals
```typescript
function generateTimeIntervals(startTime: Date, intervalSeconds: number, count: number): Date[] {
const intervals: Date[] = [];
let currentTime = new Date(startTime);
for (let i = 0; i < count; i++) {
intervals.push(new Date(currentTime));
currentTime = addSeconds(currentTime, intervalSeconds);
}
return intervals;
}
const start = new Date(2024, 7, 15, 12, 0, 0); // August 15, 2024 12:00:00
const intervals = generateTimeIntervals(start, 15, 8); // Every 15 seconds, 8 times
console.log(intervals);
// [12:00:00, 12:00:15, 12:00:30, 12:00:45, 12:01:00, 12:01:15, 12:01:30, 12:01:45]
```
## Immutability
`addSeconds()` does not modify the original Date object:
```typescript
const originalDate = new Date(2024, 7, 15, 14, 30, 45);
const modifiedDate = addSeconds(originalDate, 120);
console.log(originalDate); // August 15, 2024 14:30:45 (unchanged)
console.log(modifiedDate); // August 15, 2024 14:32:45 (new object);
```
## See Also
- [`addYears()`](./addYears) - Add/subtract years
- [`addMonths()`](./addMonths) - Add/subtract months
- [`addDays()`](./addDays) - Add/subtract days
- [`addHours()`](./addHours) - Add/subtract hours
- [`addMinutes()`](./addMinutes) - Add/subtract minutes
- [`addMilliseconds()`](./addMilliseconds) - Add/subtract milliseconds
- [`subtract()`](./subtract) - Calculate differences with Duration objects
================================================
FILE: docs/api/addYears.md
================================================
---
title: addYears()
---
Adds or subtracts years from a Date object. Handles leap years and edge cases appropriately.
## Syntax
```typescript
addYears(dateObj, years[, timeZone])
```
### Parameters
| Parameter | Type | Required | Description |
|------------|----------------------|----------|----------------------------------------------------------|
| `dateObj` | `Date` | Yes | The base Date object |
| `years` | `number` | Yes | Number of years to add (positive) or subtract (negative) |
| `timeZone` | `TimeZone \| string` | No | Timezone for the calculation |
### Returns
`Date` - A new Date object with the specified number of years added or subtracted
## Basic Examples
### Adding and Subtracting Years
```typescript
import { addYears } from 'date-and-time';
const date = new Date(2024, 0, 15); // January 15, 2024
// Add years
const future = addYears(date, 3);
console.log(future); // January 15, 2027
// Subtract years
const past = addYears(date, -2);
console.log(past); // January 15, 2022
```
### Daylight Saving Time Aware Calculations
```typescript
import { addYears } from 'date-and-time';
// Working with specific timezones
const nyDate = new Date('2024-03-10T05:00:00Z'); // March 10, 2024 05:00 UTC (DST transition day)
// Add years in New York timezone
const futureNY = addYears(nyDate, 1, 'America/New_York');
console.log(futureNY); // March 10, 2025 04:00 UTC (EST, DST adjusted)
// UTC calculation for comparison
const futureUTC = addYears(nyDate, 1, 'UTC');
console.log(futureUTC); // March 10, 2025 05:00 UTC (same time, no DST adjustment)
```
## Use Cases
### Age Calculation
```typescript
function calculateAge(birthDate: Date): number {
const now = new Date();
const thisYear = addYears(birthDate, now.getFullYear() - birthDate.getFullYear());
if (thisYear > now) {
return now.getFullYear() - birthDate.getFullYear() - 1;
}
return now.getFullYear() - birthDate.getFullYear();
}
const birthDate = new Date(1990, 6, 15); // July 15, 1990;
console.log(calculateAge(birthDate)); // Current age
```
### Financial Year Calculations
```typescript
function getFinancialYearEnd(date: Date): Date {
const currentYear = date.getFullYear();
const financialYearEnd = new Date(currentYear, 2, 31); // March 31
if (date <= financialYearEnd) {
return financialYearEnd;
} else {
return addYears(financialYearEnd, 1); // Next year's March 31
}
}
const someDate = new Date(2024, 5, 15); // June 15, 2024
console.log(getFinancialYearEnd(someDate)); // March 31, 2025
```
## Edge Cases and Behavior
### February 29 Handling
```typescript
// Starting from February 29 (leap year)
const feb29 = new Date(2024, 1, 29); // February 29, 2024
// Adding to non-leap years
console.log(addYears(feb29, 1)); // February 28, 2025
console.log(addYears(feb29, 2)); // February 28, 2026
console.log(addYears(feb29, 3)); // February 28, 2027
console.log(addYears(feb29, 4)); // February 29, 2028 (leap year)
```
### Negative Years
```typescript
const date = new Date(2024, 6, 15); // July 15, 2024
// Go back in time
console.log(addYears(date, -10)); // July 15, 2014
console.log(addYears(date, -100)); // July 15, 1924
```
## Immutability
`addYears()` does not modify the original Date object:
```typescript
const originalDate = new Date(2024, 0, 15);
const modifiedDate = addYears(originalDate, 5);
console.log(originalDate); // January 15, 2024 (unchanged)
console.log(modifiedDate); // January 15, 2029 (new object)
```
## See Also
- [`addMonths()`](./addMonths) - Add/subtract months
- [`addDays()`](./addDays) - Add/subtract days
- [`addHours()`](./addHours) - Add/subtract hours
- [`addMinutes()`](./addMinutes) - Add/subtract minutes
- [`addSeconds()`](./addSeconds) - Add/subtract seconds
- [`addMilliseconds()`](./addMilliseconds) - Add/subtract milliseconds
- [`subtract()`](./subtract) - Calculate differences with Duration objects
================================================
FILE: docs/api/compile.md
================================================
---
title: compile()
---
Precompiles a format string into a reusable compiled object for improved performance when the same format pattern is used repeatedly.
## Syntax
```typescript
compile(formatString)
```
### Parameters
| Parameter | Type | Required | Description |
|----------------|----------|----------|-------------------------------|
| `formatString` | `string` | Yes | The format pattern to compile |
### Returns
`CompiledObject` - A compiled format object that can be reused with `format()` and `parse()`
## Basic Usage
```typescript
import { compile, format, parse } from 'date-and-time';
// Compile once
const pattern = compile('YYYY-MM-DD HH:mm:ss');
// Use multiple times - much faster than parsing the format string each time
const date1 = new Date(2025, 7, 23, 14, 30, 45);
const date2 = new Date(2025, 7, 24, 9, 15, 30);
const formatted1 = format(date1, pattern); // => 2025-08-23 14:30:45
const formatted2 = format(date2, pattern); // => 2025-08-24 09:15:30
// Also works with parse()
const parsed = parse('2025-08-25 16:20:10', pattern);
```
## Performance Benefits
The `compile()` function provides significant performance improvements for repeated operations:
### Without Compilation (Slower)
```typescript
import { format } from 'date-and-time';
const dates = Array.from({ length: 1000 }, () => new Date());
// Format string is parsed 1000 times
dates.forEach(date => {
format(date, 'YYYY-MM-DD HH:mm:ss.SSS [GMT]ZZ');
});
```
### With Compilation (Faster)
```typescript
import { format, compile } from 'date-and-time';
const dates = Array.from({ length: 1000 }, () => new Date());
const pattern = compile('YYYY-MM-DD HH:mm:ss.SSS [GMT]ZZ');
// Format string is compiled once, reused 1000 times
dates.forEach(date => {
format(date, pattern); // Much faster!
});
```
## Real-world Examples
### Logging System
```typescript
import { compile, format } from 'date-and-time';
class Logger {
private timestampPattern = compile('\\[YYYY-MM-DD HH:mm:ss.SSS\\]');
log(level: string, message: string) {
const timestamp = format(new Date(), this.timestampPattern);
console.log(`${timestamp} ${level.toUpperCase()}: ${message}`);
}
}
const logger = new Logger();
logger.log('info', 'Application started');
logger.log('error', 'Database connection failed');
// [2025-08-23 14:30:45.123] INFO: Application started
// [2025-08-23 14:30:45.124] ERROR: Database connection failed
```
### Template Engine Integration
```typescript
import { compile, format } from 'date-and-time';
class EmailTemplateEngine {
private patterns = {
timestamp: compile('YYYY-MM-DD HH:mm:ss'),
friendly: compile('MMMM D, YYYY [at] h:mm A'),
fileDate: compile('YYYY-MM-DD')
};
generateEmail(user: string, data: any): string {
const now = new Date();
return `
Dear ${user},
This report was generated on ${format(now, this.patterns.friendly)}.
System timestamp: ${format(now, this.patterns.timestamp)}
Report date: ${format(data.reportDate, this.patterns.fileDate)}
Best regards,
System
`.trim();
}
}
const engine = new EmailTemplateEngine();
const email = engine.generateEmail('John', {
reportDate: new Date(2025, 7, 23)
});
```
### API Response Formatting
```typescript
import { compile, format } from 'date-and-time';
class ApiService {
private isoPattern = compile('YYYY-MM-DD[T]HH:mm:ss.SSS[Z]');
private friendlyPattern = compile('MMMM D, YYYY [at] h:mm A');
formatResponse(data: any[]) {
return data.map(item => ({
...item,
createdAt: format(item.createdAt, this.isoPattern, { timeZone: 'UTC' }),
createdAtFriendly: format(item.createdAt, this.friendlyPattern)
}));
}
}
```
### Batch File Operations
```typescript
import { compile, format } from 'date-and-time';
import { writeFileSync } from 'fs';
const filenamePattern = compile('YYYY-MM-DD_HH-mm-ss');
function generateReports(data: any[]) {
const timestamp = format(new Date(), filenamePattern);
data.forEach((report, index) => {
const filename = `report_${index}_${timestamp}.json`;
writeFileSync(filename, JSON.stringify(report));
});
}
```
## Advanced Usage
### Multiple Compiled Patterns
```typescript
import { compile, format } from 'date-and-time';
import en from 'date-and-time/locales/en';
import ja from 'date-and-time/locales/ja';
class MultiFormatHandler {
private patterns = {
iso: compile('YYYY-MM-DD[T]HH:mm:ss[Z]'),
friendly: compile('MMMM D, YYYY [at] h:mm A'),
japanese: compile('YYYY年M月D日(ddd) HH:mm'),
filename: compile('YYYYMMDD_HHmmss')
};
format(date: Date, type: keyof typeof this.patterns) {
const pattern = this.patterns[type];
switch (type) {
case 'iso':
return format(date, pattern, { timeZone: 'UTC' });
case 'japanese':
return format(date, pattern, { locale: ja });
default:
return format(date, pattern);
}
}
}
const handler = new MultiFormatHandler();
const date = new Date();
console.log(handler.format(date, 'iso')); // => 2025-08-23T14:30:45Z
console.log(handler.format(date, 'friendly')); // => August 23, 2025 at 2:30 PM
console.log(handler.format(date, 'japanese')); // => 2025年8月23日(土) 14:30
console.log(handler.format(date, 'filename')); // => 20250823_143045
```
### Conditional Compilation
```typescript
import { compile, format } from 'date-and-time';
class SmartFormatter {
private cache = new Map<string, any>();
private getCompiledPattern(formatString: string) {
if (!this.cache.has(formatString)) {
this.cache.set(formatString, compile(formatString));
}
return this.cache.get(formatString);
}
format(date: Date, formatString: string, options?: any) {
const pattern = this.getCompiledPattern(formatString);
return format(date, pattern, options);
}
}
const formatter = new SmartFormatter();
// First call compiles the pattern
formatter.format(new Date(), 'YYYY-MM-DD');
// Subsequent calls reuse the compiled pattern
formatter.format(new Date(), 'YYYY-MM-DD'); // Faster!
```
## Best Practices
### 1. Compile Once, Use Many Times
```typescript
// ✅ Good - compile once
const pattern = compile('YYYY-MM-DD HH:mm:ss');
for (const date of dates) {
format(date, pattern);
}
// ❌ Bad - compiles every time
for (const date of dates) {
format(date, 'YYYY-MM-DD HH:mm:ss');
}
```
### 2. Cache Compiled Patterns
```typescript
// ✅ Good - cached patterns
class DateFormatter {
private static patterns = {
iso: compile('YYYY-MM-DD[T]HH:mm:ss[Z]'),
short: compile('MM/DD/YYYY'),
long: compile('MMMM D, YYYY')
};
static format(date: Date, type: keyof typeof DateFormatter.patterns) {
return format(date, DateFormatter.patterns[type]);
}
}
```
### 3. Lazy Compilation
```typescript
// ✅ Good - lazy compilation for dynamic patterns
class DynamicFormatter {
private cache = new Map<string, CompiledObject>();
format(date: Date, pattern: string) {
if (!this.cache.has(pattern)) {
this.cache.set(pattern, compile(pattern));
}
return format(date, this.cache.get(pattern)!);
}
}
```
## See Also
- [`format()`](./format) - Format Date objects using compiled patterns
- [`parse()`](./parse) - Parse date strings using compiled patterns
- [`preparse()`](./preparse) - Parse and return intermediate parsing results
- [`transform()`](./transform) - Transform date strings between formats
================================================
FILE: docs/api/format.md
================================================
---
title: format()
---
Formats a Date object according to the specified format string.
## Syntax
```typescript
format(dateObj, formatString[, options])
```
### Parameters
| Parameter | Type | Required | Description |
|----------------|----------------------------|----------|--------------------------------------|
| `dateObj` | `Date` | Yes | The Date object to format |
| `formatString` | `string \| CompiledObject` | Yes | The format string or compiled object |
| `options` | `FormatterOptions` | No | Formatter options for customization |
### Returns
`string` - The formatted date string
## Basic Examples
```typescript
import { format } from 'date-and-time';
const now = new Date();
format(now, 'YYYY/MM/DD HH:mm:ss');
// => 2025/08/23 14:30:45
format(now, 'ddd, MMM DD YYYY');
// => Sat, Aug 23 2025
format(now, 'hh:mm A [GMT]Z');
// => 02:30 PM GMT-0700
```
## Format Tokens
### Date Tokens
| Token | Description | Output Examples |
|--------|----------------------------|-------------------|
| `YYYY` | 4-digit year | 0999, 2015 |
| `YY` | 2-digit year | 99, 01, 15 |
| `Y` | Year without zero padding | 2, 44, 888, 2015 |
| `MMMM` | Full month name | January, December |
| `MMM` | Short month name | Jan, Dec |
| `MM` | Month (01-12) | 01, 12 |
| `M` | Month without zero padding | 1, 12 |
| `DD` | Day (01-31) | 02, 31 |
| `D` | Day without zero padding | 2, 31 |
### Day of Week Tokens
| Token | Description | Output Examples |
|--------|---------------------|-----------------|
| `dddd` | Full day name | Friday, Sunday |
| `ddd` | Short day name | Fri, Sun |
| `dd` | Very short day name | Fr, Su |
### Time Tokens
| Token | Description | Output Examples |
|-------|---------------------------------------------|-----------------|
| `HH` | Hour in 24-hour format | 23, 08 |
| `H` | Hour in 24-hour format without zero padding | 23, 8 |
| `hh` | Hour in 12-hour format | 11, 08 |
| `h` | Hour in 12-hour format without zero padding | 11, 8 |
| `mm` | Minutes | 14, 07 |
| `m` | Minutes without zero padding | 14, 7 |
| `ss` | Seconds | 05, 10 |
| `s` | Seconds without zero padding | 5, 10 |
| `SSS` | 3-digit milliseconds | 753, 022 |
| `SS` | 2-digit milliseconds | 75, 02 |
| `S` | 1-digit milliseconds | 7, 0 |
### AM/PM Tokens
| Token | Description | Output Examples |
|-------|--------------------------------|-----------------|
| `A` | Uppercase AM/PM | AM, PM |
| `AA` | Uppercase AM/PM (with periods) | A.M., P.M. |
| `a` | Lowercase AM/PM | am, pm |
| `aa` | Lowercase AM/PM (with periods) | a.m., p.m. |
### Timezone Tokens
| Token | Description | Output Examples |
|-------|----------------------------|-----------------|
| `Z` | Timezone offset | +0100, -0800 |
| `ZZ` | Timezone offset with colon | +01:00, -08:00 |
### Plugin Tokens
Additional tokens available with plugins:
| Token | Description | Output Examples | Plugin Required |
|--------|-------------------------------------|-----------------------|-----------------|
| `DDD` | Ordinal representation | 1st, 2nd, 3rd | ordinal |
| `Q` | Quarter of year | 1, 2, 3, 4 | quarter |
| `t` | Unix timestamp (seconds) | 0, 1000000000 | timestamp |
| `T` | Unix timestamp (milliseconds) | 0, 1000000000000 | timestamp |
| `W` | ISO week number | 1, 27, 53 | week |
| `WW` | ISO week number (zero-padded) | 01, 27, 53 | week |
| `G` | ISO week year | 2024, 2025 | week |
| `GG` | ISO week year (2-digit zero-padded) | 24, 25 | week |
| `GGGG` | ISO week year (4-digit zero-padded) | 2024, 2025 | week |
| `z` | Short timezone name | PST, EST | zonename |
| `zz` | Long timezone name | Pacific Standard Time | zonename |
For available plugins, see the [`plugins`](#plugins) option in FormatterOptions.
## FormatterOptions
The `FormatterOptions` object allows you to customize the formatting behavior:
```typescript
interface FormatterOptions {
locale?: Locale;
timeZone?: TimeZone | string;
numeral?: Numeral;
calendar?: 'gregory' | 'buddhist';
hour12?: 'h11' | 'h12';
hour24?: 'h23' | 'h24';
plugins?: FormatterPlugin[];
}
```
### locale
**Type**: `Locale`
**Default**: `en` (English)
Specifies the locale for localized formatting of month names, day names, and meridiem indicators.
```typescript
import { format } from 'date-and-time';
import ja from 'date-and-time/locales/ja';
import es from 'date-and-time/locales/es';
const date = new Date();
// Japanese formatting
format(date, 'YYYY年M月D日(ddd)', { locale: ja });
// => 2025年8月23日(土)
// Spanish formatting
format(date, 'dddd, D [de] MMMM [de] YYYY', { locale: es });
// => sábado, 23 de agosto de 2025
```
For a complete list of all supported locales with import examples, see [Supported Locales](../locales).
### timeZone
**Type**: `TimeZone | string`
**Default**: `undefined` (local timezone)
Converts the date to the specified timezone before formatting.
```typescript
import { format } from 'date-and-time';
const date = new Date();
format(date, 'YYYY-MM-DD HH:mm:ss [JST]', { timeZone: 'Asia/Tokyo' });
// => 2025-08-23 23:30:45 JST
format(date, 'YYYY-MM-DD HH:mm:ss [EST]', { timeZone: 'America/New_York' });
// => 2025-08-23 09:30:45 EST
format(date, 'YYYY-MM-DD HH:mm:ss [UTC]', { timeZone: 'UTC' });
// => 2025-08-23 14:30:45 UTC
```
For a complete list of all supported timezones, see [Supported Timezones](../timezones).
### numeral
**Type**: `Numeral`
**Default**: `latn` (Latin numerals)
Specifies the numeral system for formatting numbers.
```typescript
import { format } from 'date-and-time';
import arab from 'date-and-time/numerals/arab';
import beng from 'date-and-time/numerals/beng';
const date = new Date();
// Arabic-Indic numerals
format(date, 'DD/MM/YYYY', { numeral: arab });
// => ٠٨/٠٧/٢٠٢٥
// Bengali numerals
format(date, 'DD/MM/YYYY', { numeral: beng });
// => ০৮/০৭/২০২৫
```
**Available numeral systems:**
- `latn` - Latin numerals (0-9) - default
- `arab` - Arabic-Indic numerals (٠-٩)
- `arabext` - Extended Arabic-Indic numerals (۰-۹)
- `beng` - Bengali numerals (০-৯)
- `mymr` - Myanmar numerals (၀-၉)
### calendar
**Type**: `"gregory" | "buddhist"`
**Default**: `"gregory"`
Specifies the calendar system for date calculations.
```typescript
import { format } from 'date-and-time';
const date = new Date();
// Gregorian calendar (default)
format(date, 'MMMM D, YYYY');
// => August 23, 2025
// Buddhist calendar (543 years ahead)
format(date, 'MMMM D, YYYY', { calendar: 'buddhist' });
// => August 23, 2568
```
### hour12
**Type**: `"h11" | "h12"`
**Default**: `"h12"`
Controls the 12-hour format interpretation. Use h11 for 11-hour format (0-11) or h12 for 12-hour format (1-12).
```typescript
import { format } from 'date-and-time';
const midnight = new Date(2025, 7, 23, 0, 30, 0); // 12:30 AM
// h12 format (1-12)
format(midnight, 'h:mm A', { hour12: 'h12' });
// => 12:30 AM
// h11 format (0-11)
format(midnight, 'h:mm A', { hour12: 'h11' });
// => 0:30 AM
```
### hour24
**Type**: `"h23" | "h24"`
**Default**: `"h23"`
Controls the 24-hour format interpretation. Use h23 for 23-hour format (0-23) or h24 for 24-hour format (1-24).
```typescript
import { format } from 'date-and-time';
const midnight = new Date(2025, 7, 23, 0, 30, 0);
// h23 format (0-23)
format(midnight, 'H:mm', { hour24: 'h23' });
// => 0:30
// h24 format (1-24)
format(midnight, 'H:mm', { hour24: 'h24' });
// => 24:30
```
### plugins
**Type**: `FormatterPlugin[]`
**Default**: `undefined`
Enables additional format tokens provided by plugins. Plugins extend the formatter with special tokens that are not included in the core library.
```typescript
import { format } from 'date-and-time';
import { formatter as ordinal } from 'date-and-time/plugins/ordinal';
import { formatter as zonename } from 'date-and-time/plugins/zonename';
const date = new Date();
// Use ordinal plugin
format(date, 'MMMM DDD, YYYY', { plugins: [ordinal] });
// => August 23rd, 2025
// Use zonename plugin
format(date, 'YYYY-MM-DD HH:mm z', { plugins: [zonename] });
// => 2025-08-23 14:30 PDT
// Use multiple plugins together
format(date, 'MMMM DDD, YYYY h:mm A zz', { plugins: [ordinal, zonename] });
// => August 23rd, 2025 2:30 PM Pacific Daylight Time
```
For a complete list of available plugins, see [Plugins](../plugins).
## Advanced Usage
### Comments in Format Strings
Parts of the format string enclosed in square brackets are output literally:
```typescript
import { format } from 'date-and-time';
const date = new Date();
format(date, '[Today is] dddd, MMMM D, YYYY');
// => Today is Saturday, August 23, 2025
format(date, 'YYYY-MM-DD[T]HH:mm:ss[Z]');
// => 2025-08-23T14:30:45Z
format(date, '[Report generated on] YYYY/MM/DD [at] HH:mm');
// => Report generated on 2025/08/23 at 14:30
// Escape square brackets to output them literally
format(date, '\\[YYYY-MM-DD HH:mm:ss\\]');
// => [2025-08-23 14:30:45]
```
### Complex Localized Formatting
```typescript
import { format } from 'date-and-time';
import ja from 'date-and-time/locales/ja';
const date = new Date();
format(date, 'YYYY年MMMM月D日dddd Ah:mm:ss [GMT]Z', {
timeZone: 'Asia/Tokyo',
locale: ja
});
// => 2025年8月23日土曜日 午後11:30:45 GMT+0900
```
### Business and Technical Formats
```typescript
import { format } from 'date-and-time';
const date = new Date();
// ISO 8601 format
format(date, 'YYYY-MM-DD[T]HH:mm:ss.SSS[Z]', { timeZone: 'UTC' });
// => 2025-08-23T14:30:45.123Z
// RFC 2822 format
format(date, 'ddd, DD MMM YYYY HH:mm:ss ZZ');
// => Sat, 23 Aug 2025 14:30:45 +09:00
// Log timestamp
format(date, '\\[YYYY-MM-DD HH:mm:ss.SSS]\\');
// => [2025-08-23 14:30:45.123]
// File naming
format(date, 'YYYYMMDD_HHmmss');
// => 20250823_143045
```
## Performance Considerations
For repeated formatting with the same pattern, use [`compile()`](./compile) to precompile the format string:
```typescript
import { format, compile } from 'date-and-time';
// Compile once
const pattern = compile('YYYY-MM-DD HH:mm:ss');
// Reuse for better performance
const dates = [new Date(), new Date(), new Date()];
dates.forEach(date => {
console.log(format(date, pattern));
});
```
## See Also
- [`compile()`](./compile) - Precompile format patterns for performance
- [`transform()`](./transform) - Transform date strings between formats
================================================
FILE: docs/api/index.md
================================================
---
title: API Reference
---
Welcome to the comprehensive API reference for date-and-time v4.x. This section provides detailed documentation for all available functions, types, and options.
## Core Functions
### Formatting and Parsing
| Function | Description |
|------------------------------|-----------------------------------------------|
| [`format()`](./format) | Convert Date objects to formatted strings |
| [`parse()`](./parse) | Parse date strings into Date objects |
| [`compile()`](./compile) | Precompile format patterns for performance |
| [`preparse()`](./preparse) | Parse and return intermediate parsing results |
| [`isValid()`](./isValid) | Validate date string formats |
| [`transform()`](./transform) | Transform date strings between formats |
### Date Arithmetic
| Function | Description |
|--------------------------------------------------------|--------------------------------------------------|
| [`addYears()`](./add-functions#addyears) | Add/subtract years from dates |
| [`addMonths()`](./add-functions#addmonths) | Add/subtract months from dates |
| [`addDays()`](./add-functions#adddays) | Add/subtract days from dates |
| [`addHours()`](./add-functions#addhours) | Add/subtract hours from dates |
| [`addMinutes()`](./add-functions#addminutes) | Add/subtract minutes from dates |
| [`addSeconds()`](./add-functions#addseconds) | Add/subtract seconds from dates |
| [`addMilliseconds()`](./add-functions#addmilliseconds) | Add/subtract milliseconds from dates |
| [`subtract()`](./subtract) | Calculate time differences with Duration objects |
### Utility Functions
| Function | Description |
|----------------------------------------------|----------------------------------------|
| [`isLeapYear()`](./utils/isLeapYear) | Check if a year is a leap year |
| [`isSameDay()`](./utils/isSameDay) | Check if two dates are on the same day |
| [`getDaysInMonth()`](./utils/getDaysInMonth) | Get the number of days in a month |
| [`getISOWeekYear()`](./utils/getISOWeekYear) | Get the ISO week year for a date |
| [`getISOWeek()`](./utils/getISOWeek) | Get the ISO week number for a date |
## Quick Examples
### Basic Usage
```typescript
import { format, parse, isValid } from 'date-and-time'
// Formatting
const date = new Date()
format(date, 'YYYY-MM-DD HH:mm:ss');
// => 2025-08-23 14:30:45
// Parsing
const parsed = parse('2025-08-23 14:30:45', 'YYYY-MM-DD HH:mm:ss');
// => Date object
// Validation
isValid('2025-02-29', 'YYYY-MM-DD'); // => false (not a leap year)
```
### With Options
```typescript
import { format } from 'date-and-time';
import ja from 'date-and-time/locales/ja';
format(new Date(), 'YYYY年M月D日(ddd) HH:mm', {
locale: ja,
timeZone: 'Asia/Tokyo'
});
// => 2025年8月23日(土) 23:30
```
## Supported Locales
date-and-time supports 40+ locales. Import only the ones you need:
```typescript
// Examples
import ar from 'date-and-time/locales/ar'; // Arabic
import ja from 'date-and-time/locales/ja'; // Japanese
import es from 'date-and-time/locales/es'; // Spanish
import fr from 'date-and-time/locales/fr'; // French
import de from 'date-and-time/locales/de'; // German
import ru from 'date-and-time/locales/ru'; // Russian
import zhHans from 'date-and-time/locales/zh-Hans'; // Simplified Chinese
```
For a complete list of all supported locales with import examples, see [Supported Locales](../locales).
## Supported Timezones
Complete IANA timezone database support. Pass an IANA timezone name string directly to any function:
```typescript
format(new Date(), 'YYYY-MM-DD HH:mm:ss', { timeZone: 'Asia/Tokyo' });
format(new Date(), 'YYYY-MM-DD HH:mm:ss', { timeZone: 'America/New_York' });
```
For a complete list of all supported timezones, see [Supported Timezones](../timezones).
## Numeral Systems
Support for different numeral systems:
```typescript
import arab from 'date-and-time/numerals/arab'; // Arabic-Indic
import beng from 'date-and-time/numerals/beng'; // Bengali
import mymr from 'date-and-time/numerals/mymr'; // Myanmar
import latn from 'date-and-time/numerals/latn'; // Latin (default)
format(new Date(), 'DD/MM/YYYY', { numeral: arab });
// => ٠٨/٠٧/٢٠٢٥
```
## Error Handling
### Parse Failures
```typescript
import { parse, isValid } from 'date-and-time';
// Always check validity first
if (!isValid('invalid-date', 'YYYY-MM-DD')) {
throw new Error('Invalid date format');
}
// Or check parse results
const result = parse('invalid-date', 'YYYY-MM-DD');
if (isNaN(result.getTime())) {
throw new Error('Parse failed');
}
```
### Type Safety
```typescript
import { format, FormatterOptions } from 'date-and-time';
// TypeScript will catch type errors
const options: FormatterOptions = {
locale: 'invalid', // ❌ TypeScript error
timeZone: 123 // ❌ TypeScript error
};
```
## Performance Tips
1. **Use `compile()`** for repeated operations:
```typescript
const pattern = compile('YYYY-MM-DD HH:mm:ss');
// Reuse pattern for better performance
```
2. **Import only what you need**:
```typescript
import { format } from 'date-and-time'; // ✅ Tree-shakable
import * as date from 'date-and-time'; // ❌ Imports everything
```
## Migration from v3.x
If you're migrating from version 3.x, see the [Migration Guide](../migration) for detailed upgrade instructions and breaking changes.
================================================
FILE: docs/api/isValid.md
================================================
---
title: isValid()
---
Validates whether a date string conforms to the specified format pattern and represents a valid date.
## Syntax
```typescript
isValid(dateString, formatString[, options])
```
### Parameters
| Parameter | Type | Required | Description |
|----------------|----------------------------|----------|------------------------------------------------------------------------------------|
| `dateString` | `string` | Yes | The date string to validate |
| `formatString` | `string \| CompiledObject` | Yes | The format pattern or compiled object |
| `options` | `ParserOptions` | No | Parser options for validation (see [`parse()`](./parse#parseroptions) for details) |
### Returns
`boolean` - `true` if the date string is valid and matches the format, `false` otherwise
## Basic Examples
```typescript
import { isValid } from 'date-and-time';
// Valid dates
isValid('2025-08-23', 'YYYY-MM-DD'); // => true
isValid('08/23/2025', 'MM/DD/YYYY'); // => true
isValid('14:30:45', 'HH:mm:ss'); // => true
isValid('2:30 PM', 'h:mm A'); // => true
// Invalid dates
isValid('2025-02-30', 'YYYY-MM-DD'); // => false (Feb 30th doesn't exist)
isValid('2025-13-01', 'YYYY-MM-DD'); // => false (month 13 doesn't exist)
isValid('25:30:00', 'HH:mm:ss'); // => false (hour 25 doesn't exist)
isValid('invalid-date', 'YYYY-MM-DD'); // => false (doesn't match format)
// Format mismatch
isValid('2025-08-23', 'MM/DD/YYYY'); // => false (wrong format)
isValid('08/23/2025', 'YYYY-MM-DD'); // => false (wrong format)
```
## Validation with Options
### Locale Validation
```typescript
import { isValid } from 'date-and-time';
import es from 'date-and-time/locales/es';
// Spanish month names
isValid('23 de agosto de 2025', 'D [de] MMMM [de] YYYY', { locale: es }); // => true
isValid('23 de invalid de 2025', 'D [de] MMMM [de] YYYY', { locale: es }); // => false
```
### Case-Insensitive Validation
```typescript
import { isValid } from 'date-and-time';
// Case-sensitive (default)
isValid('AUGUST 23, 2025', 'MMMM D, YYYY'); // => false
isValid('august 23, 2025', 'MMMM D, YYYY'); // => false
// Case-insensitive
isValid('AUGUST 23, 2025', 'MMMM D, YYYY', { ignoreCase: true }); // => true
isValid('august 23, 2025', 'MMMM D, YYYY', { ignoreCase: true }); // => true
isValid('August 23, 2025', 'MMMM D, YYYY'); // => true (correct case)
```
### defaultDate Validation
Use `defaultDate` to provide context for validation of partial date strings. The most practical use case is leap year-aware validation of month-day strings.
```typescript
import { isValid } from 'date-and-time';
// Leap day validation — result depends on the year
isValid('02-29', 'MM-DD', { defaultDate: { Y: 2024 } }); // => true (2024 is a leap year)
isValid('02-29', 'MM-DD', { defaultDate: { Y: 2023 } }); // => false (2023 is not a leap year)
isValid('02-29', 'MM-DD'); // => false (default year 1970 is not a leap year)
// Day range validation — depends on both year and month
isValid('29', 'D', { defaultDate: { Y: 2024, M: 2 } }); // => true (Feb 2024 has 29 days)
isValid('31', 'D', { defaultDate: { Y: 2024, M: 4 } }); // => false (April has 30 days)
```
**Note**: Values provided in `defaultDate` are also subject to range validation. For example, an out-of-range `H` value in `defaultDate` will cause `isValid()` to return `false`.
## Advanced Validation Patterns
### Multiple Format Validation
```typescript
import { isValid } from 'date-and-time';
function isValidDate(dateString: string): boolean {
const formats = [
'YYYY-MM-DD',
'MM/DD/YYYY',
'DD.MM.YYYY',
'MMMM D, YYYY',
'MMM D, YYYY'
];
return formats.some(format => isValid(dateString, format));
}
// Usage
console.log(isValidDate('2025-08-23')); // => true
console.log(isValidDate('08/23/2025')); // => true
console.log(isValidDate('23.08.2025')); // => true
console.log(isValidDate('August 23, 2025')); // => true
console.log(isValidDate('invalid-date')); // => false
```
### Business Rule Validation
```typescript
import { isValid, parse } from 'date-and-time';
function isBusinessDay(dateString: string, format: string): boolean {
// First check if it's a valid date
if (!isValid(dateString, format)) {
return false;
}
// Parse and check if it's a weekday
const date = parse(dateString, format);
const dayOfWeek = date.getDay();
// 0 = Sunday, 6 = Saturday
return dayOfWeek >= 1 && dayOfWeek <= 5;
}
// Usage
console.log(isBusinessDay('2025-08-23', 'YYYY-MM-DD')); // => false (Saturday)
console.log(isBusinessDay('2025-08-25', 'YYYY-MM-DD')); // => true (Monday)
```
### Range Validation
```typescript
import { isValid, parse } from 'date-and-time';
function isValidInRange(
dateString: string,
format: string,
minDate: Date,
maxDate: Date
): boolean {
if (!isValid(dateString, format)) {
return false;
}
const date = parse(dateString, format);
return date >= minDate && date <= maxDate;
}
// Usage
const min = new Date(2025, 0, 1); // Jan 1, 2025
const max = new Date(2025, 11, 31); // Dec 31, 2025
console.log(isValidInRange('2025-08-23', 'YYYY-MM-DD', min, max)); // => true
console.log(isValidInRange('2024-08-23', 'YYYY-MM-DD', min, max)); // => false
```
## Performance with Compiled Patterns
For repeated validation, use `compile()` for better performance:
```typescript
import { isValid, compile } from 'date-and-time';
// Compile once
const pattern = compile('YYYY-MM-DD HH:mm:ss');
// Validate multiple times (faster)
const dateStrings = [
'2025-08-23 14:30:45',
'2025-08-24 09:15:30',
'2025-02-30 12:00:00', // Invalid
'2025-08-25 16:45:20'
];
const validDates = dateStrings.filter(dateString =>
isValid(dateString, pattern)
);
console.log('Valid dates:', validDates);
// => ['2025-08-23 14:30:45', '2025-08-24 09:15:30', '2025-08-25 16:45:20']
```
## Common Use Cases
### Form Input Validation
```typescript
import { isValid, parse } from 'date-and-time';
class DateInputValidator {
static validateBirthDate(dateString: string): boolean {
if (!isValid(dateString, 'YYYY-MM-DD')) {
return false;
}
const date = parse(dateString, 'YYYY-MM-DD');
const now = new Date();
// Must be in the past and reasonable range
return date < now && date > new Date(1900, 0, 1);
}
static validateAppointment(dateString: string): boolean {
if (!isValid(dateString, 'YYYY-MM-DD HH:mm')) {
return false;
}
const date = parse(dateString, 'YYYY-MM-DD HH:mm');
const now = new Date();
// Must be in the future
return date > now;
}
}
```
### API Input Validation
```typescript
import { isValid, parse } from 'date-and-time';
function validateApiDateRange(startDate: string, endDate: string) {
const format = 'YYYY-MM-DD';
// Check both dates are valid
if (!isValid(startDate, format) || !isValid(endDate, format)) {
throw new Error('Invalid date format. Expected YYYY-MM-DD');
}
const start = parse(startDate, format);
const end = parse(endDate, format);
// Check logical order
if (start >= end) {
throw new Error('Start date must be before end date');
}
return { start, end };
}
```
## See Also
- [`parse()`](./parse) - Parse validated date strings into Date objects
- [`compile()`](./compile) - Precompile format patterns for performance
- [`preparse()`](./preparse) - Parse and return intermediate parsing results
================================================
FILE: docs/api/parse.md
================================================
---
title: parse()
---
Parses a formatted date string into a Date object according to the specified format pattern.
## Syntax
```typescript
parse(dateString, formatString[, options])
```
### Parameters
| Parameter | Type | Required | Description |
|----------------|----------------------------|----------|---------------------------------------|
| `dateString` | `string` | Yes | The date string to parse |
| `formatString` | `string \| CompiledObject` | Yes | The format pattern or compiled object |
| `options` | `ParserOptions` | No | Parser options for customization |
### Returns
`Date` - The parsed Date object, or Invalid Date if parsing fails
## Basic Examples
```typescript
import { parse } from 'date-and-time';
// Basic date parsing
parse('2025-08-23', 'YYYY-MM-DD');
// => Fri Aug 23 2025 00:00:00 GMT-0700
parse('08/23/2025', 'MM/DD/YYYY');
// => Fri Aug 23 2025 00:00:00 GMT-0700
parse('23.08.2025', 'DD.MM.YYYY');
// => Fri Aug 23 2025 00:00:00 GMT-0700
// Time parsing
parse('14:30:45', 'HH:mm:ss');
// => Thu Jan 01 1970 14:30:45 GMT-0800
parse('2:30:45 PM', 'h:mm:ss A');
// => Thu Jan 01 1970 14:30:45 GMT-0800
// Combined date and time
parse('2025-08-23 14:30:45', 'YYYY-MM-DD HH:mm:ss');
// => Fri Aug 23 2025 14:30:45 GMT-0700
```
## Format Tokens
### Date Tokens
| Token | Description | Input Examples |
|--------|----------------------------|-------------------|
| `YYYY` | 4-digit year | 0999, 2015 |
| `Y` | Year without zero padding | 2, 44, 888, 2015 |
| `MMMM` | Full month name | January, December |
| `MMM` | Short month name | Jan, Dec |
| `MM` | Month (01-12) | 01, 12 |
| `M` | Month without zero padding | 1, 12 |
| `DD` | Day (01-31) | 02, 31 |
| `D` | Day without zero padding | 2, 31 |
### Time Tokens
| Token | Description | Input Examples |
|-------|---------------------------------------------|----------------|
| `HH` | Hour in 24-hour format | 23, 08 |
| `H` | Hour in 24-hour format without zero padding | 23, 8 |
| `hh` | Hour in 12-hour format | 11, 08 |
| `h` | Hour in 12-hour format without zero padding | 11, 8 |
| `mm` | Minutes | 14, 07 |
| `m` | Minutes without zero padding | 14, 7 |
| `ss` | Seconds | 05, 10 |
| `s` | Seconds without zero padding | 5, 10 |
| `SSS` | 3-digit milliseconds | 753, 022 |
| `SS` | 2-digit milliseconds | 75, 02 |
| `S` | 1-digit milliseconds | 7, 0 |
### AM/PM Tokens
| Token | Description | Input Examples |
|-------|--------------------------------|----------------|
| `A` | Uppercase AM/PM | AM, PM |
| `AA` | Uppercase AM/PM (with periods) | A.M., P.M. |
| `a` | Lowercase AM/PM | am, pm |
| `aa` | Lowercase AM/PM (with periods) | a.m., p.m. |
### Timezone Tokens
| Token | Description | Input Examples |
|-------|----------------------------|----------------|
| `Z` | Timezone offset | +0100, -0800 |
| `ZZ` | Timezone offset with colon | +01:00, -08:00 |
### Plugin Tokens
Additional tokens available with plugins:
| Token | Description | Input Examples | Plugin Required |
|-------------|------------------------|----------------------|-----------------|
| `YY` | 2-digit year | 90, 00, 08, 19 | two-digit-year |
| `DDD` | Ordinal representation | 1st, 2nd, 3rd | ordinal |
| `dddd` | Full day name | Friday, Sunday | day-of-week |
| `ddd` | Short day name | Fri, Sun | day-of-week |
| `dd` | Very short day name | Fr, Su | day-of-week |
| `SSSSSS` | 6-digit milliseconds | 123456, 000001 | microsecond |
| `SSSSS` | 5-digit milliseconds | 12345, 00001 | microsecond |
| `SSSS` | 4-digit milliseconds | 1234, 0001 | microsecond |
| `fff` | 3-digit microseconds | 753, 022 | microsecond |
| `ff` | 2-digit microseconds | 75, 02 | microsecond |
| `f` | 1-digit microseconds | 7, 0 | microsecond |
| `SSSSSSSSS` | 9-digit milliseconds | 123456789, 000000001 | nanosecond |
| `SSSSSSSS` | 8-digit milliseconds | 12345678, 00000001 | nanosecond |
| `SSSSSSS` | 7-digit milliseconds | 1234567, 0000001 | nanosecond |
| `FFF` | 3-digit nanoseconds | 753, 022 | nanosecond |
| `FF` | 2-digit nanoseconds | 75, 02 | nanosecond |
| `F` | 1-digit nanoseconds | 7, 0 | nanosecond |
For available plugins, see the [`plugins`](#plugins) option in ParserOptions.
## ParserOptions
The `ParserOptions` object allows you to customize the parsing behavior:
```typescript
interface ParserOptions {
locale?: Locale;
timeZone?: TimeZone | string;
numeral?: Numeral;
calendar?: 'gregory' | 'buddhist';
hour12?: 'h11' | 'h12';
hour24?: 'h23' | 'h24';
ignoreCase?: boolean;
defaultDate?: ParsedComponents;
plugins?: ParserPlugin[];
}
```
### locale
**Type**: `Locale`
**Default**: `en` (English)
Specifies the locale for parsing localized month names, day names, and meridiem indicators.
```typescript
import { parse } from 'date-and-time';
import es from 'date-and-time/locales/es';
// Spanish parsing
parse('23 de agosto de 2025', 'D [de] MMMM [de] YYYY', { locale: es });
// => Fri Aug 23 2025 00:00:00 GMT-0700
```
For a complete list of all supported locales with import examples, see [Supported Locales](../locales).
### timeZone
**Type**: `TimeZone | string`
**Default**: `undefined` (local timezone)
Interprets the parsed date in the specified timezone.
**Note**: If the input string contains a timezone offset (e.g., `Z` or `ZZ` tokens), that offset takes precedence and the `timeZone` option is ignored.
```typescript
import { parse } from 'date-and-time';
// Parse using an IANA timezone name string
parse('2025-08-23 14:30:00', 'YYYY-MM-DD HH:mm:ss', { timeZone: 'Asia/Tokyo' });
// => Fri Aug 23 2025 14:30:00 GMT+0900
// Parse in UTC
parse('2025-08-23 14:30:00', 'YYYY-MM-DD HH:mm:ss', { timeZone: 'UTC' });
// => Fri Aug 23 2025 14:30:00 GMT+0000
// Timezone offset in input takes precedence over timeZone option
parse('2025-08-23 14:30:00 +0300', 'YYYY-MM-DD HH:mm:ss Z', { timeZone: 'Asia/Tokyo' });
// => Fri Aug 23 2025 14:30:00 GMT+0300 (Asia/Tokyo timeZone is ignored)
parse('2025-08-23T14:30:00 +05:00', 'YYYY-MM-DD[T]HH:mm:ss ZZ', { timeZone: 'America/New_York' });
// => Fri Aug 23 2025 14:30:00 GMT+0500 (America/New_York timeZone is ignored)
```
For a complete list of all supported timezones, see [Supported Timezones](../timezones).
### numeral
**Type**: `Numeral`
**Default**: `latn` (Latin numerals)
Specifies the numeral system for parsing numbers.
```typescript
import { parse } from 'date-and-time';
import arab from 'date-and-time/numerals/arab';
import beng from 'date-and-time/numerals/beng';
// Arabic-Indic numerals
parse('٠٨/٠٧/٢٠٢٥', 'DD/MM/YYYY', { numeral: arab });
// => Fri Aug 08 2025 00:00:00 GMT-0700
// Bengali numerals
parse('০৮/০৭/২০২৫', 'DD/MM/YYYY', { numeral: beng });
// => Fri Aug 08 2025 00:00:00 GMT-0700
```
**Available numeral systems:**
- `latn` - Latin numerals (0-9) - default
- `arab` - Arabic-Indic numerals (٠-٩)
- `arabext` - Extended Arabic-Indic numerals (۰-۹)
- `beng` - Bengali numerals (০-৯)
- `mymr` - Myanmar numerals (၀-၉)
### calendar
**Type**: `"gregory" | "buddhist"`
**Default**: `"gregory"`
Specifies the calendar system for date calculations.
```typescript
import { parse } from 'date-and-time';
// Gregorian calendar (default)
parse('August 23, 2025', 'MMMM D, YYYY');
// => Fri Aug 23 2025 00:00:00 GMT-0700
// Buddhist calendar (543 years behind)
parse('August 23, 2568', 'MMMM D, YYYY', { calendar: 'buddhist' });
// => Fri Aug 23 2025 00:00:00 GMT-0700
```
### hour12
**Type**: `"h11" | "h12"`
**Default**: `"h12"`
Controls the 12-hour format interpretation. Use `h11` for 11-hour format (0-11) or `h12` for 12-hour format (1-12).
```typescript
import { parse } from 'date-and-time';
// h12 format - midnight is 12 AM
parse('12:30 AM', 'h:mm A', { hour12: 'h12' });
// => Thu Jan 01 1970 00:30:00 GMT-0800
// h11 format - midnight is 0 AM
parse('0:30 AM', 'h:mm A', { hour12: 'h11' });
// => Thu Jan 01 1970 00:30:00 GMT-0800
```
### hour24
**Type**: `"h23" | "h24"`
**Default**: `"h23"`
Controls the 24-hour format interpretation. Use `h23` for 23-hour format (0-23) or `h24` for 24-hour format (1-24).
```typescript
import { parse } from 'date-and-time';
// h23 format - midnight is 0
parse('0:30', 'H:mm', { hour24: 'h23' });
// => Thu Jan 01 1970 00:30:00 GMT-0800
// h24 format - midnight is 24 (of previous day)
parse('24:30', 'H:mm', { hour24: 'h24' });
// => Thu Jan 01 1970 00:30:00 GMT-0800
```
### ignoreCase
**Type**: `boolean`
**Default**: `false`
Enables case-insensitive parsing for text elements.
```typescript
import { parse } from 'date-and-time';
// Case-sensitive (default)
parse('august 23, 2025', 'MMMM D, YYYY');
// => Invalid Date
// Case-insensitive
parse('AUGUST 23, 2025', 'MMMM D, YYYY', { ignoreCase: true });
// => Fri Aug 23 2025 00:00:00 GMT-0700
parse('fri aug 23 2025', 'ddd MMM DD YYYY', { ignoreCase: true });
// => Fri Aug 23 2025 00:00:00 GMT-0700
```
### defaultDate
**Type**: `ParsedComponents`
**Default**: `{ Y: 1970, M: 1, D: 1, m: 0, s: 0, S: 0 }`
Specifies default values for date/time components that are missing from the format string. This is useful when parsing partial strings such as time-only or month-day formats.
```typescript
interface ParsedComponents {
Y?: number; // Year
M?: number; // Month (1-12)
D?: number; // Day
H?: number; // Hour (24-hour)
A?: number; // Meridiem (0: AM, 1: PM)
h?: number; // Hour (12-hour)
m?: number; // Minute
s?: number; // Second
S?: number; // Millisecond
Z?: number; // Timezone offset in minutes (e.g., UTC+9 = -540)
}
```
**Note**: If `defaultDate.Z` is set, it takes precedence over the `timeZone` option. `Z` is in minutes, using the same sign convention as the `Z` / `ZZ` format tokens (e.g., UTC+9 = `-540`).
```typescript
import { parse } from 'date-and-time';
// Parse time-only string — fill in date from defaultDate
parse('12:30', 'HH:mm', { defaultDate: { Y: 2024, M: 3, D: 15 } });
// => Fri Mar 15 2024 12:30:00
// Parse month-day only — fill in year from defaultDate
parse('03-15', 'MM-DD', { defaultDate: { Y: 2024 } });
// => Fri Mar 15 2024 00:00:00
// Fill in time components for a date-only format
parse('2024-03-15', 'YYYY-MM-DD', { defaultDate: { H: 10, m: 30, s: 45 } });
// => Fri Mar 15 2024 10:30:45
// defaultDate.Z takes precedence over timeZone option
parse('12:30', 'HH:mm', { defaultDate: { Y: 2024, M: 3, D: 15, Z: -540 }, timeZone: 'UTC' });
// => Fri Mar 15 2024 03:30:00 UTC (interpreted as UTC+9; timeZone: 'UTC' is ignored)
```
### plugins
**Type**: `ParserPlugin[]`
**Default**: `undefined`
Enables additional parse tokens provided by plugins. Plugins extend the parser with special tokens that are not included in the core library.
```typescript
import { parse } from 'date-and-time';
import { parser as ordinal } from 'date-and-time/plugins/ordinal';
import { parser as two_digit_year } from 'date-and-time/plugins/two-digit-year';
import { parser as microsecond } from 'date-and-time/plugins/microsecond';
// Use ordinal plugin
parse('January 1st, 2025', 'MMMM DDD, YYYY', { plugins: [ordinal] });
// => Wed Jan 01 2025 00:00:00 GMT-0800
// Use two-digit-year plugin
parse('12/25/99', 'MM/DD/YY', { plugins: [two_digit_year] });
// => Sat Dec 25 1999 00:00:00 GMT-0800
// Use microsecond plugin
parse('14:30:45.123456', 'HH:mm:ss.SSSSSS', { plugins: [microsecond] });
// => Thu Jan 01 1970 14:30:45 GMT-0800
// Use multiple plugins together
parse('January 1st, 99 14:30:45.123456', 'MMMM DDD, YY HH:mm:ss.SSSSSS', {
plugins: [ordinal, two_digit_year, microsecond]
});
// => Fri Jan 01 1999 14:30:45 GMT-0800
```
For a complete list of available plugins, see [Plugins](../plugins).
## Parsing Behavior and Limitations
### Default Date and Time Values
When parsing partial dates or times, missing components are filled with default values. The default date is `January 1, 1970`, and the default time is `00:00:00.000`.
```typescript
import { parse } from 'date-and-time';
// Only time - defaults to Jan 1, 1970
parse('14:30:45', 'HH:mm:ss');
// => Thu Jan 01 1970 14:30:45 GMT-0800
// Only date - defaults to 00:00:00
parse('2025-08-23', 'YYYY-MM-DD');
// => Fri Aug 23 2025 00:00:00 GMT-0700
// Year and month - defaults to 1st day
parse('2025-08', 'YYYY-MM');
// => Fri Aug 01 2025 00:00:00 GMT-0700
// Just year - defaults to Jan 1st, 00:00:00
parse('2025', 'YYYY');
// => Wed Jan 01 2025 00:00:00 GMT-0800
```
To customize these defaults, use the [`defaultDate`](#defaultdate) option.
### Date Range Limitations
The parsable maximum date is `December 31, 9999`, and the minimum date is `January 1, 0001`.
```typescript
import { parse } from 'date-and-time';
// Valid maximum date
parse('Dec 31 9999', 'MMM D YYYY');
// => Fri Dec 31 9999 00:00:00 GMT-0800
// Invalid - exceeds maximum
parse('Dec 31 10000', 'MMM D YYYY');
// => Invalid Date
// Valid minimum date
parse('Jan 1 0001', 'MMM D YYYY');
// => Mon Jan 1 0001 00:00:00 GMT-0800
// Invalid - below minimum
parse('Jan 1 0000', 'MMM D YYYY');
// => Invalid Date
```
### UTC Input Parsing
If the input string doesn't contain a timezone offset and no `timeZone` option is specified, the function treats the input as the local timezone. To parse input as UTC, set `timeZone: 'UTC'` in the options.
```typescript
import { parse } from 'date-and-time';
// Parsed as the local timezone
parse('14:30:45', 'HH:mm:ss');
// => Thu Jan 01 1970 14:30:45 GMT-0800
// Timezone offset in input takes precedence
parse('14:30:45 +0000', 'HH:mm:ss Z');
// => Thu Jan 01 1970 14:30:45 GMT+0000
// Force UTC parsing
parse('14:30:45', 'HH:mm:ss', { timeZone: 'UTC' });
// => Thu Jan 01 1970 14:30:45 GMT+0000
```
### 12-hour Format and Meridiem
When using 12-hour format tokens (`h` or `hh`), always include the meridiem token (`A` or `a`) for correct parsing.
```typescript
import { parse } from 'date-and-time';
// Without meridiem - ambiguous time
parse('11:30:45', 'h:mm:ss');
// => Thu Jan 01 1970 11:30:45 GMT-0800 (assumes AM)
// With meridiem - unambiguous time
parse('11:30:45 PM', 'h:mm:ss A');
// => Thu Jan 01 1970 23:30:45 GMT-0800
```
## Advanced Usage
### Comments in Format Strings
Parts of the format string enclosed in square brackets are treated as literal text:
```typescript
import { parse } from 'date-and-time';
parse('Today is Saturday, August 23, 2025', '[Today is] dddd, MMMM D, YYYY');
// => Sat Aug 23 2025 00:00:00 GMT-0700
parse('2025-08-23T14:30:45Z', 'YYYY-MM-DD[T]HH:mm:ss[Z]');
// => Sat Aug 23 2025 14:30:45 GMT-0700
parse('Report generated on 2025/08/23 at 14:30', '[Report generated on] YYYY/MM/DD [at] HH:mm');
// => Sat Aug 23 2025 14:30:00 GMT-0700
// Escape square brackets to parse them from input string
parse('[2025-08-23 14:30:45]', '\\[YYYY-MM-DD HH:mm:ss\\]');
// => Sat Aug 23 2025 14:30:45 GMT-0700
```
### Wildcard Parsing
Whitespace in the format string acts as a wildcard token, allowing you to skip corresponding parts of the input string. The character count must match between the format string and input string.
```typescript
import { parse } from 'date-and-time';
// This will fail - extra content not accounted for
parse('2025/08/23 14:30:45', 'YYYY/MM/DD');
// => Invalid Date
// Use whitespace as wildcard (9 spaces to match ' 14:30:45')
parse('2025/08/23 14:30:45', 'YYYY/MM/DD ');
// => Sat Aug 23 2025 00:00:00 GMT-0700
```
### Ellipsis Token
The `...` token ignores all subsequent content in the input string. Use this token only at the end of a format string.
```typescript
import { parse } from 'date-and-time';
// Ignore everything after the date
parse('2025/08/23 14:30:45', 'YYYY/MM/DD...');
// => Sat Aug 23 2025 00:00:00 GMT-0700
// More complex example
parse('Log entry: 2025-08-23 some extra data here', '[Log entry: ]YYYY-MM-DD...');
// => Sat Aug 23 2025 00:00:00 GMT-0700
```
### Complex Localized Parsing
```typescript
import { parse } from 'date-and-time';
import fr from 'date-and-time/locales/fr';
// French with timezone
parse('samedi, 23 août 2025 à 14:30:45', 'dddd, D MMMM YYYY [à] HH:mm:ss', {
locale: fr,
timeZone: 'Europe/Paris'
});
// => Fri Aug 23 2025 14:30:45 GMT+0200
```
### Business and Technical Formats
```typescript
import { parse } from 'date-and-time';
// ISO 8601 format
parse('2025-08-23T14:30:45.123Z', 'YYYY-MM-DD[T]HH:mm:ss.SSS[Z]', { timeZone: 'UTC' });
// => Fri Aug 23 2025 14:30:45 GMT+0000
// RFC 2822 format
parse('Sat, 23 Aug 2025 14:30:45 +0900', 'ddd, DD MMM YYYY HH:mm:ss ZZ');
// => Sat Aug 23 2025 14:30:45 GMT+0900
// File naming format
parse('20250823_143045', 'YYYYMMDD_HHmmss');
// => Sat Aug 23 2025 14:30:45 GMT-0700
```
## Error Handling
### When Parsing Fails
If the `parse()` function fails to parse the input, it returns an `Invalid Date` object. Note that `Invalid Date` is still a Date object, not `NaN` or `null`.
```typescript
import { parse } from 'date-and-time';
// Example of parsing failure
const result = parse('invalid-date', 'YYYY-MM-DD');
// Check if parsing failed
if (isNaN(result.getTime())) {
console.error('Parse failed - invalid date');
} else {
console.log('Successfully parsed:', result);
}
// Common parsing failures
parse('Jam 1 2017', 'MMM D YYYY'); // Invalid - 'Jam' is not a valid month
parse('2025-02-30', 'YYYY-MM-DD'); // Invalid - Feb 30th doesn't exist
parse('2025-13-01', 'YYYY-MM-DD'); // Invalid - month 13 doesn't exist
parse('25:30:00', 'HH:mm:ss'); // Invalid - hour 25 doesn't exist
parse('12 hours 34', 'HH hours mm'); // Invalid - format mismatch
```
## Performance Considerations
For repeated parsing with the same pattern, use [`compile()`](./compile):
```typescript
import { parse, compile } from 'date-and-time';
// Compile once
const pattern = compile('YYYY-MM-DD HH:mm:ss');
// Reuse for better performance
const dateStrings = ['2025-08-23 14:30:45', '2025-08-24 09:15:30'];
dateStrings.forEach(dateString => {
const parsed = parse(dateString, pattern);
console.log(parsed);
});
```
## Common Parsing Patterns
### Log Timestamps
```typescript
import { parse } from 'date-and-time';
const logLine = '[2025-08-23 14:30:45.123] Application started';
const timestamp = parse(logLine, ' YYYY-MM-DD HH:mm:ss.SSS ...');
// => Sat Aug 23 2025 14:30:45 GMT-0700
// For different log formats
const syslogLine = 'Aug 23 14:30:45 server: Process started';
const syslogTimestamp = parse(syslogLine, 'MMM DD HH:mm:ss...');
// => Sat Aug 23 1970 14:30:45 GMT-0700
```
### API Responses
```typescript
import { parse } from 'date-and-time';
const apiTimestamp = '2025-08-23T14:30:45Z';
const date = parse(apiTimestamp, 'YYYY-MM-DD[T]HH:mm:ss[Z]', { timeZone: 'UTC' });
```
### User Input
```typescript
import { parse } from 'date-and-time';
function parseUserDate(input: string) {
const formats = [
'YYYY-MM-DD',
'MM/DD/YYYY',
'DD.MM.YYYY',
'MMMM D, YYYY'
];
for (const format of formats) {
const result = parse(input, format);
if (!isNaN(result.getTime())) {
return result;
}
}
throw new Error('Unable to parse date');
}
```
## See Also
- [`compile()`](./compile) - Precompile format patterns for performance
- [`preparse()`](./preparse) - Parse and return intermediate parsing results
- [`isValid()`](./isValid) - Validate date string formats
================================================
FILE: docs/api/preparse.md
================================================
---
title: preparse()
---
Pre-parses date strings and returns intermediate parsing results. This function is useful when you need to examine parsing details before creating a final Date object.
## Syntax
```typescript
preparse(dateString, formatString[, options])
```
### Parameters
| Parameter | Type | Required | Description |
|----------------|----------------------------|----------|--------------------------------------------------------------------------|
| `dateString` | `string` | Yes | The date string to parse |
| `formatString` | `string \| CompiledObject` | Yes | Format pattern string or compiled object |
| `options` | `ParserOptions` | No | Parsing options for customization (see [`parse()`](./parse#parseroptions) for details) |
### Returns
`ParseResult` - Object containing parsed date components
```typescript
interface ParseResult {
Y?: number // Year
M?: number // Month (1-12)
D?: number // Day
H?: number // Hours (24-hour format, 0-23)
A?: number // AM/PM (0 = AM, 1 = PM)
h?: number // Hours (12-hour format, 1-12)
m?: number // Minutes (0-59)
s?: number // Seconds (0-59)
S?: number // Milliseconds (0-999)
SS?: number // 2-digit milliseconds (0-99)
SSS?: number // 3-digit milliseconds (0-999)
Z?: number // Timezone offset in minutes
_index?: number // Current parsing position
_length?: number // Total length of input string
_match?: number // Number of matched tokens
}
```
## Basic Examples
### Simple Date Parsing
```typescript
import { preparse } from 'date-and-time';
const result = preparse('2025-08-23 14:30:45', 'YYYY-MM-DD HH:mm:ss');
console.log(result);
// {
// Y: 2025,
// M: 8,
// D: 23,
// H: 14,
// m: 30,
// s: 45
// }
```
### With 12-hour Format
```typescript
const result = preparse('2025-08-23 2:30:45 PM', 'YYYY-MM-DD h:mm:ss A');
console.log(result);
// {
// Y: 2025,
// M: 8,
// D: 23,
// A: 1, // PM
// h: 2,
// m: 30,
// s: 45
// }
```
### With Localized Content
```typescript
import { preparse } from 'date-and-time';
import ja from 'date-and-time/locales/ja';
const result = preparse('2025年8月23日', 'YYYY年M月D日', { locale: ja });
console.log(result);
// {
// Y: 2025,
// M: 8,
// D: 23
// }
```
## ParserOptions
The `options` parameter accepts the same `ParserOptions` as the [`parse()`](./parse#parseroptions) function. This includes locale, timezone, numeral system, calendar, case sensitivity, hour format settings, and `defaultDate`. Refer to the parse documentation for complete details on all available options.
## Use Cases
### Validation Before Parsing
```typescript
import { preparse, parse, isValid } from 'date-and-time';
function safeParse(dateString: string, format: string) {
const result = preparse(dateString, format);
// Check if required components are present
if (result.Y && result.M && result.D) {
return parse(dateString, format);
}
throw new Error('Missing required date components');
}
```
### Custom Date Validation
```typescript
function validateBusinessDay(dateString: string, format: string) {
const result = preparse(dateString, format);
if (result.Y && result.M && result.D) {
const date = new Date(result.Y, result.M - 1, result.D);
const dayOfWeek = date.getDay();
if (dayOfWeek === 0 || dayOfWeek === 6) {
throw new Error('Business days only (Monday-Friday)');
}
return date;
}
throw new Error('Invalid date format');
}
```
## Error Handling
If parsing fails, `preparse()` returns an object with parsing metadata but without the main date components (Y, M, D, H, etc.).
```typescript
const result = preparse('invalid-date', 'YYYY-MM-DD');
console.log(result);
// {
// _index: 0,
// _length: 12,
// _match: 0
// }
// Check for successful parsing by looking for date components
if (!result.Y && !result.M && !result.D) {
console.log('Parsing failed - no date components found');
}
// Alternative: check the _match property
if (result._match === 0) {
console.log('Parsing failed - no tokens matched');
}
```
## See Also
- [`parse()`](./parse) - Parse formatted date strings into Date objects
- [`compile()`](./compile) - Precompile format patterns for performance
- [`isValid()`](./isValid) - Validate date string formats
================================================
FILE: docs/api/subtract.md
================================================
---
title: subtract()
---
Calculates the difference between two Date objects and returns a rich Duration object with multiple time units and formatting options.
## Syntax
```typescript
subtract(date1, date2)
```
### Parameters
| Parameter | Type | Required | Description |
|-----------|--------|----------|------------------------|
| `date1` | `Date` | Yes | The earlier/start date |
| `date2` | `Date` | Yes | The later/end date |
### Returns
`Duration` - Rich duration object containing the time difference with properties for years, months, days, hours, minutes, seconds, and milliseconds
## Basic Examples
### Calculating Time Differences
```typescript
import { subtract } from 'date-and-time';
const start = new Date(2024, 0, 1, 10, 30, 0); // January 1, 2024 10:30:00
const end = new Date(2024, 0, 1, 14, 45, 30); // January 1, 2024 14:45:30
const duration = subtract(start, end);
console.log(duration.toHours().value); // 4.258333...
console.log(duration.toMinutes().value); // 255.5
console.log(duration.toSeconds().value); // 15330
const hoursParts = duration.toHours().toParts();
console.log(hoursParts.hours); // 4
console.log(hoursParts.minutes); // 15
console.log(hoursParts.seconds); // 30
```
### Cross-Day Calculation
```typescript
const start = new Date(2024, 6, 15, 22, 30); // July 15, 2024 22:30
const end = new Date(2024, 6, 18, 8, 15); // July 18, 2024 08:15
const duration = subtract(start, end);
const daysParts = duration.toDays().toParts();
console.log(daysParts.days); // 2
console.log(daysParts.hours); // 9
console.log(daysParts.minutes); // 45
console.log(duration.toHours().value); // 57.75 (total hours as decimal)
```
### Age Calculation
```typescript
const birthDate = new Date(1990, 5, 15); // June 15, 1990
const today = new Date(); // Current date
const age = subtract(birthDate, today);
const ageParts = age.toDays().toParts();
// Note: Simple age calculation (not accounting for leap years)
console.log(`Age: ${Math.floor(ageParts.days / 365)} years`);
// Get total days lived
console.log(`Total days lived: ${ageParts.days}`);
```
## Duration Object Methods
The returned Duration object provides methods to convert and format durations. The Duration can also be directly instantiated with a millisecond value:
```typescript
class Duration {
constructor(milliseconds: number) // Create Duration instance directly
// Convert to different time units with value and formatting capabilities
toNanoseconds(): DurationDescriptor<NanosecondsParts>
toMicroseconds(): DurationDescriptor<MicrosecondsParts>
toMilliseconds(): DurationDescriptor<MillisecondsParts>
toSeconds(): DurationDescriptor<SecondsParts>
toMinutes(): DurationDescriptor<MinutesParts>
toHours(): DurationDescriptor<HoursParts>
toDays(): DurationDescriptor<DaysParts>
}
interface DurationDescriptor<T> {
value: number // Total duration in the specified unit
format: (formatString: string, numeral?: Numeral) => string // Format duration with custom pattern
toParts: () => T // Get duration broken down into parts
}
// Example part interfaces
interface HoursParts {
hours: number
minutes: number
seconds: number
milliseconds: number
microseconds: number
nanoseconds: number
}
```
### Creating Duration Instances Directly
```typescript
import { Duration } from 'date-and-time';
// Create a Duration for 2 hours (7200000 milliseconds)
const duration = new Duration(7200000);
console.log(duration.toHours().value); // 2
console.log(duration.toMinutes().value); // 120
// Format the duration
console.log(duration.toHours().format('H[h] m[m]')); // "2h 0m"
```
### Advanced Duration Formatting
```typescript
const start = new Date(2024, 7, 15, 9, 30, 45);
const end = new Date(2024, 7, 18, 16, 15, 20);
const duration = subtract(start, end);
// Various formatting options
console.log(duration.toDays().format('D[d] H[h] m[m]')); // "3d 6h 44m"
console.log(duration.toHours().format('H:mm:ss')); // "78:44:35"
console.log(duration.toMinutes().format('[Total minutes:] m')); // "Total minutes: 4724"
console.log(duration.toDays().format('D[day], H:mm:ss.SSS')); // "3day, 6:44:35.000"
```
## Use Cases
### Work Session Tracking
```typescript
const clockIn = new Date(2024, 7, 15, 9, 0); // August 15, 2024 09:00
const clockOut = new Date(2024, 7, 15, 17, 45); // August 15, 2024 17:45
const duration = subtract(clockIn, clockOut);
console.log(duration.toHours().value); // 8.75
console.log(duration.toHours().format('H:mm')); // "8:45"
console.log(duration.toHours().format('H[h] m[m]')); // "8h 45m"
```
### Performance Monitoring
```typescript
const start = performance.now();
// ... some operation ...
const end = performance.now();
// Create Duration directly from millisecond difference
const duration = new Duration(end - start);
console.log(duration.toMilliseconds().format('SSS[ms]')); // "234ms"
```
## Edge Cases and Behavior
### Negative Durations
When the first argument is later than the second argument, `subtract()` returns negative duration values. This behavior allows for flexible date comparison in either direction.
```typescript
// Comparing dates in reverse chronological order
const later = new Date(2024, 7, 15, 14, 30); // 2:30 PM
const earlier = new Date(2024, 7, 15, 10, 15); // 10:15 AM
const negativeDuration = subtract(later, earlier);
console.log(negativeDuration.toHours().value); // -4.25 (negative value)
console.log(negativeDuration.toMinutes().value); // -255 (all values are negative)
// Format methods handle negative values appropriately
console.log(negativeDuration.toHours().format('H[h] m[m]')); // "-4h 15m"
```
### Negative Zero
An edge case of negative durations occurs when the difference is negative but the integer part of certain units is zero. This affects both `toParts()` and `format()` output differently.
```typescript
// Short negative duration (less than 1 day but more than 1 hour)
const date1 = new Date(2024, 7, 15, 14, 30); // 2:30 PM
const date2 = new Date(2024, 7, 15, 12, 15); // 12:15 PM
const duration = subtract(date1, date2);
console.log(duration.toDays().value); // -0.09375 (negative but less than 1 day)
// toParts() shows negative signs on all non-zero unit values
const parts = duration.toDays().toParts();
console.log(parts); // { days: 0, hours: -2, minutes: -15, seconds: 0, ... }
// format() places a single negative sign at the beginning, potentially creating "-0"
console.log(duration.toDays().format('D[day], H:mm:ss')); // "-0day, 2:15:00"
```
## Immutability
Both input Date objects remain unchanged:
```typescript
const date1 = new Date(2024, 7, 15, 14, 30);
const date2 = new Date(2024, 7, 15, 12, 15);
const duration = subtract(date2, date1);
console.log(date1); // Unchanged
console.log(date2); // Unchanged
console.log(duration.toHours().value); // 2.25 (new Duration object)
```
## See Also
- [`addYears()`](./addYears) - Add/subtract years
- [`addMonths()`](./addMonths) - Add/subtract months
- [`addDays()`](./addDays) - Add/subtract days
- [`addHours()`](./addHours) - Add/subtract hours
- [`addMinutes()`](./addMinutes) - Add/subtract minutes
- [`addSeconds()`](./addSeconds) - Add/subtract seconds
- [`addMilliseconds()`](./addMilliseconds) - Add/subtract milliseconds
================================================
FILE: docs/api/transform.md
================================================
---
title: transform()
---
Transforms date strings from one format to another. This is a convenience function that combines parse() and format() operations.
## Syntax
```typescript
transform(dateString, sourceFormat, targetFormat[, parserOptions, formatterOptions])
```
### Parameters
| Parameter | Type | Required | Description |
|--------------------|----------------------------|----------|-------------------------------------------|
| `dateString` | `string` | Yes | The input date string to transform |
| `sourceFormat` | `string \| CompiledObject` | Yes | Source format pattern or compiled pattern |
| `targetFormat` | `string \| CompiledObject` | Yes | Target format pattern or compiled pattern |
| `parserOptions` | `ParserOptions` | No | Options for parsing the source string |
| `formatterOptions` | `FormatterOptions` | No | Options for formatting the target string |
### Returns
`string` - The transformed date string in the target format
## Basic Examples
### Format Transformation
```typescript
import { transform } from 'date-and-time';
// ISO to US format
const result = transform('2025-08-23', 'YYYY-MM-DD', 'MM/DD/YYYY');
console.log(result); // '08/23/2025'
// Add time components
const withTime = transform('2025-08-23', 'YYYY-MM-DD', 'DD/MM/YYYY HH:mm:ss');
console.log(withTime); // '23/08/2025 00:00:00'
```
### Time Format Conversion
```typescript
// 24-hour to 12-hour format
const time12 = transform('14:30:45', 'HH:mm:ss', 'h:mm:ss A');
console.log(time12); // '2:30:45 PM'
// 12-hour to 24-hour format
const time24 = transform('2:30:45 PM', 'h:mm:ss A', 'H:mm:ss');
console.log(time24); // '14:30:45'
```
### With Localized Formats
```typescript
import es from 'date-and-time/locales/es';
// Transform Spanish to English UTC
const localized = transform(
'viernes, 23 ago 2025 14:30:45 GMT+0200',
'dddd, DD MMM YYYY HH:mm:ss [GMT]Z',
'ddd, DD MMM YYYY HH:mm:ss [GMT]',
{ locale: es }
);
console.log(localized); // 'Fri, 23 Aug 2025 12:30:45 GMT'
```
### Using Compiled Patterns
```typescript
import { compile, transform } from 'date-and-time';
// Precompile for better performance
const sourcePattern = compile('YYYY-MM-DD HH:mm:ss');
const targetPattern = compile('DD/MM/YYYY h:mm:ss A');
const result = transform(
'2025-08-23 14:30:45',
sourcePattern,
targetPattern
);
console.log(result); // '23/08/2025 2:30:45 PM'
```
## Use Cases
### API Response Transformation
```typescript
function normalizeApiDates(apiResponse: any) {
// Transform API dates to display format
if (apiResponse.created_at) {
apiResponse.created_at = transform(
apiResponse.created_at,
'YYYY-MM-DD[T]HH:mm:ss[Z]',
'MMM DD, YYYY [at] h:mm A'
);
}
return apiResponse;
}
const data = { created_at: '2025-08-23T14:30:45Z' };
console.log(normalizeApiDates(data));
// { created_at: 'Aug 23, 2025 at 2:30 PM' }
```
### Batch Format Conversion
```typescript
function convertDateFormats(dates: string[], sourceFormat: string, targetFormat: string) {
return dates.map(date => transform(date, sourceFormat, targetFormat));
}
const dates = ['2025-08-23', '2025-08-24', '2025-08-25'];
const converted = convertDateFormats(dates, 'YYYY-MM-DD', 'DD/MM/YYYY');
console.log(converted);
// ['23/08/2025', '24/08/2025', '25/08/2025']
```
### Form Input Standardization
```typescript
function standardizeUserInput(userDate: string, userFormat: string) {
// Always convert user input to ISO format for storage
return transform(userDate, userFormat, 'YYYY-MM-DD');
}
const userInput = '23/08/2025';
const standardized = standardizeUserInput(userInput, 'DD/MM/YYYY');
console.log(standardized); // '2025-08-23'
```
## Implementation Details
The `transform()` function is a convenience wrapper that internally:
1. Parses the input string using the source format
2. Formats the resulting Date object using the target format
```typescript
// transform() is equivalent to:
const date = parse(dateString, sourceFormat);
const result = format(date, targetFormat);
// But provides a cleaner API:
const result = transform(dateString, sourceFormat, targetFormat);
```
## See Also
- [`format()`](./format) - Format Date objects using compiled patterns
- [`compile()`](./compile) - Precompile format patterns for performance
================================================
FILE: docs/api/utils/getDaysInMonth.md
================================================
---
title: getDaysInMonth()
---
Returns the number of days in a given month of a specific year. Correctly handles leap years when calculating February.
## Syntax
```typescript
getDaysInMonth(date)
getDaysInMonth(year, month)
```
### Parameters
| Parameter | Type | Required | Description |
|-----------|----------|------------------|----------------------------------------|
| `date` | `Date` | Yes (overload 1) | The date object whose month to examine |
| `year` | `number` | Yes (overload 2) | The Gregorian year (1–9999) |
| `month` | `number` | Yes (overload 2) | The month (1–12) |
### Returns
`number` - The number of days in the specified month
## Basic Examples
### Using a Date Object
```typescript
import { getDaysInMonth } from 'date-and-time';
getDaysInMonth(new Date(2024, 1, 1)); // => 29 (Feb 2024, leap year)
getDaysInMonth(new Date(2023, 1, 1)); // => 28 (Feb 2023, not a leap year)
getDaysInMonth(new Date(2025, 0, 1)); // => 31 (January 2025)
```
### Using Year and Month Numbers
```typescript
import { getDaysInMonth } from 'date-and-time';
getDaysInMonth(2024, 2); // => 29 (Feb 2024, leap year)
getDaysInMonth(2023, 2); // => 28 (Feb 2023, not a leap year)
getDaysInMonth(2025, 4); // => 30 (April 2025)
getDaysInMonth(2025, 12); // => 31 (December 2025)
```
## See Also
- [`isLeapYear()`](./isLeapYear) - Check if a year is a leap year
- [`addMonths()`](../addMonths) - Add months to a date
================================================
FILE: docs/api/utils/getISOWeek.md
================================================
---
title: getISOWeek()
---
Returns the ISO 8601 week number (1–53) for a given date. ISO weeks start on Monday, and week 1 is the week containing the first Thursday of the year.
## Syntax
```typescript
getISOWeek(date)
getISOWeek(year, month, day)
```
### Parameters
| Parameter | Type | Required | Description |
|-----------|----------|------------------|-----------------------------|
| `date` | `Date` | Yes (overload 1) | The date object to examine |
| `year` | `number` | Yes (overload 2) | The Gregorian year (1–9999) |
| `month` | `number` | Yes (overload 2) | The month (1–12) |
| `day` | `number` | Yes (overload 2) | The day (1–31) |
### Returns
`number` - The ISO week number (1–53) for the given date
## Basic Examples
### Using a Date Object
```typescript
import { getISOWeek } from 'date-and-time';
getISOWeek(new Date(2025, 0, 1)); // => 1 (Jan 1, 2025 is in week 1)
getISOWeek(new Date(2025, 5, 15)); // => 24 (Jun 15, 2025 is in week 24)
```
### Using Year, Month, and Day
```typescript
import { getISOWeek } from 'date-and-time';
getISOWeek(2025, 1, 1); // => 1
getISOWeek(2025, 6, 15); // => 24
```
### Years with Week 53
Some years have 53 ISO weeks (when January 1 is a Thursday, or a Wednesday in a leap year):
```typescript
import { getISOWeek } from 'date-and-time';
getISOWeek(new Date(2020, 11, 31)); // => 53 (Dec 31, 2020)
getISOWeek(2020, 12, 31); // => 53
```
## See Also
- [`getISOWeekYear()`](./getISOWeekYear) - Get the ISO week year for a date
- [week plugin](../../plugins#week) - Format ISO week dates with `format()`
================================================
FILE: docs/api/utils/getISOWeekYear.md
================================================
---
title: getISOWeekYear()
---
Returns the ISO 8601 week year for a given date. The ISO week year may differ from the calendar year near the start and end of the year, because ISO weeks always start on Monday and the first week of the year is the one containing the first Thursday of the year.
## Syntax
```typescript
getISOWeekYear(date)
getISOWeekYear(year, month, day)
```
### Parameters
| Parameter | Type | Required | Description |
|-----------|----------|------------------|-----------------------------|
| `date` | `Date` | Yes (overload 1) | The date object to examine |
| `year` | `number` | Yes (overload 2) | The Gregorian year (1–9999) |
| `month` | `number` | Yes (overload 2) | The month (1–12) |
| `day` | `number` | Yes (overload 2) | The day (1–31) |
### Returns
`number` - The ISO week year corresponding to the given date
## Basic Examples
### Using a Date Object
```typescript
import { getISOWeekYear } from 'date-and-time';
getISOWeekYear(new Date(2025, 5, 15)); // => 2025 (mid-year, same as calendar year)
```
### Year Boundary Cases
Near year boundaries, the ISO week year can differ from the calendar year:
```typescript
import { getISOWeekYear } from 'date-and-time';
// Dec 30, 2024 is in ISO week 1 of 2025
getISOWeekYear(new Date(2024, 11, 30)); // => 2025
getISOWeekYear(2024, 12, 30); // => 2025
// Jan 1, 2016 is in ISO week 53 of 2015
getISOWeekYear(new Date(2016, 0, 1)); // => 2015
getISOWeekYear(2016, 1, 1); // => 2015
```
## See Also
- [`getISOWeek()`](./getISOWeek) - Get the ISO week number for a date
- [week plugin](../../plugins#week) - Format ISO week dates with `format()`
================================================
FILE: docs/api/utils/isLeapYear.md
================================================
---
title: isLeapYear()
---
Determines if a given year is a leap year according to the Gregorian calendar rules.
## Syntax
```typescript
isLeapYear(year)
```
### Parameters
| Parameter | Type | Required | Description |
|-----------|----------|----------|-------------------|
| `year` | `number` | Yes | The year to check |
### Returns
`boolean` - Returns `true` if the year is a leap year, `false` otherwise
## Basic Examples
### Checking Leap Years
```typescript
import { isLeapYear } from 'date-and-time';
console.log(isLeapYear(2024)); // true (divisible by 4)
console.log(isLeapYear(2023)); // false (not divisible by 4)
console.log(isLeapYear(2000)); // true (divisible by 400)
console.log(isLeapYear(1900)); // false (divisible by 100 but not by 400)
```
### Working with Date Objects
```typescript
function checkDateLeapYear(date: Date): boolean {
return isLeapYear(date.getFullYear());
}
const dates = [
new Date(2024, 1, 29), // February 29, 2024
new Date(2023, 1, 28), // February 28, 2023
new Date(2000, 1, 29) // February 29, 2000
];
dates.forEach(date => {
const year = date.getFullYear();
console.log(`${year}: ${isLeapYear(year) ? 'Leap year' : 'Not a leap year'}`);
});
```
## Edge Cases
### Historical Context
```typescript
// Note: Gregorian calendar was adopted in 1582
// Before that, different leap year rules applied
function isHistoricalAccurate(year: number): boolean {
if (year < 1582) {
console.warn('Year is before Gregorian calendar adoption (1582)');
// Julian calendar had simpler rule: every 4 years
return year % 4 === 0;
}
return isLeapYear(year);
}
console.log(isHistoricalAccurate(1500)); // true (Julian calendar rule)
console.log(isHistoricalAccurate(1700)); // false (Gregorian calendar rule)
```
================================================
FILE: docs/api/utils/isSameDay.md
================================================
---
title: isSameDay()
---
Checks if two Date objects represent the same calendar day, regardless of time.
## Syntax
```typescript
isSameDay(date1, date2)
```
### Parameters
| Parameter | Type | Required | Description |
|-----------|--------|----------|-----------------------------------|
| `date1` | `Date` | Yes | The first Date object to compare |
| `date2` | `Date` | Yes | The second Date object to compare |
### Returns
`boolean` - Returns `true` if both dates are on the same calendar day, `false` otherwise
## Basic Examples
### Comparing Calendar Days
```typescript
import { isSameDay } from 'date-and-time';
const morning = new Date(2024, 7, 15, 9, 30, 0); // August 15, 2024 09:30:00
const evening = new Date(2024, 7, 15, 18, 45, 30); // August 15, 2024 18:45:30
const nextDay = new Date(2024, 7, 16, 9, 30, 0); // August 16, 2024 09:30:00
console.log(isSameDay(morning, evening)); // true (same day, different times)
console.log(isSameDay(morning, nextDay)); // false (different days)
```
### Ignoring Time Components
```typescript
const startOfDay = new Date(2024, 7, 15, 0, 0, 0, 0); // August 15, 2024 00:00:00.000
const endOfDay = new Date(2024, 7, 15, 23, 59, 59, 999); // August 15, 2024 23:59:59.999
console.log(isSameDay(startOfDay, endOfDay)); // true
// Even milliseconds don't matter for day comparison
const precise1 = new Date(2024, 7, 15, 12, 30, 45, 123);
const precise2 = new Date(2024, 7, 15, 12, 30, 45, 456);
console.log(isSameDay(precise1, precise2)); // true
```
================================================
FILE: docs/content.config.ts
================================================
import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { docsSchema } from '@astrojs/starlight/schema';
export const collections = {
docs: defineCollection({
loader: glob({
pattern: '**/*.{md,mdx}',
base: './docs',
}),
schema: docsSchema(),
}),
};
================================================
FILE: docs/env.d.ts
================================================
/// <reference types="astro/client" />
================================================
FILE: docs/guide/index.md
================================================
---
title: Introduction
---
**date-and-time** is the simplest, most intuitive date and time library for JavaScript and TypeScript. Built from the ground up with modern development practices, it provides a comprehensive set of tools for date manipulation, formatting, parsing, and timezone handling.
## Why date-and-time?
### 🚀 Modern & Performant
- Written entirely in **TypeScript** with ES2021 target
- **Tree-shakable** modules for optimal bundle size
- **Zero dependencies** for core functionality
- Full **ES Modules** and **CommonJS** support
### 🌍 Internationalization Ready
- Support for **40+ locales** with native month/day names
- Multiple **calendar systems** (Gregorian, Buddhist)
- **Numeral systems** (Latin, Arabic, Bengali, Myanmar)
- **Timezone-aware** formatting and parsing
### 🎯 Developer Experience
- **Full TypeScript** support with comprehensive type definitions
- **IntelliSense** support in modern editors
- **Consistent API** design across all functions
- **Extensive documentation** and examples
### 📦 Production Ready
- **Node.js 18+** support
- **Modern browser** compatibility (Chrome 85+, Firefox 78+, Safari 14+)
- **Comprehensive test suite** with high coverage
- **Battle-tested** in production environments
## Key Features
### Formatting and Parsing
- **`format()`** - Convert Date objects to formatted strings
- **`parse()`** - Parse date strings into Date objects
- **`compile()`** - Precompile format strings for performance
- **`preparse()`** - Parse date strings and return intermediate results
- **`isValid()`** - Validate date string formats
- **`transform()`** - Transform date strings between different formats
### Date Arithmetic
- **`addYears()`, `addMonths()`, `addDays()`** - Date addition
- **`addHours()`, `addMinutes()`, `addSeconds()`, `addMilliseconds()`** - Time addition
- **`subtract()`** - Calculate time differences with Duration objects
### Utility Functions
- **`isLeapYear()`** - Check if a year is a leap year
- **`isSameDay()`** - Check if two dates are on the same day
- **`getDaysInMonth()`** - Get the number of days in a month
- **`getISOWeekYear()`** - Get the ISO week year for a date (follows ISO 8601)
- **`getISOWeek()`** - Get the ISO week number for a date (1–53, follows ISO 8601)
### Advanced Features
- **Timezone Support** - Comprehensive timezone data from timezonedb
- **Locale Support** - 40+ languages with native formatting
- **Plugin System** - Extend formatters and parsers
- **Duration Objects** - Rich time difference calculations
## Version 4.x Highlights
Version 4.x represents a complete rewrite with significant improvements:
### 🔄 Breaking Changes
- **TypeScript-first** development approach
- **Integrated plugins** - timezone and timespan functionality built-in
- **New API signatures** - options objects replace boolean parameters
- **Modern JavaScript** - ES2021 features throughout
### 📈 Performance Improvements
- **Reduced bundle size** with tree-shaking
### 🛠 Developer Improvements
- **Expanded language support** - Now supporting 40+ locales
- **Improved TypeScript** inference and completion
- **Comprehensive documentation** with live examples
## Architecture
```typescript
import { format, parse } from 'date-and-time';
import ja from 'date-and-time/locales/ja';
// Core functionality
const date = new Date();
const formatted = format(date, 'YYYY/MM/DD');
// Localized formatting
const localized = format(date, 'YYYY年M月D日', { locale: ja });
// Timezone-aware operations
const tokyoTime = format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: 'Asia/Tokyo' });
```
## Browser and Environment Support
### Node.js
- **Node.js 18.0.0+** (LTS recommended)
- Full ES Modules support
- CommonJS compatibility
### Browsers
| Browser | Minimum Version |
|---------|-----------------|
| Chrome | 85+ |
| Firefox | 78+ |
| Safari | 14+ |
| Edge | 85+ |
### Module Systems
- **ES Modules** (`.mjs`, `type: "module"`)
- **CommonJS** (`.cjs`, traditional Node.js)
- **TypeScript** (4.5+)
- **Bundlers** (Webpack, Rollup, Vite, etc.)
## Getting Started
Ready to start using date-and-time? Continue to the [Installation Guide](./installation) to set up the library in your project.
================================================
FILE: docs/guide/installation.mdx
================================================
---
title: Installation
---
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
Get started with date-and-time in your project using your preferred package manager.
## Package Manager Installation
<Tabs>
<TabItem label="npm">
```bash
npm install date-and-time
```
</TabItem>
<TabItem label="yarn">
```bash
yarn add date-and-time
```
</TabItem>
<TabItem label="pnpm">
```bash
pnpm add date-and-time
```
</TabItem>
</Tabs>
## Requirements
### Runtime Requirements
- **Node.js**: Version 18.0.0 or higher
- **Browsers**: ES2021 support required
### Development Requirements (optional)
- **TypeScript**: Version 4.5 or higher for full type support
- **Modern bundler**: For optimal tree-shaking (Webpack 5+, Rollup, Vite, etc.)
## Import Methods
date-and-time supports both ES Modules and CommonJS, allowing you to use the import style that best fits your project.
### ES Modules (Recommended)
```typescript
import { format, parse } from 'date-and-time';
format(new Date(), 'YYYY/MM/DD');
// => 2025/08/23
```
### CommonJS
```typescript
const { format, parse } = require('date-and-time');
format(new Date(), 'YYYY/MM/DD');
// => 2025/08/23
```
## Importing Locales and Timezones
Locales and timezones are distributed as separate modules to support tree shaking:
### Locale Imports
```typescript
// Import specific locales
import ja from 'date-and-time/locales/ja';
import es from 'date-and-time/locales/es';
import fr from 'date-and-time/locales/fr';
// Use in formatting
format(new Date(), 'YYYY年M月D日', { locale: ja });
format(new Date(), 'D [de] MMMM [de] YYYY', { locale: es });
format(new Date(), 'D MMMM YYYY', { locale: fr });
```
For a complete list of all supported locales with import examples, see [Supported Locales](../locales).
### Timezone Usage
Pass an IANA timezone name string directly to any function that accepts a timezone option:
```typescript
format(new Date(), 'YYYY-MM-DD HH:mm:ss', { timeZone: 'Asia/Tokyo' });
format(new Date(), 'YYYY-MM-DD HH:mm:ss', { timeZone: 'America/New_York' });
```
For a complete list of all supported timezones, see [Supported Timezones](../timezones).
### Numeral Systems
```typescript
// Import numeral systems
import arab from 'date-and-time/numerals/arab';
import beng from 'date-and-time/numerals/beng';
format(new Date(), 'DD/MM/YYYY', { numeral: arab });
// => ٠٨/٠٧/٢٠٢٥
```
## Plugin Imports
Some advanced features are available as plugins:
```typescript
import { format } from 'date-and-time';
// Import specific plugins
import microsecond from 'date-and-time/plugins/microsecond';
import ordinal from 'date-and-time/plugins/ordinal';
import zonename from 'date-and-time/plugins/zonename';
// Use plugin-specific tokens with plugins specified in options
format(new Date(), 'MMMM DDD, YYYY', { plugins: [ordinal] }); // with ordinal plugin
format(new Date(), 'HH:mm:ss.SSSSSS', { plugins: [microsecond] }); // with microsecond plugin
```
## CDN Usage
For browser-only projects, you can use date-and-time directly from a CDN:
### Via jsDelivr
```html
<script type="module">
import { format } from 'https://cdn.jsdelivr.net/npm/date-and-time/dist/index.js';
console.log(format(new Date(), 'YYYY/MM/DD'));
</script>
```
### Via unpkg
```html
<script type="module">
import { format } from 'https://unpkg.com/date-and-time/dist/index.js';
console.log(format(new Date(), 'YYYY/MM/DD'));
</script>
```
## Bundle Size
<Aside type="tip" title="Tree Shaking Benefits">
date-and-time is built with tree-shaking in mind. You only bundle the functions and locales you actually use, resulting in optimal bundle sizes. Modern bundlers like Webpack 5, Rollup, and Vite automatically eliminate unused code, ensuring your application stays lightweight.
</Aside>
## Verification
After installation, verify that the library works correctly:
```typescript
import { format } from 'date-and-time';
console.log(format(new Date(), 'YYYY/MM/DD HH:mm:ss'));
// Should output current date in YYYY/MM/DD HH:mm:ss format
```
## Next Steps
Now that you have date-and-time installed, you can:
1. **[Quick Start](./quick-start)** - Learn the basics with simple examples
2. **[API Reference](/api/)** - Dive deep into all available functions
## Troubleshooting
### TypeScript Issues
If you encounter TypeScript errors, ensure you're using TypeScript 4.5+ and have the latest version of date-and-time:
```bash
npm install typescript@latest date-and-time@latest
```
### Module Resolution Issues
For Node.js projects using ES Modules, ensure your `package.json` includes:
```json
{
"type": "module"
}
```
For CommonJS projects, this field should be omitted or set to `"commonjs"`.
================================================
FILE: docs/guide/quick-start.md
================================================
---
title: Quick Start
---
This guide will get you up and running with date-and-time in just a few minutes.
## Basic Example
```typescript
import { format, parse } from 'date-and-time';
const now = new Date();
// Format a date
const formatted = format(now, 'YYYY/MM/DD HH:mm:ss');
console.log(formatted);
// => 2025/08/23 14:30:45
// Parse a date string
const parsed = parse('2025/08/23 14:30:45', 'YYYY/MM/DD HH:mm:ss');
console.log(parsed);
// => Fri Aug 23 2025 14:30:45 GMT+0900
```
## Common Format Patterns
### Date Formats
```typescript
import { format } from 'date-and-time';
const date = new Date();
format(date, 'YYYY-MM-DD'); // => 2025-08-23
format(date, 'MM/DD/YYYY'); // => 08/23/2025
format(date, 'DD.MM.YYYY'); // => 23.08.2025
format(date, 'MMMM D, YYYY'); // => August 23, 2025
format(date, 'ddd, MMM DD YYYY'); // => Sat, Aug 23 2025
```
### Time Formats
```typescript
format(date, 'HH:mm:ss'); // => 14:30:45 (24-hour)
format(date, 'hh:mm:ss A'); // => 02:30:45 PM (12-hour)
format(date, 'h:mm A'); // => 2:30 PM (12-hour, no leading zero)
```
### Combined DateTime Formats
```typescript
format(date, 'YYYY-MM-DD HH:mm:ss'); // => 2025-08-23 14:30:45
format(date, 'ddd, MMM D, YYYY [at] h:mm A');
// => Sat, Aug 23, 2025 at 2:30 PM
format(date, '[Today is] dddd'); // => Today is Saturday
```
## Working with Locales
```typescript
import { format } from 'date-and-time';
import ja from 'date-and-time/locales/ja';
import es from 'date-and-time/locales/es';
import fr from 'date-and-time/locales/fr';
const date = new Date();
// Japanese
format(date, 'YYYY年M月D日(ddd)', { locale: ja });
// => 2025年8月23日(土)
// Spanish
format(date, 'dddd, D [de] MMMM [de] YYYY', { locale: es });
// => sábado, 23 de agosto de 2025
// French
format(date, 'dddd D MMMM YYYY', { locale: fr });
// => samedi 23 août 2025
```
For a complete list of all supported locales with import examples, see [Supported Locales](../locales).
## Timezone Operations
```typescript
import { format, parse } from 'date-and-time';
const date = new Date();
// Format in a specific timezone
format(date, 'YYYY-MM-DD HH:mm:ss [EST]', { timeZone: 'America/New_York' });
// => 2025-08-23 09:30:45 EST
// UTC formatting
format(date, 'YYYY-MM-DD HH:mm:ss [UTC]', { timeZone: 'UTC' });
// => 2025-08-23 14:30:45 UTC
// Parsing in timezone
parse('2025-08-23 23:30:45', 'YYYY-MM-DD HH:mm:ss', { timeZone: 'Asia/Tokyo' });
// => Fri Aug 23 2025 23:30:45 GMT+0900
```
For a complete list of all supported timezones, see [Supported Timezones](../timezones).
## Date Arithmetic
```typescript
import { addDays, addHours, addMonths, subtract } from 'date-and-time';
const date = new Date(2025, 7, 23); // Aug 23, 2025
// Add time
const nextWeek = addDays(date, 7); // Aug 30, 2025
const nextMonth = addMonths(date, 1); // Sep 23, 2025
const inFiveHours = addHours(date, 5); // Aug 23, 2025 05:00:00
// Subtract time (use negative values)
const lastWeek = addDays(date, -7); // Aug 16, 2025
// Calculate differences
const start = new Date(2025, 7, 23, 10, 0, 0);
const end = new Date(2025, 7, 23, 14, 30, 0);
const duration = subtract(start, end);
console.log(duration.toHours().value); // => 4.5
console.log(duration.toMinutes().value); // => 270
```
## Validation
```typescript
import { isValid, parse } from 'date-and-time';
// Check if a date string is valid
isValid('2025/08/23', 'YYYY/MM/DD'); // => true
isValid('2025/02/30', 'YYYY/MM/DD'); // => false (no Feb 30th)
isValid('invalid-date', 'YYYY/MM/DD'); // => false
// Safe parsing with validation
if (isValid('2025/08/23', 'YYYY/MM/DD')) {
const date = parse('2025/08/23', 'YYYY/MM/DD');
console.log('Parsed successfully:', date);
} else {
console.log('Invalid date format');
}
```
## Performance Optimization
For repeated operations with the same format pattern, use `compile()`:
```typescript
import { compile, format, parse } from 'date-and-time';
// Compile the pattern once
const pattern = compile('YYYY/MM/DD HH:mm:ss');
// Reuse for multiple operations (faster)
const dates = [new Date(), new Date(), new Date()];
dates.forEach(date => {
console.log(format(date, pattern));
});
```
## Error Handling
```typescript
import { parse } from 'date-and-time';
// parse() returns Invalid Date on failure
const result = parse('invalid-date', 'YYYY/MM/DD');
// Check for parsing errors
if (isNaN(result.getTime())) {
console.error('Failed to parse date');
} else {
console.log('Successfully parsed:', result);
}
```
## Next Steps
Now that you're familiar with the basics:
1. **[API Reference](/api/)** - Explore all available functions
2. **[Plugins](../plugins)** - Extend functionality with microsecond precision, ordinals, and more
3. **[Migration Guide](../migration)** - If upgrading from v3.x
================================================
FILE: docs/index.mdx
================================================
---
title: date-and-time
description: The simplest, most intuitive date and time library
template: splash
hero:
title: The simplest, most intuitive date and time library
tagline: Modern TypeScript library for date manipulation with full ES Modules support.
image:
alt: date-and-time
file: ./assets/logo.png
actions:
- text: Get Started
link: /date-and-time/guide
icon: right-arrow
variant: primary
- text: API Reference
link: /date-and-time/api
variant: minimal
- text: View on GitHub
link: https://github.com/knowledgecode/date-and-time
icon: external
variant: minimal
---
import { Card, CardGrid, Tabs, TabItem } from '@astrojs/starlight/components';
## Features
<CardGrid>
<Card title="Modern & Fast" icon="rocket">
Written in TypeScript with ES2021 target. Tree-shakable modules for optimal bundle size.
</Card>
<Card title="Internationalization" icon="translate">
Support for 40+ locales and multiple calendar systems. Arabic, Bengali, Myanmar numerals.
</Card>
<Card title="Timezone Support" icon="moon">
Complete timezone handling with IANA timezone database built-in.
</Card>
<Card title="Type Safe" icon="approve-check">
Full TypeScript support with comprehensive type definitions and IntelliSense.
</Card>
<Card title="Tree Shakable" icon="puzzle">
Import only what you need. Optimized for modern bundlers with sideEffects false.
</Card>
<Card title="Plugin System" icon="add-document">
Extensible plugin system allows you to extend formatters and parsers.
</Card>
</CardGrid>
## Quick Example
```typescript
import { format, parse, addDays } from 'date-and-time';
import ja from 'date-and-time/locales/ja';
const now = new Date();
// Basic formatting
format(now, 'YYYY/MM/DD HH:mm:ss');
// => 2025/08/23 14:30:45
// Localized formatting
format(now, 'YYYY年M月D日(ddd)', { locale: ja });
// => 2025年8月23日(金)
// Timezone-aware formatting
format(now, 'YYYY-MM-DD HH:mm:ss [EST]', { timeZone: 'America/New_York' });
// => 2025-08-23 09:30:45 EST
// Parsing
const date = parse('2025/08/23 14:30:45', 'YYYY/MM/DD HH:mm:ss');
console.log(date)
// Date arithmetic
const futureDate = addDays(now, 7);
console.log(format(futureDate, 'YYYY/MM/DD'));
```
## Key Features in v4.x
- **Complete TypeScript rewrite** with enhanced type safety
- **Tree-shaking support** for better bundle optimization
- **Integrated timezone and timespan plugins** into the core library
- **Modern JavaScript** targeting ES2021 (Node.js ≥18 required)
- **Enhanced API** with options objects instead of boolean flags
- **Improved locale handling** with per-function locale specification
## Browser & Environment Support
- **Node.js**: 18+
- **Browsers**: Chrome 85+, Firefox 78+, Safari 14+, Edge 85+
- **Module Systems**: ES Modules, CommonJS
- **TypeScript**: 4.5+
## Installation
<Tabs>
<TabItem label="npm">
```bash
npm install date-and-time
```
</TabItem>
<TabItem label="yarn">
```bash
yarn add date-and-time
```
</TabItem>
<TabItem label="pnpm">
```bash
pnpm add date-and-time
```
</TabItem>
</Tabs>
## Community
- [GitHub Repository](https://github.com/knowledgecode/date-and-time)
- [npm Package](https://www.npmjs.com/package/date-and-time)
- [Issue Tracker](https://github.com/knowledgecode/date-and-time/issues)
================================================
FILE: docs/locales.md
================================================
---
title: Locales
---
Locales customize the language-specific strings used in date formatting and parsing — month names, day-of-week names, and AM/PM indicators. By default, the library uses English (`en`). To use another language, import the corresponding locale module and pass it as the `locale` option.
```typescript
import { format, parse } from 'date-and-time';
import es from 'date-and-time/locales/es';
const date = new Date('2025-08-23T12:00:00');
format(date, 'MMMM D, YYYY', { locale: es });
// => agosto 23, 2025
format(date, 'ddd, D MMM', { locale: es });
// => sáb, 23 ago
```
## Supported Locales
The following 41 locales are available:
### ar (Arabic)
```typescript
import ar from 'date-and-time/locales/ar';
```
### az (Azerbaijani)
```typescript
import az from 'date-and-time/locales/az';
```
### bn (Bengali)
```typescript
import bn from 'date-and-time/locales/bn';
```
### cs (Czech)
```typescript
import cs from 'date-and-time/locales/cs';
```
### da (Danish)
```typescript
import da from 'date-and-time/locales/da';
```
### de (German)
```typescript
import de from 'date-and-time/locales/de';
```
### el (Greek)
```typescript
import el from 'date-and-time/locales/el';
```
### en (English)
```typescript
import en from 'date-and-time/locales/en';
```
### es (Spanish)
```typescript
import es from 'date-and-time/locales/es';
```
### fa (Persian)
```typescript
import fa from 'date-and-time/locales/fa';
```
### fi (Finnish)
```typescript
import fi from 'date-and-time/locales/fi';
```
### fr (French)
```typescript
import fr from 'date-and-time/locales/fr';
```
### he (Hebrew)
```typescript
import he from 'date-and-time/locales/he';
```
### hi (Hindi)
```typescript
import hi from 'date-and-time/locales/hi';
```
### hu (Hungarian)
```typescript
import hu from 'date-and-time/locales/hu';
```
### id (Indonesian)
```typescript
import id from 'date-and-time/locales/id';
```
### it (Italian)
```typescript
import it from 'date-and-time/locales/it';
```
### ja (Japanese)
```typescript
import ja from 'date-and-time/locales/ja';
```
### ko (Korean)
```typescript
import ko from 'date-and-time/locales/ko';
```
### ms (Malay)
```typescript
import ms from 'date-and-time/locales/ms';
```
### my (Burmese)
```typescript
import my from 'date-and-time/locales/my';
```
### nl (Dutch)
```typescript
import nl from 'date-and-time/locales/nl';
```
### no (Norwegian)
```typescript
import no from 'date-and-time/locales/no';
```
### pl (Polish)
```typescript
import pl from 'date-and-time/locales/pl';
```
### pt-BR (Brazilian Portuguese)
```typescript
import ptBR from 'date-and-time/locales/pt-BR';
```
### pt-PT (European Portuguese)
```typescript
import ptPT from 'date-and-time/locales/pt-PT';
```
### ro (Romanian)
```typescript
import ro from 'date-and-time/locales/ro';
```
### ru (Russian)
```typescript
import ru from 'date-and-time/locales/ru';
```
### rw (Kinyarwanda)
```typescript
import rw from 'date-and-time/locales/rw';
```
### sr-Cyrl (Serbian Cyrillic)
```typescript
import srCyrl from 'date-and-time/locales/sr-Cyrl';
```
### sr-Latn (Serbian Latin)
```typescript
import srLatn from 'date-and-time/locales/sr-Latn';
```
### sv (Swedish)
```typescript
import sv from 'date-and-time/locales/sv';
```
### ta (Tamil)
```typescript
import ta from 'date-and-time/locales/ta';
```
### th (Thai)
```typescript
import th from 'date-and-time/locales/th';
```
### tr (Turkish)
```typescript
import tr from 'date-and-time/locales/tr';
```
### uk (Ukrainian)
```typescript
import uk from 'date-and-time/locales/uk';
```
### uz-Cyrl (Uzbek Cyrillic)
```typescript
import uzCyrl from 'date-and-time/locales/uz-Cyrl';
```
### uz-Latn (Uzbek Latin)
```typescript
import uzLatn from 'date-and-time/locales/uz-Latn';
```
### vi (Vietnamese)
```typescript
import vi from 'date-and-time/locales/vi';
```
### zh-Hans (Simplified Chinese)
```typescript
import zhHans from 'date-and-time/locales/zh-Hans';
```
### zh-Hant (Traditional Chinese)
```typescript
import zhHant from 'date-and-time/locales/zh-Hant';
```
================================================
FILE: docs/migration.md
================================================
---
title: Migration Guide
---
Version `4.x` has been completely rewritten in TypeScript and some features from `3.x` are no longer compatible. This section explains the changes to each feature and the migration methods.
## Installation
Version `4.x` adopts a modern development style and no longer supports older browsers. Module imports are only supported in ES Modules or CommonJS style. Additionally, since functions can now be imported directly, it is more likely to reduce the final module size through bundler tree shaking.
### ES Modules (Recommended)
```typescript
import { format } from 'date-and-time';
format(new Date(), 'ddd, MMM DD YYYY');
// => Wed, Jul 09 2025
```
### CommonJS
```typescript
const { format } = require('date-and-time');
format(new Date(), 'ddd, MMM DD YYYY');
// => Wed, Jul 09 2025
```
## CDN Usage
For browser-only projects, you can use date-and-time directly from a CDN:
### Via jsDelivr
```html
<script type="module">
import { format } from 'https://cdn.jsdelivr.net/npm/date-and-time/dist/index.js';
console.log(format(new Date(), 'YYYY/MM/DD'));
</script>
```
### Via unpkg
```html
<script type="module">
import { format } from 'https://unpkg.com/date-and-time/dist/index.js';
console.log(format(new Date(), 'YYYY/MM/DD'));
</script>
```
## API
### format
The third argument has been changed from `boolean` to `FormatterOptions`. With `FormatterOptions`, you can now specify timezone and locale settings. If you previously set the third argument to `true` to output in UTC timezone, you can achieve the same output as follows:
```typescript
import { format } from 'date-and-time';
format(new Date(), 'ddd, MMM DD YYYY hh:mm A [GMT]Z', { timeZone: 'UTC' });
// => Fri, Jan 02 2015 07:14 AM GMT+0000
```
Additionally, since the `timezone` plugin has been integrated into the main library, the `formatTZ` function is now obsolete. Pass an IANA timezone name string directly to the `timeZone` option:
```typescript
import { format } from 'date-and-time';
const now = new Date();
format(now, 'YYYY-MM-DD HH:mm:ss [EST]', { timeZone: 'America/New_York' });
// => 2025-08-23 09:30:45 EST
```
### parse
The third argument has been changed from `boolean` to `ParserOptions`. With `ParserOptions`, you can now specify timezone and locale settings. If you previously set the third argument to `true` to parse input in UTC timezone, you can achieve the same output as follows:
```typescript
import { parse } from 'date-and-time';
parse('11:14:05 PM', 'h:mm:ss A', { timeZone: 'UTC' });
// => Jan 02 1970 23:14:05 GMT+0000
```
Additionally, since the `timezone` plugin has been integrated into the main library, the `parseTZ` function is now obsolete. Pass an IANA timezone name string directly to the `timeZone` option:
```typescript
import { parse } from 'date-and-time';
import fr from 'date-and-time/locales/fr';
parse(
'02 janv. 2015, 11:14:05 PM', 'DD MMM YYYY, h:mm:ss A',
{ timeZone: 'Europe/Paris', locale: fr }
);
// => Jan 02 2015 23:14:05 GMT+0100
```
### preparse
The third argument has been changed from `boolean` to `ParserOptions`. With `ParserOptions`, you can now specify timezone and locale settings. If you previously set the third argument to `true` to parse input in UTC timezone, you can achieve the same output as follows:
```typescript
import { preparse } from 'date-and-time';
preparse('11:14:05 PM', 'h:mm:ss A', { timeZone: 'UTC' });
{
A: 1,
h: 11,
m: 14,
s: 5,
_index: 11,
_length: 11,
_match: 4
}
```
Additionally, the `PreparseResult` object returned by the `preparse` function has the following changes:
- Properties for tokens that were not read are not included. For example, in the code example above, since the string does not contain a date part, properties representing dates such as `Y`, `M`, and `D` are not included.
- Read values are returned as-is. For example, previously, time read in 12-hour format was converted to 24-hour format, but this is no longer done.
### isValid
The following usage that takes `PreparseResult` as an argument is now obsolete.
```typescript
import { isValid, preparse } from 'date-and-time';
const pr = preparse('11:14:05 PM', 'h:mm:ss A');
// This usage is no longer supported
isValid(pr);
```
Other changes are the same as for the `parse` function.
### transform
The fourth argument has been changed from `boolean` to `FormatterOptions`. With `FormatterOptions`, you can now specify timezone and locale settings. Additionally, `ParserOptions` has been added as a parameter before `FormatterOptions`. Since the `timezone` plugin has been integrated into the main library, the `transformTZ` function is now obsolete.
```typescript
import { transform } from 'date-and-time';
// Convert 24-hour format to 12-hour format
transform('13:05', 'HH:mm', 'hh:mm A', { timeZone: 'UTC' }, { timeZone: 'UTC' });
// => 01:05 PM
// Convert East Coast time to West Coast time
transform(
'3/8/2020 1:05 PM', 'D/M/YYYY h:mm A', 'D/M/YYYY h:mm A',
{ timeZone: 'America/New_York' }, { timeZone: 'America/Los_Angeles' }
);
// => 3/8/2020 10:05 AM
```
### addYears
The third argument has been changed from `boolean` to `TimeZone | UTC`. If you previously set the third argument to `true` to calculate in UTC timezone, you can achieve the same output as follows:
```typescript
import { addYears } from 'date-and-time';
const now = new Date(Date.UTC(2024, 2, 11, 1));
// => Mar 11 2024 01:00:00 GMT+0000
addYears(now, 1, 'UTC');
// => Mar 11 2025 01:00:00 GMT+0000
```
Additionally, since the `timezone` plugin has been integrated into the main library, the `addYearsTZ` function is now obsolete. Pass an IANA timezone name string directly:
```typescript
import { addYears } from 'date-and-time';
const now = new Date(2024, 2, 11, 1);
// => Mar 11 2024 01:00:00 GMT-07:00
addYears(now, 1, 'America/Los_Angeles');
// => Mar 11 2025 01:00:00 GMT-07:00
```
### addMonths
The changes are the same as for the `addYears` function.
### addDays
The changes are the same as for the `addYears` function.
### subtract
The calculation order has been reversed. Previously, the second argument was subtracted from the first argument, but now the first argument is subtracted from the second argument.
Additionally, the return value object has been changed to `Duration`. You can achieve the same output as before as follows:
```typescript
import { subtract } from 'date-and-time';
const yesterday = new Date(2015, 0, 1);
const today = new Date(2015, 0, 2);
subtract(yesterday, today).toDays().value; // => 1
subtract(yesterday, today).toHours().value; // => 24
subtract(yesterday, today).toMinutes().value; // => 1440
subtract(yesterday, today).toSeconds().value; // => 86400
subtract(yesterday, today).toMilliseconds().value; // => 86400000
```
### timeSpan
The `timeSpan` plugin is now obsolete as it has been integrated into the main library's `subtract` function. Please note that the argument order of the `subtract` function has changed. You can achieve the same output as before as follows:
```typescript
import { subtract } from 'date-and-time';
const new_years_day = new Date(2020, 0, 1);
const now = new Date(2020, 2, 5, 1, 2, 3, 4);
subtract(new_years_day, now).toDays().format('D HH:mm:ss.SSS');
// => 64 01:02:03.004
subtract(new_years_day, now).toHours().format('H [hours] m [minutes] s [seconds]');
// => 1537 hours 2 minutes 3 seconds
subtract(new_years_day, now).toMinutes().format('mmmmmmmmmm [minutes]');
// => 0000092222 minutes
```
## Locale
The method for switching locales has changed. Previously, the locale used throughout the library was switched, but now it is specified as a function argument. Below is a code example for the `format` function.
```typescript
import { format } from 'date-and-time';
import es from 'date-and-time/locales/es';
format(new Date(), 'dddd, D [de] MMMM [de] YYYY, h:mm aa [GMT]ZZ', { locale: es });
// => miércoles, 23 de julio de 2025, 12:38 a.m. GMT-07:00
```
## Plugins
The following plugins are now obsolete as they have been integrated into the main library:
- `meridiem`
- `timespan`
- `timezone`
The custom plugin feature that existed up to 3.x is not yet supported at this time.
================================================
FILE: docs/plugins.md
================================================
---
title: Plugins
---
`date-and-time` adopts a plugin system. Special tokens used relatively infrequently are provided as plugins outside the main library. By adding plugins as needed, you can use those tokens in `Formatter` and `Parser`. Here, `Formatter` refers to the output engine used by the `format` function, and `Parser` refers to the parsing engine used by the `parse`, `preparse`, and `isValid` functions. These engines are extended by adding plugins as arguments to these functions.
## Installation
### ESModules (Recommended)
```typescript
import { format } from 'date-and-time';
import { formatter as foobar } from 'date-and-time/plugins/foobar';
format(new Date(), 'ddd, MMM DD YYYY', { plugins: [foobar] });
```
### CommonJS
```typescript
const { format } = require('date-and-time');
const foobar = require('date-and-time/plugins/foobar');
format(new Date(), 'ddd, MMM DD YYYY', { plugins: [foobar.formatter] });
```
## day-of-week
This plugin adds tokens to the `Parser` for reading the day of the week. Since the day of the week does not provide information that identifies a specific date, it is a meaningless token, but it can be used to skip that portion when the string you want to read contains a day of the week.
### Parser
| Token | Meaning | Input Examples |
|-------|---------------------|----------------|
| dddd | Full day name | Friday, Sunday |
| ddd | Short day name | Fri, Sun |
| dd | Very short day name | Fr, Su |
```typescript
import { parse } from 'date-and-time';
import { parser as day_of_week } from 'date-and-time/plugins/day-of-week';
parse(
'Thursday, March 05, 2020', 'dddd, MMMM, D YYYY',
{ plugins: [day_of_week] }
);
```
## microsecond
This plugin adds tokens to the `Parser` for reading microseconds. Since the precision of JavaScript's Date type is milliseconds, these tokens are meaningless, but they can be used to skip that portion when the string you want to read contains microseconds.
### Parser
| Token | Meaning | Input Examples |
|--------|----------------------|----------------|
| SSSSSS | 6-digit milliseconds | 123456, 000001 |
| SSSSS | 5-digit milliseconds | 12345, 00001 |
| SSSS | 4-digit milliseconds | 1234, 0001 |
| fff | 3-digit microseconds | 753, 022 |
| ff | 2-digit microseconds | 75, 02 |
| f | 1-digit microseconds | 7, 0 |
```typescript
import { parse } from 'date-and-time';
import { parser as microsecond } from 'date-and-time/plugins/microsecond';
parse('12:34:56.123456', 'HH:mm:ss.SSSSSS', { plugins: [microsecond] });
parse('12:34:56 123.456', 'HH:mm:ss SSS.fff', { plugins: [microsecond] });
```
## nanosecond
This plugin adds tokens to the `Parser` for reading nanoseconds. Since the precision of JavaScript's Date type is milliseconds, these tokens are meaningless, but they can be used to skip that portion when the string you want to read contains nanoseconds.
### Parser
| Token | Meaning | Input Examples |
|-----------|----------------------|----------------------|
| SSSSSSSSS | 9-digit milliseconds | 123456789, 000000001 |
| SSSSSSSS | 8-digit milliseconds | 12345678, 00000001 |
| SSSSSSS | 7-digit milliseconds | 1234567, 0000001 |
| FFF | 3-digit nanoseconds | 753, 022 |
| FF | 2-digit nanoseconds | 75, 02 |
| F | 1-digit nanoseconds | 7, 0 |
```typescript
import { parse } from 'date-and-time';
import { parser as microsecond } from 'date-and-time/plugins/microsecond';
import { parser as nanosecond } from 'date-and-time/plugins/nanosecond';
parse(
'12:34:56.123456789',
'HH:mm:ss.SSSSSSSSS',
{ plugins: [microsecond, nanosecond] }
);
parse(
'12:34:56 123456.789',
'HH:mm:ss SSSSSS.FFF',
{ plugins: [microsecond, nanosecond] }
);
```
## ordinal
This plugin adds tokens to the `Formatter` and `Parser` for outputting or reading ordinal representations of days. This ordinal representation is limited to English and is not supported for locales other than English.
### Formatter
| Token | Meaning | Output Examples |
|-------|-------------------------------|-----------------|
| DDD | Ordinal representation of day | 1st, 2nd, 3rd |
```typescript
import { format } from 'date-and-time';
import { formatter as ordinal } from 'date-and-time/plugins/ordinal';
format(new Date(), 'MMM DDD YYYY', { plugins: [ordinal] });
// => Jan 1st 2019
```
### Parser
| Token | Meaning | Input Examples |
|-------|-------------------------------|----------------|
| DDD | Ordinal representation of day | 1st, 2nd, 3rd |
```typescript
import { parse } from 'date-and-time';
import { parser as ordinal } from 'date-and-time/plugins/ordinal';
parse('Jan 1st 2019', 'MMM DDD YYYY', { plugins: [ordinal] });
```
## quarter
This plugin adds a token to the `Formatter` for outputting the quarter of the year.
### Formatter
| Token | Meaning | Output Examples |
|-------|-----------------|-----------------|
| Q | Quarter of year | 1, 2, 3, 4 |
```typescript
import { format } from 'date-and-time';
import { formatter as quarter } from 'date-and-time/plugins/quarter';
format(new Date(2025, 0, 1), 'YYYY [Q]Q', { plugins: [quarter] });
// => 2025 Q1
format(new Date(2025, 9, 1), 'YYYY [Q]Q', { plugins: [quarter] });
// => 2025 Q4
```
## timestamp
This plugin adds tokens to the `Formatter` for outputting Unix timestamps.
### Formatter
| Token | Meaning | Output Examples |
|-------|-------------------------------|------------------|
| t | Unix timestamp (seconds) | 0, 1000000000 |
| T | Unix timestamp (milliseconds) | 0, 1000000000000 |
```typescript
import { format } from 'date-and-time';
import { formatter as timestamp } from 'date-and-time/plugins/timestamp';
format(new Date(1000000000000), 't', { plugins: [timestamp] });
// => 1000000000
format(new Date(1000000000000), 'T', { plugins: [timestamp] });
// => 1000000000000
```
## two-digit-year
This plugin adds tokens to the `Parser` for reading 2-digit years. This token identifies years based on the following rules:
- Values of 70 or above are interpreted as 1900s
- Values of 69 or below are interpreted as 2000s
### Parser
| Token | Meaning | Input Examples |
|-------|--------------|----------------|
| YY | 2-digit year | 90, 00, 08, 19 |
```typescript
import { parse } from 'date-and-time';
import { parser as two_digit_year } from 'date-and-time/plugins/two-digit-year';
parse('Dec 25 69', 'MMM DD YY', { plugins: [two_digit_year] });
// => Dec 25 2069
parse('Dec 25 70', 'MMM DD YY', { plugins: [two_digit_year] });
// => Dec 25 1970
```
## week
This plugin adds tokens to the `Formatter` for outputting ISO week dates. These tokens follow
the ISO 8601 week date system, where weeks start on Monday and the first week of
the year is the one that contains the first Thursday.
### Formatter
| Token | Meaning | Output Examples |
|-------|-------------------------------------|-----------------|
| W | ISO week number | 1, 27, 53 |
| WW | ISO week number (zero-padded) | 01, 27, 53 |
| G | ISO week year | 2024, 2025 |
| GG | ISO week year (2-digit zero-padded) | 24, 25 |
| GGGG | ISO week year (4-digit zero-padded) | 2024, 2025 |
```typescript
import { format } from 'date-and-time';
import { formatter as week } from 'date-and-time/plugins/week';
format(new Date(2024, 0, 1), 'GGGG-[W]WW', { plugins: [week] });
// => 2024-W01
// Note: Dec 30, 2024 belongs to ISO week year 2025
format(new Date(2024, 11, 30), 'YYYY vs GGGG [W]W', { plugins: [week] });
// => 2024 vs 2025 W1
```
## zonename
This plugin adds tokens to the `Formatter` for outputting timezone names. These timezone names are limited to English and are not supported for locales other than English.
### Formatter
| Token | Meaning | Output Examples |
|-------|---------------------|-----------------------|
| z | Short timezone name | PST, EST |
| zz | Long timezone name | Pacific Standard Time |
```typescript
import { format } from 'date-and-time';
import { formatter as zonename } from 'date-and-time/plugins/zonename';
format(
new Date(),
'MMMM DD YYYY H:mm zz',
{ plugins: [zonename] }
);
// March 14 2021 1:59 Pacific Standard Time
format(
new Date(),
'MMMM DD YYYY H:mm z',
{ plugins: [zonename], timeZone: 'Asia/Tokyo' }
);
// March 14 2021 18:59 JST
```
================================================
FILE: docs/styles/custom.css
================================================
/* ─── Font sizes (match VitePress heading scale) ─── */
:root {
--sl-text-h1: 1.75rem;
--sl-text-h2: 1.5rem;
--sl-text-h3: 1.25rem;
--sl-text-h4: 1.125rem;
}
@media (min-width: 50em) {
:root {
--sl-text-h1: 1.75rem;
--sl-text-h2: 1.5rem;
--sl-text-h3: 1.25rem;
--sl-text-h4: 1.125rem;
}
}
/* ─── Colors (neutral, matching VitePress) ─── */
:root {
--sl-color-text: rgba(235, 235, 245, 0.86);
/* Accent: #5672cd — dark mode */
--sl-color-accent-low: hsl(226, 40%, 18%);
--sl-color-accent: hsl(226, 54%, 57%);
--sl-color-accent-high: hsl(226, 80%, 85%);
}
:root[data-theme='light'] {
--sl-color-text: rgba(60, 60, 67);
--sl-color-hairline: rgba(60, 60, 67, 0.12);
--sl-color-hairline-light: rgba(60, 60, 67, 0.08);
/* Accent: #5672cd — light mode */
--sl-color-accent-low: hsl(226, 60%, 94%);
--sl-color-accent: hsl(226, 54%, 47%);
--sl-color-accent-high: hsl(226, 54%, 28%);
}
/* ─── h2 border-top (VitePress section divider style) ─── */
.sl-markdown-content h2:not(:where(.not-content *)) {
border-top: 1px solid var(--sl-color-hairline);
padding-top: 24px;
margin-top: 2em;
}
/* ─── Left sidebar menu line-height ─── */
.sidebar-content a,
.sidebar-content summary {
line-height: 1.6;
}
/* ─── "On this page" TOC line-height ─── */
starlight-toc a {
line-height: 1.6;
}
/* ─── Tables ─── */
.sl-markdown-content table:not(:where(.not-content *)) {
border-collapse: collapse;
margin: 20px 0;
font-size: 14px;
width: 100%;
}
.sl-markdown-content tr:not(:where(.not-content *)) {
border-top: 1px solid var(--sl-color-hairline);
border-bottom: 1px solid var(--sl-color-hairline);
transition: background-color 0.25s;
}
/* Zebra stripe (dark mode default) */
.sl-markdown-content tr:nth-child(2n):not(:where(.not-content *)) {
background-color: var(--sl-color-gray-6);
}
:root[data-theme='light'] .sl-markdown-content tr:nth-child(2n):not(:where(.not-content *)) {
background-color: var(--sl-color-gray-7);
}
/* th (dark mode default) */
.sl-markdown-content th:not(:where(.not-content *)) {
border: var(--ec-brdWd) solid var(--ec-brdCol);
padding: 8px 16px;
background-color: var(--sl-color-gray-6);
color: var(--sl-color-gray-3);
}
:root[data-theme='light'] .sl-markdown-content th:not(:where(.not-content *)) {
background-color: var(--sl-color-gray-7);
}
.sl-markdown-content td:not(:where(.not-content *)) {
border: var(--ec-brdWd) solid var(--ec-brdCol);
padding: 8px 16px;
}
/* ─── Pagination ─── */
.pagination-links {
margin-top: 40px;
padding-top: 24px;
border-top: 1px solid var(--sl-color-hairline);
}
.pagination-links a {
align-items: center;
gap: 0.75rem;
border-color: var(--sl-color-hairline);
border-radius: 8px;
padding: 16px;
box-shadow: none;
transition: border-color 0.25s;
}
.pagination-links a:hover {
border-color: var(--sl-color-accent);
}
.pagination-links a > span {
font-size: 0.75rem;
color: var(--sl-color-gray-3);
letter-spacing: 0.4px;
}
.pagination-links .link-title {
font-size: var(--sl-text-base);
line-height: 1.4;
color: var(--sl-color-white);
margin-top: 4px;
}
:root[data-theme='light'] .pagination-links .link-title {
color: var(--sl-color-gray-1);
}
.pagination-links svg {
color: var(--sl-color-accent);
flex-shrink: 0;
}
/* ─── Hero image ─── */
.hero img {
width: 320px;
height: 320px;
}
/* ─── Cards ─── */
/* Dark mode default */
article.card {
background-color: var(--sl-color-gray-6);
border: 1px solid var(--sl-color-gray-6);
border-radius: 12px;
transition: border-color 0.25s;
}
/* Light mode override */
:root[data-theme='light'] article.card {
background-color: var(--sl-color-gray-7);
border-color: var(--sl-color-gray-7);
}
article.card:hover {
border-color: var(--sl-color-accent);
}
article.card .title {
color: inherit;
}
================================================
FILE: docs/timezones.md
================================================
---
title: Timezones
---
Timezone support lets you format and parse dates in any timezone, regardless of the local system timezone. Pass an IANA timezone name string as the `timeZone` option to any function that accepts it — no additional imports are needed for the recommended approach.
```typescript
import { format } from 'date-and-time';
const date = new Date();
format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: 'Asia/Tokyo' });
// => 2025-08-23 23:30:45
```
## Import Methods
There are three ways to import and use timezones with the date-and-time library:
### Method 1: IANA Timezone Name String (Recommended)
Pass an IANA timezone name string directly to any function that accepts a timezone option. No imports are required — just use the timezone name as a string.
```typescript
import { format } from 'date-and-time';
const date = new Date();
format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: 'Asia/Tokyo' });
// => 2025-08-23 23:30:45
format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: 'America/New_York' });
// => 2025-08-23 09:30:45
format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: 'Europe/London' });
// => 2025-08-23 14:30:45
```
The string `"UTC"` is treated specially by this library and is processed faster than other timezone strings. While other strings that represent UTC (e.g., `"Etc/UTC"`) are also recognized, using `"UTC"` is always recommended.
### Method 2: Consolidated Import (Deprecated)
**This approach is deprecated and will be removed in the next major version. Use IANA timezone name strings instead.**
Import multiple timezones from a single module using named imports.
```typescript
import { format } from 'date-and-time';
import { Tokyo, New_York, London, Sydney } from 'date-and-time/timezone';
const date = new Date();
format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: Tokyo }); // JST
format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: New_York }); // EST/EDT
format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: London }); // GMT/BST
format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: Sydney }); // AEDT/AEST
```
### Method 3: Individual Import (Deprecated)
**This approach is deprecated and will be removed in the next major version. Use IANA timezone name strings instead.**
Import each timezone you need directly from its module path.
```typescript
import { format } from 'date-and-time';
import Tokyo from 'date-and-time/timezones/Asia/Tokyo';
import New_York from 'date-and-time/timezones/America/New_York';
const date = new Date();
format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: Tokyo });
// => 2025-08-23 23:30:45
format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: New_York });
// => 2025-08-23 09:30:45
```
## Regions
The timezones listed below are confirmed to work — since this library internally relies on the `Intl` API, other timezones supported by your runtime may also work.
1. [Africa](#africa)
2. [America](#america)
3. [Antarctica](#antarctica)
4. [Arctic](#arctic)
5. [Asia](#asia)
6. [Atlantic](#atlantic)
7. [Australia](#australia)
8. [Europe](#europe)
9. [Indian](#indian)
10. [Pacific](#pacific)
## Africa
- Africa/Abidjan
- Africa/Accra
- Africa/Addis_Ababa
- Africa/Algiers
- Africa/Asmara
- Africa/Bamako
- Africa/Bangui
- Africa/Banjul
- Africa/Bissau
- Africa/Blantyre
- Africa/Brazzaville
- Africa/Bujumbura
- Africa/Cairo
- Africa/Casablanca
- Africa/Ceuta
- Africa/Conakry
- Africa/Dakar
- Africa/Dar_es_Salaam
- Africa/Djibouti
- Africa/Douala
- Africa/El_Aaiun
- Africa/Freetown
- Africa/Gaborone
- Africa/Harare
- Africa/Johannesburg
- Africa/Juba
- Africa/Kampala
- Africa/Khartoum
- Africa/Kigali
- Africa/Kinshasa
- Africa/Lagos
- Africa/Libreville
- Africa/Lome
- Africa/Luanda
- Africa/Lubumbashi
- Africa/Lusaka
- Africa/Malabo
- Africa/Maputo
- Africa/Maseru
- Africa/Mbabane
- Africa/Mogadishu
- Africa/Monrovia
- Africa/Nairobi
- Africa/Ndjamena
- Africa/Niamey
- Africa/Nouakchott
- Africa/Ouagadougou
- Africa/Porto-Novo
- Africa/Sao_Tome
- Africa/Tripoli
- Africa/Tunis
- Africa/Windhoek
## America
- America/Adak
- America/Anchorage
- America/Anguilla
- America/Antigua
- America/Araguaina
- America/Argentina/Buenos_Aires
- America/Argentina/Catamarca
- America/Argentina/Cordoba
- America/Argentina/Jujuy
- America/Argentina/La_Rioja
- America/Argentina/Mendoza
- America/Argentina/Rio_Gallegos
- America/Argentina/Salta
- America/Argentina/San_Juan
- America/Argentina/San_Luis
- America/Argentina/Tucuman
- America/Argentina/Ushuaia
- America/Aruba
- America/Asuncion
- America/Atikokan
- America/Bahia_Banderas
- America/Bahia
- America/Barbados
- America/Belem
- America/Belize
- America/Blanc-Sablon
- America/Boa_Vista
- America/Bogota
- America/Boise
- America/Cambridge_Bay
- America/Campo_Grande
- America/Cancun
- America/Caracas
- America/Cayenne
- America/Cayman
- America/Chicago
- America/Chihuahua
- America/Ciudad_Juarez
- America/Costa_Rica
- America/Coyhaique
- America/Creston
- America/Cuiaba
- America/Curacao
- America/Danmarkshavn
- America/Dawson_Creek
- America/Dawson
- America/Denver
- America/Detroit
- America/Dominica
- America/Edmonton
- America/Eirunepe
- America/El_Salvador
- America/Fort_Nelson
- America/Fortaleza
- America/Glace_Bay
- America/Goose_Bay
- America/Grand_Turk
- America/Grenada
- America/Guadeloupe
- America/Guatemala
- America/Guayaquil
- America/Guyana
- America/Halifax
- America/Havana
- America/Hermosillo
- America/Indiana/Indianapolis
- America/Indiana/Knox
- America/Indiana/Marengo
- America/Indiana/Petersburg
- America/Indiana/Tell_City
- America/Indiana/Vevay
- America/Indiana/Vincennes
- America/Indiana/Winamac
- America/Inuvik
- America/Iqaluit
- America/Jamaica
- America/Juneau
- America/Kentucky/Louisville
- America/Kentucky/Monticello
- America/Kralendijk
- America/La_Paz
- America/Lima
- America/Los_Angeles
- America/Lower_Princes
- America/Maceio
- America/Managua
- America/Manaus
- America/Marigot
- America/Martinique
- America/Matamoros
- America/Mazatlan
- America/Menominee
- America/Merida
- America/Metlakatla
- America/Mexico_City
- America/Miquelon
- America/Moncton
- America/Monterrey
- America/Montevideo
- America/Montserrat
- America/Nassau
- America/New_York
- America/Nome
- America/Noronha
- America/North_Dakota/Beulah
- America/North_Dakota/Center
- America/North_Dakota/New_Salem
- America/Nuuk
- America/Ojinaga
- America/Panama
- America/Paramaribo
- America/Phoenix
- America/Port_of_Spain
- America/Port-au-Prince
- America/Porto_Velho
- America/Puerto_Rico
- America/Punta_Arenas
- America/Rankin_Inlet
- America/Recife
- America/Regina
- America/Resolute
- America/Rio_Branco
- America/Santarem
- America/Santiago
- America/Santo_Domingo
- America/Sao_Paulo
- America/Scoresbysund
- America/Sitka
- America/St_Barthelemy
- America/St_Johns
- America/St_Kitts
- America/St_Lucia
- America/St_Thomas
- America/St_Vincent
- America/Swift_Current
- America/Tegucigalpa
- America/Thule
- America/Tijuana
- America/Toronto
- America/Tortola
- America/Vancouver
- America/Whitehorse
- America/Winnipeg
- America/Yakutat
## Antarctica
- Antarctica/Casey
- Antarctica/Davis
- Antarctica/DumontDUrville
- Antarctica/Macquarie
- Antarctica/Mawson
- Antarctica/McMurdo
- Antarctica/Palmer
- Antarctica/Rothera
- Antarctica/Syowa
- Antarctica/Troll
- Antarctica/Vostok
## Arctic
- Arctic/Longyearbyen
## Asia
- Asia/Aden
- Asia/Almaty
- Asia/Amman
- Asia/Anadyr
- Asia/Aqtau
- Asia/Aqtobe
- Asia/Ashgabat
- Asia/Atyrau
- Asia/Baghdad
- Asia/Bahrain
- Asia/Baku
- Asia/Bangkok
- Asia/Barnaul
- Asia/Beirut
- Asia/Bishkek
- Asia/Brunei
- Asia/Chita
- Asia/Colombo
- Asia/Damascus
- Asia/Dhaka
- Asia/Dili
- Asia/Dubai
- Asia/Dushanbe
- Asia/Famagusta
- Asia/Gaza
- Asia/Hebron
- Asia/Ho_Chi_Minh
- Asia/Hong_Kong
- Asia/Hovd
- Asia/Irkutsk
- Asia/Jakarta
- Asia/Jayapura
- Asia/Jerusalem
- Asia/Kabul
- Asia/Kamchatka
- Asia/Karachi
- Asia/Kathmandu
- Asia/Khandyga
- Asia/Kolkata
- Asia/Krasnoyarsk
- Asia/Kuala_Lumpur
- Asia/Kuching
- Asia/Kuwait
- Asia/Macau
- Asia/Magadan
- Asia/Makassar
- Asia/Manila
- Asia/Muscat
- Asia/Nicosia
- Asia/Novokuznetsk
- Asia/Novosibirsk
- Asia/Omsk
- Asia/Oral
- Asia/Phnom_Penh
- Asia/Pontianak
- Asia/Pyongyang
- Asia/Qatar
- Asia/Qostanay
- Asia/Qyzylorda
- Asia/Riyadh
- Asia/Sakhalin
- Asia/Samarkand
- Asia/Seoul
- Asia/Shanghai
- Asia/Singapore
- Asia/Srednekolymsk
- Asia/Taipei
- Asia/Tashkent
- Asia/Tbilisi
- Asia/Tehran
- Asia/Thimphu
- Asia/Tokyo
- Asia/Tomsk
- Asia/Ulaanbaatar
- Asia/Urumqi
- Asia/Ust-Nera
- Asia/Vientiane
- Asia/Vladivostok
- Asia/Yakutsk
- Asia/Yangon
- Asia/Yekaterinburg
- Asia/Yerevan
## Atlantic
- Atlantic/Azores
- Atlantic/Bermuda
- Atlantic/Canary
- Atlantic/Cape_Verde
- Atlantic/Faroe
- Atlantic/Madeira
- Atlantic/Reykjavik
- Atlantic/South_Georgia
- Atlantic/St_Helena
- Atlantic/Stanley
## Australia
- Australia/Adelaide
- Australia/Brisbane
- Australia/Broken_Hill
- Australia/Darwin
- Australia/Eucla
- Australia/Hobart
- Australia/Lindeman
- Australia/Lord_Howe
- Australia/Melbourne
- Australia/Perth
- Australia/Sydney
## Europe
- Europe/Amsterdam
- Europe/Andorra
- Europe/Astrakhan
- Europe/Athens
- Europe/Belgrade
- Europe/Berlin
- Europe/Bratislava
- Europe/Brussels
- Europe/Bucharest
- Europe/Budapest
- Europe/Busingen
- Europe/Chisinau
- Europe/Copenhagen
- Europe/Dublin
- Europe/Gibraltar
- Europe/Guernsey
- Europe/Helsinki
- Europe/Isle_of_Man
- Europe/Istanbul
- Europe/Jersey
- Europe/Kaliningrad
- Europe/Kirov
- Europe/Kyiv
- Europe/Lisbon
- Europe/Ljubljana
- Europe/London
- Europe/Luxembourg
- Europe/Madrid
- Europe/Malta
- Europe/Mariehamn
- Europe/Minsk
- Europe/Monaco
- Europe/Moscow
- Europe/Oslo
- Europe/Paris
- Europe/Podgorica
- Europe/Prague
- Europe/Riga
- Europe/Rome
- Europe/Samara
- Europe/San_Marino
- Europe/Sarajevo
- Europe/Saratov
- Europe/Simferopol
- Europe/Skopje
- Europe/Sofia
- Europe/Stockholm
- Europe/Tallinn
- Europe/Tirane
- Europe/Ulyanovsk
- Europe/Vaduz
- Europe/Vatican
- Europe/Vienna
- Europe/Vilnius
- Europe/Volgograd
- Europe/Warsaw
- Europe/Zagreb
- Europe/Zurich
## Indian
- Indian/Antananarivo
- Indian/Chagos
- Indian/Christmas
- Indian/Cocos
- Indian/Comoro
- Indian/Kerguelen
- Indian/Mahe
- Indian/Maldives
- Indian/Mauritius
- Indian/Mayotte
- Indian/Reunion
## Pacific
- Pacific/Apia
- Pacific/Auckland
- Pacific/Bougainville
- Pacific/Chatham
- Pacific/Chuuk
- Pacific/Easter
- Pacific/Efate
- Pacific/Fakaofo
- Pacific/Fiji
- Pacific/Funafuti
- Pacific/Galapagos
- Pacific/Gambier
- Pacific/Guadalcanal
- Pacific/Guam
- Pacific/Honolulu
- Pacific/Kanton
- Pacific/Kiritimati
- Pacific/Kosrae
- Pacific/Kwajalein
- Pacific/Majuro
- Pacific/Marquesas
- Pacific/Midway
- Pacific/Nauru
- Pacific/Niue
- Pacific/Norfolk
- Pacific/Noumea
- Pacific/Pago_Pago
- Pacific/Palau
- Pacific/Pitcairn
- Pacific/Pohnpei
- Pacific/Port_Moresby
- Pacific/Rarotonga
- Pacific/Saipan
- Pacific/Tahiti
- Pacific/Tarawa
- Pacific/Tongatapu
- Pacific/Wake
- Pacific/Wallis
================================================
FILE: docs/tsconfig.json
================================================
{
"extends": "astro/tsconfigs/base",
"include": ["../.astro/types.d.ts", "./**/*"],
"exclude": ["../node_modules"]
}
================================================
FILE: eslint.config.js
================================================
import { defineConfig } from 'eslint/config';
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
import stylistic from '@stylistic/eslint-plugin';
export default defineConfig(
eslint.configs.recommended,
tseslint.configs.strictTypeChecked,
tseslint.configs.stylisticTypeChecked,
{
ignores: ["**/*.js", "**/*.mjs", "coverage", "dist", "docs", ".astro"]
},
{
files: ['**/*.ts'],
plugins: {
'@stylistic': stylistic
},
languageOptions: {
ecmaVersion: 2021,
sourceType: 'module',
globals: {
process: true
},
parserOptions: {
projectService: true
}
},
rules: {
'@typescript-eslint/no-extraneous-class': 'off',
'accessor-pairs': 'error',
'array-callback-return': 'error',
'block-scoped-var': 'error',
'consistent-return': 'error',
'curly': 'error',
'default-case-last': 'error',
'eqeqeq': ['error', 'smart'],
'func-name-matching': 'error',
'func-style': ['error', 'expression', { overrides: { namedExports: 'ignore' } }],
'grouped-accessor-pairs': 'error',
'max-depth': 'error',
'max-nested-callbacks': 'error',
'new-cap': 'error',
'no-caller': 'error',
'no-constructor-return': 'error',
'no-div-regex': 'error',
'no-else-return': 'error',
'no-empty-static-block': 'error',
'no-eval': 'error',
'no-extend-native': 'error',
'no-extra-bind': 'error',
'no-extra-label': 'error',
'no-implicit-globals': 'error',
'no-implied-eval': 'error',
'no-iterator': 'error',
'no-label-var': 'error',
'no-labels': 'error',
'no-lone-blocks': 'error',
'no-lonely-if': 'error',
'no-multi-assign': ['error', { ignoreNonDeclaration: true }],
'no-multi-str': 'error',
'no-negated-condition': 'error',
'no-new': 'error',
'no-new-func': 'error',
'no-new-wrappers': 'error',
'no-object-constructor': 'error',
'no-octal-escape': 'error',
'no-proto': 'error',
'no-return-assign': 'error',
'no-script-url': 'error',
'no-self-compare': 'error',
'no-sequences': 'error',
'no-shadow-restricted-names': 'error',
'no-template-curly-in-string': 'error',
'no-undef-init': 'error',
'no-unmodified-loop-condition': 'error',
'no-unneeded-ternary': 'error',
'no-unreachable-loop': 'error',
'no-useless-call': 'error',
'no-useless-computed-key': 'error',
'no-useless-concat': 'error',
'no-useless-rename': 'error',
'no-useless-return': 'error',
'no-void': 'error',
'no-warning-comments': 'error',
'operator-assignment': 'error',
'prefer-exponentiation-operator': 'error',
'prefer-numeric-literals': 'error',
'prefer-object-has-own': 'error',
'prefer-object-spread': 'error',
'prefer-promise-reject-errors': ['error', { allowEmptyReject: true }],
'prefer-regex-literals': 'error',
'prefer-rest-params': 'error',
'prefer-spread': 'error',
'radix': 'error',
'require-atomic-updates': 'error',
'symbol-description': 'error',
'unicode-bom': 'error',
'yoda': 'error',
'@stylistic/array-bracket-spacing': ['warn', 'never'],
'@stylistic/arrow-spacing': 'warn',
'@stylistic/block-spacing': 'warn',
'@stylistic/comma-dangle': 'warn',
'@stylistic/comma-spacing': 'warn',
'@stylistic/comma-style': 'warn',
'@stylistic/computed-property-spacing': 'warn',
'@stylistic/dot-location': ['warn', 'property'],
'@stylistic/eol-last': 'warn',
'@stylistic/function-call-spacing': 'warn',
'@stylistic/generator-star-spacing': 'warn',
'@stylistic/implicit-arrow-linebreak': 'warn',
'@stylistic/indent': ['warn', 2, { SwitchCase: 0, ignoreComments: true }],
'@stylistic/jsx-quotes': 'warn',
'@stylistic/key-spacing': 'warn',
'@stylistic/keyword-spacing': 'warn',
'@stylistic/linebreak-style': 'warn',
'@stylistic/lines-between-class-members': 'warn',
'@stylistic/member-delimiter-style': ['warn', { multiline: { delimiter: 'semi', requireLast: true }, singleline: { delimiter: 'semi', requireLast: false } }],
'@stylistic/new-parens': 'warn',
'@stylistic/no-extra-parens': ['warn', 'functions'],
'@stylistic/no-extra-semi': 'warn',
'@stylistic/no-floating-decimal': 'warn',
'@stylistic/no-mixed-spaces-and-tabs': 'warn',
'@stylistic/no-multi-spaces': ['warn', { ignoreEOLComments: true }],
'@stylistic/no-tabs': 'warn',
'@stylistic/no-trailing-spaces': 'warn',
'@stylistic/no-whitespace-before-property': 'warn',
'@stylistic/nonblock-statement-body-position': 'warn',
'@stylistic/object-curly-newline': 'warn',
'@stylistic/object-curly-spacing': ['warn', 'always'],
'@stylistic/padding-line-between-statements': 'warn',
'@stylistic/quotes': ['warn', 'single'],
'@stylistic/rest-spread-spacing': 'warn',
'@stylistic/semi': 'warn',
'@stylistic/semi-spacing': 'warn',
'@stylistic/semi-style': 'warn',
'@stylistic/space-before-blocks': 'warn',
'@stylistic/space-in-parens': 'warn',
'@stylistic/space-infix-ops': 'warn',
'@stylistic/space-unary-ops': 'warn',
'@stylistic/switch-colon-spacing': 'warn',
'@stylistic/template-curly-spacing': 'warn',
'@stylistic/template-tag-spacing': 'warn',
'@stylistic/wrap-iife': ['warn', 'any'],
'@stylistic/yield-star-spacing': 'warn'
}
}
);
================================================
FILE: package.json
================================================
{
"name": "date-and-time",
"version": "4.5.0",
"description": "The simplest, most intuitive date and time library",
"keywords": [
"date",
"datetime",
"duration",
"format",
"parse",
"time",
"timezone"
],
"main": "dist/index.js",
"types": "dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js",
"require": "./dist/index.cjs"
},
"./plugin": {
"types": "./dist/plugin.d.ts",
"import": "./dist/plugin.js",
"require": "./dist/plugin.cjs"
},
"./timezone": {
"types": "./dist/timezone.d.ts",
"import": "./dist/timezone.js",
"require": "./dist/timezone.cjs"
},
"./locales/*": {
"types": "./dist/locales/*.d.ts",
"import": "./dist/locales/*.js",
"require": "./dist/locales/*.cjs"
},
"./numerals/*": {
"types": "./dist/numerals/*.d.ts",
"import": "./dist/numerals/*.js",
"require": "./dist/numerals/*.cjs"
},
"./plugins/*": {
"types": "./dist/plugins/*.d.ts",
"import": "./dist/plugins/*.js",
"require": "./dist/plugins/*.cjs"
},
"./timezones/*": {
"types": "./dist/timezones/*.d.ts",
"import": "./dist/timezones/*.js",
"require": "./dist/timezones/*.cjs"
}
},
"files": [
"LICENSE",
"README.md",
"dist/"
],
"scripts": {
"build": "rm -rf dist && rollup -c",
"build-watch": "rollup -c --watch",
"build:ts": "rollup -c --config-ts",
"build:types": "rollup -c --config-types",
"docs:build": "astro build",
"docs:dev": "astro dev",
"docs:preview": "astro preview",
"lint": "eslint",
"prepublishOnly": "npm run build",
"test": "vitest run",
"test:coverage": "vitest run --coverage",
"timezone": "tsx tools/timezone.ts",
"ts": "tsc --noEmit",
"zonename": "tsx tools/zonename.ts"
},
"author": "KNOWLEDGECODE",
"license": "MIT",
"engines": {
"node": ">=18"
},
"homepage": "https://knowledgecode.github.io/date-and-time/",
"bugs": {
"url": "https://github.com/knowledgecode/date-and-time/issues"
},
"repository": {
"type": "git",
"url": "git+https://github.com/knowledgecode/date-and-time.git"
},
"type": "module",
"sideEffects": false,
"devDependencies": {
"@astrojs/starlight": "^0.38.5",
"@eslint/js": "^10.0.1",
"@rollup/plugin-alias": "^6.0.0",
"@rollup/plugin-terser": "^1.0.0",
"@stylistic/eslint-plugin": "^5.10.0",
"@types/node": "^25.6.0",
"@vitest/coverage-v8": "^4.1.5",
"astro": "^6.2.2",
"eslint": "^10.3.0",
"glob": "^13.0.6",
"prettier": "^3.8.3",
"rollup": "^4.60.3",
"rollup-plugin-dts": "^6.4.1",
"rollup-plugin-esbuild": "^6.2.1",
"tsx": "^4.21.0",
"typescript-eslint": "^8.59.2",
"vitest": "^4.1.5"
}
}
================================================
FILE: rollup.config.ts
================================================
import alias from '@rollup/plugin-alias';
import esbuild from 'rollup-plugin-esbuild';
import terser from '@rollup/plugin-terser';
import { dts } from 'rollup-plugin-dts';
import { globSync } from 'glob';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
const outputDir = (input: string) => input.replace(/^src/g, 'dist').replace(/\/[^/]*$/g, '');
const replacePath = (input: string) => input.replace(/(^src\/|\.ts$)/g, '');
const ts = () => {
const plugins = [
alias({ entries: [{ find: '@', replacement: resolve(dirname(fileURLToPath(import.meta.url)), 'src') }] }),
esbuild({ minify: false, target: 'es2021' }),
terser()
];
const config = (input: string | Record<string, string>, outputDir: string) => ({
input,
output: [
{ dir: outputDir, format: 'es' },
{ dir: outputDir, format: 'cjs', entryFileNames: '[name].cjs' }
],
plugins
});
return [
config('src/index.ts', 'dist'),
config('src/plugin.ts', 'dist'),
config('src/timezone.ts', 'dist'),
config(Object.fromEntries(globSync('src/numerals/**/*.ts').map(input => [replacePath(input), input])), 'dist'),
globSync('src/locales/**/*.ts').map(input => config(input, outputDir(input))),
globSync('src/plugins/**/*.ts').map(input => config(input, outputDir(input))),
config(Object.fromEntries(globSync('src/timezones/**/*.ts').map(input => [replacePath(input), input])), 'dist')
].flat();
};
const types = () => {
const plugins = [
alias({ entries: [{ find: '@', replacement: resolve(dirname(fileURLToPath(import.meta.url)), 'src') }] }),
dts()
];
const config = (input: string | Record<string, string>, outputDir: string) => ({
input,
output: { dir: outputDir },
plugins
});
return [
config('src/index.ts', 'dist'),
config('src/plugin.ts', 'dist'),
config('src/timezone.ts', 'dist'),
config(Object.fromEntries(globSync('src/numerals/**/*.ts').map(input => [replacePath(input), input])), 'dist'),
globSync('src/locales/**/*.ts').map(input => config(input, outputDir(input))),
globSync('src/plugins/**/*.ts').map(input => config(input, outputDir(input))),
config(Object.fromEntries(globSync('src/timezones/**/*.ts').map(input => [replacePath(input), input])), 'dist')
].flat();
};
export default (args: Record<string, string>) => {
if (args['config-ts']) {
return ts();
}
if (args['config-types']) {
return types();
}
return [...ts(), ...types()];
};
================================================
FILE: src/addDays.ts
================================================
import { toParts, fromParts, isUTC } from './datetime.ts';
import { isTimeZone, createTimezoneDate } from './zone.ts';
import type { TimeZone } from './zone.ts';
/**
* Adds the specified number of days to a Date object.
* @param dateObj - The Date object to modify
* @param days - The number of days to add
* @param [timeZone] - Optional time zone object, an IANA timezone name or 'UTC' to use Coordinated Universal Time.
* @returns A new Date object with the specified number of days added
*/
export function addDays(dateObj: Date, days: number, timeZone?: TimeZone | string) {
const zoneName = isTimeZone(timeZone) ? timeZone.zone_name : timeZone ?? undefined;
if (!zoneName || isUTC(zoneName)) {
const d = new Date(dateObj.getTime());
// Handle UTC calculation
if (isUTC(timeZone)) {
d.setUTCDate(d.getUTCDate() + days);
return d;
}
// Handle local time calculation
d.setDate(d.getDate() + days);
return d;
}
// Handle timezone-specific calculation
const parts = toParts(dateObj, zoneName);
parts.day += days;
parts.timezoneOffset = 0;
return createTimezoneDate(fromParts(parts), zoneName);
}
================================================
FILE: src/addHours.ts
================================================
/**
* Adds the specified number of hours to a Date object.
* @param dateObj - The Date object to modify
* @param hours - The number of hours to add
* @returns A new Date object with the specified number of hours added
*/
export function addHours(dateObj: Date, hours: number) {
return new Date(dateObj.getTime() + hours * 3600000);
}
================================================
FILE: src/addMilliseconds.ts
================================================
/**
* Adds the specified number of milliseconds to a Date object.
* @param dateObj - The Date object to modify
* @param milliseconds - The number of milliseconds to add
* @returns A new Date object with the specified number of milliseconds added
*/
export function addMilliseconds(dateObj: Date, milliseconds: number) {
return new Date(dateObj.getTime() + milliseconds);
}
================================================
FILE: src/addMinutes.ts
================================================
/**
* Adds the specified number of minutes to a Date object.
* @param dateObj - The Date object to modify
* @param minutes - The number of minutes to add
* @returns A new Date object with the specified number of minutes added
*/
export function addMinutes(dateObj: Date, minutes: number) {
return new Date(dateObj.getTime() + minutes * 60000);
}
================================================
FILE: src/addMonths.ts
================================================
import { toParts, fromParts, isUTC } from './datetime.ts';
import { isTimeZone, createTimezoneDate } from './zone.ts';
import type { TimeZone } from './zone.ts';
/**
* Adds the specified number of months to a Date object.
* @param dateObj - The Date object to modify
* @param months - The number of months to add
* @param [timeZone] - Optional time zone object, an IANA timezone name or 'UTC' to use Coordinated Universal Time.
* @returns A new Date object with the specified number of months added
*/
export function addMonths(dateObj: Date, months: number, timeZone?: TimeZone | string) {
const zoneName = isTimeZone(timeZone) ? timeZone.zone_name : timeZone ?? undefined;
if (!zoneName || isUTC(zoneName)) {
const d = new Date(dateObj.getTime());
// Handle UTC calculation
if (isUTC(timeZone)) {
d.setUTCMonth(d.getUTCMonth() + months);
// Adjust to last day of month if new month has fewer days
if (d.getUTCDate() < dateObj.getUTCDate()) {
d.setUTCDate(0);
return d;
}
return d;
}
// Handle local time calculation
d.setMonth(d.getMonth() + months);
// Adjust to last day of month if new month has fewer days
if (d.getDate() < dateObj.getDate()) {
d.setDate(0);
return d;
}
return d;
}
// Handle timezone-specific calculation
const parts = toParts(dateObj, zoneName);
parts.month += months;
parts.timezoneOffset = 0;
const d = new Date(fromParts(parts));
if (d.getUTCDate() < parts.day) {
d.setUTCDate(0);
}
return createTimezoneDate(
fromParts({
...parts,
year: d.getUTCFullYear(),
month: d.getUTCMonth() + 1,
day: d.getUTCDate()
}),
zoneName
);
}
================================================
FILE: src/addSeconds.ts
================================================
/**
* Adds the specified number of seconds to a Date object.
* @param dateObj - The Date object to modify
* @param seconds - The number of seconds to add
* @returns A new Date object with the specified number of seconds added
*/
export function addSeconds(dateObj: Date, seconds: number) {
return new Date(dateObj.getTime() + seconds * 1000);
}
================================================
FILE: src/addYears.ts
================================================
import { addMonths } from './addMonths.ts';
import type { TimeZone } from './zone.ts';
/**
* Adds the specified number of years to a Date object.
* @param dateObj - The Date object to modify
* @param years - The number of years to add
* @param [timeZone] - Optional time zone object, an IANA timezone name or 'UTC' to use Coordinated Universal Time.
* @returns A new Date object with the specified number of years added
*/
export function addYears(dateObj: Date, years: number, timeZone?: TimeZone | string) {
return addMonths(dateObj, years * 12, timeZone);
}
================================================
FILE: src/compile.ts
================================================
/** @preserve Copyright (c) KNOWLEDGECODE - MIT License */
export type CompiledObject = string[];
// Escape sequences for literal brackets
const LBRACKET = /\\\[/g;
const RBRACKET = /\\\]/g;
// Private Use Area characters to temporarily replace literal brackets
const PUA_LBRACKET = /\uE000/g;
const PUA_RBRACKET = /\uE001/g;
// Regular expression to match format tokens, literal text, and escaped characters
const REGEXP = /\[(?:[^[\]]|\[[^[\]]*])*]|([A-Za-z])\1*|\.{3}|./g;
/**
* Compiles a format string into a tokenized array for efficient parsing and formatting.
* @param formatString - The format string to compile
* @returns A compiled array where the first element is the original format string,
* followed by tokenized format components
*/
export const compile = (formatString: string): CompiledObject => {
const array = formatString.replace(LBRACKET, '\uE000').replace(RBRACKET, '\uE001').match(REGEXP) ?? [];
return [formatString, ...array.map(token => token.replace(PUA_LBRACKET, '[').replace(PUA_RBRACKET, ']'))];
};
================================================
FILE: src/datetime.ts
================================================
import { getDateTimeFormat } from './dtf.ts';
export interface DateTimeParts {
weekday: number;
year: number;
month: number;
day: number;
hour: number;
minute: number;
second: number;
fractionalSecond: number;
timezoneOffset: number;
}
export const fromParts = (parts: DateTimeParts) => {
return Date.UTC(
parts.year,
parts.month - (parts.year < 100 ? 1900 * 12 + 1 : 1),
parts.day,
parts.hour,
parts.minute,
parts.second,
parts.fractionalSecond + parts.timezoneOffset * 60000
);
};
export const dtfToParts = (dtf: Intl.DateTimeFormat, time: number): DateTimeParts => {
return dtf.formatToParts(time)
.reduce((parts, { type, value }) => {
switch (type) {
case 'weekday':
parts[type] = 'SunMonTueWedThuFriSat'.indexOf(value) / 3;
break;
case 'hour':
parts[type] = +value % 24;
break;
case 'year':
case 'month':
case 'day':
case 'minute':
case 'second':
case 'fractionalSecond':
parts[type] = +value;
}
return parts;
}, {
weekday: 4, year: 1970, month: 1, day: 1,
hour: 0, minute: 0, second: 0, fractionalSecond: 0,
timezoneOffset: 0
});
};
export const isUTC = (timeZone: unknown): timeZone is 'UTC' => {
return typeof timeZone === 'string' && timeZone.toUpperCase() === 'UTC';
};
export const toParts = (dateObj: Date, zoneName: string): DateTimeParts => {
if (isUTC(zoneName)) {
return {
weekday: dateObj.getUTCDay(),
year: dateObj.getUTCFullYear(),
month: dateObj.getUTCMonth() + 1,
day: dateObj.getUTCDate(),
hour: dateObj.getUTCHours(),
minute: dateObj.getUTCMinutes(),
second: dateObj.getUTCSeconds(),
fractionalSecond: dateObj.getUTCMilliseconds(),
timezoneOffset: 0
};
}
const time = dateObj.getTime();
const parts = dtfToParts(getDateTimeFormat(zoneName), time);
parts.timezoneOffset = (time - fromParts(parts)) / 60000;
return parts;
};
export interface DateLike {
/**
* Returns the year of the date.
*/
getFullYear(): number;
/**
* Returns the month of the date (0-11).
*/
getMonth(): number;
/**
* Returns the day of the month (1-31).
*/
getDate(): number;
/**
* Returns the hours of the date (0-23).
*/
getHours(): number;
/**
* Returns the minutes of the date (0-59).
*/
getMinutes(): number;
/**
* Returns the seconds of the date (0-59).
*/
getSeconds(): number;
/**
* Returns the milliseconds of the date (0-999).
*/
getMilliseconds(): number;
/**
* Returns the day of the week (0-6, where 0 is Sunday).
*/
getDay(): number;
/**
* Returns the time value in milliseconds since the Unix epoch (January 1, 1970).
*/
getTime(): number;
/**
* Returns the timezone offset in minutes from UTC.
*/
getTimezoneOffset(): number;
}
export class DateTime implements DateLike {
private readonly parts: DateTimeParts;
private readonly time: number;
constructor (dateObj: Date, zoneName: string) {
this.parts = toParts(dateObj, zoneName);
this.time = dateObj.getTime();
}
getFullYear () {
return this.parts.year;
}
getMonth () {
return this.parts.month - 1;
}
getDate () {
return this.parts.day;
}
getHours () {
return this.parts.hour;
}
getMinutes () {
return this.parts.minute;
}
getSeconds () {
return this.parts.second;
}
getMilliseconds () {
return this.parts.fractionalSecond;
}
getDay () {
return this.parts.weekday;
}
getTime () {
return this.time;
}
getTimezoneOffset () {
return this.parts.timezoneOffset;
}
}
================================================
FILE: src/dtf.ts
================================================
const cache = new Map<string, Intl.DateTimeFormat>();
export const getDateTimeFormat = (zoneName: string): Intl.DateTimeFormat => {
return cache.get(zoneName) ?? (() => {
const dtf = new Intl.DateTimeFormat('en-US', {
hour12: false, weekday: 'short', year: 'numeric', month: 'numeric', day: 'numeric',
hour: 'numeric', minute: 'numeric', second: 'numeric', fractionalSecondDigits: 3,
timeZone: zoneName
});
if (zoneName) {
cache.set(zoneName, dtf);
}
return dtf;
})();
};
================================================
FILE: src/duration.ts
================================================
import { compile } from './compile.ts';
import latn from './numerals/latn.ts';
import type { Numeral } from './numeral.ts';
const comment = /^\[(.*)\]$/;
interface DurationFormatter {
D?: number;
H?: number;
m?: number;
s?: number;
S?: number;
f?: number;
F?: number;
}
const nanosecondsPart = (parts: DurationFormatter, time: DOMHighResTimeStamp) => {
parts.F = Math.trunc(time * 1000000);
return parts;
};
const microsecondsPart = (parts: DurationFormatter, time: DOMHighResTimeStamp) => {
parts.f = Math.trunc(time * 1000);
return nanosecondsPart(parts, Math.abs(time) * 1000 % 1 / 1000);
};
const millisecondsPart = (parts: DurationFormatter, time: DOMHighResTimeStamp) => {
parts.S = Math.trunc(time);
return microsecondsPart(parts, Math.abs(time) % 1);
};
const secondsPart = (parts: DurationFormatter, time: number) => {
parts.s = Math.trunc(time / 1000);
return millisecondsPart(parts, Math.abs(time) % 1000);
};
const minutesPart = (parts: DurationFormatter, time: number) => {
parts.m = Math.trunc(time / 60000);
return secondsPart(parts, Math.abs(time) % 60000);
};
const hoursPart = (parts: DurationFormatter, time: number) => {
parts.H = Math.trunc(time / 3600000);
return minutesPart(parts, Math.abs(time) % 3600000);
};
const daysPart = (parts: DurationFormatter, time: number) => {
parts.D = Math.trunc(time / 86400000);
return hoursPart(parts, Math.abs(time) % 86400000);
};
const sign = (time: number) => {
return time < 0 || time === 0 && (1 / time) === -Infinity ? '-' : '';
};
const format = (times: DurationFormatter, formatString: string, numeral: Numeral = latn) => {
const pattern = compile(formatString).slice(1);
const resolveToken = (token: string) => {
if (token[0] in times) {
const time = times[token[0] as keyof DurationFormatter] ?? 0;
return numeral.encode(`${sign(time)}${String(Math.abs(time)).padStart(token.length, '0')}`);
}
return comment.test(token) ? token.replace(comment, '$1') : token;
};
return pattern.reduce((result, token) => result + resolveToken(token), '');
};
export interface NanosecondsParts {
nanoseconds: number;
}
export interface MicrosecondsParts extends NanosecondsParts {
microseconds: number;
}
export interface MillisecondsParts extends MicrosecondsParts {
milliseconds: number;
}
export interface SecondsParts extends MillisecondsParts {
seconds: number;
}
export interface MinutesParts extends SecondsParts {
minutes: number;
}
export interface HoursParts extends MinutesParts {
hours: number;
}
export interface DaysParts extends HoursParts {
days: number;
}
export interface DurationDescriptor<T> {
/**
* The value of the duration in the respective unit.
*/
value: number;
/**
* Formats the duration according to the provided format string.
* @param formatString - The format string to use for formatting
* @param numeral - Optional numeral object for number formatting
* @returns Formatted string representation of the duration
*/
format: (formatString: string, numeral?: Numeral) => string;
/**
* Converts the duration to an object containing the parts of the duration in the respective unit.
* @returns An object containing the parts of the duration in the respective unit.
*/
toParts: () => T;
}
export class Duration {
private readonly time: DOMHighResTimeStamp;
constructor (time: DOMHighResTimeStamp) {
this.time = time;
}
/**
* Converts the duration to nanoseconds.
* @returns DurationDescriptor with the value in nanoseconds and methods to format and get
* the parts of the duration in nanoseconds.
*/
toNanoseconds (): DurationDescriptor<NanosecondsParts> {
return {
value: this.time * 1000000,
format: (formatString: string, numeral?: Numeral) => {
return format(nanosecondsPart({}, this.time), formatString, numeral);
},
toParts: () => {
return {
nanoseconds: Math.trunc(this.time * 1000000) + 0
};
}
};
}
/**
* Converts the duration to microseconds.
* @returns DurationDescriptor with the value in microseconds and methods to format and get
* the parts of the duration in microseconds and nanoseconds.
*/
toMicroseconds (): DurationDescriptor<MicrosecondsParts> {
return {
value: this.time * 1000,
format: (formatString: string, numeral?: Numeral) => {
return format(microsecondsPart({}, this.time), formatString, numeral);
},
toParts: () => {
return {
microseconds: Math.trunc(this.time * 1000) + 0,
nanoseconds: Math.trunc(this.time * 1000000 % 1000) + 0
};
}
};
}
/**
* Converts the duration to milliseconds.
* @returns DurationDescriptor with the value in milliseconds and methods to format and get
* the parts of the duration in milliseconds, microseconds, and nanoseconds.
*/
toMilliseconds (): DurationDescriptor<Millisecond
gitextract_4dtccixv/ ├── .editorconfig ├── .github/ │ └── workflows/ │ ├── deploy-docs.yml │ └── test.yml ├── .gitignore ├── LICENSE ├── README.md ├── astro.config.mjs ├── docs/ │ ├── api/ │ │ ├── addDays.md │ │ ├── addHours.md │ │ ├── addMilliseconds.md │ │ ├── addMinutes.md │ │ ├── addMonths.md │ │ ├── addSeconds.md │ │ ├── addYears.md │ │ ├── compile.md │ │ ├── format.md │ │ ├── index.md │ │ ├── isValid.md │ │ ├── parse.md │ │ ├── preparse.md │ │ ├── subtract.md │ │ ├── transform.md │ │ └── utils/ │ │ ├── getDaysInMonth.md │ │ ├── getISOWeek.md │ │ ├── getISOWeekYear.md │ │ ├── isLeapYear.md │ │ └── isSameDay.md │ ├── content.config.ts │ ├── env.d.ts │ ├── guide/ │ │ ├── index.md │ │ ├── installation.mdx │ │ └── quick-start.md │ ├── index.mdx │ ├── locales.md │ ├── migration.md │ ├── plugins.md │ ├── styles/ │ │ └── custom.css │ ├── timezones.md │ └── tsconfig.json ├── eslint.config.js ├── package.json ├── rollup.config.ts ├── src/ │ ├── addDays.ts │ ├── addHours.ts │ ├── addMilliseconds.ts │ ├── addMinutes.ts │ ├── addMonths.ts │ ├── addSeconds.ts │ ├── addYears.ts │ ├── compile.ts │ ├── datetime.ts │ ├── dtf.ts │ ├── duration.ts │ ├── format.ts │ ├── formatter.ts │ ├── index.ts │ ├── isValid.ts │ ├── locale.ts │ ├── locales/ │ │ ├── ar.ts │ │ ├── az.ts │ │ ├── bn.ts │ │ ├── cs.ts │ │ ├── da.ts │ │ ├── de.ts │ │ ├── el.ts │ │ ├── en.ts │ │ ├── es.ts │ │ ├── fa.ts │ │ ├── fi.ts │ │ ├── fr.ts │ │ ├── he.ts │ │ ├── hi.ts │ │ ├── hu.ts │ │ ├── id.ts │ │ ├── it.ts │ │ ├── ja.ts │ │ ├── ko.ts │ │ ├── ms.ts │ │ ├── my.ts │ │ ├── nl.ts │ │ ├── no.ts │ │ ├── pl.ts │ │ ├── pt-BR.ts │ │ ├── pt-PT.ts │ │ ├── ro.ts │ │ ├── ru.ts │ │ ├── rw.ts │ │ ├── sr-Cyrl.ts │ │ ├── sr-Latn.ts │ │ ├── sv.ts │ │ ├── ta.ts │ │ ├── th.ts │ │ ├── tr.ts │ │ ├── uk.ts │ │ ├── uz-Cyrl.ts │ │ ├── uz-Latn.ts │ │ ├── vi.ts │ │ ├── zh-Hans.ts │ │ └── zh-Hant.ts │ ├── numeral.ts │ ├── numerals/ │ │ ├── arab.ts │ │ ├── arabext.ts │ │ ├── beng.ts │ │ ├── latn.ts │ │ └── mymr.ts │ ├── parse.ts │ ├── parser.ts │ ├── plugin.ts │ ├── plugins/ │ │ ├── day-of-week.ts │ │ ├── microsecond.ts │ │ ├── nanosecond.ts │ │ ├── ordinal.ts │ │ ├── quarter.ts │ │ ├── timestamp.ts │ │ ├── two-digit-year.ts │ │ ├── week.ts │ │ └── zonename.ts │ ├── preparse.ts │ ├── subtract.ts │ ├── timezone.ts │ ├── timezones/ │ │ ├── Africa/ │ │ │ ├── Abidjan.ts │ │ │ ├── Accra.ts │ │ │ ├── Addis_Ababa.ts │ │ │ ├── Algiers.ts │ │ │ ├── Asmara.ts │ │ │ ├── Bamako.ts │ │ │ ├── Bangui.ts │ │ │ ├── Banjul.ts │ │ │ ├── Bissau.ts │ │ │ ├── Blantyre.ts │ │ │ ├── Brazzaville.ts │ │ │ ├── Bujumbura.ts │ │ │ ├── Cairo.ts │ │ │ ├── Casablanca.ts │ │ │ ├── Ceuta.ts │ │ │ ├── Conakry.ts │ │ │ ├── Dakar.ts │ │ │ ├── Dar_es_Salaam.ts │ │ │ ├── Djibouti.ts │ │ │ ├── Douala.ts │ │ │ ├── El_Aaiun.ts │ │ │ ├── Freetown.ts │ │ │ ├── Gaborone.ts │ │ │ ├── Harare.ts │ │ │ ├── Johannesburg.ts │ │ │ ├── Juba.ts │ │ │ ├── Kampala.ts │ │ │ ├── Khartoum.ts │ │ │ ├── Kigali.ts │ │ │ ├── Kinshasa.ts │ │ │ ├── Lagos.ts │ │ │ ├── Libreville.ts │ │ │ ├── Lome.ts │ │ │ ├── Luanda.ts │ │ │ ├── Lubumbashi.ts │ │ │ ├── Lusaka.ts │ │ │ ├── Malabo.ts │ │ │ ├── Maputo.ts │ │ │ ├── Maseru.ts │ │ │ ├── Mbabane.ts │ │ │ ├── Mogadishu.ts │ │ │ ├── Monrovia.ts │ │ │ ├── Nairobi.ts │ │ │ ├── Ndjamena.ts │ │ │ ├── Niamey.ts │ │ │ ├── Nouakchott.ts │ │ │ ├── Ouagadougou.ts │ │ │ ├── Porto-Novo.ts │ │ │ ├── Sao_Tome.ts │ │ │ ├── Tripoli.ts │ │ │ ├── Tunis.ts │ │ │ └── Windhoek.ts │ │ ├── America/ │ │ │ ├── Adak.ts │ │ │ ├── Anchorage.ts │ │ │ ├── Anguilla.ts │ │ │ ├── Antigua.ts │ │ │ ├── Araguaina.ts │ │ │ ├── Argentina/ │ │ │ │ ├── Buenos_Aires.ts │ │ │ │ ├── Catamarca.ts │ │ │ │ ├── Cordoba.ts │ │ │ │ ├── Jujuy.ts │ │ │ │ ├── La_Rioja.ts │ │ │ │ ├── Mendoza.ts │ │ │ │ ├── Rio_Gallegos.ts │ │ │ │ ├── Salta.ts │ │ │ │ ├── San_Juan.ts │ │ │ │ ├── San_Luis.ts │ │ │ │ ├── Tucuman.ts │ │ │ │ └── Ushuaia.ts │ │ │ ├── Aruba.ts │ │ │ ├── Asuncion.ts │ │ │ ├── Atikokan.ts │ │ │ ├── Bahia.ts │ │ │ ├── Bahia_Banderas.ts │ │ │ ├── Barbados.ts │ │ │ ├── Belem.ts │ │ │ ├── Belize.ts │ │ │ ├── Blanc-Sablon.ts │ │ │ ├── Boa_Vista.ts │ │ │ ├── Bogota.ts │ │ │ ├── Boise.ts │ │ │ ├── Cambridge_Bay.ts │ │ │ ├── Campo_Grande.ts │ │ │ ├── Cancun.ts │ │ │ ├── Caracas.ts │ │ │ ├── Cayenne.ts │ │ │ ├── Cayman.ts │ │ │ ├── Chicago.ts │ │ │ ├── Chihuahua.ts │ │ │ ├── Ciudad_Juarez.ts │ │ │ ├── Costa_Rica.ts │ │ │ ├── Coyhaique.ts │ │ │ ├── Creston.ts │ │ │ ├── Cuiaba.ts │ │ │ ├── Curacao.ts │ │ │ ├── Danmarkshavn.ts │ │ │ ├── Dawson.ts │ │ │ ├── Dawson_Creek.ts │ │ │ ├── Denver.ts │ │ │ ├── Detroit.ts │ │ │ ├── Dominica.ts │ │ │ ├── Edmonton.ts │ │ │ ├── Eirunepe.ts │ │ │ ├── El_Salvador.ts │ │ │ ├── Fort_Nelson.ts │ │ │ ├── Fortaleza.ts │ │ │ ├── Glace_Bay.ts │ │ │ ├── Goose_Bay.ts │ │ │ ├── Grand_Turk.ts │ │ │ ├── Grenada.ts │ │ │ ├── Guadeloupe.ts │ │ │ ├── Guatemala.ts │ │ │ ├── Guayaquil.ts │ │ │ ├── Guyana.ts │ │ │ ├── Halifax.ts │ │ │ ├── Havana.ts │ │ │ ├── Hermosillo.ts │ │ │ ├── Indiana/ │ │ │ │ ├── Indianapolis.ts │ │ │ │ ├── Knox.ts │ │ │ │ ├── Marengo.ts │ │ │ │ ├── Petersburg.ts │ │ │ │ ├── Tell_City.ts │ │ │ │ ├── Vevay.ts │ │ │ │ ├── Vincennes.ts │ │ │ │ └── Winamac.ts │ │ │ ├── Inuvik.ts │ │ │ ├── Iqaluit.ts │ │ │ ├── Jamaica.ts │ │ │ ├── Juneau.ts │ │ │ ├── Kentucky/ │ │ │ │ ├── Louisville.ts │ │ │ │ └── Monticello.ts │ │ │ ├── Kralendijk.ts │ │ │ ├── La_Paz.ts │ │ │ ├── Lima.ts │ │ │ ├── Los_Angeles.ts │ │ │ ├── Lower_Princes.ts │ │ │ ├── Maceio.ts │ │ │ ├── Managua.ts │ │ │ ├── Manaus.ts │ │ │ ├── Marigot.ts │ │ │ ├── Martinique.ts │ │ │ ├── Matamoros.ts │ │ │ ├── Mazatlan.ts │ │ │ ├── Menominee.ts │ │ │ ├── Merida.ts │ │ │ ├── Metlakatla.ts │ │ │ ├── Mexico_City.ts │ │ │ ├── Miquelon.ts │ │ │ ├── Moncton.ts │ │ │ ├── Monterrey.ts │ │ │ ├── Montevideo.ts │ │ │ ├── Montserrat.ts │ │ │ ├── Nassau.ts │ │ │ ├── New_York.ts │ │ │ ├── Nome.ts │ │ │ ├── Noronha.ts │ │ │ ├── North_Dakota/ │ │ │ │ ├── Beulah.ts │ │ │ │ ├── Center.ts │ │ │ │ └── New_Salem.ts │ │ │ ├── Nuuk.ts │ │ │ ├── Ojinaga.ts │ │ │ ├── Panama.ts │ │ │ ├── Paramaribo.ts │ │ │ ├── Phoenix.ts │ │ │ ├── Port-au-Prince.ts │ │ │ ├── Port_of_Spain.ts │ │ │ ├── Porto_Velho.ts │ │ │ ├── Puerto_Rico.ts │ │ │ ├── Punta_Arenas.ts │ │ │ ├── Rankin_Inlet.ts │ │ │ ├── Recife.ts │ │ │ ├── Regina.ts │ │ │ ├── Resolute.ts │ │ │ ├── Rio_Branco.ts │ │ │ ├── Santarem.ts │ │ │ ├── Santiago.ts │ │ │ ├── Santo_Domingo.ts │ │ │ ├── Sao_Paulo.ts │ │ │ ├── Scoresbysund.ts │ │ │ ├── Sitka.ts │ │ │ ├── St_Barthelemy.ts │ │ │ ├── St_Johns.ts │ │ │ ├── St_Kitts.ts │ │ │ ├── St_Lucia.ts │ │ │ ├── St_Thomas.ts │ │ │ ├── St_Vincent.ts │ │ │ ├── Swift_Current.ts │ │ │ ├── Tegucigalpa.ts │ │ │ ├── Thule.ts │ │ │ ├── Tijuana.ts │ │ │ ├── Toronto.ts │ │ │ ├── Tortola.ts │ │ │ ├── Vancouver.ts │ │ │ ├── Whitehorse.ts │ │ │ ├── Winnipeg.ts │ │ │ └── Yakutat.ts │ │ ├── Antarctica/ │ │ │ ├── Casey.ts │ │ │ ├── Davis.ts │ │ │ ├── DumontDUrville.ts │ │ │ ├── Macquarie.ts │ │ │ ├── Mawson.ts │ │ │ ├── McMurdo.ts │ │ │ ├── Palmer.ts │ │ │ ├── Rothera.ts │ │ │ ├── Syowa.ts │ │ │ ├── Troll.ts │ │ │ └── Vostok.ts │ │ ├── Arctic/ │ │ │ └── Longyearbyen.ts │ │ ├── Asia/ │ │ │ ├── Aden.ts │ │ │ ├── Almaty.ts │ │ │ ├── Amman.ts │ │ │ ├── Anadyr.ts │ │ │ ├── Aqtau.ts │ │ │ ├── Aqtobe.ts │ │ │ ├── Ashgabat.ts │ │ │ ├── Atyrau.ts │ │ │ ├── Baghdad.ts │ │ │ ├── Bahrain.ts │ │ │ ├── Baku.ts │ │ │ ├── Bangkok.ts │ │ │ ├── Barnaul.ts │ │ │ ├── Beirut.ts │ │ │ ├── Bishkek.ts │ │ │ ├── Brunei.ts │ │ │ ├── Chita.ts │ │ │ ├── Colombo.ts │ │ │ ├── Damascus.ts │ │ │ ├── Dhaka.ts │ │ │ ├── Dili.ts │ │ │ ├── Dubai.ts │ │ │ ├── Dushanbe.ts │ │ │ ├── Famagusta.ts │ │ │ ├── Gaza.ts │ │ │ ├── Hebron.ts │ │ │ ├── Ho_Chi_Minh.ts │ │ │ ├── Hong_Kong.ts │ │ │ ├── Hovd.ts │ │ │ ├── Irkutsk.ts │ │ │ ├── Jakarta.ts │ │ │ ├── Jayapura.ts │ │ │ ├── Jerusalem.ts │ │ │ ├── Kabul.ts │ │ │ ├── Kamchatka.ts │ │ │ ├── Karachi.ts │ │ │ ├── Kathmandu.ts │ │ │ ├── Khandyga.ts │ │ │ ├── Kolkata.ts │ │ │ ├── Krasnoyarsk.ts │ │ │ ├── Kuala_Lumpur.ts │ │ │ ├── Kuching.ts │ │ │ ├── Kuwait.ts │ │ │ ├── Macau.ts │ │ │ ├── Magadan.ts │ │ │ ├── Makassar.ts │ │ │ ├── Manila.ts │ │ │ ├── Muscat.ts │ │ │ ├── Nicosia.ts │ │ │ ├── Novokuznetsk.ts │ │ │ ├── Novosibirsk.ts │ │ │ ├── Omsk.ts │ │ │ ├── Oral.ts │ │ │ ├── Phnom_Penh.ts │ │ │ ├── Pontianak.ts │ │ │ ├── Pyongyang.ts │ │ │ ├── Qatar.ts │ │ │ ├── Qostanay.ts │ │ │ ├── Qyzylorda.ts │ │ │ ├── Riyadh.ts │ │ │ ├── Sakhalin.ts │ │ │ ├── Samarkand.ts │ │ │ ├── Seoul.ts │ │ │ ├── Shanghai.ts │ │ │ ├── Singapore.ts │ │ │ ├── Srednekolymsk.ts │ │ │ ├── Taipei.ts │ │ │ ├── Tashkent.ts │ │ │ ├── Tbilisi.ts │ │ │ ├── Tehran.ts │ │ │ ├── Thimphu.ts │ │ │ ├── Tokyo.ts │ │ │ ├── Tomsk.ts │ │ │ ├── Ulaanbaatar.ts │ │ │ ├── Urumqi.ts │ │ │ ├── Ust-Nera.ts │ │ │ ├── Vientiane.ts │ │ │ ├── Vladivostok.ts │ │ │ ├── Yakutsk.ts │ │ │ ├── Yangon.ts │ │ │ ├── Yekaterinburg.ts │ │ │ └── Yerevan.ts │ │ ├── Atlantic/ │ │ │ ├── Azores.ts │ │ │ ├── Bermuda.ts │ │ │ ├── Canary.ts │ │ │ ├── Cape_Verde.ts │ │ │ ├── Faroe.ts │ │ │ ├── Madeira.ts │ │ │ ├── Reykjavik.ts │ │ │ ├── South_Georgia.ts │ │ │ ├── St_Helena.ts │ │ │ └── Stanley.ts │ │ ├── Australia/ │ │ │ ├── Adelaide.ts │ │ │ ├── Brisbane.ts │ │ │ ├── Broken_Hill.ts │ │ │ ├── Darwin.ts │ │ │ ├── Eucla.ts │ │ │ ├── Hobart.ts │ │ │ ├── Lindeman.ts │ │ │ ├── Lord_Howe.ts │ │ │ ├── Melbourne.ts │ │ │ ├── Perth.ts │ │ │ └── Sydney.ts │ │ ├── Europe/ │ │ │ ├── Amsterdam.ts │ │ │ ├── Andorra.ts │ │ │ ├── Astrakhan.ts │ │ │ ├── Athens.ts │ │ │ ├── Belgrade.ts │ │ │ ├── Berlin.ts │ │ │ ├── Bratislava.ts │ │ │ ├── Brussels.ts │ │ │ ├── Bucharest.ts │ │ │ ├── Budapest.ts │ │ │ ├── Busingen.ts │ │ │ ├── Chisinau.ts │ │ │ ├── Copenhagen.ts │ │ │ ├── Dublin.ts │ │ │ ├── Gibraltar.ts │ │ │ ├── Guernsey.ts │ │ │ ├── Helsinki.ts │ │ │ ├── Isle_of_Man.ts │ │ │ ├── Istanbul.ts │ │ │ ├── Jersey.ts │ │ │ ├── Kaliningrad.ts │ │ │ ├── Kirov.ts │ │ │ ├── Kyiv.ts │ │ │ ├── Lisbon.ts │ │ │ ├── Ljubljana.ts │ │ │ ├── London.ts │ │ │ ├── Luxembourg.ts │ │ │ ├── Madrid.ts │ │ │ ├── Malta.ts │ │ │ ├── Mariehamn.ts │ │ │ ├── Minsk.ts │ │ │ ├── Monaco.ts │ │ │ ├── Moscow.ts │ │ │ ├── Oslo.ts │ │ │ ├── Paris.ts │ │ │ ├── Podgorica.ts │ │ │ ├── Prague.ts │ │ │ ├── Riga.ts │ │ │ ├── Rome.ts │ │ │ ├── Samara.ts │ │ │ ├── San_Marino.ts │ │ │ ├── Sarajevo.ts │ │ │ ├── Saratov.ts │ │ │ ├── Simferopol.ts │ │ │ ├── Skopje.ts │ │ │ ├── Sofia.ts │ │ │ ├── Stockholm.ts │ │ │ ├── Tallinn.ts │ │ │ ├── Tirane.ts │ │ │ ├── Ulyanovsk.ts │ │ │ ├── Vaduz.ts │ │ │ ├── Vatican.ts │ │ │ ├── Vienna.ts │ │ │ ├── Vilnius.ts │ │ │ ├── Volgograd.ts │ │ │ ├── Warsaw.ts │ │ │ ├── Zagreb.ts │ │ │ └── Zurich.ts │ │ ├── Indian/ │ │ │ ├── Antananarivo.ts │ │ │ ├── Chagos.ts │ │ │ ├── Christmas.ts │ │ │ ├── Cocos.ts │ │ │ ├── Comoro.ts │ │ │ ├── Kerguelen.ts │ │ │ ├── Mahe.ts │ │ │ ├── Maldives.ts │ │ │ ├── Mauritius.ts │ │ │ ├── Mayotte.ts │ │ │ └── Reunion.ts │ │ └── Pacific/ │ │ ├── Apia.ts │ │ ├── Auckland.ts │ │ ├── Bougainville.ts │ │ ├── Chatham.ts │ │ ├── Chuuk.ts │ │ ├── Easter.ts │ │ ├── Efate.ts │ │ ├── Fakaofo.ts │ │ ├── Fiji.ts │ │ ├── Funafuti.ts │ │ ├── Galapagos.ts │ │ ├── Gambier.ts │ │ ├── Guadalcanal.ts │ │ ├── Guam.ts │ │ ├── Honolulu.ts │ │ ├── Kanton.ts │ │ ├── Kiritimati.ts │ │ ├── Kosrae.ts │ │ ├── Kwajalein.ts │ │ ├── Majuro.ts │ │ ├── Marquesas.ts │ │ ├── Midway.ts │ │ ├── Nauru.ts │ │ ├── Niue.ts │ │ ├── Norfolk.ts │ │ ├── Noumea.ts │ │ ├── Pago_Pago.ts │ │ ├── Palau.ts │ │ ├── Pitcairn.ts │ │ ├── Pohnpei.ts │ │ ├── Port_Moresby.ts │ │ ├── Rarotonga.ts │ │ ├── Saipan.ts │ │ ├── Tahiti.ts │ │ ├── Tarawa.ts │ │ ├── Tongatapu.ts │ │ ├── Wake.ts │ │ └── Wallis.ts │ ├── transform.ts │ ├── utils.ts │ ├── zone.ts │ └── zonenames.ts ├── tests/ │ ├── addDays.spec.ts │ ├── addHours.spec.ts │ ├── addMilliseconds.spec.ts │ ├── addMinutes.spec.ts │ ├── addMonths.spec.ts │ ├── addSeconds.spec.ts │ ├── addYears.spec.ts │ ├── compile.spec.ts │ ├── duration.spec.ts │ ├── format.spec.ts │ ├── isValid.spec.ts │ ├── locales/ │ │ ├── ar.spec.ts │ │ ├── az.spec.ts │ │ ├── bn.spec.ts │ │ ├── cs.spec.ts │ │ ├── da.spec.ts │ │ ├── de.spec.ts │ │ ├── el.spec.ts │ │ ├── en.spec.ts │ │ ├── es.spec.ts │ │ ├── fa.spec.ts │ │ ├── fi.spec.ts │ │ ├── fr.spec.ts │ │ ├── he.spec.ts │ │ ├── hi.spec.ts │ │ ├── hu.spec.ts │ │ ├── id.spec.ts │ │ ├── it.spec.ts │ │ ├── ja.spec.ts │ │ ├── ko.spec.ts │ │ ├── ms.spec.ts │ │ ├── my.spec.ts │ │ ├── nl.spec.ts │ │ ├── no.spec.ts │ │ ├── pl.spec.ts │ │ ├── pt-BR.spec.ts │ │ ├── pt-PT.spec.ts │ │ ├── ro.spec.ts │ │ ├── ru.spec.ts │ │ ├── rw.spec.ts │ │ ├── sr-Cyrl.spec.ts │ │ ├── sr-Latn.spec.ts │ │ ├── sv.spec.ts │ │ ├── ta.spec.ts │ │ ├── th.spec.ts │ │ ├── tr.spec.ts │ │ ├── uk.spec.ts │ │ ├── uz-Cyrl.spec.ts │ │ ├── uz-Latn.spec.ts │ │ ├── vi.spec.ts │ │ ├── zh-Hans.spec.ts │ │ └── zh-Hant.spec.ts │ ├── numerals/ │ │ ├── arab.spec.ts │ │ ├── arabext.spec.ts │ │ ├── beng.spec.ts │ │ ├── latn.spec.ts │ │ └── mymr.spec.ts │ ├── parse.spec.ts │ ├── plugins/ │ │ ├── microsecond.spec.ts │ │ ├── nanosecond.spec.ts │ │ ├── ordinal.spec.ts │ │ ├── quarter.spec.ts │ │ ├── timestamp.spec.ts │ │ ├── two-digit-year.spec.ts │ │ ├── week.spec.ts │ │ └── zonename.spec.ts │ ├── preparse.spec.ts │ ├── subtract.spec.ts │ ├── timezones/ │ │ └── timezones.spec.ts │ ├── transform.spec.ts │ └── utils.spec.ts ├── tools/ │ ├── locale.ts │ ├── timezone.ts │ └── zonename.ts ├── tsconfig.json └── vitest.config.ts
SYMBOL INDEX (325 symbols across 71 files)
FILE: src/addDays.ts
function addDays (line 12) | function addDays(dateObj: Date, days: number, timeZone?: TimeZone | stri...
FILE: src/addHours.ts
function addHours (line 7) | function addHours(dateObj: Date, hours: number) {
FILE: src/addMilliseconds.ts
function addMilliseconds (line 7) | function addMilliseconds(dateObj: Date, milliseconds: number) {
FILE: src/addMinutes.ts
function addMinutes (line 7) | function addMinutes(dateObj: Date, minutes: number) {
FILE: src/addMonths.ts
function addMonths (line 12) | function addMonths(dateObj: Date, months: number, timeZone?: TimeZone | ...
FILE: src/addSeconds.ts
function addSeconds (line 7) | function addSeconds(dateObj: Date, seconds: number) {
FILE: src/addYears.ts
function addYears (line 11) | function addYears(dateObj: Date, years: number, timeZone?: TimeZone | st...
FILE: src/compile.ts
type CompiledObject (line 3) | type CompiledObject = string[];
constant LBRACKET (line 6) | const LBRACKET = /\\\[/g;
constant RBRACKET (line 7) | const RBRACKET = /\\\]/g;
constant PUA_LBRACKET (line 10) | const PUA_LBRACKET = /\uE000/g;
constant PUA_RBRACKET (line 11) | const PUA_RBRACKET = /\uE001/g;
constant REGEXP (line 14) | const REGEXP = /\[(?:[^[\]]|\[[^[\]]*])*]|([A-Za-z])\1*|\.{3}|./g;
FILE: src/datetime.ts
type DateTimeParts (line 3) | interface DateTimeParts {
type DateLike (line 79) | interface DateLike {
class DateTime (line 122) | class DateTime implements DateLike {
method constructor (line 127) | constructor (dateObj: Date, zoneName: string) {
method getFullYear (line 132) | getFullYear () {
method getMonth (line 136) | getMonth () {
method getDate (line 140) | getDate () {
method getHours (line 144) | getHours () {
method getMinutes (line 148) | getMinutes () {
method getSeconds (line 152) | getSeconds () {
method getMilliseconds (line 156) | getMilliseconds () {
method getDay (line 160) | getDay () {
method getTime (line 164) | getTime () {
method getTimezoneOffset (line 168) | getTimezoneOffset () {
FILE: src/duration.ts
type DurationFormatter (line 7) | interface DurationFormatter {
type NanosecondsParts (line 69) | interface NanosecondsParts {
type MicrosecondsParts (line 73) | interface MicrosecondsParts extends NanosecondsParts {
type MillisecondsParts (line 77) | interface MillisecondsParts extends MicrosecondsParts {
type SecondsParts (line 81) | interface SecondsParts extends MillisecondsParts {
type MinutesParts (line 85) | interface MinutesParts extends SecondsParts {
type HoursParts (line 89) | interface HoursParts extends MinutesParts {
type DaysParts (line 93) | interface DaysParts extends HoursParts {
type DurationDescriptor (line 97) | interface DurationDescriptor<T> {
class Duration (line 118) | class Duration {
method constructor (line 121) | constructor (time: DOMHighResTimeStamp) {
method toNanoseconds (line 130) | toNanoseconds (): DurationDescriptor<NanosecondsParts> {
method toMicroseconds (line 149) | toMicroseconds (): DurationDescriptor<MicrosecondsParts> {
method toMilliseconds (line 169) | toMilliseconds (): DurationDescriptor<MillisecondsParts> {
method toSeconds (line 190) | toSeconds (): DurationDescriptor<SecondsParts> {
method toMinutes (line 212) | toMinutes (): DurationDescriptor<MinutesParts> {
method toHours (line 235) | toHours (): DurationDescriptor<HoursParts> {
method toDays (line 259) | toDays (): DurationDescriptor<DaysParts> {
FILE: src/format.ts
function format (line 19) | function format(dateObj: Date, arg: string | CompiledObject, options?: F...
FILE: src/formatter.ts
type FormatterPluginOptions (line 7) | interface FormatterPluginOptions {
type FormatterOptions (line 52) | interface FormatterOptions extends Partial<FormatterPluginOptions> {
class DefaultFormatter (line 60) | class DefaultFormatter extends FormatterPlugin {
method YYYY (line 61) | YYYY (d: DateLike, options: FormatterPluginOptions) {
method YY (line 65) | YY (d: DateLike, options: FormatterPluginOptions) {
method Y (line 69) | Y (d: DateLike, options: FormatterPluginOptions) {
method MMMM (line 73) | MMMM (d: DateLike, options: FormatterPluginOptions, compiledObj: Compi...
method MMM (line 78) | MMM (d: DateLike, options: FormatterPluginOptions, compiledObj: Compil...
method MM (line 83) | MM (d: DateLike) {
method M (line 87) | M (d: DateLike) {
method DD (line 91) | DD (d: DateLike) {
method D (line 95) | D (d: DateLike) {
method HH (line 99) | HH (d: DateLike, options: FormatterPluginOptions) {
method H (line 103) | H (d: DateLike, options: FormatterPluginOptions) {
method AA (line 107) | AA (d: DateLike, options: FormatterPluginOptions, compiledObj: Compile...
method A (line 112) | A (d: DateLike, options: FormatterPluginOptions, compiledObj: Compiled...
method aa (line 117) | aa (d: DateLike, options: FormatterPluginOptions, compiledObj: Compile...
method a (line 122) | a (d: DateLike, options: FormatterPluginOptions, compiledObj: Compiled...
method hh (line 127) | hh (d: DateLike, options: FormatterPluginOptions) {
method h (line 131) | h (d: DateLike, options: FormatterPluginOptions) {
method mm (line 135) | mm (d: DateLike) {
method m (line 139) | m (d: DateLike) {
method ss (line 143) | ss (d: DateLike) {
method s (line 147) | s (d: DateLike) {
method SSS (line 151) | SSS (d: DateLike) {
method SS (line 155) | SS (d: DateLike) {
method S (line 159) | S (d: DateLike) {
method dddd (line 163) | dddd (d: DateLike, options: FormatterPluginOptions, compiledObj: Compi...
method ddd (line 168) | ddd (d: DateLike, options: FormatterPluginOptions, compiledObj: Compil...
method dd (line 173) | dd (d: DateLike, options: FormatterPluginOptions, compiledObj: Compile...
method Z (line 178) | Z (d: DateLike) {
method ZZ (line 184) | ZZ (d: DateLike) {
FILE: src/isValid.ts
function validatePreparseResult (line 43) | function validatePreparseResult(pr: PreparseResult, options?: ParserOpti...
function isValid (line 74) | function isValid(dateString: string, arg: string | CompiledObject, optio...
FILE: src/locale.ts
type LocaleOptions (line 3) | interface LocaleOptions {
type Locale (line 9) | interface Locale {
FILE: src/locales/ar.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/az.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/bn.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/cs.ts
method getLocale (line 26) | getLocale () {
method getMonthList (line 30) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 36) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 44) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/da.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/de.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/el.ts
method getLocale (line 23) | getLocale () {
method getMonthList (line 27) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 33) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 41) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/en.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/es.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/fa.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/fi.ts
method getLocale (line 26) | getLocale () {
method getMonthList (line 30) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 36) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 44) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/fr.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/he.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/hi.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/hu.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/id.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/it.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/ja.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/ko.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/ms.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/my.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/nl.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/no.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/pl.ts
method getLocale (line 23) | getLocale () {
method getMonthList (line 27) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 33) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 41) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/pt-BR.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/pt-PT.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/ro.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/ru.ts
method getLocale (line 26) | getLocale () {
method getMonthList (line 30) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 36) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 44) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/rw.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/sr-Cyrl.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/sr-Latn.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/sv.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/ta.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/th.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/tr.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/uk.ts
method getLocale (line 23) | getLocale () {
method getMonthList (line 27) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 33) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 41) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/uz-Cyrl.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/uz-Latn.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/vi.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/zh-Hans.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/locales/zh-Hant.ts
method getLocale (line 20) | getLocale () {
method getMonthList (line 24) | getMonthList (options: LocaleOptions) {
method getDayOfWeekList (line 30) | getDayOfWeekList (options: LocaleOptions) {
method getMeridiemList (line 38) | getMeridiemList (options: LocaleOptions) {
FILE: src/numeral.ts
type Numeral (line 1) | interface Numeral {
FILE: src/parse.ts
function parse (line 26) | function parse(dateString: string, arg: string | CompiledObject, options...
FILE: src/parser.ts
type ParserToken (line 6) | type ParserToken = 'Y' | 'M' | 'D' | 'H' | 'A' | 'h' | 'm' | 's' | 'S' |...
type ParsedComponents (line 8) | interface ParsedComponents {
type ParserPluginOptions (line 60) | interface ParserPluginOptions {
type ParseResult (line 115) | interface ParseResult {
type ParserOptions (line 125) | interface ParserOptions extends Partial<ParserPluginOptions> {
constant VALID_TOKENS (line 161) | const VALID_TOKENS = new Set<ParserToken>(['Y', 'M', 'D', 'H', 'A', 'h',...
class DefaultParser (line 170) | class DefaultParser extends ParserPlugin {
method YYYY (line 171) | YYYY (str: string) {
method Y (line 175) | Y (str: string) {
method MMMM (line 179) | MMMM (str: string, options: ParserPluginOptions, compiledObj: Compiled...
method MMM (line 187) | MMM (str: string, options: ParserPluginOptions, compiledObj: CompiledO...
method MM (line 195) | MM (str: string) {
method M (line 199) | M (str: string) {
method DD (line 203) | DD (str: string) {
method D (line 207) | D (str: string) {
method HH (line 211) | HH (str: string) {
method H (line 215) | H (str: string) {
method AA (line 219) | AA (str: string, options: ParserPluginOptions, compiledObj: CompiledOb...
method A (line 224) | A (str: string, options: ParserPluginOptions, compiledObj: CompiledObj...
method aa (line 229) | aa (str: string, options: ParserPluginOptions, compiledObj: CompiledOb...
method a (line 234) | a (str: string, options: ParserPluginOptions, compiledObj: CompiledObj...
method hh (line 239) | hh (str: string) {
method h (line 243) | h (str: string) {
method mm (line 247) | mm (str: string) {
method m (line 251) | m (str: string) {
method ss (line 255) | ss (str: string) {
method s (line 259) | s (str: string) {
method SSS (line 263) | SSS (str: string) {
method SS (line 267) | SS (str: string) {
method S (line 273) | S (str: string) {
method Z (line 279) | Z (str: string) {
method ZZ (line 285) | ZZ (str: string) {
FILE: src/plugins/day-of-week.ts
class Parser (line 3) | class Parser extends ParserPlugin {
method dddd (line 4) | dddd (str: string, options: ParserPluginOptions, compiledObj: Compiled...
method ddd (line 9) | ddd (str: string, options: ParserPluginOptions, compiledObj: CompiledO...
method dd (line 14) | dd (str: string, options: ParserPluginOptions, compiledObj: CompiledOb...
FILE: src/plugins/microsecond.ts
class Parser (line 3) | class Parser extends ParserPlugin {
method SSSS (line 4) | SSSS (str: string) {
method SSSSS (line 11) | SSSSS (str: string) {
method SSSSSS (line 18) | SSSSSS (str: string) {
method f (line 25) | f (str: string) {
method ff (line 29) | ff (str: string) {
method fff (line 33) | fff (str: string) {
FILE: src/plugins/nanosecond.ts
class Parser (line 3) | class Parser extends ParserPlugin {
method SSSSSSS (line 4) | SSSSSSS (str: string) {
method SSSSSSSS (line 11) | SSSSSSSS (str: string) {
method SSSSSSSSS (line 18) | SSSSSSSSS (str: string) {
method F (line 25) | F (str: string) {
method FF (line 29) | FF (str: string) {
method FFF (line 33) | FFF (str: string) {
FILE: src/plugins/ordinal.ts
class Formatter (line 4) | class Formatter extends FormatterPlugin {
method DDD (line 5) | DDD (d: DateLike) {
class Parser (line 25) | class Parser extends ParserPlugin {
method DDD (line 26) | DDD (str: string, options: ParserPluginOptions) {
FILE: src/plugins/quarter.ts
class Formatter (line 4) | class Formatter extends FormatterPlugin {
method Q (line 5) | Q (d: DateLike) {
FILE: src/plugins/timestamp.ts
class Formatter (line 4) | class Formatter extends FormatterPlugin {
method t (line 5) | t (d: DateLike) {
method T (line 9) | T (d: DateLike) {
FILE: src/plugins/two-digit-year.ts
class Parser (line 4) | class Parser extends ParserPlugin {
method YY (line 5) | YY (str: string, options: ParserPluginOptions) {
FILE: src/plugins/week.ts
class Formatter (line 9) | class Formatter extends FormatterPlugin {
method W (line 10) | W (d: DateLike) {
method WW (line 14) | WW (d: DateLike) {
method GGGG (line 18) | GGGG (d: DateLike) {
method GG (line 22) | GG (d: DateLike) {
method G (line 26) | G (d: DateLike) {
FILE: src/plugins/zonename.ts
class Formatter (line 18) | class Formatter extends FormatterPlugin {
method z (line 19) | z (d: DateLike, options: FormatterPluginOptions) {
method zz (line 24) | zz (d: DateLike, options: FormatterPluginOptions) {
FILE: src/preparse.ts
type PreparseResult (line 9) | interface PreparseResult extends ParsedComponents {
function preparse (line 37) | function preparse(dateString: string, arg: string | CompiledObject, opti...
FILE: src/transform.ts
function transform (line 16) | function transform(dateString: string, arg1: string | CompiledObject, ar...
FILE: src/utils.ts
function getDaysInMonth (line 39) | function getDaysInMonth (...args: [date: Date] | [year: number, month: n...
function getISOWeekYear (line 76) | function getISOWeekYear (...args: [date: Date] | [year: number, month: n...
function getISOWeek (line 102) | function getISOWeek (...args: [date: Date] | [year: number, month: numbe...
FILE: src/zone.ts
type TimeZone (line 4) | interface TimeZone {
Condensed preview — 618 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (929K chars).
[
{
"path": ".editorconfig",
"chars": 110,
"preview": "root = true\n\n[*.{js,ts}]\ncharset = utf-8\nindent_size = 2\nindent_style = space\ntrim_trailing_whitespace = true\n"
},
{
"path": ".github/workflows/deploy-docs.yml",
"chars": 1188,
"preview": "name: Deploy Starlight site to GitHub Pages\n\non:\n push:\n branches:\n - master\n paths:\n - 'docs/**'\n "
},
{
"path": ".github/workflows/test.yml",
"chars": 1896,
"preview": "name: CI\n\non:\n push:\n branches: [ master, develop ]\n pull_request:\n branches: [ master, develop ]\n\njobs:\n test:"
},
{
"path": ".gitignore",
"chars": 80,
"preview": ".DS_Store\n.vscode/\ncache/\ncoverage/\ndist/\npages/\nnode_modules/\n\n# Astro\n.astro/\n"
},
{
"path": "LICENSE",
"chars": 1080,
"preview": "The MIT License (MIT)\n\nCopyright (c) 2015 KNOWLEDGECODE\n\nPermission is hereby granted, free of charge, to any person obt"
},
{
"path": "README.md",
"chars": 2171,
"preview": "# date-and-time\n\n<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/knowledgecode/date-and-time/refs/hea"
},
{
"path": "astro.config.mjs",
"chars": 3137,
"preview": "import { defineConfig } from 'astro/config';\nimport starlight from '@astrojs/starlight';\n\nexport default defineConfig({\n"
},
{
"path": "docs/api/addDays.md",
"chars": 3695,
"preview": "---\ntitle: addDays()\n---\n\nAdds or subtracts days from a Date object. Handles month boundaries, leap years, and daylight "
},
{
"path": "docs/api/addHours.md",
"chars": 3600,
"preview": "---\ntitle: addHours()\n---\n\nAdds or subtracts hours from a Date object.\n\n## Syntax\n\n```typescript\naddHours(dateObj, hours"
},
{
"path": "docs/api/addMilliseconds.md",
"chars": 3580,
"preview": "---\ntitle: addMilliseconds()\n---\n\nAdds or subtracts milliseconds from a Date object.\n\n## Syntax\n\n```typescript\naddMillis"
},
{
"path": "docs/api/addMinutes.md",
"chars": 3722,
"preview": "---\ntitle: addMinutes()\n---\n\nAdds or subtracts minutes from a Date object.\n\n## Syntax\n\n```typescript\naddMinutes(dateObj,"
},
{
"path": "docs/api/addMonths.md",
"chars": 4241,
"preview": "---\ntitle: addMonths()\n---\n\nAdds or subtracts months from a Date object. Handles month boundaries, leap years, and varyi"
},
{
"path": "docs/api/addSeconds.md",
"chars": 3292,
"preview": "---\ntitle: addSeconds()\n---\n\nAdds or subtracts seconds from a Date object.\n\n## Syntax\n\n```typescript\naddSeconds(dateObj,"
},
{
"path": "docs/api/addYears.md",
"chars": 4096,
"preview": "---\ntitle: addYears()\n---\n\nAdds or subtracts years from a Date object. Handles leap years and edge cases appropriately.\n"
},
{
"path": "docs/api/compile.md",
"chars": 7514,
"preview": "---\ntitle: compile()\n---\n\nPrecompiles a format string into a reusable compiled object for improved performance when the "
},
{
"path": "docs/api/format.md",
"chars": 11474,
"preview": "---\ntitle: format()\n---\n\nFormats a Date object according to the specified format string.\n\n## Syntax\n\n```typescript\nforma"
},
{
"path": "docs/api/index.md",
"chars": 5928,
"preview": "---\ntitle: API Reference\n---\n\nWelcome to the comprehensive API reference for date-and-time v4.x. This section provides d"
},
{
"path": "docs/api/isValid.md",
"chars": 7806,
"preview": "---\ntitle: isValid()\n---\n\nValidates whether a date string conforms to the specified format pattern and represents a vali"
},
{
"path": "docs/api/parse.md",
"chars": 20414,
"preview": "---\ntitle: parse()\n---\n\nParses a formatted date string into a Date object according to the specified format pattern.\n\n##"
},
{
"path": "docs/api/preparse.md",
"chars": 4590,
"preview": "---\ntitle: preparse()\n---\n\nPre-parses date strings and returns intermediate parsing results. This function is useful whe"
},
{
"path": "docs/api/subtract.md",
"chars": 7453,
"preview": "---\ntitle: subtract()\n---\n\nCalculates the difference between two Date objects and returns a rich Duration object with mu"
},
{
"path": "docs/api/transform.md",
"chars": 4440,
"preview": "---\ntitle: transform()\n---\n\nTransforms date strings from one format to another. This is a convenience function that comb"
},
{
"path": "docs/api/utils/getDaysInMonth.md",
"chars": 1512,
"preview": "---\ntitle: getDaysInMonth()\n---\n\nReturns the number of days in a given month of a specific year. Correctly handles leap "
},
{
"path": "docs/api/utils/getISOWeek.md",
"chars": 1654,
"preview": "---\ntitle: getISOWeek()\n---\n\nReturns the ISO 8601 week number (1–53) for a given date. ISO weeks start on Monday, and we"
},
{
"path": "docs/api/utils/getISOWeekYear.md",
"chars": 1724,
"preview": "---\ntitle: getISOWeekYear()\n---\n\nReturns the ISO 8601 week year for a given date. The ISO week year may differ from the "
},
{
"path": "docs/api/utils/isLeapYear.md",
"chars": 1805,
"preview": "---\ntitle: isLeapYear()\n---\n\nDetermines if a given year is a leap year according to the Gregorian calendar rules.\n\n## Sy"
},
{
"path": "docs/api/utils/isSameDay.md",
"chars": 1564,
"preview": "---\ntitle: isSameDay()\n---\n\nChecks if two Date objects represent the same calendar day, regardless of time.\n\n## Syntax\n\n"
},
{
"path": "docs/content.config.ts",
"chars": 317,
"preview": "import { defineCollection } from 'astro:content';\nimport { glob } from 'astro/loaders';\nimport { docsSchema } from '@ast"
},
{
"path": "docs/env.d.ts",
"chars": 39,
"preview": "/// <reference types=\"astro/client\" />\n"
},
{
"path": "docs/guide/index.md",
"chars": 4259,
"preview": "---\ntitle: Introduction\n---\n\n**date-and-time** is the simplest, most intuitive date and time library for JavaScript and "
},
{
"path": "docs/guide/installation.mdx",
"chars": 4691,
"preview": "---\ntitle: Installation\n---\n\nimport { Aside, Tabs, TabItem } from '@astrojs/starlight/components';\n\nGet started with dat"
},
{
"path": "docs/guide/quick-start.md",
"chars": 4883,
"preview": "---\ntitle: Quick Start\n---\n\nThis guide will get you up and running with date-and-time in just a few minutes.\n\n## Basic E"
},
{
"path": "docs/index.mdx",
"chars": 3340,
"preview": "---\ntitle: date-and-time\ndescription: The simplest, most intuitive date and time library\ntemplate: splash\nhero:\n title:"
},
{
"path": "docs/locales.md",
"chars": 4114,
"preview": "---\ntitle: Locales\n---\n\nLocales customize the language-specific strings used in date formatting and parsing — month name"
},
{
"path": "docs/migration.md",
"chars": 8241,
"preview": "---\ntitle: Migration Guide\n---\n\nVersion `4.x` has been completely rewritten in TypeScript and some features from `3.x` a"
},
{
"path": "docs/plugins.md",
"chars": 8650,
"preview": "---\ntitle: Plugins\n---\n\n`date-and-time` adopts a plugin system. Special tokens used relatively infrequently are provided"
},
{
"path": "docs/styles/custom.css",
"chars": 3842,
"preview": "/* ─── Font sizes (match VitePress heading scale) ─── */\n:root {\n --sl-text-h1: 1.75rem;\n --sl-text-h2: 1.5rem;\n --sl"
},
{
"path": "docs/timezones.md",
"chars": 10926,
"preview": "---\ntitle: Timezones\n---\n\nTimezone support lets you format and parse dates in any timezone, regardless of the local syst"
},
{
"path": "docs/tsconfig.json",
"chars": 123,
"preview": "{\n \"extends\": \"astro/tsconfigs/base\",\n \"include\": [\"../.astro/types.d.ts\", \"./**/*\"],\n \"exclude\": [\"../node_modules\"]"
},
{
"path": "eslint.config.js",
"chars": 5628,
"preview": "import { defineConfig } from 'eslint/config';\nimport eslint from '@eslint/js';\nimport tseslint from 'typescript-eslint';"
},
{
"path": "package.json",
"chars": 2859,
"preview": "{\n \"name\": \"date-and-time\",\n \"version\": \"4.5.0\",\n \"description\": \"The simplest, most intuitive date and time library\""
},
{
"path": "rollup.config.ts",
"chars": 2503,
"preview": "import alias from '@rollup/plugin-alias';\nimport esbuild from 'rollup-plugin-esbuild';\nimport terser from '@rollup/plugi"
},
{
"path": "src/addDays.ts",
"chars": 1163,
"preview": "import { toParts, fromParts, isUTC } from './datetime.ts';\nimport { isTimeZone, createTimezoneDate } from './zone.ts';\ni"
},
{
"path": "src/addHours.ts",
"chars": 341,
"preview": "/**\n * Adds the specified number of hours to a Date object.\n * @param dateObj - The Date object to modify\n * @param hour"
},
{
"path": "src/addMilliseconds.ts",
"chars": 380,
"preview": "/**\n * Adds the specified number of milliseconds to a Date object.\n * @param dateObj - The Date object to modify\n * @par"
},
{
"path": "src/addMinutes.ts",
"chars": 353,
"preview": "/**\n * Adds the specified number of minutes to a Date object.\n * @param dateObj - The Date object to modify\n * @param mi"
},
{
"path": "src/addMonths.ts",
"chars": 1727,
"preview": "import { toParts, fromParts, isUTC } from './datetime.ts';\nimport { isTimeZone, createTimezoneDate } from './zone.ts';\ni"
},
{
"path": "src/addSeconds.ts",
"chars": 352,
"preview": "/**\n * Adds the specified number of seconds to a Date object.\n * @param dateObj - The Date object to modify\n * @param se"
},
{
"path": "src/addYears.ts",
"chars": 570,
"preview": "import { addMonths } from './addMonths.ts';\nimport type { TimeZone } from './zone.ts';\n\n/**\n * Adds the specified number"
},
{
"path": "src/compile.ts",
"chars": 1053,
"preview": "/** @preserve Copyright (c) KNOWLEDGECODE - MIT License */\n\nexport type CompiledObject = string[];\n\n// Escape sequences "
},
{
"path": "src/datetime.ts",
"chars": 3701,
"preview": "import { getDateTimeFormat } from './dtf.ts';\n\nexport interface DateTimeParts {\n weekday: number;\n year: number;\n mon"
},
{
"path": "src/dtf.ts",
"chars": 522,
"preview": "const cache = new Map<string, Intl.DateTimeFormat>();\n\nexport const getDateTimeFormat = (zoneName: string): Intl.DateTim"
},
{
"path": "src/duration.ts",
"chars": 9051,
"preview": "import { compile } from './compile.ts';\nimport latn from './numerals/latn.ts';\nimport type { Numeral } from './numeral.t"
},
{
"path": "src/format.ts",
"chars": 1858,
"preview": "import { compile } from './compile.ts';\nimport { DateTime } from './datetime.ts';\nimport { formatter as defaultFormatter"
},
{
"path": "src/formatter.ts",
"chars": 6255,
"preview": "import type { CompiledObject } from './compile.ts';\nimport type { DateLike } from './datetime.ts';\nimport type { Locale "
},
{
"path": "src/index.ts",
"chars": 746,
"preview": "export { compile } from './compile.ts';\nexport { format } from './format.ts';\nexport { preparse } from './preparse.ts';\n"
},
{
"path": "src/isValid.ts",
"chars": 3315,
"preview": "import { preparse } from './preparse.ts';\nimport { getDaysInMonth } from './utils.ts';\nimport type { CompiledObject } fr"
},
{
"path": "src/locale.ts",
"chars": 418,
"preview": "import type { CompiledObject } from './compile.ts';\n\nexport interface LocaleOptions {\n compiledObj: CompiledObject;\n s"
},
{
"path": "src/locales/ar.ts",
"chars": 1248,
"preview": "/**\n * @file Arabic (ar)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['يناير'"
},
{
"path": "src/locales/az.ts",
"chars": 1227,
"preview": "/**\n * @file Azerbaijani (az)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['y"
},
{
"path": "src/locales/bn.ts",
"chars": 1246,
"preview": "/**\n * @file Bangla (bn)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['জানুয়"
},
{
"path": "src/locales/cs.ts",
"chars": 1554,
"preview": "/**\n * @file Czech (cs)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: [\n ['l"
},
{
"path": "src/locales/da.ts",
"chars": 1241,
"preview": "/**\n * @file Danish (da)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['januar"
},
{
"path": "src/locales/de.ts",
"chars": 1241,
"preview": "/**\n * @file German (de)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['Januar"
},
{
"path": "src/locales/el.ts",
"chars": 1496,
"preview": "/**\n * @file Greek (el)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: [\n ['Ι"
},
{
"path": "src/locales/en.ts",
"chars": 1230,
"preview": "/**\n * @file English (en)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['Janua"
},
{
"path": "src/locales/es.ts",
"chars": 1230,
"preview": "/**\n * @file Spanish (es)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['enero"
},
{
"path": "src/locales/fa.ts",
"chars": 1280,
"preview": "/**\n * @file Persian (fa)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['دی', "
},
{
"path": "src/locales/fi.ts",
"chars": 1619,
"preview": "/**\n * @file Finnish (fi)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: [\n ["
},
{
"path": "src/locales/fr.ts",
"chars": 1245,
"preview": "/**\n * @file French (fr)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['janvie"
},
{
"path": "src/locales/he.ts",
"chars": 1251,
"preview": "/**\n * @file Hebrew (he)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['ינואר'"
},
{
"path": "src/locales/hi.ts",
"chars": 1224,
"preview": "/**\n * @file Hindi (hi)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['जनवरी',"
},
{
"path": "src/locales/hu.ts",
"chars": 1251,
"preview": "/**\n * @file Hungarian (hu)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['jan"
},
{
"path": "src/locales/id.ts",
"chars": 1220,
"preview": "/**\n * @file Indonesian (id)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['Ja"
},
{
"path": "src/locales/it.ts",
"chars": 1238,
"preview": "/**\n * @file Italian (it)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['genna"
},
{
"path": "src/locales/ja.ts",
"chars": 1093,
"preview": "/**\n * @file Japanese (ja)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['1', "
},
{
"path": "src/locales/ko.ts",
"chars": 1115,
"preview": "/**\n * @file Korean (ko)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['1월', '"
},
{
"path": "src/locales/ms.ts",
"chars": 1213,
"preview": "/**\n * @file Malay (ms)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['Januari"
},
{
"path": "src/locales/my.ts",
"chars": 1251,
"preview": "/**\n * @file Burmese (my)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['ဇန်နဝ"
},
{
"path": "src/locales/nl.ts",
"chars": 1225,
"preview": "/**\n * @file Dutch (nl)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['januari"
},
{
"path": "src/locales/no.ts",
"chars": 1255,
"preview": "/**\n * @file Norwegian (no)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['jan"
},
{
"path": "src/locales/pl.ts",
"chars": 1479,
"preview": "/**\n * @file Polish (pl)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: [\n ['"
},
{
"path": "src/locales/pt-BR.ts",
"chars": 1293,
"preview": "/**\n * @file Brazilian Portuguese (pt-BR)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {"
},
{
"path": "src/locales/pt-PT.ts",
"chars": 1322,
"preview": "/**\n * @file European Portuguese (pt-PT)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n"
},
{
"path": "src/locales/ro.ts",
"chars": 1252,
"preview": "/**\n * @file Romanian (ro)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['ianu"
},
{
"path": "src/locales/ru.ts",
"chars": 1558,
"preview": "/**\n * @file Russian (ru)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: [\n ["
},
{
"path": "src/locales/rw.ts",
"chars": 1308,
"preview": "/**\n * @file Kinyarwanda (rw)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['M"
},
{
"path": "src/locales/sr-Cyrl.ts",
"chars": 1237,
"preview": "/**\n * @file Serbian (sr-Cyrl)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['"
},
{
"path": "src/locales/sr-Latn.ts",
"chars": 1232,
"preview": "/**\n * @file Serbian (sr-Latn)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['"
},
{
"path": "src/locales/sv.ts",
"chars": 1227,
"preview": "/**\n * @file Swedish (sv)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['janua"
},
{
"path": "src/locales/ta.ts",
"chars": 1240,
"preview": "/**\n * @file Tamil (ta)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['ஜனவரி',"
},
{
"path": "src/locales/th.ts",
"chars": 1318,
"preview": "/**\n * @file Thai (th)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['มกราคม',"
},
{
"path": "src/locales/tr.ts",
"chars": 1208,
"preview": "/**\n * @file Turkish (tr)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['Ocak'"
},
{
"path": "src/locales/uk.ts",
"chars": 1455,
"preview": "/**\n * @file Ukrainian (uk)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: [\n "
},
{
"path": "src/locales/uz-Cyrl.ts",
"chars": 1211,
"preview": "/**\n * @file Uzbek (uz-Cyrl)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['ян"
},
{
"path": "src/locales/uz-Latn.ts",
"chars": 1238,
"preview": "/**\n * @file Uzbek (uz-Latn)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['ya"
},
{
"path": "src/locales/vi.ts",
"chars": 1268,
"preview": "/**\n * @file Vietnamese (vi)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['th"
},
{
"path": "src/locales/zh-Hans.ts",
"chars": 1109,
"preview": "/**\n * @file Chinese (zh-Hans)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['"
},
{
"path": "src/locales/zh-Hant.ts",
"chars": 1109,
"preview": "/**\n * @file Chinese (zh-Hant)\n */\n\nimport type { Locale, LocaleOptions } from '@/locale.ts';\n\nconst list = {\n MMMM: ['"
},
{
"path": "src/numeral.ts",
"chars": 99,
"preview": "export interface Numeral {\n encode: (str: string) => string;\n decode: (str: string) => string;\n}\n"
},
{
"path": "src/numerals/arab.ts",
"chars": 327,
"preview": "const numeral = '٠١٢٣٤٥٦٧٨٩';\nconst array = numeral.split('');\nconst map = Object.fromEntries(array.map((char, index) =>"
},
{
"path": "src/numerals/arabext.ts",
"chars": 327,
"preview": "const numeral = '۰۱۲۳۴۵۶۷۸۹';\nconst array = numeral.split('');\nconst map = Object.fromEntries(array.map((char, index) =>"
},
{
"path": "src/numerals/beng.ts",
"chars": 327,
"preview": "const numeral = '০১২৩৪৫৬৭৮৯';\nconst array = numeral.split('');\nconst map = Object.fromEntries(array.map((char, index) =>"
},
{
"path": "src/numerals/latn.ts",
"chars": 83,
"preview": "export default {\n encode: (str: string) => str,\n decode: (str: string) => str\n};\n"
},
{
"path": "src/numerals/mymr.ts",
"chars": 327,
"preview": "const numeral = '၀၁၂၃၄၅၆၇၈၉';\nconst array = numeral.split('');\nconst map = Object.fromEntries(array.map((char, index) =>"
},
{
"path": "src/parse.ts",
"chars": 2127,
"preview": "import { createTimezoneDate, TimeZone } from './zone.ts';\nimport { isUTC } from './datetime.ts';\nimport { preparse } fro"
},
{
"path": "src/parser.ts",
"chars": 8120,
"preview": "import type { CompiledObject } from './compile.ts';\nimport type { Locale } from './locale.ts';\nimport type { Numeral } f"
},
{
"path": "src/plugin.ts",
"chars": 467,
"preview": "export { FormatterPlugin } from './formatter.ts';\nexport { ParserPlugin, exec, find } from './parser.ts';\nexport type { "
},
{
"path": "src/plugins/day-of-week.ts",
"chars": 786,
"preview": "import { ParserPlugin, ParserPluginOptions, CompiledObject, find } from '@/plugin.ts';\n\nclass Parser extends ParserPlugi"
},
{
"path": "src/plugins/microsecond.ts",
"chars": 739,
"preview": "import { ParserPlugin, exec } from '@/plugin.ts';\n\nclass Parser extends ParserPlugin {\n SSSS (str: string) {\n const "
},
{
"path": "src/plugins/nanosecond.ts",
"chars": 757,
"preview": "import { ParserPlugin, exec } from '@/plugin.ts';\n\nclass Parser extends ParserPlugin {\n SSSSSSS (str: string) {\n con"
},
{
"path": "src/plugins/ordinal.ts",
"chars": 839,
"preview": "import { FormatterPlugin, ParserPlugin, ParserPluginOptions, exec } from '@/plugin.ts';\nimport type { DateLike } from '@"
},
{
"path": "src/plugins/quarter.ts",
"chars": 251,
"preview": "import { FormatterPlugin } from '@/plugin.ts';\nimport type { DateLike } from '@/plugin.ts';\n\nclass Formatter extends For"
},
{
"path": "src/plugins/timestamp.ts",
"chars": 312,
"preview": "import { FormatterPlugin } from '@/plugin.ts';\nimport type { DateLike } from '@/plugin.ts';\n\nclass Formatter extends For"
},
{
"path": "src/plugins/two-digit-year.ts",
"chars": 496,
"preview": "import { ParserPlugin, exec } from '@/plugin.ts';\nimport type { ParserPluginOptions } from '@/plugin.ts';\n\nclass Parser "
},
{
"path": "src/plugins/week.ts",
"chars": 807,
"preview": "import { FormatterPlugin } from '@/plugin.ts';\nimport { getISOWeekYear, getISOWeek } from '@/utils.ts';\nimport type { Da"
},
{
"path": "src/plugins/zonename.ts",
"chars": 1188,
"preview": "import timeZoneNames from '@/zonenames.ts';\nimport { FormatterPlugin } from '@/plugin.ts';\nimport { isTimeZone } from '@"
},
{
"path": "src/preparse.ts",
"chars": 2896,
"preview": "import { compile } from './compile.ts';\nimport { isTimeZone } from './zone.ts';\nimport { parser as defaultParser, valida"
},
{
"path": "src/subtract.ts",
"chars": 369,
"preview": "import { Duration } from './duration.ts';\n\n/**\n * Calculates the difference between two dates.\n * @param from - The firs"
},
{
"path": "src/timezone.ts",
"chars": 46988,
"preview": "import { TimeZone } from '@/zone.ts';\n\nexport const Abidjan: TimeZone = {\n zone_name: 'Africa/Abidjan',\n gmt_offset: ["
},
{
"path": "src/timezones/Africa/Abidjan.ts",
"chars": 75,
"preview": "export default {\n zone_name: 'Africa/Abidjan',\n gmt_offset: [0, -968]\n};\n"
},
{
"path": "src/timezones/Africa/Accra.ts",
"chars": 84,
"preview": "export default {\n zone_name: 'Africa/Accra',\n gmt_offset: [1800, 1200, 0, -52]\n};\n"
},
{
"path": "src/timezones/Africa/Addis_Ababa.ts",
"chars": 89,
"preview": "export default {\n zone_name: 'Africa/Addis_Ababa',\n gmt_offset: [10800, 9320, 9288]\n};\n"
},
{
"path": "src/timezones/Africa/Algiers.ts",
"chars": 91,
"preview": "export default {\n zone_name: 'Africa/Algiers',\n gmt_offset: [7200, 3600, 732, 561, 0]\n};\n"
},
{
"path": "src/timezones/Africa/Asmara.ts",
"chars": 84,
"preview": "export default {\n zone_name: 'Africa/Asmara',\n gmt_offset: [10800, 9332, 9320]\n};\n"
},
{
"path": "src/timezones/Africa/Bamako.ts",
"chars": 82,
"preview": "export default {\n zone_name: 'Africa/Bamako',\n gmt_offset: [0, -1920, -3600]\n};\n"
},
{
"path": "src/timezones/Africa/Bangui.ts",
"chars": 77,
"preview": "export default {\n zone_name: 'Africa/Bangui',\n gmt_offset: [4460, 3600]\n};\n"
},
{
"path": "src/timezones/Africa/Banjul.ts",
"chars": 82,
"preview": "export default {\n zone_name: 'Africa/Banjul',\n gmt_offset: [0, -3600, -3996]\n};\n"
},
{
"path": "src/timezones/Africa/Bissau.ts",
"chars": 82,
"preview": "export default {\n zone_name: 'Africa/Bissau',\n gmt_offset: [0, -3600, -3740]\n};\n"
},
{
"path": "src/timezones/Africa/Blantyre.ts",
"chars": 91,
"preview": "export default {\n zone_name: 'Africa/Blantyre',\n gmt_offset: [8470, 8460, 8400, 7200]\n};\n"
},
{
"path": "src/timezones/Africa/Brazzaville.ts",
"chars": 82,
"preview": "export default {\n zone_name: 'Africa/Brazzaville',\n gmt_offset: [3668, 3600]\n};\n"
},
{
"path": "src/timezones/Africa/Bujumbura.ts",
"chars": 80,
"preview": "export default {\n zone_name: 'Africa/Bujumbura',\n gmt_offset: [7200, 7048]\n};\n"
},
{
"path": "src/timezones/Africa/Cairo.ts",
"chars": 83,
"preview": "export default {\n zone_name: 'Africa/Cairo',\n gmt_offset: [10800, 7509, 7200]\n};\n"
},
{
"path": "src/timezones/Africa/Casablanca.ts",
"chars": 85,
"preview": "export default {\n zone_name: 'Africa/Casablanca',\n gmt_offset: [3600, 0, -1820]\n};\n"
},
{
"path": "src/timezones/Africa/Ceuta.ts",
"chars": 86,
"preview": "export default {\n zone_name: 'Africa/Ceuta',\n gmt_offset: [7200, 3600, 0, -1276]\n};\n"
},
{
"path": "src/timezones/Africa/Conakry.ts",
"chars": 83,
"preview": "export default {\n zone_name: 'Africa/Conakry',\n gmt_offset: [0, -3292, -3600]\n};\n"
},
{
"path": "src/timezones/Africa/Dakar.ts",
"chars": 81,
"preview": "export default {\n zone_name: 'Africa/Dakar',\n gmt_offset: [0, -3600, -4184]\n};\n"
},
{
"path": "src/timezones/Africa/Dar_es_Salaam.ts",
"chars": 91,
"preview": "export default {\n zone_name: 'Africa/Dar_es_Salaam',\n gmt_offset: [10800, 9900, 9428]\n};\n"
},
{
"path": "src/timezones/Africa/Djibouti.ts",
"chars": 81,
"preview": "export default {\n zone_name: 'Africa/Djibouti',\n gmt_offset: [10800, 10356]\n};\n"
},
{
"path": "src/timezones/Africa/Douala.ts",
"chars": 77,
"preview": "export default {\n zone_name: 'Africa/Douala',\n gmt_offset: [3600, 2328]\n};\n"
},
{
"path": "src/timezones/Africa/El_Aaiun.ts",
"chars": 90,
"preview": "export default {\n zone_name: 'Africa/El_Aaiun',\n gmt_offset: [3600, 0, -3168, -3600]\n};\n"
},
{
"path": "src/timezones/Africa/Freetown.ts",
"chars": 91,
"preview": "export default {\n zone_name: 'Africa/Freetown',\n gmt_offset: [0, -2400, -3180, -3600]\n};\n"
},
{
"path": "src/timezones/Africa/Gaborone.ts",
"chars": 92,
"preview": "export default {\n zone_name: 'Africa/Gaborone',\n gmt_offset: [10800, 7200, 6220, 5400]\n};\n"
},
{
"path": "src/timezones/Africa/Harare.ts",
"chars": 77,
"preview": "export default {\n zone_name: 'Africa/Harare',\n gmt_offset: [7452, 7200]\n};\n"
},
{
"path": "src/timezones/Africa/Johannesburg.ts",
"chars": 96,
"preview": "export default {\n zone_name: 'Africa/Johannesburg',\n gmt_offset: [10800, 7200, 6720, 5400]\n};\n"
},
{
"path": "src/timezones/Africa/Juba.ts",
"chars": 82,
"preview": "export default {\n zone_name: 'Africa/Juba',\n gmt_offset: [10800, 7588, 7200]\n};\n"
},
{
"path": "src/timezones/Africa/Kampala.ts",
"chars": 91,
"preview": "export default {\n zone_name: 'Africa/Kampala',\n gmt_offset: [10800, 9900, 9000, 7780]\n};\n"
},
{
"path": "src/timezones/Africa/Khartoum.ts",
"chars": 86,
"preview": "export default {\n zone_name: 'Africa/Khartoum',\n gmt_offset: [10800, 7808, 7200]\n};\n"
},
{
"path": "src/timezones/Africa/Kigali.ts",
"chars": 77,
"preview": "export default {\n zone_name: 'Africa/Kigali',\n gmt_offset: [7216, 7200]\n};\n"
},
{
"path": "src/timezones/Africa/Kinshasa.ts",
"chars": 79,
"preview": "export default {\n zone_name: 'Africa/Kinshasa',\n gmt_offset: [3672, 3600]\n};\n"
},
{
"path": "src/timezones/Africa/Lagos.ts",
"chars": 84,
"preview": "export default {\n zone_name: 'Africa/Lagos',\n gmt_offset: [3600, 1800, 815, 0]\n};\n"
},
{
"path": "src/timezones/Africa/Libreville.ts",
"chars": 81,
"preview": "export default {\n zone_name: 'Africa/Libreville',\n gmt_offset: [3600, 2268]\n};\n"
},
{
"path": "src/timezones/Africa/Lome.ts",
"chars": 71,
"preview": "export default {\n zone_name: 'Africa/Lome',\n gmt_offset: [292, 0]\n};\n"
},
{
"path": "src/timezones/Africa/Luanda.ts",
"chars": 83,
"preview": "export default {\n zone_name: 'Africa/Luanda',\n gmt_offset: [3600, 3176, 3124]\n};\n"
},
{
"path": "src/timezones/Africa/Lubumbashi.ts",
"chars": 87,
"preview": "export default {\n zone_name: 'Africa/Lubumbashi',\n gmt_offset: [7200, 6592, 3600]\n};\n"
},
{
"path": "src/timezones/Africa/Lusaka.ts",
"chars": 77,
"preview": "export default {\n zone_name: 'Africa/Lusaka',\n gmt_offset: [7200, 6788]\n};\n"
},
{
"path": "src/timezones/Africa/Malabo.ts",
"chars": 80,
"preview": "export default {\n zone_name: 'Africa/Malabo',\n gmt_offset: [3600, 2108, 0]\n};\n"
},
{
"path": "src/timezones/Africa/Maputo.ts",
"chars": 77,
"preview": "export default {\n zone_name: 'Africa/Maputo',\n gmt_offset: [7818, 7200]\n};\n"
},
{
"path": "src/timezones/Africa/Maseru.ts",
"chars": 84,
"preview": "export default {\n zone_name: 'Africa/Maseru',\n gmt_offset: [10800, 7200, 6600]\n};\n"
},
{
"path": "src/timezones/Africa/Mbabane.ts",
"chars": 78,
"preview": "export default {\n zone_name: 'Africa/Mbabane',\n gmt_offset: [7464, 7200]\n};\n"
},
{
"path": "src/timezones/Africa/Mogadishu.ts",
"chars": 88,
"preview": "export default {\n zone_name: 'Africa/Mogadishu',\n gmt_offset: [10888, 10800, 9000]\n};\n"
},
{
"path": "src/timezones/Africa/Monrovia.ts",
"chars": 84,
"preview": "export default {\n zone_name: 'Africa/Monrovia',\n gmt_offset: [0, -2588, -2670]\n};\n"
},
{
"path": "src/timezones/Africa/Nairobi.ts",
"chars": 91,
"preview": "export default {\n zone_name: 'Africa/Nairobi',\n gmt_offset: [10800, 9900, 9000, 8836]\n};\n"
},
{
"path": "src/timezones/Africa/Ndjamena.ts",
"chars": 85,
"preview": "export default {\n zone_name: 'Africa/Ndjamena',\n gmt_offset: [7200, 3612, 3600]\n};\n"
},
{
"path": "src/timezones/Africa/Niamey.ts",
"chars": 86,
"preview": "export default {\n zone_name: 'Africa/Niamey',\n gmt_offset: [3600, 508, 0, -3600]\n};\n"
},
{
"path": "src/timezones/Africa/Nouakchott.ts",
"chars": 86,
"preview": "export default {\n zone_name: 'Africa/Nouakchott',\n gmt_offset: [0, -3600, -3828]\n};\n"
},
{
"path": "src/timezones/Africa/Ouagadougou.ts",
"chars": 79,
"preview": "export default {\n zone_name: 'Africa/Ouagadougou',\n gmt_offset: [0, -364]\n};\n"
},
{
"path": "src/timezones/Africa/Porto-Novo.ts",
"chars": 83,
"preview": "export default {\n zone_name: 'Africa/Porto-Novo',\n gmt_offset: [3600, 628, 0]\n};\n"
},
{
"path": "src/timezones/Africa/Sao_Tome.ts",
"chars": 89,
"preview": "export default {\n zone_name: 'Africa/Sao_Tome',\n gmt_offset: [3600, 1616, 0, -2205]\n};\n"
},
{
"path": "src/timezones/Africa/Tripoli.ts",
"chars": 84,
"preview": "export default {\n zone_name: 'Africa/Tripoli',\n gmt_offset: [7200, 3600, 3164]\n};\n"
},
{
"path": "src/timezones/Africa/Tunis.ts",
"chars": 87,
"preview": "export default {\n zone_name: 'Africa/Tunis',\n gmt_offset: [7200, 3600, 2444, 561]\n};\n"
},
{
"path": "src/timezones/Africa/Windhoek.ts",
"chars": 98,
"preview": "export default {\n zone_name: 'Africa/Windhoek',\n gmt_offset: [10800, 7200, 5400, 4104, 3600]\n};\n"
},
{
"path": "src/timezones/America/Adak.ts",
"chars": 103,
"preview": "export default {\n zone_name: 'America/Adak',\n gmt_offset: [44002, -32400, -36000, -39600, -42398]\n};\n"
},
{
"path": "src/timezones/America/Anchorage.ts",
"chars": 108,
"preview": "export default {\n zone_name: 'America/Anchorage',\n gmt_offset: [50424, -28800, -32400, -35976, -36000]\n};\n"
},
{
"path": "src/timezones/America/Anguilla.ts",
"chars": 84,
"preview": "export default {\n zone_name: 'America/Anguilla',\n gmt_offset: [-14400, -15136]\n};\n"
},
{
"path": "src/timezones/America/Antigua.ts",
"chars": 91,
"preview": "export default {\n zone_name: 'America/Antigua',\n gmt_offset: [-14400, -14832, -18000]\n};\n"
},
{
"path": "src/timezones/America/Araguaina.ts",
"chars": 92,
"preview": "export default {\n zone_name: 'America/Araguaina',\n gmt_offset: [-7200, -10800, -11568]\n};\n"
},
{
"path": "src/timezones/America/Argentina/Buenos_Aires.ts",
"chars": 121,
"preview": "export default {\n zone_name: 'America/Argentina/Buenos_Aires',\n gmt_offset: [-7200, -10800, -14028, -14400, -15408]\n};"
},
{
"path": "src/timezones/America/Argentina/Catamarca.ts",
"chars": 118,
"preview": "export default {\n zone_name: 'America/Argentina/Catamarca',\n gmt_offset: [-7200, -10800, -14400, -15408, -15788]\n};\n"
},
{
"path": "src/timezones/America/Argentina/Cordoba.ts",
"chars": 108,
"preview": "export default {\n zone_name: 'America/Argentina/Cordoba',\n gmt_offset: [-7200, -10800, -14400, -15408]\n};\n"
},
{
"path": "src/timezones/America/Argentina/Jujuy.ts",
"chars": 114,
"preview": "export default {\n zone_name: 'America/Argentina/Jujuy',\n gmt_offset: [-7200, -10800, -14400, -15408, -15672]\n};\n"
},
{
"path": "src/timezones/America/Argentina/La_Rioja.ts",
"chars": 117,
"preview": "export default {\n zone_name: 'America/Argentina/La_Rioja',\n gmt_offset: [-7200, -10800, -14400, -15408, -16044]\n};\n"
},
{
"path": "src/timezones/America/Argentina/Mendoza.ts",
"chars": 116,
"preview": "export default {\n zone_name: 'America/Argentina/Mendoza',\n gmt_offset: [-7200, -10800, -14400, -15408, -16516]\n};\n"
},
{
"path": "src/timezones/America/Argentina/Rio_Gallegos.ts",
"chars": 121,
"preview": "export default {\n zone_name: 'America/Argentina/Rio_Gallegos',\n gmt_offset: [-7200, -10800, -14400, -15408, -16612]\n};"
},
{
"path": "src/timezones/America/Argentina/Salta.ts",
"chars": 114,
"preview": "export default {\n zone_name: 'America/Argentina/Salta',\n gmt_offset: [-7200, -10800, -14400, -15408, -15700]\n};\n"
},
{
"path": "src/timezones/America/Argentina/San_Juan.ts",
"chars": 117,
"preview": "export default {\n zone_name: 'America/Argentina/San_Juan',\n gmt_offset: [-7200, -10800, -14400, -15408, -16444]\n};\n"
},
{
"path": "src/timezones/America/Argentina/San_Luis.ts",
"chars": 117,
"preview": "export default {\n zone_name: 'America/Argentina/San_Luis',\n gmt_offset: [-7200, -10800, -14400, -15408, -15924]\n};\n"
},
{
"path": "src/timezones/America/Argentina/Tucuman.ts",
"chars": 116,
"preview": "export default {\n zone_name: 'America/Argentina/Tucuman',\n gmt_offset: [-7200, -10800, -14400, -15408, -15652]\n};\n"
},
{
"path": "src/timezones/America/Argentina/Ushuaia.ts",
"chars": 116,
"preview": "export default {\n zone_name: 'America/Argentina/Ushuaia',\n gmt_offset: [-7200, -10800, -14400, -15408, -16392]\n};\n"
},
{
"path": "src/timezones/America/Aruba.ts",
"chars": 89,
"preview": "export default {\n zone_name: 'America/Aruba',\n gmt_offset: [-14400, -16200, -16824]\n};\n"
},
{
"path": "src/timezones/America/Asuncion.ts",
"chars": 92,
"preview": "export default {\n zone_name: 'America/Asuncion',\n gmt_offset: [-10800, -13840, -14400]\n};\n"
},
{
"path": "src/timezones/America/Atikokan.ts",
"chars": 92,
"preview": "export default {\n zone_name: 'America/Atikokan',\n gmt_offset: [-18000, -21600, -21988]\n};\n"
},
{
"path": "src/timezones/America/Bahia.ts",
"chars": 87,
"preview": "export default {\n zone_name: 'America/Bahia',\n gmt_offset: [-7200, -9244, -10800]\n};\n"
},
{
"path": "src/timezones/America/Bahia_Banderas.ts",
"chars": 106,
"preview": "export default {\n zone_name: 'America/Bahia_Banderas',\n gmt_offset: [-18000, -21600, -25200, -25260]\n};\n"
},
{
"path": "src/timezones/America/Barbados.ts",
"chars": 100,
"preview": "export default {\n zone_name: 'America/Barbados',\n gmt_offset: [-10800, -12600, -14309, -14400]\n};\n"
},
{
"path": "src/timezones/America/Belem.ts",
"chars": 88,
"preview": "export default {\n zone_name: 'America/Belem',\n gmt_offset: [-7200, -10800, -11636]\n};\n"
},
{
"path": "src/timezones/America/Belize.ts",
"chars": 98,
"preview": "export default {\n zone_name: 'America/Belize',\n gmt_offset: [-18000, -19800, -21168, -21600]\n};\n"
},
{
"path": "src/timezones/America/Blanc-Sablon.ts",
"chars": 96,
"preview": "export default {\n zone_name: 'America/Blanc-Sablon',\n gmt_offset: [-10800, -13708, -14400]\n};\n"
},
{
"path": "src/timezones/America/Boa_Vista.ts",
"chars": 93,
"preview": "export default {\n zone_name: 'America/Boa_Vista',\n gmt_offset: [-10800, -14400, -14560]\n};\n"
},
{
"path": "src/timezones/America/Bogota.ts",
"chars": 90,
"preview": "export default {\n zone_name: 'America/Bogota',\n gmt_offset: [-14400, -17776, -18000]\n};\n"
}
]
// ... and 418 more files (download for full content)
About this extraction
This page contains the full source code of the knowledgecode/date-and-time GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 618 files (833.5 KB), approximately 301.1k tokens, and a symbol index with 325 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.