@std/datetime format method and FormatOptions is inconsistent
- Dominant language
- TypeScript
- Stars
- 3.6k
- Forks
- 681
- PR merge metrics
- No merged PRs in 30d
Description
1. The implementation [FormatOptions](https://jsr.io/@std/datetime/doc/~/FormatOptions) should allow different values for `timeZone`, and not just `UTC`.
I would allow all values that [env.TZ can be set to](https://infocenter-archive.sybase.com/help/index.jsp?topic=/com.sybase.infocenter.dc38151.1270/html/iqref/BGBIJFAJ.htm).
Note that the `format` method page has more documentation for `FormatOptions` than the `FormatOptions` page, and is inconsistently documented (is it a `boolean` or a `string` that only allows the value 'UTC'?). If only UTC is allowed, the option should be called `utc`, and not `timeZone`. The FormatOptions page needs to be updated as well.
2. The `format` method should include the defined Unicode LDML options to output the timezone as part of the string.
This, in combination with allowing timeZone to be set to different timezone values, would allow a date to be expressed for any timezone. Strings such as _2024-10-04T21:05:59.878Z_ and _2024-01-01T11:59:59.456-06:00_ could then be produced.
You can get the timezone to display using something like this (taken from this [@epdoc/timeutil module](https://github.com/epdoc/timeutil/blob/master/src/date-util.ts)):
```ts
export type Minutes = number;
const tzOffset:Minutes = new Date().getTimezoneOffset()
const tzAsString = tzFormat(tzOffset);
function tzFormat(m: Minutes) {
if (m === 0) {
return 'Z';
}
return (m < 0 ? '+' : '-') + pad(Math.floor(Math.abs(m) / 60), 2) + ':' + pad(Math.abs(m) % 60, 2);
}
function pad(n: number, width: number, z: string = "0"): string {
const sn = String(n);
return sn.length >= width
? sn
: new Array(width - sn.length + 1).join(z) + sn;
}
```
3. Even if you don't allow FormatOptions.timeZone to have other values, it would still be useful to be able to format the timezone so that ISO date strings using local time can be output.
4. The naming of FormatOptions timeZone is inconsistent with nodejs getTimezoneOffset. I would suggest timezone be used (all lower case)
Contributor guide
Assessment
This issue has not been assessed yet.