@alexstukovnikov/oz-time 1.0.0 → 1.0.1

package/src/modules/interval.js

@@ -0,0 +1,190 @@
+import { OzTime } from '../core/core.js';
+import { normalizeUnit, isFixedUnit, unitToMilliseconds } from '../utils/units.js';
+
+/**
+ * Модуль интервалов времени.
+ *
+ * @module modules/interval
+ */
+
+/**
+ * Проверяет, является ли значение экземпляром OzTime.
+ *
+ * @private
+ * @param {*} value - Проверяемое значение.
+ * @param {string} name - Имя параметра.
+ * @throws {TypeError} Выбрасывается, если значение не является экземпляром OzTime.
+ * @returns {void}
+ */
+function assertOzTime(value, name) {
+    if (!(value instanceof OzTime)) {
+        throw new TypeError(`${name} must be OzTime`);
+    }
+}
+
+/**
+ * Представляет замкнутый интервал между двумя значениями времени.
+ *
+ * @class
+ * @example
+ * import { Interval, fromISO } from '@alexstukovnikov/oz-time';
+ *
+ * const start = fromISO('2024-05-25T10:00:00Z');
+ * const end = fromISO('2024-05-25T12:00:00Z');
+ * const range = new Interval(start, end);
+ * console.log(range.contains(fromISO('2024-05-25T11:00:00Z'))); // ожидаемый результат: true
+ */
+export class Interval {
+    /**
+     * Создаёт новый экземпляр Interval.
+     *
+     * @param {OzTime} start - Начало интервала.
+     * @param {OzTime} end - Конец интервала.
+     * @throws {TypeError} Выбрасывается, если start или end не являются экземплярами OzTime.
+     * @throws {RangeError} Выбрасывается, если start больше end.
+     */
+    constructor(start, end) {
+        assertOzTime(start, 'start');
+        assertOzTime(end, 'end');
+
+        if (start.getTimestamp() > end.getTimestamp()) {
+            throw new RangeError('Interval: start must be before or equal to end');
+        }
+
+        this._start = start;
+        this._end = end;
+    }
+
+    /**
+     * Возвращает начало интервала.
+     *
+     * @returns {OzTime} Начальная граница интервала.
+     * @example
+     * import { Interval, fromISO } from '@alexstukovnikov/oz-time';
+     *
+     * const range = new Interval(
+     *   fromISO('2024-05-25T10:00:00Z'),
+     *   fromISO('2024-05-25T12:00:00Z')
+     * );
+     * console.log(range.getStart().toISOString()); // ожидаемый результат: 2024-05-25T10:00:00.000Z
+     */
+    getStart() {
+        return this._start;
+    }
+
+    /**
+     * Возвращает конец интервала.
+     *
+     * @returns {OzTime} Конечная граница интервала.
+     * @example
+     * import { Interval, fromISO } from '@alexstukovnikov/oz-time';
+     *
+     * const range = new Interval(
+     *   fromISO('2024-05-25T10:00:00Z'),
+     *   fromISO('2024-05-25T12:00:00Z')
+     * );
+     * console.log(range.getEnd().toISOString()); // ожидаемый результат: 2024-05-25T12:00:00.000Z
+     */
+    getEnd() {
+        return this._end;
+    }
+
+    /**
+     * Проверяет, содержит ли интервал переданное значение времени.
+     *
+     * @param {OzTime} moment - Проверяемое значение.
+     * @throws {TypeError} Выбрасывается, если moment не является экземпляром OzTime.
+     * @returns {boolean} `true`, если значение входит в интервал.
+     * @example
+     * import { Interval, fromISO } from '@alexstukovnikov/oz-time';
+     *
+     * const range = new Interval(
+     *   fromISO('2024-05-25T10:00:00Z'),
+     *   fromISO('2024-05-25T12:00:00Z')
+     * );
+     * console.log(range.contains(fromISO('2024-05-25T11:00:00Z'))); // ожидаемый результат: true
+     */
+    contains(moment) {
+        assertOzTime(moment, 'moment');
+
+        const ts = moment.getTimestamp();
+        return ts >= this._start.getTimestamp() && ts <= this._end.getTimestamp();
+    }
+
+    /**
+     * Проверяет, пересекается ли текущий интервал с другим интервалом.
+     *
+     * @param {Interval} other - Второй интервал.
+     * @throws {TypeError} Выбрасывается, если other не является экземпляром Interval.
+     * @returns {boolean} `true`, если интервалы пересекаются.
+     * @example
+     * import { Interval, fromISO } from '@alexstukovnikov/oz-time';
+     *
+     * const a = new Interval(
+     *   fromISO('2024-05-25T10:00:00Z'),
+     *   fromISO('2024-05-25T12:00:00Z')
+     * );
+     * const b = new Interval(
+     *   fromISO('2024-05-25T11:00:00Z'),
+     *   fromISO('2024-05-25T13:00:00Z')
+     * );
+     * console.log(a.overlaps(b)); // ожидаемый результат: true
+     */
+    overlaps(other) {
+        if (!(other instanceof Interval)) {
+            throw new TypeError('other must be Interval');
+        }
+
+        const startA = this._start.getTimestamp();
+        const endA = this._end.getTimestamp();
+        const startB = other.getStart().getTimestamp();
+        const endB = other.getEnd().getTimestamp();
+
+        return startA <= endB && startB <= endA;
+    }
+
+    /**
+     * Возвращает длительность интервала в фиксированной единице времени.
+     *
+     * @param {string} [unit='millisecond'] - Фиксированная единица времени.
+     * @throws {Error} Выбрасывается, если unit не является фиксированной единицей времени.
+     * @returns {number} Длительность интервала в указанной единице.
+     * @example
+     * import { Interval, fromISO } from '@alexstukovnikov/oz-time';
+     *
+     * const range = new Interval(
+     *   fromISO('2024-05-25T10:00:00Z'),
+     *   fromISO('2024-05-25T12:00:00Z')
+     * );
+     * console.log(range.duration('hour')); // ожидаемый результат: 2
+     */
+    duration(unit = 'millisecond') {
+        const normalizedUnit = normalizeUnit(unit);
+
+        if (!isFixedUnit(normalizedUnit)) {
+            throw new Error(`Interval.duration supports only fixed units: ${unit}`);
+        }
+
+        const diffMs = this._end.getTimestamp() - this._start.getTimestamp();
+        return diffMs / unitToMilliseconds(normalizedUnit);
+    }
+}
+
+/**
+ * Создаёт и возвращает экземпляр {@link Interval}.
+ *
+ * @param {OzTime} start - Начало интервала.
+ * @param {OzTime} end - Конец интервала.
+ * @returns {Interval} Новый экземпляр Interval.
+ * @example
+ * import { interval, fromISO } from '@alexstukovnikov/oz-time';
+ *
+ * const range = interval(
+ *   fromISO('2024-05-25T10:00:00Z'),
+ *   fromISO('2024-05-25T12:00:00Z')
+ * );
+ * console.log(range.duration('hour')); // ожидаемый результат: 2
+ */
+export function interval(start, end) {
+    return new Interval(start, end);
+}

