meduzen / datetime-attribute Goto Github PK

Add date+time precision for global and global second.

Should be datetimeTz(something).

Spec. Notes:

This format allows for time-zone offsets from -23:59 to +23:59. Right now, in practice, the range of offsets of actual time zones is -12:00 to +14:00, and the minutes component of offsets of actual time zones is always either 00, 30, or 45. There is no guarantee that this will remain so forever, however, since time zones are used as political footballs and are thus subject to very whimsical policy decisions.

Output examples:

Z
+0200 (+HHMM)
+04:30 (+HH:MM)
-0300 (-HHMM)
-08:00 (-HH:MM)

Note: values outside the real-life range (-12:00 to +14:00) are currently not adjusted to fit in it. This means tzOffset(26) will output +26:00 instead of +02:00.

However, as stated in the spec:

This format allows for time-zone offsets from -23:59 to +23:59. Right now, in practice, the range of offsets of actual time zones is -12:00 to +14:00, and the minutes component of offsets of actual time zones is always either 00, 30, or 45. There is no guarantee that this will remain so forever, however, since time zones are used as political footballs and are thus subject to very whimsical policy decisions.

datetime-attribute should enforce the offset to stay between -23:59 and +23:59 (to be spec-compliant), and maybe provide an option to stay between -12:00 and +14:00 for convenience.

Per spec, nothing forbids a duration component to represents a duration of 0 seconds.

Right now, datetime({ s: 0 }) returns null instead of PT0S.

datetimeIn(date, timezone, optionalPrecision) could take a local time and shift it to another timezone.

Use case: “what time is it now in [somewhere far away]?”

How we could make it work:

1. Read the UTC values of the provided Date object.
2. Do something with these values (sorry, should go to bed) and use Intl.DateTimeFormat to transform the timezone to the specified location, e.g.:

new Intl.DateTimeFormat('en-GB', {
  dateStyle: 'short',
  timeStyle: 'long',
  timeZone: 'America/New_York'
}).format(date); // '03/05/2021, 17:28:22 GMT-4'

3. Compute timezones difference by comparing the GMT values and/or reparsing the output of 2.
4. ??

(Also, check what Moments and others are doing.)

Instead of having one .d.ts file per module, it would be nice to combine them in one file.

See qmhc/vite-plugin-dts#255 for research.

From previous (and maybe inaccurate) memory, having less types files speed up the resolution time of types.

How it works now:

datetimeDuration({ h: 31 }) // 'P1DT7H'

But sometimes, we want the duration to stay as provided. datetimeDuration could accept a convert flag as additional parameter:

datetimeDuration({ h: 31 }, false) // 'PT31H'

Should be doable with a new type used as optional param (example):

// type definition
@typedef { 'keyword1' | 'keyword2' } datetimePrecision`

// param declaration
@param {null | datetimePrecision}

This is needed to improve the autocompletion in this situation:

datetime(someDate, /* when the cursor is here */)

datetime(date, 'global') outputs UTC timezone, but it should be able to express a given date to any timezones, like:

• 13:43:07+04:30
• 1941-03-15 07:06:23.678Z (already supported)
• 2013-12-25T11:12-08:00
• 2013-12-25T11:12+0200

This way they stopped being deleted after each types generation. In other words, running npm run types is currently deleting /types/index.test-d.ts. Maybe the /tests directory is the right one, unless Jest is complaining.

Try https://github.com/SamVerschueren/tsd#test-directory to see if it’s the correct way to do it.

npx typedoc src/index.js is enough to get the following from TypeDoc:

`DateTime` class view

• use TypeDoc;
• host it somewhere using a CI (GitHub page, my own website…), and consider versioning (like Laravel does).

Looking at the ISO 8601 years specifics:

ISO 8601 prescribes, as a minimum, a four-digit year [YYYY] to avoid the year 2000 problem. It therefore represents years from 0000 to 9999, year 0000 being equal to 1 BC […] However, years before 1583 (the first full year following the introduction of the Gregorian calendar) are not automatically allowed by the standard. Instead, the standard states that "values in the range [0000] through [1582] shall only be used by mutual agreement of the partners in information interchange"
To represent years before 0000 or after 9999, the standard also permits the expansion of the year representation but only by prior agreement between the sender and the receiver.[20] An expanded year representation [±YYYYY] must have an agreed-upon number of extra year digits beyond the four-digit minimum, and it must be prefixed with a + or − sign[21] instead of the more common AD/BC (or CE/BCE) notation; by convention 1 BC is labelled +0000, 2 BC is labeled −0001, and so on.[22]

Topics:

1. Mutual agreement for the representation of years before 1583 (first year fully covered by the Gregorian calendar): using ISO 8601 for dates before 1583 is not allowed unless everyone parties agree it’s allowed.
2. Mutual agreement needed for anything outside of the 4-digits notation, with mandatory use of the sign (event for +).
3. What to do with “year 0”? It doesn’t exist in real world but ISO 8601 says it’s actually year -1. For new Date(-33, 0, 1).getFullYear(), does it represent actual year -33 or actual year -34? For accuracy with date diffing, it would be nice if datetime-attribute could allow to configure this behaviour (e.g. with a shiftDatesBeforeYearOne setting or with something else that would remind the era of the Temporal.PlainDateTime object). Currently new Date(-33, 0, 1) is expected to be real year -33 (see tests).

Tasks:

• add missing + sign beyond 9999;
• document stuff regarding “year 0”;
• decide how to enable the year shift before year 1 (check how libraries are handling that).

There’s a bug in datetime(date, 'week'). The correct test should be

  test('week on 2020-12-31', () => expect(datetime(december31th2020, 'week')).toBe('2020-W53'))
--  test('week on 2021-01-01', () => expect(datetime(january1st, 'week')).toBe('2021-W53'))
++  test('week on 2021-01-01', () => expect(datetime(january1st, 'week')).toBe('2020-W53'))

Could be useful since the documentation points to various external links.

Could be done once a month, using Lychee. See example implementation in my projects.

Resources:

• Temporal: getting started with JavaScript’s new date time API by Axel Rauschmayer
• TC39 proposal

const date = new Date() // 5th July 2021, it’s 16:13
const attribute = datetime(date) 

// expected
console.log(attribute) // 2021-07-05

// current result
console.log(attribute) // 2021-07-5T

Only happens if date is before the 10th of the month. The day isn’t properly padded.

As noted in #30. Should include at least:

• how to run tests
• how to update types and test them

Try a GitHub action like size-limit.

Currently, timezone offsets in the library are using : to separate minutes from hours (e.g. +02:00).

The spec makes the separator optional (+0200 is valid):

2. Two ASCII digits, representing the hours…
3. Optionally, a U+003A COLON character (:)
4. Two ASCII digits, representing the minutes…

I’d rather not increase the library size, but it should be a very light feature addition, and it could help library users to fit some API requirements.

As for the approach, I’m thinking about setting a separator var using a function. This separator var will be retrieved by timezone functions. Should be around 20 additional bytes (minified, uncompressed).