TypeScript/JavaScript docs improvements (#5984)

* use correct language formatter for TypeScript examples

* fixes typo in JS/TS copied from PHP (apparently)

the variables are not named with a prefixed `$`

* fixes bizarre line breaks in markdown examples

* fixes snake case typo to fit JS/TS conventions

* makes example of Uint8Array usage explicit

* removes random extra lines between language blocks

* adds simple example for writing to file in node

* typo: flabuffers => flatbuffers

* adds (previously missing) code blocks to TypeScript code block

* adds context about where `monster_generated` comes from

to the uninitiated, a bit of help like this is welcome

1 files changed, 47 insertions, 38 deletions

diff --git a/docs/source/Tutorial.md b/docs/source/Tutorial.md
index 43ce54ff..15f1ccd9 100644
--- a/docs/source/Tutorial.md
+++ b/docs/source/Tutorial.md
@@ -281,7 +281,6 @@ See [flatcc build instructions](https://github.com/dvidelabs/flatcc#building).
 Please be aware of the difference between `flatc` and `flatcc` tools.
 <br>
 </div>
-
 <div class="language-cpp">
 ~~~{.sh}
   cd flatbuffers/samples
@@ -453,9 +452,11 @@ The first step is to import/include the library, generated files, etc.
 ~~~
 </div>
 <div class="language-typescript">
+~~~{.ts}
   // note: import flatbuffers with your desired import method
 
   import { MyGame } from './monster_generated';
+~~~
 </div>
 <div class="language-php">
 ~~~{.php}
@@ -534,7 +535,6 @@ The first step is to import/include the library, generated files, etc.
                                                Weapon, WeaponArgs};
 ~~~
 </div>
-
 <div class="language-swift">
 ~~~{.swift}
   /**
@@ -771,7 +771,7 @@ our `orc` Monster, let's create some `Weapon`s: a `Sword` and an `Axe`.
 ~~~
 </div>
 <div class="language-typescript">
-~~~{.js}
+~~~{.ts}
   let weaponOne = builder.createString('Sword');
   let weaponTwo = builder.createString('Axe');
 
@@ -910,7 +910,6 @@ our `orc` Monster, let's create some `Weapon`s: a `Sword` and an `Axe`.
   });
 ~~~
 </div>
-
 <div class="language-swift">
 ~~~{.swift}
   let weapon1Name = builder.create(string: "Sword")
@@ -1032,7 +1031,7 @@ traversal. This is generally easy to do on any tree structures.
 ~~~
 </div>
 <div class="language-typescript">
-~~~{.js}
+~~~{.ts}
   // Serialize a name for our monster, called 'Orc'.
   let name = builder.createString('Orc');
 
@@ -1420,7 +1419,7 @@ for the `path` field above:
 <div class="language-swift">
 ~~~{.swift}
   //
-  let points = builder.createVector(structs: [MyGame.Sample.createVec3(x: 1, y: 2, z: 3), 
+  let points = builder.createVector(structs: [MyGame.Sample.createVec3(x: 1, y: 2, z: 3),
                                               MyGame.Sample.createVec3(x: 4, y: 5, z: 6)],
                                    type: Vec3.self)
 ~~~
@@ -1701,7 +1700,7 @@ can serialize the monster itself:
 </div>
 <div class="language-swift">
 ~~~{.swift}
-  let orc = Monster.createMonster(builder, 
+  let orc = Monster.createMonster(builder,
                                   offsetOfPos: pos,
                                   hp: 300,
                                   offsetOfName: name,
@@ -1776,7 +1775,6 @@ a bit more flexibility.
   ns(Monster_end_as_root(B));
 ~~~
 </div>
-
 <div class="language-swift">
 ~~~{.swift}
   let start = Monster.startMonster(builder)
@@ -1913,8 +1911,7 @@ appropriate `finish` method.
   // Call `Finish()` to instruct the builder that this monster is complete.
   // Note: Regardless of how you created the `orc`, you still need to call
   // `Finish()` on the `FlatBufferBuilder`.
-  builder.Finish(orc); // You could also call `FinishMonsterBuffer(builder,
-                       //                                          orc);`.
+  builder.Finish(orc); // You could also call `FinishMonsterBuffer(builder, orc);`.
 ~~~
 </div>
 <div class="language-java">
@@ -1950,22 +1947,19 @@ appropriate `finish` method.
 <div class="language-javascript">
 ~~~{.js}
   // Call `finish()` to instruct the builder that this monster is complete.
-  builder.finish(orc); // You could also call `MyGame.Sample.Monster.finishMonsterBuffer(builder,
-                       //                                                                 orc);`.
+  builder.finish(orc); // You could also call `MyGame.Sample.Monster.finishMonsterBuffer(builder, orc);`.
 ~~~
 </div>
 <div class="language-typescript">
 ~~~{.ts}
   // Call `finish()` to instruct the builder that this monster is complete.
-  builder.finish(orc); // You could also call `MyGame.Sample.Monster.finishMonsterBuffer(builder,
-                       //                                                                 orc);`.
+  builder.finish(orc); // You could also call `MyGame.Sample.Monster.finishMonsterBuffer(builder, orc);`.
 ~~~
 </div>
 <div class="language-php">
 ~~~{.php}
   // Call `finish()` to instruct the builder that this monster is complete.
-   $builder->finish($orc); // You may also call `\MyGame\Sample\Monster::FinishMonsterBuffer(
-                           //                        $builder, $orc);`.
+   $builder->finish($orc); // You may also call `\MyGame\Sample\Monster::FinishMonsterBuffer($builder, $orc);`.
 ~~~
 </div>
 <div class="language-c">
@@ -2130,7 +2124,6 @@ like so:
   let buf = builder.finished_data(); // Of type `&[u8]`
 ~~~
 </div>
-
 <div class="language-swift">
 ~~~{.swift}
   // This must be called after `finish()`.
@@ -2146,6 +2139,19 @@ Now you can write the bytes to a file or send them over the network.
 If you transfer a FlatBuffer in text mode, the buffer will be corrupted,
 which will lead to hard to find problems when you read the buffer.
 
+<div class="language-javascript">
+For example, in Node you can simply do:
+~~~{.js}
+  writeFileSync('monster.bin', buf, 'binary');
+~~~
+</div>
+<div class="language-typescript">
+For example, in Node you can simply do:
+~~~{.ts}
+  writeFileSync('monster.bin', buf, 'binary');
+~~~
+</div>
+
 #### Reading Orc FlatBuffers
 
 Now that we have successfully created an `Orc` FlatBuffer, the monster data can
@@ -2217,9 +2223,10 @@ before:
 ~~~
 </div>
 <div class="language-typescript">
-~~~{.js}
-  // note: import flabuffers with your desired import method
+~~~{.ts}
+  // note: import flatbuffers with your desired import method
 
+  // note: the `./monster_generated.ts` file was previously generated by `flatc` above using the `monster.fbs` schema
   import { MyGame } from './monster_generated';
 ~~~
 </div>
@@ -2370,7 +2377,11 @@ won't work.**
 </div>
 <div class="language-javascript">
 ~~~{.js}
-  var bytes = /* the data you just read, in an object of type "Uint8Array" */
+  // the data you just read, as a `Uint8Array`
+  // Note that the example here uses `readFileSync` from the built-in `fs` module,
+  // but other methods for accessing the file contents will also work.
+  var bytes = new Uint8Array(readFileSync('./monsterdata.bin'));
+
   var buf = new flatbuffers.ByteBuffer(bytes);
 
   // Get an accessor to the root object inside the buffer.
@@ -2379,7 +2390,11 @@ won't work.**
 </div>
 <div class="language-typescript">
 ~~~{.ts}
-  let bytes = /* the data you just read, in an object of type "Uint8Array" */
+  // the data you just read, as a `Uint8Array`.
+  // Note that the example here uses `readFileSync` from the built-in `fs` module,
+  // but other methods for accessing the file contents will also work.
+  let bytes = new Uint8Array(readFileSync('./monsterdata.bin'));
+
   let buf = new flatbuffers.ByteBuffer(bytes);
 
   // Get an accessor to the root object inside the buffer.
@@ -2439,7 +2454,6 @@ myGame.Monster monster = new myGame.Monster(data);
   let monster = get_root_as_monster(buf);
 ~~~
 </div>
-
 <div class="language-swift">
 ~~~{.swift}
   // create a ByteBuffer(:) from an [UInt8] or Data()
@@ -2499,16 +2513,16 @@ accessors for all non-`deprecated` fields. For example:
 </div>
 <div class="language-javascript">
 ~~~{.js}
-  var hp = $monster.hp();
-  var mana = $monster.mana();
-  var name = $monster.name();
+  var hp = monster.hp();
+  var mana = monster.mana();
+  var name = monster.name();
 ~~~
 </div>
 <div class="language-typescript">
 ~~~{.ts}
-  let hp = $monster.hp();
-  let mana = $monster.mana();
-  let name = $monster.name();
+  let hp = monster.hp();
+  let mana = monster.mana();
+  let name = monster.name();
 ~~~
 </div>
 <div class="language-php">
@@ -2556,7 +2570,6 @@ accessors for all non-`deprecated` fields. For example:
   let name = monster.name();
 ~~~
 </div>
-
 <div class="language-swift">
 ~~~{.swift}
   let hp = monster.hp
@@ -2689,7 +2702,6 @@ To access sub-objects, in the case of our `pos`, which is a `Vec3`:
   let z = pos.z();
 ~~~
 </div>
-
 <div class="language-swift">
 ~~~{.swift}
   let pos = monster.pos
@@ -2798,7 +2810,6 @@ FlatBuffers `vector`.
   let third_item = inv[2];
 ~~~
 </div>
-
 <div class="language-swift">
 ~~~{.swift}
   // Get a the count of objects in the vector
@@ -3034,8 +3045,8 @@ We can access the type to dynamically cast the data as needed (since the
   var unionType = monster.equippedType();
 
   if (unionType == MyGame.Sample.Equipment.Weapon) {
-    var weapon_name = monster.equipped(new MyGame.Sample.Weapon()).name();     // 'Axe'
-    var weapon_damage = monster.equipped(new MyGame.Sample.Weapon()).damage(); // 5
+    var weaponName = monster.equipped(new MyGame.Sample.Weapon()).name();     // 'Axe'
+    var weaponDamage = monster.equipped(new MyGame.Sample.Weapon()).damage(); // 5
   }
 ~~~
 </div>
@@ -3044,8 +3055,8 @@ We can access the type to dynamically cast the data as needed (since the
   let unionType = monster.equippedType();
 
   if (unionType == MyGame.Sample.Equipment.Weapon) {
-    let weapon_name = monster.equipped(new MyGame.Sample.Weapon()).name();     // 'Axe'
-    let weapon_damage = monster.equipped(new MyGame.Sample.Weapon()).damage(); // 5
+    let weaponName = monster.equipped(new MyGame.Sample.Weapon()).name();     // 'Axe'
+    let weaponDamage = monster.equipped(new MyGame.Sample.Weapon()).damage(); // 5
   }
 ~~~
 </div>
@@ -3121,7 +3132,6 @@ We can access the type to dynamically cast the data as needed (since the
     let weapon_damage = equipped.damage();
 ~~~
 </div>
-
 <div class="language-swift">
 ~~~{.swift}
   // Get and check if the monster has an equipped item
@@ -3235,7 +3245,6 @@ mutators like so:
   <API for mutating FlatBuffers is not yet available in Rust.>
 ~~~
 </div>
-
 <div class="language-swift">
 ~~~{.swift}
   let monster = Monster.getRootAsMonster(bb: ByteBuffer(bytes: buf))
@@ -3316,7 +3325,7 @@ You can run this file through the `flatc` compiler with the `-b` flag and
 our `monster.fbs` schema to produce a FlatBuffer binary file.
 
 ~~~{.sh}
-./../flatc -b monster.fbs monsterdata.json
+./../flatc --binary monster.fbs monsterdata.json
 ~~~
 
 The output of this will be a file `monsterdata.bin`, which will contain the