Balisage Paper: Asynchronous XSLT

Promises

A Promise is introduced into the XDM data model as a new kind of item. The ItemType syntax is extended to allow promise(X), where X is any sequence type: for example, promise(document-node()) is a promise which, when successfully fulfilled, will deliver a document node. The type promise(*) is equivalent to promise(item()*), that is, a promise that may deliver a value of any type.

In [Wright 2016], a Promise is modelled as a kind of function; in [Lockett & Retter 2019], a promise is modelled as a kind of map. I have made it a primitive item type because I don't want promises to be substitutable for anything else: I want to exploit the type checking machinery to ensure that promises can only be used in a well-defined and restricted set of circumstances.

A promise can be delivered as the result of a number of new asynchronous functions, described in the next section.

A promise can be handled by any operation that is applicable to arbitrary items: for example the comma operator can be used to construct a sequence of promises, and the head() function can be used to select the first promise in such a sequence. You can test whether an item is a promise using the instance of operator, and you can construct a map or array of promises if you find it useful.

A promise has no string value, it cannot be atomized or serialized, it has no effective boolean value, and it cannot be added to the content of a node. There is no equality operator for comparing promises; there are no match patterns that match a promise, and the built-in template rules when applied to a promise throw an error.

Nested promises are collapsed into a single promise: that is, a promise of a promise of X is treated as a promise of X. For orthogonality, however, the type syntax promise(promise(X)) is allowed.

