date

bun add @stopcock/date

Dates are branded numbers (Unix ms timestamps). No Date objects get allocated anywhere, it’s all integer arithmetic. Data-oriented operations expose paired data-first and data-last overloads where noted below.

import { pipe } from '@stopcock/fp'
import { now, add, startOf, format, isWeekend } from '@stopcock/date'

const nextMonday = pipe(now(), startOf('week'), add(7, 'day'))

format(nextMonday, 'YYYY-MM-DD')

• Timestamp is a branded number so you can’t accidentally mix raw numbers with timestamps. Use fromTimestamp() for explicit conversion.
• Dual operations work both ways: add(7, 'day') returns (ts) => Timestamp for pipe, or add(ts, 7, 'day') runs data-first.
• Business days, holidays, timezones, and interval merging are all built in.

Benchmarks

Measured on Bun 1.3, batch operations over 10,000 timestamps.

Arithmetic

Operation	vs date-fns	vs moment	vs luxon
add days	1.6x faster	4.5x faster	8.6x faster
add months	2.3x faster	6.1x faster	11.5x faster
startOf day	1.5x faster	3.6x faster	6.4x faster
startOf month	2.6x faster	5.4x faster	10x faster
endOf year	3.2x faster	5.5x faster	48x faster

Format

Operation	vs date-fns	vs moment	vs luxon
YYYY-MM-DD HH:mm:ss	7.3x faster	3.2x faster	5.9x faster
ddd, DD MMM YYYY hh:mm A	8.4x faster	3.4x faster	6.7x faster

Tip

formatter(pattern) pre-compiles the format string. The compiled formatter is ~9% faster than calling format() directly. Worth it in hot loops.

Diff

Operation	vs date-fns	vs moment	vs luxon
diffInDays	73x faster	45x faster	308x faster
diffInMonths	13x faster	25x faster	45x faster
diffInYears	10x faster	25x faster	44x faster

Note

Native (a - b) / 86400000 is still faster for simple day diffs, but it doesn’t handle month/year boundaries or DST transitions. stopcock is the fastest correct implementation.

Comparisons

Adding time

// date-fns
import { addDays, format } from 'date-fns'
const result = format(addDays(new Date(), 7), 'yyyy-MM-dd')

// dayjs
import dayjs from 'dayjs'
const result = dayjs().add(7, 'day').format('YYYY-MM-DD')

// stopcock: no Date objects, pipes naturally
import { pipe } from '@stopcock/fp'
import { now, add, format } from '@stopcock/date'
const result = pipe(now(), add(7, 'day'), format('YYYY-MM-DD'))

Timezone

// date-fns: needs date-fns-tz, separate adapter
import { toZonedTime } from 'date-fns-tz'
import { isWeekend } from 'date-fns'
isWeekend(toZonedTime(new Date(), 'Asia/Tokyo'))

// dayjs: needs timezone + utc plugins
import dayjs from 'dayjs'
import utc from 'dayjs/plugin/utc'
import tz from 'dayjs/plugin/timezone'
dayjs.extend(utc); dayjs.extend(tz)
dayjs().tz('Asia/Tokyo').day() === 0 || dayjs().tz('Asia/Tokyo').day() === 6

// stopcock: built-in, no plugins
import { Tz, now } from '@stopcock/date'
Tz.isWeekend(now(), 'Asia/Tokyo')

Business days

// date-fns: no built-in business day support
// You need date-fns-business-days or manual loops

// stopcock: built-in
import { now, addBusinessDaysWithHolidays, format, fromISO } from '@stopcock/date'

const holidays = [fromISO('2026-12-25'), fromISO('2026-01-01')]
const delivery = addBusinessDaysWithHolidays(now(), 10, holidays)
format(delivery, 'YYYY-MM-DD')

Real-world patterns

Invoice due date

import { pipe } from '@stopcock/fp'
import { fromISO, add, isWeekend, nextBusinessDay, format, isBefore, now } from '@stopcock/date'

const invoiceDueDate = (issuedAt: string, netDays: number) => {
  const due = pipe(fromISO(issuedAt), add(netDays, 'day'))
  return isWeekend(due) ? nextBusinessDay(due) : due
}

const due = invoiceDueDate('2026-03-15', 30)
const overdue = isBefore(due, now())
format(due, 'DD MMM YYYY') // "14 Apr 2026"

Calendar grid

import { pipe } from '@stopcock/fp'
import * as A from '@stopcock/fp/array'
import { daysIn, getWeekday, format, isToday, isWeekend } from '@stopcock/date'

const calendarMonth = (year: number, month: number) =>
  pipe(
    daysIn(year, month),
    A.map((day) => ({
      label: format(day, 'D'),
      weekday: getWeekday(day),
      today: isToday(day),
      weekend: isWeekend(day),
    })),
  )

Time-ago formatting

import { now, diffInMinutes, diffInHours, diffInDays } from '@stopcock/date'

const timeAgo = (ts: Timestamp) => {
  const mins = diffInMinutes(now(), ts)
  if (mins < 1) return 'just now'
  if (mins < 60) return `${mins}m ago`
  const hrs = diffInHours(now(), ts)
  if (hrs < 24) return `${hrs}h ago`
  return `${diffInDays(now(), ts)}d ago`
}

Cross-timezone scheduling

import { pipe } from '@stopcock/fp'
import { fromISO, Tz } from '@stopcock/date'

const standup = pipe(fromISO('2026-04-03'), Tz.add(9, 'hour', 'Europe/London'))

Tz.format(standup, 'HH:mm z', 'America/New_York') // "04:00 EDT"
Tz.format(standup, 'HH:mm z', 'Asia/Tokyo') // "17:00 JST"

Merging overlapping bookings

import { fromISO, mergeIntervals } from '@stopcock/date'

const bookings = [
  [fromISO('2026-06-01'), fromISO('2026-06-05')],
  [fromISO('2026-06-03'), fromISO('2026-06-08')],
  [fromISO('2026-06-10'), fromISO('2026-06-12')],
] as [Timestamp, Timestamp][]

mergeIntervals(bookings)
// [[Jun 1 → Jun 8], [Jun 10 → Jun 12]]

---

API reference

Types

type Timestamp = number & { readonly [TimestampBrand]: true }
type Duration = number & { readonly [DurationBrand]: true }
type DateUnit = 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond'
type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6
type DateParts = {
  year: number
  month: number
  day?: number
  hour?: number
  minute?: number
  second?: number
  millisecond?: number
}

Creation

now(): Timestamp
fromDate(date: Date): Timestamp
toDate(ts: Timestamp): Date
fromParts(parts: DateParts): Timestamp
fromTimestamp(ms: number): Timestamp
fromISO(iso: string): Timestamp
toTimestamp(ts: Timestamp): number
toISO(ts: Timestamp): string

Extraction

getYear(ts): number              getMonth(ts): number         // 1-12
getDay(ts): number                getWeekday(ts): Weekday      // 0=Sun
getHours(ts): number              getMinutes(ts): number
getSeconds(ts): number            getMilliseconds(ts): number
getDayOfYear(ts): number          getWeekOfYear(ts): number
getQuarter(ts): number            getDaysInMonth(ts): number
getDaysInYear(ts): number         isLeapYear(ts): boolean

Comparison & predicates

The timestamp-taking predicates and clamp support both forms. compare, min, max, isWeekend, isWeekday, isToday, isPast, isFuture, and isValid are direct functions.

compare(a, b): number
min(dates: Timestamp[]): Timestamp        max(dates: Timestamp[]): Timestamp
clamp(ts, lo, hi): Timestamp               clamp(lo, hi): (ts) => Timestamp
isBefore(ts, other): boolean               isBefore(other): (ts) => boolean
isAfter(ts, other): boolean                isAfter(other): (ts) => boolean
isEqual(ts, other): boolean                isEqual(other): (ts) => boolean
isSameDay(ts, other): boolean              isSameDay(other): (ts) => boolean
isSameMonth(ts, other): boolean            isSameMonth(other): (ts) => boolean
isSameYear(ts, other): boolean             isSameYear(other): (ts) => boolean
isBetween(ts, start, end): boolean         isBetween(start, end): (ts) => boolean
isWeekend(ts): boolean                    isWeekday(ts): boolean
isToday(ts): boolean                      isPast(ts): boolean
isFuture(ts): boolean                     isValid(ts): boolean

Arithmetic

add(ts, amount, unit): Timestamp            add(amount, unit): (ts) => Timestamp
subtract(ts, amount, unit): Timestamp       subtract(amount, unit): (ts) => Timestamp
startOf(ts, unit): Timestamp                startOf(unit): (ts) => Timestamp
endOf(ts, unit): Timestamp                  endOf(unit): (ts) => Timestamp
setYear(ts, year): Timestamp                setYear(year): (ts) => Timestamp
setMonth(ts, month): Timestamp              setMonth(month): (ts) => Timestamp
setDay(ts, day): Timestamp                  setDay(day): (ts) => Timestamp
setHours(ts, hours): Timestamp              setHours(hours): (ts) => Timestamp
setMinutes(ts, minutes): Timestamp          setMinutes(minutes): (ts) => Timestamp
setSeconds(ts, seconds): Timestamp          setSeconds(seconds): (ts) => Timestamp

Diff

diff(a, b, unit): number                    diff(b, unit): (a) => number
diffInDays(a, b): number                    diffInDays(b): (a) => number
diffInHours(a, b): number                   diffInHours(b): (a) => number
diffInMinutes(a, b): number                 diffInMinutes(b): (a) => number
diffInSeconds(a, b): number                 diffInSeconds(b): (a) => number
diffInMonths(a, b): number                  diffInMonths(b): (a) => number
diffInYears(a, b): number                   diffInYears(b): (a) => number

Rounding

