npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@purple-brock/time

v2.0.0

Published

Lightweight date engine and formatter — no moment, no date-fns.

Downloads

693

Readme

The date library that actually understands where your users are sett.

A small, fast library for working with dates and times in JavaScript and TypeScript apps. No extra packages required — it works entirely with tools already built into browsers and Node.js. We dug deep so you don't have to.


What does it do?

Working with dates sounds simple — until your app needs to handle users in different countries, different time zones, and different date formats. Most date libraries assume everyone works Monday to Friday, weeks start on Monday, and times are shown in 24-hour format. That's wrong for a large part of the world.

Purple Brock Time handles this automatically:

  • Weekends differ by country. In Saudi Arabia, the weekend is Friday and Saturday. In Israel it is also Friday and Saturday. In most of the world it is Saturday and Sunday. Purple Brock Time knows this for every locale (country/language setting) in the world.
  • Week starts differ by country. In the US, weeks start on Sunday. In the UK and most of Europe, they start on Monday. Purple Brock Time picks the right one automatically.
  • Time format differs by country. In the US, people use 12-hour clocks (3:30 PM). In Germany, 24-hour clocks (15:30). Purple Brock Time switches automatically based on locale.
  • Daylight saving time is handled correctly. Calculating "start of today" or "days between two dates" can give wrong answers when clocks change. Purple Brock Time does this correctly.

You set your app's locale once at startup — every date operation and every formatted date in your app picks it up automatically.


Install

npm install @purple-brock/time
# or
yarn add @purple-brock/time

Requires Node.js 20 or higher. The library will throw an error on startup if you are running an older version.

formatDuration and formatCountdown require Node 24+. Everything else in the library works on Node 20+.


How does it compare to other libraries?

| Feature | moment | date-fns | luxon | Purple Brock Time | |---|:---:|:---:|:---:|:---:| | No extra packages needed | ✗ | ✗ | ✅ | ✅ | | Dates are never modified in place | ✗ | ✅ | ✅ | ✅ | | No new keyword required | ✗ | ✅ | ✗ | ✅ | | Uses the platform's built-in locale tools — no separate language files | ✗ | ✗ | ✅ | ✅ | | Correct day/week differences across clock changes | ✗ | ✗ | ✅ | ✅ | | Correct start/end of day across clock changes | ✗ | via date-fns-tz | ✅ | ✅ | | Create a date from a local time (not UTC) | ✗ | ✗ | ✅ | ✅ | | Fractional differences (e.g. 1.5 hours) | ✅ | ✅ | ✅ | ✅ | | Inclusive range options | ✅ | partial | ✗ | ✅ | | Correct weekends for every country | ✗ | ✗ | ✗ | ✅ | | Correct week start for every country | ✗ | ✗ | ✗ | ✅ | | 12h/24h clock chosen automatically by country | ✗ | ✗ | ✗ | ✅ | | Business day calculations per country | ✗ | ✗ | ✗ | ✅ | | Date range generator | ✗ | ✗ | ✗ | ✅ | | Countdown that returns null for past dates | ✗ | ✗ | ✗ | ✅ | | Duration formatting in the user's language | ✗ | ✗ | ✗ | ✅ | | Reactive global locale (one call updates the whole app) | ✗ | ✗ | ✗ | ✅ | | Bundle size (minified + gzipped) | ~72 KB | ~14 KB | ~23 KB | ~5.7 KB |


Quick start

import { Badger, Sett, BadgerSettings } from "@purple-brock/time";

// Tell the library which country/language your app is running in.
// Do this once at startup — every date operation will use it automatically.
// A plain tag string works everywhere, including React Native (an Intl.Locale works too).
BadgerSettings.setLocale("en-US");
BadgerSettings.defaultTimeZone = "America/New_York";

// Add 7 days to a date
Badger("2026-06-15").add(7, "day").toLocalISODate()
// "2026-06-22"

// Check if an order's delivery time is today
Badger(order.deliveryTime).isToday()

// Format a date for display — picks up locale automatically
// (examples: a delivery at 3:30:45 PM New York time on 15 June 2026)
Sett(order.deliveryTime).formatDate()        // "06/15/2026, 03:30:45 PM"  (12-hour because en-US)
Sett(order.deliveryTime).formatTimeOnly()    // "03:30:45 PM"
Sett(order.deliveryTime).formatRelative()    // e.g. "in 2 hours"

// Show a countdown — returns null automatically when the date has passed
Sett(new Date()).formatCountdown(new Date("2026-12-25"))
// e.g. "193 days, 4 hours, 22 minutes, and 11 seconds"

API

The three main exports

| Export | What it does | |---|---| | Badger(date?) | Date arithmetic — add/subtract time, compare dates, check if a date is today/past/future, generate ranges, business day calculations | | Sett(date?, locale?, options?) | Formatting — display dates in the user's language, relative time ("2 hours ago"), countdown timers, sending dates to a backend | | BadgerSettings | Global defaults — set the locale and time zone once, subscribe to locale changes |

No new keyword is needed anywhere. Every operation returns a new value — the original date is never changed.

TypeScript types

If you are using TypeScript, the factory names double as the instance types — so Badger and Sett can be used as both a value and a type, with no separate type import:

import { Badger, Sett } from "@purple-brock/time";

function addBusinessDays(date: Badger, n: number): Badger {
    return date.addBusinessDays(n);
}

function formatForDisplay(date: Badger): Sett {
    return Sett(date.toDate());
}

The explicit instance-type aliases BadgerInstance / BadgerSettInstance remain exported and are equivalent — use whichever reads better:

import type { BadgerInstance, BadgerSettInstance } from "@purple-brock/time";

Badger — working with dates

Creating a date

Badger()                              // right now
Badger("2026-03-15T10:30:00")        // a specific date and time (treated as UTC)
Badger("2026-03-15")                 // a specific date (local midnight)
Badger("2026-03-15T10:30:00Z")       // explicit time zone offset — used as-is
Badger("2026-03-15T10:30:00+02:00")  // with a +2 hour offset — used as-is
Badger(someDate)                     // copy of a JavaScript Date object

How strings are interpreted:

  • A date-only string like "2026-03-15" is anchored to local midnight, so its calendar day is correct in every time zone — reading .day, adding months, or building a range never drifts to the previous day for users west of UTC
  • A string that already includes a time zone (ends in Z or +02:00) is used exactly as written
  • Any other date-time string (no time zone) is treated as UTC

Creating a date from local time

Use Badger.fromLocal() when a date and time come from a form or picker and represent the user's local time, not UTC.

// The user selected "22 May 2026 at 00:15" in their local time zone
const dt = Badger.fromLocal("2026-05-22", "00:15");
dt.hour;      // 0  — local midnight, not shifted
dt.dayOfWeek; // 5  — Friday in local time

The date must be "YYYY-MM-DD" and the time must be "HH:mm". An error is thrown if the format is wrong or if the date doesn't exist (e.g. "2026-02-30").


Finding the earliest or latest date

const earliest = Badger.min(deadline, today, cutoff);
const latest   = Badger.max(deadline, today, cutoff);

Throws an error if called with no arguments or if any input is an invalid date. Filter out invalid dates first:

const valid = dates.filter(d => d.isValid());
const earliest = valid.length ? Badger.min(...valid) : null;

Generating a list of dates (range)

Returns an array of dates from start up to (but not including) end. Useful for building calendars, chart labels, and report headers.

// Every day in June 2026
Badger.range("2026-06-01", "2026-07-01", "day")
// → [Jun 1, Jun 2, … Jun 30]  — 30 dates

// One entry per week across a quarter
Badger.range(startOfQuarter, endOfQuarter, "week")

// Monthly labels for a chart
Badger.range("2026-01-01", "2027-01-01", "month")
// → [Jan 1, Feb 1, Mar 1, … Dec 1]

// Strings, plain Dates, and Badger instances all work interchangeably
Badger.range(new Date("2026-06-01"), new Date("2026-06-08"), "day")

Monthly ranges re-anchor to the start's day-of-month, clamping per month rather than drifting. A range from January 31 yields Jan 31, Feb 28, Mar 31, Apr 30, May 31 — not a steady slide down to the 28th.


Reading parts of a date

const dt = Badger("2026-07-04T15:30:45.123Z");

dt.year        // 2026
dt.month       // 7        (1 = January, 12 = December)
dt.day         // 4
dt.hour        // 15
dt.minute      // 30
dt.second      // 45
dt.millisecond // 123
dt.dayOfWeek   // 6        (0 = Sunday, 1 = Monday … 6 = Saturday, in local time)
dt.dayOfYear   // 185      (which day of the year this is, 1–366)
dt.weekYear    // 2026     (the ISO year for the week — may differ at year boundaries)
dt.quarter     // 3        (1–4)

Adding and subtracting time

dt.add(7, "day")          // 7 days later
dt.subtract(1, "month")   // 1 month earlier
dt.add(-2, "hour")        // 2 hours earlier (negative numbers work)

// Apply several units at once
dt.add({ days: 7, hours: 2, minutes: 30 })
dt.subtract({ months: 1, days: 5 })

Singular and plural both work: "day" and "days", "month" and "months", etc.

Available units: "year", "quarter", "month", "week", "day", "hour", "minute", "second", "millisecond"

Adding months clamps to the last valid day of the target month — January 31 + 1 month becomes February 28 or 29, not March 3.

Amounts must be whole numbers. A fractional amount (e.g. add(1.5, "day")) throws a RangeError rather than silently truncating to a whole unit — use a finer unit instead (add(36, "hour")).


Changing one field

dt.set("year", 2030)    // returns a new date with just the year changed
dt.set("month", 12)     // 1-indexed — 12 is December
dt.set("hour", 9)

// Clamps to the last valid day if needed
Badger("2026-01-31").set("month", 2)  // → February 28

Throws an error for impossible values (e.g. month 0, hour 25), fractional values (e.g. set("hour", 1.5)), or NaN.


Business days

This is where Purple Brock Time is unique. It uses built-in browser/Node tools to know which days are weekends for every country in the world — no hard-coded rules, no extra data files.

Weekend rules are looked up in this order: explicit locale argument → BadgerSettings.defaultLocale → Saturday + Sunday.

// Standard week (Saturday + Sunday weekend)
Badger("2026-06-12").isBusinessDay()    // true  (Friday)
Badger("2026-06-13").isBusinessDay()    // false (Saturday)
Badger("2026-06-15").isWeekend()        // false (Monday)
Badger("2026-06-20").isWeekend()        // true  (Saturday)

// Saudi Arabia uses a Friday + Saturday weekend
Badger("2026-06-12").isBusinessDay(new Intl.Locale("ar-SA"))  // false (Friday is the weekend)
Badger("2026-06-14").isBusinessDay(new Intl.Locale("ar-SA"))  // true  (Sunday is a workday)

// Add business days — skips the correct weekends for the locale
// The count must be a whole number — 1.5 throws an error
Badger("2026-06-12").addBusinessDays(1)                             // Mon Jun 15 (skips Sat+Sun)
Badger("2026-06-12").addBusinessDays(1, new Intl.Locale("ar-SA"))  // Sun Jun 14 (skips Fri+Sat)
Badger("2026-06-15").subtractBusinessDays(1)                        // Fri Jun 12

// Set the locale once — all business day methods pick it up
BadgerSettings.setLocale(new Intl.Locale("ar-SA"));
Badger("2026-06-12").isBusinessDay()    // false — uses ar-SA automatically
Badger("2026-06-12").addBusinessDays(1) // Sun Jun 14

No other date library does this natively. Other libraries just don't give a badger.

Public holidays (optional)

Weekends are derived automatically; public holidays are not — no locale or region string can tell you that Dec 25 is a UK bank holiday but not a Saudi one, and Purple Brock Time deliberately ships no holiday data (that would be a country- by-country calendar to maintain forever). Instead every business-day method takes an optional set of holiday dates that you supply — typically resolved from a source like date-holidays, keyed off the user's region. Holidays are then skipped exactly like weekends:

const holidays = ["2026-12-25", "2026-12-28"]; // your dates, e.g. from date-holidays

Badger("2026-12-25").isBusinessDay(new Intl.Locale("en-GB"), holidays);            // false
Badger("2026-12-24").addBusinessDays(1, new Intl.Locale("en-GB"), holidays);       // Dec 29
Badger("2026-12-29").subtractBusinessDays(1, new Intl.Locale("en-GB"), holidays);  // Dec 24

Rules that keep this safe:

  • Strict ISO only. Each entry must be a YYYY-MM-DD string. A typo, a datetime, or a localized format (25/12/2026, 12/25/2026) throws a RangeError at the boundary rather than silently never matching — and so do impossible dates (2026-13-25, 2026-02-30). Convert any localized user input to ISO before passing it in; the library never guesses DD/MM vs MM/DD.
  • Accepts an array or a Set (anything Iterable<string>). Omitted or empty means "weekends only" — fully backward compatible.
  • Local-date keyed. A holiday matches the date's local calendar day, consistent with the locale weekend evaluation (so it's correct near midnight in any timezone, not just UTC).
  • Never hangs. A pathological set that blocks every reachable day makes addBusinessDays/subtractBusinessDays throw a RangeError instead of looping forever.

Countdown

Returns the time remaining until a future date as days, hours, minutes, and seconds. Returns null if the date has already passed — so you always know you need to handle the "expired" case.

Badger("2026-12-25").countdown()
// e.g. { days: 193, hours: 4, minutes: 22, seconds: 11 }

Badger("2025-01-01").countdown()
// null — already passed

// Useful in tests: provide a fixed "now" instead of the real current time
Badger("2026-12-25").countdown(Badger("2026-12-01").toDate())
// { days: 24, hours: 0, minutes: 0, seconds: 0 }
// (both dates are local midnight; across a daylight-saving change the hours shift by one)

// Pair with Sett.formatCountdown() to get a display string (web/Node 24+, not Hermes)
Sett(new Date()).formatCountdown(new Date("2026-12-25"))
// e.g. "193 days, 4 hours, 22 minutes, and 11 seconds"
// null if the date has passed

Start and end of a period

All operations use local time and never change the original date.

dt.startOf("year")    // 1 Jan, midnight (local time)
dt.startOf("quarter") // first day of the quarter, midnight
dt.startOf("month")   // first of the month, midnight
dt.startOf("week")    // Monday 00:00:00 (ISO 8601 standard)
dt.startOf("day")     // midnight (00:00:00.000)
dt.startOf("hour")    // top of the hour
dt.startOf("minute")
dt.startOf("second")

dt.endOf("year")      // 31 Dec, 23:59:59.999 (local time)
dt.endOf("quarter")
dt.endOf("month")     // last day of the month, 23:59:59.999
dt.endOf("week")      // Sunday 23:59:59.999
dt.endOf("day")       // 23:59:59.999
dt.endOf("hour")
dt.endOf("minute")
dt.endOf("second")

Comparing dates

dt.isBefore(other)
dt.isAfter(other)
dt.isSameOrBefore(other)
dt.isSameOrAfter(other)
dt.isSame(other)             // same exact millisecond
dt.isSame(other, "day")      // same calendar day
dt.isSame(other, "month")    // same month
dt.isSame(other, "week")     // same ISO week (handles year boundaries correctly)
dt.isSame(other, "quarter")

Checking if a date is within a range:

// By default, the boundaries themselves are not included
date.isBetween(open, close)

// Include the start boundary
open.isBetween(open, close, { includeStart: true })

// Include the end boundary
close.isBetween(open, close, { includeEnd: true })

// Include both
date.isBetween(open, close, { includeStart: true, includeEnd: true })

Throws an error if either boundary is invalid, or if start is after end.

Clamping a date to a range:

// Returns the closest valid date within the range
Badger("2025-01-01").clamp(min, max)  // → min  (too early, clamped to start)
Badger("2027-01-01").clamp(min, max)  // → max  (too late, clamped to end)
Badger("2026-06-15").clamp(min, max)  // → unchanged (already within range)

Quick helpers:

dt.isToday()       // is this date today (in local time)?
dt.isYesterday()
dt.isTomorrow()
dt.isPast()        // is this date before right now?
dt.isFuture()      // is this date after right now?
dt.isWeekend()     // is this a weekend day? (respects BadgerSettings.defaultLocale)
dt.isWeekday()     // is this a working day? (respects BadgerSettings.defaultLocale)

All comparisons accept either a Badger instance or a plain JavaScript Date.


Difference between two dates

a.diff(b, "hour")        // 1    — whole hours, rounded down
a.diff(b, "hour", true)  // 1.5  — fractional (pass true as the third argument)
b.diff(a, "minute")      // -90  — negative when b is before a

Day and week differences account for daylight saving time correctly — they count calendar days, not raw hours.


Other utilities

dt.toISOString()              // "2026-03-15T10:30:00.000Z"  — UTC instant; throws if invalid
dt.toLocalISODate()           // "2026-03-15"  — LOCAL calendar date; use this, never toISOString().slice(0,10)
dt.toDate()                   // a plain JavaScript Date (a copy — changes won't affect the Badger)
dt.toUnixTimestamp()          // seconds since 1 Jan 1970 (floored)
dt.toMillisecondTimestamp()   // milliseconds since 1 Jan 1970
dt.toObject()                 // { year, month, day, hour, minute, second, millisecond }
dt.clone()                    // independent copy
dt.isValid()                  // false if the date is corrupt or unparseable — always check this
dt.getDaysInMonth()           // how many days are in the date's month (28–31)
dt.daysInYear()               // 365 or 366 (NaN if invalid)
dt.getWeekNumber()            // ISO 8601 week number (1–53)
dt.isLeapYear()               // is this a leap year?

Invalid dates

Always call isValid() before using a Badger that was created from user input or an external source. When a date is invalid, methods return safe fallback values rather than crashing:

