choice randomization: better approximation of JR behaviour, fixes #49

[brontolosone]

Closes #49

I have verified this PR works in these browsers (latest versions):

• Chromium
• Firefox

Some related problems remain to be solved:

• String to number conversion: Differences between JavaRosa and Webforms #240
• Seed for randomization derived from non-numeric-looking string is always 0 javarosa#800

This brings what Webforms does more in line (barring #240) with what Javarosa does, and as such fixes the immediate problem of #49.

I felt it was worth it to be verbose with the comments here, so check those out.

This story is not over yet. Depending on whether we deem it OK to change the seed derivation algo, I'd like to make it value type/length agnostic and would just hash the input in its textual form and derive a seed from that hash - see getodk/javarosa#800. And in that case this code will need to be altered again.

[changeset-bot]

🦋 Changeset detected

Latest commit: 954f9e9

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@getodk/xpath	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[eyelidlessness]

This is great. I really appreciate how the commentary here tells the why story!

As discussed a bit in Slack, I think a couple of adjustments would make the change clearer. And would either make the need for some of the commentary moot, or make the remaining commentary more useful.

1. There's a clear "JavaRosa compatibility" responsibility here. While it is inherently coupled to the seededRandomize implementation, it is also very specifically a mapping to a more general concept: longValue. I think it would help immensely for future understanding of what's going on here if we make that an explicit function, with the same name.

2. In general, I've found liberal use of JSDoc comments (i.e. /** ... */) really helpful. The comment style provides support for all sorts of editor functionality.

   Here, we'd get a lot of benefit from inline linking support (i.e. {@link $URL_OR_REFERENCE} and/or {@link $URL_OR_REFERENCER | more specific title}). In particular I think a permalink to the JavaRosa resolveRandomSeed method would be useful, and probably also links to the pertinent issues. This ties directly to point 1: giving the JavaRosa-compatible thing a name corresponding to the Java thing it emulates, also gives a clear place for that JSDoc to reference it and clarify the nuances it's addressing.

   I think a few tweaks to this comment would be pretty much perfect.

3. We can eliminate the divergences from JavaRosa by using BigInt values for several of these cases. This, combined with their usage in a clearly articulated longValue JR-equivalent would also eliminate the need for commentary on those cases. In my local exploration of this, what I found made the most sense with the least fuss was to change type Int = number to type Int = bigint | number, then have the longValue equivalent also produce that Int type. Pretty much everything else that would need to change falls out of that (i.e. any mixed-type operators producing fractional values do the appropriate explicit Number() casts to preserve those mathematical semantics).

   It'd also be useful for the Infinity/-Infinity cases to be bound to constants with clear names. Insofar as there's still benefit to commentary on those, JSDoc on those constants is a good place.

Aside from making some of the intent clearer here, I suspect we may find there are other edge cases where we want to cordon off JavaRosa-compat/Java-isms in a general and reusable way. Even if that seems like a premature abstraction, doing it in this case is a direct, 1:1 linkable reference to the existing abstraction we'll be emulating.

Edit: oh, and this definitely feels like it deserves a changeset.

[brontolosone]

This needs updates for:

• incorporating the fallback for non-numeric-looking seed nodes to hash-based seed derivation of hash un-numeric input when used as PRNG seed, fixes #800 javarosa#801
• incorporating the followup thereof; the behaviour for zero-length strings of Extend randomize seed tests javarosa#805

Drafting!

[brontolosone]

This needs updates for:

* incorporating the fallback for non-numeric-looking seed nodes to hash-based seed derivation of [hash un-numeric input when used as PRNG seed, fixes #800 javarosa#801](https://github.com/getodk/javarosa/pull/801)

* incorporating the followup thereof; the behaviour for zero-length strings of [Extend randomize seed tests javarosa#805](https://github.com/getodk/javarosa/pull/805)

Done!