roundTo(ts, unit): Timestamp                roundTo(unit): (ts) => Timestamp
ceilTo(ts, unit): Timestamp                 ceilTo(unit): (ts) => Timestamp
floorTo(ts, unit): Timestamp                floorTo(unit): (ts) => Timestamp
snapTo(ts, interval, unit): Timestamp       snapTo(interval, unit): (ts) => Timestamp

Duration

duration(amount, unit): Duration
addDuration(ts, d): Timestamp               addDuration(d): (ts) => Timestamp
subtractDuration(ts, d): Timestamp          subtractDuration(d): (ts) => Timestamp
durationToUnit(d, unit): number              durationToUnit(unit): (d) => number
toDuration(a, b): Duration                   scaleDuration(d, factor): Duration
negateDuration(d): Duration

toDuration, scaleDuration, and negateDuration aren’t curried; they’re plain functions.

Ranges & intervals

range(start, end, step, unit): Timestamp[]   range(end, step, unit): (start) => Timestamp[]
rangeBy(start, end, stepFn): Timestamp[]     rangeBy(end, stepFn): (start) => Timestamp[]
daysIn(year, month): Timestamp[]     weekdaysIn(year, month): Timestamp[]
sequence(start, count, step, unit): Timestamp[]
sequence(count, step, unit): (start) => Timestamp[]
overlaps(a1, a2, b1, b2): boolean    contains(start, end, point): boolean
intersection(a1, a2, b1, b2): [Timestamp, Timestamp] | null
union(a1, a2, b1, b2): [Timestamp, Timestamp] | null
gap(a1, a2, b1, b2): [Timestamp, Timestamp] | null
mergeIntervals(intervals): [Timestamp, Timestamp][]

daysIn and weekdaysIn take a year and a month, not a range. overlaps, contains, intersection, union, gap, and mergeIntervals aren’t curried.

Business days

isBusinessDay(ts): boolean
addBusinessDays(ts, amount): Timestamp       addBusinessDays(amount): (ts) => Timestamp
subtractBusinessDays(ts, amount): Timestamp  subtractBusinessDays(amount): (ts) => Timestamp
businessDaysBetween(a, b): number            businessDaysBetween(b): (a) => number
nextBusinessDay(ts): Timestamp    prevBusinessDay(ts): Timestamp
addBusinessDaysWithHolidays(ts, amount, holidays): Timestamp
addBusinessDaysWithHolidays(amount, holidays): (ts) => Timestamp

Formatting & parsing

format(ts, pattern): string                  format(pattern): (ts) => string
formatter(pattern): (ts) => string
parse(input, pattern): Timestamp             parse(pattern): (input) => Timestamp
parser(pattern): (input) => Timestamp
tryParse(input, pattern): Timestamp | null   tryParse(pattern): (input) => Timestamp | null
tryParser(pattern): (input) => Timestamp | null
parseISO(input): Timestamp

Timezone (Tz namespace)

Tz.getYear(ts, zone): number                    Tz.getYear(zone): (ts) => number
Tz.getMonth(ts, zone): number                   Tz.getMonth(zone): (ts) => number
Tz.getDay(ts, zone): number                     Tz.getDay(zone): (ts) => number
Tz.getHours(ts, zone): number                   Tz.getHours(zone): (ts) => number
Tz.getMinutes(ts, zone): number                 Tz.getMinutes(zone): (ts) => number
Tz.getSeconds(ts, zone): number                 Tz.getSeconds(zone): (ts) => number
Tz.isSameDay(a, b, zone): boolean               Tz.isSameDay(b, zone): (a) => boolean
Tz.startOf(ts, unit, zone, disambiguation?): Timestamp
Tz.startOf(unit, zone): (ts) => Timestamp
Tz.endOf(ts, unit, zone, disambiguation?): Timestamp
Tz.endOf(unit, zone): (ts) => Timestamp
Tz.add(ts, amount, unit, zone, disambiguation?): Timestamp
Tz.add(amount, unit, zone): (ts) => Timestamp
Tz.subtract(ts, amount, unit, zone, disambiguation?): Timestamp
Tz.subtract(amount, unit, zone): (ts) => Timestamp
Tz.format(ts, pattern, zone): string            Tz.format(pattern, zone): (ts) => string
Tz.diff(a, b, unit, zone): number               Tz.diff(b, unit, zone): (a) => number

Tz.utcToLocal(ts, zone): Timestamp
Tz.localToUTC(localMs, zone): Timestamp
Tz.isWeekend(ts, zone): boolean
Tz.isToday(ts, zone): boolean
Tz.getOffsetMinutes(ts, zone): number
Tz.getOffsetString(ts, zone): string

Tip

Curried Tz.startOf, Tz.endOf, Tz.add, and Tz.subtract use the default disambiguation policy. Pass disambiguation only to the complete data-first call. Predicates and offset lookups (Tz.isWeekend, Tz.isToday, Tz.getOffsetMinutes, Tz.getOffsetString, Tz.utcToLocal, Tz.localToUTC) take the timestamp first and are not curried.