datetime-lube 1.0.0

package/src/add.js

@@ -0,0 +1,148 @@
+import { last_day } from "./calendar.js"
+import time_of from "./time_of.js"
+import { check_zone, date_of, fields_of } from "./zone.js"
+/** @type {Map<string, (number | string)[]>} */
+const durations = new Map()
+const duration_regex = /([+-]?\d+)(sss|[YMWDHms])/g
+/** @type {Record<string, number | undefined>} */
+const unit_ms = {
+	H: 3600000,
+	m: 60000,
+	s: 1000,
+	sss: 1
+}
+/**
+ * @param {Date} date
+ * @param {number} months
+ * @param {string=} zone
+ * @returns {Date}
+ */
+function add_months(date, months, zone) {
+	if (zone === undefined) {
+		const month = date.getMonth() + months
+		const year = date.getFullYear() + Math.floor(month / 12)
+		const rest = (month % 12 + 12) % 12
+		const result = new Date(date.getTime())
+		result.setFullYear(
+			year,
+			rest,
+			Math.min(
+				date.getDate(),
+				last_day(year, rest)
+			)
+		)
+		return result
+	}
+	const fields = fields_of(date, zone)
+	const month = /** @type {number} */(fields[1])/**/ + months
+	const year = /** @type {number} */(fields[0])/**/ + Math.floor(month / 12)
+	const rest = (month % 12 + 12) % 12
+	fields[0] = year
+	fields[1] = rest
+	fields[2] = Math.min(
+		/** @type {number} */(fields[2])/**/,
+		last_day(year, rest)
+	)
+	return date_of(fields, zone)
+}
+/**
+ * @param {string} sum
+ * @returns {(number | string)[]}
+ */
+function compile(sum) {
+	let steps = durations.get(sum)
+	if (steps) return steps
+	steps = []
+	if (!/\S/.test(sum) || /\S/.test(
+		sum.replace(duration_regex, "")
+	)) throw new RangeError(
+		`add: Invalid duration "${String(sum)}"`
+	)
+	for (const [ , value = "", unit = "" ] of sum.matchAll(duration_regex)) {
+		if (!+value) continue
+		if (unit == "W") steps.push("D", +value * 7)
+		else steps.push(unit, +value)
+	}
+	if (durations.size >= 1000) durations.clear()
+	durations.set(sum, steps)
+	return steps
+}
+/**
+ * Calculates and adds the specified time duration to the provided date and returns a new Date.
+ * Years and months are clamped to the end of the month, e.g. Jan 31 + 1M is Feb 28 or 29.
+ * Days follow the clock, so a day over a daylight saving change is 23 or 25 hours,
+ * while hours, minutes, seconds and milliseconds are elapsed time.
+ * A part of zero adds nothing; any other part of years, months, weeks or days lands on a clock time,
+ * which moves forward out of a daylight saving gap and takes the first occurrence of an hour that repeats.
+ * @param {Date} date
+ * @param {string} sum
+ * ```
+ * e.g. "1Y2M 3D"
+ * ```
+ *
+ * Supported time units:
+ * - "Y": Years
+ * - "M": Months
+ * - "W": Weeks
+ * - "D": Days
+ * - "H": Hours
+ * - "m": Minutes
+ * - "s": Seconds
+ * - "sss": Milliseconds
+ * @param {import("../public.js").TimeZone=} zone
+ * @returns {Date}
+ * @throws
+ * ```
+ * RangeError(`add: Invalid duration "${sum}"`) // sum is empty, or a part of it is not a number followed by a unit
+ * RangeError(`add: Invalid time zone "${zone}"`) // Intl.DateTimeFormat rejects the zone
+ * TypeError(`add: Expected a Date, got ${typeof date}`)
+ * ```
+ * @example add(new Date, "-1D") //=> Date { yesterday }
+ */
+export default function(date, sum, zone) {
+	const time = time_of("add", date)
+	const steps = compile(sum)
+	check_zone("add", zone)
+	const result = new Date(time)
+	if (isNaN(time)) return result
+	if (zone === undefined) {
+		for (let i = 0; i < steps.length; i += 2) {
+			const unit = /** @type {string} */(steps[i])/**/
+			const value = /** @type {number} */(steps[i + 1])/**/
+			const ms = unit_ms[unit]
+			if (ms) result.setTime(result.getTime() + value * ms)
+			else if (unit == "D") result.setDate(result.getDate() + value)
+			else result.setTime(
+				add_months(
+					result,
+					unit == "Y"
+						? value * 12
+						: value
+				).getTime()
+			)
+		}
+		return result
+	}
+	let shifted = result
+	for (let i = 0; i < steps.length; i += 2) {
+		const unit = /** @type {string} */(steps[i])/**/
+		const value = /** @type {number} */(steps[i + 1])/**/
+		const ms = unit_ms[unit]
+		if (ms) {
+			shifted = new Date(shifted.getTime() + value * ms)
+		} else if (unit == "D") {
+			const fields = fields_of(shifted, zone)
+			fields[2] = /** @type {number} */(fields[2])/**/ + value
+			shifted = date_of(fields, zone)
+		} else {
+			shifted = add_months(
+				shifted,
+				unit == "Y"
+					? value * 12
+					: value,
+				zone
+			)
+		}
+	}
+	return shifted
+}

package/src/calendar.js

@@ -0,0 +1,88 @@
+const month_days = [ 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 ]
+/**
+ * @param {number} year
+ * @param {number} month
+ * @param {number} day
+ * @returns {number}
+ */
+function days_of(year, month, day) {
+	if (month < 0 || month > 11) {
+		year += Math.floor(month / 12)
+		month = (month % 12 + 12) % 12
+	}
+	if (month < 2) year--
+	const era = Math.floor(year / 400)
+	const yoe = year - era * 400
+	return era * 146097
+		+ yoe * 365
+		+ Math.floor(yoe / 4)
+		- Math.floor(yoe / 100)
+		+ Math.floor(
+			(153 * (month < 2 ? month + 10 : month - 2) + 2) / 5
+		)
+		+ day
+		- 719469
+}
+/**
+ * @param {number} wall
+ * @returns {number[]}
+ */
+function fields_of_wall(wall) {
+	const days = Math.floor(wall / 86400000)
+	let rest = wall - days * 86400000
+	const hour = Math.floor(rest / 3600000)
+	rest -= hour * 3600000
+	const minute = Math.floor(rest / 60000)
+	rest -= minute * 60000
+	const second = Math.floor(rest / 1000)
+	const z = days + 719468
+	const era = Math.floor(z / 146097)
+	const doe = z - era * 146097
+	const yoe = Math.floor(
+		(doe - Math.floor(doe / 1460) + Math.floor(doe / 36524) - Math.floor(doe / 146096)) / 365
+	)
+	const doy = doe - (365 * yoe + Math.floor(yoe / 4) - Math.floor(yoe / 100))
+	const mp = Math.floor((5 * doy + 2) / 153)
+	const month = mp < 10 ? mp + 2 : mp - 10
+	return [
+		yoe + era * 400 + (month < 2 ? 1 : 0),
+		month,
+		doy - Math.floor((153 * mp + 2) / 5) + 1,
+		hour,
+		minute,
+		second,
+		rest - second * 1000,
+		(days % 7 + 11) % 7
+	]
+}
+/**
+ * @param {number} year
+ * @param {number} month
+ * @returns {number}
+ */
+function last_day(year, month) {
+	return month == 1 && !(year % 4) && (year % 100 || !(year % 400))
+		? 29
+		: /** @type {number} */(month_days[month])/**/
+}
+/**
+ * @param {number[]} fields
+ * @returns {number}
+ */
+function wall_of_fields(fields) {
+	return days_of(
+		/** @type {number} */(fields[0])/**/,
+		/** @type {number} */(fields[1])/**/,
+		/** @type {number} */(fields[2])/**/
+	) * 86400000
+		+ /** @type {number} */(fields[3])/**/ * 3600000
+		+ /** @type {number} */(fields[4])/**/ * 60000
+		+ /** @type {number} */(fields[5])/**/ * 1000
+		+ /** @type {number} */(fields[6])/**/
+}
+export {
+	days_of,
+	fields_of_wall,
+	last_day,
+	wall_of_fields
+}

package/src/date_to_string.js

