Skip to main content
On this page

@std/datetime

Unstable

This @std package is experimental and its API may change without a major version bump.

Overview Jump to heading

Utilities for dealing with Date objects.

import { dayOfYear, isLeap, difference, HOUR, MINUTE, SECOND } from "@std/datetime";
import { assertEquals } from "@std/assert";

assertEquals(dayOfYear(new Date("2019-03-11T03:24:00")), 70);
assertEquals(isLeap(1970), false);

const date0 = new Date("2018-05-14");
const date1 = new Date("2020-05-13");
assertEquals(difference(date0, date1).years, 1);

assertEquals(HOUR / MINUTE, 60);
assertEquals(MINUTE / SECOND, 60);

Add to your project Jump to heading

deno add jsr:@std/datetime

See all symbols in @std/datetime on

What is datetime? Jump to heading

In JavaScript, dates and times center around the built‑in Date object:

  • A Date stores a single point in time as milliseconds since the Unix epoch (1970‑01‑01T00:00:00Z). Its internal value is always UTC.
  • Rendering and many getters can be either local time (e.g., getHours) or UTC (e.g., getUTCHours). Be explicit about which you need.
  • Parsing with the Date constructor is locale/implementation‑dependent for non‑ISO strings. Prefer ISO‑8601 (YYYY‑MM‑DDTHH:mm:ssZ) or a library/parser.

The @std/datetime package builds on top of this to offer simple parsing, formatting, and date arithmetic with explicit patterns and options.

It aims to cover common needs without a large dependency and works across Deno, Node.js, Bun, browsers, and Workers.

When to use @std/datetime Jump to heading

If you are formatting and parsing dates/times and doing small calculations without pulling larger libraries. Typical use cases:

  • Human‑readable timestamps for logs, filenames, or UI.
  • Parsing user input safely with explicit formats instead of Date’s heuristics.
  • Showing relative durations (e.g., “X days remaining”).
  • Getting calendar fields like week of year or day number in year.
  • Generating standards‑compliant strings (e.g., ISO‑8601) for APIs.

Examples Jump to heading

import {
  dayOfYear,
  dayOfYearUtc,
  difference,
  format,
  isLeap,
  isUtcLeap,
  parse,
  weekOfYear,
} from "@std/datetime";

// Format with time zone
const nowTokyo = format(
  new Date("2025-01-02T12:34:56Z"),
  "yyyy-MM-dd HH:mm XXX",
  { timeZone: "Asia/Tokyo" },
);

// Parse an explicit pattern (local time unless the pattern/offset specifies otherwise)
const parsed = parse("2025-01-02 09:30", "yyyy-MM-dd HH:mm");
parsed instanceof Date; // true

// Difference in specific units
const a = new Date("2024-01-01T00:00:00Z");
const b = new Date("2025-06-01T00:00:00Z");
difference(a, b, { units: ["years", "months", "days"] });
// -> { years: 1, months: 5, days: 0 }

// Week of year and day-of-year
weekOfYear(new Date("2025-01-05")); // ISO week number (1-53)
dayOfYear(new Date("2025-03-01")); // Local TZ
dayOfYearUtc(new Date(Date.UTC(2025, 2, 1))); // UTC

// Leap year checks
isLeap(2024); // true in local rules
isUtcLeap(2024); // true (timezone-independent)

// Format in UTC vs a specific time zone
import { format } from "@std/datetime";

const d = new Date("2025-01-02T00:00:00Z");
format(d, "yyyy-MM-dd HH:mm XXX", { timeZone: "UTC" }); // 2025-01-02 00:00 +00:00
format(d, "yyyy-MM-dd HH:mm XXX", { timeZone: "Asia/Tokyo" }); // 2025-01-02 09:00 +09:00

// Parse an ISO string with numeric offset
import { parse } from "@std/datetime";

const withOffset = parse(
  "2025-01-02T09:30:00+09:00",
  "yyyy-MM-dd'T'HH:mm:ssXXX",
);
withOffset.toISOString(); // 2025-01-02T00:30:00.000Z

// Add durations using provided constants
import { HOUR, MINUTE, SECOND } from "@std/datetime";

const start = new Date("2025-01-01T00:00:00Z");
const plus90m = new Date(start.getTime() + 90 * MINUTE);
const plus1h5s = new Date(start.getTime() + HOUR + 5 * SECOND);

// Days until a deadline (countdown)
import { difference } from "@std/datetime";

const now = new Date("2025-01-01T00:00:00Z");
const launch = new Date("2025-02-15T00:00:00Z");
difference(now, launch, { units: ["days"] }); // { days: 45 }

// ISO week-of-year around year boundaries
import { weekOfYear } from "@std/datetime";

weekOfYear(new Date("2020-12-31")); // 53
weekOfYear(new Date("2021-01-01")); // 53 (still the last ISO week of 2020)
weekOfYear(new Date("2021-01-04")); // 1

// Leap-year checks with Date inputs
import { isLeap } from "@std/datetime";

isLeap(new Date("2000-01-01")); // true (divisible by 400)
isLeap(new Date("1900-01-01")); // false (century not divisible by 400)

Tips Jump to heading

  • Be explicit about time zones in formats (e.g., include XXX offset tokens).
  • Prefer ISO 8601 for interchange and storage.

Did you find what you needed?

Edit this page
Privacy policy