package/src/modules/timezone.js

@@ -0,0 +1,112 @@
+import { OzTime } from '../core/core.js';
+
+/**
+ * Модуль для работы с часовыми поясами.
+ *
+ * @module modules/timezone
+ */
+
+/**
+ * Проверяет корректность идентификатора часового пояса.
+ *
+ * @private
+ * @param {string} timezone - Идентификатор часового пояса в формате IANA.
+ * @throws {TypeError} Выбрасывается, если timezone пустой или не является строкой.
+ * @throws {Error} Выбрасывается, если timezone не поддерживается.
+ * @returns {void}
+ */
+function validateTimezone(timezone) {
+    if (typeof timezone !== 'string' || timezone.trim() === '') {
+        throw new TypeError('setTimezone: timezone must be a non-empty string');
+    }
+
+    if (!Intl.supportedValuesOf('timeZone').includes(timezone)) {
+        throw new Error(`Unsupported timezone: ${timezone}`);
+    }
+}
+
+/**
+ * Вычисляет смещение часового пояса относительно UTC для конкретного timestamp.
+ *
+ * @private
+ * @param {number} timestamp - Unix timestamp в миллисекундах.
+ * @param {string} timeZone - Часовой пояс в формате IANA.
+ * @returns {number} Смещение в минутах относительно UTC.
+ */
+function getOffsetMinutesFor(timestamp, timeZone) {
+    const date = new Date(timestamp);
+
+    const formatter = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+    });
+
+    const parts = formatter.formatToParts(date);
+    const lookup = Object.fromEntries(parts.map((p) => [p.type, p.value]));
+
+    const year = Number(lookup.year);
+    const month = Number(lookup.month);
+    const day = Number(lookup.day);
+    const hour = Number(lookup.hour);
+    const minute = Number(lookup.minute);
+    const second = Number(lookup.second);
+
+    const utcTimestamp = Date.UTC(year, month - 1, day, hour, minute, second);
+
+    return (utcTimestamp - timestamp) / 60000;
+}
+
+/**
+ * Возвращает новый экземпляр {@link OzTime} с тем же timestamp и locale,
+ * но с другим часовым поясом.
+ *
+ * Абсолютный момент времени при этом не изменяется.
+ *
+ * @param {OzTime} time - Исходный экземпляр {@link OzTime}.
+ * @param {string} timezone - Новый часовой пояс в формате IANA.
+ * @throws {TypeError} Выбрасывается, если первый аргумент не является экземпляром OzTime или timezone некорректен.
+ * @throws {Error} Выбрасывается, если timezone не поддерживается.
+ * @returns {OzTime} Новый экземпляр OzTime с другим часовым поясом.
+ * @example
+ * import { setTimezone, fromISO } from '@alexstukovnikov/oz-time';
+ *
+ * const time = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
+ * const moscow = setTimezone(time, 'Europe/Moscow');
+ * console.log(moscow.getTimezone()); // ожидаемый результат: Europe/Moscow
+ */
+export function setTimezone(time, timezone) {
+    if (!(time instanceof OzTime)) {
+        throw new TypeError('tz: first argument must be OzTime');
+    }
+
+    validateTimezone(timezone);
+
+    return new OzTime(time.getTimestamp(), timezone, time.getLocale());
+}
+
+/**
+ * Возвращает смещение часового пояса экземпляра относительно UTC в минутах.
+ *
+ * @param {OzTime} time - Экземпляр времени.
+ * @throws {TypeError} Выбрасывается, если аргумент не является экземпляром OzTime.
+ * @returns {number} Смещение в минутах относительно UTC.
+ * @example
+ * import { getTimezoneOffset, fromISO } from '@alexstukovnikov/oz-time';
+ *
+ * const time = fromISO('2024-05-25T12:00:00Z', 'Europe/Moscow', 'ru-RU');
+ * console.log(getTimezoneOffset(time)); // ожидаемый результат: 180
+ */
+export function getTimezoneOffset(time) {
+    if (!(time instanceof OzTime)) {
+        throw new TypeError('getTimezoneOffset: argument must be OzTime');
+    }
+    const timestamp = time.getTimestamp();
+    const timeZone = time.getTimezone();
+    return getOffsetMinutesFor(timestamp, timeZone);
+}

