It's a language implementation gotcha, not really a library problem. The internal data structure used to represent values is polymorphic and uses flags to represent the types of operations performed on the represented data (numeric, string, etc).
The only reliable way to serialize a value with a desired type is to request that type explicitly--as one might do to represent a large integer or very precise decimal in JavaScript or JSON, for example.
Well, JSON::PP and Cpanel::JSON::XS don't have this problem somehow.
The fact that they need to literally fortune-tell from Perl guts if something is a number or a string is telling as literally every other mainstream language including current dialects of Pascal has this problem solved. But I'm most unimpressed by the fact that merely looking at a variable will mutate its internal representation enough for there to be externally-visible effects.
It doesn't matter if JSON::XS is looking at the internals wrong, or if it's Perl's behavior at fault: from whichever angle you look at it, the whole thing is a tangled mess of wrongness.
JSON::PP and Cpanel::JSON::XS don't have this problem somehow.
From my reading of the documentation of the former (especially the MAPPING section), it has the same problem for the same reasons.
the whole thing is a tangled mess of wrongness
Perl has monomorphic operators and polymorphic values. Every time someone tries to flip that, whether encoding arbitrary data structures to monomorphic values via a polymorphic visitor pattern, the smart-match experiment, or (as I already mentioned in this story's comments) polymorphic operators for data structure dereferencing, these problems occur.
Regardless of whether anyone believes that Perl's operator/value design is good or useful, that's how the language works. Working at cross purposes is an exercise in frustration. (I'll leave analogies about duck typing, contravariance, casting, and type erasure to people who like debating programming language design.)
~ perl -MJSON::XS -E 'my $d = {foo => 42}; say encode_json($d); $d->{foo} eq "bar"; say encode_json($d);'
{"foo":42}
{"foo":"42"}
~ perl -MJSON::PP -E 'my $d = {foo => 42}; say encode_json($d); $d->{foo} eq "bar"; say encode_json($d);'
{"foo":42}
{"foo":42}
~ perl -MCpanel::JSON::XS -E 'my $d = {foo => 42}; say encode_json($d); $d->{foo} eq "bar"; say encode_json($d);'
{"foo":42}
{"foo":42}
So it seems either the documentation is now wrong, or the assumptions about "usage" are wrong except for JSON::Xs (on Perl 5.32.1).
However, it "works as documented" when the implicit conversion is the other way around:
~ perl -MCpanel::JSON::XS -E 'my $d = {foo => "42"}; say encode_json($d); $d->{foo} == 0; say encode_json($d);'
{"foo":"42"}
{"foo":42}
> Every time someone tries to flip that, whether encoding arbitrary data structures to monomorphic values via a polymorphic visitor pattern, the smart-match experiment, or (as I already mentioned in this story's comments) polymorphic operators for data structure dereferencing, these problems occur.
Nothing in the typelessness of the language, though, makes it necessary to flip any internal state of a variable, though, any time its usage context changes. Especially if the state is readable by public API. Even in a typeless language, the "primary" type of the thing, if it's queryable by anything at all, should intuitively be what it's being set to by assignment or other kind of explicit mutation.
The only reliable way to serialize a value with a desired type is to request that type explicitly--as one might do to represent a large integer or very precise decimal in JavaScript or JSON, for example.