[findtext] Usage (or not) of Promise in ``search`` (#19)

(This issue tries to summarize a discussion thread on the mailing list (see the [start of the full thread](https://lists.w3.org/Archives/Public/public-annotation/2015Oct/0009.html) and a [flattened view](http://bit.ly/1jPMJb5) thereof) on the mailing list regarding the usage of Promises in the FindText API.)

The current [FindText API](https://w3c.github.io/findtext/#findtext-api) relies on two methods ``search`` and ``searchAll``. Both of these return a Promise. While there is *no* disagreement on the ``searchAll`` method (which returns a Promise with all search results in one step), questions were raised whether the ``search`` method should indeed return a Promise (or whether that method should be defined at all).

The "model" is to make a cycle using ``search`` to sequentially address each match. However, how this would/could be done with Promises (taking into account that we do not know in advance the number of hits) is not obvious. There have been a number of solutions experimented with on the thread (possibly involving ES6 generators, for example); but there are two issues still pending:

* None of the approaches are very easy to grasp, unless the developer has a complete mastership of the intricacies of Promises.
* They *seem* to provide a fake asynchrony, in fact (at least in the approaches provided in the thread). Indeed, the unfolding *all* solutions of the search would have to happen *before* the first invocation of the ``search`` method would return its value to the caller. In other words, there is no real difference, in terms of efficiency, asynchrony, etc, between calling ``search`` in a cycle, and considering the return Promise of ``searchAll`` and doing a simple cycle on the result. 

If there indeed *is* an issue with this, the possibilities that came up on the thread were

* define ``search`` as an iterator in the ES6 sense, trusting that the implementation will take care of asynchrony in the background, hidden to the end user (not sure this is possible, though)
* remove ``search`` altogether, and keep ``searchAll`` as the only entry point as a method returning a Promise with all the results

It was recognized, however, that we need some input from people who *really* understand promises…


---
Reply to this email directly or view it on GitHub:
https://github.com/w3c/findtext/issues/19