Currently, when we parse (actually when we lex) a timestamp we will automatically convert it to a Date object based on either a provided or inferred timestamp.
This has some odd behaviour, for example the Org <2021-07-12 Mon> might become the Date 2021-07-11T12:00. In some cases (if you only care about the actual time value), this would be fine, but generally speaking we should probably not be making such assumptions. This could cause issues e.g., when rendering, we aren't able to tell what format the original timestamp was in, as all the information is currently squashed to a single Date. In the case provided, it is meaningful to preserve the fact that this timestamp just references a particular date, without caring about the actual Date this represents (i.e., we just want to render to <2021-07-12 Mon>).
Another issue is that timestamps are in the owner's timezone, and we don't always have access to this information, but what ends up happening is that the parser assumes that whoever is running it is the owner, which may not be correct. Concrete example - think about sites like https://deno.land/x or GitHub where you take READMEs written by 'owners' and render them. If you wanted to render a timestamp, what timezone do you use when parsing? You (typically) don't have access to the owner's timezone, and to use any other might possibly misrepresent what the owner intended. In these cases you would just want to render back the exact (modulo prettification) timestamp that was written.
Alternatives
One possible alternative would be to maintain the syntactic timestamp for as long as possible, i.e., track the specified day/month/year and time, whether a day name was specified, repeats, range, etc., then we can provide utilities for converting these to a Date when a timestamp is known. Further, we could actually provide plugins (or parser options) that convert all timestamps to dates for you, given a timezone (for cases where users actually want to have a Date rather than a timestamp).
Another alternative would be to always require a timestamp to be specified - but this doesn't alleviate the second issue mentioned above.
A third alternative would be to still return a Date object (though again, this makes it harder when re-rendering) along with the timezone that was used when parsing, in the hopes that the user would look at this timezone and use it to convert the provided Date when e.g., rendering.
I prefer option 1, as it provides the most flexibility, ease of extension (e.g., to support repeats), and requires less assumptions. It would also allow us to better match Org's semantics. I'll play around with this option over at https://github.com/GuiltyDolphin/orgajs/tree/gd/token-lexer.
Currently, when we parse (actually when we lex) a timestamp we will automatically convert it to a
Dateobject based on either a provided or inferred timestamp.This has some odd behaviour, for example the Org
<2021-07-12 Mon>might become theDate2021-07-11T12:00. In some cases (if you only care about the actual time value), this would be fine, but generally speaking we should probably not be making such assumptions. This could cause issues e.g., when rendering, we aren't able to tell what format the original timestamp was in, as all the information is currently squashed to a singleDate. In the case provided, it is meaningful to preserve the fact that this timestamp just references a particular date, without caring about the actualDatethis represents (i.e., we just want to render to<2021-07-12 Mon>).Another issue is that timestamps are in the owner's timezone, and we don't always have access to this information, but what ends up happening is that the parser assumes that whoever is running it is the owner, which may not be correct. Concrete example - think about sites like https://deno.land/x or GitHub where you take READMEs written by 'owners' and render them. If you wanted to render a timestamp, what timezone do you use when parsing? You (typically) don't have access to the owner's timezone, and to use any other might possibly misrepresent what the owner intended. In these cases you would just want to render back the exact (modulo prettification) timestamp that was written.
Alternatives
One possible alternative would be to maintain the syntactic timestamp for as long as possible, i.e., track the specified day/month/year and time, whether a day name was specified, repeats, range, etc., then we can provide utilities for converting these to a
Datewhen a timestamp is known. Further, we could actually provide plugins (or parser options) that convert all timestamps to dates for you, given a timezone (for cases where users actually want to have aDaterather than a timestamp).Another alternative would be to always require a timestamp to be specified - but this doesn't alleviate the second issue mentioned above.
A third alternative would be to still return a
Dateobject (though again, this makes it harder when re-rendering) along with the timezone that was used when parsing, in the hopes that the user would look at this timezone and use it to convert the providedDatewhen e.g., rendering.I prefer option 1, as it provides the most flexibility, ease of extension (e.g., to support repeats), and requires less assumptions. It would also allow us to better match Org's semantics. I'll play around with this option over at https://github.com/GuiltyDolphin/orgajs/tree/gd/token-lexer.