fix: use type-specific methods in public clients, Value in internal clients

[anitarua]

addresses #69

First approach: Allows users to pass String and Binary (List) arguments to functions directly by using the dynamic type, while converting to StringValue or BinaryValue internally.

After discussion, we settled on creating public-facing methods that accept String keys and String/Binary values, but internal clients still use Value as a way to create a type union of the two

[cprice404]

this is a really cool thing to try!

I'm guessing the editor isn't able to give any type hints for this at all though? and it would be a runtime error if you just tried to pass in like, some random object type as the argument to one of these dynamic args? If so, lemme noodle on that.

[nand4011]

If type hints are a good trade for an uglier API, we could add the type to the function name like we do with some of the collection methods in Java: dictionarySetFieldsStringBytes.

[malandis]

In my reading about Dart, I see that:

• Dart does not support union types
• Dart does not support implicit conversions
• Dart does not support overloading
• Dart does support generics and generic constraints, but not sealed classes (T extends P but we cannot control who derives from P)
• Dart does support extension methods

I believe our options are then:

• Use a wrapper type that the user has to instantiate (previous solution)
• Use a wrapper type and implement extension methods so the user has to explicitly convert but it's somewhat easier (not explored): "key".asValue()
• Mangle the names to include the type information as @nand4011 pointed out
• Use the dynamic keyword and document the allowed types

I see the strong typing is one of Dart's selling points, and I do not have an intuition as to how kosher it is to use dynamic. That said I have looked at popular Dart libraries that could face this problem to see their solution:

• Hive, a nice container library. They overload the brackets operator to allow indexing by string (key) or by row id (integer). This uses dynamic https://github.com/isar/hive/blob/main/lib/src/impl/box_impl.dart#L105
• Json decoding returns a dynamic even though the universe of allowed Json types is known. https://api.dart.dev/stable/3.2.4/dart-convert/jsonDecode.html

Are there any official statements on the matter? These two GitHub issue threads show a lot of folks are unsatisfied about this:

• Union types dart-lang/language#1222
• Sum/union types and type matching dart-lang/language#83

Show no sign of quick resolution and that JSON parsing is an exemplar of the problem and a sore point for devs.

I am leaning toward using extension methods or the mangled function names.

[anitarua]

opted to allow only String keys, but can provide options for allowing binary keys too if preferable

[cprice404]

this seems like a good compromise to me.

The only suggestion I might throw out there is to consider doing a find-and-replace on the word Binary with the word Bytes, I think that might be a little more clear and a little more consistent with naming in other SDKs, but I don't feel strongly about it and am fine shipping like this if you or others prefer Binary.

[cprice404]