There are a number of standard functions that apply to promises: these are in a namespace (provisionally http://expath.org/ns/promise), represented here by the prefix a: (for "asynchronous"). These functions include:

Asynchronous Functions

A number of asynchronous functions are added to the core function library. These are characterised by the fact that the function returns a promise as its result.

This function library includes asynchronous versions of all the core functions that fetch external resources: a:doc, a:document, a:doc-available, a:unparsed-text, a:unparsed-text-lines, a:unparsed-text-available, a:json-doc, a:collection, a:uri-collection. In each case the arguments and the semantics are the same as the existing function; the only difference is that the returned value is a promise.

Similarly, asynchronous versions of extension functions such as those in the EXPath File module [EXPath-File] and EXPath HTTP module [EXPath-HTTP] are made available, typically in another namespace.

A function a:sleep($duration, $value) is supplied, which completes after a specified time has elapsed, returning $value when it does so.

The function a:promise($value) delivers a trivial promise that completes immediately, returning $value. This is useful in a conditional when one branch is synchronous and another asynchronous. If the argument is a call on the fn:error function then the returned promise fails immediately.

User-supplied asynchronous functions may be written simply by declaring the return type as promise(X) (and actually delivering a promise as the result, of course).

Asynchronous Variables

As discussed above, in some environments it is possible to wait for a promise to be fulfilled using the function a:await, but this doesn't work in the Javascript environment.

In the Javascript environment, we will provide only one way to capture and manipulate the result of an asynchronous function (other than in deferred callback code): namely to use an asynchronous variable. For example:

<xsl:variable name="data" as="document-node()" 
      select="a:doc('data.xml')" async="yes"/>

Asynchronous variables may be either global or local. In either case, the select expression is expected to return a promise, and the value of the variable is the value delivered on successful fulfilment of this promise. (If the select expression delivers something other than a promise, then its value can be used directly; the async attribute then has no effect.) An asychronous variable therefore behaves very like an "await" instruction in Javascript.

Example 1: Displaying Data on Demand

The demonstration applications for Saxon-JS include a client-side example [cities.xsl] that loads data on demand from JSON files on demand, and updates the HTML page with a rendition of the selected data.

The critical logic of this application is shown below.

First, there is a template rule to process the event that occurs when a user selects the data to be displayed:

    <xsl:template match="span[@class='link']" mode="ixsl:onclick">
        <xsl:call-template name="loadJSON">
            <xsl:with-param name="X" select="string(@id)"/>
        </xsl:call-template>
    </xsl:template>               
                

This invokes the template:

    <xsl:template name="loadJSON">
        <xsl:param name="X" select="'A'"/>
        <ixsl:schedule-action document="{$baseURL || $X || '.json'}">
            <xsl:call-template name="show-all">
                <xsl:with-param name="X" select="$X"/>
            </xsl:call-template>
        </ixsl:schedule-action>
    </xsl:template>             
                

which triggers asynchronous loading of the selected document, calling another template which updates the HTML page (in situ) to show the results:

    <xsl:template name="show-all">
        <xsl:param name="X"/>
        <xsl:result-document href="#title" method="ixsl:replace-content">
            A List of Cities Beginning With {$X}
        </xsl:result-document>
        <xsl:result-document href="#target" method="ixsl:replace-content">
            <table id="cities-table">
                <thead>
                    <tr>
                        <th>City</th>
                        <th>Country</th>
                        <th data-type="number">Longitude</th>
                        <th data-type="number">Latitude</th>
                    </tr>
                </thead>
                <tbody>
                    <xsl:for-each select="json-doc($baseURL || $X ||'.json')?*">
                        <tr>
                            <td>{?name}</td>
                            <td>{?country}</td>
                            <td>{?coord?lon}</td>
                            <td>{?coord?lat}</td>
                        </tr>
                    </xsl:for-each>
                </tbody>
            </table>
        </xsl:result-document>
    </xsl:template>               
              
                

With the new constructs proposed in this paper, we can rewrite the last two templates as follows:

    <xsl:template name="loadJSON">
        <xsl:param name="X" select="'A'"/>
        <xsl:variable name="json" select="a:json-doc($baseURL||$X||'.json')" async="yes"/>

        <xsl:result-document href="#title" method="ixsl:replace-content">
            A List of Cities Beginning With {$X}
        </xsl:result-document>
        
        <xsl:result-document href="#target" method="ixsl:replace-content">
            <table id="cities-table">
                <thead>
                    <tr>
                        <th>City</th>
                        <th>Country</th>
                        <th data-type="number">Longitude</th>
                        <th data-type="number">Latitude</th>
                    </tr>
                </thead>
                <tbody>
                    <xsl:for-each select="$json?*">
                        <tr>
                            <td>{?name}</td>
                            <td>{?country}</td>
                            <td>{?coord?lon}</td>
                            <td>{?coord?lat}</td>
                        </tr>
                    </xsl:for-each>
                </tbody>
            </table>
        </xsl:result-document>
    </xsl:template>
                

Things to note:

This example also makes an asynchronous call to json:doc right at the start of the transformation:

    <xsl:template name="main">
        <xsl:result-document href="#index" method="ixsl:replace-content">
            ....
        </xsl:result-document>
        
        <xsl:call-template name="loadJSON"/>
    </xsl:template>

(where loadJSON is shown above). This is a case where an asynchronous global variable could be usefully employed. It would require a little restructuring of the code, but would simplify the logic for cases like this where the initial resources to be fetched can be determined without reference to the source document.

Example 2: Animation

Also in the sample applications for Saxon-JS, the knight's tour [tour.xsl] demonstrates timer-based animation.

The existing logic for this is:

    <xsl:template name="next-move">

        <!-- This function takes the board in a given state, decides on the next move to make,
         and then calls itself recursively to make further moves, until the knight has completed
         his tour of the board. It returns the board in its final state. -->

        <xsl:param name="move" as="xs:integer"/>
        <xsl:param name="board" as="array(array(xs:integer))"/>
        <xsl:param name="square" as="map(xs:string, xs:integer)"/>

        <!-- determine the possible squares that the knight can move to -->

        <xsl:variable name="possible-destinations" as="map(xs:string, xs:integer)*"
            select="tour:list-possible-destinations($board, $square)"/>

        <!-- try these moves in turn until one is found that works -->
        
        <xsl:choose>

            <xsl:when test="empty($possible-destinations)">
                <xsl:message>Failed! - the knight is stuck</xsl:message>
            </xsl:when>

            <xsl:when test="ixsl:page()//*:button[@id='stop']/@data-stopped = ('stopped', 'reset')">
                <!--<xsl:message>Stopped/reset at user request</xsl:message>-->
            </xsl:when>

            <xsl:otherwise>

                <xsl:variable name="best-square" as="map(xs:string, xs:integer)"
                    select="tour:find-best-square($board, $possible-destinations, 9, ())"/>

                <!-- update the board to make the move chosen as the best one -->

                <!--<xsl:message>Moving to square <xsl:value-of select="$best-square"/></xsl:message>-->

                <xsl:variable name="next-board" as="array(array(xs:integer))"
                    select="tour:place-knight($move, $board, $best-square)"/>

                <!-- output the board in its new state -->

                <xsl:call-template name="print-board">
                    <xsl:with-param name="board" select="$next-board"/>
                </xsl:call-template>

                <!-- schedule the next move to be made after an interval of time -->

                <xsl:if test="$move != 64">
                    <ixsl:schedule-action wait="tour:speed()">
                        <xsl:call-template name="next-move">
                            <xsl:with-param name="board" select="$next-board"/>
                            <xsl:with-param name="move" select="$move + 1"/>
                            <xsl:with-param name="square" select="$best-square"/>
                        </xsl:call-template>
                    </ixsl:schedule-action>
                </xsl:if>
                
                <xsl:if test="$move = 64">
                    <xsl:result-document href="#title" method="ixsl:replace-content">
                        Completed Knight's Tour: using XSLT 3.0 with maps and arrays
                    </xsl:result-document>
                </xsl:if>

            </xsl:otherwise>

        </xsl:choose>

    </xsl:template>            
                

This code is invoked to find the next move for the knight in its tour of the chessboard. The logic is:

With the new syntax proposed in this paper, the only change to this code is that the ixsl:schedule-action logic can be simplified to:

                <xsl:if test="$move != 64">
                    <xsl:variable name="next-move" select="a:sleep(tour:speed(), $move+1)" async="yes"/>
                    <xsl:call-template name="next-move">
                        <xsl:with-param name="board" select="$next-board"/>
                        <xsl:with-param name="move" select="$next-move"/>
                        <xsl:with-param name="square" select="$best-square"/>
                    </xsl:call-template>
                </xsl:if>               
                

In addition, the next-move template, and others that call it, need to be declared with async="yes".

In addition, there's a more subtle change to what's going on here. In the original stylesheet, the final logic (the <xsl:if test="$move = 64"> instruction) executes immediately after firing off the asynchronous next-move code. With the new logic, this code executes only when the asynchronous call completes. In this example, this makes no difference, but it's useful to be aware of it.