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

iherman has just created a new issue for 
https://github.com/w3c/findtext:

== Usage (or not) of Promise in ``search`` ==
(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…


Please view or discuss this issue at 
https://github.com/w3c/findtext/issues/19 using your GitHub account

Received on Thursday, 10 December 2015 10:18:35 UTC