This is a proposal that I think would be a good idea to cleanup the code, but there may be counter-arguments I’m not aware of, so take this with a grain of salt.
In Cristal, we use undefined in a lot of function’s return types, but sometimes we use null. I believe it would be better to use a single, do-it-all type for all scenarios, and I vouch for using null.
In my opinion, undefined is a special value that should never be used explicitly in programs, except for checking equivalence. We should not use it in types, as it’s a value mainly used by the JS engine itself, and it represents the absence of value rather than an “empty” value.
You can read more about the nuance here, here, and here.
Specifically, the EcmaScript specification states that:
4.3.10 undefined value
primitive value used when a variable has not been assigned a value
4.3.12 null value
primitive value that represents the intentional absence of any object value
So I think it would be a good approach to stop using undefined in types altogether, and use null instead. The undefined values should only be used for the absence of a value, for instance in an optional object property.
null is ok when the type can actually have the absence of something.
In opposition, using null to represent a failing state is not ok (e.g., a get(index: number) function should not return null for an out-of-bounds index, but only when the value at the requested index is null. We need a separate proposal to agree on a way to represent errors in types.
Moreover, I’m -1 to break existing publicly exposed types using undefined, unless we have to modify them for another reason.
I’d say the opposite. It’s the right time since there are no existing public API yet in Cristal (as v1.0 has not been released yet and there are no users of the APIs except us). It’ll be much harder later on.
Said differently, now is not the right time to leave any technical debt on API in Cristal.
PS: I’m not commenting on the “undefined” topic. This is just a general remark on API breakage.
I’m not really sure, on one side it’s true we can afford breaking things, on the other side this may result in subtle breakages given null and undefined interact in sometimes weird ways.
But it’s true that given we don’t have that much code surface yet, this may be a good time to break things, and it’ll be a good motivation for pushing a better test harness for Cristal.
ok, I don’t think we want to go for a full fix of everything at once, because it can get complex.
But I agree we can take the opportunity of modifying a package for an unrelated reason to also comply with the new rule since, as Vincent said, we are still in a position where breaking APIs is ok.