@@ -0,0 +1,106 @@
+import time_of from "./time_of.js"
+import { check_zone, fields_of } from "./zone.js"
+/** @type {Map<string, (string | number[])[]>} */
+const formats = new Map()
+const token_regex = /DD|HH|MM|YYYY|mm|sss?/g
+const year_token = [ 0, 4, 0 ]
+/** @type {Record<string, number[]>} */
+const tokens = {
+	DD: [ 2, 2, 0 ],
+	HH: [ 3, 2, 0 ],
+	MM: [ 1, 2, 1 ],
+	YYYY: year_token,
+	mm: [ 4, 2, 0 ],
+	ss: [ 5, 2, 0 ],
+	sss: [ 6, 3, 0 ]
+}
+/**
+ * @param {string} format
+ * @returns {(string | number[])[]}
+ */
+function compile(format) {
+	let parts = formats.get(format)
+	if (parts) return parts
+	parts = []
+	let last = 0
+	for (const { 0: token, index = 0 } of format.matchAll(token_regex)) {
+		if (index > last) parts.push(format.slice(last, index))
+		parts.push(
+			/** @type {number[]} */(tokens[token])/**/
+		)
+		last = index + token.length
+	}
+	if (last < format.length) parts.push(format.slice(last))
+	if (formats.size >= 1000) formats.clear()
+	formats.set(format, parts)
+	return parts
+}
+/**
+ * @param {number} value
+ * @param {number} length
+ * @returns {string}
+ */
+function pad(value, length) {
+	return String(value).padStart(length, "0")
+}
+/**
+ * @param {number} year
+ * @returns {string}
+ */
+function year_text(year) {
+	return year >= 0 && year <= 9999
+		? String(year).padStart(4, "0")
+		: (year < 0 ? "-" : "+") + String(Math.abs(year)).padStart(6, "0")
+}
+/**
+ * Converts a Date object to a formatted string representation.
+ * Letters that are not a time unit are kept as they are, so `"HHhmm"` gives `"11h22"`.
+ * A year before 0 or after 9999 is printed as an expanded year, such as `"+012345"`.
+ * @param {Date} date
+ * @param {string=} format
+ * ```js
+ * = "YYYY-MM-DDTHH:mm:ss.sss"
+ * ```
+ *
+ * Supported time units:
+ * - "YYYY": Years
+ * - "MM": Months
+ * - "DD": Days
+ * - "HH": Hours
+ * - "mm": Minutes
+ * - "ss": Seconds
+ * - "sss": Milliseconds
+ * @param {import("../public.js").TimeZone=} zone
+ * @returns {string}
+ * @throws
+ * ```
+ * RangeError(`dateToString: Invalid time zone "${zone}"`) // Intl.DateTimeFormat rejects the zone
+ * TypeError(`dateToString: Expected a Date, got ${typeof date}`)
+ * ```
+ * @example dateToString(new Date, "YYYY-MM-DD HH:mm", "Asia/Seoul") //=> "2024-07-15 21:00"
+ */
+export default function(
+	date,
+	format = "YYYY-MM-DDTHH:mm:ss.sss",
+	zone
+) {
+	const time = time_of("dateToString", date)
+	check_zone("dateToString", zone)
+	if (isNaN(time)) return "Invalid Date"
+	const fields = fields_of(date, zone)
+	const parts = compile(format)
+	let result = ""
+	for (const part of parts) {
+		result += typeof part == "string"
+			? part
+			: part === year_token
+				? year_text(
+					/** @type {number} */(fields[0])/**/
+				)
+				: pad(
+				/** @type {number} */(fields[/** @type {number} */(part[0])/**/])/**/ + /** @type {number} */(part[2])/**/,
+					/** @type {number} */(part[1])/**/
+				)
+	}
+	return result
+}

package/src/diff.js

