chronia

Chronia Documentation

Welcome to the Chronia documentation! This comprehensive guide covers everything you need to know about using and contributing to Chronia, a modern TypeScript date/time utility library.

What is Chronia?

Chronia is a modern, lightweight TypeScript date/time utility library with comprehensive formatting, parsing, and manipulation capabilities. It provides:

🚀 TypeScript-first – Strict typings with TypeScript 5.9+
📦 Lightweight – ESM/CJS dual modules, fully tree-shakable
🌍 Internationalization – Built-in locale support
📅 Comprehensive Utilities – 76 functions organized into 11 categories for date operations
🎯 Consistent API – Unified support for Date objects, timestamps, and ISO 8601 strings
✅ Safe Error Handling – No exceptions; graceful degradation
⚡ Well-tested – 3500+ automated test cases

For Users

Installation

Chronia requires Node.js v18 to v24.

# Using pnpm (recommended)
pnpm add chronia

# Using npm
npm install chronia

# Using yarn
yarn add chronia

Quick Start

Basic Usage

import { format, addDays, isBefore } from "chronia";

// Format dates
const today = new Date();
format(today, "yyyy-MM-dd"); // '2025-01-23'

// Date arithmetic
const nextWeek = addDays(today, 7);

// Date comparison
isBefore(today, nextWeek); // true

Working with Timestamps and Strings

Chronia functions accept Date objects, numeric timestamps, and ISO 8601 strings:

import { isValid, getYear, addDays } from "chronia";

// Date object
isValid(new Date(2025, 0, 1)); // true

// Timestamp
isValid(1704067200000); // true
getYear(1704067200000); // 2025

// ISO 8601 string
isValid("2025-01-01"); // true
addDays("2025-01-01", 7); // January 8, 2025
getYear("2025-01-15T14:30:00Z"); // 2025

Error Handling

Chronia never throws exceptions. Invalid inputs return predictable values:

import { isValid, getYear, addDays } from "chronia";

// Validation functions return false
isValid(new Date("invalid")); // false
isValid(NaN); // false

// Accessor functions return NaN
getYear(NaN); // NaN

// Transformation functions return Invalid Date
const result = addDays(NaN, 5);
isValid(result); // false

Core Concepts

Type Flexibility

All Chronia functions accept DateInput (Date | number | string) for date parameters:

type DateInput = Date | number | string;

function isValid(date: DateInput): boolean;
function format(date: DateInput, pattern: string): string;
function addDays(date: DateInput, amount: number): Date;

This provides flexibility while maintaining type safety. ISO 8601 strings are automatically parsed:

// All these are equivalent
addDays(new Date(2025, 0, 1), 7);
addDays(1735689600000, 7);
addDays("2025-01-01", 7);
addDays("2025-01-01T00:00:00Z", 7);

Immutability

Transformation functions always return new Date objects:

const original = new Date(2025, 0, 1);
const modified = addDays(original, 5);

original.getTime() !== modified.getTime(); // true - original unchanged

Options Pattern

Functions with configurable behavior use an options parameter:

import { isBefore } from "chronia";

const morning = new Date(2025, 0, 1, 9, 0);
const evening = new Date(2025, 0, 1, 17, 0);

// Default: millisecond precision
isBefore(morning, evening); // true

// Custom: day precision
isBefore(morning, evening, { unit: "day" }); // false (same day)

Function Categories

Chronia organizes its 76 functions into 11 logical categories:

Validations

Validate dates and compare date values

isValid, isBefore, isAfter, isEqual, isSameDay, etc.
Use for: Input validation, date comparisons, chronological ordering

Accessors

Extract components from dates

getYear, getMonth, getDay, getHours, etc.
Use for: Reading date components, extracting values

Arithmetic

Add, subtract, and calculate date differences

addYears, addMonths, addDays, subHours, diffDays, etc.
Use for: Date calculations, scheduling, time intervals

Boundaries

Get start/end of time periods

startOfDay, endOfMonth, startOfYear, etc.
Use for: Date ranges, period boundaries, calendar operations

Comparisons

Compare and sort dates

max, min, compare, clamp
Use for: Finding earliest/latest dates, sorting, range validation

Formatting

Convert dates to strings

format with customizable patterns
createFormatter for pre-compiled efficient formatting
Use for: Display formatting, localization, string conversion

Parsing

Convert strings to dates

parse with pattern matching
createParser for pre-compiled efficient parsing
Use for: User input parsing, string-to-date conversion

Mutators

Set date components (immutably)

setYear, setMonth, setDay, setHours, etc.
Use for: Creating dates with specific components

Truncations

Truncate dates to specific units

truncToYear, truncToMonth, truncToDay, etc.
Use for: Date normalization, grouping by period

Utilities

Utility functions

now - Get current timestamp
Use for: Current time, testing, timestamps

Comparisons (Advanced)

Utility functions for date comparison

max, min, compare, clamp
Use for: Array operations, sorting, range operations

Browse Functions by Category

Basic Operations

Date Manipulation

Advanced Features

Common Use Cases

Input Validation

import { isValid } from "chronia";

function processDate(input: string): Date | null {
  const date = new Date(input);
  return isValid(date) ? date : null;
}

Date Formatting

import { format } from "chronia";

const date = new Date(2025, 0, 23);
format(date, "yyyy-MM-dd"); // '2025-01-23'
format(date, "MMMM d, yyyy"); // 'January 23, 2025'
format(date, "MMM d, yyyy HH:mm"); // 'Jan 23, 2025 00:00'

Date Arithmetic

import { addDays, addMonths, diffDays } from "chronia";

const today = new Date(2025, 0, 23);
const nextWeek = addDays(today, 7);
const nextMonth = addMonths(today, 1);

diffDays(today, nextWeek); // 7

Date Comparison

import { isBefore, isAfter, isSameDay } from "chronia";

const date1 = new Date(2025, 0, 1);
const date2 = new Date(2025, 0, 15);

isBefore(date1, date2); // true
isAfter(date1, date2); // false
isSameDay(date1, date2); // false

Date Ranges

import { startOfMonth, endOfMonth } from "chronia";

const date = new Date(2025, 0, 15);
const monthStart = startOfMonth(date); // 2025-01-01 00:00:00
const monthEnd = endOfMonth(date); // 2025-01-31 23:59:59

Sorting Dates

import { compare, max, min } from "chronia";

const dates = [
  new Date(2025, 0, 15),
  new Date(2025, 0, 1),
  new Date(2025, 0, 30),
];

dates.sort(compare); // Sort chronologically
const latest = max(dates); // 2025-01-30
const earliest = min(dates); // 2025-01-01

Internationalization

Chronia supports localization for formatting and parsing with 39 built-in locales:

import { format } from "chronia";
import { enUS } from "chronia/locale/en-US";
import { ja } from "chronia/locale/ja";
import { fr } from "chronia/locale/fr";

const date = new Date(2025, 0, 23);

// English (default)
format(date, "MMMM d, yyyy", enUS); // 'January 23, 2025'

// Japanese
format(date, "yyyy'年'M'月'd'日'", ja); // '2025年1月23日'

// French
format(date, "EEEE d MMMM yyyy", fr); // 'jeudi 23 janvier 2025'

Supported Locales (39)

Core:

en-US - English (United States)
ja - Japanese

World Languages:

zh-CN - Chinese (Simplified)
ko - Korean
es - Spanish
fr - French
de - German
pt-BR - Portuguese (Brazil)
ru - Russian
ar - Arabic

European Languages:

it - Italian
nl - Dutch
pl - Polish
pt - Portuguese (Portugal)
sv - Swedish
tr - Turkish

Asian Languages:

zh-TW - Chinese (Traditional, Taiwan)
zh-HK - Chinese (Traditional, Hong Kong)
vi - Vietnamese
id - Indonesian
ms - Malay
th - Thai
hi - Hindi

English Variants:

en-GB - English (United Kingdom)
en-AU - English (Australia)
en-CA - English (Canada)

Major European Languages:

da - Danish
fi - Finnish
nb - Norwegian (Bokmål)
cs - Czech
el - Greek
he - Hebrew
hu - Hungarian
ro - Romanian
uk - Ukrainian
sk - Slovak
bg - Bulgarian
hr - Croatian
sr - Serbian

Performance Tips

Use Timestamps for Performance-Critical Code

Timestamps are fastest, followed by Date objects, then strings:

// Fastest - direct timestamp
isValid(1704067200000);

// Fast - Date object
isValid(new Date(2025, 0, 1));

// Slower - requires string parsing
isValid("2025-01-01");

Choose Appropriate Comparison Units

