temporal-extra

Locale-aware Temporal utilities for ISO week numbers, business day navigation, and calendar inspections. Built on top of the Temporal API, with optional polyfill support.

Features

• Adjusters: Jump to previous/next business day, week day, or boundary of a month/year.
• Inspectors: Get accurate week numbers using locale-specific rules (like ISO-8601, US, or Middle Eastern systems).
• Polyfill support: Includes a tiny TypeScript-compatible Intl.Locale.getWeekInfo() polyfill.

Installation

Install via your favorite package manager:

npm install temporal-extra
# or
pnpm add temporal-extra
# or
yarn add temporal-extra

Using the Temporal Polyfill

If you want to use the Temporal API in environments where it is not yet natively supported, you can include the temporal-polyfill.

Once you have it installed, you can enable it:

if (typeof Temporal === "undefined") {
    await import("temporal-polyfill/global");
}

This will globally patch the environment, adding the Temporal API on globalThis.Temporal.

TypeScript support for Temporal

To get proper TypeScript typings for the polyfill (and the Temporal API in general), you need to install the temporal-spec types package.

Then create a temporal.d.ts file in your project (e.g., in your src folder or your types folder) with the following content:

import "temporal-spec/global";

This will augment the TypeScript global scope with Temporal API types, so your editor and compiler understand Temporal properly.

Usage

Adjusters

Adjust or navigate PlainDate, PlainDateTime, or ZonedDateTime instances:

import {
  previousBusinessDay,
  nextDayOfWeek,
  firstDayOfMonth,
  lastDayOfYear,
} from "temporal-extra";

const date = Temporal.PlainDate.from("2024-06-18");

previousBusinessDay(date, [6, 7]); // skips Sat/Sun
nextDayOfWeek(date, 5);            // jump to next Friday
firstDayOfMonth(date);             // 2024-06-01
lastDayOfYear(date);               // 2024-12-31

All functions are type-safe and maintain the input type (PlainDate, PlainDateTime, or ZonedDateTime).

Inspectors

Get locale-aware week numbers:

import { localeAwareWeekNumber } from "temporal-extra";

const date = Temporal.PlainDate.from("2023-01-01");

localeAwareWeekNumber(date, "en-US"); // 1 (US week rules)
localeAwareWeekNumber(date, "de-DE"); // 52 (ISO-8601 rules)

Internally, this uses the Intl.Locale.getWeekInfo() proposal and falls back to a polyfill if necessary.

Polyfill support

The module automatically loads the Intl.Locale.getWeekInfo() polyfill only when needed (e.g. in Node or older environments). But you can import it explicitly too:

import "temporal-extra/week-info/polyfill";

NOTE: This also automatically augments the global TypeScript types for Intl.Locale.prototype.getWeekInfo.

Now you can use the API even when your environment does not support it:

new Intl.Locale("de-DE").getWeekInfo();
// { firstDay: 1, weekend: [6, 7], minimalDays: 4 }

The polyfill is tiny, brotli-compressed clocking in at just a little over 400 bytes!