Variants

Variants represent objects that can be one of a finite number of different things (cases). Here are a few examples:

A traffic light may be red, yellow or green.
Money might be in US dollars or Australian dollars.
A geometric object might be a point, a square (with a side length) or a rectangle (with both a width and a height).
A piece of data might exist, or be missing.
A function might either successfully return a value, or encounter an error.
An IP address might be IPv4 with a 32-bit address, or IPv6 with a 128-bit address.

Variants are data structures designed to optimally represent data in all these cases. The data structure stores not only which case it is, but all the additional data required to represent that case. They are known by various names: sum types, algebraic data types, tagged/discriminated unions, variants or polymorphic row types.

Many languages provide a simple "enumeration" type for distinguishing different cases. Such enumerations are typically just pretty syntax for known integer values. While they are sufficient to identify what "type" of thing might be represented, any additional data needs to be handled seperately. Variants provide a place to store that data with strong static type guarantees.

The variants in East are somewhat similar to an enum in Rust or a variant type in OCaml. East variants consist of a set of known cases, each of which has exactly one associated value. If no associated data is required, then NullType is used. If multiple pieces of associated data is required, then a StructType may be used. (In contrast, Rust, OCaml, Haskell, etc all permit zero or more associated values.)

Variant values and types

Variants are the only East value that doesn't have a distinct type built into JavaScript. All other East types rely on JavaScripts boolean, number, bigint, string types, the null value, vanilla objects, and built-in classes Array, Set and Map. Since JavaScript doesn't provide a sum type, Elara had to provide one.

The JavaScript interface for variants

Variants are provided as a JavaScript library embedded into the EDK. The EDK exports the variant function for creating a variant. A variant with case (or tag) "a" and associated value true can be constructed by variant("a", true). If you do not need an associated value, just use null.

The TypeScript type of the above value is variant<"a", boolean>. However, you might have some variant whose case depends on run-time behavior. For example:

const v = Math.random() > 0.5 ? variant("lucky", true) : variant("unlucky", "very")

The value v might end up as either of these two distinct variants. The TypeScript type for v is variant<"lucky", boolean> | variant<"unlucky", string>.

Later you might want to use the value v. How do you do this? First you want to know what which case v has. Is it an lucky or unlucky?

If you attempted to access the associated value without first identifying the case, you end up with a value with TypeScript type boolean | string. While JavaScript is dynamically typed and this allowed, it is still difficult to do anything safely with such a value. And in East, which has strong, static typing, you cannot produce such a value.

Instead you use the match function to perform an action. You can think of match a bit like if statement or a switch statement. For each possible case, it will create .

match(v, {
    lucky: boolean_value => console.log(`I am lucky, it's ${boolean_value}!`),
    unlucky: string_value => console.log(`I am ${string_value} unlucky...`),
})

This will print out either "I am lucky, it's true!" or "I am very unlucky..." to the console. The match function is a type-safe way of unwrapping the data inside a variant. Note how it the unwrapped value is "injected" into an arrow function that you provide. TypeScript will know that the type of boolean_value is boolean and the type of string_value is string.

(Note: while TypeScript programmers would typically use "discriminated unions" to peform this task, East does not support that programming style.)

The East type for variants

So, in the EDK variant is used to provide variant values for your solution template. The East type for variants is VariantType(cases) where cases is an object mapping case names (or tags) to East types.

For example VariantType({ a: IntegerType, b: StringType }) is the type of a variant containing either case a with integer values or case b with string values. The JavaScript representation is a variant object, such as the value variant("a", 42n). The TypeScript type of such values is variant<"a", bigint> | variant<"b", string>.

East type	Example value (JavaScript)	East object notation
`VariantType({ a: IntegerType })`	`variant("a", 42n)`	`.a 42`
`VariantType({ a: IntegerType, b: StringType })`	`variant("b", "ABC")`	`.b "ABC"`

