date-format 2.0.0 → 4.0.2

package/README.md

@@ -15,18 +15,28 @@ Formatting dates as strings
 
 ```javascript
 var format = require('date-format');
-format.asString(); //defaults to ISO8601 format and current date.
-format.asString(new Date()); //defaults to ISO8601 format
-format.asString('hh:mm:ss.SSS', new Date()); //just the time
+format.asString(); // defaults to ISO8601 format and current date
+format.asString(new Date()); // defaults to ISO8601 format
+format.asString('hh:mm:ss.SSS', new Date()); // just the time
+format.asString(format.ISO8601_WITH_TZ_OFFSET_FORMAT, new Date()); // in ISO8601 with timezone
 ```
 
 or
 
 ```javascript
 var format = require('date-format');
-format(); //defaults to ISO8601 format and current date.
-format(new Date());
-format('hh:mm:ss.SSS', new Date());
+format(); // defaults to ISO8601 format and current date
+format(new Date()); // defaults to ISO8601 format
+format('hh:mm:ss.SSS', new Date()); // just the time
+format(format.ISO8601_WITH_TZ_OFFSET_FORMAT, new Date()); // in ISO8601 with timezone
+```
+
+**output:**
+```javascript
+2017-03-14T14:10:20.391
+2017-03-14T14:10:20.391
+14:10:20.391
+2017-03-14T14:10:20.391+11:00
 ```
 
 Format string can be anything, but the following letters will be replaced (and leading zeroes added if necessary):
