iso8601-js 0.2.0 → 0.2.1

data/.travis.yml

@@ -0,0 +1,4 @@
+language: node_js
+env: TZ=PST+8
+node_js:
+  - 0.6

data/CHANGELOG.md

@@ -1,17 +1,23 @@
+## 0.2.1 (2011-12-29)
+
+* Polyfills for **Date.prototype.toJSON** and **Date.now**.
+
+
 ## 0.2.0 (2011-12-27)
 
 * API changed to match [ECMAScript 5.1][ecmascript] ISO 8601 support for the
   Date object.
   * `Date.prototype.toISO8601UTCString` is now `Date.prototype.toISOString`.
-  * `Date.prototype.toISO8601LocaleString` has been removed. Similar formatting
-    is available by passing *true* to `Date.prototype.toISO8601String` which
-    allows other customizations as well.
+  * Removed `Date.prototype.toISO8601LocaleString`. Similar formatting is
+    available by passing *true* for *localTimezone* to
+    `Date.prototype.toISO8601String`.
 * ISO 8601 UTC formatting falls back to native support if available. Performance
   improvement on modern browsers for common usages.
 * Stricter browser test for native ISO 8601 parsing. Ensures timezone offsets
   are correctly handled. Fixes Firefox issues.
 * Unit tests. Suite runs via node or browser harness.
 
+
 ## 0.1.0 (2011-12-23)
 
 * First release. Extracted from the Do web client, based on Paul Gallagher's

data/README.md

@@ -1,52 +1,50 @@
-iso8601.js
-==========
+iso8601.js [![Build Status][buildstatus]][travis]
+=================================================
 
-Partial ECMAScript 5.1 Date object cross-browser polyfill to add
-a [ISO 8601][iso8601] support to **Date.parse** and
-**Date.prototype.toISOString**. Originally based on Paul Gallagher's
-a [rfc3339date.js library][rfc3339date.js].
+Partial cross-browser polyfill to add [ISO 8601][iso8601] support to
+**Date.parse** and **Date.prototype.toISOString** as defined in ECMAScript 5.1.
+Originally based on Paul Gallagher's [rfc3339date.js library][rfc3339date.js].
 
 Supports only the subset of ISO 8601 described in
-a [ECMAScript 5.1 section 15.9.4.2][ecmascript], [RFC 3339][rfc3339], and the
-a [Date and Time Formats W3C NOTE][w3c-note].
+[ECMAScript 5.1 section 15.9.4.2][ecmascript], [RFC 3339][rfc3339], and the
+[Date and Time Formats W3C NOTE][w3c-note].
 
 
 ## Usage
 
-Download [iso8601.js][downloads] and include as usual before other scripts:
+Download [iso8601.js][downloads] and include before other scripts:
 
 ```html
 <script src="iso8601.min.js"></script>
 ```
 
-If you're using [Sprockets 2][sprockets], you can use the gem version of the
-library. Add to your Gemfile:
+Using [Sprockets 2][sprockets]? There's a gem version. Add to your Gemfile:
 
 ```ruby
 gem 'iso8601-js'
 ```
 
-If using Rails 3.1+, the library is automatically added to your asset paths.
-Otherwise add `ISO8601JS.assets_path` to your Sprockets environment:
+For Rails 3.1+, the library is automatically added to your asset paths. For
+other frameworks, add `ISO8601JS.assets_path` to your Sprockets environment:
 
 ```ruby
 env = Sprockets::Environment.new  # or however you initialize Sprockets
 env.append_path ISO8601JS.assets_path
 ```
 
-Then require it from the appropriate JavaScript or CoffeeScript files with the
-`= require` Sprockets directive:
+Include it in your JavaScript or CoffeeScript files with the `= require`
+Sprockets directive:
 
 JavaScript:
 
 ```javascript
-//= require iso8601-js
+//= require iso8601
 ```
 
 CoffeeScript:
 
 ```coffee-script
-#= require iso8601-js
+#= require iso8601
 ```
 
 
@@ -54,19 +52,18 @@ CoffeeScript:
 
 Parse ISO 8601 date/time strings two ways:
 
-* **Date.parseISO8601("...")** builds a Date instance from a string containing
-  an ISO 8610 date.
-* **Date.parse("...")** is polyfilled to attempt ISO 8601 parsing on the string
-  before using the browser's native `Date.parse`. Returns the number of
-  milliseconds between the Unix epoch and the date.
+* **Date.parseISO8601** creates a Date instance from a ISO 8601 date string.
+* **Date.parse** is polyfilled to attempt ISO 8601 parsing before using the
+  browser's native `Date.parse`. Returns the number of milliseconds between the
+  Unix epoch and the date. [*EC5 15.9.4.2*][ec15.9.4.2]
 
 Examples:
 
 ```js
-console.log(Date.parseISO8601("2010-07-20T15:00:00Z"))
+Date.parseISO8601("2010-07-20T15:00:00Z")
 // => Tue Jul 20 2010 08:00:00 GMT-0700 (PDT)
 
-console.log(Date.parse("2010-07-20T15:00:00Z"));
+Date.parse("2010-07-20T15:00:00Z")
 // => 1307834445456
 ```
 