| Type of method | Examples | Returns when invalid | |---|---|---| | Yes/no checks | isWeekend, isBusinessDay, isLeapYear, isPast, isBefore… | false | | Number values | year, month, day, diff, toUnixTimestamp… | NaN | | Countdown | countdown() | null | | Arithmetic | add, subtract, startOf, endOf, clone | An invalid Badger (further chaining stays invalid) | | Business day iteration | addBusinessDays, subtractBusinessDays | Invalid clone — no looping | | toISOString() / toLocalISODate() | — | Throws an error (there is no meaningful string to produce) | | Sett formatters | formatDate, formatTimeOnly, getDayName… | Throw an error |

const bad = Badger("not-a-date");
bad.isValid()            // false — check this first
bad.isWeekend()          // false
bad.countdown()          // null
bad.daysInYear()         // NaN
bad.addBusinessDays(5)   // returns an invalid clone — no looping happens

// toISOString is the one that throws — it can't produce a string for an invalid date
bad.toISOString()        // Error: Badger.toISOString(): date is not valid…

// Badger.min and Badger.max also throw on invalid input — filter first
const dates = [Badger("2026-01-01"), Badger("bad"), Badger("2026-06-15")];
const valid = dates.filter(d => d.isValid());
Badger.min(...valid)     // Badger("2026-01-01")

Sett — displaying and formatting dates

Sett turns a date into a string your users can read. It uses the platform's built-in formatting tools, so it automatically uses the right format for the user's country — no extra language files, no manual configuration per locale.

Defaults to British English (en-GB) and the device's own time zone, unless you override them with BadgerSettings.

formatDate() shows the time on the locale's own clock: 12-hour for en-US ("06/15/2026, 03:30:45 PM"), 24-hour for en-GB ("15/06/2026, 15:30:45"). If you pass your own options to Sett(), they're used exactly as given.

Creating a Sett

String inputs follow the same rules as Badger() — bare date-time strings are treated as UTC.

Sett()                                              // now, global defaults
Sett(someDate)                                      // specific date, global defaults
Sett("2026-03-15T10:30:00")                         // string input → treated as UTC
Sett("2026-03-15")                                  // date-only → LOCAL midnight
Sett(someDate, new Intl.Locale("sv-SE"))            // override the locale
Sett(someDate, new Intl.Locale("sv-SE"), {          // override locale + formatting options
    timeZone: "Europe/Stockholm",
    year: "numeric",
    month: "2-digit",
    day: "2-digit"
})
Sett(someDate, "sv-SE")                             // a plain locale string works too

Hermes caveat: formatRelative needs Intl.RelativeTimeFormat, and formatCountdown / formatDuration need Intl.DurationFormat. Hermes (React Native) doesn't document either, so treat those three as web/Node only. Everything else is Hermes-safe. formatRelative rounds to the nearest month (31 Jan → 1 Mar is "last month").

Time zone default: a Sett with no timeZone option uses BadgerSettings.defaultTimeZone, else the device's own zone (it used to fall back to Europe/London).

React Native / Hermes: Hermes has no Intl.Locale. Purple Brock Time never needs one: the default locale is the plain tag "en-GB", and anything that wants week info (isWeekend, startOfWeek, getDaysOfTheWeek, the business-day methods) or the 12/24-hour clock (formatTimeOnly) reads it safely, falling back to Monday-first, Saturday + Sunday weekend when Intl.Locale is missing. On Hermes, pass locales as strings ("sv-SE") rather than new Intl.Locale(...). Every locale parameter accepts either form (LocaleInput), including BadgerSettings.setLocale().

Displaying a date

const s = Sett(new Date("2026-03-15T14:30:45Z"));   // outputs shown for a device in UTC

s.formatDate()           // "15/03/2026, 14:30:45"  (en-GB format, 24-hour)
s.formatDateOnly()       // "15/03/2026"
s.formatTimeOnly()       // "14:30:45"  (24-hour for en-GB, chosen automatically)
s.getDayName()           // "Sunday"   (pass "short" → "Sun", "narrow" → "S")
s.getMonthName()         // "March"    (pass "short" → "Mar", "narrow" → "M")
s.getDaysOfTheWeek()     // ["Monday", "Tuesday", …]  — starts on the locale's first day
s.getMonthsOfTheYear()   // ["January", …, "December"]

formatDateOnly() never shows a time. If you pass date options to Sett() (weekday, day, month, year, era, or dateStyle), it uses them; otherwise it's numeric:

Sett(new Date("2026-07-27T12:00:00Z"), "en-GB", { weekday: "long", day: "numeric", month: "long", year: "numeric" })
    .formatDateOnly()    // "Monday, 27 July 2026"
Sett(new Date("2026-07-27T12:00:00Z"), "en-GB", { dateStyle: "long" })
    .formatDateOnly()    // "27 July 2026"

12-hour vs 24-hour clocks — automatic

formatTimeOnly() and formatDate() read the locale and pick the right clock format. You don't need to configure anything.