@@ -0,0 +1,143 @@
+import { days_of, last_day, wall_of_fields } from "./calendar.js"
+import time_of from "./time_of.js"
+import { check_zone, date_of, fields_of } from "./zone.js"
+/** @type {Record<string, number | undefined>} */
+const unit_ms = {
+	H: 3600000,
+	m: 60000,
+	s: 1000,
+	sss: 1
+}
+const units_of = new Set(
+	[ "D", "H", "M", "W", "Y", "m", "s", "sss" ]
+)
+/**
+ * @param {number[]} from_fields
+ * @param {number} months
+ * @param {number} to_wall
+ * @param {number} end
+ * @param {string=} zone
+ * @returns {number}
+ */
+function anchor_after(
+	from_fields,
+	months,
+	to_wall,
+	end,
+	zone
+) {
+	const month = /** @type {number} */(from_fields[1])/**/ + months
+	const year = /** @type {number} */(from_fields[0])/**/ + Math.floor(month / 12)
+	const index = (month % 12 + 12) % 12
+	const fields = [
+		year,
+		index,
+		Math.min(
+			/** @type {number} */(from_fields[2])/**/,
+			last_day(year, index)
+		),
+		/** @type {number} */(from_fields[3])/**/,
+		/** @type {number} */(from_fields[4])/**/,
+		/** @type {number} */(from_fields[5])/**/,
+		/** @type {number} */(from_fields[6])/**/
+	]
+	const distance = wall_of_fields(fields) - to_wall
+	if (Math.abs(distance) >= 172800000) return distance
+	const time = date_of(fields, zone).getTime()
+	return isNaN(time)
+		? distance
+		: time - end
+}
+/**
+ * Counts the whole units from one date to another, negative when the second date is earlier.
+ * Years, months, weeks and days follow the clock, so a day over a daylight saving change still
+ * counts as one day, while hours, minutes, seconds and milliseconds are elapsed time.
+ * @param {Date} from
+ * @param {Date} to
+ * @param {import("../public.js").Unit} unit
+ * ```
+ * "Y" | "M" | "W" | "D" | "H" | "m" | "s" | "sss"
+ * ```
+ * @param {import("../public.js").TimeZone=} zone
+ * @returns {number}
+ * @throws
+ * ```
+ * RangeError(`diff: Invalid unit "${unit}"`) // The unit is not one of the listed ones
+ * RangeError(`diff: Invalid time zone "${zone}"`) // Intl.DateTimeFormat rejects the zone
+ * TypeError(`diff: Expected a Date, got ${typeof from}`) // from or to is not a Date
+ * ```
+ * @example diff(start, end, "D") //=> 30
+ */
+export default function(from, to, unit, zone) {
+	const start = time_of("diff", from)
+	const end = time_of("diff", to)
+	if (!units_of.has(unit)) throw new RangeError(
+		`diff: Invalid unit "${String(unit)}"`
+	)
+	check_zone("diff", zone)
+	if (isNaN(start) || isNaN(end)) return NaN
+	const ms = unit_ms[unit]
+	if (ms) return Math.trunc((end - start) / ms) + 0
+	const from_fields = fields_of(from, zone)
+	const to_fields = fields_of(to, zone)
+	if (unit == "D" || unit == "W") {
+		const days = days_of(
+			/** @type {number} */(to_fields[0])/**/,
+			/** @type {number} */(to_fields[1])/**/,
+			/** @type {number} */(to_fields[2])/**/
+		) - days_of(
+			/** @type {number} */(from_fields[0])/**/,
+			/** @type {number} */(from_fields[1])/**/,
+			/** @type {number} */(from_fields[2])/**/
+		)
+		return unit == "D"
+			? days
+			: Math.trunc(days / 7) + 0
+	}
+	let months = (/** @type {number} */(to_fields[0])/**/ - /** @type {number} */(from_fields[0])/**/) * 12
+		+ /** @type {number} */(to_fields[1])/**/ - /** @type {number} */(from_fields[1])/**/
+	const to_day = /** @type {number} */(to_fields[2])/**/
+	const from_day = /** @type {number} */(from_fields[2])/**/
+	if (Math.abs(to_day - from_day) > 2 && to_day < 27 && from_day < 27) {
+		if (months > 0 && to_day < from_day) months--
+		else if (months < 0 && to_day > from_day) months++
+	} else {
+		const to_wall = wall_of_fields(to_fields)
+		if (end >= start) {
+			months = Math.max(months, 0)
+			while (months && anchor_after(
+				from_fields,
+				months,
+				to_wall,
+				end,
+				zone
+			) > 0) months--
+			if (anchor_after(
+				from_fields,
+				months + 1,
+				to_wall,
+				end,
+				zone
+			) <= 0) months++
+		} else {
+			months = Math.min(months, 0)
+			while (months && anchor_after(
+				from_fields,
+				months,
+				to_wall,
+				end,
+				zone
+			) < 0) months++
+			if (anchor_after(
+				from_fields,
+				months - 1,
+				to_wall,
+				end,
+				zone
+			) >= 0) months--
+		}
+	}
+	return unit == "Y"
+		? Math.trunc(months / 12) + 0
+		: months
+}

package/src/end_of.js

