Overview

Narrative JavaScript is a small extension to the JavaScript language that enables blocking capabilities for asynchronous operations. This makes writing asynchronous code sequences easier and increases code readability.

Narrative JavaScript invents a "yielding" operator (notated as '->') that allows you to write asynchronous code in a single, linear code block. For example, with Narrative JavaScript fetching a document using XmlHttp goes from looking like this:

    function handleResponse(responseText) {
        document.getElementById("myElem").innerHTML = responseText;
    }
    fetch("http://www.url.com/", handleResponse);
	
to this:
    document.getElementById("myElem").innerHTML = fetch->("http://www.url.com/");
	
And an animation sequence goes from looking like this:
    var left = 0;
    function onTimer() {
        left += 10;
        if (left <= 300) {
            document.getElementById("myElem").style.left = left;
            setTimeout(onTimer, 30);
        }   
    }
    onTimer();
	
to this:
    for (var left = 0; left <= 300; left += 10) {
        left += 10;
        document.getElementById("myElem").style.left = left;        
        sleep->(30);
    }
	
Any operation that requires a callback function is a candidate for blocking.

Keep in mind that blocking does not mean that the entire JavaScript runtime locks up waiting for an operation to finish. Instead, Narrative JavaScript makes use of co-operative multitasking. When you use the blocking operator, you are yielding control to the JavaScript runtime to execute other operations until your operation provides a return value.

More details about writing Narrative JavaScript can be found in the coding section of the documentation.