@haruhimemoe/time

Timezones, weekly availability, match slot finding, regions and .ics files for tournament and event tools. DST-aware IANA zones through Intl, availability grids stored in UTC, ranked match times with who is free, region locks from osu! country codes. No runtime dependencies; zod 4 is a peer. ESM for Node 22.12+, Bun, Deno, browsers and bundlers.

bun add @haruhimemoe/time zodnpm install @haruhimemoe/time zoddeno add npm:@haruhimemoe/time npm:zod

zod 4.0.16 or later. Only /availability (its schema) and /region load it; /zone, /slots and /ics don't.

Two players pick their free hours in their own zones. Find a 90-minute match on the coming Pacific weekend and put it in a calendar file.

import { fromZone, localSlot } from "@haruhimemoe/time/availability";import { buildCalendar } from "@haruhimemoe/time/ics";import { findSlots } from "@haruhimemoe/time/slots";import { weeklyWindow } from "@haruhimemoe/time/zone";// Saturday 18:00 to 21:00 in Los Angeles, and Sunday 10:00 to 13:00 in Tokyo.const alice = fromZone([18, 19, 20].map((h) => localSlot("sat", h * 60)), "America/Los_Angeles");const kenta = fromZone([10, 11, 12].map((h) => localSlot("sun", h * 60)), "Asia/Tokyo");const [best] = findSlots({  sides: [    { id: "alice", members: [{ id: "alice", availability: alice }] },    { id: "kenta", members: [{ id: "kenta", availability: kenta }] },  ],  window: weeklyWindow(new Date(), "America/Los_Angeles", { day: "fri", days: 3 }),  lengthMinutes: 90,});if (best) {  const ics = buildCalendar([    { uid: "r1-m1@example.org", start: best.start, end: best.end, title: "Round 1: alice vs kenta" },  ]);}

In October, Saturday 18:00 in Los Angeles is Sunday 10:00 in Tokyo (01:00 UTC). Both are free for three hours, so a 90-minute match can start at 01:00 or 02:00 UTC: best.start is 01:00 UTC and best.runMinutes is 150.

Instants and zones. Every instant you pass can be a Date or epoch milliseconds; every instant returned is a Date. Zones are IANA ids ("Asia/Tokyo"), never fixed offsets, because an offset goes stale when DST changes. Offsets come from the runtime's Intl data.

Weeks start Monday. Day codes are strings, "mon" to "sun" (WEEKDAYS), so they can't be mixed up with Date#getDay(), which starts on Sunday at 0.

Grids. An Availability is a weekly pattern of UTC slots: { slotMinutes, slots }, where slot 0 starts Monday 00:00 UTC and each slot lasts slotMinutes (a whole divisor of 1440, at least 5). Storing UTC means grids from different zones compare directly.

A player's 18:00 isn't the same UTC hour all year. fromZone converts the local week that contains at (default now) slot by slot, and records zone and week (that local Monday) on the grid. isFreeAt, isFreeDuring, toZone and findSlots use those two fields to move the grid with the owner's clock: a Saturday 18:00 entered in October still means Saturday 18:00 after the clocks change in November. A grid without them is a fixed UTC pattern.

Inside one week, a local slot a spring-forward gap skips is dropped, and one that happens twice at fall back marks both UTC slots. A dropped slot can't come back when the grid is moved to other weeks, so ask for availability in a week without a DST switch (the default, now, is fine on all but two weekends a year). A local slot that doesn't line up with UTC slots (Kolkata, UTC+5:30, at 60 minutes) is floored to the UTC slot containing its start, which can show someone free up to half an hour early. Use slotMinutes: 30 for half-hour zones and 15 for Nepal (UTC+5:45) and Chatham (UTC+12:45) to avoid that. Either way, toZone(fromZone(x, zone), zone) gives x back, so loading and saving a grid never shifts it.

Treat grids as immutable: to change one, build a new slots array. The functions cache per slots array.

disambiguation decides what happens to a wall time a DST switch skips (a gap) or repeats (an overlap), with Temporal's names:

Types: Instant, Weekday, WallTime, ZonedWallTime, Disambiguation, WeeklyWindowOptions.

Union, intersect and count need one slot size (else mismatched-slot-minutes); they keep zone and week only when every grid shares them. An empty list gives an empty 60-minute grid.

findSlots(query) walks a window in steps and returns the best match starts, best first.

Each candidate is { start, end, runMinutes, readySides, sides, staff }, where sides lists { id, free, total, need, ready } and staff lists free staff ids. A side is ready when at least need of its members with data are free, and it has at least one. The default order (compareSlots) is more ready sides, then more free players, more free staff, a longer run, and the earlier start.

A higher seed's fallback (accept slots where only the better seed is fully free) is minReadySides: 1 with filter: (c) => c.sides[0].ready. Preferences such as "Saturday before Sunday" or "not before 10:00 local" go in tiebreak, using toWallTime(c.start, zone).

findSlots throws invalid-window for an empty window or more than MAX_STARTS (20,000) starts, invalid-query for bad counts or lengths, and mismatched-slot-minutes for grids of different sizes.

Serve the file as text/calendar; charset=utf-8.

Everything above, plus TimeError with code: "invalid-zone" | "invalid-wall-time" | "nonexistent-time" | "ambiguous-time" | "invalid-instant" | "invalid-offset" | "invalid-slot-minutes" | "mismatched-slot-minutes" | "invalid-slot" | "invalid-window" | "invalid-query" | "invalid-region" | "invalid-event".

MIT