Experiment with Temporal API

.size-limit.json

@@ -4,63 +4,127 @@
       "path": "src/index.js",
       "import": "{ datetime }"
     },
+    {
+      "name": "`datetime` (Temporal)",
+      "path": "src/temporal-same-features/index.js",
+      "import": "{ datetime }"
+    },
     {
       "name": "`utc`",
       "path": "src/index.js",
       "import": "{ utc }"
     },
+    {
+      "name": "`utc` (Temporal)",
+      "path": "src/temporal-same-features/index.js",
+      "import": "{ utc }"
+    },
     {
       "name": "`datetimeTz`",
       "path": "src/index.js",
       "import": "{ datetimeTz }"
     },
+    {
+      "name": "`datetimeTz` (Temporal)",
+      "path": "src/temporal-same-features/index.js",
+      "import": "{ datetimeTz }"
+    },
     {
       "name": "`duration`",
       "path": "src/index.js",
       "import": "{ duration }"
     },
+    {
+      "name": "`duration` (Temporal)",
+      "path": "src/temporal-same-features/index.js",
+      "import": "{ duration }"
+    },
     {
       "name": "`tzOffset`",
       "path": "src/index.js",
       "import": "{ tzOffset }"
     },
+    {
+      "name": "`tzOffset` (Temporal)",
+      "path": "src/temporal-same-features/index.js",
+      "import": "{ tzOffset }"
+    },
     {
       "name": "`setTimeSeparator`",
       "path": "src/index.js",
       "import": "{ setTimeSeparator }"
     },
+    {
+      "name": "`setTimeSeparator` (Temporal)",
+      "path": "src/temporal-same-features/index.js",
+      "import": "{ setTimeSeparator }"
+    },
     {
       "name": "`setTzConfig`",
       "path": "src/index.js",
       "import": "{ setTzConfig }"
     },
+    {
+      "name": "`setTzConfig` (Temporal)",
+      "path": "src/temporal-same-features/index.js",
+      "import": "{ setTzConfig }"
+    },
     {
       "name": "`setTzInRealWorldRange`",
       "path": "src/index.js",
       "import": "{ setTzInRealWorldRange }"
     },
+    {
+      "name": "`setTzInRealWorldRange` (Temporal)",
+      "path": "src/temporal-same-features/index.js",
+      "import": "{ setTzInRealWorldRange }"
+    },
     {
       "name": "`setTzSeparator`",
       "path": "src/index.js",
       "import": "{ setTzSeparator }"
     },
+    {
+      "name": "`setTzSeparator` (Temporal)",
+      "path": "src/temporal-same-features/index.js",
+      "import": "{ setTzSeparator }"
+    },
     {
       "name": "`daysBetween`",
       "path": "src/index.js",
       "import": "{ daysBetween }"
     },
+    {
+      "name": "`daysBetween` (Temporal)",
+      "path": "src/temporal-same-features/index.js",
+      "import": "{ daysBetween }"
+    },
     {
       "name": "`weekNumber`",
       "path": "src/index.js",
       "import": "{ weekNumber }"
     },
+    {
+      "name": "`weekNumber` (Temporal)",
+      "path": "src/temporal-same-features/index.js",
+      "import": "{ weekNumber }"
+    },
     {
       "name": "`DateTime`",
       "path": "src/index.js",
       "import": "{ DateTime }"
     },
+    {
+      "name": "`DateTime` (Temporal)",
+      "path": "src/temporal-same-features/index.js",
+      "import": "{ DateTime }"
+    },
     {
       "name": "**All modules** (`import *`)",
       "path": "src/index.js"
+    },
+    {
+      "name": "**All modules** (`import *`, Temporal)",
+      "path": "src/temporal-same-features/index.js"
     }
   ]

package.json

@@ -73,5 +73,9 @@
       "has": "npm:@nolyfill/has@latest",
       "hasown": "npm:@nolyfill/hasown@latest"
     }
+  },
+  "peerDependencies": {
+    "@js-temporal/polyfill": "^0.4.4",
+    "temporal-polyfill": "^0.2.4"
   }
 }

src/datetime.js

