Skip to main content

Introduction to Holy Time

Holy Time is a type-safe date and time manipulation library that provides an intuitive, chainable API for working with dates, times, and durations in JavaScript and TypeScript.

Why Holy Time?

Holy Time offers a modern approach to date manipulation with several key advantages:

Type-Safe

Built with TypeScript from the ground up, providing full type safety and excellent autocomplete support

Chainable API

Fluent interface allows you to chain operations for clean, readable code

Lightweight

Zero dependencies and small bundle size

Intuitive

Simple, consistent API that feels natural to use

Key Features

Time Manipulation

Holy Time provides both static and instance methods for adding, subtracting, and manipulating dates:
import HolyTime from 'holy-time'

// Add and subtract time units
HolyTime
  .in(4, 'days')
  .add(2, 'weeks')
  .subtract(4, 'minutes')

// Work with specific time boundaries
const startOfDay = HolyTime.startOf('day')
const endOfMonth = HolyTime.endOf('month')

Comparisons & Queries

Check relationships between dates and query properties:
// Check if a date is in the future, past, weekend
const isFuture = HolyTime.isFuture(someDate)
const isPast = new HolyTime('2022-10-20').isPast()
const isWeekend = HolyTime.isWeekend(new Date())

// Compare dates
const isAfter = HolyTime.isAfter(dateA, dateB)
const isBefore = new HolyTime(dateA).isBefore(dateB)

Duration Calculations

Calculate and format time differences:
// Calculate duration between two dates
const duration = HolyTime.between(
  HolyTime.startOf('day'),
  HolyTime.now()
).in('hours')

// Create and manipulate durations
HolyTime
  .duration(2, 'hours')
  .add(30, 'minutes')
  .in('seconds') // 9000

Formatting

Format dates with custom patterns and timezone support:
// Format with patterns
HolyTime.format(new Date(), 'YYYY-MM-DD HH:mm:ss')

// Format with timezone
const formatted = HolyTime.format(
  new Date(),
  'YYYY-MM-DD HH:mm:ss TZ',
  'America/New_York'
)

// Relative time formatting
const relative = HolyTime.relativeFromTo(
  HolyTime.now(),
  HolyTime.in(2, 'hours')
) // "in 2 hours"

Comparison to Alternatives

Holy Time is designed as a modern alternative to libraries like Moment.js, Day.js, and date-fns, with a focus on type safety and chainable operations.
FeatureHoly TimeMoment.jsDay.jsdate-fns
Type-safeYesNoPartialYes
Chainable APIYesYesYesNo
Dependencies0Multiple00
Bundle SizeSmallLargeSmallMedium
Mutable/ImmutableMutableMutableImmutableImmutable
If you’re looking for a TypeScript-first library with a fluent API similar to Moment.js but without the weight, Holy Time is an excellent choice.

Next Steps

Installation

Get started by installing Holy Time in your project

Quickstart

Learn the basics with a hands-on example

Build docs developers (and LLMs) love