WaktooJS

UTC-First • Lightweight • Chainable Date-Time Library

A fast, modern, dependency-free datetime engine for JavaScript —
with strict UTC parsing, timezone support, locale formatting, durations,
relative time, calendar outputs, and flexible tokens, date range, and age calculation.

“Time made simple. Lightweight. Predictable. Powerful.”

See Release notes

Why WaktooJS?

Ideal for applications needing reliable, predictable, and readable date manipulation without heavy dependencies.

Modern JavaScript apps need predictable and readable date operations — not massive libraries. Waktoo focuses on the essentials:

Fast, Lightweight, Zero Dependencies

No overhead. No polyfills. No bloated parsing engine.

UTC-First (Predictable Everywhere)

Your code runs the same on every machine — CI, server, client, container.
No surprise timezone shifts.

Timezone support

Full timezone formatting + abbreviations & offsets.

Modern, Clean, Chainable API

waktoo().tz("Asia/Tokyo").add(1, "day").format("DD MMM YYYY");

Table of Contents

• Introduction
• Why Waktoo
• Installation
• Importing
• Quick Usage
• UTC Default Behavior
• Timezone-Aware Getters
• Date Arithmetic
• Diff
• Range
• Age
• Duration
• Duration.format()
• Relative Time
• Calendar Output
• Token-Based Date Parsing
• Timezone Formatting
• Supported Format Tokens
• Supported Timezone Abbreviations
• API Reference Index
• License

Installation

npm install waktoo

Importing

CommonJS

const waktoo = require("waktoo");

ESM

import waktoo from "waktoo";

Quick Usage

waktoo().format();
// → "2025-12-01T00:00:00.000Z"

waktoo().format("DD MMM YYYY");
// → "16 Nov 2025"

waktoo("2025-12-01").tz("Asia/Jakarta").format("DD MMM YYYY HH:mm Z");
// → "02 Des 2025 07:00 +07:00"

waktoo().locale("id-ID").format("DD MMMM YYYY");
// → "16 November 2025"

waktoo("2025-12-31").fromNow();
// → "in 1 month"

UTC Default Behavior

Waktoo stores everything in strict UTC.

This means:

• waktoo().hour() → UTC hour
• waktoo().date() → UTC date
• waktoo().day() → UTC weekday

This guarantees reproducibility across all machines.

Timezone-Aware Getters

waktoo("2025-12-01T00:00:00Z").tz("Asia/Jakarta").hour();
// → 7

waktoo("2025-12-01T00:00:00Z").tz("America/New_York").date();
// → 30 (previous day)

Any of these reflect the chosen timezone:

• year()
• month()
• date()
• day()
• hour()
• minute()
• second()

Date Arithmetic

waktoo("2025-01-01").add(3, "days");
waktoo("2025-01-01").add({ months: 2, hours: 5 });

waktoo("2025-01-10").subtract(1, "month");

Diff

const a = waktoo("2025-12-25");
const b = waktoo("2025-12-10");

a.diff(b, "days"); // 15
a.diff(b, "days", true); // 15.0 (float)

Range

Human-readable, localized difference between two dates.

Detailed breakdown

waktoo("2023-01-01").range("2025-03-05");
// → "2 years 2 months 4 days"

Single-unit output

waktoo("2023-01-01").range("2025-01-01", "day");
// → "731 days"

waktoo("2023-01-01").range("2023-01-03", "minute");
// → "2880 minutes"

Localized

waktoo("2023-01-01").locale("id-ID").range("2025-01-01");
// → "2 tahun"

Age

Age is always:

• absolute
• localized
• humanized by default
• still convertible numerically with .asDays() etc

Basic age

waktoo("2023-01-01").age();
// → "2 years"

Month-based

waktoo("2024-12-01").age();
// → "1 month"

Localized

waktoo("2023-01-01").locale("id-ID").age();
// → "2 tahun"

Conversions

waktoo("2023-01-01").age().asDays();
// → 731

waktoo("2023-01-01").age().asMonths();
// → 24

Duration

waktoo.duration(3, "hours").asMinutes();
// → 180

waktoo.duration({ hours: 2, minutes: 30 }).humanize();
// → "in 2 hours"

Durations support:

• numeric conversions (.asDays(), .asHours(), etc.)
• human-readable output (.humanize())
• suffixless output (.humanize(false))
• localization (.locale("id-ID"))
• deterministic normalized formatting (.format())

Duration.format()

.format() always returns a fully normalized breakdown, using localized unit names.

Object-based durations:

waktoo
	.duration({
		years: 2,
		months: 3,
		days: 5,
		hours: 4,
		minutes: 30,
		seconds: 10,
	})
	.format();

// → "2 years 3 months 5 days 4 hours 30 minutes 10 seconds"

Numeric or mixed durations normalize automatically:

waktoo.duration({ minutes: 90 }).format();
// → "1 hour 30 minutes"

Localized:

