@alexstukovnikov/oz-time 1.0.0 → 1.0.1

package/src/modules/arithmetic.js

@@ -0,0 +1,100 @@
+import { OzTime } from '../core/core.js';
+import { normalizeUnit, isFixedUnit, isCalendarUnit } from '../utils/units.js';
+import { addByFixedUnit, addByCalendarUnit } from '../utils/calendar.js';
+
+/**
+ * Модуль арифметических операций над экземплярами {@link OzTime}.
+ *
+ * @module modules/arithmetic
+ */
+
+/**
+ * Проверяет, является ли значение экземпляром 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`);
+    }
+}
+
+/**
+ * Проверяет корректность числового значения amount.
+ *
+ * @private
+ * @param {number} amount - Количество единиц времени.
+ * @throws {TypeError} Выбрасывается, если amount не является корректным числом.
+ * @returns {void}
+ */
+function assertAmount(amount) {
+    if (typeof amount !== 'number' || Number.isNaN(amount)) {
+        throw new TypeError('amount must be a valid number');
+    }
+}
+
+/**
+ * Возвращает новый экземпляр {@link OzTime}, у которого timestamp увеличен
+ * на указанное количество единиц времени.
+ *
+ * Поддерживает как фиксированные, так и календарные единицы времени.
+ * Исходный экземпляр не изменяется.
+ *
+ * @param {OzTime} time - Исходное значение времени.
+ * @param {number} amount - Количество единиц времени.
+ * @param {string} unit - Единица времени.
+ * @throws {TypeError} Выбрасывается, если time или amount некорректны.
+ * @returns {OzTime} Новый экземпляр OzTime с timestamp, сдвинутым вперёд.
+ * @example
+ * import { add, fromISO } from '@alexstukovnikov/oz-time';
+ *
+ * const time = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
+ * const result = add(time, 2, 'day');
+ * console.log(result.toISOString()); // ожидаемый результат: 2024-05-27T12:00:00.000Z
+ */
+export function add(time, amount, unit) {
+    assertOzTime(time, 'time');
+    assertAmount(amount);
+
+    const normalizedUnit = normalizeUnit(unit);
+    const timestamp = time.getTimestamp();
+
+    let nextTimestamp;
+
+    if (isFixedUnit(normalizedUnit)) {
+        nextTimestamp = addByFixedUnit(timestamp, amount, normalizedUnit);
+    } else if (isCalendarUnit(normalizedUnit)) {
+        nextTimestamp = addByCalendarUnit(timestamp, amount, normalizedUnit);
+    }
+
+    return new OzTime(nextTimestamp, time.getTimezone(), time.getLocale());
+}
+
+/**
+ * Возвращает новый экземпляр {@link OzTime}, у которого timestamp уменьшен
+ * на указанное количество единиц времени.
+ *
+ * Исходный экземпляр не изменяется.
+ *
+ * @param {OzTime} time - Исходное значение времени.
+ * @param {number} amount - Количество единиц времени.
+ * @param {string} unit - Единица времени.
+ * @throws {TypeError} Выбрасывается, если time или amount некорректны.
+ * @returns {OzTime} Новый экземпляр OzTime с timestamp, сдвинутым назад.
+ * @example
+ * import { subtract, fromISO } from '@alexstukovnikov/oz-time';
+ *
+ * const time = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
+ * const result = subtract(time, 3, 'hour');
+ * console.log(result.toISOString()); // ожидаемый результат: 2024-05-25T09:00:00.000Z
+ */
+export function subtract(time, amount, unit) {
+    assertOzTime(time, 'time');
+    assertAmount(amount);
+
+    return add(time, -amount, unit);
+}

package/src/modules/compare.js

