Description
TypeScript matters
When then SDK has been migrated to TypeScript, some choices have been made that are not culturally aligned with the TS community. Below is what I would like to see in the v5 of the SDK.
1. Get rid of enums
They are considered harmful. They have no benefit over a constant object but bring many downsides.
2. Use types instead of data objects
Many classes, such as LookupInResult, have no purpose.
They just force you to create an object, prevent you from manipulating the data as you see fit. They also consume memory for no reason. Very little, but still, since they have no reason to exist in the first place, don't use them.
3. Prefer utility functions
Take BucketSettings as an example.
It's a class that has a single method, a static one, to convert the data from one format to another. The method is tagged as internal.
The TS way to do this, would be to have a type that represents the data, and a utility function to change the format.
In this case, we do have a type that represent the data: IBucketSettings. And since the method is static, we don't use the conversion function from the instance. So again, no reason for a class, use utility functions.
4. Use unknown instead of any
The any type is unsafe and defeats the purpose of TS. If you don't know the type, then give it the unknown type. any is widely used in the SDK and should be removed.
You don't write TypeScript if you use any, then it's just JavaScript.
5. Better exports
Right now, everything is exported, in place.
Some types or classes should not be exposed. Such as the utility functions for example. Or classes like SdUtils.
It's also better to merge all type declarations into a single file, so you can serve different types for different versions of TS.
6. Pin the TS version
Changing the TS version of a project, is a breaking change. It allows the lib to use new syntax internally that may not be supported by the project that imports it. I have seen the version of TS been updated in v4, this should not happen.
7. Use popular file hierarchy
src is for the source of the project, not the source of a third-party. So lib is now src, and src is now napi.
Next, no more flat structure. I guess it's because we want to have clean import paths, but this can be achieved by using a bundler, that will solve this point and also point #5.
8. Prepare a clean package
Right now the package loads informations at runtime to load the bindings. To do so, it uses Node.js filesystem functions, which is a problem when using the SDK in stateless environment like lambdas.
For example, right now you cannot use Couchbase if you are using Cloudflare Workers.
Do the work once, during the install, and that's it.