JSON Parser Date Extensions

Date parsing extensions for the JavaScript JSON parser to provide real JavaScript dates from JSON.parse()####

This small JavaScript library provides for automatically parsing JSON date strings to real JavaScript dates as part of regular JSON parsing. You can parse either individual date values or complex objects containing dates and have them automatically turned into dates, unlike the default JSON parser behavior of parsing to ISO 8601 date strings.

You can either manually run the date parsing or replace the JSON parser for the global scope to force all JSON operations to parse dates automatically, including those by other frameworks such as jQuery, angularJS etc.

This library came about as part of the following blog post:

• JavaScript JSON Date Parsing and real Dates

This library provides:

• JSON.dateParser
  JSON parser extension that can be used with JSON.parse() to parse dates with explicit calls to JSON.parse().

• JSON.parseWithDate()
  Function to provide a wrapper function that behaves like JSON.parse() but parses dates.

• JSON.useDateParser()
  Globally replace JSON.parse() with JSON.parseWithDates to affect all JSON.parse() operations within the current page/scope. Affects all JSON operations including framework JSON parsing such as jQuery.getJSON(), Angular $http functions etc.

• JSON.dateStringToDate()
  Safely converts JSON ISO and MSAJAX dates, raw ISO and MSAJAX string values and dates to JavaScript dates. This function is a simple helper to guarantee you get a date value regardless of which format the date is in with an optional override to return a known value if the date can't be resolved.

Installation

You can either use the files out of the root folder directly or you can install from one of the package repositories:

Bower

bower install json.date-extensions

NPM

npm install json.date-extensions

JSPM

jspm install json.date-extensions

Note this library has no exports - it only extends the JSON object with additional members you can call. You can require without capturing the return value.

require('json.date-extensions');JSON.useDateParser();

or use simple script references in your HTML document:

<scriptsrc="scripts/json.date-extensions.min.js"></script><script>JSON.useDateParser();</script>

Usage

This library provides a simple API for changing the behavior of the JSON parser. You can either explicitly parse JSON data using provided functions or change the behavior of the parser globally.

JSON.parseWithDate

Manual JSON parsing with automatic date conversion:

vardate=newDate();varjson=JSON.stringify(date);vardate2=JSON.parseWithDate(json);console.log(date2);// date: Wed Jan 01 2014 13:28:56 GMT-1000 (Hawaiian Standard Time) 

Likewise you can apply that to complex objects that contain dates:

varobj={id: "141923asd1",name: "rick",entered: newDate(),updated: newDate()};varjson=JSON.stringify(obj);varobj2=JSON.parseWithDate(json);equal(!obj2.entered.getTime,false,"Date should be a date object");equal(obj2.entered.toString(),obj.entered.toString(),"Dates should be equal");

JSON.useDateParser

useDateParser() can globally replace the JSON.parse() function with the JSON.parseWithDate() function, which results in automatically converting dates for all JSON operations on the global scope. This allows automatic conversions for all subsequent JSON.parse() calls including those inside of frameworks.

// enable global JSON date parsingJSON.useDateParser();vardate=newDate();varjson=JSON.stringify(date);// using just plain JSON.parse() should decode datesvardate2=JSON.parse(json);console.log(date2);equal(!date2.getTime,false,"Date should be a date object");equal(date2.toString(),date.toString(),"Dates should be equal");// optionally replace original parserJSON.useDateParser(false);

The following example demonstrates using $.getJSON() with automatic date conversion:

// enable global JSON date parsingJSON.useDateParser();$.getJSON("JsonWithDate.txt").done(function(data){console.log("jquery result.entered: "+data.entered+" result.updated: "+data.updated);equal(!data.entered.getTime,false,"Entered should be a date");}).success(function(){// Optionally replace original parserJSON.useDateParser(false);});

JSON.dateParser

dateParser is the JSON parse extension that is used to filter dates from date strings. You can use this filter directly with JSON.parse() although I'd recommend you use JSON.parseWithDate() instead.

varobj={id: "141923asd1",name: "rick",entered: newDate(),updated: newDate()};varjson=JSON.stringify(obj);varobj2=JSON.parse(json,JSON.dateParser);console.log(obj2.entered,obj2.updated);

JSON.dateStringToDate

dateStringToDate reliably provides JavaScript dates from JSON dates strings, plain strings in ISO or MS AJAX formats or dates. Useful when you are not converting JSON dates automatically and you need to be sure you always get consistent date values in code.

All of the following should produce a date:

vardate=newDate();varjson=JSON.stringify(date);// JSON datevardate2=JSON.dateStringToDate(json);console.log(date2);// string ISO datedate2=JSON.dateStringToDate("2014-01-01T13:13:34.441Z");console.log(date2);date2=JSON.dateStringToDate("2014-01-01T13:13:34.441Z");console.log(date2);// real date - just echoed backdate2=JSON.dateStringToDate(newDate());console.log(date2);