Usage (or not) of Promise in search

[iherman]

(This issue tries to summarize a discussion thread on the mailing list (see the start of the full thread and a flattened view thereof) on the mailing list regarding the usage of Promises in the FindText API.)

The current 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…

[gobengo]

Promises are great for asynchronously getting a single future result.

It sounds like you want to leave the option open for 'search' to stream many results over time. In that case Promises are probably not so good.

EventTarget is a decent interface.

var results = whatever.search('...')
results.addEventListener('result', function (result) {});

or 'forEachable'

whatever.search('...').forEach(function (result) {});

Generators are appropriate too, but futuristic.

You could also make it an iterator of promises, but meh.

More theory:
From https://github.com/kriskowal/gtor

	Singular	Plural
Spatial	Value	Iterable<Value>
Temporal	Promise<Value>	Observable<Value>