Appendix: Subtyping rules

Each value in FlowScript belongs to at least one type. The value true, for example, belongs to the type boolean, and the value {x: 1} belongs to type {x: number}. The types themselves have mutual relationships. This document outlines the relationship between the types in FlowScript

Subtypes and supertypes

You may think of a type as a set of values. The type boolean is the set containg the two values true and false. The type boolean? (nullable boolean) is the set containing the three values true, false and null.

Because all members of the boolean set are also members of the boolean? set, boolean is a subtype of boolean?.

If A is a subtype of B, it means that you may pass values of type A whenever a value of type B is called for.

If A is a subtype of B, we say that B is a supertype of A.

// Example 1: we can assign a value of type boolean
// to a variable of type boolean?.
// In other words, boolean is a subtype of boolean?.

let x: boolean = false;
let y: boolean? = x; // no problem

// Example 2: we cannot assign any value of type boolean?
// to a variable of type boolean.
// In other words, boolean? is not a subtype of boolean.

let x: boolean? = null;
let y: boolean = x; // Type mismatch

Record subtyping

FlowScript record values are subject to width and depth subtyping rules. Width subtyping means that a record {x: number, y: number} is a subtype {x: number}. Depth subtyping means that a record {x: boolean} is a subtype of {x: boolean?}.

Intuitively, we can think of a record type as specifying the minimum members that a record must have. A record is allowed to have more members than required, but not less.

// Example: demonstrate width subtyping of records
let user = {id: 1, name: "Leon"};

// We can update the "user" variable with a record containing
// more fields than required by its type.
set user = {id: 2, name: "Theodora", email: "[e-mail]"};

In the example above, the user variable after the set statement has an extra member called email. The type of the variable, however, does not include the email member, so we cannot access it directly. The member is still there, but you must use type narrowing to "find" it.

Lowest common supertype

For any pair of types A and B, there exists at least one type C which is a supertype of A and B. The type unknown is supertype of all other types, but sometimes there is a more useful and specific common supertype. This is known as the lowest common supertype (LCS).

For example, given the types {name: text, email: text} and {name: text, age: number}, the lowest common supertype is {name: text}. We can think of the LCS as the "common denominator" of two types.

// Example of a situation where FlowScript will
// find the lowest common supertype of several values.

let people = [
    {name: "Gregorsz", email: "[e-mail]"},
    {name: "Felicia", age: 51}
];

Similarly, the LCS of boolean and boolean? is boolean? and the LCS of number* and text* is text*.