Types

Author: adespawn

docs/source/internal/SUMMARY.md

@@ -32,3 +32,4 @@ this driver, new driver, scylladb-driver, scylladb-driver-alpha. Official: Scyll
 - [Logging](./logging.md)
 - [Napi](./napi.md)
 - [Miscellaneous](./miscellaneous.md)
+- [On types](./on-types.md)

docs/source/internal/on-types.md

@@ -0,0 +1,26 @@
+# Some rambling on JS types
+
+JavaScript does allow you to ignore ignore the call this library with arbitrary values as arguments.
+In general using this driver API with values of types different than provided than described in the documentation
+(JS Docs) can be considered UB.
+
+Withing JavaScript Objects we allow for some duck-typing - this applies to all of the config options and named parameters.
+Any object passed there that has required fields is considered valid.
+There are some exceptions, where we rely on some other aspects of the objects, that the field present.
+
+- Policies: In policies we expect objects with specified constructors. This means you have to used objects as provided through the driver.
+- Type guessing & encoding: Parts of type guessing and encoding depend on receiving values of specified types.
+
+When it comes to built-in types, we may perform some explicit checks to ensure you have provided expected builtin type.
+
+In general, lacks specific policy on allowing duck-typing: in many places like configuration it's allowed, but there are exceptions
+as above mentioned policies.
+
+## TS fixes something, but exposes you to other problems
+
+When you call TS function from JS code you can NOT assume that someone will call it with the types as specified in TS.
+You can only assume this is what the function should accept and correctly handle.
+When calling internally with wrong types, consider it a bug.
+When calling it internally, but with wrong types provided from user, consider it the same as direct calls from user with different types: undefined behavior.
+Either way try to gracefully handle those cases. Clear errors (remember, napi will complain when receiving invalid types: [#251](https://github.com/scylladb/nodejs-rs-driver/issues/251)),
+or where possible allow for duck-typing (ie. don't explicitly disallow it where it makes sens)