@@ -38,11 +48,11 @@ Format string can be anything, but the following letters will be replaced (and l
 * mm - `date.getMinutes()`
 * ss - `date.getSeconds()`
 * SSS - `date.getMilliseconds()`
-* O - timezone offset in +hm format (note that time will be in UTC if displaying offset)
+* O - timezone offset in ±hh:mm format (note that time will still be local if displaying offset)
 
 Built-in formats:
 * `format.ISO8601_FORMAT` - `2017-03-14T14:10:20.391` (local time used)
-* `format.ISO8601_WITH_TZ_OFFSET_FORMAT` - `2017-03-14T03:10:20.391+1100` (UTC + TZ used)
+* `format.ISO8601_WITH_TZ_OFFSET_FORMAT` - `2017-03-14T14:10:20.391+11:00` (local + TZ used)
 * `format.DATETIME_FORMAT` - `14 03 2017 14:10:20.391` (local time used)
 * `format.ABSOLUTETIME_FORMAT` - `14:10:20.391` (local time used)
 
@@ -54,5 +64,8 @@ The date format library has limited ability to parse strings into dates. It can
 var format = require('date-format');
 // pass in the format of the string as first argument
 format.parse(format.ISO8601_FORMAT, '2017-03-14T14:10:20.391');
+format.parse(format.ISO8601_WITH_TZ_OFFSET_FORMAT, '2017-03-14T14:10:20.391+1100');
+format.parse(format.ISO8601_WITH_TZ_OFFSET_FORMAT, '2017-03-14T14:10:20.391+11:00');
+format.parse(format.ISO8601_WITH_TZ_OFFSET_FORMAT, '2017-03-14T03:10:20.391Z');
 // returns Date
 ```

package/lib/index.js

@@ -1,15 +1,15 @@
-'use strict';
+"use strict";
 
 function padWithZeros(vNumber, width) {
-    var numAsString = vNumber.toString();
-    while (numAsString.length < width) {
-        numAsString = '0' + numAsString;
-    }
-    return numAsString;
+  var numAsString = vNumber.toString();
+  while (numAsString.length < width) {
+    numAsString = "0" + numAsString;
+  }
+  return numAsString;
 }
 
 function addZero(vNumber) {
-    return padWithZeros(vNumber, 2);
+  return padWithZeros(vNumber, 2);
 }
 
 /**
@@ -18,108 +18,191 @@ function addZero(vNumber) {
  * @private
  */
 function offset(timezoneOffset) {
-    var os = Math.abs(timezoneOffset);
-    var h = String(Math.floor(os / 60));
-    var m = String(os % 60);
-    if (h.length === 1) {
-        h = '0' + h;
-    }
-    if (m.length === 1) {
-        m = '0' + m;
-    }
-    return timezoneOffset < 0 ? '+' + h + m : '-' + h + m;
-}
-
-function datePart(date, displayUTC, part) {
-  return displayUTC ? date['getUTC' + part]() : date['get' + part]();
+  var os = Math.abs(timezoneOffset);
+  var h = String(Math.floor(os / 60));
+  var m = String(os % 60);
+  if (h.length === 1) {
+    h = "0" + h;
+  }
+  if (m.length === 1) {
+    m = "0" + m;
+  }
+  return timezoneOffset === 0 ? "Z" : (timezoneOffset < 0 ? "+" : "-") + h + ":" + m;
 }
 
 function asString(format, date) {
-    if (typeof format !== 'string') {
-        date = format;
-        format = module.exports.ISO8601_FORMAT;
-    }
-    if (!date) {
-        date =  module.exports.now();
-    }
+  if (typeof format !== "string") {
+    date = format;
+    format = module.exports.ISO8601_FORMAT;
+  }
+  if (!date) {
+    date = module.exports.now();
+  }
+
+  // Issue # 14 - Per ISO8601 standard, the time string should be local time
+  // with timezone info.
+  // See https://en.wikipedia.org/wiki/ISO_8601 section "Time offsets from UTC"
+
+  var vDay = addZero(date.getDate());
+  var vMonth = addZero(date.getMonth() + 1);
+  var vYearLong = addZero(date.getFullYear());
+  var vYearShort = addZero(vYearLong.substring(2, 4));
+  var vYear = format.indexOf("yyyy") > -1 ? vYearLong : vYearShort;
+  var vHour = addZero(date.getHours());
+  var vMinute = addZero(date.getMinutes());
+  var vSecond = addZero(date.getSeconds());
+  var vMillisecond = padWithZeros(date.getMilliseconds(), 3);
+  var vTimeZone = offset(date.getTimezoneOffset());
+  var formatted = format
+    .replace(/dd/g, vDay)
+    .replace(/MM/g, vMonth)
+    .replace(/y{1,4}/g, vYear)
+    .replace(/hh/g, vHour)
+    .replace(/mm/g, vMinute)
+    .replace(/ss/g, vSecond)
+    .replace(/SSS/g, vMillisecond)
+    .replace(/O/g, vTimeZone);
+  return formatted;
+}
 
-    var displayUTC = format.indexOf('O') > -1;
-
-    var vDay = addZero(datePart(date, displayUTC, 'Date'));
-    var vMonth = addZero(datePart(date, displayUTC, 'Month') + 1);
-    var vYearLong = addZero(datePart(date, displayUTC, 'FullYear'));
-    var vYearShort = addZero(vYearLong.substring(2, 4));
-    var vYear = (format.indexOf('yyyy') > -1 ? vYearLong : vYearShort);
-    var vHour = addZero(datePart(date, displayUTC, 'Hours'));
-    var vMinute = addZero(datePart(date, displayUTC, 'Minutes'));
-    var vSecond = addZero(datePart(date, displayUTC, 'Seconds'));
-    var vMillisecond = padWithZeros(datePart(date, displayUTC, 'Milliseconds'), 3);
-    var vTimeZone = offset(date.getTimezoneOffset());
-    var formatted = format
-        .replace(/dd/g, vDay)
-        .replace(/MM/g, vMonth)
-        .replace(/y{1,4}/g, vYear)
-        .replace(/hh/g, vHour)
-        .replace(/mm/g, vMinute)
-        .replace(/ss/g, vSecond)
-        .replace(/SSS/g, vMillisecond)
-        .replace(/O/g, vTimeZone);
-    return formatted;
+function setDatePart(date, part, value, local) {
+  date['set' + (local ? '' : 'UTC') + part](value);
 }
 
-function extractDateParts(pattern, str) {
+function extractDateParts(pattern, str, missingValuesDate) {
+  // Javascript Date object doesn't support custom timezone.  Sets all felds as
+  // GMT based to begin with.  If the timezone offset is provided, then adjust
+  // it using provided timezone, otherwise, adjust it with the system timezone.
+  var local = pattern.indexOf('O') < 0;
   var matchers = [
-    { pattern: /y{1,4}/, regexp: "\\d{1,4}", fn: function(date, value) { date.setFullYear(value); } },
-    { pattern: /MM/, regexp: "\\d{1,2}", fn: function(date, value) { date.setMonth(value -1); } },
-    { pattern: /dd/, regexp: "\\d{1,2}", fn: function(date, value) { date.setDate(value); } },
-    { pattern: /hh/, regexp: "\\d{1,2}", fn: function(date, value) { date.setHours(value); } },
-    { pattern: /mm/, regexp: "\\d\\d", fn: function(date, value) { date.setMinutes(value); } },
-    { pattern: /ss/, regexp: "\\d\\d", fn: function(date, value) { date.setSeconds(value); } },
-    { pattern: /SSS/, regexp: "\\d\\d\\d", fn: function(date, value) { date.setMilliseconds(value); } },
-    { pattern: /O/, regexp: "[+-]\\d{3,4}|Z", fn: function(date, value) {
-      if (value === 'Z') {
-        value = 0;
+    {
+      pattern: /y{1,4}/,
+      regexp: "\\d{1,4}",
+      fn: function(date, value) {
+        setDatePart(date, 'FullYear', value, local);
+      }
+    },
+    {
+      pattern: /MM/,
+      regexp: "\\d{1,2}",
+      fn: function(date, value) {
+        setDatePart(date, 'Month', (value - 1), local);
+      }
+    },
+    {
+      pattern: /dd/,
+      regexp: "\\d{1,2}",
+      fn: function(date, value) {
+        setDatePart(date, 'Date', value, local);
+      }
+    },
+    {
+      pattern: /hh/,
+      regexp: "\\d{1,2}",
+      fn: function(date, value) {
+        setDatePart(date, 'Hours', value, local);
+      }
+    },
+    {
+      pattern: /mm/,
+      regexp: "\\d\\d",
+      fn: function(date, value) {
+        setDatePart(date, 'Minutes', value, local);
+      }
+    },
+    {
+      pattern: /ss/,
+      regexp: "\\d\\d",
+      fn: function(date, value) {
+        setDatePart(date, 'Seconds', value, local);
+      }
+    },
+    {
+      pattern: /SSS/,
+      regexp: "\\d\\d\\d",
+      fn: function(date, value) {
+        setDatePart(date, 'Milliseconds', value, local);
       }
-      var offset = Math.abs(value);
-      var minutes = (offset % 100) + (Math.floor(offset / 100) * 60);
-      date.setMinutes(date.getMinutes() + (value > 0 ? minutes : -minutes));
-    } }
+    },
+    {
+      pattern: /O/,
+      regexp: "[+-]\\d{1,2}:?\\d{2}?|Z",
+      fn: function(date, value) {
+        if (value === "Z") {
+          value = 0;
+        }
+        else {
+          value = value.replace(":", "");
+        }
+        var offset = Math.abs(value);
+        var timezoneOffset = (value > 0 ? -1 :  1 ) * ((offset % 100) + Math.floor(offset / 100) * 60);
+        // Per ISO8601 standard: UTC = local time - offset
+        //
+        // For example, 2000-01-01T01:00:00-0700
+        //   local time: 2000-01-01T01:00:00
+        //   ==> UTC   : 2000-01-01T08:00:00 ( 01 - (-7) = 8 )
+        //
+        // To make it even more confusing, the date.getTimezoneOffset() is
+        // opposite sign of offset string in the ISO8601 standard.  So if offset
+        // is '-0700' the getTimezoneOffset() would be (+)420. The line above
+        // calculates timezoneOffset to matche Javascript's behavior.
+        //
+        // The date/time of the input is actually the local time, so the date
+        // object that was constructed is actually local time even thought the
+        // UTC setters are used.  This means the date object's internal UTC
+        // representation was wrong.  It needs to be fixed by substracting the
+        // offset (or adding the offset minutes as they are opposite sign).
+        //
+        // Note: the time zone has to be processed after all other fileds are
+        // set.  The result would be incorrect if the offset was calculated
+        // first then overriden by the other filed setters.
+        date.setUTCMinutes(date.getUTCMinutes() + timezoneOffset);
+      }
+    }
   ];
 
-  var parsedPattern = matchers.reduce(function(p, m) {
-    if (m.pattern.test(p.regexp)) {
-      m.index = p.regexp.match(m.pattern).index;
-      p.regexp = p.regexp.replace(m.pattern, "(" + m.regexp + ")");
-    } else {
-      m.index = -1;
-    }
-    return p;
-  }, { regexp: pattern, index: [] });
+  var parsedPattern = matchers.reduce(
+    function(p, m) {
+      if (m.pattern.test(p.regexp)) {
+        m.index = p.regexp.match(m.pattern).index;
+        p.regexp = p.regexp.replace(m.pattern, "(" + m.regexp + ")");
+      } else {
+        m.index = -1;
+      }
+      return p;
+    },
+    { regexp: pattern, index: [] }
+  );
 
   var dateFns = matchers.filter(function(m) {
     return m.index > -1;
   });
-  dateFns.sort(function(a, b) { return a.index - b.index; });
+  dateFns.sort(function(a, b) {
+    return a.index - b.index;
+  });
 
   var matcher = new RegExp(parsedPattern.regexp);
   var matches = matcher.exec(str);
   if (matches) {
-    var date = module.exports.now();
+    var date = missingValuesDate || module.exports.now();
     dateFns.forEach(function(f, i) {
-      f.fn(date, matches[i+1]);
+      f.fn(date, matches[i + 1]);
     });
+
     return date;
   }
 
-  throw new Error('String \'' + str + '\' could not be parsed as \'' + pattern + '\'');
+  throw new Error(
+    "String '" + str + "' could not be parsed as '" + pattern + "'"
+  );
 }
 
-function parse(pattern, str) {
+function parse(pattern, str, missingValuesDate) {
   if (!pattern) {
-    throw new Error('pattern must be supplied');
+    throw new Error("pattern must be supplied");
   }
 
-  return extractDateParts(pattern, str);
+  return extractDateParts(pattern, str, missingValuesDate);
 }
 
 /**
@@ -133,7 +216,7 @@ module.exports = asString;
 module.exports.asString = asString;
 module.exports.parse = parse;
 module.exports.now = now;
-module.exports.ISO8601_FORMAT = 'yyyy-MM-ddThh:mm:ss.SSS';
-module.exports.ISO8601_WITH_TZ_OFFSET_FORMAT = 'yyyy-MM-ddThh:mm:ss.SSSO';
-module.exports.DATETIME_FORMAT = 'dd MM yyyy hh:mm:ss.SSS';
-module.exports.ABSOLUTETIME_FORMAT = 'hh:mm:ss.SSS';
+module.exports.ISO8601_FORMAT = "yyyy-MM-ddThh:mm:ss.SSS";
+module.exports.ISO8601_WITH_TZ_OFFSET_FORMAT = "yyyy-MM-ddThh:mm:ss.SSSO";
+module.exports.DATETIME_FORMAT = "dd MM yyyy hh:mm:ss.SSS";
+module.exports.ABSOLUTETIME_FORMAT = "hh:mm:ss.SSS";

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "date-format",
-  "version": "2.0.0",
+  "version": "4.0.2",
   "description": "Formatting Date objects as strings since 2013",
   "main": "lib/index.js",
+  "files": [
+    "lib"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/nomiddlename/date-format.git"
@@ -25,9 +28,9 @@
   "readmeFilename": "README.md",
   "gitHead": "bf59015ab6c9e86454b179374f29debbdb403522",
   "devDependencies": {
-    "eslint": "^5.5.0",
-    "eslint-plugin-mocha": "^5.2.0",
-    "mocha": "^5.2.0",
+    "eslint": "^8.6.0",
+    "eslint-plugin-mocha": "^10.0.3",
+    "mocha": "^9.1.3",
     "should": "^13.2.3"
   }
 }

package/.eslintrc

@@ -1,12 +0,0 @@
-{
-  "extends": [
-    "eslint:recommended"
-  ],
-  "env": {
-    "node": true,
-    "mocha": true
-  },
-  "plugins": [
-      "mocha"
-  ]
-}

package/.travis.yml

@@ -1,6 +0,0 @@
-language: node_js
-sudo: false
-node_js:
-  - "10"
-  - "8"
-  - "6"

package/test/date_format-test.js

@@ -1,64 +0,0 @@
-'use strict';
-
-require('should');
-
-var dateFormat = require('../lib');
-
-function createFixedDate() {
-    return new Date(2010, 0, 11, 14, 31, 30, 5);
-}
-
-describe('date_format', function() {
-    var date = createFixedDate();
-
-    it('should default to now when a date is not provided', function() {
-        dateFormat.asString(dateFormat.DATETIME_FORMAT).should.not.be.empty();
-    });
-
-    it('should be usable directly without calling asString', function() {
-        dateFormat(dateFormat.DATETIME_FORMAT, date).should.eql('11 01 2010 14:31:30.005');
-    });
-
-    it('should format a date as string using a pattern', function() {
-        dateFormat.asString(dateFormat.DATETIME_FORMAT, date).should.eql('11 01 2010 14:31:30.005');
-    });
-
-    it('should default to the ISO8601 format', function() {
-        dateFormat.asString(date).should.eql('2010-01-11T14:31:30.005');
-    });
-
-    it('should provide a ISO8601 with timezone offset format', function() {
-        var tzDate = createFixedDate();
-        tzDate.setMinutes(tzDate.getMinutes() - tzDate.getTimezoneOffset() - 660);
-        tzDate.getTimezoneOffset = function () {
-            return -660;
-        };
-
-        // when tz offset is in the pattern, the date should be in UTC
-        dateFormat.asString(dateFormat.ISO8601_WITH_TZ_OFFSET_FORMAT, tzDate)
-            .should.eql('2010-01-11T03:31:30.005+1100');
-
-        tzDate = createFixedDate();
-        tzDate.setMinutes((tzDate.getMinutes() - tzDate.getTimezoneOffset()) + 120);
-        tzDate.getTimezoneOffset = function () {
-            return 120;
-        };
-
-        dateFormat.asString(dateFormat.ISO8601_WITH_TZ_OFFSET_FORMAT, tzDate)
-            .should.eql('2010-01-11T16:31:30.005-0200');
-    });
-
-    it('should provide a just-the-time format', function() {
-        dateFormat.asString(dateFormat.ABSOLUTETIME_FORMAT, date).should.eql('14:31:30.005');
-    });
-
-    it('should provide a custom format', function() {
-        var customDate = createFixedDate();
-        customDate.setMinutes((customDate.getMinutes() - customDate.getTimezoneOffset()) + 120);
-        customDate.getTimezoneOffset = function () {
-            return 120;
-        };
-
-        dateFormat.asString('O.SSS.ss.mm.hh.dd.MM.yy', customDate).should.eql('-0200.005.30.31.16.11.01.10');
-    });
-});

package/test/parse-test.js

@@ -1,139 +0,0 @@
-'use strict';
-
-require('should');
-var dateFormat = require('../lib');
-
-describe('dateFormat.parse', function() {
-  it('should require a pattern', function() {
-    (function() { dateFormat.parse() }).should.throw(/pattern must be supplied/);
-    (function() { dateFormat.parse(null) }).should.throw(/pattern must be supplied/);
-    (function() { dateFormat.parse('') }).should.throw(/pattern must be supplied/);
-  });
-
-  describe('with a pattern that has no replacements', function() {
-    it('should return a new date when the string matches', function() {
-      dateFormat.parse('cheese', 'cheese').should.be.a.Date()
-    });
-
-    it('should throw if the string does not match', function() {
-      (function() {
-        dateFormat.parse('cheese', 'biscuits');
-      }).should.throw(/String 'biscuits' could not be parsed as 'cheese'/);
-    });
-  });
-
-  describe('with a full pattern', function() {
-    var pattern = 'yyyy-MM-dd hh:mm:ss.SSSO';
-
-    it('should return the correct date if the string matches', function() {
-      var testDate = new Date();
-      testDate.setFullYear(2018);
-      testDate.setMonth(8);
-      testDate.setDate(13);
-      testDate.setHours(18);
-      testDate.setMinutes(10);
-      testDate.setSeconds(12);
-      testDate.setMilliseconds(392);
-      testDate.getTimezoneOffset = function() { return 600; };
-
-      dateFormat.parse(pattern, '2018-09-13 08:10:12.392+1000').getTime().should.eql(testDate.getTime());
-    });
-
-    it('should throw if the string does not match', function() {
-      (function() {
-        dateFormat.parse(pattern, 'biscuits')
-      }).should.throw(/String 'biscuits' could not be parsed as 'yyyy-MM-dd hh:mm:ss.SSSO'/);
-    });
-  });
-
-  describe('with a partial pattern', function() {
-    var testDate = new Date();
-    dateFormat.now = function() { return testDate; };
-
-    function verifyDate(actual, expected) {
-      actual.getFullYear().should.eql(expected.year || testDate.getFullYear());
-      actual.getMonth().should.eql(expected.month || testDate.getMonth());
-      actual.getDate().should.eql(expected.day || testDate.getDate());
-      actual.getHours().should.eql(expected.hours || testDate.getHours());
-      actual.getMinutes().should.eql(expected.minutes || testDate.getMinutes());
-      actual.getSeconds().should.eql(expected.seconds || testDate.getSeconds());
-      actual.getMilliseconds().should.eql(expected.milliseconds || testDate.getMilliseconds());
-    }
-
-    it('should return a date with missing values defaulting to current time', function() {
-      var date = dateFormat.parse('yyyy-MM', '2015-09');
-      verifyDate(date, { year: 2015, month: 8 });
-    });
-
-    it('should handle variations on the same pattern', function() {
-      var date = dateFormat.parse('MM-yyyy', '09-2015');
-      verifyDate(date, { year: 2015, month: 8 });
-
-      date = dateFormat.parse('yyyy MM', '2015 09');
-      verifyDate(date, { year: 2015, month: 8 });
-
-      date = dateFormat.parse('MM, yyyy.', '09, 2015.');
-      verifyDate(date, { year: 2015, month: 8 });
-    });
-
-    it('should match all the date parts', function() {
-      var date = dateFormat.parse('dd', '21');
-      verifyDate(date, { day: 21 });
-
-      date = dateFormat.parse('hh', '12');
-      verifyDate(date, { hours: 12 });
-
-      date = dateFormat.parse('mm', '34');
-      verifyDate(date,  { minutes: 34 });
-
-      date = dateFormat.parse('ss', '59');
-      verifyDate(date, { seconds: 59 });
-
-      date = dateFormat.parse('ss.SSS', '23.452');
-      verifyDate(date, { seconds: 23, milliseconds: 452 });
-
-      date = dateFormat.parse('hh:mm O', '05:23 +1000');
-      verifyDate(date, { hours: 15, minutes: 23 });
-
-      date = dateFormat.parse('hh:mm O', '05:23 -200');
-      verifyDate(date, { hours: 3, minutes: 23 });
-
-      date = dateFormat.parse('hh:mm O', '05:23 +0930');
-      verifyDate(date, { hours: 14, minutes: 53 });
-    });
-  });
-
-  describe('with a date formatted by this library', function() {
-    var testDate = new Date();
-    testDate.setUTCFullYear(2018);
-    testDate.setUTCMonth(8);
-    testDate.setUTCDate(13);
-    testDate.setUTCHours(18);
-    testDate.setUTCMinutes(10);
-    testDate.setUTCSeconds(12);
-    testDate.setUTCMilliseconds(392);
-
-    it('should format and then parse back to the same date', function() {
-      dateFormat.parse(
-        dateFormat.ISO8601_WITH_TZ_OFFSET_FORMAT,
-        dateFormat(dateFormat.ISO8601_WITH_TZ_OFFSET_FORMAT, testDate)
-      ).should.eql(testDate);
-
-      dateFormat.parse(
-        dateFormat.ISO8601_FORMAT,
-        dateFormat(dateFormat.ISO8601_FORMAT, testDate)
-      ).should.eql(testDate);
-
-      dateFormat.parse(
-        dateFormat.DATETIME_FORMAT,
-        dateFormat(dateFormat.DATETIME_FORMAT, testDate)
-      ).should.eql(testDate);
-
-      dateFormat.parse(
-        dateFormat.ABSOLUTETIME_FORMAT,
-        dateFormat(dateFormat.ABSOLUTETIME_FORMAT, testDate)
-      ).should.eql(testDate);
-    });
-
-  });
-});