waktoo.duration({ minutes: 90 }).locale("id-ID").format();
// → "1 jam 30 menit"

Relative Time

waktoo("2025-12-31").fromNow();
// → "in 1 month"

waktoo("2025-12-01").from("2025-11-25");
// → "in 6 days"

Localized:

waktoo().add(1, "hour").locale("id-ID").fromNow();
// → "dalam 1 jam"

waktoo().subtract(2, "hours").locale("id-ID").fromNow();
// → "2 jam yang lalu"

Calendar Output

waktoo("2025-12-31").calendar();
// → "Today at 15:00"
// → "Tomorrow at 11:00"
// → "Yesterday at 22:00"
// → "Sunday at 09:00"
// → "31/12/2025"

Localized:

waktoo("2025-12-31").locale("id-ID").calendar();
// → "Hari ini pukul 15:00"

Token-Based Date Parsing

Supports patterns similar to Moment:

Example:

waktoo("25/12/2025", "DD/MM/YYYY").format("YYYY-MM-DD");
// → "2025-12-25"

waktoo().format("D MMM YYYY HH:mm");
// → "1 January 2025 12:30"

Localized:

waktoo().locale("id-ID").format("D MMM YYYY HH:mm");
// → "1 Januari 2025 12:30"

Strict mode rejects wrong formats:

waktoo("999/99/9999", "DD/MM/YYYY");
// Throws invalid date error

Timezone Formatting

Waktoo supports:

• Z → "+07:00"
• ZZ → "+0700"
• z → "WIB"
• zzz → "WIB" (long/variant)

waktoo().tz("Asia/Jakarta").format("DD MMM YYYY HH:mm:ss Z z");
// → "16 Nov 2025 23:00:00 +07:00 WIB"

Supported Format Tokens

| Token | Description | | ----- | -------------------- | | YYYY | 4-digit year | | YY | 2-digit year | | MMMM | Month long | | MMM | Month short | | MM | 01–12 | | M | 1–12 | | DD | 01–31 | | D | 1–31 | | dddd | Weekday long | | ddd | Weekday short | | HH | 00–23 | | H | 0–23 | | hh | 01–12 | | h | 1–12 | | mm | 00–59 | | m | 0–59 | | ss | 00–59 | | s | 0–59 | | A | AM/PM | | a | am/pm | | Z | +07:00 | | ZZ | +0700 | | z | timezone abbr | | zzz | long/display TZ abbr |

Supported Timezone Abbreviations

Waktoo includes an expanded global TZ abbreviation map:

| Timezone | Abbrev | | ------------------- | --------- | | Asia/Jakarta | WIB | | Asia/Makassar | WITA | | Asia/Jayapura | WIT | | America/New_York | EST/EDT | | America/Chicago | CST/CDT | | America/Denver | MST/MDT | | America/Los_Angeles | PST/PDT | | America/Phoenix | MST | | America/Toronto | EST | | America/Vancouver | PST | | America/Sao_Paulo | BRT | | Europe/London | GMT/BST | | Europe/Dublin | GMT/IST | | Europe/Paris | CET/CEST | | Europe/Berlin | CET/CEST | | Europe/Madrid | CET/CEST | | Europe/Rome | CET/CEST | | Europe/Moscow | MSK | | Africa/Johannesburg | SAST | | Africa/Cairo | EET | | Africa/Nairobi | EAT | | Asia/Tokyo | JST | | Asia/Seoul | KST | | Asia/Shanghai | CST | | Asia/Hong_Kong | HKT | | Asia/Singapore | SGT | | Asia/Kuala_Lumpur | MYT | | Asia/Bangkok | ICT | | Australia/Sydney | AEST/AEDT | | Australia/Perth | AWST | | Pacific/Auckland | NZST/NZDT |

Fallback behavior:

If a timezone is missing an abbreviation, waktoo uses the last segment of the TZ name (e.g., "Asia/Colombo" → "Colombo").

API Reference Index

Core

• waktoo(input?)
• waktoo().format(pattern)
• waktoo().locale(localeCode)
• waktoo().tz(timezone)

Getters

• year()
• month()
• date()
• day()
• hour()
• minute()
• second()

Math

• add(value, unit)
• add({ parts })
• subtract(value, unit)
• subtract({ parts })
• diff(otherDate, unit?, float?)

Range

• range(date2)
• range(date2, unit)

Age

• age()
• .asSeconds()
• .asMinutes()
• .asHours()
• .asDays()
• .asWeeks()
• .asMonths()
• .asYears()

Relative

• fromNow()
• from(otherWaktooInstance)

Calendar

• calendar()

Duration API

• waktoo.duration(number, unit)
• waktoo.duration({ parts })
• .locale(localeCode)
• .asMilliseconds()
• .asSeconds()
• .asMinutes()
• .asHours()
• .asDays()
• .asWeeks()
• .asMonths()
• .asYears()
• .humanize(withSuffix = true)
• .format()

License

MIT