// US English — 12-hour clock
Sett(new Date("2026-06-15T15:30:45Z"), new Intl.Locale("en-US"), { timeZone: "UTC" }).formatTimeOnly()
// "03:30:45 PM"

// German — 24-hour clock
Sett(new Date("2026-06-15T15:30:45Z"), new Intl.Locale("de-DE"), { timeZone: "UTC" }).formatTimeOnly()
// "15:30:45"

// Arabic (Saudi Arabia) — 12-hour in Arabic numerals
Sett(new Date("2026-06-15T15:30:45Z"), new Intl.Locale("ar-SA"), { timeZone: "UTC" }).formatTimeOnly()

Locale-aware calendar helpers

isWeekend() and startOfWeek() use the platform's built-in country data — correct for every country worldwide. Both use local time, so they give the right answer even near midnight in non-UTC time zones.

// Saudi Arabia: Friday and Saturday are the weekend
Sett(new Date("2026-06-05"), new Intl.Locale("ar-SA")).isWeekend()  // true  (Friday)
Sett(new Date("2026-06-07"), new Intl.Locale("ar-SA")).isWeekend()  // false (Sunday is a workday)

// Where does the week start?
Sett(new Date("2026-06-10T12:00:00"), new Intl.Locale("en-US")).startOfWeek()
// → Midnight on Sunday Jun 7  (US weeks start Sunday)

Sett(new Date("2026-06-10T12:00:00"), new Intl.Locale("en-GB")).startOfWeek()
// → Midnight on Monday Jun 8  (UK weeks start Monday)

Relative time

Shows how long ago or how far in the future a date is — like "3 hours ago" or "in 2 days".

s.formatRelative()             // "3 hours ago" / "in 2 days" / "last month"
s.formatRelative(anchorDate)   // relative to a specific date instead of now

Month and year thresholds are based on elapsed days, not calendar month boundaries. A 7-day gap that crosses a month boundary shows as "last week", not "last month". 28+ days in different months shows as months.

Throws an error if the date is invalid — never silently shows garbage.

Duration formatting

Shows a duration in the user's natural language. Uses the platform's built-in tools — no hand-rolled formatting.

Requires Node 24+, Chrome 127+, Firefox 127+, or Safari 17.4+. If you call this on an older environment it throws — but the rest of Sett continues to work fine on Node 20+.

Sett(new Date(), new Intl.Locale("en-GB")).formatDuration({ hours: 3, minutes: 22 })
// "3 hours and 22 minutes"

Sett(new Date(), new Intl.Locale("de-DE")).formatDuration({ hours: 2, minutes: 30 })
// "2 Stunden und 30 Minuten"  (German)

Sett(new Date(), new Intl.Locale("fr-FR")).formatDuration({ days: 1, hours: 4 })
// "1 jour et 4 heures"  (French)

// Calculate elapsed time and format in one go
const minutes = Badger(startTime).diff(Badger(), "minute");
Sett(new Date()).formatDuration({ minutes })
// "47 minutes"

Countdown display

Combines the countdown calculation with duration formatting in a single call. Returns null if the date has passed. Needs Intl.DurationFormat (Node 24+ / modern browsers, not Hermes).

Sett(new Date()).formatCountdown(new Date("2026-12-25"))
// e.g. "193 days, 4 hours, 22 minutes, and 11 seconds"

Sett(new Date()).formatCountdown(new Date("2025-01-01"))
// null — date is in the past

Live countdown timer in React Native — updates every second, switches to "Expired" when done. It uses Badger().countdown() (plain maths, Hermes-safe) and formats the numbers itself:

function CountdownLabel({ endsAt }: { endsAt: string }) {
    const [label, setLabel] = useState<string | null>(null);

    useEffect(() => {
        const tick = () => {
            const left = Badger(endsAt).countdown();
            setLabel(left ? `${left.days}d ${left.hours}h ${left.minutes}m ${left.seconds}s` : "Expired");
        };
        tick();
        const id = setInterval(tick, 1000);
        return () => clearInterval(id);
    }, [endsAt]);

    return <Text>{label}</Text>;
}

Sending dates to a backend server

These methods convert a date to a standard format (UTC ISO 8601) suitable for sending to a server. Start/end of day calculations account for daylight saving time — the correct UTC offset is resolved for that specific date, not approximated.

s.formatForBackend()              // "2026-03-15T10:30:45.000Z"
s.formatForBackendToStartOfDay()  // midnight in the configured time zone → UTC
s.formatForBackendToEndOfDay()    // 23:59:59.999 in the configured time zone → UTC
// London is UTC+1 in summer (BST) — midnight on 15 Jul = 23:00 UTC on 14 Jul
Sett("2026-07-15T12:00:00Z").formatForBackendToStartOfDay()
// "2026-07-14T23:00:00.000Z"

