Duration
intervalToDuration
Calculates a human-readable duration between two UTC timestamps, expressed as calendar components (years, months, days … milliseconds) in the specified timezone.
Internally the function converts both instants to Calendar structures in
the target zone and then delegates the heavy-lifting to
.
The sign of the interval does not matter – if start is after end
the arguments are swapped so the returned duration is always positive.
import { intervalToDuration } from "datezone";
const start = Date.UTC(2020, 0, 1, 0, 0, 0, 0); // 2020-01-01T00:00:00.000Z
const end = Date.UTC(2021, 1, 2, 3, 4, 5, 6); // 2021-02-02T03:04:05.006Z
const duration = intervalToDuration(start, end, "UTC");
console.log(duration);
// {
// year: 1,
// month: 1,
// day: 1,
// hour: 3,
// minute: 4,
// second: 5,
// millisecond: 6
// }
intervalToDurationBase
Low-level counterpart to . Both arguments MUST be
in the same timezone context – normally produced with
timestampToCalendar.
It performs a calendar subtraction using a classic borrow-chain so that the result components are always non-negative.
import { intervalToDurationBase } from "datezone";
const start = {
day: 1,
hour: 0,
millisecond: 0,
minute: 0,
month: 1,
second: 0,
year: 2020,
};
const end = {
day: 2,
hour: 3,
millisecond: 6,
minute: 4,
month: 2,
second: 5,
year: 2021,
};
const duration = intervalToDurationBase(start, end);
console.log(duration);
// {
// year: 1,
// month: 1,
// day: 1,
// hour: 3,
// minute: 4,
// second: 5,
// millisecond: 6
// }
areIntervalsOverlapping
Checks whether two half-open intervals overlap.
Mathematically the function answers whether
[start1, end1) ∩ [start2, end2) ≠ ∅.
Border-touching intervals (e.g. end1 == start2) are not considered an
overlap.
import { areIntervalsOverlapping } from "datezone";
// Check if two intervals [0, 10) and [5, 15) overlap
const overlap = areIntervalsOverlapping(0, 10, 5, 15);
console.log(overlap); // true
// Check if two intervals [0, 5) and [5, 10) overlap (touching but not overlapping)
const noOverlap = areIntervalsOverlapping(0, 5, 5, 10);
console.log(noOverlap); // false
clamp
Restricts a numeric value to the [min, max] range.
Equivalent to Math.min(Math.max(value, min), max) but without the extra
function calls.
import { clamp } from "datezone";
console.log(clamp(-5, 0, 10)); // 0
console.log(clamp(15, 0, 10)); // 10
console.log(clamp(7, 0, 10)); // 7