@@ -75,7 +72,11 @@ console.log(Date.parse("2010-07-20T15:00:00Z"));
 
 Format ISO 8601 date strings directly from Date instances:
 
-* **Date.prototype.toISOString** generates an ISO 8601 string in UTC.
+* **Date.prototype.toISOString** generates an ISO 8601 UTC string.
+  [*EC5 15.9.5.32*][ec15.9.5.43]. Throws `RangeError` for invalid dates.
+* **Date.prototype.toJSON** generates an ISO 8601 UTC string for use by
+  JSON.stringify. Returns `null` for invalid dates.
+  [*EC5 15.9.5.44*][ec15.9.5.44]
 * **Date.prototype.toISO8601String** generates an ISO 8601 string with
   formatting options:
   * *localTimezone*: Use local timezone with offset or UTC? Defaults to *false*.
@@ -85,16 +86,34 @@ Format ISO 8601 date strings directly from Date instances:
 Examples:
 
 ```js
-var date = Date.parseISO8601("2010-07-20T15:00:00Z");
+var date = Date.parseISO8601("2010-07-20T15:00:00Z")
 
-console.log(date.toISOString());
+date.toISOString()
 // => "2010-07-20T15:00:00.000Z"
 
-console.log(date.toISO8601String(true, true, false));
+date.toJSON()
+// => "2010-07-20T15:00:00.000Z"
+
+date.toISO8601String(true, true, false)
 // => "2010-07-20T08:00:00-07:00"
 ```
 
 
