@alexstukovnikov/oz-time 1.0.0 → 1.0.2

package/src/core/factory.js

@@ -0,0 +1,194 @@
+import { OzTime } from './core.js';
+import { daysInMonth } from '../utils/calendar.js';
+
+/**
+ * Фабричные функции для создания экземпляров {@link OzTime}.
+ *
+ * @module core/factory
+ */
+
+/**
+ * Проверяет корректность timestamp.
+ *
+ * @private
+ * @param {number} timestamp - Unix timestamp в миллисекундах.
+ * @throws {TypeError} Выбрасывается, если timestamp некорректен.
+ * @returns {void}
+ */
+function assertValidTimestamp(timestamp) {
+    if (typeof timestamp !== 'number' || Number.isNaN(timestamp)) {
+        throw new TypeError('fromTimestamp: timestamp must be a valid number');
+    }
+}
+
+/**
+ * Проверяет корректность объекта Date.
+ *
+ * @private
+ * @param {Date} date - Проверяемый объект Date.
+ * @throws {TypeError} Выбрасывается, если date некорректен.
+ * @returns {void}
+ */
+function assertValidDate(date) {
+    if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
+        throw new TypeError('fromDate: date must be a valid Date');
+    }
+}
+
+/**
+ * Проверяет, что значение является целым числом.
+ *
+ * @private
+ * @param {number} value - Проверяемое значение.
+ * @param {string} name - Имя параметра.
+ * @throws {TypeError} Выбрасывается, если значение не является целым числом.
+ * @returns {void}
+ */
+function assertInteger(value, name) {
+    if (!Number.isInteger(value)) {
+        throw new TypeError(`${name} must be an integer`);
+    }
+}
+
+/**
+ * Создаёт и возвращает экземпляр {@link OzTime} для текущего момента времени.
+ *
+ * @param {string} [timezone='UTC'] - Часовой пояс в формате IANA.
+ * @param {string} [locale='en-US'] - Локаль форматирования.
+ * @returns {OzTime} Экземпляр с текущим временем.
+ * @example
+ * import { now } from '@alexstukovnikov/oz-time';
+ *
+ * const current = now('Europe/Moscow', 'ru-RU');
+ * console.log(current.getTimezone()); // ожидаемый результат: Europe/Moscow
+ */
+export function now(timezone = 'UTC', locale = 'en-US') {
+    return new OzTime(Date.now(), timezone, locale);
+}
+
+/**
+ * Создаёт и возвращает экземпляр {@link OzTime} на основе Unix timestamp.
+ *
+ * @param {number} timestamp - Unix timestamp в миллисекундах.
+ * @param {string} [timezone='UTC'] - Часовой пояс в формате IANA.
+ * @param {string} [locale='en-US'] - Локаль форматирования.
+ * @throws {TypeError} Выбрасывается, если timestamp некорректен.
+ * @returns {OzTime} Экземпляр времени.
+ * @example
+ * import { fromTimestamp } from '@alexstukovnikov/oz-time';
+ *
+ * const time = fromTimestamp(1716638400000, 'UTC', 'ru-RU');
+ * console.log(time.toISOString()); // ожидаемый результат: 2024-05-25T12:00:00.000Z
+ */
+export function fromTimestamp(timestamp, timezone = 'UTC', locale = 'en-US') {
+    assertValidTimestamp(timestamp);
+    return new OzTime(timestamp, timezone, locale);
+}
+
+/**
+ * Создаёт и возвращает экземпляр {@link OzTime} на основе объекта {@link Date}.
+ *
+ * @param {Date} date - Нативный объект Date.
+ * @param {string} [timezone='UTC'] - Часовой пояс в формате IANA.
+ * @param {string} [locale='en-US'] - Локаль форматирования.
+ * @throws {TypeError} Выбрасывается, если date некорректен.
+ * @returns {OzTime} Экземпляр времени.
+ * @example
+ * import { fromDate } from '@alexstukovnikov/oz-time';
+ *
+ * const time = fromDate(new Date('2024-05-25T12:00:00Z'), 'UTC', 'ru-RU');
+ * console.log(time.toTimestamp()); // ожидаемый результат: 1716638400000
+ */
+export function fromDate(date, timezone = 'UTC', locale = 'en-US') {
+    assertValidDate(date);
+    return new OzTime(date.getTime(), timezone, locale);
+}
+
+/**
+ * Создаёт и возвращает экземпляр {@link OzTime} на основе ISO-строки.
+ *
+ * @param {string} isoString - Строка даты и времени в формате ISO 8601.
+ * @param {string} [timezone='UTC'] - Часовой пояс в формате IANA.
+ * @param {string} [locale='en-US'] - Локаль форматирования.
+ * @throws {TypeError} Выбрасывается, если строка пустая или не является строкой.
+ * @throws {Error} Выбрасывается, если строку не удалось распарсить.
+ * @returns {OzTime} Экземпляр времени.
+ * @example
+ * import { fromISO } from '@alexstukovnikov/oz-time';
+ *
+ * const time = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
+ * console.log(time.format('DD.MM.YYYY HH:mm')); // ожидаемый результат: 25.05.2024 12:00
+ */
+export function fromISO(isoString, timezone = 'UTC', locale = 'en-US') {
+    if (typeof isoString !== 'string' || isoString.trim() === '') {
+        throw new TypeError('fromISO: isoString must be a non-empty string');
+    }
+
+    const ts = Date.parse(isoString);
+
+    if (Number.isNaN(ts)) {
+        throw new Error(`Invalid ISO date string: ${isoString}`);
+    }
+
+    return new OzTime(ts, timezone, locale);
+}
+
+/**
+ * Создаёт и возвращает экземпляр {@link OzTime} на основе отдельных компонентов даты и времени.
+ *
+ * @param {number} year - Год.
+ * @param {number} month - Месяц от 1 до 12.
+ * @param {number} day - День месяца.
+ * @param {number} [hour=0] - Час от 0 до 23.
+ * @param {number} [minute=0] - Минута от 0 до 59.
+ * @param {number} [second=0] - Секунда от 0 до 59.
+ * @param {number} [ms=0] - Миллисекунда от 0 до 999.
+ * @param {string} [timezone='UTC'] - Часовой пояс в формате IANA.
+ * @param {string} [locale='en-US'] - Локаль форматирования.
+ * @throws {TypeError} Выбрасывается, если любой числовой параметр не является целым числом.
+ * @throws {RangeError} Выбрасывается, если любой компонент даты или времени вне допустимого диапазона.
+ * @returns {OzTime} Экземпляр времени.
+ * @example
+ * import { fromComponents } from '@alexstukovnikov/oz-time';
+ *
+ * const time = fromComponents(2024, 5, 25, 12, 0, 0, 0, 'UTC', 'ru-RU');
+ * console.log(time.toISOString()); // ожидаемый результат: 2024-05-25T12:00:00.000Z
+ */
+export function fromComponents(year, month, day, hour = 0, minute = 0, second = 0, ms = 0, timezone = 'UTC', locale = 'en-US') {
+    assertInteger(year, 'year');
+    assertInteger(month, 'month');
+    assertInteger(day, 'day');
+    assertInteger(hour, 'hour');
+    assertInteger(minute, 'minute');
+    assertInteger(second, 'second');
+    assertInteger(ms, 'millisecond');
+
+    if (month < 1 || month > 12) {
+        throw new RangeError('month must be between 1 and 12');
+    }
+
+    if (hour < 0 || hour > 23) {
+        throw new RangeError('hour must be between 0 and 23');
+    }
+
+    if (minute < 0 || minute > 59) {
+        throw new RangeError('minute must be between 0 and 59');
+    }
+
+    if (second < 0 || second > 59) {
+        throw new RangeError('second must be between 0 and 59');
+    }
+
+    if (ms < 0 || ms > 999) {
+        throw new RangeError('millisecond must be between 0 and 999');
+    }
+
+    const maxDay = daysInMonth(year, month);
+
+    if (day < 1 || day > maxDay) {
+        throw new RangeError(`day must be between 1 and ${maxDay} for ${year}-${month}`);
+    }
+
+    const ts = Date.UTC(year, month - 1, day, hour, minute, second, ms);
+    return new OzTime(ts, timezone, locale);
+}

package/src/index.js

@@ -0,0 +1,22 @@
+/**
+ * Публичная точка входа библиотеки OzTime.
+ *
+ * @module index
+ */
+
+export { OzTime } from './core/core.js';
+export { now, fromTimestamp, fromDate, fromISO, fromComponents } from './core/factory.js';
+
+export { add, subtract } from './modules/arithmetic.js';
+
+export { isSame, isBefore, isAfter, isBetween } from './modules/compare.js';
+
+export { setTimezone, getTimezoneOffset } from './modules/timezone.js';
+
+export { Interval, interval } from './modules/interval.js';
+
+export { Duration, duration } from './modules/duration.js';
+
+export { format } from './modules/format.js';
+
+export { isLeapYear, daysInMonth } from './utils/calendar.js';

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