Add relative time formatting

Gruntfile.js

@@ -279,6 +279,25 @@ module.exports = function( grunt ) {
 									endFile: "src/build/outro.js"
 								}
 							}
+						},
+						{
+							name: "globalize.relative-time",
+							include: [ "relative-time" ],
+							exclude: [
+								"cldr",
+								"cldr/event",
+								"cldr/supplemental",
+								"./core",
+								"./number",
+								"./plural"
+							],
+							create: true,
+							override: {
+								wrap: {
+									startFile: "src/build/intro-relative-time.js",
+									endFile: "src/build/outro.js"
+								}
+							}
 						}
 					]
 				}
@@ -330,7 +349,8 @@ module.exports = function( grunt ) {
 					"tmp/globalize/date.min.js": [ "dist/globalize/date.js" ],
 					"tmp/globalize/number.min.js": [ "dist/globalize/number.js" ],
 					"tmp/globalize/plural.min.js": [ "dist/globalize/plural.js" ],
-					"tmp/globalize/message.min.js": [ "dist/globalize/message.js" ]
+					"tmp/globalize/message.min.js": [ "dist/globalize/message.js" ],
+					"tmp/globalize/relative-time.min.js": [ "dist/globalize/relative-time.js" ]
 				}
 			}
 		},

README.md

