@alexstukovnikov/oz-time 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +70 -251
  2. package/package.json +1 -1
  3. package/src/core/core.js +218 -62
package/README.md CHANGED
@@ -4,7 +4,8 @@ JavaScript-библиотека для работы с датой и време
4
4
 
5
5
  `OzTime` предоставляет неизменяемые объекты времени, фабричные функции создания экземпляров, арифметику по фиксированным и календарным единицам, сравнение, форматирование, работу с часовыми поясами, интервалы и длительности.
6
6
 
7
- [Полная документация API](https://AlexStukovnikov.github.io/oz-time/)
7
+ - Документация API: [AlexStukovnikov.github.io/oz-time](https://AlexStukovnikov.github.io/oz-time/)
8
+ - Пакет npm: [`@alexstukovnikov/oz-time`](https://www.npmjs.com/package/@alexstukovnikov/oz-time)
8
9
 
9
10
  ## Содержание
10
11
 
@@ -12,20 +13,16 @@ JavaScript-библиотека для работы с датой и време
12
13
  - [Возможности](#возможности)
13
14
  - [Установка](#установка)
14
15
  - [Быстрый старт](#быстрый-старт)
15
- - [Что использовать в каком случае](#что-использовать-в-каком-случае)
16
+ - [Основные сценарии](#основные-сценарии)
16
17
  - [Создание экземпляров](#создание-экземпляров)
17
18
  - [Арифметика](#арифметика)
18
19
  - [Сравнение](#сравнение)
19
20
  - [Форматирование](#форматирование)
20
21
  - [Часовые пояса](#часовые-пояса)
21
- - [Интервалы](#интервалы)
22
- - [Длительности](#длительности)
22
+ - [Интервалы и длительности](#интервалы-и-длительности)
23
23
  - [Поддерживаемые единицы времени](#поддерживаемые-единицы-времени)
24
24
  - [Токены форматирования](#токены-форматирования)
25
- - [Публичный API](#публичный-api)
26
25
  - [FAQ](#faq)
27
- - [Разработка](#разработка)
28
- - [Генерация документации](#генерация-документации)
29
26
  - [Ограничения и особенности](#ограничения-и-особенности)
30
27
  - [Лицензия](#лицензия)
31
28
 
@@ -50,48 +47,21 @@ JavaScript-библиотека для работы с датой и време
50
47
  ## Возможности
51
48
 
52
49
  - Неизменяемые экземпляры `OzTime`
53
- - Фабричные функции:
54
- - `now`
55
- - `fromTimestamp`
56
- - `fromDate`
57
- - `fromISO`
58
- - `fromComponents`
59
- - Арифметика по времени:
60
- - `add`
61
- - `subtract`
62
- - Сравнение:
63
- - `isSame`
64
- - `isBefore`
65
- - `isAfter`
66
- - `isBetween`
50
+ - Фабричные функции: `now`, `fromTimestamp`, `fromDate`, `fromISO`, `fromComponents`
51
+ - Арифметика по времени: `add`, `subtract`
52
+ - Сравнение: `isSame`, `isBefore`, `isAfter`, `isBetween`
67
53
  - Форматирование по шаблону
68
- - Работа с часовыми поясами:
69
- - `setTimezone`
70
- - `getTimezoneOffset`
71
- - Интервалы:
72
- - `Interval`
73
- - `interval`
74
- - Длительности:
75
- - `Duration`
76
- - `duration`
77
- - Календарные утилиты:
78
- - `isLeapYear`
79
- - `daysInMonth`
54
+ - Работа с часовыми поясами: `setTimezone`, `getTimezoneOffset`
55
+ - Интервалы: `Interval`, `interval`
56
+ - Длительности: `Duration`, `duration`
57
+ - Календарные утилиты: `isLeapYear`, `daysInMonth`
80
58
 
81
59
  ## Установка
82
60
 
83
- ### Как зависимость проекта
84
-
85
61
  ```bash
86
62
  npm install @alexstukovnikov/oz-time
87
63
  ```
88
64
 
89
- ### Для локальной разработки
90
-
91
- ```bash
92
- npm install
93
- ```
94
-
95
65
  ## Быстрый старт
96
66
 
97
67
  ```js
@@ -114,107 +84,72 @@ const oneHour = duration(1, 'hour');
114
84
  console.log(oneHour.asMinutes()); // ожидаемый результат: 60
115
85
  ```
116
86
 
117
- ## Что использовать в каком случае
118
-
119
- | Сценарий | Что использовать | Почему |
120
- | ----------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------ |
121
- | Нужен текущий момент времени | `now()` | Самый простой способ получить новый экземпляр `OzTime` для текущего момента. |
122
- | Есть Unix timestamp в миллисекундах | `fromTimestamp()` | Подходит для работы с временем из API, БД и системных источников. |
123
- | Есть нативный `Date` | `fromDate()` | Удобно интегрировать библиотеку в существующий код на JavaScript. |
124
- | Есть ISO-строка | `fromISO()` | Лучший вариант для внешних API и сериализованных значений времени. |
125
- | Нужно создать дату вручную из компонентов | `fromComponents()` | Подходит, когда год, месяц, день и время приходят по отдельности. |
126
- | Нужно прибавить или вычесть время | `add()` / `subtract()` | Возвращают новый экземпляр и не изменяют исходный объект. |
127
- | Нужно сравнить два значения | `isSame()` / `isBefore()` / `isAfter()` | Дают читаемый API для логики сравнения. |
128
- | Нужно проверить попадание в диапазон | `isBetween()` | Удобнее, чем писать проверку вручную. |
129
- | Нужно получить красивую строку | `format()` | Форматирование по шаблону с токенами. |
130
- | Нужно изменить отображаемый часовой пояс | `setTimezone()` | Меняет timezone у нового экземпляра, не меняя абсолютный момент времени. |
131
- | Нужно узнать смещение UTC | `getTimezoneOffset()` | Полезно для отображения, отладки и расчётов. |
132
- | Нужно описать диапазон времени | `Interval` / `interval()` | Подходит для проверки попадания, пересечений и длительности интервала. |
133
- | Нужно описать фиксированную длительность | `Duration` / `duration()` | Удобно для преобразования между миллисекундами, секундами, минутами, часами и днями. |
134
- | Нужно проверить високосный год | `isLeapYear()` | Простая календарная утилита. |
135
- | Нужно узнать число дней в месяце | `daysInMonth()` | Удобно для валидации и генерации дат. |
136
-
137
- ## Создание экземпляров
138
-
139
- ### `now(timezone?, locale?)`
140
-
141
- Создаёт экземпляр `OzTime` для текущего момента времени.
87
+ ### Цепочка операций
142
88
 
143
89
  ```js
144
- import { now } from '@alexstukovnikov/oz-time';
145
-
146
- const current = now('Europe/Moscow', 'ru-RU');
147
- console.log(current.getTimezone()); // ожидаемый результат: Europe/Moscow
148
- ```
149
-
150
- ### `fromTimestamp(timestamp, timezone?, locale?)`
151
-
152
- Создаёт экземпляр из Unix timestamp в миллисекундах.
153
-
154
- ```js
155
- import { fromTimestamp } from '@alexstukovnikov/oz-time';
156
-
157
- const time = fromTimestamp(1716638400000, 'UTC', 'ru-RU');
158
- console.log(time.toISOString()); // ожидаемый результат: 2024-05-25T12:00:00.000Z
159
- ```
160
-
161
- ### `fromDate(date, timezone?, locale?)`
162
-
163
- Создаёт экземпляр из объекта `Date`.
90
+ import { fromISO } from '@alexstukovnikov/oz-time';
164
91
 
165
- ```js
166
- import { fromDate } from '@alexstukovnikov/oz-time';
92
+ const result = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU')
93
+ .add(1, 'day')
94
+ .add(2, 'hour')
95
+ .subtract(30, 'minute')
96
+ .setTimezone('Europe/Moscow')
97
+ .format('DD.MM.YYYY HH:mm:ss');
167
98
 
168
- const time = fromDate(new Date('2024-05-25T12:00:00Z'), 'UTC', 'ru-RU');
169
- console.log(time.toTimestamp()); // ожидаемый результат: 1716638400000
99
+ console.log(result);
170
100
  ```
171
101
 
172
- ### `fromISO(isoString, timezone?, locale?)`
102
+ ## Основные сценарии
103
+
104
+ | Сценарий | Что использовать | Почему |
105
+ | ----------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
106
+ | Нужен текущий момент времени | `now()` | Самый простой способ получить новый экземпляр `OzTime` для текущего момента |
107
+ | Есть Unix timestamp в миллисекундах | `fromTimestamp()` | Подходит для работы с временем из API, БД и системных источников |
108
+ | Есть нативный `Date` | `fromDate()` | Удобно интегрировать библиотеку в существующий JavaScript-код |
109
+ | Есть ISO-строка | `fromISO()` | Подходит для внешних API и сериализованных значений времени |
110
+ | Нужно создать дату вручную из компонентов | `fromComponents()` | Удобно, когда год, месяц, день и время приходят по отдельности |
111
+ | Нужно прибавить или вычесть время | `add()` / `subtract()` | Возвращают новый экземпляр и не изменяют исходный объект |
112
+ | Нужно сравнить два значения | `isSame()` / `isBefore()` / `isAfter()` | Дают читаемый API для логики сравнения |
113
+ | Нужно проверить попадание в диапазон | `isBetween()` | Удобнее, чем писать проверку вручную |
114
+ | Нужно получить строковое представление | `format()` | Форматирование по шаблону с токенами |
115
+ | Нужно изменить отображаемый часовой пояс | `setTimezone()` | Меняет timezone у нового экземпляра, не меняя абсолютный момент времени |
116
+ | Нужно узнать смещение относительно UTC | `getTimezoneOffset()` | Полезно для отображения, отладки и расчётов |
117
+ | Нужно описать диапазон времени | `Interval` / `interval()` | Подходит для проверки попадания, пересечений и длительности интервала |
118
+ | Нужно описать фиксированную длительность | `Duration` / `duration()` | Удобно для преобразования между миллисекундами, секундами, минутами, часами и днями |
119
+ | Нужно проверить високосный год | `isLeapYear()` | Простая календарная утилита |
120
+ | Нужно узнать число дней в месяце | `daysInMonth()` | Удобно для валидации и генерации дат |
173
121
 
174
- Создаёт экземпляр из ISO-строки.
122
+ ## Создание экземпляров
175
123
 
176
124
  ```js
177
- import { fromISO } from '@alexstukovnikov/oz-time';
125
+ import { now, fromTimestamp, fromDate, fromISO, fromComponents } from '@alexstukovnikov/oz-time';
178
126
 
179
- const time = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
180
- console.log(time.format('DD.MM.YYYY HH:mm')); // ожидаемый результат: 25.05.2024 12:00
127
+ const a = now('Europe/Moscow', 'ru-RU');
128
+ const b = fromTimestamp(1716638400000, 'UTC', 'ru-RU');
129
+ const c = fromDate(new Date('2024-05-25T12:00:00Z'), 'UTC', 'ru-RU');
130
+ const d = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
131
+ const e = fromComponents(2024, 5, 25, 12, 0, 0, 0, 'UTC', 'ru-RU');
181
132
  ```
182
133
 
183
- ### `fromComponents(year, month, day, hour?, minute?, second?, ms?, timezone?, locale?)`
184
-
185
- Создаёт экземпляр из отдельных компонентов даты и времени.
186
-
187
- ```js
188
- import { fromComponents } from '@alexstukovnikov/oz-time';
189
-
190
- const time = fromComponents(2024, 5, 25, 12, 0, 0, 0, 'UTC', 'ru-RU');
191
- console.log(time.toISOString()); // ожидаемый результат: 2024-05-25T12:00:00.000Z
192
- ```
134
+ - `now()` — создаёт экземпляр `OzTime` для текущего момента времени.
135
+ - `fromTimestamp()` — создаёт экземпляр из Unix timestamp в миллисекундах.
136
+ - `fromDate()` — создаёт экземпляр из объекта `Date`.
137
+ - `fromISO()` — создаёт экземпляр из ISO-строки.
138
+ - `fromComponents()` — создаёт экземпляр из отдельных компонентов даты и времени.
193
139
 
194
140
  ## Арифметика
195
141
 
196
142
  Все арифметические операции возвращают новый экземпляр `OzTime` и не изменяют исходный объект.
197
143
 
198
- ### Добавление времени
199
-
200
- ```js
201
- import { fromISO } from '@alexstukovnikov/oz-time';
202
-
203
- const time = fromISO('2024-05-25T12:00:00Z');
204
- const result = time.add(1, 'day');
205
-
206
- console.log(result.toISOString()); // ожидаемый результат: 2024-05-26T12:00:00.000Z
207
- ```
208
-
209
- ### Вычитание времени
144
+ ### Добавление и вычитание
210
145
 
211
146
  ```js
212
147
  import { fromISO } from '@alexstukovnikov/oz-time';
213
148
 
214
149
  const time = fromISO('2024-05-25T12:00:00Z');
215
- const result = time.subtract(2, 'hour');
216
150
 
217
- console.log(result.toISOString()); // ожидаемый результат: 2024-05-25T10:00:00.000Z
151
+ console.log(time.add(1, 'day').toISOString()); // ожидаемый результат: 2024-05-26T12:00:00.000Z
152
+ console.log(time.subtract(2, 'hour').toISOString()); // ожидаемый результат: 2024-05-25T10:00:00.000Z
218
153
  ```
219
154
 
220
155
  ### Разница между датами
@@ -241,54 +176,22 @@ console.log(result.toISOString()); // ожидаемый результат: 202
241
176
 
242
177
  ## Сравнение
243
178
 
244
- ### `isSame`
245
-
246
179
  ```js
247
180
  import { fromISO } from '@alexstukovnikov/oz-time';
248
181
 
249
182
  const a = fromISO('2024-05-25T12:00:00.100Z');
250
183
  const b = fromISO('2024-05-25T12:00:00.900Z');
184
+ const c = fromISO('2024-05-26T12:00:00Z');
251
185
 
252
186
  console.log(a.isSame(b, 'second')); // ожидаемый результат: true
253
- ```
254
-
255
- ### `isBefore`
256
-
257
- ```js
258
- import { fromISO } from '@alexstukovnikov/oz-time';
259
-
260
- const a = fromISO('2024-05-25T12:00:00Z');
261
- const b = fromISO('2024-05-26T12:00:00Z');
262
-
263
- console.log(a.isBefore(b)); // ожидаемый результат: true
264
- ```
265
-
266
- ### `isAfter`
267
-
268
- ```js
269
- import { fromISO } from '@alexstukovnikov/oz-time';
270
-
271
- const a = fromISO('2024-05-26T12:00:00Z');
272
- const b = fromISO('2024-05-25T12:00:00Z');
273
-
274
- console.log(a.isAfter(b)); // ожидаемый результат: true
275
- ```
276
-
277
- ### `isBetween`
278
-
279
- ```js
280
- import { fromISO } from '@alexstukovnikov/oz-time';
281
-
282
- const target = fromISO('2024-05-25T12:00:00Z');
283
- const start = fromISO('2024-05-25T10:00:00Z');
284
- const end = fromISO('2024-05-25T14:00:00Z');
285
-
286
- console.log(target.isBetween(start, end)); // ожидаемый результат: true
187
+ console.log(a.isBefore(c)); // ожидаемый результат: true
188
+ console.log(c.isAfter(a)); // ожидаемый результат: true
189
+ console.log(a.isBetween(a.subtract(1, 'day'), c)); // ожидаемый результат: true
287
190
  ```
288
191
 
289
192
  ## Форматирование
290
193
 
291
- Функция `format()` и метод `OzTime#format()` поддерживают шаблоны.
194
+ Функция `format()` и метод `OzTime#format()` поддерживают шаблоны форматирования.
292
195
 
293
196
  ```js
294
197
  import { fromISO } from '@alexstukovnikov/oz-time';
@@ -323,7 +226,9 @@ const time = fromISO('2024-05-25T12:00:00Z', 'Europe/Moscow', 'ru-RU');
323
226
  console.log(time.getTimezoneOffset()); // ожидаемый результат: 180
324
227
  ```
325
228
 
326
- ## Интервалы
229
+ ## Интервалы и длительности
230
+
231
+ ### Интервалы
327
232
 
328
233
  Интервал представляет диапазон между двумя экземплярами `OzTime`, включая границы.
329
234
 
@@ -350,7 +255,7 @@ const b = new Interval(fromISO('2024-05-25T11:00:00Z'), fromISO('2024-05-25T13:0
350
255
  console.log(a.overlaps(b)); // ожидаемый результат: true
351
256
  ```
352
257
 
353
- ## Длительности
258
+ ### Длительности
354
259
 
355
260
  `Duration` используется для работы с фиксированными единицами времени.
356
261
 
@@ -425,44 +330,6 @@ console.log(a.add(b).asMinutes()); // ожидаемый результат: 75
425
330
  | `SSS` | Миллисекунды | `123` |
426
331
  | `A` | AM/PM | `AM`, `PM` |
427
332
 
428
- ## Публичный API
429
-
430
- ### Core
431
-
432
- - `OzTime`
433
- - `now`
434
- - `fromTimestamp`
435
- - `fromDate`
436
- - `fromISO`
437
- - `fromComponents`
438
-
439
- ### Арифметика и сравнение
440
-
441
- - `add`
442
- - `subtract`
443
- - `isSame`
444
- - `isBefore`
445
- - `isAfter`
446
- - `isBetween`
447
-
448
- ### Форматирование и часовые пояса
449
-
450
- - `format`
451
- - `setTimezone`
452
- - `getTimezoneOffset`
453
-
454
- ### Интервалы и длительности
455
-
456
- - `Interval`
457
- - `interval`
458
- - `Duration`
459
- - `duration`
460
-
461
- ### Календарные утилиты
462
-
463
- - `isLeapYear`
464
- - `daysInMonth`
465
-
466
333
  ## FAQ
467
334
 
468
335
  ### Чем `fromISO()` отличается от `fromTimestamp()`?
@@ -504,63 +371,15 @@ console.log(a.add(b).asMinutes()); // ожидаемый результат: 75
504
371
 
505
372
  Используй `Interval`, когда есть начало и конец диапазона. Используй `Duration`, когда нужна именно фиксированная длина времени, например 2 часа, 30 минут или 7 дней.
506
373
 
507
- ## Разработка
508
-
509
- ### Запуск dev-режима
510
-
511
- ```bash
512
- npm run dev
513
- ```
514
-
515
- ### Сборка библиотеки
516
-
517
- ```bash
518
- npm run build
519
- ```
520
-
521
- ### Запуск тестов
522
-
523
- ```bash
524
- npm test
525
- ```
526
-
527
- ### Однократный запуск тестов
528
-
529
- ```bash
530
- npm run test:run
531
- ```
532
-
533
- ### Покрытие тестами
534
-
535
- ```bash
536
- npm run test:coverage
537
- ```
538
-
539
- ## Генерация документации
540
-
541
- ### Генерация HTML-документации JSDoc
542
-
543
- ```bash
544
- npm run docs
545
- ```
546
-
547
- ### Полная пересборка документации
548
-
549
- ```bash
550
- npm run docs:build
551
- ```
552
-
553
- После генерации документация будет находиться в папке `docs/`.
554
-
555
374
  ## Ограничения и особенности
556
375
 
557
- - Внутреннее значение времени хранится как Unix timestamp в миллисекундах.
558
- - Часовой пояс не меняет абсолютный момент времени, а влияет на форматирование и вычисление смещения.
559
- - Методы `add`, `subtract`, `setTimezone` и другие операции не изменяют текущий экземпляр, а возвращают новый.
560
- - `Duration` поддерживает только фиксированные единицы времени.
561
- - Календарная арифметика через `month` и `year` учитывает реальную длину месяцев.
562
- - Разница в `month` и `year` считается календарно, а не через точное число миллисекунд.
563
- - Поддержка часовых поясов зависит от `Intl` и доступных IANA time zone в среде выполнения.
376
+ - Внутреннее значение времени хранится как Unix timestamp в миллисекундах
377
+ - Часовой пояс не меняет абсолютный момент времени, а влияет на форматирование и вычисление смещения
378
+ - Методы `add`, `subtract`, `setTimezone` и другие операции не изменяют текущий экземпляр, а возвращают новый
379
+ - `Duration` поддерживает только фиксированные единицы времени
380
+ - Календарная арифметика через `month` и `year` учитывает реальную длину месяцев
381
+ - Разница в `month` и `year` считается календарно, а не через точное число миллисекунд
382
+ - Поддержка часовых поясов зависит от `Intl` и доступных IANA time zone в среде выполнения
564
383
 
565
384
  ## Лицензия
566
385
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alexstukovnikov/oz-time",
3
- "version": "1.0.1",
3
+ "version": "1.0.2",
4
4
  "description": "Lightweight JavaScript date-time library",
5
5
  "repository": {
6
6
  "type": "git",
package/src/core/core.js CHANGED
@@ -2,7 +2,16 @@ import { add, subtract } from '../modules/arithmetic.js';
2
2
  import { format } from '../modules/format.js';
3
3
  import { isSame, isBefore, isAfter, isBetween } from '../modules/compare.js';
4
4
  import { setTimezone, getTimezoneOffset } from '../modules/timezone.js';
5
+ import { interval as createInterval } from '../modules/interval.js';
6
+ import { duration as createDuration } from '../modules/duration.js';
5
7
  import { diff } from '../utils/calendar.js';
8
+ import {
9
+ now as createNow,
10
+ fromTimestamp as createFromTimestamp,
11
+ fromDate as createFromDate,
12
+ fromISO as createFromISO,
13
+ fromComponents as createFromComponents,
14
+ } from './factory.js';
6
15
 
7
16
  /**
8
17
  * Основной модуль, содержащий класс {@link OzTime}.
@@ -80,7 +89,28 @@ function assertValidLocale(locale) {
80
89
  * Неизменяемый объект даты и времени на основе UTC timestamp
81
90
  * с дополнительными метаданными о часовом поясе и локали.
82
91
  *
92
+ * Класс поддерживает как создание экземпляров через конструктор,
93
+ * так и через статические фабричные методы.
94
+ *
83
95
  * @class
96
+ * @example
97
+ * import { OzTime } from '@alexstukovnikov/oz-time';
98
+ *
99
+ * const time = OzTime.fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
100
+ * console.log(time.toISOString()); // ожидаемый результат: 2024-05-25T12:00:00.000Z
101
+ *
102
+ * @example
103
+ * import { OzTime } from '@alexstukovnikov/oz-time';
104
+ *
105
+ * const result = OzTime
106
+ * .fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU')
107
+ * .add(1, 'day')
108
+ * .add(2, 'hour')
109
+ * .subtract(30, 'minute')
110
+ * .setTimezone('Europe/Moscow')
111
+ * .format('DD.MM.YYYY HH:mm:ss');
112
+ *
113
+ * console.log(result);
84
114
  */
85
115
  export class OzTime {
86
116
  /**
@@ -101,14 +131,139 @@ export class OzTime {
101
131
  this._locale = locale;
102
132
  }
103
133
 
134
+ /**
135
+ * Создаёт экземпляр {@link OzTime} для текущего момента времени.
136
+ *
137
+ * @param {TimezoneString} [timezone='UTC'] - Часовой пояс в формате IANA.
138
+ * @param {LocaleString} [locale='en-US'] - Локаль форматирования.
139
+ * @returns {OzTime} Экземпляр с текущим временем.
140
+ * @example
141
+ * import { OzTime } from '@alexstukovnikov/oz-time';
142
+ *
143
+ * const current = OzTime.now('Europe/Moscow', 'ru-RU');
144
+ * console.log(current.getTimezone()); // ожидаемый результат: Europe/Moscow
145
+ */
146
+ static now(timezone = 'UTC', locale = 'en-US') {
147
+ return createNow(timezone, locale);
148
+ }
149
+
150
+ /**
151
+ * Создаёт экземпляр {@link OzTime} из Unix timestamp в миллисекундах.
152
+ *
153
+ * @param {number} timestamp - Unix timestamp в миллисекундах.
154
+ * @param {TimezoneString} [timezone='UTC'] - Часовой пояс в формате IANA.
155
+ * @param {LocaleString} [locale='en-US'] - Локаль форматирования.
156
+ * @returns {OzTime} Экземпляр времени.
157
+ * @example
158
+ * import { OzTime } from '@alexstukovnikov/oz-time';
159
+ *
160
+ * const time = OzTime.fromTimestamp(1716638400000, 'UTC', 'ru-RU');
161
+ * console.log(time.toISOString()); // ожидаемый результат: 2024-05-25T12:00:00.000Z
162
+ */
163
+ static fromTimestamp(timestamp, timezone = 'UTC', locale = 'en-US') {
164
+ return createFromTimestamp(timestamp, timezone, locale);
165
+ }
166
+
167
+ /**
168
+ * Создаёт экземпляр {@link OzTime} из объекта {@link Date}.
169
+ *
170
+ * @param {Date} date - Нативный объект Date.
171
+ * @param {TimezoneString} [timezone='UTC'] - Часовой пояс в формате IANA.
172
+ * @param {LocaleString} [locale='en-US'] - Локаль форматирования.
173
+ * @returns {OzTime} Экземпляр времени.
174
+ * @example
175
+ * import { OzTime } from '@alexstukovnikov/oz-time';
176
+ *
177
+ * const time = OzTime.fromDate(new Date('2024-05-25T12:00:00Z'), 'UTC', 'ru-RU');
178
+ * console.log(time.toTimestamp()); // ожидаемый результат: 1716638400000
179
+ */
180
+ static fromDate(date, timezone = 'UTC', locale = 'en-US') {
181
+ return createFromDate(date, timezone, locale);
182
+ }
183
+
184
+ /**
185
+ * Создаёт экземпляр {@link OzTime} из ISO-строки.
186
+ *
187
+ * @param {string} isoString - Строка даты и времени в формате ISO 8601.
188
+ * @param {TimezoneString} [timezone='UTC'] - Часовой пояс в формате IANA.
189
+ * @param {LocaleString} [locale='en-US'] - Локаль форматирования.
190
+ * @returns {OzTime} Экземпляр времени.
191
+ * @example
192
+ * import { OzTime } from '@alexstukovnikov/oz-time';
193
+ *
194
+ * const time = OzTime.fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
195
+ * console.log(time.format('DD.MM.YYYY HH:mm')); // ожидаемый результат: 25.05.2024 12:00
196
+ */
197
+ static fromISO(isoString, timezone = 'UTC', locale = 'en-US') {
198
+ return createFromISO(isoString, timezone, locale);
199
+ }
200
+
201
+ /**
202
+ * Создаёт экземпляр {@link OzTime} из отдельных компонентов даты и времени.
203
+ *
204
+ * @param {number} year - Год.
205
+ * @param {number} month - Месяц от 1 до 12.
206
+ * @param {number} day - День месяца.
207
+ * @param {number} [hour=0] - Час от 0 до 23.
208
+ * @param {number} [minute=0] - Минута от 0 до 59.
209
+ * @param {number} [second=0] - Секунда от 0 до 59.
210
+ * @param {number} [ms=0] - Миллисекунда от 0 до 999.
211
+ * @param {TimezoneString} [timezone='UTC'] - Часовой пояс в формате IANA.
212
+ * @param {LocaleString} [locale='en-US'] - Локаль форматирования.
213
+ * @returns {OzTime} Экземпляр времени.
214
+ * @example
215
+ * import { OzTime } from '@alexstukovnikov/oz-time';
216
+ *
217
+ * const time = OzTime.fromComponents(2024, 5, 25, 12, 0, 0, 0, 'UTC', 'ru-RU');
218
+ * console.log(time.toISOString()); // ожидаемый результат: 2024-05-25T12:00:00.000Z
219
+ */
220
+ static fromComponents(year, month, day, hour = 0, minute = 0, second = 0, ms = 0, timezone = 'UTC', locale = 'en-US') {
221
+ return createFromComponents(year, month, day, hour, minute, second, ms, timezone, locale);
222
+ }
223
+
224
+ /**
225
+ * Создаёт новый интервал между двумя значениями {@link OzTime}.
226
+ *
227
+ * @param {OzTime} start - Начало интервала.
228
+ * @param {OzTime} end - Конец интервала.
229
+ * @returns {Interval} Экземпляр интервала.
230
+ * @example
231
+ * import { OzTime } from '@alexstukovnikov/oz-time';
232
+ *
233
+ * const start = OzTime.fromISO('2024-05-25T10:00:00Z');
234
+ * const end = OzTime.fromISO('2024-05-25T12:00:00Z');
235
+ * const range = OzTime.interval(start, end);
236
+ *
237
+ * console.log(range.duration('hour')); // ожидаемый результат: 2
238
+ */
239
+ static interval(start, end) {
240
+ return createInterval(start, end);
241
+ }
242
+
243
+ /**
244
+ * Создаёт новую длительность из фиксированной единицы времени.
245
+ *
246
+ * @param {number} amount - Количество единиц времени.
247
+ * @param {TimeUnit|string} unit - Единица времени.
248
+ * @returns {Duration} Экземпляр длительности.
249
+ * @example
250
+ * import { OzTime } from '@alexstukovnikov/oz-time';
251
+ *
252
+ * const value = OzTime.duration(2, 'hour');
253
+ * console.log(value.asMinutes()); // ожидаемый результат: 120
254
+ */
255
+ static duration(amount, unit) {
256
+ return createDuration(amount, unit);
257
+ }
258
+
104
259
  /**
105
260
  * Возвращает внутренний Unix timestamp экземпляра в миллисекундах.
106
261
  *
107
262
  * @returns {number} Unix timestamp в миллисекундах.
108
263
  * @example
109
- * import { fromISO } from '@alexstukovnikov/oz-time';
264
+ * import { OzTime } from '@alexstukovnikov/oz-time';
110
265
  *
111
- * const time = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
266
+ * const time = OzTime.fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
112
267
  * console.log(time.getTimestamp()); // ожидаемый результат: 1716638400000
113
268
  */
114
269
  getTimestamp() {
@@ -120,9 +275,9 @@ export class OzTime {
120
275
  *
121
276
  * @returns {TimezoneString} Идентификатор часового пояса.
122
277
  * @example
123
- * import { fromISO } from '@alexstukovnikov/oz-time';
278
+ * import { OzTime } from '@alexstukovnikov/oz-time';
124
279
  *
125
- * const time = fromISO('2024-05-25T12:00:00Z', 'Europe/Moscow', 'ru-RU');
280
+ * const time = OzTime.fromISO('2024-05-25T12:00:00Z', 'Europe/Moscow', 'ru-RU');
126
281
  * console.log(time.getTimezone()); // ожидаемый результат: Europe/Moscow
127
282
  */
128
283
  getTimezone() {
@@ -134,9 +289,9 @@ export class OzTime {
134
289
  *
135
290
  * @returns {LocaleString} Строка локали.
136
291
  * @example
137
- * import { fromISO } from '@alexstukovnikov/oz-time';
292
+ * import { OzTime } from '@alexstukovnikov/oz-time';
138
293
  *
139
- * const time = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
294
+ * const time = OzTime.fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
140
295
  * console.log(time.getLocale()); // ожидаемый результат: ru-RU
141
296
  */
142
297
  getLocale() {
@@ -144,12 +299,14 @@ export class OzTime {
144
299
  }
145
300
 
146
301
  /**
147
- * Преобразует экземпляр в числовой timestamp.
302
+ * Возвращает внутренний Unix timestamp экземпляра в миллисекундах.
148
303
  *
149
304
  * @returns {number} Unix timestamp в миллисекундах.
150
305
  * @example
151
- * const time = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
152
- console.log(time.toTimestamp()); // ожидаемый результат: 1716638400000
306
+ * import { OzTime } from '@alexstukovnikov/oz-time';
307
+ *
308
+ * const time = OzTime.fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
309
+ * console.log(time.toTimestamp()); // ожидаемый результат: 1716638400000
153
310
  */
154
311
  toTimestamp() {
155
312
  return this._timestamp;
@@ -160,9 +317,9 @@ console.log(time.toTimestamp()); // ожидаемый результат: 17166
160
317
  *
161
318
  * @returns {string} Строковое представление даты и времени в формате ISO 8601.
162
319
  * @example
163
- * import { fromComponents } from '@alexstukovnikov/oz-time';
320
+ * import { OzTime } from '@alexstukovnikov/oz-time';
164
321
  *
165
- * const time = fromComponents(2024, 5, 25, 12, 0, 0, 0, 'UTC', 'ru-RU');
322
+ * const time = OzTime.fromComponents(2024, 5, 25, 12, 0, 0, 0, 'UTC', 'ru-RU');
166
323
  * console.log(time.toISOString()); // ожидаемый результат: 2024-05-25T12:00:00.000Z
167
324
  */
168
325
  toISOString() {
@@ -179,10 +336,12 @@ console.log(time.toTimestamp()); // ожидаемый результат: 17166
179
336
  * @param {TimeUnit|string} unit - Единица времени.
180
337
  * @returns {OzTime} Новый экземпляр OzTime с timestamp, сдвинутым вперёд.
181
338
  * @example
182
- * import { fromISO } from '@alexstukovnikov/oz-time';
339
+ * import { OzTime } from '@alexstukovnikov/oz-time';
340
+ *
341
+ * const nextDay = OzTime
342
+ * .fromISO('2024-05-25T12:00:00Z')
343
+ * .add(1, 'day');
183
344
  *
184
- * const time = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
185
- * const nextDay = time.add(1, 'day');
186
345
  * console.log(nextDay.toISOString()); // ожидаемый результат: 2024-05-26T12:00:00.000Z
187
346
  */
188
347
  add(amount, unit) {
@@ -199,10 +358,12 @@ console.log(time.toTimestamp()); // ожидаемый результат: 17166
199
358
  * @param {TimeUnit|string} unit - Единица времени.
200
359
  * @returns {OzTime} Новый экземпляр OzTime с timestamp, сдвинутым назад.
201
360
  * @example
202
- * import { fromISO } from '@alexstukovnikov/oz-time';
361
+ * import { OzTime } from '@alexstukovnikov/oz-time';
362
+ *
363
+ * const prevHour = OzTime
364
+ * .fromISO('2024-05-25T12:00:00Z')
365
+ * .subtract(1, 'hour');
203
366
  *
204
- * const time = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
205
- * const prevHour = time.subtract(1, 'hour');
206
367
  * console.log(prevHour.toISOString()); // ожидаемый результат: 2024-05-25T11:00:00.000Z
207
368
  */
208
369
  subtract(amount, unit) {
@@ -210,33 +371,33 @@ console.log(time.toTimestamp()); // ожидаемый результат: 17166
210
371
  }
211
372
 
212
373
  /**
213
- * Возвращает строковое представление текущего значения времени по заданному шаблону.
374
+ * Форматирует текущее значение времени по заданному шаблону.
214
375
  *
215
376
  * @param {string} template - Строка шаблона форматирования.
216
- * @param {LocaleString} [locale] - Локаль, которая переопределяет локаль экземпляра.
377
+ * @param {LocaleString} [locale] - Локаль, которая временно переопределяет локаль экземпляра.
217
378
  * @returns {string} Отформатированная строка.
218
379
  * @example
219
- * import { fromISO } from '@alexstukovnikov/oz-time';
380
+ * import { OzTime } from '@alexstukovnikov/oz-time';
220
381
  *
221
- * const time = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
222
- * console.log(time.format('DD.MM.YYYY HH:mm')); // ожидаемый результат: 25.05.2024 12:00
382
+ * const value = OzTime.fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
383
+ * console.log(value.format('DD.MM.YYYY HH:mm')); // ожидаемый результат: 25.05.2024 12:00
223
384
  */
224
385
  format(template, locale) {
225
386
  return format(this, template, locale);
226
387
  }
227
388
 
228
389
  /**
229
- * Проверяет, совпадает ли текущее значение с другим значением времени
390
+ * Проверяет, совпадает ли текущее значение с другим временем
230
391
  * на заданной точности.
231
392
  *
232
393
  * @param {OzTime} other - Второе значение для сравнения.
233
394
  * @param {TimeUnit|string} [unit='millisecond'] - Точность сравнения.
234
- * @returns {boolean} `true`, если значения совпадают на указанной точности.
395
+ * @returns {boolean} `true`, если значения совпадают.
235
396
  * @example
236
- * import { fromISO } from '@alexstukovnikov/oz-time';
397
+ * import { OzTime } from '@alexstukovnikov/oz-time';
237
398
  *
238
- * const a = fromISO('2024-05-25T12:00:00.100Z');
239
- * const b = fromISO('2024-05-25T12:00:00.900Z');
399
+ * const a = OzTime.fromISO('2024-05-25T12:00:00.100Z');
400
+ * const b = OzTime.fromISO('2024-05-25T12:00:00.900Z');
240
401
  * console.log(a.isSame(b, 'second')); // ожидаемый результат: true
241
402
  */
242
403
  isSame(other, unit = 'millisecond') {
@@ -244,17 +405,16 @@ console.log(time.toTimestamp()); // ожидаемый результат: 17166
244
405
  }
245
406
 
246
407
  /**
247
- * Проверяет, находится ли текущее значение раньше другого значения времени
248
- * на заданной точности.
408
+ * Проверяет, находится ли текущее значение раньше другого времени.
249
409
  *
250
410
  * @param {OzTime} other - Второе значение для сравнения.
251
411
  * @param {TimeUnit|string} [unit='millisecond'] - Точность сравнения.
252
- * @returns {boolean} `true`, если текущее значение раньше.
412
+ * @returns {boolean} `true`, если текущее значение меньше.
253
413
  * @example
254
- * import { fromISO } from '@alexstukovnikov/oz-time';
414
+ * import { OzTime } from '@alexstukovnikov/oz-time';
255
415
  *
256
- * const a = fromISO('2024-05-25T12:00:00Z');
257
- * const b = fromISO('2024-05-26T12:00:00Z');
416
+ * const a = OzTime.fromISO('2024-05-25T12:00:00Z');
417
+ * const b = a.add(1, 'day');
258
418
  * console.log(a.isBefore(b)); // ожидаемый результат: true
259
419
  */
260
420
  isBefore(other, unit = 'millisecond') {
@@ -262,17 +422,16 @@ console.log(time.toTimestamp()); // ожидаемый результат: 17166
262
422
  }
263
423
 
264
424
  /**
265
- * Проверяет, находится ли текущее значение позже другого значения времени
266
- * на заданной точности.
425
+ * Проверяет, находится ли текущее значение позже другого времени.
267
426
  *
268
427
  * @param {OzTime} other - Второе значение для сравнения.
269
428
  * @param {TimeUnit|string} [unit='millisecond'] - Точность сравнения.
270
- * @returns {boolean} `true`, если текущее значение позже.
429
+ * @returns {boolean} `true`, если текущее значение больше.
271
430
  * @example
272
- * import { fromISO } from '@alexstukovnikov/oz-time';
431
+ * import { OzTime } from '@alexstukovnikov/oz-time';
273
432
  *
274
- * const a = fromISO('2024-05-26T12:00:00Z');
275
- * const b = fromISO('2024-05-25T12:00:00Z');
433
+ * const a = OzTime.fromISO('2024-05-26T12:00:00Z');
434
+ * const b = OzTime.fromISO('2024-05-25T12:00:00Z');
276
435
  * console.log(a.isAfter(b)); // ожидаемый результат: true
277
436
  */
278
437
  isAfter(other, unit = 'millisecond') {
@@ -280,8 +439,7 @@ console.log(time.toTimestamp()); // ожидаемый результат: 17166
280
439
  }
281
440
 
282
441
  /**
283
- * Проверяет, попадает ли текущее значение времени в диапазон между двумя границами
284
- * на заданной точности.
442
+ * Проверяет, попадает ли текущее значение в диапазон между двумя датами.
285
443
  *
286
444
  * @param {OzTime} start - Левая граница диапазона.
287
445
  * @param {OzTime} end - Правая граница диапазона.
@@ -289,11 +447,11 @@ console.log(time.toTimestamp()); // ожидаемый результат: 17166
289
447
  * @param {Inclusivity} [inclusivity='[]'] - Формат включённости границ.
290
448
  * @returns {boolean} `true`, если значение находится внутри диапазона.
291
449
  * @example
292
- * import { fromISO } from '@alexstukovnikov/oz-time';
450
+ * import { OzTime } from '@alexstukovnikov/oz-time';
293
451
  *
294
- * const current = fromISO('2024-05-25T12:00:00Z');
295
- * const start = fromISO('2024-05-25T10:00:00Z');
296
- * const end = fromISO('2024-05-25T14:00:00Z');
452
+ * const current = OzTime.fromISO('2024-05-25T12:00:00Z');
453
+ * const start = current.subtract(1, 'day');
454
+ * const end = current.add(1, 'day');
297
455
  * console.log(current.isBetween(start, end)); // ожидаемый результат: true
298
456
  */
299
457
  isBetween(start, end, unit = 'millisecond', inclusivity = '[]') {
@@ -301,18 +459,17 @@ console.log(time.toTimestamp()); // ожидаемый результат: 17166
301
459
  }
302
460
 
303
461
  /**
304
- * Возвращает новый экземпляр OzTime с тем же timestamp и locale,
305
- * но с другим часовым поясом.
306
- *
307
- * Абсолютный момент времени при этом не изменяется.
462
+ * Возвращает новый экземпляр с тем же timestamp, но другим часовым поясом.
308
463
  *
309
464
  * @param {TimezoneString} timezone - Новый часовой пояс.
310
- * @returns {OzTime} Новый экземпляр OzTime с обновлённым часовым поясом.
465
+ * @returns {OzTime} Новый экземпляр с обновлённым часовым поясом.
311
466
  * @example
312
- * import { fromISO } from '@alexstukovnikov/oz-time';
467
+ * import { OzTime } from '@alexstukovnikov/oz-time';
468
+ *
469
+ * const moscowTime = OzTime
470
+ * .fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU')
471
+ * .setTimezone('Europe/Moscow');
313
472
  *
314
- * const time = fromISO('2024-05-25T12:00:00Z', 'UTC', 'ru-RU');
315
- * const moscowTime = time.setTimezone('Europe/Moscow');
316
473
  * console.log(moscowTime.getTimezone()); // ожидаемый результат: Europe/Moscow
317
474
  */
318
475
  setTimezone(timezone) {
@@ -322,11 +479,11 @@ console.log(time.toTimestamp()); // ожидаемый результат: 17166
322
479
  /**
323
480
  * Возвращает смещение текущего часового пояса относительно UTC в минутах.
324
481
  *
325
- * @returns {number} Смещение в минутах относительно UTC.
482
+ * @returns {number} Смещение в минутах.
326
483
  * @example
327
- * import { fromISO } from '@alexstukovnikov/oz-time';
484
+ * import { OzTime } from '@alexstukovnikov/oz-time';
328
485
  *
329
- * const time = fromISO('2024-05-25T12:00:00Z', 'Europe/Moscow', 'ru-RU');
486
+ * const time = OzTime.fromISO('2024-05-25T12:00:00Z', 'Europe/Moscow', 'ru-RU');
330
487
  * console.log(time.getTimezoneOffset()); // ожидаемый результат: 180
331
488
  */
332
489
  getTimezoneOffset() {
@@ -334,17 +491,16 @@ console.log(time.toTimestamp()); // ожидаемый результат: 17166
334
491
  }
335
492
 
336
493
  /**
337
- * Возвращает числовую разницу между текущим экземпляром и другим значением времени
338
- * в указанной единице измерения.
494
+ * Вычисляет разницу между текущим значением и другим временем.
339
495
  *
340
496
  * @param {OzTime} other - Второе значение для сравнения.
341
497
  * @param {TimeUnit|string} [unit='millisecond'] - Единица измерения разницы.
342
- * @returns {number} Разница между двумя значениями времени.
498
+ * @returns {number} Разница между двумя значениями.
343
499
  * @example
344
- * import { fromISO } from '@alexstukovnikov/oz-time';
500
+ * import { OzTime } from '@alexstukovnikov/oz-time';
345
501
  *
346
- * const start = fromISO('2024-05-25T12:00:00Z');
347
- * const end = fromISO('2024-05-25T14:00:00Z');
502
+ * const start = OzTime.fromISO('2024-05-25T12:00:00Z');
503
+ * const end = start.add(2, 'hour');
348
504
  * console.log(end.diff(start, 'hour')); // ожидаемый результат: 2
349
505
  */
350
506
  diff(other, unit = 'millisecond') {