spacetime: Instructions file for Codex

Spacetime

spacetime is a zero-dependency JavaScript library for working with dates across timezones. It does timezone math (DST, leap years, hemispheres) without the Intl API, and exposes a Moment-like, mostly immutable API.

See the usage guide for behavior and edge cases, and the API reference for public signatures.

Quick example

import spacetime from 'spacetime'

let s = spacetime('March 1 2012 3:22pm', 'America/New_York')
const time = s.time() //'3:22pm'
s = s.time('4:20pm') // modify the time
s = s.goto('America/Los_Angeles') // change the timezone
s.time() // '1:20pm'  (same instant, west-coast clock)

const dec31 = s.endOf('year')
const until = s.diff(dec31, 'days')

const out = s.format('{day-short} {month} {date-ordinal}, {time}') // 'Thu March 1st, 1:20pm'

Docs

• start here - overview and task index
• API - full method list
• inputs - date/time parsing and supported formats
• getters - getting specific datetime information
• setters - modifying the datetime
• formatting - customizable output formats
• timezones - setting and changing iana zones
• comparisons - utility functions on datetimes
• plugins - extending or changing spacetime behaviour

---

Repository map

• src/ — regular entry, instance implementation, parsers (input/), public methods (methods/), and timezone calculations (timezone/).
• src/temporal/ — experimental Temporal-backed entry.
• zonefile/ — timezone data and packing; scripts/tz/ updates the data.
• builds/ — generated distribution bundles; change source rather than bundles.
• types/ — public declarations;
• tests/ — Tape suites grouped by behavior; plugins/ contains workspace packages.

Checks and builds

Run checks relevant to the change. Use a runtime with globalThis.Temporal for Temporal tests; CI uses Node 26 for tooling and tests the regular library on Node 18, 20, 22, 24, and 26.