date-format 0.0.2 → 2.0.0

package/.eslintrc

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

package/.travis.yml

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

package/README.md

@@ -3,31 +3,56 @@ date-format
 
 node.js formatting of Date objects as strings. Probably exactly the same as some other library out there.
 
-        npm install date-format
+```sh
+npm install date-format
+```
 
 usage
 =====
 
-        var format = require('date-format');
-        format.asString(new Date()); //defaults to ISO8601 format
-        format.asString('hh:mm:ss.SSS', new Date()); //just the time
+Formatting dates as strings
+----
 
-or
+```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
+```
 
-        var format = require('date-format');
-        format(new Date());
-        format('hh:mm:ss.SSS', new Date());
+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 string can be anything, but the following letters will be replaced (and leading zeroes added if necessary):
-* dd - date.getDate()
-* MM - date.getMonth() + 1
-* yy - date.getFullYear().toString().substring(2, 4)
-* yyyy - date.getFullYear()
-* hh - date.getHours()
-* mm - date.getMinutes()
-* ss - date.getSeconds()
-* SSS - date.getMilliseconds()
-* O - timezone offset in +hm format
-
-That's it.
+* dd - `date.getDate()`
+* MM - `date.getMonth() + 1`
+* yy - `date.getFullYear().toString().substring(2, 4)`
+* yyyy - `date.getFullYear()`
+* hh - `date.getHours()`
+* 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)
+
+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.DATETIME_FORMAT` - `14 03 2017 14:10:20.391` (local time used)
+* `format.ABSOLUTETIME_FORMAT` - `14:10:20.391` (local time used)
+
+Parsing strings as dates
+----
+The date format library has limited ability to parse strings into dates. It can convert strings created using date format patterns (as above), but if you're looking for anything more sophisticated than that you should probably look for a better library ([momentjs](https://momentjs.com) does pretty much everything).
+
+```javascript
+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');
+// returns Date
+```

package/lib/index.js

@@ -1,74 +1,139 @@
-"use strict";
-
-module.exports = asString
-asString.asString = asString
-
-asString.ISO8601_FORMAT = "yyyy-MM-dd hh:mm:ss.SSS";
-asString.ISO8601_WITH_TZ_OFFSET_FORMAT = "yyyy-MM-ddThh:mm:ssO";
-asString.DATETIME_FORMAT = "dd MM yyyy hh:mm:ss.SSS";
-asString.ABSOLUTETIME_FORMAT = "hh:mm:ss.SSS";
+'use strict';
 
 function padWithZeros(vNumber, width) {
-  var numAsString = vNumber + "";
-  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);
 }
 
 /**
- * Formats the TimeOffest
+ * Formats the TimeOffset
  * Thanks to http://www.svendtofte.com/code/date_format/
  * @private
  */
-function offset(date) {
-  // Difference to Greenwich time (GMT) in hours
-  var os = Math.abs(date.getTimezoneOffset());
-  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 date.getTimezoneOffset() < 0 ? "+"+h+m : "-"+h+m;
+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]();
+}
+
+function asString(format, date) {
+    if (typeof format !== 'string') {
+        date = format;
+        format = module.exports.ISO8601_FORMAT;
+    }
+    if (!date) {
+        date =  module.exports.now();
+    }
+
+    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 asString(/*format,*/ date) {
-  var format = asString.ISO8601_FORMAT;
-  if (typeof(date) === "string") {
-    format = arguments[0];
-    date = arguments[1];
+function extractDateParts(pattern, str) {
+  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;
+      }
+      var offset = Math.abs(value);
+      var minutes = (offset % 100) + (Math.floor(offset / 100) * 60);
+      date.setMinutes(date.getMinutes() + (value > 0 ? minutes : -minutes));
+    } }
+  ];
+
+  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; });
+
+  var matcher = new RegExp(parsedPattern.regexp);
+  var matches = matcher.exec(str);
+  if (matches) {
+    var date = module.exports.now();
+    dateFns.forEach(function(f, i) {
+      f.fn(date, matches[i+1]);
+    });
+    return date;
   }
-  
-  if (!date) {
-    date = new Date();
+
+  throw new Error('String \'' + str + '\' could not be parsed as \'' + pattern + '\'');
+}
+
+function parse(pattern, str) {
+  if (!pattern) {
+    throw new Error('pattern must be supplied');
   }
 
-  var vDay = addZero(date.getDate());
-  var vMonth = addZero(date.getMonth()+1);
-  var vYearLong = addZero(date.getFullYear());
-  var vYearShort = addZero(date.getFullYear().toString().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);
-  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;
-
-};
+  return extractDateParts(pattern, str);
+}
+
+/**
+ * Used for testing - replace this function with a fixed date.
+ */
+function now() {
+  return new Date();
+}
+
+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';

package/package.json

@@ -1,26 +1,33 @@
 {
   "name": "date-format",
-  "version": "0.0.2",
-  "description": "formatting Date objects as strings since 2013",
+  "version": "2.0.0",
+  "description": "Formatting Date objects as strings since 2013",
   "main": "lib/index.js",
-  "scripts": {
-    "test": "mocha"
-  },
   "repository": {
     "type": "git",
     "url": "https://github.com/nomiddlename/date-format.git"
   },
+  "engines": {
+    "node": ">=4.0"
+  },
+  "scripts": {
+    "lint": "eslint lib/* test/*",
+    "pretest": "eslint lib/* test/*",
+    "test": "mocha"
+  },
   "keywords": [
     "date",
     "format",
     "string"
   ],
-  "author": "Gareth Jones <gareth.jones@sensis.com.au>",
+  "author": "Gareth Jones <gareth.nomiddlename@gmail.com>",
   "license": "MIT",
   "readmeFilename": "README.md",
   "gitHead": "bf59015ab6c9e86454b179374f29debbdb403522",
   "devDependencies": {
-    "should": "~1.2.2",
-    "mocha": "~1.12.0"
+    "eslint": "^5.5.0",
+    "eslint-plugin-mocha": "^5.2.0",
+    "mocha": "^5.2.0",
+    "should": "^13.2.3"
   }
 }

package/test/date_format-test.js

@@ -1,42 +1,64 @@
-"use strict";
-var should = require('should')
-, dateFormat = require('../lib');
+'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 = new Date(2010, 0, 11, 14, 31, 30, 5);
-
-  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-11 14:31:30.005');
-  });
-
-  it('should provide a ISO8601 with timezone offset format', function() {
-    date.getTimezoneOffset = function() { return -660; };
-    dateFormat.asString(
-      dateFormat.ISO8601_WITH_TZ_OFFSET_FORMAT, 
-      date
-    ).should.eql(
-      "2010-01-11T14:31:30+1100"
-    );
-
-    date.getTimezoneOffset = function() { return 120; };
-    dateFormat.asString(
-      dateFormat.ISO8601_WITH_TZ_OFFSET_FORMAT, 
-      date
-    ).should.eql(
-      "2010-01-11T14:31:30-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() {
-    date.getTimezoneOffset = function() { return 120; };
-    dateFormat.asString("O.SSS.ss.mm.hh.dd.MM.yy", date).should.eql('-0200.005.30.31.14.11.01.10');
-  });
+    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

@@ -0,0 +1,139 @@
+'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);
+    });
+
+  });
+});

package/.npmignore

@@ -1,15 +0,0 @@
-lib-cov
-*.seed
-*.log
-*.csv
-*.dat
-*.out
-*.pid
-*.gz
-
-pids
-logs
-results
-
-npm-debug.log
-node_modules