Make time zone functionality public (#404)

Make `DateTime#zone` and `Info.normalizeZone` public

src/datetime.js

@@ -408,7 +408,7 @@ export default class DateTime {
     /**
      * @access private
      */
-    this.zone = zone;
+    this._zone = zone;
     /**
      * @access private
      */
@@ -918,6 +918,14 @@ export default class DateTime {
     return this.isValid ? this.loc.outputCalendar : null;
   }
 
+  /**
+   * Get the time zone associated with this DateTime.
+   * @type {Zone}
+   */
+  get zone() {
+    return this._zone;
+  }
+
   /**
    * Get the name of the time zone.
    * @type {string}

src/info.js

@@ -2,6 +2,7 @@ import DateTime from "./datetime";
 import Settings from "./settings";
 import Locale from "./impl/locale";
 import IANAZone from "./zones/IANAZone";
+import { normalizeZone } from "./impl/zoneUtil";
 
 import { hasFormatToParts, hasIntl, hasRelative } from "./impl/util";
 
@@ -31,6 +32,24 @@ export default class Info {
     return !!IANAZone.isValidSpecifier(zone) && IANAZone.isValidZone(zone);
   }
 
+  /**
+   * Converts the input into a {@link Zone} instance.
+   *
+   * * If `input` is already a Zone instance, it is returned unchanged.
+   * * If `input` is a string containing a valid time zone name, a Zone instance
+   *   with that name is returned.
+   * * If `input` is a string that doesn't refer to a known time zone, a Zone
+   *   instance with {@link Zone.isValid} == false is returned.
+   * * If `input is a number, a Zone instance with the specified fixed offset
+   *   in minutes is returned.
+   * * If `input` is `null` or `undefined`, the default zone is returned.
+   * @param {string|Zone|number} [input] - the value to be converted
+   * @return {Zone}
+   */
+  static normalizeZone(input) {
+    return normalizeZone(input, Settings.defaultZone);
+  }
+
   /**
    * Return an array of standalone month names.
    * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat

src/luxon.js

@@ -5,7 +5,19 @@ import Info from "./info";
 import Zone from "./zone";
 import FixedOffsetZone from "./zones/fixedOffsetZone";
 import IANAZone from "./zones/IANAZone";
+import InvalidZone from "./zones/invalidZone";
 import LocalZone from "./zones/localZone";
 import Settings from "./settings";
 
-export { DateTime, Duration, Interval, Info, Zone, FixedOffsetZone, IANAZone, LocalZone, Settings };
+export {
+  DateTime,
+  Duration,
+  Interval,
+  Info,
+  Zone,
+  FixedOffsetZone,
+  IANAZone,
+  InvalidZone,
+  LocalZone,
+  Settings
+};

test/datetime/getters.test.js

@@ -1,6 +1,7 @@
 /* global test expect */
 
 import { DateTime } from "../../src/luxon";
+import Settings from "../../src/settings";
 
 const dateTime = DateTime.fromJSDate(new Date(1982, 4, 25, 9, 23, 54, 123)),
   utc = DateTime.fromMillis(Date.UTC(1982, 4, 25, 9, 23, 54, 123)).toUTC(),
@@ -167,6 +168,17 @@ test("DateTime#locale returns the locale", () => {
   expect(dt.locale).toBe("be");
 });
 
+//------
+// zone/zoneName
+//------
+test("DateTime#zone returns the time zone", () => {
+  expect(dateTime.zone).toBe(Settings.defaultZone);
+});
+
+test("DateTime#zoneName returns the name of the time zone", () => {
+  expect(dateTime.zoneName).toBe(Settings.defaultZone.name);
+});
+
 //------
 // Misc
 //------

test/info/zones.test.js

@@ -1,6 +1,6 @@
 /* global test expect */
 
-import { Info } from "../../src/luxon";
+import { Info, FixedOffsetZone, IANAZone, InvalidZone, LocalZone, Settings } from "../../src/luxon";
 import { Helpers } from "../helpers";
 
 //------
@@ -56,3 +56,44 @@ test("Info.isValidIANAZone returns true for valid zones like America/Indiana/Ind
 test("Info.isValidIANAZone returns false for well-specified but invalid zones like America/Indiana/Blork", () => {
   expect(Info.isValidIANAZone("America/Indiana/Blork")).toBe(false);
 });
+
+//------
+// .normalizeZone()
+//------
+
+test("Info.normalizeZone returns Zone objects unchanged", () => {
+  const fixedOffsetZone = FixedOffsetZone.instance(5);
+  expect(Info.normalizeZone(fixedOffsetZone)).toBe(fixedOffsetZone);
+
+  const ianaZone = new IANAZone("Europe/Paris");
+  expect(Info.normalizeZone(ianaZone)).toBe(ianaZone);
+
+  const invalidZone = new InvalidZone("bumblebee");
+  expect(Info.normalizeZone(invalidZone)).toBe(invalidZone);
+
+  const localZone = LocalZone.instance;
+  expect(Info.normalizeZone(localZone)).toBe(localZone);
+});
+
+test.each([
+  ["Local", LocalZone.instance],
+  ["UTC", FixedOffsetZone.utcInstance],
+  ["GMT", FixedOffsetZone.utcInstance],
+  ["Etc/GMT+5", FixedOffsetZone.instance(-5 * 60)],
+  ["Etc/GMT-10", FixedOffsetZone.instance(+10 * 60)],
+  ["Europe/Paris", new IANAZone("Europe/Paris")],
+  [0, FixedOffsetZone.utcInstance],
+  [3, FixedOffsetZone.instance(3)],
+  [-11, FixedOffsetZone.instance(-11)]
+])("Info.normalizeZone converts valid input %p into valid Zone instance", (input, expected) => {
+  expect(Info.normalizeZone(input)).toEqual(expected);
+});
+
+test("Info.normalizeZone converts unknown name to invalid Zone", () => {
+  expect(Info.normalizeZone("bumblebee").isValid).toBe(false);
+});
+
+test("Info.normalizeZone converts null and undefined to default Zone", () => {
+  expect(Info.normalizeZone(null)).toBe(Settings.defaultZone);
+  expect(Info.normalizeZone(undefined)).toBe(Settings.defaultZone);
+});