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.
Description
Adds
None
as possibleVariables
value.Motivation and Context
Incorrect handling of
null
andundefined
lead to confusion by end users, and we internally introduced bugs as TypeScript types didn't allownull
as 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
None
is defined as union ofundefined
andnull
.It will be added as possible
Variables
value.None
CANNOT be used as primitive type, it is implicit type fornullable
values.We will add
NoneLiteral
to supportundefined
andnull
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 toObject.hasOwn()
in JavaScript.By default, value is
Optional
.Required
value CANNOT beNone
.Example
If we surfaced types for profile’s input, field1 would be typed as
Optional<string>
, which can be represented also asstring | None
and 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
undefined
andnull
values.Types of changes
Checklist: