splitIntervalByUnitUnix

Signature

splitIntervalByUnitUnix(start: string | number, end: string | number, unit: string, amount: number, options?: { maxPieces?: number; epochUnit?: UnixUnit; timeZone?: string; }): { start: number; end: number; }[]

Split a Unix epoch interval into sub-intervals of amount × unit.

• Returns an array of half-open [start, end) records that tile the interval: each record’s end is the next record’s start and belongs only to that next record, so the pieces share no value and together cover [start, end) exactly once.
• The final sub-interval is trimmed so its end never exceeds the original end.
• Calendar-unit boundaries (years, months, weeks, days) are computed from start (start + k × amount), so month-end starts don’t drift: a monthly split from January 31 lands on February 29, March 31, April 30. Temporal’s add constrains a day the month lacks to the month’s last day, and stepping from that boundary would keep the shortened day (February 29, then March 29).
• Comparison: Luxon’s Interval.splitBy computes each boundary from the start the same way.
• Exact-unit boundaries (hours and smaller) step from the previous boundary. Exact units never clamp, and stepping keeps nanosecond precision where k × amount would pass Number.MAX_SAFE_INTEGER (boundaries are then floored to milliseconds).
• A calendar step that resolves to the same instant as the previous boundary (a deleted local day, such as 30 December 2011 in Pacific/Apia) is skipped, so no empty slice is produced. A step that goes backwards returns [].
• A step finer than epochUnit (500 milliseconds when the epochs are seconds, any microsecond or nanosecond step shorter than a millisecond) cannot be written in that unit: its boundaries floor to every whole unit from start to end, so the pieces are one epochUnit long and none is empty. maxPieces counts those pieces.
• Returns [{ start, end }] when start === end (zero-length interval).
• Returns [] on invalid input (start/end that is not a safe integer or numeric string of one — fractions, empty strings and values beyond ±(2^53 − 1) are invalid — unsupported unit, non-positive amount, an invalid epochUnit or an unknown timeZone).
• start and end are each a safe integer or a string of optionally negative ASCII digits.
• Accepts singular or plural units ("day" and "days" behave identically).
• A split into more than options.maxPieces slices returns [], decided from the span before stepping where it can be, and otherwise as soon as slice maxPieces + 1 is due.
• 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
start	string | number	Unix epoch in epochUnit — interval start
end	string | number	Unix epoch in epochUnit — interval end
unit	string	duration unit string — any DateTimeDurationUnit, singular or plural
amount	number	positive number of units per step

Options

options

optional: the limit on the number of slices, how the epochs are read and the zone calendar steps run in

Option	Type	Default	Description
maxPieces?	number	1_000_000	The most records the result may hold. A result that would hold more, or more than the longest possible array (2^32 - 1 elements), returns [] and none is built. A value that is not a positive safe integer also returns [].
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 []. The result is in the same unit.
timeZone?	string	"UTC"	The time zone the calendar arithmetic runs 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 [].

Returns

array of { start, end } records, or [] on invalid input

Members of each item

Member	Type	Description
start	number	The instant the interval begins at, as a Unix epoch number counted in epochUnit. A boundary that falls between two whole units is rounded down to the earlier one.
end	number	The first instant after the interval, counted in epochUnit and rounded as start is. It is exclusive: the interval holds everything from start up to but not including this value. It can equal start, which makes the interval empty.

Related types

• UnixUnit

Examples

import { splitIntervalByUnitUnix } from "@northguild/gmt/unix/interval";

splitIntervalByUnitUnix(0, 86400000, "hour", 6) // [{ start: 0, end: 21600000 }, { start: 21600000, end: 43200000 }, { start: 43200000, end: 64800000 }, { start: 64800000, end: 86400000 }]

startendunitamount

output

 

Source

unix/interval/splitIntervalByUnitUnix.ts