@@ -0,0 +1,118 @@
+import {
+	days_of,
+	fields_of_wall,
+	last_day,
+	wall_of_fields
+} from "./calendar.js"
+import time_of from "./time_of.js"
+import {
+	check_zone,
+	end_at,
+	instant_of,
+	offset_in,
+	offset_of,
+	unit_end
+} from "./zone.js"
+/** @type {Record<string, number | undefined>} */
+const unit_ms = { H: 3600000, m: 60000, s: 1000 }
+/** @type {Record<string, number>} */
+const units = { D: 3, M: 2, W: 3, Y: 1 }
+const units_of = new Set(
+	[ "D", "H", "M", "W", "Y", "m", "s" ]
+)
+/**
+ * Returns a new Date at the last millisecond of the given unit, such as 23:59:59.999 of the day.
+ * A week ends on Sunday, as in ISO 8601.
+ * @param {Date} date
+ * @param {Exclude<import("../public.js").Unit, "sss">} unit
+ * ```
+ * "Y" | "M" | "W" | "D" | "H" | "m" | "s"
+ * ```
+ * @param {import("../public.js").TimeZone=} zone
+ * @returns {Date}
+ * @throws
+ * ```
+ * RangeError(`endOf: Invalid unit "${unit}"`) // The unit is not one of the listed ones
+ * RangeError(`endOf: Invalid time zone "${zone}"`) // Intl.DateTimeFormat rejects the zone
+ * TypeError(`endOf: Expected a Date, got ${typeof date}`)
+ * ```
+ * @example endOf(new Date, "M") //=> Date { last millisecond of this month }
+ */
+export default function(date, unit, zone) {
+	const time = time_of("endOf", date)
+	if (!units_of.has(unit)) throw new RangeError(
+		`endOf: Invalid unit "${String(unit)}"`
+	)
+	check_zone("endOf", zone)
+	if (isNaN(time)) return new Date(NaN)
+	const ms = unit_ms[unit]
+	if (ms) {
+		if (zone !== undefined) {
+			const offset = offset_of(time, zone)
+			const rest = ms - ((time + offset) % ms + ms) % ms
+			return new Date(
+				offset_of(time + rest - 1, zone) == offset
+					? time + rest - 1
+					: unit_end(time, ms, zone)
+			)
+		}
+		const rest = ms - (
+			ms > 60000
+				? date.getMinutes() * 60000 + date.getSeconds() * 1000 + date.getMilliseconds()
+				: ms > 1000
+					? date.getSeconds() * 1000 + date.getMilliseconds()
+					: date.getMilliseconds()
+		)
+		const result = new Date(time + rest - 1)
+		if (
+			result.getTimezoneOffset() == date.getTimezoneOffset()
+			&& result.getSeconds() == (ms > 1000 ? 59 : date.getSeconds())
+		) return result
+		result.setTime(unit_end(time, ms))
+		return result
+	}
+	const from = /** @type {number} */(units[unit])/**/
+	let end = time
+	if (zone === undefined) {
+		const result = new Date(time)
+		result.setHours(
+			unit == "D"
+				? 24
+				: unit == "W"
+					? 168 - 24 * ((result.getDay() + 6) % 7)
+					: unit == "M"
+						? 24 * (last_day(
+							result.getFullYear(),
+							result.getMonth()
+						) - result.getDate() + 1)
+						: 24 * (days_of(result.getFullYear() + 1, 0, 1) - days_of(
+							result.getFullYear(),
+							result.getMonth(),
+							result.getDate()
+						)),
+			0,
+			0,
+			0
+		)
+		end = result.getTime() - 1
+		if (end >= time && !(result.getHours() || result.getMinutes() || result.getSeconds())) {
+			result.setTime(end)
+			return result
+		}
+	}
+	const offset = offset_in(time, zone)
+	const fields = fields_of_wall(time + offset)
+	if (unit == "W") fields[2] = /** @type {number} */(fields[2])/**/ + 7 - (/** @type {number} */(fields[7])/**/ + 6) % 7
+	else fields[from - 1] = /** @type {number} */(fields[from - 1])/**/ + 1
+	for (let i = from; i < 7; i++) fields[i] = i == 2 ? 1 : 0
+	const wall = wall_of_fields(fields)
+	if (zone !== undefined) {
+		const next = offset_of(wall - offset, zone)
+		if (
+			next == offset
+			|| wall - next > time && offset_of(wall - next, zone) == next
+		) return new Date(wall - next - 1)
+		end = instant_of(wall, zone) - 1
+	}
+	return new Date(end_at(wall, end, time, zone))
+}

package/src/index.js

@@ -0,0 +1,8 @@
+export { default as add } from "./add.js"
+export { default as dateToString } from "./date_to_string.js"
+export { default as diff } from "./diff.js"
+export { default as endOf } from "./end_of.js"
+export { default as startOf } from "./start_of.js"
+export { default as stringToDate } from "./string_to_date.js"
+export { default as timeUnit } from "./time_unit.js"
+export { default as timeZoneOffset } from "./time_zone_offset.js"