// London is UTC+0 in winter (GMT) — midnight on 15 Jan = 00:00 UTC
Sett("2026-01-15T12:00:00Z").formatForBackendToStartOfDay()
// "2026-01-15T00:00:00.000Z"

BadgerSettings — global defaults

Set your app's locale and time zone once at startup. Every Sett() and Badger() call will inherit these automatically, unless you override them at the call site.

import { BadgerSettings } from "@purple-brock/time";

BadgerSettings.defaultLocale   = "sv-SE";   // or new Intl.Locale("sv-SE")
BadgerSettings.defaultTimeZone = "Europe/Stockholm";

// No locale argument needed anywhere in the app
Sett(order.deliveryTime).formatDate()       // formatted in sv-SE / Stockholm
Sett(order.deliveryTime).isWeekend()        // uses Swedish weekend rules
Sett(order.deliveryTime).formatTimeOnly()   // 24-hour (Sweden uses 24-hour clocks)

// Badger picks up the locale too
Badger("2026-06-12").isBusinessDay()        // uses Swedish weekend definition
Badger("2026-06-12").addBusinessDays(3)     // skips Swedish weekends

// You can always override the global locale for a single call
Sett(date, new Intl.Locale("fr-FR")).formatDate()  // → French format, ignores global

Reactive language switching

setLocale() updates the global locale and immediately notifies all active listeners. One call, entire app updates.

It takes a tag string ("fr-FR") or an Intl.Locale, and throws straight away on anything else: a RangeError for a tag that isn't a real locale, a TypeError for a value that isn't a string or Intl.Locale. Listeners get two arguments: the value you passed, and its tag as a string.

// Listen for locale changes
const unsub = BadgerSettings.subscribe((locale, tag) => {
    console.log("Switched to", tag);
});

BadgerSettings.setLocale("fr-FR");
// → "Switched to fr-FR"

unsub(); // stop listening — important to clean up in components

React Native

