Add API for making generator

[harumazzz]

Generator
Would be nice if we could have C API to create JS generator like JS_NewGenerator. I'm not sure if we have it yet, correct me if yes.

[bnoordhuis]

There isn't one yet. Can you provide a sketch of what JS_NewGenerator would do? Is the idea to wrap a C function that's called repeatedly?

[harumazzz]

Yes, like JS_NewCFunction but it call C function repeatedly.

[bnoordhuis]

In principle no new API is needed for that, all the pieces are already in place. Maybe a new API might makes things more convenient (lining up everything currently takes a few steps) but probably not that much more convenient.

Here is how to do it today:

1. Return an object with a Symbol.iterator property. Either create one manually or via JS_SetPropertyFunctionList:

static const JSCFunctionListEntry my_object[] = {
    JS_CFUNC_DEF("[Symbol.iterator]", 0, my_object_iterator),
    // or if you already have an iterator-returning method
    JS_ALIAS_DEF("[Symbol.iterator]", "myMethod"),
};

2. From my_object_iterator, return an iterator object:

enum { Next, Return, Throw };

static JSValue my_iterator_func(JSContext *ctx, JSValueConst this_val, int argc, JSValueConst *argv, int *pdone, int magic);

static const JSCFunctionListEntry my_iterator_proto_funcs[] = {
    JS_ITERATOR_NEXT_DEF("next", 1, my_iterator_func, Next),
    JS_ITERATOR_NEXT_DEF("return", 1, my_iterator_func, Return),
    JS_ITERATOR_NEXT_DEF("throw", 1, my_iterator_func, Throw), // can of course also be separate functions
};

3. In my_iterator_func, return a value and set *pdone = false, or return JS_UNDEFINED and set *pdone = true.

You don't even need to use JS_ITERATOR_NEXT_DEF. Plain JS_CFUNC_DEF works just as well as long as the callback returns objects with .value and .done properties: {value: 42, done: false} or {value: undefined, done: true}

4. Optional: tweak the object's prototype to make it inherit methods from Iterator.prototype