Merge main into experiment-temporal-api

Author: meduzen

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:
 

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')
     })
 

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')
     })

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

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

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;

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;