Hermes (React Native's engine) has no Intl.Locale, so use tag strings everywhere: setLocale("fr-FR"), and read the tag argument in listeners.

// localeContext.tsx — wrap your app with this so any component can get the current locale
import { createContext, useContext, useEffect, useState, type ReactNode } from "react";
import { BadgerSettings } from "@purple-brock/time";

BadgerSettings.setLocale("en-GB");
const LocaleContext = createContext("en-GB");

export function LocaleProvider({ children }: { children: ReactNode }) {
    const [locale, setLocale] = useState("en-GB");

    // Re-render when the locale changes; unsubscribes automatically on unmount
    useEffect(() => BadgerSettings.subscribe((_locale, tag) => setLocale(tag)), []);

    return <LocaleContext.Provider value={locale}>{children}</LocaleContext.Provider>;
}

export const useLocale = () => useContext(LocaleContext);
// A language switcher button — one press updates every date in the app
<Button title="Français" onPress={() => BadgerSettings.setLocale("fr-FR")} />
// Any component — re-renders when the locale changes
function OrderCard({ order }) {
    const locale = useLocale();
    return (
        <View>
            <Text>{Sett(order.deliveryTime, locale).formatDate()}</Text>
            <Text>{Sett(order.deliveryTime, locale).formatTimeOnly()}</Text>
        </View>
    );
}

(formatRelative is left out on purpose: it needs Intl.RelativeTimeFormat, which Hermes doesn't document.)

React (web)

// Restore the saved locale when the app loads
useEffect(() => {
    const saved = localStorage.getItem("locale");
    if (saved) BadgerSettings.setLocale(saved);
}, []);

Vue

export const appLocale = ref("en-GB");
BadgerSettings.subscribe((_locale, tag) => { appLocale.value = tag; });

// In a component
const formatted = computed(() => Sett(order.deliveryTime, appLocale.value).formatDate());

Vanilla JS

BadgerSettings.subscribe(locale => {
    document.querySelectorAll<HTMLElement>("[data-timestamp]").forEach(el => {
        el.textContent = Sett(new Date(el.dataset.timestamp!), locale).formatRelative();
    });
});

Resetting (for tests)

Clears the locale, time zone, and all subscribers. Essential in tests to prevent settings from leaking between test cases.

afterEach(() => BadgerSettings.reset());

Real-world examples

Delivery app — order card

const order = { dueAt: "2026-06-15T18:30:00Z", locale: new Intl.Locale("en-GB") };

// Is the order due today?
Badger(order.dueAt).isToday()

// How many minutes until it's due?
Badger(order.dueAt).diff(Badger(), "minute")

// Display the due time in the customer's locale (12h/24h chosen automatically)
Sett(order.dueAt, order.locale).formatTimeOnly()

// Show a countdown — or null if already past due
Sett(new Date(), order.locale).formatCountdown(new Date(order.dueAt))
// "3 hours and 22 minutes"

HR system — notice periods

// Add 30 business days, skipping the correct weekends for the employee's country
const lastDay = Badger(terminationDate).addBusinessDays(30, employeeLocale);

// Count remaining working days
const workingDays = Badger.range(Badger(), lastDay, "day")
    .filter(d => d.isBusinessDay(employeeLocale)).length;

// Display the last working day
Sett(lastDay.toDate(), employeeLocale).formatDateOnly()
// "27/07/2026"  (en-GB)

// Or spelled out: pass date options and formatDateOnly uses them
Sett(lastDay.toDate(), employeeLocale, { weekday: "long", day: "numeric", month: "long", year: "numeric" }).formatDateOnly()
// "Monday, 27 July 2026"

Calendar UI — month grid

// Get every day in June 2026
const days = Badger.range(
    Badger("2026-06-01").startOf("month"),
    Badger("2026-06-01").endOf("month").add(1, "day"),
    "day"
);

// Week start and day names vary by country
const weekStart = Sett(new Date(), userLocale).startOfWeek();
const weekDayNames = Sett(new Date(), userLocale).getDaysOfTheWeek("short");
// en-GB: ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
// en-US: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]

Event countdown — live timer

function EventBanner({ eventDate }: { eventDate: string }) {
    const [label, setLabel] = useState<string | null>(null);

    useEffect(() => {
        const tick = () => {
            const left = Badger(eventDate).countdown();   // Hermes-safe
            setLabel(left ? `${left.days} days ${left.hours}h ${left.minutes}m` : "Event has started!");
        };
        tick();
        const id = setInterval(tick, 1000);
        return () => clearInterval(id);
    }, [eventDate]);

    return <Text>{label}</Text>;
}

Backend query — this week's data

const locale = new Intl.Locale("en-GB");
const tz = "Europe/London";
const opts = {
    timeZone: tz,
    year: "numeric" as const, month: "2-digit" as const,
    day: "2-digit" as const, hour: "2-digit" as const,
    minute: "2-digit" as const, second: "2-digit" as const,
    hour12: false
};

// Get the correct start and end of this week, accounting for clock changes
const weekStart = Sett(new Date(), locale, opts);
const weekEnd   = Sett(Badger().endOf("week").toDate(), locale, opts);

const from = weekStart.formatForBackendToStartOfDay();
const to   = weekEnd.formatForBackendToEndOfDay();

await fetch(`/api/orders?from=${from}&to=${to}`);

Comparing dates across time zones

// Server returns UTC timestamps — Purple Brock Time handles them correctly
const serverDate = Badger("2026-06-15T22:00:00Z");

// A user in Central European Summer Time (UTC+2) sees this as midnight on Jun 16
serverDate.isToday()    // correct for the user's local time zone
serverDate.dayOfWeek    // correct local day of week
serverDate.isWeekend()  // correct local weekend check

// The backend always receives UTC, regardless of the user's time zone
Sett(serverDate.toDate()).formatForBackend()
// "2026-06-15T22:00:00.000Z"

Quality

  • 817 tests (8 skipped on Node < 24, where formatDuration/formatCountdown are unavailable) — every public method, every unit, edge cases including clock change transitions, year boundaries, ISO week rollovers, and locale-specific weekend/week-start logic, plus type-level tests that lock the public type surface
  • 100% coverage — statements, branches, functions, and lines
  • Four time zone suites — tests run under Europe/Berlin, America/New_York, America/Los_Angeles, and UTC to verify calculations in UTC+ and UTC− zones. New York and Los Angeles cover spring-forward (March) and fall-back (November). Los Angeles also guards the date-only-string path west of UTC, where a mis-anchored parse would drift the calendar day. Kolkata (UTC+5:30, no clock changes) covers the half-hour offset across all months and month-ends
  • Structured audit — every function was audited for bad inputs, missing inputs, and unexpected values. All findings fixed
  • No runtime dependencies — the bundle is the entire library
npm test           # full suite + coverage
npm run test:cet   # Europe/Berlin (CET/CEST) clock change suite
npm run test:ny    # America/New_York (EST/EDT) clock change suite
npm run test:la    # America/Los_Angeles — date-only west-of-UTC guard

License

MIT © 2026 Luke Price (The Purple Brock).