So, the only real difference between the DOM and On Demand APIs, from a user point of view, is that On Demand can't access things out of order. (It's true that we made an exception to this for objects, but for the purposes of this discussion, let's view that as a one-off.)

I propose we remove this restriction, treating On Demand as what it currently is: a full index of structurals. Values store their start_index (though I believe it's optimized away). I propose we use that start_index to access values instead of relying solely on the global cursor.

Pros

• DOM Equivalence: The On Demand API is already 90% compatible with the DOM, which has usability on a level with gold standards like nlohmann_json. The 90% compatible is probably the right 90% (the most common use cases). Making this change would buy us the other 10%, making switching easy.

• Sharp Edge Elimination: Right now, you can still get errors because you introduced out of order access--or worse, got inexplicably bad behavior at runtime because you compiled in release instead of debug mode. It can be hard to understand these errors. We could improve error messages, but these are still poky edges. These will make some people think twice about using or recommending simdjson. This change would eliminate all (or 99.9%) of those sharp edges.

  It's not theoretical, either: when writing examples, I wrote make_pair<double, double>(object["x"], object["y"]), and it failed at runtime. This happened because the cursor moved from x to y.

Concerns

• Performance: If we start using start_index, it's possible it will no longer be optimized out, slowing down even forward-only use cases. This is a real risk, but I suspect it won't materialize: when a value is used forward-only, the underlying cursor will be == start_index. Optimizers should be able to recognize the pattern value.start_index = iter.index; *value.start_index and just use *iter.index.
• Future Streaming Support: By doing this, we lose the hard line that has been drawn in the code, ensuring it will work with future streaming support. But the majority use case--possibly even the one we'll ship with in 1.0--is non-streaming; we're replacing a DOM :) I think if we do this carefully we won't lose the code; but even if we did, it's in source control and we can resurrect what we need when we do support streaming.
• Array and Object Cursor: Right now, we only allow nested iteration--we never allow iteration of more than one object or array at a time. This is because we do iteration in a cursor, for really good reasons. This is a thorny problem, but it may well be possible to introduce a new local cursor when you begin() an out-of-order iteration on an array or object, without performance impact if the optimizer is reasonable. At the least, we can emit a good runtime error consistently.