Consider implementing a date() function

[kit494way]

A date() function accepts a date/time string and output unix timestamp, string or object.

First argument accepts followings.

• ISO 8601 format string.
  • date('2023-01-01T00:00:00Z')
• human readable date time string.
  • date('1 days ago')
  • date('2 hours ago')
  • date('now')
• unix timestamp number.
  • date(1672531200)
• object that has required properties.
  • date({ year:2023, month:1, date:1, hours:0, minutes:0, seconds:0, offsetMinutes:0})

Second argument accepts output format and time zone as object properties.
The output format is specified by the format property.

expression	output
date('2023-01-01T00:00:00Z', { format: 'timestamp' })	1672531200
date('2023-01-01T00:00:00Z', { format: 'seconds' })	'2023-01-01T00:00:00+00:00'
date('2023-01-01T00:00:00Z', { format: 'date' })	'2023-01-01'
date('2023-01-01T00:00:00Z', { format: 'object' })	{ year:2023, month:1, date:1, hours:0, minutes:0, seconds:0, offsetMinutes:0, timestamp:1672531200, value:"2023-01-01T00:00:00Z"}
date('2023-01-01T00:00:00Z', { format: format_string })	string formatted in format_string, e.g %Y-%d-%m %H:%M:%S

Default format is 'timestamp'.
When specify { format: 'object' }, output object the first argument in value property.

The output time zone is specified by the out_timezone property.

expression	output
date('2023-01-01T00:00:00Z', { format: 'seconds', out_timezone: '09:00' })	'2023-01-01T09:00:00+09:00'

The out_timezone may be ignored in some format.
If out_timezone is not specified, return in the same time zone as first argument.

The input time zone is specified by the in_timezone property.

expression	output
date('2023-01-01T00:00:00', { format: 'seconds', in_timezone: '09:00' })	'2023-01-01T00:00:00+09:00'

The in_timezone is ignored if time zone is indicated by first argument.
If time zone is not indicated by first argument and in_timezone is not specified, use local time zone.

Example

xs[? date(updatedAt) >= date('1 days ago')] | sort_by(@, &date(updatedAt)) | [].{ id: id, date(updatedAt, { format: '%Y-%m-%dT%H:%M:%S%:z' }) }

xs[].{id: id, updatedAt: date(updatedAt, { format: 'object' })}[? updatedAt.timestamp >= date('1 days ago')] | sort_by(@, &updatedAt.timestamp) | [].{id: id, updatedAt: updatedAt.value }

[springcomp]

Thanks for the feedback.

[springcomp]

I think we first need String Comparisons in order to enable comparing date strings.

[gibson042]

The standard library currently encompasses no I/O with an external environment, and that's a nice property to preserve. I'm opposed to breaking it with introduction of a date or similar function.

[springcomp]

I agree JMESPath should be deterministic.

I read this proposal as providing date formatting functions. This would help subsequent comparisons with date/times as strings.

This rules out the relative dates formatting such as 1 hour ago.

Also, the formatting patterns needs rework. I more inclined to use .NET style patterns such as yyyy, MM, etc.

[springcomp]

As this would be a conversion function, I’m inclined to name it to_date().

[kit494way]

The standard library currently encompasses no I/O with an external environment

I did not realize that.
Now I agree with that JMESPath should be deterministic.

[FilipPyrek]

Great idea 👍 this would be handy

[springcomp]

Challenges when implementing date-related functions

• Dates are hard
• There is no single unambiguous string representation of dates and times. For instance 2024-25-10T14:00:00.0000000UTC+02:00 is equal to 2024-25-10T12:00:00.0000000UTC+00:00 are the same dates but are expressed in terms of different timezones. So there should probably be a host of date-time functions, for conversions, adding time spans to dates, changing time zones, etc.
• JMESPath does not have a type for dates/times. So comparison can only happen using date-aware date-time functions.