# collections.group-by-key

Within a group, records keep the order they arrived in. That is the property
callers actually depend on - grouping a sorted list must not unsort it - and it
is guaranteed in all three languages.

A missing key and a null value are the same thing: both group under the empty
string "". A JSON document that omits a field and one that sets it to null mean
the same thing to every reader, and dropping those records would silently lose
data from a total. The cost is that a record whose value is genuinely "" lands
in the same group; in practice an empty string is a missing value, and if the
distinction matters, normalise before calling.

Group names are derived by an explicit rendering, not by each language's default
string conversion, because those disagree: a string is itself, an integer is its
decimal digits, true and false are "true" and "false".

A float, a list or a map at the key is an error. A float has no decimal
rendering the three languages agree on (Python prints 1.0, JavaScript prints 1),
and there is no defensible name for a group identified by a list. Integers
outside the +/-2^53 safe range are rejected for the same reason: JavaScript
would render them in exponential notation or lose digits.

Key order in the returned map is first-appearance order everywhere except
JavaScript, which reorders integer-like object keys ahead of the rest. Do not
rely on the order of the groups; sort the keys if you need one. The order WITHIN
each group is guaranteed.