Millisecond comparisons are fastest:

// Fastest - millisecond comparison
isBefore(date1, date2);

// Slower - requires truncation
isBefore(date1, date2, { unit: "day" });

Avoid Repeated Date Conversions

Cache converted values when possible:

// Less efficient
for (const event of events) {
  if (isBefore(event.date, new Date())) {
    // Process past event
  }
}

// More efficient
const now = new Date();
for (const event of events) {
  if (isBefore(event.date, now)) {
    // Process past event
  }
}

Type Definitions

Core Types

// Flexible date input type - accepts Date objects, timestamps, or ISO 8601 strings
type DateInput = Date | number | string;

type TimeUnit =
  | "year"
  | "month"
  | "day"
  | "hour"
  | "minute"
  | "second"
  | "millisecond";

// Locale is a data structure containing localized strings
interface Locale {
  era: { narrow: string[]; abbr: string[]; wide: string[] };
  month: { narrow: string[]; abbr: string[]; wide: string[] };
  weekday: { narrow: string[]; abbr: string[]; wide: string[] };
  dayPeriod: { narrow: string[]; abbr: string[]; wide: string[] };
}

interface ComparisonOptions {
  unit?: TimeUnit;
}

Supported ISO 8601 Formats

Chronia supports standard ISO 8601 date/time formats:

Format	Example
Date only	`2025-01-15`
Date and time	`2025-01-15T14:30:00`
With milliseconds	`2025-01-15T14:30:00.000`
UTC (Z suffix)	`2025-01-15T14:30:00Z`
With timezone offset	`2025-01-15T14:30:00+09:00`
Year and month only	`2025-01`

Function Signatures

All date functions follow consistent patterns:

// Validation functions return boolean
function isValid(date: DateInput): boolean;

// Accessor functions return number (or NaN for invalid input)
function getYear(date: DateInput): number;

// Transformation functions return Date
function addDays(date: DateInput, amount: number): Date;

// Comparison functions return boolean
function isBefore(
  a: DateInput,
  b: DateInput,
  options?: ComparisonOptions,
): boolean;

Error Handling

Error Handling Philosophy

Chronia follows a no-exceptions philosophy:

Validation functions return false for invalid input
Accessor functions return NaN for invalid input
Transformation functions return Invalid Date for invalid input

Handling Invalid Inputs

import { isValid, getYear, addDays } from "chronia";

// Always validate before processing
const date = new Date(userInput);
if (!isValid(date)) {
  console.error("Invalid date provided");
  return;
}

// Safe to use
const year = getYear(date);
const nextWeek = addDays(date, 7);

Migration Guide

From date-fns

// date-fns
import { format, addDays, isBefore } from "date-fns";

// Chronia (same API)
import { format, addDays, isBefore } from "chronia";

From moment.js

// moment.js
moment(date).format("YYYY-MM-DD");
moment(date).add(7, "days");

// Chronia
format(date, "yyyy-MM-dd");
addDays(date, 7);

From Day.js

// Day.js
dayjs(date).format("YYYY-MM-DD");
dayjs(date).add(7, "day");

// Chronia
format(date, "yyyy-MM-dd");
addDays(date, 7);

License

Chronia is MIT licensed.

Acknowledgments

Chronia is inspired by excellent date libraries like date-fns, moment.js, and Day.js. We thank the JavaScript community for their continued innovation in date/time handling.

Happy coding with Chronia! 📅

This site is open source. Improve this page.

Chronia Documentation

What is Chronia?

Documentation Navigation

For Users

Getting Started

Function Reference

Advanced Topics

API Reference

Installation

Quick Start

Basic Usage

Working with Timestamps and Strings

Error Handling

Core Concepts

Type Flexibility

Immutability

Options Pattern

Function Categories

Browse Functions by Category

Basic Operations

Date Manipulation

Advanced Features

Common Use Cases

Input Validation

Date Formatting

Date Arithmetic

Date Comparison

Date Ranges

Sorting Dates

Internationalization

Supported Locales (39)

Performance Tips

Use Timestamps for Performance-Critical Code

Choose Appropriate Comparison Units

Avoid Repeated Date Conversions

Type Definitions

Core Types

Supported ISO 8601 Formats

Function Signatures

Error Handling

Error Handling Philosophy

Handling Invalid Inputs

Migration Guide

From date-fns

From moment.js

From Day.js

License

Acknowledgments