CHANGELOG.md

@@ -3,6 +3,50 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [4.0.0] / 16 January 2020
+
+Majority of using projects don't have to worry by this being a new major version.
+
+**TLDR;** if your project manipulates `Writer.prototype.parse | Writer.cache` directly or uses `.to_html()`, you probably have to change that code.
+
+This release allows the internal template cache to be customised, either by disabling it completely
+or provide a custom strategy deciding how the cache should behave when mustache.js parses templates.
+
+```js
+const mustache = require('mustache');
+
+// disable caching
+Mustache.templateCache = undefined;
+
+// or use a built-in Map in modern environments
+Mustache.templateCache = new Map();
+```
+
+Projects that wanted to customise the caching behaviour in earlier versions of mustache.js were forced to
+override internal method responsible for parsing templates; `Writer.prototype.parse`. In short, that was unfortunate
+because there is more than caching happening in that method.
+
+We've improved that now by introducing a first class API that only affects template caching.
+
+The default template cache behaves as before and is still compatible with older JavaScript environments.
+For those who wants to provide a custom more sopisiticated caching strategy, one can do that with an object that adheres to the following requirements:
+
+```ts
+{
+  set(cacheKey: string, value: string): void
+  get(cacheKey: string): string | undefined
+  clear(): void
+}
+```
+
+### Added
+
+* [#731]: Allow template caching to be customised, by [@AndrewLeedham].
+
+### Removed
+
+* [#735]: Remove `.to_html()`, by [@phillipj].
+
 ## [3.2.1] / 30 December 2019
 
 ### Fixed
@@ -417,6 +461,7 @@ This release is made to revert changes introduced in [2.3.1] that caused unexpec
   * Fixed a bug that clashed with QUnit (thanks [@kannix]).
   * Added volo support (thanks [@guybedford]).
 
+[4.0.0]: https://github.com/janl/mustache.js/compare/v3.2.1...v4.0.0
 [3.2.1]: https://github.com/janl/mustache.js/compare/v3.2.0...v3.2.1
 [3.2.0]: https://github.com/janl/mustache.js/compare/v3.1.0...v3.2.0
 [3.1.0]: https://github.com/janl/mustache.js/compare/v3.0.3...v3.1.0
@@ -488,10 +533,13 @@ This release is made to revert changes introduced in [2.3.1] that caused unexpec
 [#717]: https://github.com/janl/mustache.js/issues/717
 [#728]: https://github.com/janl/mustache.js/issues/728
 [#733]: https://github.com/janl/mustache.js/issues/733
+[#731]: https://github.com/janl/mustache.js/issues/731
+[#735]: https://github.com/janl/mustache.js/issues/735
 
 [@afc163]: https://github.com/afc163
 [@andersk]: https://github.com/andersk
 [@Andersos]: https://github.com/Andersos
+[@AndrewLeedham]: https://github.com/AndrewLeedham
 [@bbrooks]: https://github.com/bbrooks
 [@calvinf]: https://github.com/calvinf
 [@cmbuckley]: https://github.com/cmbuckley

README.md

@@ -4,7 +4,7 @@
 
 [![Build Status](https://travis-ci.org/janl/mustache.js.svg?branch=master)](https://travis-ci.org/janl/mustache.js) [![Gitter chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/janl/mustache.js)
 
-[mustache.js](http://github.com/janl/mustache.js) is an implementation of the [mustache](http://mustache.github.com/) template system in JavaScript.
+[mustache.js](http://github.com/janl/mustache.js) is a zero-dependency implementation of the [mustache](http://mustache.github.com/) template system in JavaScript.
 
 [Mustache](http://mustache.github.com/) is a logic-less template syntax. It can be used for HTML, config files, source code - anything. It works by expanding tags in a template using values provided in a hash or object.
 
@@ -16,7 +16,9 @@ For a language-agnostic overview of mustache's template syntax, see the `mustach
 
 You can use mustache.js to render mustache templates anywhere you can use JavaScript. This includes web browsers, server-side environments such as [Node.js](http://nodejs.org/), and [CouchDB](http://couchdb.apache.org/) views.
 
-mustache.js ships with support for both the [CommonJS](http://www.commonjs.org/) module API and the [Asynchronous Module Definition](https://github.com/amdjs/amdjs-api/wiki/AMD) API (AMD).
+mustache.js ships with support for the [CommonJS](http://www.commonjs.org/) module API, the [Asynchronous Module Definition](https://github.com/amdjs/amdjs-api/wiki/AMD) API (AMD) and [ECMAScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules).
+
+In addition to being a package to be used programmatically, you can use it as a [command line tool](#command-line-tool).
 
 And this will be your templates after you use Mustache:
 
@@ -30,65 +32,6 @@ You can get Mustache via [npm](http://npmjs.com).
 $ npm install mustache --save
 ```
 
-## Command line tool
-
-mustache.js is shipped with a Node.js based command line tool. It might be installed as a global tool on your computer to render a mustache template of some kind
-
-```bash
-$ npm install -g mustache
-
-$ mustache dataView.json myTemplate.mustache > output.html
-```
-
-also supports stdin.
-
-```bash
-$ cat dataView.json | mustache - myTemplate.mustache > output.html
-```
-
-or as a package.json `devDependency` in a build process maybe?
-
-```bash
-$ npm install mustache --save-dev
-```
-
-```json
-{
-  "scripts": {
-    "build": "mustache dataView.json myTemplate.mustache > public/output.html"
-  }
-}
-```
-```bash
-$ npm run build
-```
-
-The command line tool is basically a wrapper around `Mustache.render` so you get all the features.
-
-If your templates use partials you should pass paths to partials using `-p` flag:
-
-```bash
-$ mustache -p path/to/partial1.mustache -p path/to/partial2.mustache dataView.json myTemplate.mustache
-```
-
-## Who uses mustache.js?
-
-An updated list of mustache.js users is kept [on the Github wiki](https://github.com/janl/mustache.js/wiki/Beard-Competition). Add yourself or your company if you use mustache.js!
-
-## Contributing
-
-mustache.js is a mature project, but it continues to actively invite maintainers. You can help out a high-profile project that is used in a lot of places on the web. There is [plenty](https://github.com/janl/mustache.js/issues) of [work](https://github.com/janl/mustache.js/pulls) to do. No big commitment required, if all you do is review a single [Pull Request](https://github.com/janl/mustache.js/pulls), you are a maintainer. And a hero.
-
-### Your First Contribution
-
-- review a [Pull Request](https://github.com/janl/mustache.js/pulls)
-- fix an [Issue](https://github.com/janl/mustache.js/issues)
-- update the [documentation](https://github.com/janl/mustache.js#usage)
-- make a website
-- write a tutorial
-
-* * *
-
 ## Usage
 
 Below is a quick example how to use mustache.js:
@@ -106,29 +49,6 @@ var output = Mustache.render("{{title}} spends {{calc}}", view);
 
 In this example, the `Mustache.render` function takes two parameters: 1) the [mustache](http://mustache.github.com/) template and 2) a `view` object that contains the data and code needed to render the template.
 
-## API
-
-Following is an [rtype](https://git.io/rtype) signature of the most commonly used functions.
-
-```js
-Mustache.render(
-  template            : String,
-  view                : Object,
-  partials?           : Object,
-  tags = ['{{', '}}'] : Tags,
-) => String
-
-Mustache.parse(
-  template              : String,
-  tags = ['{{', '}}']   : Tags,
-) => Token[]
-
-interface Token [String, String, Number, Number, Token[]?, Number?]
-
-interface Tags [String, String]
-
-```
-
 ## Templates
 
 A [mustache](http://mustache.github.com/) template is a string that contains any number of mustache tags. Tags are indicated by the double mustaches that surround them. `{{person}}` is a tag, as is `{{#person}}`. In both examples we refer to `person` as the tag's key. There are several types of tags available in mustache.js, described below.
@@ -137,39 +57,44 @@ There are several techniques that can be used to load templates and hand them to
 
 #### Include Templates
 
-If you need a template for a dynamic part in a static website, you can consider including the template in the static HTML file to avoid loading templates separately. Here's a small example using `jQuery`:
+If you need a template for a dynamic part in a static website, you can consider including the template in the static HTML file to avoid loading templates separately. Here's a small example:
+
+```js
+// file: render.js
+
+function renderHello() {
+  var template = document.getElementById('template').innerHTML;
+  var rendered = Mustache.render(template, { name: 'Luke' });
+  document.getElementById('target').innerHTML = rendered;
+}
+```
 
 ```html
-<!DOCTYPE HTML>
 <html>
-<body onload="loadUser()">
-<div id="target">Loading...</div>
-<script id="template" type="x-tmpl-mustache">
-Hello {{ name }}!
-</script>
-</body>
+  <body onload="renderHello()">
+    <div id="target">Loading...</div>
+    <script id="template" type="x-tmpl-mustache">
+      Hello {{ name }}!
+    </script>
+
+    <script src="https://unpkg.com/mustache@latest"></script>
+    <script src="render.js"></script>
+  </body>
 </html>
 ```
 
-```js
-function loadUser() {
-  var template = $('#template').html();
-  Mustache.parse(template);   // optional, speeds up future uses
-  var rendered = Mustache.render(template, {name: "Luke"});
-  $('#target').html(rendered);
-}
-```
-
 #### Load External Templates
 
-If your templates reside in individual files, you can load them asynchronously and render them when they arrive. Another example using `jQuery`:
+If your templates reside in individual files, you can load them asynchronously and render them when they arrive. Another example using [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch):
 
 ```js
-function loadUser() {
-  $.get('template.mst', function(template) {
-    var rendered = Mustache.render(template, {name: "Luke"});
-    $('#target').html(rendered);
-  });
+function renderHello() {
+  fetch('template.mustache')
+    .then((response) => response.text())
+    .then((template) => {
+      var rendered = Mustache.render(template, { name: 'Luke' });
+      document.getElementById('target').innerHTML = rendered;    
+    });
 }
 ```
 
@@ -548,6 +473,47 @@ Mustache.parse(template);
 Mustache.render(template, view);
 ```
 
+## Command line tool
+
+mustache.js is shipped with a Node.js based command line tool. It might be installed as a global tool on your computer to render a mustache template of some kind
+
+```bash
+$ npm install -g mustache
+
+$ mustache dataView.json myTemplate.mustache > output.html
+```
+
+also supports stdin.
+
+```bash
+$ cat dataView.json | mustache - myTemplate.mustache > output.html
+```
+
+or as a package.json `devDependency` in a build process maybe?
+
+```bash
+$ npm install mustache --save-dev
+```
+
+```json
+{
+  "scripts": {
+    "build": "mustache dataView.json myTemplate.mustache > public/output.html"
+  }
+}
+```
+```bash
+$ npm run build
+```
+
+The command line tool is basically a wrapper around `Mustache.render` so you get all the features.
+
+If your templates use partials you should pass paths to partials using `-p` flag:
+
+```bash
+$ mustache -p path/to/partial1.mustache -p path/to/partial2.mustache dataView.json myTemplate.mustache
+```
+
 ## Plugins for JavaScript Libraries
 
 mustache.js may be built specifically for several different client libraries, including the following:
@@ -566,6 +532,12 @@ $ rake dojo
 $ rake yui3
 $ rake qooxdoo
 ```
+
+## TypeScript
+
+Since the source code of this package is written in JavaScript, we follow the [TypeScript publishing docs](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) preferred approach
+by having type definitions available via [@types/mustache](https://www.npmjs.com/package/@types/mustache).
+
 ## Testing
 
 In order to run the tests you'll need to install [Node.js](http://nodejs.org/).
@@ -597,6 +569,7 @@ Then, you can run the test with:
 ```bash
 $ TEST=mytest npm run test-render
 ```
+
 ### Browser tests
 
 Browser tests are not included in `npm test` as they run for too long, although they are ran automatically on Travis when merged into master. Run browser tests locally in any browser:
@@ -605,14 +578,22 @@ $ npm run test-browser-local
 ```
 then point your browser to `http://localhost:8080/__zuul`
 
-### Troubleshooting
+## Who uses mustache.js?
 
-#### npm install fails
+An updated list of mustache.js users is kept [on the Github wiki](https://github.com/janl/mustache.js/wiki/Beard-Competition). Add yourself or your company if you use mustache.js!
+
+## Contributing
+
+mustache.js is a mature project, but it continues to actively invite maintainers. You can help out a high-profile project that is used in a lot of places on the web. No big commitment required, if all you do is review a single [Pull Request](https://github.com/janl/mustache.js/pulls), you are a maintainer. And a hero.
+
+### Your First Contribution
+
+- review a [Pull Request](https://github.com/janl/mustache.js/pulls)
+- fix an [Issue](https://github.com/janl/mustache.js/issues)
+- update the [documentation](https://github.com/janl/mustache.js#usage)
+- make a website
+- write a tutorial
 
-Ensure to have a recent version of npm installed. While developing this project requires npm with support for `^` version ranges.
-```bash
-$ npm install -g npm
-```
 ## Thanks
 
 mustache.js wouldn't kick ass if it weren't for these fine souls: