Document types in the JS nutshell

Author: Kaiepi

doc/Language/js-nutshell.pod6

@@ -1,6 +1,6 @@
 =begin pod :tag<convert>
 
-=TITLE Javascript (Node.js) to Perl 6 - nutshell
+=TITLE JavaScript (Node.js) to Perl 6 - nutshell
 
 =SUBTITLE Learning Perl 6 from Node.js, in a nutshell
 
@@ -609,9 +609,150 @@ say VERSION_NUMBER; # OUTPUT: 33554432
 
 =head2 Types
 
-=comment TODO
+=head3 Creating types
 
-# TBD
+In JavaScript, types are created by making a class (or a constructor in ES5
+and earlier). If you've used TypeScript, you can define a type as a subset of
+other types like so:
+
+=begin code :lang<typescript>
+type ID = string | number;
+=end code
+
+In Perl 6, classes, roles, subsets, and enums are considered types. Creating
+classes and roles will be discussed in
+L<the OOP section of this article|#Object-oriented_programming>. Creating an ID
+subset can be done like so:
+
+=begin code
+subset ID where Str | Int;
+=end code
+
+See the documentation on L<subset|/language/typesystem#subset> and
+L<Junction|/type/Junction> for more information.
+
+TypeScript enums may have numbers or strings as their values. Defining the
+values is optional; by default, the value of the first key is 0, the next key,
+1, the next, 2, etc. For example, here is an enum that defines directions for
+extended ASCII arrow symbols (perhaps for a TUI game):
+
+=begin code :lang<typescript>
+enum Direction (
+    UP    = '↑',
+    DOWN  = '↓',
+    LEFT  = '←',
+    RIGHT = '→'
+);
+=end code
+
+Enums in Perl 6 may have any type as their keys' values. Enum keys (and
+optionally, values) can be defined by writing C<enum>, followed by the name
+of the enum, then the list of keys (and optionally, values), which can be done
+using L«< >|/language/quoting#Word_quoting:_<_>»,
+L<« »|/language/quoting#Word_quoting_with_interpolation_and_quote_protection:_«_»>,
+or L<( )|/language/operators#term_(_)>. C<( )> must be used if you want to
+define values for the enum's keys. Here is the Direction enum as written in
+Perl 6:
+
+=begin code
+enum Direction (
+    UP    => '↑',
+    DOWN  => '↓',
+    LEFT  => '←',
+    RIGHT => '→'
+);
+=end code
+
+See the documentation on L<enum|/language/typesystem#enum> for more information.
+
+=head3 Using types
+
+In TypeScript, you can define the type of variables. Attempting to assign a
+value that doesn't match the type of the variable will make the transpiler
+error out. This is done like so:
+
+=begin code :lang<typescript>
+enum Name (Phoebe, Daniel, Joe);
+let name: string = 'Phoebe';
+name = Phoebe; # Causes tsc to error out
+
+let hobbies: [string] = ['origami', 'playing instruments', 'programming'];
+
+let todo: Map<string, boolean> = new Map([
+    ['clean the bathroom', false],
+    ['walk the dog', true],
+    ['wash the dishes', true]
+]);
+=end code
+
+In Perl 6, variables can be typed by placing the type between the declarator
+(C<my>, C<our>, etc.) and the variable name. Assigning a value that doesn't
+match the variable's type will throw either a compile-time or runtime error,
+depending on how the value is evaluated:
+
+=begin code :skip-test
+enum Name <Phoebe Daniel Joe>;
+my Str $name = 'Phoebe';
+$name = Phoebe; # Throws a compile-time error
+
+# The type here defines the type of the elements of the array.
+my Str @hobbies = ['origami', 'playing instruments', 'programming'];
+
+# The type here defines the type of the keys of the hash.
+# The type in the curly braces defines the type of the values of the hash.
+my Str %todo{Bool} = (
+    'clean the bathroom' => False,
+    'walk the dog'       => True,
+    'wash the dishes'    => True
+);
+=end code
+
+=head3 Comparing JavaScript and Perl 6 types
+
+Here is a table of some JavaScript types and their equivalents in Perl 6:
+
+=begin table
+JavaScript | Perl 6
+=============================
+Object     | Mu, Any, Hash
+Array      | List, Array, Seq
+String     | Str
+Number     | Int, Num, Rat
+Boolean    | Bool
+Map        | Map, Hash
+Set        | Set, SetHash
+=end table
+
+C<Object> is both a superclass of all types in JavaScript and a way to create
+a hash. In Perl 6, L<Mu|/type/Mu> is a superclass of all types, though usually
+you want to use L<Any|/type/Any> instead, which is a subclass of C<Mu> but also
+a superclass of nearly every type, with L<Junction|/type/Junction> being an
+exception. When using C<Object> as a hash, L<Hash|/type/Hash> is what you want
+to use.
+
+There are three types equivalent to C<Array>. L<List|/type/List> is most similar
+to C<Array>, since it acts as a mutable array. L<Array|/type/Array> is similar
+to C<List>, but is immutable. L<Seq|/type/Seq> is used to create lazy arrays.
+
+C<String> and L<Str|/type/Str> are for the most part used identically.
+
+There are several different types in Perl 6 equivalent to C<Number>, but the
+three you'll most commonly see are L<Int|/type/Int>, L<Num|/type/Num>, and
+L<Rat|/type/Rat>. C<Int> represents an integer. C<Num> represents a
+floating-point number, making it the most similar to C<Number>. C<Rat>
+represents a fraction of two numbers, and is used when C<Num> cannot provide
+precise enough values.
+
+C<Boolean> and L<Bool|/type/Bool> are for the most part used identically.
+
+C<Map> has both a mutable and an immutable equivalent in Perl 6.
+L<Map|/type/Map> is the immutable one, and L<Hash|/type/Hash> is the mutable
+one. Don't get them mixed up! Like C<Map> in JavaScript, C<Map> and C<Hash> can
+have any type of key or value, not just strings for keys.
+
+Like C<Map>, C<Set> also has both a mutable and an immutable equivalent in Perl
+ 6. L<Set|/type/Set> is the immutable one, and L<SetHash|/type/SetHash> is the
+mutable one.
 
 =head2 Functions
 
@@ -625,6 +766,12 @@ say VERSION_NUMBER; # OUTPUT: 33554432
 
 # TBD
 
+=head1 Asynchronous programming
+
+=comment TODO
+
+# TBD
+
 =head1 The networking API
 
 =head2 Net