@@ -0,0 +1,197 @@
+import { OzTime } from '../core/core.js';
+import { normalizeUnit } from '../utils/units.js';
+
+/**
+ * Модуль сравнений для экземпляров {@link OzTime}.
+ *
+ * @module modules/compare
+ */
+
+/**
+ * Проверяет, является ли значение экземпляром 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} timestamp - Исходный timestamp в миллисекундах.
+ * @param {string} unit - Единица точности.
+ * @throws {Error} Выбрасывается, если единица не поддерживается.
+ * @returns {number} Timestamp, обрезанный до заданной единицы времени.
+ */
+function truncateToUnit(timestamp, unit) {
+    const normalizedUnit = normalizeUnit(unit);
+    const d = new Date(timestamp);
+
+    switch (normalizedUnit) {
+        case 'millisecond':
+            return d.getTime();
+
+        case 'second':
+            d.setUTCMilliseconds(0);
+            break;
+
+        case 'minute':
+            d.setUTCSeconds(0, 0);
+            break;
+
+        case 'hour':
+            d.setUTCMinutes(0, 0, 0);
+            break;
+
+        case 'day':
+            d.setUTCHours(0, 0, 0, 0);
+            break;
+
+        case 'month':
+            d.setUTCHours(0, 0, 0, 0);
+            d.setUTCDate(1);
+            break;
+
+        case 'year':
+            d.setUTCHours(0, 0, 0, 0);
+            d.setUTCDate(1);
+            d.setUTCMonth(0);
+            break;
+
+        default:
+            throw new Error(`Unsupported unit for truncateToUnit: ${unit}`);
+    }
+
+    return d.getTime();
+}
+
+/**
+ * Проверяет, равны ли два значения времени с учётом заданной точности.
+ *
+ * @param {OzTime} a - Первое значение.
+ * @param {OzTime} b - Второе значение.
+ * @param {string} [unit='millisecond'] - Точность сравнения.
+ * @throws {TypeError} Выбрасывается, если хотя бы один аргумент не является экземпляром OzTime.
+ * @returns {boolean} `true`, если значения равны на заданной точности.
+ * @example
+ * import { isSame, fromISO } from '@alexstukovnikov/oz-time';
+ *
+ * const a = fromISO('2024-05-25T12:00:00.100Z');
+ * const b = fromISO('2024-05-25T12:00:00.900Z');
+ * console.log(isSame(a, b, 'second')); // ожидаемый результат: true
+ */
+export function isSame(a, b, unit = 'millisecond') {
+    assertOzTime(a, 'a');
+    assertOzTime(b, 'b');
+
+    const tsA = truncateToUnit(a.getTimestamp(), unit);
+    const tsB = truncateToUnit(b.getTimestamp(), unit);
+
+    return tsA === tsB;
+}
+
+/**
+ * Проверяет, находится ли первое значение раньше второго
+ * с учётом заданной точности.
+ *
+ * @param {OzTime} a - Первое значение.
+ * @param {OzTime} b - Второе значение.
+ * @param {string} [unit='millisecond'] - Точность сравнения.
+ * @throws {TypeError} Выбрасывается, если хотя бы один аргумент не является экземпляром OzTime.
+ * @returns {boolean} `true`, если первое значение раньше второго.
+ * @example
+ * import { isBefore, fromISO } from '@alexstukovnikov/oz-time';
+ *
+ * const a = fromISO('2024-05-25T12:00:00Z');
+ * const b = fromISO('2024-05-26T12:00:00Z');
+ * console.log(isBefore(a, b)); // ожидаемый результат: true
+ */
+export function isBefore(a, b, unit = 'millisecond') {
+    assertOzTime(a, 'a');
+    assertOzTime(b, 'b');
+
+    const tsA = truncateToUnit(a.getTimestamp(), unit);
+    const tsB = truncateToUnit(b.getTimestamp(), unit);
+
+    return tsA < tsB;
+}
+
+/**
+ * Проверяет, находится ли первое значение позже второго
+ * с учётом заданной точности.
+ *
+ * @param {OzTime} a - Первое значение.
+ * @param {OzTime} b - Второе значение.
+ * @param {string} [unit='millisecond'] - Точность сравнения.
+ * @throws {TypeError} Выбрасывается, если хотя бы один аргумент не является экземпляром OzTime.
+ * @returns {boolean} `true`, если первое значение позже второго.
+ * @example
+ * import { isAfter, fromISO } from '@alexstukovnikov/oz-time';
+ *
+ * const a = fromISO('2024-05-26T12:00:00Z');
+ * const b = fromISO('2024-05-25T12:00:00Z');
+ * console.log(isAfter(a, b)); // ожидаемый результат: true
+ */
+export function isAfter(a, b, unit = 'millisecond') {
+    assertOzTime(a, 'a');
+    assertOzTime(b, 'b');
+
+    const tsA = truncateToUnit(a.getTimestamp(), unit);
+    const tsB = truncateToUnit(b.getTimestamp(), unit);
+
+    return tsA > tsB;
+}
+
+/**
+ * Проверяет, попадает ли целевое значение в диапазон между двумя границами
+ * с учётом заданной точности.
+ *
+ * @param {OzTime} target - Проверяемое значение.
+ * @param {OzTime} left - Левая граница.
+ * @param {OzTime} right - Правая граница.
+ * @param {string} [unit='millisecond'] - Точность сравнения.
+ * @param {'[]'|'[)'|'(]'|'()'} [inclusivity='[]'] - Формат включённости границ.
+ * @throws {TypeError} Выбрасывается, если хотя бы один аргумент не является экземпляром OzTime.
+ * @throws {Error} Выбрасывается, если inclusivity задан некорректно.
+ * @returns {boolean} `true`, если значение находится внутри диапазона.
+ * @example
+ * import { isBetween, fromISO } from '@alexstukovnikov/oz-time';
+ *
+ * const target = fromISO('2024-05-25T12:00:00Z');
+ * const start = fromISO('2024-05-25T10:00:00Z');
+ * const end = fromISO('2024-05-25T14:00:00Z');
+ * console.log(isBetween(target, start, end)); // ожидаемый результат: true
+ */
+export function isBetween(target, left, right, unit = 'millisecond', inclusivity = '[]') {
+    assertOzTime(target, 'target');
+    assertOzTime(left, 'left');
+    assertOzTime(right, 'right');
+
+    const t = truncateToUnit(target.getTimestamp(), unit);
+    const l = truncateToUnit(left.getTimestamp(), unit);
+    const r = truncateToUnit(right.getTimestamp(), unit);
+
+    const min = Math.min(l, r);
+    const max = Math.max(l, r);
+
+    switch (inclusivity) {
+        case '[]':
+            return t >= min && t <= max;
+        case '[)':
+            return t >= min && t < max;
+        case '(]':
+            return t > min && t <= max;
+        case '()':
+            return t > min && t < max;
+        default:
+            throw new Error(`Invalid inclusivity value: ${inclusivity}`);
+    }
+}

