diff --git a/README.md b/README.md index 06cfb6f..c351736 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ datetime(now, 'time') // '10:29' datetimeTz(now, 'datetime', -7) // '2021-03-14T10:29-07:00' utc(now, 'time') // '09:29Z' -tzOffset(-9, 30) // '-09:30' (Marquesas Islands) +tzOffset(-9, -30) // '-09:30' (Marquesas Islands) duration({ d: 4, h: 3, m: 17 }) // 'P4DT3H17M' const importantMeeting = new DateTime(2021, 12, 17, 19, 00) // 17/11 @@ -209,14 +209,17 @@ import { tzOffset } from 'datetime-attribute' tzOffset(3) // '+03:00' (Moscow) -tzOffset(-9, 30) // '-09:30' (Marquesas Islands) +tzOffset(-9, -30) // '-09:30' (Marquesas Islands) tzOffset(-9.5) // '-09:30' (same with 1 parameter) +tzOffset(5, -30) // '+04:30' (Afghanistan) +tzOffset(5, 30) // '+05:30' (India) + tzOffset(0) // 'Z' (Ghana; 'Z' is equal to '+00:00') // in Belgium tzOffset() // '+01:00' -tzOffset() // '+02:00' (under daylight time saving) +tzOffset() // '+02:00' (under daylight saving time) ``` ### Hours-minutes separator @@ -251,7 +254,7 @@ tzOffset(44) // '+20:00' tzOffset(44, 0, true) // '-04:00' ``` -Curious about timezones? Have a look at [the timezone map](https://fr.m.wikipedia.org/wiki/Fichier:World_Time_Zones_Map.png) and the [daylight time saving chaos](https://en.wikipedia.org/wiki/Daylight_saving_time_by_country). +Curious about timezones? Have a look at [the timezone map](https://fr.m.wikipedia.org/wiki/Fichier:World_Time_Zones_Map.png) and the [daylight saving time chaos](https://en.wikipedia.org/wiki/Daylight_saving_time_by_country). ## Adding a timezone offset to a moment with `datetimeTz()` @@ -296,7 +299,7 @@ datetimeTz(now, 'time', -3, 30) // '23:51-03:30' datetimeTz(now, 'time', -14, 0, true) // '23:51+10:00' ``` -`datetimeTz()` **does not convert** your moment to another timezone: it **only adds the wanted timezone** to the moment. Its purpose is to generate a valid `datetime` attribute saying “here’s a moment, it has this [hours, minutes] timezone offset”. +`datetimeTz()` **does not convert** your moment to another timezone: it **only adds the wanted timezone** to the moment. Its purpose is to generate a valid `datetime` attribute saying “here’s a moment, it has this [hours, minutes and] timezone offset”. Let’s take this sentence and its HTML: diff --git a/src/datetime.test.js b/src/datetime.test.js index 8e33489..ab368ae 100644 --- a/src/datetime.test.js +++ b/src/datetime.test.js @@ -1,7 +1,7 @@ import { describe, expect, test } from 'vitest' import { datetime, datetimeTz, tzOffset, utc } from './index.js' -import { getNormalizeDay } from './utils/date.js' +import { getNormalizedDay } from './utils/date.js' const togoIndependanceDay = new Date(1960, 3, 27) const date = togoIndependanceDay // alias for the sake of brevity @@ -90,7 +90,7 @@ describe('datetime', () => { // 1st day of the year is after Thurdsay test('week on 2021-01-01 is 2020-W53', () => { - expect(getNormalizeDay(january1st2021)).toBeGreaterThan(4) + expect(getNormalizedDay(january1st2021)).toBeGreaterThan(4) expect(datetime(january1st2021, 'week')).toBe('2020-W53') }) @@ -109,7 +109,7 @@ describe('datetime', () => { // 1st day of the month is after Thurdsay, but it’s not in January test('week on 2021-03-01 is 2021-W17', () => { const march1st2021 = new Date(2021, 4, 1) - expect(getNormalizeDay(march1st2021)).toBeGreaterThan(4) + expect(getNormalizedDay(march1st2021)).toBeGreaterThan(4) expect(datetime(march1st2021, 'week')).toBe('2021-W17') }) diff --git a/src/timezone.test.js b/src/timezone.test.js index ef5afba..574fd3c 100644 --- a/src/timezone.test.js +++ b/src/timezone.test.js @@ -21,49 +21,89 @@ describe('tzOffset', () => { describe('in boundaries', () => { - test('tzOffset(-8) is -08:00', () => { + test('tzOffset(-23, -59) is -23:59', () => { + expect(tzOffset(-23, -59)).toBe('-23:59') + }) + + test('tzOffset(-9, -30) is -09:30', () => { + expect(tzOffset(-9, -30)).toBe('-09:30') + }) + + test('tzOffset(-9, 30) is -08:30', () => { + expect(tzOffset(-9, 30)).toBe('-08:30') + }) + + test('tzOffset(-8) is -08:00', () => { expect(tzOffset(-8)).toBe('-08:00') }) - test('tzOffset(-4.5) is -04:30', () => { + test('tzOffset(-4.5) is -04:30', () => { expect(tzOffset(-4.5)).toBe('-04:30') }) - test('tzOffset(0, -30) is -00:30', () => { + test('tzOffset(0, -30) is -00:30', () => { expect(tzOffset(0, -30)).toBe('-00:30') }) - test('tzOffset(0) is Z', () => { + test('tzOffset(0) is Z', () => { expect(tzOffset(0)).toBe('Z') }) - test('tzOffset(0, 30) is +00:30', () => { + test('tzOffset(0, 30) is +00:30', () => { expect(tzOffset(0, 30)).toBe('+00:30') }) - test('tzOffset(1) is +01:00', () => { + test('tzOffset(1) is +01:00', () => { expect(tzOffset(1)).toBe('+01:00') }) - test('tzOffset(2, -200) is -01:20', () => { + test('tzOffset(2, -200) is -01:20', () => { expect(tzOffset(2, -200)).toBe('-01:20') }) - test('tzOffset(4, 30) is +04:30', () => { + test('tzOffset(4, 30) is +04:30', () => { expect(tzOffset(4, 30)).toBe('+04:30') }) - test('tzOffset(12, 45) is +12:45', () => { + test('tzOffset(12, 45) is +12:45', () => { expect(tzOffset(12, 45)).toBe('+12:45') }) - test('tzOffset(12.75) is +12:45', () => { + test('tzOffset(12.75) is +12:45', () => { expect(tzOffset(12.75)).toBe('+12:45') }) + + test('tzOffset(23, 59) is +23:59', () => { + expect(tzOffset(23, 59)).toBe('+23:59') + }) }) describe('out of boundaries', () => { + test('tzOffset(-24) is Z', () => { + expect(tzOffset(-24)).toBe('Z') + }) + + test('tzOffset(24) is Z', () => { + expect(tzOffset(24)).toBe('Z') + }) + + test('tzOffset(-24, 0, true) is Z', () => { + expect(tzOffset(-24, 0, true)).toBe('Z') + }) + + test('tzOffset(24, 0, true) is Z', () => { + expect(tzOffset(24, 0, true)).toBe('Z') + }) + + test('tzOffset(-24, -1) is -00:01', () => { + expect(tzOffset(-24, -1)).toBe('-00:01') + }) + + test('tzOffset(24, 1) is 00:01', () => { + expect(tzOffset(24, 1)).toBe('+00:01') + }) + test('tzOffset(-35) is -11:00', () => { expect(tzOffset(-35)).toBe('-11:00') }) diff --git a/src/utils/const.js b/src/utils/const.js index 5fcc57c..1889e40 100644 --- a/src/utils/const.js +++ b/src/utils/const.js @@ -1,8 +1,18 @@ export const MINUTES_PER_DAY = 60 * 24 export const MILLISECONDS_PER_DAY = 1000 * 60 * 60 * 24 export const MILLISECONDS_PER_WEEK = MILLISECONDS_PER_DAY * 7 -export const REAL_LIFE_LOWER_TIMEZONE = -12 * 60 -export const REAL_LIFE_UPPER_TIMEZONE = 14 * 60 -// Local timezone offset from UTC, in minutes +/** + * The farthest timezone offset **behind** UTC time. + */ +export const REAL_LIFE_LOWER_TIMEZONE = -12 * 60 // -12:00 + +/** + * The farthest timezone offset **ahead of** UTC time. + */ +export const REAL_LIFE_UPPER_TIMEZONE = 14 * 60 // +14:00 + +/** + * Local timezone offset from UTC, in minutes. + */ export const LOCAL_TZ_OFFSET = (new Date()).getTimezoneOffset() * -1 diff --git a/src/utils/date.js b/src/utils/date.js index ec38e03..a4c5023 100644 --- a/src/utils/date.js +++ b/src/utils/date.js @@ -35,7 +35,7 @@ export function daysBetween(date, furtherDate) { * @returns {number} */ export function weekNumber(date) { - const dayIndex = getNormalizeDay(date) + const dayIndex = getNormalizedDay(date) const sameWeekThursday = new Date(date) sameWeekThursday.setDate(date.getDate() + 4 - dayIndex) @@ -52,4 +52,4 @@ export function weekNumber(date) { * @param {Date} date * @returns {number} */ -export const getNormalizeDay = date => date.getDay() || 7 +export const getNormalizedDay = date => date.getDay() || 7 diff --git a/types/utils/const.d.ts b/types/utils/const.d.ts index 958d5f8..3962c4e 100644 --- a/types/utils/const.d.ts +++ b/types/utils/const.d.ts @@ -1,6 +1,15 @@ export const MINUTES_PER_DAY: number; export const MILLISECONDS_PER_DAY: number; export const MILLISECONDS_PER_WEEK: number; +/** + * The farthest timezone offset **behind** UTC time. + */ export const REAL_LIFE_LOWER_TIMEZONE: number; +/** + * The farthest timezone offset **ahead of** UTC time. + */ export const REAL_LIFE_UPPER_TIMEZONE: number; +/** + * Local timezone offset from UTC, in minutes. + */ export const LOCAL_TZ_OFFSET: number; diff --git a/types/utils/date.d.ts b/types/utils/date.d.ts index 9ffc910..5bf0563 100644 --- a/types/utils/date.d.ts +++ b/types/utils/date.d.ts @@ -18,3 +18,4 @@ export function daysBetween(date: Date, furtherDate: Date): number; * @returns {number} */ export function weekNumber(date: Date): number; +export function getNormalizedDay(date: Date): number;