package/src/utils/calendar.js

@@ -0,0 +1,277 @@
+import { normalizeUnit, isFixedUnit, unitToMilliseconds } from './units.js';
+import { OzTime } from '../core/core.js';
+
+/**
+ * Календарные утилиты для работы с датами, високосными годами
+ * и разницей между значениями времени.
+ *
+ * @module utils/calendar
+ */
+
+/**
+ * Проверяет корректность timestamp.
+ *
+ * @private
+ * @param {number} timestamp - Unix timestamp в миллисекундах.
+ * @param {string} name - Имя вызывающей функции.
+ * @throws {TypeError} Выбрасывается, если timestamp некорректен.
+ * @returns {void}
+ */
+function assertValidTimestamp(timestamp, name) {
+    if (typeof timestamp !== 'number' || Number.isNaN(timestamp)) {
+        throw new TypeError(`${name}: timestamp must be a valid number`);
+    }
+}
+
+/**
+ * Проверяет корректность количества единиц времени.
+ *
+ * @private
+ * @param {number} amount - Количество единиц времени.
+ * @param {string} name - Имя вызывающей функции.
+ * @throws {TypeError} Выбрасывается, если amount некорректен.
+ * @returns {void}
+ */
+function assertValidAmount(amount, name) {
+    if (typeof amount !== 'number' || Number.isNaN(amount)) {
+        throw new TypeError(`${name}: amount must be a valid number`);
+    }
+}
+
+/**
+ * Проверяет, является ли значение экземпляром OzTime.
+ *
+ * @private
+ * @param {*} value - Проверяемое значение.
+ * @param {string} name - Имя параметра.
+ * @throws {TypeError} Выбрасывается, если значение не является экземпляром OzTime.
+ * @returns {void}
+ */
+function assertOzTime(value, name) {
+    if (!(value instanceof OzTime)) {
+        throw new TypeError(`${name} must be OzTime`);
+    }
+}
+
+/**
+ * Вычисляет календарную разницу в месяцах между двумя timestamp.
+ *
+ * @private
+ * @param {number} leftTimestamp - Левый timestamp.
+ * @param {number} rightTimestamp - Правый timestamp.
+ * @returns {number} Разница в месяцах.
+ */
+function diffInMonths(leftTimestamp, rightTimestamp) {
+    const left = new Date(leftTimestamp);
+    const right = new Date(rightTimestamp);
+
+    let months = (left.getUTCFullYear() - right.getUTCFullYear()) * 12 + (left.getUTCMonth() - right.getUTCMonth());
+
+    const leftDay = left.getUTCDate();
+    const rightDay = right.getUTCDate();
+
+    if (months > 0 && leftDay < rightDay) {
+        months -= 1;
+    } else if (months < 0 && leftDay > rightDay) {
+        months += 1;
+    }
+
+    return months;
+}
+
+/**
+ * Вычисляет календарную разницу в годах между двумя timestamp.
+ *
+ * @private
+ * @param {number} leftTimestamp - Левый timestamp.
+ * @param {number} rightTimestamp - Правый timestamp.
+ * @returns {number} Разница в годах.
+ */
+function diffInYears(leftTimestamp, rightTimestamp) {
+    const left = new Date(leftTimestamp);
+    const right = new Date(rightTimestamp);
+
+    let years = left.getUTCFullYear() - right.getUTCFullYear();
+
+    const leftMonth = left.getUTCMonth();
+    const rightMonth = right.getUTCMonth();
+    const leftDay = left.getUTCDate();
+    const rightDay = right.getUTCDate();
+
+    if (years > 0 && (leftMonth < rightMonth || (leftMonth === rightMonth && leftDay < rightDay))) {
+        years -= 1;
+    } else if (years < 0 && (leftMonth > rightMonth || (leftMonth === rightMonth && leftDay > rightDay))) {
+        years += 1;
+    }
+
+    return years;
+}
+
+/**
+ * Проверяет, является ли год високосным по григорианскому календарю.
+ *
+ * @param {number} year - Год.
+ * @throws {TypeError} Выбрасывается, если year не является целым числом.
+ * @returns {boolean} `true`, если год високосный.
+ * @example
+ * import { isLeapYear } from '@alexstukovnikov/oz-time';
+ *
+ * console.log(isLeapYear(2024)); // ожидаемый результат: true
+ */
+export function isLeapYear(year) {
+    if (!Number.isInteger(year)) {
+        throw new TypeError('isLeapYear: year must be an integer');
+    }
+
+    return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+}
+
+/**
+ * Возвращает количество дней в указанном месяце указанного года.
+ *
+ * @param {number} year - Год.
+ * @param {number} month - Месяц от 1 до 12.
+ * @throws {TypeError} Выбрасывается, если year или month не являются целыми числами.
+ * @throws {RangeError} Выбрасывается, если month вне диапазона от 1 до 12.
+ * @returns {number} Количество дней в месяце.
+ * @example
+ * import { daysInMonth } from '@alexstukovnikov/oz-time';
+ *
+ * console.log(daysInMonth(2024, 2)); // ожидаемый результат: 29
+ */
+export function daysInMonth(year, month) {
+    if (!Number.isInteger(year) || !Number.isInteger(month)) {
+        throw new TypeError('daysInMonth: year and month must be integers');
+    }
+
+    if (month < 1 || month > 12) {
+        throw new RangeError('daysInMonth: month must be between 1 and 12');
+    }
+
+    return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+
+/**
+ * Возвращает новый timestamp, увеличенный на указанное количество
+ * фиксированных единиц времени.
+ *
+ * @param {number} timestamp - Unix timestamp в миллисекундах.
+ * @param {number} amount - Количество единиц времени.
+ * @param {string} unit - Фиксированная единица времени.
+ * @throws {TypeError} Выбрасывается, если timestamp или amount некорректны.
+ * @throws {Error} Выбрасывается, если unit не является фиксированной единицей.
+ * @returns {number} Новый Unix timestamp в миллисекундах.
+ * @example
+ * import { addByFixedUnit } from './utils/calendar.js';
+ *
+ * console.log(addByFixedUnit(1716638400000, 1, 'day')); // ожидаемый результат: 1716724800000
+ */
+export function addByFixedUnit(timestamp, amount, unit) {
+    assertValidTimestamp(timestamp, 'addByFixedUnit');
+    assertValidAmount(amount, 'addByFixedUnit');
+
+    const normalizedUnit = normalizeUnit(unit);
+
+    if (!isFixedUnit(normalizedUnit)) {
+        throw new Error(`addByFixedUnit does not support calendar unit: ${unit}`);
+    }
+
+    return timestamp + amount * unitToMilliseconds(normalizedUnit);
+}
+
+/**
+ * Возвращает новый timestamp, увеличенный на указанное количество
+ * календарных единиц времени.
+ *
+ * Поддерживаются только `month` и `year`.
+ *
+ * @param {number} timestamp - Unix timestamp в миллисекундах.
+ * @param {number} amount - Количество единиц времени.
+ * @param {string} unit - Календарная единица времени.
+ * @throws {TypeError} Выбрасывается, если timestamp или amount некорректны.
+ * @throws {Error} Выбрасывается, если unit не поддерживается.
+ * @returns {number} Новый Unix timestamp в миллисекундах.
+ * @example
+ * import { addByCalendarUnit } from './utils/calendar.js';
+ *
+ * console.log(addByCalendarUnit(Date.UTC(2024, 0, 31, 0, 0, 0, 0), 1, 'month')); // ожидаемый результат: 1709164800000
+ */
+export function addByCalendarUnit(timestamp, amount, unit) {
+    assertValidTimestamp(timestamp, 'addByCalendarUnit');
+    assertValidAmount(amount, 'addByCalendarUnit');
+
+    const normalizedUnit = normalizeUnit(unit);
+    const date = new Date(timestamp);
+
+    if (normalizedUnit === 'month') {
+        const originalDay = date.getUTCDate();
+
+        date.setUTCDate(1);
+        date.setUTCMonth(date.getUTCMonth() + amount);
+
+        const maxDay = daysInMonth(date.getUTCFullYear(), date.getUTCMonth() + 1);
+        date.setUTCDate(Math.min(originalDay, maxDay));
+
+        return date.getTime();
+    }
+
+    if (normalizedUnit === 'year') {
+        const originalMonth = date.getUTCMonth();
+        const originalDay = date.getUTCDate();
+
+        date.setUTCDate(1);
+        date.setUTCFullYear(date.getUTCFullYear() + amount);
+        date.setUTCMonth(originalMonth);
+
+        const maxDay = daysInMonth(date.getUTCFullYear(), originalMonth + 1);
+        date.setUTCDate(Math.min(originalDay, maxDay));
+
+        return date.getTime();
+    }
+
+    throw new Error(`addByCalendarUnit supports only month and year: ${unit}`);
+}
+
+/**
+ * Возвращает числовую разницу между двумя экземплярами {@link OzTime}
+ * в указанной единице времени.
+ *
+ * Для фиксированных единиц может возвращать дробное число,
+ * для месяцев и лет возвращает целочисленную календарную разницу.
+ *
+ * @param {OzTime} left - Левое значение.
+ * @param {OzTime} right - Правое значение.
+ * @param {string} [unit='millisecond'] - Единица времени.
+ * @throws {TypeError} Выбрасывается, если хотя бы один аргумент не является экземпляром OzTime.
+ * @throws {Error} Выбрасывается, если unit не поддерживается.
+ * @returns {number} Разница между двумя значениями времени.
+ * @example
+ * import { diff } from './utils/calendar.js';
+ * import { fromISO } from '@alexstukovnikov/oz-time';
+ *
+ * const a = fromISO('2024-05-25T14:00:00Z');
+ * const b = fromISO('2024-05-25T12:00:00Z');
+ * console.log(diff(a, b, 'hour')); // ожидаемый результат: 2
+ */
+export function diff(left, right, unit = 'millisecond') {
+    assertOzTime(left, 'left');
+    assertOzTime(right, 'right');
+
+    const normalizedUnit = normalizeUnit(unit);
+    const leftTimestamp = left.getTimestamp();
+    const rightTimestamp = right.getTimestamp();
+
+    if (isFixedUnit(normalizedUnit)) {
+        return (leftTimestamp - rightTimestamp) / unitToMilliseconds(normalizedUnit);
+    }
+
+    if (normalizedUnit === 'month') {
+        return diffInMonths(leftTimestamp, rightTimestamp);
+    }
+
+    if (normalizedUnit === 'year') {
+        return diffInYears(leftTimestamp, rightTimestamp);
+    }
+
+    throw new Error(`Unsupported unit: ${unit}`);
+}