Note how the first example only has one case, a. In this case it might seem the tag doesn't add much value. However variant types can combine as branching code comes back together. So if IfElse returns .a 42 in one branch and .b "ABC" in the other, the EDK can infer the output type must be VariantType({ a: IntegerType, b: StringType }).

Constructing and deconstructing variants

East provides two fundamental expressions to construct variants and access the data within, Variant and Match. These expressions mirror the JavaScript functions variant and match provided by the EDK.

East function	Description	Example usage	Result
`Variant`	Create a new variant	`Variant("a", 42n)`	`.a 42`
`Match`	Evaluate an expression for each case	`Match(Variant("a", 42n), { a: int => Add(int, 1n) })`	`43`

Note that for Match you need to provide an expression for each case. If not, some code paths would have no value to return and the expression could not be evaluated. There is an optional third argument for Match to be applied to unhandled cases, as a kind of "default" value, so that specifying many cases redundantly doesn't become burdensome.

Let us return to earlier example of randomly generating a lucky or unlucky variant. You can do the equivalent in East with:

const v = IfElse(
    Greater(RandomUniform(), 0.5),
    Variant("lucky", true),
    Variant("unlucky", "very")
)

And for deconstructing the variant to produce a string, you can use Match:

Match(v, {
    lucky: boolean_variable => StringJoin`I am lucky, it's ${boolean_variable}!`,
    unlucky: string_variable => StringJoin`I am ${string_variable} unlucky...`,
})

Together these will produce either "I am lucky, it's true!" or "I am very unlucky...".

One tricky thing to get right is remembering what part of your code is executing to produce JavaScript values when the solution template is built, and what parts are East expressions that are evaluated on the Elara platform. To aid with this, note how the JavaScript variant functions and types use lower-case names while the East expressions and types use upper-case names.

Data modelling with algebraic data types

Variants and structs work together to provide what are called "algebraic" data types. They let you build rich and useful data structures.

Variants contain one of a number of possible named values. It represents an object that can be one thing OR another thing. They are also called "sum" types.

Structs contain a number of named values. It represents an object made up of one thing AND another thing. They are also called "product" types.

You can use them in tandem to build up a complex object. Lets take the example of a geometric object. Suppose it has a center position AND a shape. The centre has an x coordinate AND a y coordinate. The shape can be a point OR a circle OR a rectangle. A point needs no further data. A circle is described by radius. A rectangle is described by a width AND a height.

You can directly map the AND components to structs, and the OR components to variants. The coordinates and distances may be represented floats. You might use the following East type to represent such a geometric object:

GeometryType = StructType({
    centre: StrucType({
        x: FloatType,
        y: FloatType,
    }),
    shape: VariantType({
        point: NullType,
        circle: FloatType,
        rectangle: StructType({
            width: FloatType,
            height: FloatType,
        }),
    }),
})

(Note the usage of NullType for the value associated with point, as no data is necessary here.)

Using OR and AND this way for "sum" types (variants) and "product" types (structs), you have a kind of closed algebra where you can piece together data into ever more complex structures. Hence the name "algebraic" data types. By thinking about the possible shapes of your data it becomes straightforward to create an East type appropriate the problems you are solving. Together with East's arrays, sets and dictionaries your data modelling powers are essentially unlimited.

The duality between variants and structs is quite deep. There is a certain correspondence between constructing a variant and getting a field from (i.e. deconstructing) a struct. Both expressions require a value and a name. Note how the East object notation puns the "get field" operator . and reverses the order from value.name to .name value. Similarly, constructing a struct and deconstructing a variant both require a named set of expressions to be provided by the programmer.

Optional values

One common usage for varaints is to handle optional data, where a value may be present OR be absent. Optional data is quite similar to nullable data, and variants provide an alternative way to handle data that may be missing.

The EDK provides an "option" variant type and associated helper functions. An option variant has two cases: you either have some data, or you have none. The case names (tags) for the variants are "some" and "none". The some case can be associated with whatever data type you like, while the none case is always associated with the null value.

Option variants in JavaScript

To produce a JavaScript value with case some you can use the some function, like some("abc"). The constant none is the variant with case none and associated value null. These are simply shorthands for variant("some", x) and variant("none", null).

When you have an optional value you can deal with it by unwrapping it with match. However with optional values you often want to do one of two things: either remove the none case, or apply a transformation to the data in the some case.

The unwrap function is used to unwrap an optional value and return a "default" value for the none case. For example unwrap(some("abc"), "empty") is "abc" and unwrap(none, "empty") is "empty".

The mapOption function applies a transformation to the data within the some case, if it exists, and maintains the. It is a way of transforming one optional value to another.

Both unwrap and mapOption are just convenient shorthand syntax for the match function for optional values.

Option variants in East

Option variants in East are represented by the type OptionType(T), for any East type T.

East type	Example value (JavaScript)	East object notation
`OptionType(IntegerType)`	`some(42n)`	`.some 42`
`OptionType(IntegerType)`	`none`	`.none null`

Optional expressions in East resemble their JavaScript counterparts. An East expression to construct the some case with a value is Some(value). An expression for the none case is None (which is just Const(none)).

There are also the helper functions Unwrap and MapOption so you can handle optional variants conveniently in East.

East function	Description	Example usage	Result
`Some`	Create a variant with case `some` and associated value	`Some(42n)`	`.some 42`
`None`	Create a variant with case `none` and `null` value	`None`	`.none null`
`Unwrap`	Unwrap `some` or replace `none` with a default value	`Unrwap(Some(42), 0n)`	`42`
`Unwrap`	Unwrap `some` or replace `none` with a default value	`Unrwap(None, 0n)`	`0`
`MapOption`	Apply an expression to the `some` case, leave none as-is	`MapOption(Some(42n), x => Add(x, 1n))`	`.some 43`
`MapOption`	Apply an expression to the `some` case, leave none as-is	`MapOption(None, x => Add(x, 1n))`	`.none null`

Using OptionType(T) instead of Nullable(T) is an alternative way to deal with missing data. One major difference between the two approaches is that OptionType can nest. You can create an OptionType(OptionType(T)) which contains a value that you need to unwrap twice. This is different to Nullable(Nullable(T)) which is just Nullable(T) (since for example in TypeScript T | null | null is just T | null). Some developers prefer to use OptionType over Nullable to gain the increased precision when dealing with complex and nested data values, while others prefer the simplicity of Nullable.

The variant type with zero cases

Note that VariantType({}) is not a valid East type. The variant with zero cases has zero possible values. (Recall that NullType and StructType({}) each have one possible value, null or () respectively).

If a variable or data structure had this type, it would be impossible to construct a value for the variable to refer to or the data structure to hold. Expressions containing this type could not possible evaluate at run time. Thus it is a compile-time error to try and make the type VariantType({}). You can think of it as a bit like never in TypeScript.

Comparison and ordering

Variants consist of set of cases, which have their own ordering. Each case has a name, or a tag (much like the fields of a struct have a name). Because flow typing (i.e. type inference) is used extensively throughout the EDK, it is usually not practical for users to define the ordering of the variant cases by hand. The EDK will automatically order variant cases by their name (or tag) as strings to provide a predictable ordering.

In that way .none null is less than .some 1, because the string "none" comes before "some".

When two variants of the same case are compared, their associated data is compared next. Thus .some 1 is less than .some 2.

Representation

Variants are represented in East's canonical JSON format as object with fields type and value. The type is a string containing the name of the case (tag). The value contains the associated data and is not optional. (If the associated data is NullType then the null still needs to be included.)

The East object notation format for variants prints a . followed by the case name and the value, like .some 1 or .none null.

Next steps

Continue to the next tutorial to understand how variants cause types in East to be related to one another via a subtyping relationship.