- Enhancement: Add timezone properties to `today`

- Docs: JSDoc and README; list available params

README.md

@@ -26,11 +26,13 @@ Public endpoints are now available on bahai-browser.org:
 
 ## Running
 
-To launch the API server, simply navigate to the main folder and type `npm start`.
+To launch the API server, simply navigate to the main folder and type
+`npm start`.
 
 ## Examples
 
-From either endpoint, the output is returned in a similar format: a JSON object containing a message, a Baháʼí calendar date, and a Gregorian date/time.
+From either endpoint, the output is returned in a similar format: a JSON object
+containing a message, a Baháʼí calendar date, and a Gregorian date/time.
 
 ### Today
 
@@ -43,7 +45,8 @@ URL: localhost:1844/today
         "year": 174,
         "month": 14,
         "day": 13,
-        "month_name": "Masá’il"
+        "month_name": "Masá’il",
+        "timezone_id": "Asia/Jerusalem"
     },
     "greg_date": {
         "year": 2017,
@@ -51,12 +54,27 @@ URL: localhost:1844/today
         "day": 5,
         "hour": 23,
         "minute": 19,
-        "second": 12
+        "second": 12,
+        "timezoneOffset": 0
     }
 }
 ```
 
-### May 23, 1844
+### `date`
+
+Available parameters include:
+
+- `year`
+- `month`
+- `day`
+- `hour`
+- `minute`
+- `second`
+- `latitude`
+- `longitude`
+- `timezoneId`
+
+#### May 23, 1844
 
 URL: localhost:1844/date?year=1844&month=5&day=23&hour=20&minute=45
 
@@ -79,12 +97,12 @@ Output:
         "hour": 20,
         "minute": 45,
         "second": 0,
-        "timezoneOffset": 0
+        "timezoneOffset": -480
     }
 }
 ```
 
-### February 15, 2014
+#### February 15, 2014
 
 URL: localhost:1844/date?year=2014&month=2&day=15&hour=13&minute=45
 
@@ -107,7 +125,7 @@ Output:
         "hour": 13,
         "minute": 45,
         "second": 0,
-        "timezoneOffset": 0
+        "timezoneOffset": -485
     }
 }
 ```

api/controllers/bDateController.js

@@ -70,13 +70,14 @@ exports.test = function (req, res) {
 };
 
 /**
-* @typedef {PlainObject} LocalBadiDateObject
+* @typedef {PlainObject} BadiDateInfo
 * @property {string} message
 * @property {PlainObject} badi_date
 * @property {Integer} badi_date.year
 * @property {Integer} badi_date.month
 * @property {Integer} badi_date.day
 * @property {string} badi_date.month_name
+* @property {string} badi_date.timezone_id
 * @property {PlainObject} greg_date
 * @property {Integer} greg_date.year
 * @property {Integer} greg_date.month
@@ -84,11 +85,19 @@ exports.test = function (req, res) {
 * @property {Integer} greg_date.hour
 * @property {Integer} greg_date.minute
 * @property {Integer} greg_date.second
+* @property {Integer} greg_date.timezoneOffset
+*/
+
+/**
+* @typedef {PlainObject} BadiDateResponse
+* @property {Date} now
+* @property {LocalBadiDate} nowBadi
+* @property {BadiDateInfo} json
 */
 
 /**
  * @param {DateConfig} dateObj
- * @returns {LocalBadiDateObject}
+ * @returns {BadiDateResponse}
  */
 const getTodayJSON = exports.getTodayJSON = function (dateObj = {}) {
   const now = new Date();
@@ -110,7 +119,8 @@ const getTodayJSON = exports.getTodayJSON = function (dateObj = {}) {
         year: nowBadi.badiDate.year,
         month: nowBadi.badiDate.month,
         day: nowBadi.badiDate.day,
-        month_name: nowBadi.badiDate.format('MM+')
+        month_name: nowBadi.badiDate.format('MM+'),
+        timezone_id: nowBadi.timezoneId
       },
       greg_date: {
         year: now.getFullYear(),
@@ -118,7 +128,8 @@ const getTodayJSON = exports.getTodayJSON = function (dateObj = {}) {
         day: now.getDate(),
         hour: now.getHours(),
         minute: now.getMinutes(),
-        second: now.getSeconds()
+        second: now.getSeconds(),
+        timezoneOffset: now.getTimezoneOffset()
       }
     }
   };
@@ -146,6 +157,20 @@ exports.date = function (req, res) {
   res.json(dateInfo.json);
 };
 
+/**
+* @typedef {DateConfig} FullDateConfig
+* @property {Integer} year
+* @property {Integer} month
+* @property {Integer} day
+* @property {Integer} hour
+* @property {Integer} minute
+* @property {Integer} second
+*/
+
+/**
+ * @param {FullDateConfig} dateObj
+ * @returns {BadiDateResponse}
+ */
 const getDate = exports.getDate = function (dateObj) {
   const year = sanitizeInteger(dateObj.year);
   const month = sanitizeInteger(dateObj.month) - 1;