@std/datetime format method and FormatOptions is inconsistent

[jpravetz]

1. The implementation FormatOptions should allow different values for timeZone, and not just UTC.

I would allow all values that env.TZ can be set to.

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):

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)

[WWRS]

timeZone and getTimezoneOffset are specified by ECMAScript, so those are unlikely to change names.

The rest of this has actually been on the todo list for some time:

std/datetime/_date_time_formatter.ts

Lines 301 to 305 in c338b2f

	// FIXME(bartlomieju)
	case "timeZoneName": {
	// string += utc ? "Z" : part.value
	break;
	}

I'm currently looking at bringing @std/datetime's supported formats to parity with Intl.DateTimeFormat.