From 895a74916a89f816de7c98e912ae9140c6327897 Mon Sep 17 00:00:00 2001 From: Peter Date: Sat, 9 Mar 2024 20:24:38 +0100 Subject: [PATCH] Added some JS doc for time zones (#1499) Signed-off-by: Peter Tandler --- src/impl/locale.js | 2 +- src/impl/util.js | 7 ++++ src/zone.js | 6 ++++ src/zones/IANAZone.js | 60 ++++++++++++++++++++++++++++----- src/zones/fixedOffsetZone.js | 64 +++++++++++++++++++++++++++++++----- 5 files changed, 121 insertions(+), 18 deletions(-) diff --git a/src/impl/locale.js b/src/impl/locale.js index cd55b3bfc..93c489b07 100644 --- a/src/impl/locale.js +++ b/src/impl/locale.js @@ -340,7 +340,7 @@ export default class Locale { static create(locale, numberingSystem, outputCalendar, weekSettings, defaultToEN = false) { const specifiedLocale = locale || Settings.defaultLocale; - // the system locale is useful for human readable strings but annoying for parsing/formatting known formats + // the system locale is useful for human-readable strings but annoying for parsing/formatting known formats const localeR = specifiedLocale || (defaultToEN ? "en-US" : systemLocale()); const numberingSystemR = numberingSystem || Settings.defaultNumberingSystem; const outputCalendarR = outputCalendar || Settings.defaultOutputCalendar; diff --git a/src/impl/util.js b/src/impl/util.js index 405192444..a9b548c3c 100644 --- a/src/impl/util.js +++ b/src/impl/util.js @@ -287,6 +287,13 @@ export function normalizeObject(obj, normalizer) { return normalized; } +/** + * Returns the offset's value as a string + * @param {number} ts - Epoch milliseconds for which to get the offset + * @param {string} format - What style of offset to return. + * Accepts 'narrow', 'short', or 'techie'. Returning '+6', '+06:00', or '+0600' respectively + * @return {string} + */ export function formatOffset(offset, format) { const hours = Math.trunc(Math.abs(offset / 60)), minutes = Math.trunc(Math.abs(offset % 60)), diff --git a/src/zone.js b/src/zone.js index cec0e4fd1..f91a02ee7 100644 --- a/src/zone.js +++ b/src/zone.js @@ -22,6 +22,12 @@ export default class Zone { throw new ZoneIsAbstractError(); } + /** + * The IANA name of this zone. + * Defaults to `name` if not overwritten by a subclass. + * @abstract + * @type {string} + */ get ianaName() { return this.name; } diff --git a/src/zones/IANAZone.js b/src/zones/IANAZone.js index ad5945132..ae66f45a4 100644 --- a/src/zones/IANAZone.js +++ b/src/zones/IANAZone.js @@ -83,7 +83,7 @@ export default class IANAZone extends Zone { * @param {string} s - The string to check validity on * @example IANAZone.isValidSpecifier("America/New_York") //=> true * @example IANAZone.isValidSpecifier("Sport~~blorp") //=> false - * @deprecated This method returns false for some valid IANA names. Use isValidZone instead. + * @deprecated For backward compatibility, this forwards to isValidZone, better use `isValidZone()` directly instead. * @return {boolean} */ static isValidSpecifier(s) { @@ -118,32 +118,65 @@ export default class IANAZone extends Zone { this.valid = IANAZone.isValidZone(name); } - /** @override **/ + /** + * The type of zone. `iana` for all instances of `IANAZone`. + * @override + * @type {string} + */ get type() { return "iana"; } - /** @override **/ + /** + * The name of this zone (i.e. the IANA zone name). + * @override + * @type {string} + */ get name() { return this.zoneName; } - /** @override **/ + /** + * Returns whether the offset is known to be fixed for the whole year: + * Always returns false for all IANA zones. + * @override + * @type {boolean} + */ get isUniversal() { return false; } - /** @override **/ + /** + * Returns the offset's common name (such as EST) at the specified timestamp + * @override + * @param {number} ts - Epoch milliseconds for which to get the name + * @param {Object} opts - Options to affect the format + * @param {string} opts.format - What style of offset to return. Accepts 'long' or 'short'. + * @param {string} opts.locale - What locale to return the offset name in. + * @return {string} + */ offsetName(ts, { format, locale }) { return parseZoneInfo(ts, format, locale, this.name); } - /** @override **/ + /** + * Returns the offset's value as a string + * @override + * @param {number} ts - Epoch milliseconds for which to get the offset + * @param {string} format - What style of offset to return. + * Accepts 'narrow', 'short', or 'techie'. Returning '+6', '+06:00', or '+0600' respectively + * @return {string} + */ formatOffset(ts, format) { return formatOffset(this.offset(ts), format); } - /** @override **/ + /** + * Return the offset in minutes for this zone at the specified timestamp. + * @override + * @param {number} ts - Epoch milliseconds for which to compute the offset + * @return {number} + */ offset(ts) { const date = new Date(ts); @@ -177,12 +210,21 @@ export default class IANAZone extends Zone { return (asUTC - asTS) / (60 * 1000); } - /** @override **/ + /** + * Return whether this Zone is equal to another zone + * @override + * @param {Zone} otherZone - the zone to compare + * @return {boolean} + */ equals(otherZone) { return otherZone.type === "iana" && otherZone.name === this.name; } - /** @override **/ + /** + * Return whether this Zone is valid. + * @override + * @type {boolean} + */ get isValid() { return this.valid; } diff --git a/src/zones/fixedOffsetZone.js b/src/zones/fixedOffsetZone.js index dcfa25a1d..b1ab4ab1d 100644 --- a/src/zones/fixedOffsetZone.js +++ b/src/zones/fixedOffsetZone.js @@ -52,16 +52,31 @@ export default class FixedOffsetZone extends Zone { this.fixed = offset; } - /** @override **/ + /** + * The type of zone. `fixed` for all instances of `FixedOffsetZone`. + * @override + * @type {string} + */ get type() { return "fixed"; } - /** @override **/ + /** + * The name of this zone. + * All fixed zones' names always start with "UTC" (plus optional offset) + * @override + * @type {string} + */ get name() { return this.fixed === 0 ? "UTC" : `UTC${formatOffset(this.fixed, "narrow")}`; } + /** + * The IANA name of this zone, i.e. `Etc/UTC` or `Etc/GMT+/-nn` + * + * @override + * @type {string} + */ get ianaName() { if (this.fixed === 0) { return "Etc/UTC"; @@ -70,32 +85,65 @@ export default class FixedOffsetZone extends Zone { } } - /** @override **/ + /** + * Returns the offset's common name at the specified timestamp. + * + * For fixed offset zones this equals to the zone name. + * @override + */ offsetName() { return this.name; } - /** @override **/ + /** + * Returns the offset's value as a string + * @override + * @param {number} ts - Epoch milliseconds for which to get the offset + * @param {string} format - What style of offset to return. + * Accepts 'narrow', 'short', or 'techie'. Returning '+6', '+06:00', or '+0600' respectively + * @return {string} + */ formatOffset(ts, format) { return formatOffset(this.fixed, format); } - /** @override **/ + /** + * Returns whether the offset is known to be fixed for the whole year: + * Always returns true for all fixed offset zones. + * @override + * @type {boolean} + */ get isUniversal() { return true; } - /** @override **/ + /** + * Return the offset in minutes for this zone at the specified timestamp. + * + * For fixed offset zones, this is constant and does not depend on a timestamp. + * @override + * @return {number} + */ offset() { return this.fixed; } - /** @override **/ + /** + * Return whether this Zone is equal to another zone (i.e. also fixed and same offset) + * @override + * @param {Zone} otherZone - the zone to compare + * @return {boolean} + */ equals(otherZone) { return otherZone.type === "fixed" && otherZone.fixed === this.fixed; } - /** @override **/ + /** + * Return whether this Zone is valid: + * All fixed offset zones are valid. + * @override + * @type {boolean} + */ get isValid() { return true; }