Runtime support (smaller and quicker code for production)

Gruntfile.js

@@ -133,7 +133,8 @@ module.exports = function( grunt ) {
 				//    Only for root id's (the ones in src, not in src's subpaths). Note there's no
 				//    conditional code checking for this type.
 				onBuildWrite: function( id, path, contents ) {
-					var name = camelCase( id.replace( /util\/|common\//, "" ) );
+					var messageformat,
+						name = camelCase( id.replace( /util\/|common\//, "" ) );
 
 					// MakePlural
 					if ( ( /make-plural/ ).test( id ) ) {
@@ -207,7 +208,7 @@ module.exports = function( grunt ) {
 							.replace( /module\.exports = \(function\(\) {([\s\S]*?)\n}\)\(\);/, [
 								"MessageFormat._parse = (function() {",
 								"$1",
-								"})().parse;"
+								"}()).parse;"
 							].join( "\n" ) )
 
 							// Remove unused code.
@@ -228,6 +229,20 @@ module.exports = function( grunt ) {
 								"}());",
 								"/* jshint ignore:end */"
 							].join( "\n" ) );
+
+					// message-runtime
+					} else if ( ( /message-runtime/ ).test( id ) ) {
+						messageformat = require( "./external/messageformat/messageformat" );
+						delete messageformat.prototype.runtime.fmt;
+						delete messageformat.prototype.runtime.pluralFuncs;
+						contents = contents.replace( "Globalize._messageFormat = {};", [
+							"/* jshint ignore:start */",
+							"Globalize._messageFormat = (function() {",
+							messageformat.prototype.runtime.toString(),
+							"return {number: number, plural: plural, select: select};",
+							"}());",
+							"/* jshint ignore:end */"
+						].join( "\n" ) );
 					}
 
 					// 1, and 2: Remove define() wrap.
@@ -361,6 +376,103 @@ module.exports = function( grunt ) {
 									endFile: "src/build/outro.js"
 								}
 							}
+						},
+						{
+							name: "globalize-runtime",
+							include: [ "core-runtime" ],
+							create: true,
+							override: {
+								wrap: {
+									startFile: "src/build/intro-core-runtime.js",
+									endFile: "src/build/outro.js"
+								}
+							}
+						},
+						{
+							name: "globalize.currency-runtime",
+							include: [ "currency-runtime" ],
+							exclude: [
+								"./core-runtime",
+								"./number-runtime"
+							],
+							create: true,
+							override: {
+								wrap: {
+									startFile: "src/build/intro-currency-runtime.js",
+									endFile: "src/build/outro.js"
+								}
+							}
+						},
+						{
+							name: "globalize.date-runtime",
+							include: [ "date-runtime" ],
+							exclude: [
+								"./core-runtime",
+								"./number-runtime"
+							],
+							create: true,
+							override: {
+								wrap: {
+									startFile: "src/build/intro-date-runtime.js",
+									endFile: "src/build/outro.js"
+								}
+							}
+						},
+						{
+							name: "globalize.message-runtime",
+							include: [ "message-runtime" ],
+							exclude: [ "./core-runtime" ],
+							create: true,
+							override: {
+								wrap: {
+									startFile: "src/build/intro-message-runtime.js",
+									endFile: "src/build/outro.js"
+								}
+							}
+						},
+						{
+							name: "globalize.number-runtime",
+							include: [ "number-runtime" ],
+							exclude: [
+								"./core-runtime"
+							],
+							create: true,
+							override: {
+								wrap: {
+									startFile: "src/build/intro-number-runtime.js",
+									endFile: "src/build/outro.js"
+								}
+							}
+						},
+						{
+							name: "globalize.plural-runtime",
+							include: [ "plural-runtime" ],
+							exclude: [
+								"./core-runtime"
+							],
+							create: true,
+							override: {
+								wrap: {
+									startFile: "src/build/intro-plural-runtime.js",
+									endFile: "src/build/outro.js"
+								}
+							}
+						},
+						{
+							name: "globalize.relative-time-runtime",
+							include: [ "relative-time-runtime" ],
+							exclude: [
+								"./core-runtime",
+								"./number-runtime",
+								"./plural-runtime"
+							],
+							create: true,
+							override: {
+								wrap: {
+									startFile: "src/build/intro-relative-time-runtime.js",
+									endFile: "src/build/outro.js"
+								}
+							}
 						}
 					]
 				}
@@ -381,21 +493,30 @@ module.exports = function( grunt ) {
 					return replaceConsts( content );
 				}
 			},
-			core: {
+			coreAndRuntime: {
 				expand: true,
 				cwd: "dist/.build/",
-				src: [ "globalize.js" ],
+				src: [ "globalize.js", "globalize-runtime.js" ],
 				dest: "dist/"
 			},
 			modules: {
 				expand: true,
 				cwd: "dist/.build/",
-				src: [ "globalize*.js", "!globalize.js" ],
+				src: [ "globalize*.js", "!globalize.js", "!*runtime*.js" ],
 				dest: "dist/globalize",
 				rename: function( dest, src ) {
 					return require( "path" ).join( dest, src.replace( /globalize\./, "" ) );
 				}
 			},
+			runtimeModules: {
+				expand: true,
+				cwd: "dist/.build/",
+				src: [ "globalize.*runtime.js" ],
+				dest: "dist/globalize-runtime",
+				rename: function( dest, src ) {
+					return require( "path" ).join( dest, src.replace( /(globalize\.|-runtime)/g, "" ) );
+				}
+			},
 			allInOneNode: {
 				src: "src/build/node-main.js",
 				dest: "dist/node-main.js"
@@ -413,7 +534,19 @@ module.exports = function( grunt ) {
 					"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/relative-time.min.js": [ "dist/globalize/relative-time.js" ]
+					"tmp/globalize/relative-time.min.js": [ "dist/globalize/relative-time.js" ],
+
+					"tmp/globalize-runtime.min.js": [ "dist/globalize-runtime.js" ],
+					"tmp/globalize-runtime/currency.min.js": [
+						"dist/globalize-runtime/currency.js"
+					],
+					"tmp/globalize-runtime/date.min.js": [ "dist/globalize-runtime/date.js" ],
+					"tmp/globalize-runtime/message.min.js": [ "dist/globalize-runtime/message.js" ],
+					"tmp/globalize-runtime/number.min.js": [ "dist/globalize-runtime/number.js" ],
+					"tmp/globalize-runtime/plural.min.js": [ "dist/globalize-runtime/plural.js" ],
+					"tmp/globalize-runtime/relative-time.min.js": [
+						"dist/globalize-runtime/relative-time.js"
+					]
 				}
 			}
 		},
@@ -422,7 +555,9 @@ module.exports = function( grunt ) {
 		"compare_size": {
 			files: [
 				"tmp/globalize.min.js",
-				"tmp/globalize/*min.js"
+				"tmp/globalize/*min.js",
+				"tmp/globalize-runtime.min.js",
+				"tmp/globalize-runtime/*min.js"
 			],
 			options: {
 				compress: {

README.md

@@ -20,6 +20,8 @@ Node.js module.
   - [Requirements](#requirements)
   - [Installation](#installation)
   - [Usage](#usage)
+  - [Performance](#performance)
+  - [Compilation and the Runtime modules](#compilation-and-the-runtime-modules)
 - [API](#api)
   - [Core](#core-module)
   - [Date module](#date-module)
@@ -136,15 +138,15 @@ information on its usage.
 
 ### Pick the modules you need
 
-| File | Minified + gzipped size | Summary |
-|---|--:|---|
-| globalize.js | 1.3KB | [Core library](#core-module) |
-| globalize/currency.js | +2.6KB | [Currency module](#currency-module) provides currency formatting and parsing |
-| globalize/date.js | +4.9KB | [Date module](#date-module) provides date formatting and parsing |
-| globalize/message.js | +5.4KB | [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 |
+| File | Minified + gzipped size | Runtime minified + gzipped size | Summary |
+|---|--:|--:|---|
+| globalize.js | 1.5KB | 1.0KB | [Core library](#core-module) |
+| globalize/currency.js | 2.6KB | 0.6KB | [Currency module](#currency-module) provides currency formatting and parsing |
+| globalize/date.js | 5.1KB | 3.8KB | [Date module](#date-module) provides date formatting and parsing |
+| globalize/message.js | 5.4KB | 0.7KB | [Message module](#message-module) provides ICU message format support |
+| globalize/number.js | 3.1KB | 1.8KB | [Number module](#number-module) provides number formatting and parsing |
+| globalize/plural.js | 2.3KB | 0.4KB | [Plural module](#plural-module) provides pluralization support |
+| globalize/relative-time.js | 0.8KB | 0.6KB | [Relative time module](#relative-time-module) provides relative time formatting support |
 
 ### Browser Support
 
@@ -253,6 +255,50 @@ to you in different flavors):
 - [Hello World (plain JavaScript)](examples/plain-javascript/).
 
 
+### Performance
+
+When formatting or parsing, there's actually a two-step process: (a) the
+formatter (or parser) *creation* and (b) its *execution*, where creation takes
+an order of magnitude more time (more expensive) than execution. In the creation
+phase, Globalize traverses the CLDR tree, processes data (e.g., expands date
+patterns, parses plural rules, etc), and returns a function that actually
+executes the formatting or parsing.
+
+```js
+// Formatter creation.
+var formatter = Globalize.numberFormatter();
+
+// Formatter execution (roughly 10x faster than above).
+formatter( Math.PI );
+// > 3.141
+```
+
+As a rule of thumb for optimal performance, cache your formatters and parsers.
+For example: (a) on iterations, generate them outside the loop and reuse while
+looping; (b) on server applications, generate them in advance and execute when
+requests arrive.
+
+### Compilation and the Runtime modules
+
+Take advantage of compiling your formatters and/or parsers during build time
+when deploying to production. It's much faster than generating them in real-time
+and it's also much smaller (i.e., better loading performance).
+
+Your compiled formatters and parsers allow you to skip a big part of the library
+and also allow you to skip loading CLDR data, because they have already been
+created (see [Performance](#performance) above for more information).
+
+To illustrate, see our [Basic Globalize Compiler example][].
+
+[Basic Globalize Compiler example]: examples/globalize-compiler/
+
+#### Globalize Compiler
+
+For information about the Globalize Compiler CLI or its JavaScript API, see the
+[Globalize Compiler documentation][].
+
+[Globalize Compiler documentation]: https://github.com/jquery-support/globalize-compiler#README
+
 ## API
 
 ### Core module

examples/amd-bower/package.json

@@ -1,5 +1,6 @@
 {
   "name": "globalize-hello-world-amd-bower",
+  "private": true,
   "comment": [
     "You don't need this file. The only reasone this example does have a",
     "package.json is to fool npm, so cldr-data-downloader doesn't get",

examples/globalize-compiler/.gitignore

@@ -0,0 +1 @@
+compiled-formatters.js

examples/globalize-compiler/README.md

@@ -0,0 +1,45 @@
+# Basic Globalize Compiler example
+
+This example focuses on the Globalize Compiler and the Globalize runtime
+modules. It assumes knowledge of Globalize usage basics.
+
+## Requirements
+
+**1. Install Globalize dependencies and Globalize Compiler**
+
+This example uses `npm` to download Globalize dependencies (i.e., CLDR data and
+the Cldrjs library) and the [Globalize Compiler][].
+
+```
+npm install
+```
+
+[Globalize Compiler]: https://github.com/jquery-support/globalize-compiler
+
+## Running the example
+
+### Development mode
+
+1. Start a server by running `python -m SimpleHTTPServer` or other alternative
+servers such as [http-server][], [nginx][], [apache][].
+1. Point your browser at `http://localhost:8000/development.html`. Note that the
+formatters are created dynamically. Therefore, Cldrjs and CLDR data are
+required.
+1. Understand the demo by reading the source code. We have comments there for
+you.
+
+[http-server]: https://github.com/nodeapps/http-server
+[nginx]: http://nginx.org/en/docs/
+[apache]: http://httpd.apache.org/docs/trunk/
+
+### Production mode
+
+1. Compile the application formatters by running `npm run build`. See
+`package.json` to understand the actual shell command that is used. For more
+information about the compiler, see the [Globalize Compiler documentation][].
+1. Point your browser at `./production.html`. Note that we don't need Cldrjs nor
+CLDR data in production here.
+1. Understand the demo by reading the source code. We have comments there for
+you.
+
+[Globalize Compiler documentation]: https://github.com/jquery-support/globalize-compiler#README

examples/globalize-compiler/app.js

@@ -0,0 +1,33 @@
+var like, number;
+
+// Set default locale as "en".
+Globalize.locale( "en" );
+
+// Use Globalize to format dates.
+document.getElementById( "date" ).innerHTML = Globalize.formatDate( new Date(), {
+	datetime: "medium"
+});
+
+// Use Globalize to format numbers.
+number = Globalize.numberFormatter();
+document.getElementById( "number" ).innerHTML = number( 12345.6789 );
+
+// Use Globalize to format currencies.
+document.getElementById( "currency" ).innerHTML = Globalize.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-form" ).innerHTML = Globalize.plural( 12345.6789 );
+
+// Use Globalize to format a message with plural inflection.
+like = Globalize.messageFormatter( "like" );
+document.getElementById( "message-0" ).innerHTML = like( 0 );
+document.getElementById( "message-1" ).innerHTML = like( 1 );
+document.getElementById( "message-2" ).innerHTML = like( 2 );
+document.getElementById( "message-3" ).innerHTML = like( 3 );
+
+// Use Globalize to format a relative time.
+document.getElementById( "relative-time" ).innerText = Globalize.formatRelativeTime( -35, "second" );
+
+document.getElementById( "requirements" ).style.display = "none";
+document.getElementById( "demo" ).style.display = "block";