@alexstukovnikov/oz-time 1.0.0 → 1.0.2

package/README.md

@@ -4,7 +4,8 @@ JavaScript-библиотека для работы с датой и време
 
 `OzTime` предоставляет неизменяемые объекты времени, фабричные функции создания экземпляров, арифметику по фиксированным и календарным единицам, сравнение, форматирование, работу с часовыми поясами, интервалы и длительности.
 
-[Полная документация API](https://AlexStukovnikov.github.io/oz-time/)
+- Документация API: [AlexStukovnikov.github.io/oz-time](https://AlexStukovnikov.github.io/oz-time/)
+- Пакет npm: [`@alexstukovnikov/oz-time`](https://www.npmjs.com/package/@alexstukovnikov/oz-time)
 
 ## Содержание
 
@@ -12,20 +13,16 @@ JavaScript-библиотека для работы с датой и време
 - [Возможности](#возможности)
 - [Установка](#установка)
 - [Быстрый старт](#быстрый-старт)
-- [Что использовать в каком случае](#что-использовать-в-каком-случае)
+- [Основные сценарии](#основные-сценарии)
 - [Создание экземпляров](#создание-экземпляров)
 - [Арифметика](#арифметика)
 - [Сравнение](#сравнение)
 - [Форматирование](#форматирование)
 - [Часовые пояса](#часовые-пояса)
-- [Интервалы](#интервалы)
-- [Длительности](#длительности)
+- [Интервалы и длительности](#интервалы-и-длительности)
 - [Поддерживаемые единицы времени](#поддерживаемые-единицы-времени)
 - [Токены форматирования](#токены-форматирования)
-- [Публичный API](#публичный-api)
 - [FAQ](#faq)
-- [Разработка](#разработка)
-- [Генерация документации](#генерация-документации)
 - [Ограничения и особенности](#ограничения-и-особенности)
 - [Лицензия](#лицензия)
 
@@ -50,48 +47,21 @@ JavaScript-библиотека для работы с датой и време
 ## Возможности
 
 - Неизменяемые экземпляры `OzTime`
-- Фабричные функции:
-    - `now`
-    - `fromTimestamp`
-    - `fromDate`
-    - `fromISO`
-    - `fromComponents`
-- Арифметика по времени:
-    - `add`
-    - `subtract`
-- Сравнение:
-    - `isSame`
-    - `isBefore`
-    - `isAfter`
-    - `isBetween`
+- Фабричные функции: `now`, `fromTimestamp`, `fromDate`, `fromISO`, `fromComponents`
+- Арифметика по времени: `add`, `subtract`
+- Сравнение: `isSame`, `isBefore`, `isAfter`, `isBetween`
 - Форматирование по шаблону
-- Работа с часовыми поясами:
-    - `setTimezone`
-    - `getTimezoneOffset`
-- Интервалы:
-    - `Interval`
-    - `interval`
-- Длительности:
-    - `Duration`
-    - `duration`
-- Календарные утилиты:
-    - `isLeapYear`
-    - `daysInMonth`
+- Работа с часовыми поясами: `setTimezone`, `getTimezoneOffset`
+- Интервалы: `Interval`, `interval`
+- Длительности: `Duration`, `duration`
+- Календарные утилиты: `isLeapYear`, `daysInMonth`
 
 ## Установка
 
-### Как зависимость проекта
-
 ```bash
 npm install @alexstukovnikov/oz-time
 ```
 
-### Для локальной разработки
-
-```bash
-npm install
-```
-
 ## Быстрый старт
 
 ```js
@@ -114,107 +84,72 @@ const oneHour = duration(1, 'hour');
 console.log(oneHour.asMinutes()); // ожидаемый результат: 60
 ```
 
-## Что использовать в каком случае
-
-| Сценарий                                  | Что использовать                        | Почему                                                                               |
-| ----------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------ |
-| Нужен текущий момент времени              | `now()`                                 | Самый простой способ получить новый экземпляр `OzTime` для текущего момента.         |
-| Есть Unix timestamp в миллисекундах       | `fromTimestamp()`                       | Подходит для работы с временем из API, БД и системных источников.                    |
-| Есть нативный `Date`                      | `fromDate()`                            | Удобно интегрировать библиотеку в существующий код на JavaScript.                    |
-| Есть ISO-строка                           | `fromISO()`                             | Лучший вариант для внешних API и сериализованных значений времени.                   |
-| Нужно создать дату вручную из компонентов | `fromComponents()`                      | Подходит, когда год, месяц, день и время приходят по отдельности.                    |
-| Нужно прибавить или вычесть время         | `add()` / `subtract()`                  | Возвращают новый экземпляр и не изменяют исходный объект.                            |
-| Нужно сравнить два значения               | `isSame()` / `isBefore()` / `isAfter()` | Дают читаемый API для логики сравнения.                                              |
-| Нужно проверить попадание в диапазон      | `isBetween()`                           | Удобнее, чем писать проверку вручную.                                                |
-| Нужно получить красивую строку            | `format()`                              | Форматирование по шаблону с токенами.                                                |
-| Нужно изменить отображаемый часовой пояс  | `setTimezone()`                         | Меняет timezone у нового экземпляра, не меняя абсолютный момент времени.             |
-| Нужно узнать смещение UTC                 | `getTimezoneOffset()`                   | Полезно для отображения, отладки и расчётов.                                         |
-| Нужно описать диапазон времени            | `Interval` / `interval()`               | Подходит для проверки попадания, пересечений и длительности интервала.               |
-| Нужно описать фиксированную длительность  | `Duration` / `duration()`               | Удобно для преобразования между миллисекундами, секундами, минутами, часами и днями. |
-| Нужно проверить високосный год            | `isLeapYear()`                          | Простая календарная утилита.                                                         |
-| Нужно узнать число дней в месяце          | `daysInMonth()`                         | Удобно для валидации и генерации дат.                                                |
-
-## Создание экземпляров
-
-### `now(timezone?, locale?)`
-
-Создаёт экземпляр `OzTime` для текущего момента времени.
+### Цепочка операций
 
 ```js
-import { now } from '@alexstukovnikov/oz-time';
-
-const current = now('Europe/Moscow', 'ru-RU');
-console.log(current.getTimezone()); // ожидаемый результат: Europe/Moscow
-```
-
-### `fromTimestamp(timestamp, timezone?, locale?)`
-
-Создаёт экземпляр из Unix timestamp в миллисекундах.
-
-```js
-import { fromTimestamp } from '@alexstukovnikov/oz-time';
-
-const time = fromTimestamp(1716638400000, 'UTC', 'ru-RU');
-console.log(time.toISOString()); // ожидаемый результат: 2024-05-25T12:00:00.000Z
-```
-
-### `fromDate(date, timezone?, locale?)`
-
-Создаёт экземпляр из объекта `Date`.
+import { fromISO } from '@alexstukovnikov/oz-time';
 
-```js
-import { fromDate } from '@alexstukovnikov/oz-time';
+const result = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU')
+    .add(1, 'day')
+    .add(2, 'hour')
+    .subtract(30, 'minute')
+    .setTimezone('Europe/Moscow')
+    .format('DD.MM.YYYY HH:mm:ss');
 
-const time = fromDate(new Date('2024-05-25T12:00:00Z'), 'UTC', 'ru-RU');
-console.log(time.toTimestamp()); // ожидаемый результат: 1716638400000
+console.log(result);
 ```
 
-### `fromISO(isoString, timezone?, locale?)`
+## Основные сценарии
+
+| Сценарий                                  | Что использовать                        | Почему                                                                              |
+| ----------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
+| Нужен текущий момент времени              | `now()`                                 | Самый простой способ получить новый экземпляр `OzTime` для текущего момента         |
+| Есть Unix timestamp в миллисекундах       | `fromTimestamp()`                       | Подходит для работы с временем из API, БД и системных источников                    |
+| Есть нативный `Date`                      | `fromDate()`                            | Удобно интегрировать библиотеку в существующий JavaScript-код                       |
+| Есть ISO-строка                           | `fromISO()`                             | Подходит для внешних API и сериализованных значений времени                         |
+| Нужно создать дату вручную из компонентов | `fromComponents()`                      | Удобно, когда год, месяц, день и время приходят по отдельности                      |
+| Нужно прибавить или вычесть время         | `add()` / `subtract()`                  | Возвращают новый экземпляр и не изменяют исходный объект                            |
+| Нужно сравнить два значения               | `isSame()` / `isBefore()` / `isAfter()` | Дают читаемый API для логики сравнения                                              |
+| Нужно проверить попадание в диапазон      | `isBetween()`                           | Удобнее, чем писать проверку вручную                                                |
+| Нужно получить строковое представление    | `format()`                              | Форматирование по шаблону с токенами                                                |
+| Нужно изменить отображаемый часовой пояс  | `setTimezone()`                         | Меняет timezone у нового экземпляра, не меняя абсолютный момент времени             |
+| Нужно узнать смещение относительно UTC    | `getTimezoneOffset()`                   | Полезно для отображения, отладки и расчётов                                         |
+| Нужно описать диапазон времени            | `Interval` / `interval()`               | Подходит для проверки попадания, пересечений и длительности интервала               |
+| Нужно описать фиксированную длительность  | `Duration` / `duration()`               | Удобно для преобразования между миллисекундами, секундами, минутами, часами и днями |
+| Нужно проверить високосный год            | `isLeapYear()`                          | Простая календарная утилита                                                         |
+| Нужно узнать число дней в месяце          | `daysInMonth()`                         | Удобно для валидации и генерации дат                                                |
 
-Создаёт экземпляр из ISO-строки.
+## Создание экземпляров
 
 ```js
-import { fromISO } from '@alexstukovnikov/oz-time';
+import { now, fromTimestamp, fromDate, fromISO, fromComponents } 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
+const a = now('Europe/Moscow', 'ru-RU');
+const b = fromTimestamp(1716638400000, 'UTC', 'ru-RU');
+const c = fromDate(new Date('2024-05-25T12:00:00Z'), 'UTC', 'ru-RU');
+const d = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
+const e = fromComponents(2024, 5, 25, 12, 0, 0, 0, 'UTC', 'ru-RU');
 ```
 
-### `fromComponents(year, month, day, hour?, minute?, second?, ms?, timezone?, locale?)`
-
-Создаёт экземпляр из отдельных компонентов даты и времени.
-
-```js
-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
-```
+- `now()` — создаёт экземпляр `OzTime` для текущего момента времени.
+- `fromTimestamp()` — создаёт экземпляр из Unix timestamp в миллисекундах.
+- `fromDate()` — создаёт экземпляр из объекта `Date`.
+- `fromISO()` — создаёт экземпляр из ISO-строки.
+- `fromComponents()` — создаёт экземпляр из отдельных компонентов даты и времени.
 
 ## Арифметика
 
 Все арифметические операции возвращают новый экземпляр `OzTime` и не изменяют исходный объект.
 
-### Добавление времени
-
-```js
-import { fromISO } from '@alexstukovnikov/oz-time';
-
-const time = fromISO('2024-05-25T12:00:00Z');
-const result = time.add(1, 'day');
-
-console.log(result.toISOString()); // ожидаемый результат: 2024-05-26T12:00:00.000Z
-```
-
-### Вычитание времени
+### Добавление и вычитание
 
 ```js
 import { fromISO } from '@alexstukovnikov/oz-time';
 
 const time = fromISO('2024-05-25T12:00:00Z');
-const result = time.subtract(2, 'hour');
 
-console.log(result.toISOString()); // ожидаемый результат: 2024-05-25T10:00:00.000Z
+console.log(time.add(1, 'day').toISOString()); // ожидаемый результат: 2024-05-26T12:00:00.000Z
+console.log(time.subtract(2, 'hour').toISOString()); // ожидаемый результат: 2024-05-25T10:00:00.000Z
 ```
 
 ### Разница между датами
@@ -241,54 +176,22 @@ console.log(result.toISOString()); // ожидаемый результат: 202
 
 ## Сравнение
 
-### `isSame`
-
 ```js
 import { fromISO } from '@alexstukovnikov/oz-time';
 
 const a = fromISO('2024-05-25T12:00:00.100Z');
 const b = fromISO('2024-05-25T12:00:00.900Z');
+const c = fromISO('2024-05-26T12:00:00Z');
 
 console.log(a.isSame(b, 'second')); // ожидаемый результат: true
-```
-
-### `isBefore`
-
-```js
-import { fromISO } from '@alexstukovnikov/oz-time';
-
-const a = fromISO('2024-05-25T12:00:00Z');
-const b = fromISO('2024-05-26T12:00:00Z');
-
-console.log(a.isBefore(b)); // ожидаемый результат: true
-```
-
-### `isAfter`
-
-```js
-import { fromISO } from '@alexstukovnikov/oz-time';
-
-const a = fromISO('2024-05-26T12:00:00Z');
-const b = fromISO('2024-05-25T12:00:00Z');
-
-console.log(a.isAfter(b)); // ожидаемый результат: true
-```
-
-### `isBetween`
-
-```js
-import { 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(target.isBetween(start, end)); // ожидаемый результат: true
+console.log(a.isBefore(c)); // ожидаемый результат: true
+console.log(c.isAfter(a)); // ожидаемый результат: true
+console.log(a.isBetween(a.subtract(1, 'day'), c)); // ожидаемый результат: true
 ```
 
 ## Форматирование
 
-Функция `format()` и метод `OzTime#format()` поддерживают шаблоны.
+Функция `format()` и метод `OzTime#format()` поддерживают шаблоны форматирования.
 
 ```js
 import { fromISO } from '@alexstukovnikov/oz-time';
@@ -323,7 +226,9 @@ const time = fromISO('2024-05-25T12:00:00Z', 'Europe/Moscow', 'ru-RU');
 console.log(time.getTimezoneOffset()); // ожидаемый результат: 180
 ```
 
-## Интервалы
+## Интервалы и длительности
+
+### Интервалы
 
 Интервал представляет диапазон между двумя экземплярами `OzTime`, включая границы.
 
@@ -350,7 +255,7 @@ const b = new Interval(fromISO('2024-05-25T11:00:00Z'), fromISO('2024-05-25T13:0
 console.log(a.overlaps(b)); // ожидаемый результат: true
 ```
 
-## Длительности
+### Длительности
 
 `Duration` используется для работы с фиксированными единицами времени.
 
@@ -425,44 +330,6 @@ console.log(a.add(b).asMinutes()); // ожидаемый результат: 75
 | `SSS`  | Миллисекунды                       | `123`         |
 | `A`    | AM/PM                              | `AM`, `PM`    |
 
-## Публичный API
-
-### Core
-
-- `OzTime`
-- `now`
-- `fromTimestamp`
-- `fromDate`
-- `fromISO`
-- `fromComponents`
-
-### Арифметика и сравнение
-
-- `add`
-- `subtract`
-- `isSame`
-- `isBefore`
-- `isAfter`
-- `isBetween`
-
-### Форматирование и часовые пояса
-
-- `format`
-- `setTimezone`
-- `getTimezoneOffset`
-
-### Интервалы и длительности
-
-- `Interval`
-- `interval`
-- `Duration`
-- `duration`
-
-### Календарные утилиты
-
-- `isLeapYear`
-- `daysInMonth`
-
 ## FAQ
 
 ### Чем `fromISO()` отличается от `fromTimestamp()`?
@@ -504,63 +371,15 @@ console.log(a.add(b).asMinutes()); // ожидаемый результат: 75
 
 Используй `Interval`, когда есть начало и конец диапазона. Используй `Duration`, когда нужна именно фиксированная длина времени, например 2 часа, 30 минут или 7 дней.
 
-## Разработка
-
-### Запуск dev-режима
-
-```bash
-npm run dev
-```
-
-### Сборка библиотеки
-
-```bash
-npm run build
-```
-
-### Запуск тестов
-
-```bash
-npm test
-```
-
-### Однократный запуск тестов
-
-```bash
-npm run test:run
-```
-
-### Покрытие тестами
-
-```bash
-npm run test:coverage
-```
-
-## Генерация документации
-
-### Генерация HTML-документации JSDoc
-
-```bash
-npm run docs
-```
-
-### Полная пересборка документации
-
-```bash
-npm run docs:build
-```
-
-После генерации документация будет находиться в папке `docs/`.
-
 ## Ограничения и особенности
 
-- Внутреннее значение времени хранится как Unix timestamp в миллисекундах.
-- Часовой пояс не меняет абсолютный момент времени, а влияет на форматирование и вычисление смещения.
-- Методы `add`, `subtract`, `setTimezone` и другие операции не изменяют текущий экземпляр, а возвращают новый.
-- `Duration` поддерживает только фиксированные единицы времени.
-- Календарная арифметика через `month` и `year` учитывает реальную длину месяцев.
-- Разница в `month` и `year` считается календарно, а не через точное число миллисекунд.
-- Поддержка часовых поясов зависит от `Intl` и доступных IANA time zone в среде выполнения.
+- Внутреннее значение времени хранится как Unix timestamp в миллисекундах
+- Часовой пояс не меняет абсолютный момент времени, а влияет на форматирование и вычисление смещения
+- Методы `add`, `subtract`, `setTimezone` и другие операции не изменяют текущий экземпляр, а возвращают новый
+- `Duration` поддерживает только фиксированные единицы времени
+- Календарная арифметика через `month` и `year` учитывает реальную длину месяцев
+- Разница в `month` и `year` считается календарно, а не через точное число миллисекунд
+- Поддержка часовых поясов зависит от `Intl` и доступных IANA time zone в среде выполнения
 
 ## Лицензия
 

package/package.json

@@ -1,48 +1,45 @@
-{
-    "name": "@alexstukovnikov/oz-time",
-    "version": "1.0.0",
-    "description": "Lightweight JavaScript date-time library",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/AlexStukovnikov/oz-time.git"
-    },
-    "type": "module",
-    "main": "./dist/oz-time.cjs",
-    "module": "./dist/oz-time.esm.js",
-    "exports": {
-        ".": {
-            "import": "./dist/oz-time.esm.js",
-            "require": "./dist/oz-time.cjs"
-        }
-    },
-    "files": [
-        "dist"
-    ],
-    "sideEffects": false,
-    "scripts": {
-        "dev": "vite",
-        "build": "vite build",
-        "test": "vitest",
-        "test:run": "vitest run",
-        "test:coverage": "vitest run --coverage",
-        "docs": "jsdoc -c jsdoc.json",
-        "docs:clean": "rimraf docs",
-        "docs:build": "npm run docs:clean && npm run docs",
-        "prepublishOnly": "npm run build"
-    },
-    "keywords": [
-        "date",
-        "time",
-        "datetime"
-    ],
-    "author": "",
-    "license": "ISC",
-    "devDependencies": {
-        "@vitest/coverage-v8": "^4.1.7",
-        "@vitest/ui": "^4.1.7",
-        "docdash": "^2.0.2",
-        "jsdoc": "^4.0.5",
-        "vite": "^8.0.14",
-        "vitest": "^4.1.7"
-    }
-}
+{
+    "name": "@alexstukovnikov/oz-time",
+    "version": "1.0.2",
+    "description": "Lightweight JavaScript date-time library",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/AlexStukovnikov/oz-time.git"
+    },
+    "type": "module",
+    "main": "./src/index.js",
+    "exports": {
+        ".": "./src/index.js"
+    },
+    "files": [
+        "src",
+        "README.md"
+    ],
+    "sideEffects": false,
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build",
+        "test": "vitest",
+        "test:run": "vitest run",
+        "test:coverage": "vitest run --coverage",
+        "docs": "jsdoc -c jsdoc.json",
+        "docs:clean": "rimraf docs",
+        "docs:build": "npm run docs:clean && npm run docs",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "date",
+        "time",
+        "datetime"
+    ],
+    "author": "",
+    "license": "ISC",
+    "devDependencies": {
+        "@vitest/coverage-v8": "^4.1.7",
+        "@vitest/ui": "^4.1.7",
+        "docdash": "^2.0.2",
+        "jsdoc": "^4.0.5",
+        "vite": "^8.0.14",
+        "vitest": "^4.1.7"
+    }
+}