@alexstukovnikov/oz-time 1.0.0 → 1.0.2

package/src/modules/format.js

@@ -0,0 +1,162 @@
+import { OzTime } from '../core/core.js';
+
+/**
+ * Модуль форматирования экземпляров {@link OzTime}.
+ *
+ * @module modules/format
+ */
+
+/**
+ * Проверяет, является ли значение экземпляром OzTime.
+ *
+ * @private
+ * @param {*} value - Проверяемое значение.
+ * @throws {TypeError} Выбрасывается, если значение не является экземпляром OzTime.
+ * @returns {void}
+ */
+function assertOzTime(value) {
+    if (!(value instanceof OzTime)) {
+        throw new TypeError('format: first argument must be OzTime');
+    }
+}
+
+/**
+ * Дополняет значение ведущими нулями до нужной длины.
+ *
+ * @private
+ * @param {string|number} value - Исходное значение.
+ * @param {number} [length=2] - Итоговая длина строки.
+ * @returns {string} Строка, дополненная ведущими нулями.
+ */
+function pad(value, length = 2) {
+    return String(value).padStart(length, '0');
+}
+
+/**
+ * Возвращает числовые части даты для форматирования.
+ *
+ * @private
+ * @param {OzTime} time - Экземпляр времени.
+ * @param {string} locale - Локаль форматирования.
+ * @returns {Object.<string, string>} Объект с числовыми частями даты и времени.
+ */
+function getNumericParts(time, locale) {
+    const formatter = new Intl.DateTimeFormat(locale, {
+        timeZone: time.getTimezone(),
+        year: 'numeric',
+        month: 'numeric',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+    });
+
+    const parts = formatter.formatToParts(new Date(time.getTimestamp()));
+    return Object.fromEntries(parts.map((part) => [part.type, part.value]));
+}
+
+/**
+ * Возвращает название месяца в нужном формате.
+ *
+ * @private
+ * @param {OzTime} time - Экземпляр времени.
+ * @param {string} locale - Локаль форматирования.
+ * @param {'long'|'short'|'narrow'} length - Длина названия месяца.
+ * @returns {string} Название месяца.
+ */
+function getMonthName(time, locale, length) {
+    return new Intl.DateTimeFormat(locale, {
+        timeZone: time.getTimezone(),
+        month: length,
+    }).format(new Date(time.getTimestamp()));
+}
+
+/**
+ * Возвращает название дня недели в нужном формате.
+ *
+ * @private
+ * @param {OzTime} time - Экземпляр времени.
+ * @param {string} locale - Локаль форматирования.
+ * @param {'long'|'short'|'narrow'} length - Длина названия дня недели.
+ * @returns {string} Название дня недели.
+ */
+function getWeekdayName(time, locale, length) {
+    return new Intl.DateTimeFormat(locale, {
+        timeZone: time.getTimezone(),
+        weekday: length,
+    }).format(new Date(time.getTimestamp()));
+}
+
+/**
+ * Возвращает строковое представление экземпляра {@link OzTime}
+ * по заданному шаблону с токенами.
+ *
+ * Поддерживаются токены `YYYY`, `YY`, `MMMM`, `MMM`, `MM`, `M`, `dddd`, `ddd`,
+ * `DD`, `D`, `HH`, `H`, `hh`, `h`, `mm`, `ss`, `SSS` и `A`.
+ *
+ * @param {OzTime} time - Экземпляр времени для форматирования.
+ * @param {string} template - Шаблон форматирования.
+ * @param {string} [locale] - Необязательное переопределение локали.
+ * @throws {TypeError} Выбрасывается, если первый аргумент не является экземпляром OzTime или template некорректен.
+ * @returns {string} Отформатированная строка.
+ * @example
+ * import { format, fromISO } from '@alexstukovnikov/oz-time';
+ *
+ * const time = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
+ * console.log(format(time, 'DD.MM.YYYY HH:mm')); // ожидаемый результат: 25.05.2024 12:00
+ */
+export function format(time, template, locale) {
+    assertOzTime(time);
+
+    if (typeof template !== 'string' || template.trim() === '') {
+        throw new TypeError('format: template must be a non-empty string');
+    }
+
+    const usedLocale = locale ?? time.getLocale();
+    const parts = getNumericParts(time, usedLocale);
+
+    const year = Number(parts.year);
+    const month = Number(parts.month);
+    const day = Number(parts.day);
+    const hour24 = Number(parts.hour);
+    const minute = Number(parts.minute);
+    const second = Number(parts.second);
+    const millisecond = new Date(time.getTimestamp()).getUTCMilliseconds();
+
+    const hour12base = hour24 % 12;
+    const hour12 = hour12base === 0 ? 12 : hour12base;
+    const meridiem = hour24 >= 12 ? 'PM' : 'AM';
+
+    const tokens = {
+        YYYY: String(year),
+        YY: String(year).slice(-2),
+
+        MMMM: getMonthName(time, usedLocale, 'long'),
+        MMM: getMonthName(time, usedLocale, 'short'),
+        MM: pad(month),
+        M: String(month),
+
+        dddd: getWeekdayName(time, usedLocale, 'long'),
+        ddd: getWeekdayName(time, usedLocale, 'short'),
+
+        DD: pad(day),
+        D: String(day),
+
+        HH: pad(hour24),
+        H: String(hour24),
+
+        hh: pad(hour12),
+        h: String(hour12),
+
+        mm: pad(minute),
+        ss: pad(second),
+        SSS: pad(millisecond, 3),
+
+        A: meridiem,
+    };
+
+    const tokenPattern = /YYYY|MMMM|MMM|MM|M|dddd|ddd|DD|D|HH|H|hh|h|mm|ss|SSS|YY|A/g;
+
+    return template.replace(tokenPattern, (token) => tokens[token] ?? token);
+}

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);
+}