Adding a DateTime primative

[erikmaas-malmberg]

Is your feature request related to a problem? Please describe.
Dates and times are always strange types to work with.
Let's make it easy by predefining a DateTime primitive.
In this Primitive one can specify how this is formatted and / or constrained.
Using proper DateTime specifications it's easier to understand what is going on.
Compare:

// Iso 8601 DateTime
type DateTime = String(/^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):([0-5]\d):([0-5]\d)(\.\d+)?(Z|([+-](0\d|1[0-2]):([0-5]\d)))?$/g)

With

type IsoDateTime = DateTime(ISO_8601)
//or
type IsoDateTime = DateTime(yyyy-MM-dd'T'HH:mm:ss.SSSZ)

Describe the solution you'd like
A proper DateTime primitive supporting a way to specify how this DateTime is formatted with pre-formats and with simple formatting language.

Requirements
A proper DateTime primitive supporting a way to specify how this DateTime is formatted with pre-formats and with simple formatting language.
The default DateTime should use the ISO_8601 spec as this is an ISO defined standard

Additional information
For further reading sources that triggered your feature wish

[ZzAve]

This is an interesting feature, that I believe is quite promising, especially for type hinting and IDE integration. Nevertheless, you can achieve what you want largely already using empty refined types.

Consider this comparable to the use of Scalars in graphql https://graphql.org/learn/schema/#scalar-types , where you can define a type without a backing implementation, such that you can do that yourself. Integration points such as maven and gradle plugins often offer compile-time substitutions to do so. Even though we're not planning to have this compile-time integration support, what you can do is the following.

In your wirespec file, define your type of choice:

// Just a date, e.g. 2025-01-02
type Date = String

// Date + time component e.g. 2025-01-02T13:03:01
type LocalDateTime = String

// Date + time + offset/zone component e.g. 2025-01-02T13:03:01+01:00
type OffsetDateTime = String

During compilation / code generation these get compiled into a wrapper object or marked as a type, depending on the output language. When internalizing this to your domain (assuming you don't mix your wirespec models with your app internal models), you can then apply your own validation to it, as well as have control over how you serialise and deserialise it to and from a string. For kotlin (in jvm context) you could do:

// Map from ws models to domain models
fun Date.toDomain() = LocalDate.parse(value)
fun LocalDateTime.toDomain() = java.time.LocalDateTime.parse(value)
fun OffsetDateTime.toDomain() = Instant.parse(value) // or java.time.OffsetDateTime.parse(value)

and back

// Map from domain models to ws models
fun LocalDate.toResponse() = Date(toString())
fun java.time.LocalDateTime.toResponse() = LocalDateTime(toString)
fun Instant.toResponse() = OffsetDateTime(toString())

[ZzAve]

Some small research on this topic shows some possibilities to do this soon for our 4 supported output languages + 3 other types (avro, openapi2, openapi3)

⌛ kotlin

In Kotlin 2.1 kotlin.time lib was introduced as part of the kotlin-stdlib. However, that has only been marked as 'stable' since kotlin 2.3. As of this time of writing wirespec is on 2.0.21 (https://github.com/flock-community/wirespec/blob/master/gradle/libs.versions.toml#L15).

Preferably we'd wait until we can use the time library without it being experimental, and thus having to postpone this until we're migrated to kotlin 2.3, for which I'll link a ticket / set milestone.

Before the kotlin.time stdlib migration, there was / is a lib kotlinx-datetime, but we want Wirespec to generate dependency free code, so still relying on this does not seem like a good idea. Also, it seems that kotlinx-datetime doesn't work properly from kotlin 2.1, meaning we'd also lose compatibilty:
https://medium.com/@maliksaif070/kotlin-update-instant-now-is-gone-heres-what-to-use-instead-kotlin-2-1-ba2c811ff726

https://kotlinlang.org/api/core/2.1/kotlin-stdlib/kotlin.time/-instant/

✅ Java

Java has extensive support in the built-in java.time package which is part of the standard library. From Instant, to OffsetDateTime, as well as Period and Duration, this seems 'trivial'.

✅ python

The Datetime lib, containing simple dates as well as datetime object is part of the stdlib of python and can be used
https://docs.python.org/3/library/datetime.html

⚠️ typescript

In the javascript ecosystem the native Date can be a partial solution for dates and possibly timestamps. The downsize is that Date object ALWAYS contain a timestamp and timezone, which can lead to problems. The new Temporal API looks promising, with support ramping up across many browsers. However, for server side javascript (nodejs). This would require a polyfill https://www.npmjs.com/package/@js-temporal/polyfill , which is not the bestest of experiences

See nodejs/node#57891