Consistent rendering API

[mlrawlings]

Everything returns an out

Currently, template.render() returns out and template.renderSync() returns the html string.

We will change renderSync to also return out. This will be a breaking change, but we will implement out.toString() and out.toJSON() so in many cases the out can be used as a string.

typeof out === 'string' returns false and you can't use the String.prototype methods on out, but you will be able to pass the contents to fs.writeFile, res.send, JSON.stringify, etc. and it still works as if it were a string (in many cases).

DOM helpers
Marko Widgets (which has now been merged into this repo) had implemented it's own renderer using which returned a RenderResult: a lightweight wrapper around out than implemented helper methods like .appendTo() and others.

Widgets will no longer have a special render. They will return out just like templates, but we have added these DOM helpers to all instances of out, so you can use these for templates as well as widgets.

Sync Errors
For when rendering using renderSync, we already throw an Error if anything tries to beginAsync. However we don't do the same on the other side: if you call template.render({}).appendTo() and the template has not finished rendering yet, the call to appendTo() should throw.

Events, Promises, Streams, & Callbacks
Async templates will be handled by template.render({}).on(‘finish’), template.render({}).then(), template.render({}, stream), or template.render({}, callback) all of which are passed the out instance.

[mlrawlings]

@patrick-steele-idem What are your thoughts on making and publishing a quick change to v3 that moves the logic from renderSync() to renderToString() and when renderSync() is called, it would log a warning that the method will be changing in v4 before delegating to renderToString().

Then in v4, we can keep renderToString() which would just be:

renderToString(data) {
    return this.renderSync().toString();
}

Is this worthwhile?

[patrick-steele-idem]

I think that would be worthwhile change @mlrawlings. I think it would be good to confidently say that "If you didn't see any deprecation warnings in v3 then you can safely upgrade to Marko v4".