RFE: option to be explicit about !!timestamp tags

[isaacs]

Is your feature request related to a problem? Please describe.

Even though it seems (if I'm reading it correctly?) to be in line with the spec, there's an ambiguity when dealing with date strings.

If you have an object with an actual date, and an object with a string representation of the same date, then they yaml.stringify to the same value, because !!timestamp is a default, so it isn't tagged in the yaml.

> yaml.stringify({ x: new Date('2023') })
'x: 2023-01-01T00:00:00.000Z\n'
> yaml.stringify({ x: new Date('2023').toISOString() })
'x: 2023-01-01T00:00:00.000Z\n'

This makes it impossible to know what you actually got in the value, and a string and a Date are quite different things!

What's worse, when parsing yaml, you get the same value in both cases, making rehydration impossible to do faithfully:

> yaml.parse(yaml.stringify({ x: new Date('2023') }))
{ x: '2023-01-01T00:00:00.000Z' } // <-- string, expected Date
> yaml.parse(yaml.stringify({ x: new Date('2023').toISOString() }))
{ x: '2023-01-01T00:00:00.000Z' } // <-- string, as expected

Of course, you can explicitly say "treat valid date strings as dates":

> yaml.parse(yaml.stringify({ x: new Date('2023') }), { customTags: ['timestamp'] })
{ x: 2023-01-01T00:00:00.000Z } // <-- Date, as expected

But then that swings too far in the other direction:

> yaml.parse(yaml.stringify({ x: new Date('2023').toISOString() }), { customTags: ['timestamp'] })
{ x: 2023-01-01T00:00:00.000Z } // <-- Date! expected string

If a !!timestamp were present in the stringified value, then this would work as expected:

> yaml.parse('x: 2023-01-01T00:00:00.000Z\n')
{ x: '2023-01-01T00:00:00.000Z' }  // <-- string, as expected
> yaml.parse('x: !!timestamp 2023-01-01T00:00:00.000Z\n')
{ x: 2023-01-01T00:00:00.000Z }  // <-- date, as expected

Describe the solution you'd like

It would be nice if there was an option to yaml.stringify to explicitly declare that we want to get a !!timestamp tag added to any Date objects.

As far as I can see, what yaml is doing today isn't wrong according to the spec, but neither would it be if !!timestamp were added in these cases by default (or even, always).

> yaml.stringify({ x: new Date('2023') }, { explicitTimestamp: true })
'x: !!timestamp 2023-01-01T00:00:00.000Z\n'

Describe alternatives you've considered

My alternative at the moment (which I'm not thrilled about) is to define !!timestamp in my own code as a custom tag, so that it isn't default: true. But I'd much prefer to just use the one that ships with yaml already.

[eemeli]

Atm, the internal !!timestamp tag can be accessed via

import { Schema } from 'yaml'
const schema = new Schema({ resolveKnownTags: true })
const timestamp = schema.knownTags['tag:yaml.org,2002:timestamp']
timestamp.default = false // toggles this for all users, not just this schema instance

But that's pretty hacky and undocumented. It seems to me like it might make sense to add an explicit API for accessing YAML 1.1 tags to yaml-types, which would then take the burden of digging them out of the yaml package.