+## Other
+
+Other EC5 Date-related polyfills:
+
+* **Date.now** returns the number of milliseconds since the Unix epoch.
+  [*EC5 15.9.4.4*][ec15.9.4.4]
+
+Examples:
+
+```js
+Date.now()
+// => 1325174662624
+```
+
+
 ## Caveats
 
 The Date constructor is not polyfilled to support ISO 8601. Avoid using `new
@@ -112,6 +131,8 @@ Patches and bug reports are always welcome. Just send a
 
 
 
+[buildstatus]:    https://secure.travis-ci.org/Do/iso8601.js.png?branch=master "Build status"
+[travis]:         http://travis-ci.org/Do/iso8601.js
 [iso8601]:        http://en.wikipedia.org/wiki/ISO_8601
 [rfc3339date.js]: https://github.com/tardate/rfc3339date.js
 [ecmascript]:     http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf
@@ -119,6 +140,10 @@ Patches and bug reports are always welcome. Just send a
 [w3c-note]:       http://www.w3.org/TR/NOTE-datetime
 [downloads]:      https://github.com/Do/iso8601.js/downloads
 [sprockets]:      https://github.com/sstephenson/sprockets
+[ec15.9.4.2]:     http://es5.github.com/#x15.9.4.2
+[ec15.9.5.43]:    http://es5.github.com/#x15.9.5.43
+[ec15.9.5.44]:    http://es5.github.com/#x15.9.5.44
+[ec15.9.4.4]:     http://es5.github.com/#x15.9.4.4
 [coffeescript]:   http://coffeescript.org/
 [pullrequests]:   https://github.com/Do/iso8601.js/pulls
 [issues]:         https://github.com/Do/iso8601.js/issues

data/lib/iso8601-js/version.rb

@@ -1,3 +1,3 @@
 module ISO8601JS
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

data/lib/iso8601.coffee

@@ -47,9 +47,8 @@ pad = (number, length = 2) ->
     result = '0' + result
   result
 
-# Unit tests to check native ISO 8601 support
+# Unit test to check native ISO 8601 parsing support
 supportsISOParsing = Date.parse?('2011-06-11T23:20:45.456-0700') is 1307859645456
-supportsISOFormatting = Date::toISOString?
 
 
 
@@ -119,19 +118,38 @@ Date::toISO8601String = (localTimezone = false, separators = true, milliseconds
 #
 # Format the date in UTC ISO 8601 / RFC 3339.
 #
-# Defined in ECMAScript 5.1 section 15.9.5.43. An implementation is set only if
-# the browser lacks native support.
+# Defined in ECMAScript 5.1 15.9.5.43. An implementation is set only if the
+# browser lacks native support.
 #
 # Examples
 #
 #   new Date().toISOString()
 #   // => "2010-07-25T11:51:31.427Z"
 #
-unless supportsISOFormatting
+unless Date::toISOString
   Date::toISOString = Date::toISO8601String
 
 
 
+# Date.prototype.toJSON
+#
+# Format the date in ISO 8601 UTC suitable for use by JSON.stringify. Returns
+# null for invalid dates. See ECMAScript 5.1 15.9.5.44.
+#
+# Examples
+#
+#   new Date().toJSON()
+#   // => "2010-07-25T11:51:31.427Z"
+#
+unless Date::toJSON
+  Date::toJSON = (key) ->
+    if isFinite(@valueOf())
+      @toISOString()
+    else
+      null  # Spec requires returning null for non-finite values
+
+
+
 # Date.parseISO8601
 #
 # Parses ISO8601 / RFC 3339 date strings to a Date object. Uses native browser
@@ -234,3 +252,18 @@ else if not supportsISOParsing
     result = parseISO8601(input)?.getTime()
     result = oldDateParse(input) if not result and oldDateParse
     result
+
+
+
+# Date.now
+#
+# Returns the Number value (milliseconds since the Unix epoch) of the current
+# time. See ECMAScript 5.1 15.9.4.4.
+#
+# Examples
+#
+#   Date.now()
+#   // => 1325174662624
+#
+unless Date.now
+  Date.now = -> new Date().getTime()

data/package.json

@@ -36,5 +36,8 @@
     "uglify-js": "1.2.2",
     "mocha": "0.7.1",
     "chai": "0.1.4"
+  },
+  "scripts": {
+    "test": "mocha --reporter spec"
   }
 }

data/test/test.date.coffee

@@ -1,9 +1,12 @@
-# Tests for the polyfill parsing and formatting functions. Browser native
-# support detection and usage untested.
+# Tests for the iso8601.js library
 #
 # For proper testing of timezone offsets, the suite must be run in the PST (non
 # daylight savings) timezone environment, e.g. TZ='PST+8'.
 #
+# Functions are tested directly where possible. Some of these tests won't test
+# the polyfill functions unless run in a non-ECMAScript 5.1 environment -
+# they'll just test native versions. Be sure to run the suite in older engines.
+#
 
 chai = @chai || require('chai')
 assert = chai.assert
@@ -12,8 +15,10 @@ require('../lib/iso8601') if require?
 
 describe 'Date', ->
 
-  # Date fixture: Sat Jun 18, 2011 02:20:45.678 PST
-  date = new Date(1308392445678)
+  # Date fixtures
+  date = new Date(1308392445678)         # Sat Jun 18, 2011 02:20:45.678 PST
+  invalidDate = new Date('not a date')   # Doesn't throw exception on creation
+
 
   describe 'toISO8601String', ->
 
@@ -36,12 +41,23 @@ describe 'Date', ->
       assert.equal '2011-06-18T02:20:45.678-08:00', date.toISO8601String(true, true, true)
 
     it 'throws RangeError for Invalid Dates', ->
-      fn = -> new Date('not a date').toISO8601String()
+      fn = -> invalidDate.toISO8601String()    # Should throw exception when called
       expect(fn).to.throw RangeError
 
 
+  describe 'toJSON', ->
+
+    it 'returns the UTC ISO 8601 string for valid dates', ->
+      assert.equal '2011-06-18T10:20:45.678Z', date.toJSON()
+
+    it 'returns null for invalid dates', ->
+      assert.equal null, invalidDate.toJSON()
+
+
   describe 'parseISO8601', ->
 
+    # Using Date.parseISO8601(..., false) to parse without browser fallback.
+
     it 'parses UTC ISO 8601 strings', ->
       assert.equal date.getTime(), Date.parseISO8601('2011-06-18T10:20:45.678Z', false).getTime()
 
@@ -69,3 +85,8 @@ describe 'Date', ->
 
     it 'falls back to native Date.parse for non ISO strings', ->
       assert.equal 807926400000, Date.parse('Wed, 09 Aug 1995 00:00:00 GMT')
+
+
+  describe 'now', ->
+    it 'returns the current time in milliseconds since epoch', ->
+      assert.equal new Date().getTime(), Date.now()

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: iso8601-js
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -11,11 +11,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-12-27 00:00:00.000000000Z
+date: 2011-12-29 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sprockets
-  requirement: &70341578450300 !ruby/object:Gem::Requirement
+  requirement: &70233797964100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -23,10 +23,10 @@ dependencies:
         version: '2.0'
   type: :runtime
   prerelease: false
-  version_requirements: *70341578450300
+  version_requirements: *70233797964100
 - !ruby/object:Gem::Dependency
   name: coffee-script
-  requirement: &70341578449500 !ruby/object:Gem::Requirement
+  requirement: &70233797962980 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -34,10 +34,10 @@ dependencies:
         version: '2.2'
   type: :runtime
   prerelease: false
-  version_requirements: *70341578449500
+  version_requirements: *70233797962980
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70341578448740 !ruby/object:Gem::Requirement
+  requirement: &70233797961920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -45,7 +45,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70341578448740
+  version_requirements: *70233797961920
 description: Adds cross-browser ISO 8601 support to the JavaScript Date object based
   on EC5.1. This is a Sprockets gem to simplify inclusion of the client-side library.
 email:
@@ -57,6 +57,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - CHANGELOG.md
 - Gemfile
 - LICENSE