Incorrect handling of null and undefined lead to confusion by end users, and we internally introduced bugs as TypeScript types didn't allow null as a possible value.
When we were implementing Binary Data, we discovered a major flaw in types and how they interact with required/optional fields and nullable values.
We now have only JavaScript environment.
Decision
None is defined as union of undefined and null.
It will be added as possible Variables value.
None CANNOT be used as primitive type, it is implicit type for nullable values.
We will add NoneLiteral to support undefined and null values in Examples.
By default, fields are Optional.
Required field MUST fail validation only if the field in the object isn’t defined at all. So, it doesn’t matter whether the value is None or any other Model. Behaviour similar to Object.hasOwn() in JavaScript.
By default, value is Optional.
Required value CANNOT be None.
Example
usecase Example {
input {
field1 string // optional value can be String or None, in JS: 'value', undefined, null
field2 string! // required value can be String, in JS: 'value'
}
example Success {
input {
field1 = None
field2 = 'value'
}
}
}
If we surfaced types for profile’s input, field1 would be typed as Optional<string>, which can be represented also as string | None and fully expanded as string | null | undefined.
For field2, type is simply string.
Consequences
Clearly defined behaviour of absence of the value for user, as well internal handling of undefined and null values.
Types of changes
[x] Bug fix (non-breaking change which fixes an issue)
[ ] New feature (non-breaking change which adds functionality)
[ ] Breaking change (fix or feature that would cause existing functionality to change)
Checklist:
[ ] I have updated the documentation accordingly. If you are changing code related to user secrets you need to really make sure that security documentation is correct.
freaz
commented
1 year ago
Description
Adds
Noneas possibleVariablesvalue.Motivation and Context
Incorrect handling of
nullandundefinedlead to confusion by end users, and we internally introduced bugs as TypeScript types didn't allownullas a possible value.Updated specification: https://github.com/superfaceai/spec/pull/47
Decision Record internal
Context
When we were implementing Binary Data, we discovered a major flaw in types and how they interact with required/optional fields and nullable values.
We now have only JavaScript environment.
Decision
Noneis defined as union ofundefinedandnull.It will be added as possible
Variablesvalue.NoneCANNOT be used as primitive type, it is implicit type fornullablevalues.We will add
NoneLiteralto supportundefinedandnullvalues in Examples.By default, fields are
Optional.Required field MUST fail validation only if the field in the object isn’t defined at all. So, it doesn’t matter whether the value is
Noneor any other Model. Behaviour similar toObject.hasOwn()in JavaScript.By default, value is
Optional.Requiredvalue CANNOT beNone.Example
If we surfaced types for profile’s input, field1 would be typed as
Optional<string>, which can be represented also asstring | Noneand fully expanded asstring | null | undefined.For field2, type is simply
string.Consequences
Clearly defined behaviour of absence of the value for user, as well internal handling of
undefinedandnullvalues.Types of changes
Checklist: