Null and Missing Data

East includes a null value, which serves as a placeholder where there is no data or data is missing.

Null value and null type

There is a special value, null, which represents the absence of data. The East type containing null is NullType. A NullType value takes no memory (zero bits) to store, as a NullType value is always null.

While this might not seem very useful, NullType can be a useful placeholder for a slot that contains no data. One such "slot" is the associated data for a case of a variant. Since every variant case must specify an associated data type, variant cases that contain no associated data are NullType. Alternatively, as a developer you might temporarily make a field of a struct NullType and fill the data in later. And in branching statements like IfElse, a value of null can merge together with another value to make a nullable type.

Nullable data types

In the messy real world, data is often missing or unknown. Uniquitous systems from SQL to Excel to the world's most used programming languages support missing data and null values. Elara solutions that model the real world or integrate with systems exposing nullable data need to be able to handle nullable data.

In East a nullable data type is given as Nullable(T). This type represents either null or a value of type T. Every other East type can be made nullable (there is no restriction on T).

Take for example the East type Nullable(StringType), which contains strings or the value null. The TypeScript type for the values accepted by the EDK for Nullable(StringType) is null | string.

Another example is Nullable(BooleanType). This type permits three values – null, true and false.

One interesting property of Nullable is that Nullable(Nullable(T)) is the same thing as Nullable(T). Nullable doesn't nest! Also note that Nullable(T) is the only "bare" union type in East. Variants are intended as the primary way of representing data which can be one thing or another, which use a discriminated union or sum type approach instead. In fact, Elara has a variant type called Option(T) which is a different approach missing data to Nullable(T) (see the

tutorial on variants to learn more). However nullable data is so ubiquitus that it is worthwhile to build directly into East, in addition to variants.

Handling the `null` case

The primary operation for handling Nullable data is the IfNull expression. This special operation is a branching operation much like IfElse. Instead of branching on whether a value is true or false, IfNull will branch based on whether a value is null or non-null. In the non-null branch, you can guarantee the value is not null. This is the only way to (conditionally) convert a value of type Nullable(T) to a value of type T.

The way it works is IfNull produces a new variable with a non-nullable type and injects it into the scope of the non-null branch. EDK users will need to provide a function mapping the non-null input variable to an output expression. This function is optional; it defaults to value => value. The output type will need to merge together with the null branch.

East function	Description	Example usage	Result
`IfNull`	Nullable branching	IfNull("Alice", "I don't know my name", name => StringJoin`My name is ${name}`)	`"My name is Alice"`
`IfNull`	Nullable branching	IfNull(null, "I don't know my name", name => StringJoin`My name is ${name}`)	`"I don't know my name"`
`IfNull`	Replace nullable string with a "default" value `"unknown"`	`IfNull("Alice", "unknown")`	`"Alice"`
`IfNull`	Replace nullable string with a "default" value `"unknown"`	`IfNull(null, "unknown")`	`"unknown"`

As mentioned, the most important role IfNull plays is to "unwrap" the nullable value and make it non-nullable. (You can perform more operations with a non-nullable value; most operations on nullable non-primitive types are entirely forbidden).

Note that unlike languages such as TypeScript, type narrowing on branches of IfElse is not performed. Consider for example:

IfElse(
    Equal(nullable_value, null),
    default_value,
    f(nullable_value),
)

Note how f needs to also handle the nullable case because the type of the variable nullable_value is Nullable. One way or anyother, you can only use IfNull to access the non-null value as a non-nullable type. To make that concrete, let's suppose you had a nullable integer variable in scope called nullable_integer. Compare these two code snippets for incrementing a nullable integer (or returning 1 if the value was null):

IfElse(
    Equal(nullable_integer, null),
    1n,
    Add(nullable_integer, 1n),
)

IfNull(
    nullable_integer,
    1n,
    integer => Add(integer, 1n),
)

In the first you might either return 1n or Add(nullable_integer, 1n), which have types IntegerType and Nullable(IntegerType) respectively. When the two branches of IfElse are unified "widest" type that fits all possible values is picked, and you end up with Nullable(IntegerType). This expression hasn't allowed us to remove the nullability from our type.

The second expression can either return 1n or Add(integer, 1n) since that integer cannot by null. Both branches return a result of type IntegerType, so the final result is IntegerType. With IfNull a nullable integer is converted into a non-nullable integer.

Null propagation

For operations on primitive types, like Add, Or and Duration, the EDK will automatically propagate null values. So Add(1, null) produces the value null. This works as a syntactical transformation. The EDK simply inserts extra IfNull expressions to handle the nullable types as necessary.

For operations on non-primitive types (structs, variants, arrays, sets and dictionaries) you need use IfNull yourself. Experience has shown that null propagation is the "billion dollar mistake", and automatically combining null with complex types becomes a gun for programmers to shoot themselves in the foot.

Comparison and ordering

In East null compares equal to itself – meaning Equal(null, null) is true. This is in contrast to some programming environments that treat null as an "unknown value" and make comparison of nulls impossible, return false, or return null.

Because null can share a type with any other East value via Nullable(T), you can also compare null with other values. The null value is never equal to non-null value, so Equal(null, x) is false for all x except for null. Furthermore an ordering is defined, where null is always greater than every other value (including NaN). Thus LessEqual(x, null) is true for all x.

Representation

Null values are represented as null in Elara's canonical JSON representation (and their inclusion in the JSON document is not optional). They are also printed as null by Print in East's object notation.

Next steps

Continue to the next tutorial to understand how equality and ordering are defined in East and Elara.