An untagged variant is a variant type declared with @unboxed whose cases are
represented by their bare JavaScript values: a nullary case by a literal, a
case with a payload by the payload itself. No field records which case a value
belongs to, so a switch recognizes the case by testing the value at run
time, and the type checker limits the payload cases to kinds these tests tell
apart (rule 6). The user manual describes the feature in
Untagged variants.
This document states the rules the compiler implements. Each rule names the
code that implements it and the tests that pin it. Tests named
spec_test are in
tests/tests/src/untagged_variants_spec_test.res;
the committed .mjs beside it shows the checks emitted for each declaration.
Fixtures are in tests/build_tests/super_errors/fixtures/ unless another
directory is named.
@unboxed on a variant type makes the whole variant untagged: every case with
a payload is represented by its payload. @tag(...) on the type is copied
onto every constructor. A constructor cannot have its own @unboxed: it would
mix tagged and untagged cases in one variant, and is an error telling to write
it on the type. For a constructor whose payload is an inline record with one
field, @unboxed on the type makes the value that field (the legacy unboxed
representation), so the error also tells to give the record type a name to
keep the record object.
| Declaration | Value | JavaScript |
|---|---|---|
@unboxed type whole = WA(int) | WB({x: int}) | WC |
WA(3) |
3 |
WB({x: 1}) |
{x: 1} |
|
WC |
"WC" |
| Declaration | Error | Fixture |
|---|---|---|
type t = | @unboxed A(int) | B({x: int}) | C |
@unboxed applies to a whole variant: write it on the type, ... | unboxed_on_constructor.res |
type t = | @unboxed A({x: int}) |
the same, and how to keep the record object | unboxed_on_single_field_record_constructor.res |
The layout of a declaration is computed once, after its recursive group is in the environment, and stored on the declaration.
- Implementation:
typedecl.ml(the constructor check andcopy_tag_attr_from_declintransl_declaration; the layout pass intransl_type_decl),variant_layout.ml:layout_from_type_variant. - Tests:
spec_testrule 1; the fixtures above. - Shaped by #7320 (recursive groups), #8579 (layout stored once), #9020 and
#9038 (constructor-level
@unboxedremoved).
A nullary case is its @as literal, or the string of its name when it has no
@as. A case with a payload is the payload; an inline-record payload is a
plain object holding the fields. In an untagged variant, @as on a case with
a payload and @tag on the type do not change the representation.
| Declaration | Value | JavaScript |
|---|---|---|
@unboxed type t = Named | @as("s") Str | @as(null) Null | Payload({x: int}) |
Named |
"Named" |
Str |
"s" |
|
Null |
null |
|
Payload({x: 1}) |
{x: 1} |
|
@unboxed @tag("kind") type t = TI({x: int}) | TS(string) |
TI({x: 1}) |
{x: 1} |
@unboxed type t = @as("x") AsX(string) | AsY(int) |
AsX("v") |
"v" |
- Implementation:
ast_untagged_variants.ml:declared_tag(a case without@asis its name, resolved once in the layout),translcore.ml:transl_exp0(constructor application). - Tests:
spec_testrule 2.
@as takes a string, an int, a float, a bigint, a boolean, null or
undefined. Any other payload is an error, and so is a second @as on one
constructor. An int literal must fit the compiler's native integer; it is
emitted with the 32-bit representation of int values, so @as(4294967297)
is the number 1.
- Implementation:
ast_untagged_variants.ml:runtime_tag_of_parsetree,process_constructor_tag. - Tests: fixtures
UntaggedInvalidVariantAsAnnotation.res("A variant case annotation @as(...) must be a string, integer, float, bigint, boolean, null, or undefined."),VariantAsIntegerOutOfRange.res,UntaggedDuplicatedBsAs.res;spec_testrule 2;tests/tests/src/unboxed_variant_fold_test.res(wide).
A case of an untagged variant has at most one payload. Its type is classified into one kind:
| Payload type | Kind | Recognized by |
|---|---|---|
string |
string | typeof x === "string" |
int, float |
number | typeof x === "number" |
bigint |
bigint | typeof x === "bigint" |
bool |
boolean | typeof x === "boolean" |
| a function type | function | typeof x === "function" |
a record (not @unboxed), an inline record, a JavaScript object type {"x": int}, dict<_> |
object | typeof x === "object" |
array<_>, a tuple |
instance Array |
Array.isArray(x) |
a type declared with @instanceOf("C") (rule 5) |
instance C |
x instanceof C |
promise<_> |
instance Promise |
x instanceof Promise |
a type declared with @typeOf("k") |
kind k |
typeof x === "k" |
anything else: an abstract type, a type variable, a variant, list<_>, an @unboxed record |
unknown | no check |
The builtin types state their kinds in their declarations, as the
annotations of rule 5 do for declared types. The shape is read from the type
as written and from each type it abbreviates, and a tuple, a function type
or a record is classified after expanding abbreviations, private ones
included: type ints = array<int> is an array case, and type name = private string a string case. Every
reader of rule 5 uses this one classification. A type is never recognized by
its name. @typeOf("number")
is the number kind, and @typeOf("symbol") is a kind of its own, with no
builtin payload type. @notUndefined on an abstract type leaves it unknown.
- Implementation:
predef.ml(the builtin shapes),variant_layout.ml:payload_kind,get_block_type,recognized_as. - Tests:
spec_testrules 4 (kinds,tuples,aliasDict,instances,unknown); fixturesUntaggedConstructorMoreThanOneArg.res,UntaggedConstructorAttributeMoreThanOneArg.res,UntaggedNonUnary1.res,UntaggedNonUnary2.res("Constructor A has more than one argument."),UntaggedUnknown.res(list<float>is unknown),untagged_unannotated_stdlib_name.res(a type named like a stdlib class is unknown);tests/tests/src/untagged_runtime_annotations_test.res,untagged_builtin_alias_test.res. - Shaped by #6121, #6208, #6219, #6279, #6368, #6394, #6550, #6670.
Three annotations declare what the values of a type are at run time, each level implying the one before:
@notUndefined: they are neverundefined;@typeOf("k"): theirtypeofisk, one of"string","number","bigint","boolean","symbol","function"and"object";@instanceOf("C"): they are instances of the global class at the pathC, such as"Date"or"Intl.Locale".
Like an external, an @instanceOf type can say where its class is found:
@module("m") reads the path among the exports of the module m, with
"default" for its default export, and imports it as a @module external
does, and @scope puts its properties in front of the path, so
@scope("THREE") @instanceOf("Mesh") is @instanceOf("THREE.Mesh"):
@module("three") @instanceOf("Mesh") type mesh // x instanceof Three.Mesh
@module("./shapes.js") @instanceOf("default") type shapeOn a type without @instanceOf, @module and @scope have no effect, so
they are errors. Before #9239 the compiler ignored them on every type without
a word, which hid that bug.
A type has at most one of the three, and only abstract types and type
abbreviations, public or private, can have one.
@notUndefined affects only rule 12: option of the type, and of an untagged
variant with a payload of the type, is unboxed. It does not make the type a
recognized payload kind (rule 4).
When a type is declared, its annotation is resolved into its shape, which
is stored on the declaration: "never undefined", the typeof kind, or the
class with its superclasses. The builtin types state their shapes in their
declarations (rule 4). The classes annotated further down a chain of
abbreviations are the superclasses (rule 8):
@instanceOf("Animal") type animal
@instanceOf("Dog") type dog = private animalThe classifier and every other reader take the shape of the payload type as written, or of the first type it abbreviates that states one, so the outermost annotation decides. A shape is resolved in the environment the type is declared in, so an interface's shape is what its users see, even where the implementation knows more. An annotation that repeats the abbreviated type's, as the declarations of a module alias do, adds no superclass.
An annotation on an abbreviation must agree with the abbreviated type. It can
refine a type whose representation the compiler does not see, an abstract
type that is not builtin and has no annotation, or restate what the
abbreviated type is known to be (rule 4), as @typeOf("number") type count = int, @typeOf("function") type callback = int => int and @notUndefined type count = int do; a restating @notUndefined keeps the
kind of int. The type of a functor parameter, of a
recursive module being defined, and a locally abstract type (type a) are
abstract only where they are declared: they stand for another type, so they
cannot be refined. Only a private abbreviation can declare a subclass of the
class annotated there, or of a @typeOf("object") type, also in a phantom
type hierarchy (type dogLike<'a> = private animalLike<_dog<'a>>). A public
type dog = animal would make every animal a dog without a coercion, and so
would type dog = animal<int> or type dog = phantom<int> with
type phantom<'a> = animal.
A class introduced on an abbreviation of a type the compiler does not see is
private too: @instanceOf("Element") type element = private node. A public
abbreviation would make every node an element, and a second one could
declare the same values instances of another class while the type checker
treats both as one type. The stdlib's typed arrays are such private
abbreviations of TypedArray.t<_>, so Int8Array.t and Uint8Array.t are
different types, upcast to TypedArray.t<int> with :>. Each typed array
module has the functions of TypedArray for its own type, through the
TypedArray.Impl functor.
| Declaration | Error | Fixture |
|---|---|---|
@typeOf("string") type t = option<string>, type t<'a> = 'a, an abbreviation of unit, list<_> or a variant |
@typeOf on a type abbreviation must describe an abstract type, ... | runtime_annotation_on_option.res, runtime_annotation_on_type_variable.res |
@notUndefined type t = option<int> |
@notUndefined on a type abbreviation must describe an abstract type, ... | not_undefined_on_option.res, tests/build_tests/not_undefined_attribute |
@typeOf("number") type t = sym with @typeOf("symbol") type sym, @typeOf("string") type t = int, or an abbreviation of a function type, a record or a tuple |
This annotation, @typeOf("number"), contradicts the abbreviated type, whose values are recognized by @typeOf("symbol"). An array or tuple is recognized by Array.isArray. | runtime_annotation_contradicts_manifest.res, runtime_annotation_contradicts_builtin.res, runtime_annotation_contradicts_function.res, runtime_annotation_contradicts_tuple.res |
@instanceOf("Date") type date = X.t in a functor of X, or over (type a); @notUndefined type t = X.t |
@instanceOf cannot describe the type of a functor parameter, ... | instance_of_functor_parameter.res, type_of_locally_abstract_type.res, not_undefined_on_functor_parameter_type.res |
@instanceOf("Dog") type dog = animal, = animal<int>, or = phantom<int> with type phantom<'a> = animal |
A subclass must be a private abbreviation ... | instance_of_public_subclass.res, instance_of_public_subclass_instance.res, instance_of_public_subclass_through_alias.res |
@instanceOf("Element") type element = node with type node |
A class must be declared on an abstract type or a private abbreviation ... | instance_of_public_abbreviation.res; typed_array_cases_distinct.res (typed arrays are distinct types) |
@instanceOf("Animal") type t = private dog |
Animal appears twice in this chain of abbreviations ... | instance_of_class_twice_in_chain.res |
@instanceOf("MyList") type t = private array<int> |
@instanceOf("MyList") cannot describe the values of an array type: ... subclasses of Array are not supported. | instance_of_array_subclass.res |
| any of the three on a record or variant | @instanceOf can only be used on abstract types and type abbreviations ... | runtime_annotation_on_record.res, invalid_attribute_not_undefined.res |
| two of the three | A type can have only one of @notUndefined, @instanceOf and @typeOf. ... | runtime_annotation_conflict.res, runtime_annotation_not_undefined_conflict.res |
| one annotation twice | Duplicate @instanceOf annotation; a type can have only one. | instance_of_duplicate.res |
What an interface states about a type must hold for its implementation. A
class or typeof, stated through its own annotation or the type it
abbreviates, must be the one the implementation has by rule 4, superclasses
included: "Their runtime representations differ"
(runtime_annotation_interface_over_record.res). A builtin type states its
kind, so @typeOf("number") type t in an interface accepts type t = int
(untagged_builtin_alias_test.res), and @typeOf("function") type t accepts
type t = int => int (untagged_runtime_annotations_test.res). Under @notUndefined, the
implementation must be a type that cannot hold undefined either, or one
whose representation the compiler does not see, which has none to contradict
it: an abstract type, also through an abbreviation such as
type t = Dom.element, or a JavaScript object type; a functor parameter's or
a locally abstract type stands for another type and does not count.
type t = option<int> under @notUndefined type t is an error: "the second
declaration is @notUndefined, but the first declaration can hold undefined".
An interface that states nothing hides the shape. The same holds for functor
arguments, with type constraints and module type ascriptions. Within one
variant a class is identified by its path and its module, so two types of the
same class are one case (rule 6), while a global Mesh and the Mesh that
"three" exports are two; across a signature the two declarations must also
state the same superclasses and module
(runtime_annotation_interface_module_class.res).
The class path is a dot-separated list of identifiers whose first one is not a JavaScript keyword. In a module, the path names an export, which can be named like a keyword and can be any class, so none of the global paths below is rejected there. Paths that name no class to recognize values by are rejected as well:
| Path | Error | Fixture |
|---|---|---|
| not a string, not a path, or a keyword global | @instanceOf expects the name of a global class ... | instance_of_invalid_class.res, instance_of_keyword.res, instance_of_not_string.res |
globalThis.C |
Write @instanceOf("C") without "globalThis." ... | instance_of_global_this.res |
Object, Function |
Every object is an instance of Object ... Use @typeOf("object") instead. | instance_of_object.res |
Array |
Arrays are recognized by Array.isArray ... | instance_of_array.res |
String, Number, Boolean, BigInt, Symbol |
Values of type bigint are primitives ... | instance_of_primitive_wrapper.res |
globalThis, undefined, NaN, Infinity, Math, JSON, Reflect, Atomics, Intl, Proxy |
Math is not a class ... | instance_of_not_a_class.res |
not a path, with @module |
@instanceOf expects the name of a class that "three" exports ... | instance_of_module_invalid_class.res |
@module without one non-empty string, or a payload of @instanceOf that is not a string with @module |
@module on an @instanceOf type expects the module that exports the class ...; @instanceOf expects the name of a class that "three" exports ... | instance_of_module_invalid_payload.res, instance_of_module_empty.res, instance_of_module_not_string.res |
a @scope without a string or a tuple of strings, or with a property that is not an identifier |
@scope on an @instanceOf type expects the properties the class is read through ... | instance_of_invalid_scope.res, instance_of_scope_not_strings.res, instance_of_scope_without_payload.res |
a first @scope property named like a keyword, without @module |
Without @module, the first property of @scope is a global, which cannot be named like the keyword "default". | instance_of_scope_keyword.res |
a first @scope property globalThis, without @module |
Remove "globalThis" from @scope ... | instance_of_scope_global_this.res |
@module or @scope twice |
Duplicate @module annotation; a type can have only one. | instance_of_module_duplicate.res |
@module or @scope on a type without @instanceOf |
@module on a type declaration names the module a class is imported from, so it needs @instanceOf ..., with what to do for an abstract type, a type with @typeOf or @notUndefined, and a record or variant |
module_without_instance_of.res, scope_without_instance_of.res, module_on_record.res |
An unknown typeof is an error too (type_of_invalid.res). The class is read
as a global; where a local binding of the same name is in scope, it is read
through globalThis (#8785). A class of a module is read through the module's
import, which the module that compiles the check adds, wherever the type is
declared (untagged_module_class_test.res). The compiler trusts the annotations, as it
trusts the type of an external: a value that is not what its type declares is
recognized by what it is (rule 10).
The stdlib annotates the types of the classes it binds:
| Type | Annotation |
|---|---|
Date.t, RegExp.t, ArrayBuffer.t, DataView.t, Map.t, Set.t, WeakMap.t, WeakSet.t, Blob.t |
@instanceOf the class of the same name |
File.t, a private abbreviation of Blob.t |
@instanceOf("File"), a subclass of Blob |
JsError.t |
@instanceOf("Error") |
Intl.Collator.t, Intl.DateTimeFormat.t, Intl.ListFormat.t, Intl.Locale.t, Intl.NumberFormat.t, Intl.PluralRules.t, Intl.RelativeTimeFormat.t, Intl.Segmenter.t |
@instanceOf("Intl.Collator") and so on |
Int8Array.t and the other typed arrays, public abbreviations of TypedArray.t<_> |
@instanceOf the class of the same name |
Symbol.t |
@typeOf("symbol") |
The typed-array types are abbreviations of one type, TypedArray.t<_>, and
are told apart only by their annotations, which are read on the name as
written (Known bugs).
- Implementation:
types.mli:type_shape,variant_runtime.mli:value_shape;variant_layout.ml:declaration_shape,resolve_shapes,value_shape,payload_kind;typedecl.ml:check_manifest_annotation;typeopt.ml:abstractness,undefinedness;ast_untagged_variants.ml:process_runtime_annotation,unsupported_class,check_runtime_annotation;includecore.ml:compare_runtime_annotations;variant_runtime.ml:Instance;lam_compile_external_call.ml:class_constructor. - Tests:
spec_testrules 4 and 5;tests/tests/src/untagged_runtime_annotations_test.res,untagged_runtime_annotations_shadow_test.res,untagged_file_blob_test.res,not_undefined_interface_test.res,not_undefined_abbreviation_test.res; the fixtures above,UntaggedAtMostOneInstance.res,UntaggedTupleAndArray.res,not_undefined_functor_argument.res,not_undefined_functor_parameter.res;tests/build_tests/super_errors_multi/fixtures/Cross_runtime_annotation_hidden_superclass,Cross_runtime_annotation_hidden_base,Cross_runtime_annotation_claimed_by_interface,Cross_runtime_annotation_functor_argument,Cross_not_undefined_option_implementation. - Shaped by #6296, #6383, #6396, #7458, #7464, #7788, #8009, #8950, #8948, #8949, #8955, #8964. Related: #7147.
The type checker rejects an untagged variant, with "This untagged variant definition is invalid: ..." and the reason below, when:
| Condition | Reason | Fixture |
|---|---|---|
| two object cases | At most one case can be an object type. | UntaggedAtMostOneObject.res |
two cases of one instance class, compared by path and module (arrays, tuples and records represented as arrays share Array) |
At most one case can be an instance of C; for Array, an array, a tuple or a record represented as an array. |
UntaggedAtMostOneInstance.res, UntaggedTupleAndArray.res, untagged_array_record_and_array.res, untagged_same_class_twice.res |
| two function cases | At most one case can be a function type. | UntaggedAtMostOneFunction.res |
| two string cases | At most one case can be a string type. | UntaggedAtMostOneString.res |
two number cases (int and float count together) |
At most one case can be a number type (int or float). | UntaggedAtMostOneNumber.res |
| two bigint cases | At most one case can be a bigint type. | UntaggedAtMostOneBigint.res |
| two boolean cases | At most one case can be a boolean type. | UntaggedAtMostOneBoolean.res |
| two symbol cases | At most one case can be a symbol type. | untagged_two_symbols.res |
| an unknown case beside another case with a payload | Case A has a payload that is not of one of the recognized shapes ... | UntaggedOnlyOneUnknown.res, UntaggedUnknown.res |
a bool case when both true and false are literal cases |
Case B can never match ... | UntaggedUnreachableBoolean.res |
| two nullary cases with the same literal | Duplicate literal x. | UntaggedDuplicateLiteral.res |
| two nullary cases whose literals are spelled differently but are the same JavaScript value | The literal 1.0 is the same JavaScript value as 1. | untagged_literal_same_number.res, untagged_literal_same_int32.res, untagged_literal_same_bigint.res |
Literals are compared per kind: string literals with each other (a case
without @as counts as its name), and all other literals with each other by
the JavaScript value they denote, as the === of a switch compares them.
An int is the 32-bit number it is emitted as (rule 3), so 1, 1.0 and
4294967297 are one number, and so are 0 and -0.; 1n is a bigint and
differs from 1, and 001n is 1n. Constant folding (rule 11) compares
literals the same way. The duplicate-literal check applies to every variant, tagged
or not; in a tagged variant it also compares the @as tags of the cases with
a payload.
A literal may equal a value of a payload case: @as("a") A | S(string),
@as(1) A | I(int), @as(null) N | O({x: int}) and
@as(true) A | B(bool) are accepted. Rule 7 says which case such a value
belongs to.
- Implementation:
variant_layout.ml:check_invariant,variant_runtime.ml:literal_value_key. - Tests: the fixtures above;
tests/tests/src/unboxed_variant_fold_test.res(a number and a bigint literal with the same digits);TaggedDuplicateLiteral.res,multiple_tag_1.res,multiple_tag_2.res(tagged variants). - Shaped by #6128, #6136, #7441, #8777, #8953.
A switch with literal and payload arms first tests whether the value is one
of the literal cases, compares it with === against each literal arm, and
only otherwise tests the payload cases. A value equal to a literal therefore
belongs to the literal's case, even when it was built with a payload
constructor:
| Declaration | Value | Case |
|---|---|---|
@as("a") LitA | AnyString(string) |
AnyString("a") |
LitA |
@as(1) LitOne | AnyInt(int) |
AnyInt(1) |
LitOne |
@as(true) LitTrue | AnyBool(bool) |
AnyBool(true) |
LitTrue |
@as(true) LitTrue | AnyBool(bool) |
AnyBool(false) |
AnyBool |
@as(null) LitNull | AnyObject({x: int}) |
LitNull |
LitNull |
The literals are compared with ===: by one switch (x) over the literal
arms, whose default holds the payload dispatch, or, when at most two
literals get a case, by an if per arm body. A literal without an arm of its own goes
to the default arm. It reaches the default through the payload dispatch,
which then checks its last arm, when the payload dispatch takes it there
without a class check; otherwise, as for a string literal beside a string
arm, any literal beside an unknown-kind arm, or a literal whose kind meets a
class check, it gets a case leading there. A null literal that only the
object check would accept adds x !== null to that check instead (rule 9).
The dispatch tests nothing whose outcome runs the same body: arms of
different kinds with one body, also arms with the default's body, are left
to one unchecked branch, and a literal with the body of a payload dispatch
that runs one body unchecked gets no case.
A payload pattern whose every value is a literal case's can therefore never
match, and is reported: warning 11 for an arm, such as S("a") beside
@as("a") A, and warning 12 for an alternative of an or-pattern, both with
""a" is the runtime value of constructor A, so it is always matched as A,
never as S". Values are compared as === compares them (rule 6), so
BI(02n) beside @as(2n) Two and P(#Foo) beside @as("Foo") F are
reported too, and an or-pattern also counts when it is named with as. An
untagged payload inside another is the value itself, so the outer literal
cases also shadow it: W(N(1 | 2)) reports 1 beside @as(1) One | W(inner). For the
exhaustiveness check a literal case covers the payload values equal to it, so
Yes | Ans(false) is a complete match of @as(true) Yes | Ans(bool). This
needs a payload of type bool, also through an abbreviation: a
@typeOf("boolean") type has no true and false patterns, so Yes alone
does not cover it.
- Implementation:
untagged_dispatch.ml:plan(the literal part);parmatch.ml(shadowed payload patterns, exhaustiveness). - Tests:
spec_testrule 7;tests/tests/src/untagged_variants_heuristic.res(literals that skip theswitch);unboxed_variant_fold_test.res(answerName2,bigintOrPayloadName); fixtureswarning_11_untagged_literal_shadows_payload.res,warning_11_untagged_literal_shadows_payload_kinds.res,warning_11_untagged_literal_shadows_bigint.res,warning_11_untagged_bool_payload_overlap.res,warning_8_untagged_boolean_kind_payload.res,warning_11_untagged_literal_shadows_polyvariant.res,warning_12_untagged_literal_shadows_or_pattern.res,warning_12_untagged_literal_shadows_aliased_or_pattern.res,warning_12_untagged_literal_shadows_nested_payload.res. - Shaped by #6125, #7128, #7135, #8806.
The payload arms compile to one switch (typeof x) over the arms of
primitive kinds (string, number, bigint, boolean, symbol), an if for one
kind, whose default is an if chain over the other arms:
- the instance cases (arrays, tuples and classes), a subclass before its superclasses (rule 5), otherwise in declaration order;
- the function case,
typeof x === "function"; - the object case,
typeof x === "object"; - the unknown-kind case, unchecked.
switch (typeof x) {
case "string": ...
case "number": ...
default:
if (x instanceof Dog) { ... }
else if (x instanceof Animal) { ... }
else if (typeof x === "object") { ... }
}An instance case without an arm leads to the default arm, so an array or a
class instance never lands in the function or object case. Before the last
checked arm such checks are folded into its check, which then guards them:
typeof x === "object" && !(x instanceof Date). A primitive never reaches a
class check: it is taken by the switch (typeof x), where a primitive kind
of the variant without an arm has a case leading to the default when a
class check could follow. In a complete match the last arm is not checked
(rule 10).
A value upcast to the superclass and wrapped in its case lands in the
subclass case, as a payload equal to a literal lands in the literal's case
(rule 7). instanceof consults Symbol.hasInstance, which is trusted for
the values that reach the check: objects and functions, and values outside
every case (rule 10).
An int case is recognized by typeof x === "number" and so receives every
number, integral or not.
break and continue in an arm leave or continue the enclosing loop: an
arm placed in a generated switch statement is compiled in a switch
context, where they are labeled; an arm of an if is not
(untagged_loop_control_test.res, scanIf).
- Implementation:
untagged_dispatch.ml:payload_partbuilds the dispatch as a plan,lam_compile.ml:compile_untagged_planprints it; ounit tests inounit_untagged_dispatch_tests.mlpin plans as data. - Tests:
spec_testrules 4, 5 and 8 (instanceNameshows the chain in declaration order,objectFirstthe unchecked last arm);tests/tests/src/UntaggedVariants.res(AllInstanceofTypes,MergeCases);tests/tests/src/untagged_runtime_annotations_test.res(subclasses, the function case, a missing class);untagged_default_arm_test.res(Symbol.hasInstance, incomplete matches);untagged_loop_control_test.res(break,continue). - Shaped by #6103, #6383, #6792, #7144, #7149.
typeof null and typeof [] are "object", and a class instance is an
object or a function. The object case never receives null when the variant
has an @as(null) case: the literal comparisons run first (rule 7), or the
object check tests x !== null when null goes to the default arm. Neither
the object nor the function case receives an instance of another case: the
instance checks come first (rule 8). A case declared with @typeOf("object")
(rule 5) is an object case: without an @as(null) case, it receives null,
as a record case does.
| Declaration | switch arms |
Value | Arm |
|---|---|---|---|
GArray(array<int>) | GObject({x: int}) | @as(null) GNull |
all | [] |
GArray |
| all | null |
GNull |
|
GObject(_), _ |
[], null |
_ |
- Implementation:
untagged_dispatch.ml:plan(null_guard),payload_part. - Tests:
spec_testrule 9;UntaggedVariants.res(ObjectAndNull,Json);tests/tests/src/untagged_default_arm_test.res. - Shaped by #6219, #7303, #8253, #8255, #8279, #8995.
Recognition trusts the type. A value that belongs to no case is not
rejected: in a complete match it lands in the arm that is not checked, the
last one of the if chain, or the last primitive arm when there is no other
arm. When the match sends several cases to one shared default, the dispatch
checks the arms before it and the value lands in that default instead. With I(int) | S(string), true lands in S; with
TDate(Date.t) | TRegExp(RegExp.t), {x: 1} lands in TRegExp; with
PPromise(promise<int>) | PFloat(float), the float case is checked, so a
thenable that is not a Promise lands in PPromise.
A value from another JavaScript realm fails every instanceof check and is
recognized the same way (by the semantics of instanceof; not tested):
recognition is local to a realm. A class that does not exist where the
switch runs makes its check throw for every value that reaches it: objects
and functions, and values outside every case. The literals and the
primitives of the variant never reach it.
- Implementation:
untagged_dispatch.ml:payload_part(a complete match emits no check for its last arm). - Tests:
spec_testrule 10;untagged_runtime_annotations_test.res(a missing class).
A switch on an untagged value the compiler knows, a literal or a block of
constants, folds to the arm that the run-time dispatch selects for its
JavaScript value, so S("a") matched against @as("a") A | S(string) folds
to A. Folding evaluates the plan the code is printed from, so it agrees
with the generated code by construction, also for a value outside every case
(rule 10). A value built at run time, such as A([1]) with its array, is
matched at run time.
- Implementation:
lambda.ml:switch(untagged_value,untagged_plan),untagged_dispatch.ml:select. - Tests:
tests/tests/src/unboxed_variant_fold_test.res;spec_testrule 10 (a folded value outside every case);ounit_untagged_dispatch_tests.mlcompares the plans of random variants and matches with rules 7 to 9. - Shaped by #8631.
Some(v) is emitted as v when the type of v cannot hold undefined, and
as Primitive_option.some(v) otherwise. An untagged variant cannot hold
undefined when no case is @as(undefined) and every payload type is
dict<_> or cannot hold undefined itself:
| Payload type | Holds undefined |
|---|---|
string, int, float, bool, bigint, a function, a tuple, a record without @unboxed |
no |
| an inline record with two or more fields | no |
an @unboxed record, an inline record with one field |
as the type of its field |
a type declared with @notUndefined, @instanceOf or @typeOf (rule 5), an @unboxed wrapper of one |
no |
an abstract type without it, a type variable, option<_> |
yes |
| a type whose declaration is not on the load path | yes |
An @as(null) case does not prevent unboxing; Some(N) is null. Some(U) of an @as(undefined) case is boxed, as a constant
too, so it stays distinct from None.
| Declaration | Some(v) |
|---|---|
@as(null) WNull | WString(string) |
v |
@as(undefined) WUndefined | WUString(string) |
Primitive_option.some(v) |
@as("n") ONone | OPaque(opaque) |
Primitive_option.some(v) |
BBlob(Blob.t) | BString(string) |
v |
DDate(Date.t) | DString(string) |
v |
RRecord(record) | RString(string) with type record = {y: option<int>} |
v |
INone | IRecord({x: option<int>}) |
Primitive_option.some(v) |
@as("n") UONone | UOption(unboxedOption) with @unboxed type unboxedOption = {x: option<int>} |
Primitive_option.some(v) |
@as("n") USNone | UString(unboxedString) with @unboxed type unboxedString = {s: string} |
v |
The stdlib's annotated types (rule 5) cannot hold undefined. It marks the
JSX element and component types, Iterator.t, AsyncIterator.t,
TypedArray.t, Intl.Segments.t, Intl.NumberFormat.Grouping.t and
Lazy.t with @notUndefined.
Rule 5 keeps an annotated abbreviation from claiming this of a type that can
hold undefined.
- Implementation:
typeopt.ml:type_cannot_contain_undefined. - Tests:
spec_testrule 12;UntaggedVariants.res(OptionUnboxingHeuristic);tests/tests/src/option_wrapping_test.res;tests/build_tests/option_transitive_dependency. - Shaped by #6222, #6233, #8719, #8954.
In a tagged variant, @tag("f") names the field that holds the tag of a case
with a payload (TAG by default), and @as on such a case sets the tag's
value. An inline-record field whose runtime name equals the tag field is an
error.
An interface and its implementation must agree on @unboxed, on @tag, on
the literal of every nullary case and of every tagged case with a payload,
and on the payload kind of every untagged case whose kind the interface
knows. A case without @as has the literal of its name, so A and
@as("A") A agree, here and in coercions (as_constructor_name_test.res). An unknown payload in the interface is its only payload case and is
not checked, so it agrees with any payload of the implementation
(untagged_hidden_payload_test.res). The @as of an untagged case with a
payload does not change its representation (rule 2) and is not compared.
Type declarations in messages print the @as of nullary and tagged cases.
- Implementation:
variant_layout.ml:layout_from_type_variant,ast_untagged_variants.ml:process_tag_name,check_tag_field_conflicts;includecore.ml:compare_variants,type_declarations. - Tests:
spec_testrule 13; fixturesUntaggedTagFieldNameConflict.res,variant_tag_overlaps_with_field.res,UntaggedInvalidVariantTagAnnotation.res,UntaggedImplIntf.res;tests/build_tests/super_errors_multi/fixtures/Iface_unboxed_variant_mismatch,Iface_tag_name_mismatch,Iface_variant_representation_mismatch;variant_payload_tag_mismatch.res. - Shaped by #6498, #6513, #6669, #7875, #8956.
Each was observed with the compiler built from this tree; the programs are
compiled with bsc and run in Node 25.
Typed arrays share one type (#8955). The typed-array types are public
abbreviations of TypedArray.t<_>, each annotated with its class, so a value
of one can be wrapped in the case of another.
@unboxed type ta = I8(Int8Array.t) | U8(Uint8Array.t)
let f = v => switch v { | I8(_) => "i8" | U8(_) => "u8" }
Console.log(f(I8(Uint8Array.fromArray([1])))) // u8The questions a mechanism for declaring classes and typeof kinds on types
had to answer, and the answers of rule 5:
- Unchecked claims. An annotation is trusted, as the type of an external is, but checked against the type it abbreviates (rule 5).
- Subclasses. A class's superclasses are the classes annotated further down its chain of private abbreviations. A superclass case excludes its subclass cases in any order, and an upcast value lands in the subclass case (rule 8). The relation must be visible where the variant is declared: an interface that hides it is rejected (rule 5).
- Overlaps across kinds.
Object,Function,Arrayand the wrappers of primitives are rejected as classes. A declared kind counts as the builtin kind (rule 6). Unrelated classes are tested in declaration order. - The unchecked branch stays the contract (rule 10).
- Realms. Recognition is local to a realm (rule 10).
- Interfaces and functors compare declared shapes (rule 5) and the payload kinds of untagged cases (rule 13).
- Implied
@notUndefined. A declared class or kind implies it, and rule 5 rejects annotations on abbreviations of types that can holdundefined. - Abbreviations. Annotations are read along the chain of abbreviations, and a type is never recognized by its name.
- Globals. A shadowed class is read through
globalThis. A missing class throws when the check runs (rule 10).