Cache support

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

@@ -136,15 +136,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
 
@@ -248,11 +248,84 @@ functionalities, etc.
 
 An example is worth a thousand words. Check out our Hello World demo (available
 to you in different flavors):
-- [Hello World (AMD + bower)](examples/amd-bower/).
-- [Hello World (Node.js + npm)](examples/node-npm/).
-- [Hello World (plain JavaScript)](examples/plain-javascript/).
+- [Hello World (AMD + bower)](examples/hello-world-amd-bower/).
+- [Hello World (Node.js + npm)](examples/hello-world-node-npm/).
+- [Hello World (plain JavaScript)](examples/hello-world-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
+considerably more time (more expensive) than execution. The difference is an
+order of magnitude. 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
+
+You really should 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).
+
+To illustrate, a Globalize application looks like:
+
+```html
+<script src="cldrjs/cldr.js"></script>
+<script src="cldrjs/cldr/...js"></script>
+<script src="globalize.js"></script>
+<script src="globalize/number.js"></script>
+<script src="globalize/...js"></script>
+<script>
+// Feed Globalize on CLDR data and on translation messages.
+Globalize.load({
+  ... CLDR data ...
+});
+
+// Then, use Globalize formatters and parsers.
+</script>
+```
+
+A precompiled Globalize application using the runtime modules looks like:
+
+```html
+<script src="globalize-runtime.js"></script>
+<script src="globalize-runtime/number.js"></script>
+<script src="globalize-runtime/...js"></script>
+<script src="my-compiled-formatters-and-parsers.js"></script>
+<script>
+// Use Globalize formatters and parsers.
+</script>
+```
+
+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).
+
+See our [Basic Globalize Compiler example](examples/basic-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/basic-globalize-compiler/README.md

@@ -0,0 +1,26 @@
+# Basic Globalize Compiler example
+
+On this example, we assume you know the Globalize usage basics. So, it focuses on
+the Globalize Compiler and on the Globalize runtime modules.
+
+## Running the example
+
+### Development mode
+
+1. Point your browser at `./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.
+
+### Production mode
+
+1. Install `globalize-compiler` by running `npm install`.
+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](https://github.com/jquery-support/globalize-compiler#README).
+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.
+

examples/basic-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";