@@ -106,7 +106,6 @@ export function datetime(date = new Date(), precision = 'day') {
  * - `datetime(someDate, 'somePrecision utc')`
  * - `utc(someDate, 'somePrecision')`
  *
- *
  * @param {Date} [date=new Date()] - default to now
  * @param {'datetime'|'datetime second'|'datetime ms'|'time'|'second'|'ms'} [precision=datetime]
  * @returns {string}

src/temporal-experimenting/README.md

@@ -0,0 +1,32 @@
+> [!INFO]  
+>
+> Work in progress document. Very drafty.
+
+This folder will contain the implementation of `datetime-attribute` where functions will accept [`Temporal`](https://tc39.es/proposal-temporal/docs) objects while keeping current parameters.
+
+It’s possible that some functions will not require to accept a `Temporal` object because what they accomplish is maybe already available as a `Temporal.{className}` feature.
+
+It’s also possible that new functions are created to facilitate the usage of `Temporal` objects, and the extended scope they cover in comparison with `Date`.
+
+## Parity between `Date` and `Temporal` implementations
+
+**Drafty.**
+
+function | in `Date` | in `Temporal` | note
+---|---|---|---
+`tzOffset` | yes | yes | @todo accept a `Temporal.TimeZone` (or any temporal) and output its “real-world” timezone.
+`datetime` | yes | yes | @todo evaluate
+`utc` | yes | yes | @todo evaluate
+`datetimeTz` | yes | yes | @todo evaluate
+`DateTime` | yes | yes | @todo evaluate
+`duration` | yes | yes | @todo evaluate
+`daysBetween` | yes | yes | @todo evaluate
+`weekNumber` | yes | yes | @todo evaluate
+(config feature…)| yes | yes | @todo evaluate
+
+## `tzOffset` notes
+
+```js
+const tz = new Temporal.TimeZone('-23:59')
+console.log(tz.id) // -23:59
+```

src/temporal-same-features/README.md

@@ -0,0 +1,5 @@
+# datetime-attribute implemented with the `Temporal` API
+
+This folder contains the implementation of `datetime-attribute` using the [`Temporal` API](https://tc39.es/proposal-temporal/docs).
+
+It has feature parity with the initial `datetime-attribute`.

src/temporal-same-features/config/datetime.js

@@ -0,0 +1,38 @@
+/**
+ * @typedef {Object} DateTimeOptions
+ * @property {('T'|' ')} separator The separator between date and time
+ *                                 (`'2024-04-21T10:34'`) can be a
+ *                                 'T' (default) or a space.
+ */
+
+/** @type DateTimeOptions */
+export const config = {
+  separator: 'T',
+}
+
+/**
+ * Set datetime related configuration
+ *
+ * @param {DateTimeOptions} options
+ * @returns {DateTimeOptions}
+ */
+export const setConfig = options => {
+
+  /**
+   * The separator can only be 'T' or ' '.
+   * https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#local-dates-and-times
+   */
+  if (options.separator != 'T' && options.separator != ' ') {
+    throw new Error(`Invalid timezone separator. Use 'T' or ' '.`)
+  }
+
+  return Object.assign(config, options)
+}
+
+/**
+ * Set separator between date and time
+ *
+ * @param {DateTimeOptions['separator']} [separator='T']
+ * @returns {DateTimeOptions}
+ */
+export const setTimeSeparator = (separator = 'T') => setConfig({ separator })

src/temporal-same-features/config/datetime.test.js

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'vitest'
+
+import { datetime, setTimeSeparator } from '../index.js'
+
+import { setConfig } from './datetime.js'
+
+const togoIndependanceDay = new Date(1960, 3, 27)
+const date = togoIndependanceDay // alias for the sake of brevity
+
+describe('setTimeSeparator', () => {
+
+  test('is a function', () => {
+    expect(setTimeSeparator).toBeInstanceOf(Function)
+  })
+
+  test('throws with invalid separator', () => {
+    expect(() => setTimeSeparator(42)).toThrow(Error)
+  })
+
+  test('no time separator', () => {
+    setTimeSeparator()
+    expect(datetime(date, 'datetime')).toBe('1960-04-27T00:00')
+  })
+
+  test('T as time separator', () => {
+    setTimeSeparator('T')
+    expect(datetime(date, 'datetime')).toBe('1960-04-27T00:00')
+  })
+
+  test('space as time separator', () => {
+    setTimeSeparator(' ')
+    expect(datetime(date, 'datetime')).toBe('1960-04-27 00:00')
+  })
+})
+
+describe('setConfig', () => {
+
+  test('is a function', () => {
+    expect(setConfig).toBeInstanceOf(Function)
+  })
+
+  test('throws without parameter', () => {
+    expect(() => setConfig()).toThrow(TypeError)
+  })
+
+  test('throws without proper parameter', () => {
+    expect(() => setConfig({})).toThrow(Error)
+  })
+
+  test('throws with invalid separator', () => {
+    expect(() => setConfig({ separator: 42 })).toThrow(Error)
+  })
+
+  test('T as time separator using datetime', () => {
+    setConfig({ separator: 'T' })
+    expect(datetime(date, 'datetime')).toBe('1960-04-27T00:00')
+  })
+
+  test('space as time separator using datetime', () => {
+    setConfig({ separator: ' ' })
+    expect(datetime(date, 'datetime')).toBe('1960-04-27 00:00')
+  })
+})

src/temporal-same-features/config/index.js

@@ -0,0 +1,6 @@
+export { setTimeSeparator } from './datetime.js'
+export {
+  setTzConfig,
+  setTzInRealWorldRange,
+  setTzSeparator,
+} from './tz.js'