@@ -28,6 +28,7 @@ Node.js module.
   - [Number module](#number_module)
     - [Currency module](#currency_module)
   - [Plural module](#plural_module)
+  - [Relative time module](#relative-time_module)
   - more to come...
 - [Error reference](#error)
 - [Development](#development)
@@ -103,6 +104,7 @@ information on its usage.
 | globalize/message.js | +5.6KB | [Message module](#message_module) provides ICU message format support |
 | globalize/number.js | +2.9KB | [Number module](#number_module) provides number formatting and parsing |
 | globalize/plural.js | +1.7KB | [Plural module](#plural_module) provides pluralization support |
+| globalize/relative-time.js | +0.7KB | [Relative time module](#relative-time_module) provides relative time formatting support |
 
 <a name="browser_support"></a>
 ### Browser Support
@@ -172,6 +174,7 @@ requirements. See table below.
 | Date module | cldr/main/`locale`/ca-gregorian.json<br>cldr/main/`locale`/timeZoneNames.json<br>cldr/supplemental/timeData.json<br>cldr/supplemental/weekData.json<br>+CLDR JSON files from number module |
 | Number module | cldr/main/`locale`/numbers.json<br>cldr/supplemental/numberingSystems.json |
 | Plural module | cldr/supplemental/plurals.json |
+| Relative time module | cldr/main/`locale`/dateFields.json<br>+CLDR JSON files from number and plural modules |
 
 *(b) How am I supposed to get and load CLDR content?*
 
@@ -384,6 +387,26 @@ to you in different flavors):
 
   Alias for `.pluralGenerator()( value )`.
 
+<a name="relative-time_module"></a>
+### Relative time module
+
+- **`.relativeTimeFormatter( unit [, options] )`**
+
+ Returns a function that formats a relative time according to the given unit, options, and the
+ default/instance locale.
+
+  ```javascript
+  .relativeTimeFormatter( "day" )( 1 )  ➡  "tomorrow"
+  .relativeTimeFormatter( "month" )( -1 )  ➡  "last month"
+  .relativeTimeFormatter( "month" )( 3 )  ➡  "in 3 months"
+  ```
+
+  [Read more...](doc/api/relative-time/relative-time-formatter.md)
+
+- **`.formatRelativeTime( value, unit [, options] )`**
+
+  Alias for `.relativeTimeFormatter( unit, options )( value )`.
+
 
 <a name="error"></a>
 ## Error reference
@@ -477,6 +500,8 @@ to you in different flavors):
 │   ├── number/ (number source code)
 │   ├── plural.js (plural module)
 │   ├── plural/ (plural source code)
+│   ├── relative-time.js (relative time module)
+│   ├── relative-time/ (relative time source code)
 │   └── util/ (basic JavaScript helpers polyfills, eg array.map)
 └── test/ (unit and functional test files)
     ├── fixtures/ (CLDR fixture data)

doc/api/relative-time/relative-time-formatter.md

@@ -0,0 +1,58 @@
+## .relativeTimeFormatter( unit[, options ]) ➜ function( value )
+
+Returns a function that formats a relative time according to the given unit, options, and the
+default/instance locale.
+
+The returned function is invoked with one argument: the number `value` to
+be formatted.
+
+### Parameters
+
+**unit**
+
+String value indicating the unit to be formatted. eg. "day", "week", "month", etc.
+
+**options**
+
+- form: [String] eg. "short" or "narrow". Or falsy for default long form
+
+**value**
+
+The number to be formatted.
+
+
+### Example
+
+Prior to using any relative time methods, you must load
+`cldr/main/{locale}/dateFields.json` and the
+CLDR content required by the number and plural modules. Read [CLDR content][] if you need
+more information.
+
+[CLDR content]: ../../../README.md#2-cldr-content
+
+You can use the static method `Globalize.relativeTimeFormatter()`, which uses the default
+locale.
+
+```javascript
+var formatter;
+
+Globalize.locale( "en" );
+formatter = Globalize.relativeTimeFormatter( "month" );
+
+formatter( 1 ); // "next month"
+formatter( 3 ); // "in 3 months"
+formatter( -1 ); // "last month"
+formatter( -3 ); // "3 months ago"
+```
+
+You can use the instance method `.relativeTimeFormatter()`, which uses the instance locale.
+
+```javascript
+var globalize = new Globalize( "en" ),
+	formatter = globalize.relativeTimeFormatter( "week" );
+
+formatter( 1 ); // "next week"
+```
+
+
+

examples/amd-bower/index.html

@@ -30,6 +30,7 @@ <h2>Demo output</h2>
             <li><span id="message-2"></span></li>
             <li><span id="message-3"></span></li>
         </ul>
+        <p>Something happened: <span id="relative-time"></span></p>
     </div>
 
     <!--

examples/amd-bower/main.js

@@ -31,6 +31,7 @@ require([
 	"json!cldr-data/main/en/currencies.json",
 	"json!cldr-data/main/en/ca-gregorian.json",
 	"json!cldr-data/main/en/numbers.json",
+	"json!cldr-data/main/en/dateFields.json",
 	"json!cldr-data/supplemental/currencyData.json",
 	"json!cldr-data/supplemental/likelySubtags.json",
 	"json!cldr-data/supplemental/plurals.json",
@@ -43,8 +44,9 @@ require([
 	"globalize/date",
 	"globalize/message",
 	"globalize/number",
-	"globalize/plural"
-], function( Globalize, enCurrencies, enGregorian, enNumbers, currencyData, likelySubtags,
+	"globalize/plural",
+	"globalize/relative-time"
+], function( Globalize, enCurrencies, enGregorian, enNumbers, enDateFields, currencyData, likelySubtags,
 	pluralsData, timeData, weekData, messages ) {
 
 	var en, like, number;
@@ -55,6 +57,7 @@ require([
 		enCurrencies,
 		enGregorian,
 		enNumbers,
+		enDateFields,
 		likelySubtags,
 		pluralsData,
 		timeData,
@@ -68,7 +71,7 @@ require([
 	// Use Globalize to format dates.
 	document.getElementById( "date" ).innerHTML = en.formatDate( new Date(), {
 		datetime: "medium"
-	})
+	});
 
 	// Use Globalize to format numbers.
 	number = en.numberFormatter();
@@ -78,7 +81,7 @@ require([
 	document.getElementById( "currency" ).innerHTML = en.formatCurrency( 69900, "USD" );
 
 	// Use Globalize to get the plural form of a numeric value.
-	document.getElementById( "plural-number" ).innerHTML = number( 12345.6789 )
+	document.getElementById( "plural-number" ).innerHTML = number( 12345.6789 );
 	document.getElementById( "plural-form" ).innerHTML = en.plural( 12345.6789 );
 
 	// Use Globalize to format a message with plural inflection.
@@ -91,4 +94,6 @@ require([
 	document.getElementById( "requirements" ).style.display = "none";
 	document.getElementById( "demo" ).style.display = "block";
 
+	document.getElementById( "relative-time").innerText = en.formatRelativeTime( -35, 'second' );
+
 });

examples/node-npm/main.js

@@ -9,6 +9,7 @@ Globalize.load(
 	cldrData( "main/en/currencies" ),
 	cldrData( "main/en/ca-gregorian" ),
 	cldrData( "main/en/numbers" ),
+	cldrData( "main/en/dateFields" ),
 	cldrData( "supplemental/currencyData" ),
 	cldrData( "supplemental/likelySubtags" ),
 	cldrData( "supplemental/plurals" ),
@@ -38,3 +39,5 @@ console.log( like( 0 ) );
 console.log( like( 1 ) );
 console.log( like( 2 ) );
 console.log( like( 3 ) );
+
+console.log( Globalize.formatRelativeTime( -35, "second" ) );

examples/plain-javascript/index.html

@@ -28,6 +28,7 @@ <h2>Demo output</h2>
             <li><span id="message-2"></span></li>
             <li><span id="message-3"></span></li>
         </ul>
+        <p>Something happened: <span id="relative-time"></span></p>
     </div>
 
     <!--
@@ -52,6 +53,9 @@ <h2>Demo output</h2>
     <script src="../../dist/globalize/date.js"></script>
     <script src="../../dist/globalize/currency.js"></script>
 
+    <!-- Load after globalize/number.js and globalize/plural.js-->
+    <script src="../../dist/globalize/relative-time.js"></script>
+
     <script>
 
     // At this point, we have Globalize loaded. But, before we can use it, we
@@ -114,6 +118,20 @@ <h2>Demo output</h2>
                   "medium": "{1}, {0}"
                 }
               }
+            },
+            "fields": {
+              "second": {
+                "displayName": "Second",
+                "relative-type-0": "now",
+                "relativeTime-type-future": {
+                  "relativeTimePattern-count-one": "in {0} second",
+                  "relativeTimePattern-count-other": "in {0} seconds"
+                },
+                "relativeTime-type-past": {
+                  "relativeTimePattern-count-one": "{0} second ago",
+                  "relativeTimePattern-count-other": "{0} seconds ago"
+                }
+              }
             }
           },
           "numbers": {
@@ -211,7 +229,7 @@ <h2>Demo output</h2>
     document.getElementById( "currency" ).innerHTML = en.formatCurrency( 69900, "USD" );
 
     // Use Globalize to get the plural form of a numeric value.
-    document.getElementById( "plural-number" ).innerHTML = number( 12345.6789 )
+    document.getElementById( "plural-number" ).innerHTML = number( 12345.6789 );
     document.getElementById( "plural-form" ).innerHTML = en.plural( 12345.6789 );
 
     // Use Globalize to format a message with plural inflection.
@@ -224,6 +242,8 @@ <h2>Demo output</h2>
     document.getElementById( "requirements" ).style.display = "none";
     document.getElementById( "demo" ).style.display = "block";
 
+    document.getElementById( "relative-time").innerText = en.formatRelativeTime( -35, 'second' );
+
     </script>
 
 </body>

src/build/intro-relative-time.js

@@ -0,0 +1,45 @@
+/**
+ * Globalize v@VERSION
+ *
+ * http://github.com/jquery/globalize
+ *
+ * Copyright 2010, 2014 jQuery Foundation, Inc. and other contributors
+ * Released under the MIT license
+ * http://jquery.org/license
+ *
+ * Date: @DATE
+ */
+/*!
+ * Globalize v@VERSION @DATE Released under the MIT license
+ * http://git.io/TrdQbw
+ */
+(function( root, factory ) {
+
+	// UMD returnExports
+	if ( typeof define === "function" && define.amd ) {
+
+		// AMD
+		define([
+			"cldr",
+			"../globalize",
+			"./number",
+			"./plural",
+			"cldr/event",
+			"cldr/supplemental"
+		], factory );
+	} else if ( typeof exports === "object" ) {
+
+		// Node, CommonJS
+		module.exports = factory( require( "cldrjs" ), require( "globalize" ) );
+	} else {
+
+		// Extend global
+		factory( root.Cldr, root.Globalize );
+	}
+}(this, function( Cldr, Globalize ) {
+
+var formatMessage = Globalize._formatMessage,
+	validateCldr = Globalize._validateCldr,
+	validateParameterPresence = Globalize._validateParameterPresence,
+	validateParameterTypeString = Globalize._validateParameterTypeString,
+	validateParameterTypeNumber = Globalize._validateParameterTypeNumber;

src/build/node-main.js

@@ -21,3 +21,6 @@ require( "./globalize/plural" );
 // Load after globalize/number
 require( "./globalize/currency" );
 require( "./globalize/date" );
+
+// Load after globalize/number and globalize/plural
+require( "./globalize/relative-time" );