areUnixEqualBy

Signature

areUnixEqualBy(value1: string | number, value2: string | number, unit: DateTimeUnit | PluralUnit<DateTimeUnit>, options?: { epochUnit?: UnixUnit; timeZone?: string; weekStartsOn?: "monday" | "sunday"; }): boolean

Compare two Unix epoch values for equality at a given unit.

• Both values are resolved to the start of unit in options.timeZone before comparison, so "day" compares calendar days in that zone, not raw epoch buckets.
• The start of unit is the real local bucket (see startOfUnix), so two epochs are equal only when they fall in the same bucket — including one a zone transition shortened, like Pacific/Chatham’s 15-minute 03:00 hour on its 2024 spring-forward.
• "month" requires the same month AND year, matching areDateTimesEqualBy.
• Each value is a safe integer or a string of optionally negative ASCII digits; unit may be singular or plural.
• Returns false for an unsupported unit (including "quarter") or invalid input. Mapping from date-fns:
• isSameDay(a, b) → areUnixEqualBy(a, b, "day")
• isSameMonth(a, b) → areUnixEqualBy(a, b, "month")
• isSameYear(a, b) → areUnixEqualBy(a, b, "year")
• 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 false. There false is the sentinel, not a comparison. An offset to the minute has no such limit.

Parameters

Parameter	Type	Description
value1	string | number	first Unix epoch: a safe integer or a digit string
value2	string | number	second Unix epoch, in the same unit
unit	DateTimeUnit | PluralUnit<DateTimeUnit>	Temporal.DateUnit | Temporal.TimeUnit to compare by

Options

options

optional: how both epochs are read, the zone the unit is found in and the first day of the week

Option	Type	Default	Description
epochUnit?	"seconds" | "milliseconds" | "second" | "millisecond" (UnixUnit)	"milliseconds"	The unit the epoch values are counted in: "seconds" or "milliseconds", singular or plural. Any other value returns false.
timeZone?	string	"UTC"	The time zone the unit boundaries are found in: an IANA name, a UTC offset (a time zone identifier such as +05:30, +0530 or -08, or a stored offset ±HH:MM[:SS], what getTimeZoneOffset returns), or "local" for the system time zone. An unknown zone returns false.
weekStartsOn?	"monday" | "sunday"	"monday"	The first day of the week, which sets where a "week" unit starts. "monday" is the ISO 8601 week, Monday to Sunday; "sunday" runs Sunday to Saturday. Any other value returns false, whatever the unit.

Returns

true if both values share the same start-of-unit boundary, false on an unsupported unit or invalid input

Related types

• UnixUnit

Examples

import { areUnixEqualBy } from "@northguild/gmt/unix/compare";

areUnixEqualBy(1710498000000, 1710503000000, "day", { timeZone: "UTC" }) // true (both fall on 2024-03-15 in UTC)

value1value2

output

 

Source

unix/compare/areUnixEqualBy.ts