package/src/modules/duration.js

@@ -0,0 +1,165 @@
+import { isFixedUnit, unitToMilliseconds, normalizeUnit } from '../utils/units.js';
+
+/**
+ * Модуль для работы с фиксированными длительностями.
+ *
+ * @module modules/duration
+ */
+
+/**
+ * Проверяет корректность числового значения amount.
+ *
+ * @private
+ * @param {number} amount - Количество единиц времени.
+ * @throws {TypeError} Выбрасывается, если amount не является корректным числом.
+ * @returns {void}
+ */
+function assertAmount(amount) {
+    if (typeof amount !== 'number' || Number.isNaN(amount)) {
+        throw new TypeError('amount must be a valid number');
+    }
+}
+
+/**
+ * Представляет фиксированную длительность, хранящуюся в миллисекундах.
+ *
+ * @class
+ * @example
+ * import { Duration } from '@alexstukovnikov/oz-time';
+ *
+ * const duration = new Duration(3600000);
+ * console.log(duration.asHours()); // ожидаемый результат: 1
+ */
+export class Duration {
+    /**
+     * Создаёт экземпляр Duration.
+     *
+     * @param {number} milliseconds - Длительность в миллисекундах.
+     * @throws {TypeError} Выбрасывается, если milliseconds некорректен.
+     */
+    constructor(milliseconds) {
+        if (typeof milliseconds !== 'number' || Number.isNaN(milliseconds)) {
+            throw new TypeError('Duration: milliseconds must be a valid number');
+        }
+
+        this._milliseconds = milliseconds;
+    }
+
+    /**
+     * Возвращает длительность в миллисекундах.
+     *
+     * @returns {number} Длительность в миллисекундах.
+     * @example
+     * import { duration } from '@alexstukovnikov/oz-time';
+     *
+     * const value = duration(3600000, 'millisecond');
+     * console.log(value.asMilliseconds()); // ожидаемый результат: 3600000
+     */
+    asMilliseconds() {
+        return this._milliseconds;
+    }
+
+    /**
+     * Возвращает длительность в секундах.
+     *
+     * @returns {number} Длительность в секундах.
+     * @example
+     * import { duration } from '@alexstukovnikov/oz-time';
+     *
+     * const value = duration(3600000, 'millisecond');
+     * console.log(value.asSeconds()); // ожидаемый результат: 3600
+     */
+    asSeconds() {
+        return this._milliseconds / unitToMilliseconds('second');
+    }
+
+    /**
+     * Возвращает длительность в минутах.
+     *
+     * @returns {number} Длительность в минутах.
+     * @example
+     * import { duration } from '@alexstukovnikov/oz-time';
+     *
+     * const value = duration(3600000, 'millisecond');
+     * console.log(value.asMinutes()); // ожидаемый результат: 60
+     */
+    asMinutes() {
+        return this._milliseconds / unitToMilliseconds('minute');
+    }
+
+    /**
+     * Возвращает длительность в часах.
+     *
+     * @returns {number} Длительность в часах.
+     * @example
+     * import { duration } from '@alexstukovnikov/oz-time';
+     *
+     * const value = duration(36000000, 'millisecond');
+     * console.log(value.asHours()); // ожидаемый результат: 10
+     */
+    asHours() {
+        return this._milliseconds / unitToMilliseconds('hour');
+    }
+
+    /**
+     * Возвращает длительность в днях.
+     *
+     * @returns {number} Длительность в днях.
+     * @example
+     * import { duration } from '@alexstukovnikov/oz-time';
+     *
+     * const value = duration(120, 'hour');
+     * console.log(value.asDays()); // ожидаемый результат: 5
+     */
+    asDays() {
+        return this._milliseconds / unitToMilliseconds('day');
+    }
+
+    /**
+     * Возвращает новую длительность, равную сумме текущей и переданной длительности.
+     *
+     * @param {Duration} other - Вторая длительность.
+     * @throws {TypeError} Выбрасывается, если other не является экземпляром Duration.
+     * @returns {Duration} Новая длительность, равная сумме двух значений.
+     * @example
+     * import { duration } from '@alexstukovnikov/oz-time';
+     *
+     * const a = duration(1, 'second');
+     * const b = duration(2, 'second');
+     * console.log(a.add(b).asMilliseconds()); // ожидаемый результат: 3000
+     */
+    add(other) {
+        if (!(other instanceof Duration)) {
+            throw new TypeError('Duration.add: other must be Duration');
+        }
+
+        return new Duration(this._milliseconds + other._milliseconds);
+    }
+}
+
+/**
+ * Создаёт и возвращает экземпляр {@link Duration} из числа
+ * и фиксированной единицы времени.
+ *
+ * @param {number} amount - Количество единиц времени.
+ * @param {string} unit - Фиксированная единица времени.
+ * @throws {TypeError} Выбрасывается, если amount некорректен.
+ * @throws {Error} Выбрасывается, если unit не является фиксированной единицей времени.
+ * @returns {Duration} Экземпляр Duration.
+ * @example
+ * import { duration } from '@alexstukovnikov/oz-time';
+ *
+ * const value = duration(2, 'hour');
+ * console.log(value.asMinutes()); // ожидаемый результат: 120
+ */
+export function duration(amount, unit) {
+    assertAmount(amount);
+
+    const normalizedUnit = normalizeUnit(unit);
+
+    if (!isFixedUnit(normalizedUnit)) {
+        throw new Error(`duration supports only fixed units: ${unit}`);
+    }
+
+    return new Duration(amount * unitToMilliseconds(normalizedUnit));
+}

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