floorToZone

Signature

floorToZone(value: string, unit: SmallestUnit<ZoneBucketUnit>, timeZone: string): string

Floor an instant to the start of the unit containing it in timeZone, and return the instant of that boundary.

• Flooring a UTC instant to a UTC day and calling it a local day is wrong for most of the world for most of the day: 03:00 UTC on 15 June is still 14 June in New York, so the local day it belongs to started 20 hours before the UTC one did. The zone is an argument because GMT has no ambient one and must not acquire one.
• unit is "hour", "day", "week" or "month", or its plural ("days"), as Temporal accepts. Weeks start on Monday (ISO 8601), matching startOfZoned and intervalCountZoned. isValidZoneBucketUnit narrows a candidate unit, singular or plural, so a unit out of config can be told apart from a bad instant.
• value is any instant isValidInstant accepts — Z, an offset, or a bracketed zone. Only its instant is read: a bracketed zone in value is not the zone the boundary is computed in, timeZone is, and the two may differ freely. An offset written to the minute that is the bracketed zone’s sub-minute offset rounded (-00:45[Africa/Monrovia], for −00:44:30) names the instant the zone gives, as isValidInstant describes.
• The boundary is a real instant in the zone, so it survives the days a local boundary does not exist: a local day whose midnight is skipped by a spring-forward starts at 01:00, and a wall hour repeated by a fall-back floors to whichever pass value was in.
• Returns a UTC instant string ending in "Z", exactly — no rounding.
• Returns "" on invalid input, and where the boundary itself is not representable — the week or month containing the first instant Temporal supports began before it.
• Limit at an offset with seconds. The instant is placed in the offset’s whole-minute zone, moved by its seconds, and the moved instant must be inside Temporal’s range. So within the offset’s seconds (under a minute) of the last instant Temporal supports (+275760-09-13T00:00:00Z) for an offset east of UTC, or of the first (-271821-04-20T00:00:00Z) for one west, this returns "". An offset to the minute has no such limit.

Parameters

Parameter	Type	Description
value	string	ISO 8601 instant string (e.g. “2024-06-15T03:00:00Z”)
unit	SmallestUnit<ZoneBucketUnit>	boundary unit (“hour” | “day” | “week” | “month”, or its plural)
timeZone	string	IANA name or UTC offset the boundary is computed in: a time zone identifier (+05:30, +0530, -08) or a stored offset (±HH:MM[:SS], what getTimeZoneOffset returns)

Returns

UTC instant string ending in “Z”, or "" on invalid input

Related types

• ZoneBucketUnit

Examples

import { floorToZone } from "@northguild/gmt/calendar/calculate";

floorToZone("2024-06-15T03:00:00Z", "day", "America/New_York") // "2024-06-14T04:00:00Z" (the 14 June local midnight — the instant is already 14 June there)

value

output

 

Source

calendar/calculate/floorToZone.ts