Rename DateTimeDescriptor `epochMillis` and `epochNanos`

[cdavernas]

What would you like to be added:

• [ ] Rename DateTimeDescriptor epochMillis and epochNanos.
• [ ] Move iso8601, epochMillis and epochNanos properties to a DateTimeDescriptor object, so we avoid duplication (in both WorkflowDescriptor and TaskDescriptor).
• [ ] Move epochMillis and epochNanos to a new epoch DateTimeDescriptor property, for a cleaner aspect.

Why is this needed:

• The properties use abbreviations, which should always be avoided, If we decide to abbreviate, we should use the standard format, and not an opiniated one (ms and ns).
• Cleans up definitions
• Increases maintainability
• Increases readability

The proposal:

DateTime Descriptor

Name	Type	Description	Example
iso8601	string	The start time of the execution as a ISO 8601 date time string. It uses T as the date-time delimiter, either UTC (Z) or a time zone offset (+01:00). The precision can be either seconds, milliseconds or nanoseconds	2022-01-01T12:00:00Z, 2022-01-01T12:00:00.123456Z, 2022-01-01T12:00:00.123+01:00
epoch.ms	integer	The start time of the execution as a integer value of milliseconds since midnight of 1970-01-01 UTC	1641024000123 (="2022-01-01T08:00:00.123Z")
epoch.ns	integer	The start time of the execution as a integer value of nanoseconds since midnight of 1970-01-01 UTC	1641024000123456 (="2022-01-01T08:00:00.123456Z")

[cdavernas]

@matthias-pichler-warrify WDYT? Do you want to take care of it?

[matthias-pichler]

Looks good to me 👍

[matthias-pichler]

Regarding nanoseconds: the jq docs say that all numbers are represented as IEEE 754 double precision floating point numbers: https://jqlang.github.io/jq/manual/v1.7/

Numbers in jq are internally represented by their IEEE754 double precision approximation. Any arithmetic operation with numbers, whether they are literals or results of previous filters, will produce a double precision floating point result.

and as it turns out these are too small to safely represent nanoseconds as an integer. (At least according to Number.MAX_SAFE_INTEGER in JS)

So I am afraid we have to drop nanoseconds to ensure we have safe jq expressions

[cdavernas]

That's fine to me, I didn't really like that we supported both in the first place anyways.

So what, we should therefore have iso8601 and epoch (expressed in ms)?

[matthias-pichler]

I think having epoch.ms is still nice because it's more explicit. Before I knew JS the epoch always was seconds to me 😅 and now I always have to check when using a different language/api ... we can even consider adding epoch.sec maybe?

[cdavernas]

Yeah, sure, why not?

However, we need to properly document it so that users don't start to think that seconds and milliseconds are complementary components, but are instead mutually exclusive, don't you agree?

[matthias-pichler]

However, we need to properly document it so that users don't start to think that seconds and milliseconds are complementary components, but are instead mutually exclusive, don't you agree?

not 100% sure what you mean ... you mean that ms should also contain the whole timestamp right?

I would like something like:

echo:
  sec: 1723190735
  ms: 1723190735645

[cdavernas]

not 100% sure what you mean ... you mean that ms should also contain the whole timestamp right?

No, I mean that some users might wrongly think that sec are the seconds of the epoch, and ms the milliseconds, even if that's obivous to me it isn't. Something like 10 secs AND 10000 milliseconds, instead of just 10 secs OR 10000 milliseconds.

I hope this is clearer 👅