Transitioning to nwsapi 3.0

[dperini]

There are some extra NWSAPI signatures that needs to be taken in high consideration that must be tested too.
Most important one I believe is:

document.querySelectorAll( selector, context, callback );

This was never mentioned but their existence stems from the beginning.

So the callback() function parameter will be called in document order for each element match.
What is the advantage of doing things that way ?
What are the differences, compared to the standard loop needed to act on each of the found matches ?
The functionality is awesome if you ask me, both in term of the visual happenings and the speed of the happening.
This is my suggestion, but you can test and get the feeling of it before blindly trust me and just do it the way I say.

There are further advantages by doing it this way. The 'callback()' function might be controlled more granularly.

From the 'callback()' you might return 'false' to indicate the engine that you want to stop after the first node, or to only get the first and the last nodes of the collection.

This means you can stop the engine collecting nodes in a very precise way that will run faster, smoother and let developer express their powers in different ways. You can return 'false' at any time from the callback function. You can run a DOM query only after a previous one finished or before invoking the next, the combinations are unlimited.

Previously this was also possible by using structural pseudo-classes "xxx-child()" but visually the result is improved as is the speed and in the future I will add more spicy functionality by integrating the "delegation" module.

Well all this will probably be done only from next version of "nwsapi", namely from release 3.0 and upward.
The new version (3.0) will be ready around May, in any case before the end of June.

Before 3.0 we will add a few security changes that were asked by developers:

• Control and limit the size of each query to avoid DDOS with nested queries
• Reserve a fixed number of slots for the caching to avoid unlimited memory consumption
• Setting a fixed execution time to avoid infinite running of complex queries

Other modules that will be available bundled with "nwsapi" are: forms, events, style and I am sure developers will like these news and the new functionalities. More documentation, examples and direct support from the team will be available.

Stay tuned !

[koal44]

I was confused about how callback is supposed to be used because it looks like there is a mismatch between two paths.

When the select resolver is compiled with a callback, the generated function looks roughly like this:

function Resolver(c, f, x, r) {
  var e, n, o, j = r.length - 1, k = -1;
  // c = candidate list, f = callback, x = context, r = results

  main:
  while ((e = c[++k])) {
    // selector tests...

    r[++j] = c[k];
    if (f(c[k])) { break main; }
    continue main;
  }

  return r;
}

So in that compiled path, a truthy callback return stops collection.

But in collect(), select currently does:

factory[i] = compile(optimized[i], true, null);

i.e. it unconditionally sends null as the callback value rather than the function. Therefore it skips the compiled callback early-exit logic.

Instead, what select does is apply the callback afterward through concatCall():

if (typeof callback == 'function') {
  nodes = concatCall(nodes, callback);
}

and concatCall() stops on false:

if (false === callback(list[i] = nodes[i])) break;

So currently the behavior seems to be that callback returns false to stop, but only after the full result set has already been collected.

So just to clarify: returning false from the callback is supposed to short-circuit collection inside NWSAPI?