TypeScript docs (#4680)

* Eclipse ignore * TypeScript support * Prefixing enums * Test results * Merged JS and TS generators * Fixed AppVeyor build problems * Fixed more AppVeyor build problems * Fixed more AppVeyor build problems * Changed TS flag to options struct * Storing options by value * Removed unneeded const * Re-export support for unions * Uint support * Casting bools to numbers for mutation * TS shell tests * Reverted generates js test file to original version * Backing up js tests and properly generating test data * Not importing flatbuffers for TS test generation * Not overwriting generated js for tests * AppVeyor test fixes * Generating the most strict TS code possible * Not returning null when creating vectors * Not returning null from struct contructors * Vector of unions for ts/js * Sanity check for languages * Indentation fix + output test files * Vectors of unions for php * Fixes to union vector handling + tests * Fix for strictPropertyInitialization * Fix for new aligned operator new for gcc >= 7.1 * Not generating imports/ns prefixes with --gen-all * TypeScript docs
2026-06-02 04:04:19 +00:00 · 2018-03-23 17:01:39 +01:00
parent 79f62ee353
commit cc54963830
5 changed files with 255 additions and 20 deletions
--- a/docs/source/FlatBuffers.md
+++ b/docs/source/FlatBuffers.md
@@ -4,7 +4,7 @@ FlatBuffers    {#flatbuffers_index}
 # Overview {#flatbuffers_overview}

 [FlatBuffers](@ref flatbuffers_overview) is an efficient cross platform
-serialization library for C++, C#, C, Go, Java, JavaScript, PHP, and Python.
+serialization library for C++, C#, C, Go, Java, JavaScript, TypeScript, PHP, and Python.
 It was originally created at Google for game development and other
 performance-critical applications.

--- a/docs/source/Support.md
+++ b/docs/source/Support.md
@@ -18,27 +18,28 @@ In general:

 NOTE: this table is a start, it needs to be extended.

-Feature                        | C++    | Java   | C#     | Go     | Python | JS        | C        | PHP | Ruby
------------------------------ | ------ | ------ | ------ | ------ | ------ | --------- | ------  | --- | ----
-Codegen for all basic features | Yes    | Yes    | Yes    | Yes    | Yes    | Yes       | Yes     | WiP | WiP
-JSON parsing                   | Yes    | No     | No     | No     | No     | No        | Yes     | No  | No
-Simple mutation                | Yes    | Yes    | Yes    | Yes     | No     | No        | No      | No  | No
-Reflection                     | Yes    | No     | No     | No     | No     | No        | Basic   | No  | No
-Buffer verifier                | Yes    | No     | No     | No     | No     | No        | Yes     | No  | No
-Testing: basic                 | Yes    | Yes    | Yes    | Yes    | Yes    | Yes       | Yes     | ?   | ?
-Testing: fuzz                  | Yes    | No     | No     | Yes    | Yes    | No        | No      | ?   | ?
-Performance:                   | Superb | Great  | Great  | Great  | Ok     | ?         | Superb  | ?   | ?
-Platform: Windows              | VS2010 | Yes    | Yes    | ?      | ?      | ?         | VS2010  | ?   | ?
-Platform: Linux                | GCC282 | Yes    | ?      | Yes    | Yes    | ?         | Yes     | ?   | ?
-Platform: OS X                 | Xcode4 | ?      | ?      | ?      | Yes    | ?         | Yes     | ?   | ?
-Platform: Android              | NDK10d | Yes    | ?      | ?      | ?      | ?         | ?       | ?   | ?
-Platform: iOS                  | ?      | ?      | ?      | ?      | ?      | ?         | ?       | ?   | ?
-Engine: Unity                  | ?      | ?      | Yes    | ?      | ?      | ?         | ?       | ?   | ?
-Primary authors (github)       | gwvo   | gwvo   | ev*/js*| rw     | rw     | evanw/ev* | mik*    | ch* | rw
+Feature                        | C++    | Java   | C#     | Go     | Python | JS        | TS        | C        | PHP | Ruby
+------------------------------ | ------ | ------ | ------ | ------ | ------ | --------- | --------- | ------  | --- | ----
+Codegen for all basic features | Yes    | Yes    | Yes    | Yes    | Yes    | Yes       | Yes       | Yes     | WiP | WiP
+JSON parsing                   | Yes    | No     | No     | No     | No     | No        | No        | Yes     | No  | No
+Simple mutation                | Yes    | Yes    | Yes    | Yes     | No     | No        | No        | No      | No  | No
+Reflection                     | Yes    | No     | No     | No     | No     | No        | No        | Basic   | No  | No
+Buffer verifier                | Yes    | No     | No     | No     | No     | No        | No        | Yes     | No  | No
+Testing: basic                 | Yes    | Yes    | Yes    | Yes    | Yes    | Yes       | Yes       | Yes     | ?   | ?
+Testing: fuzz                  | Yes    | No     | No     | Yes    | Yes    | No        | No        | No      | ?   | ?
+Performance:                   | Superb | Great  | Great  | Great  | Ok     | ?         | ?         | Superb  | ?   | ?
+Platform: Windows              | VS2010 | Yes    | Yes    | ?      | ?      | ?         | Yes       | VS2010  | ?   | ?
+Platform: Linux                | GCC282 | Yes    | ?      | Yes    | Yes    | ?         | Yes       | Yes     | ?   | ?
+Platform: OS X                 | Xcode4 | ?      | ?      | ?      | Yes    | ?         | Yes       | Yes     | ?   | ?
+Platform: Android              | NDK10d | Yes    | ?      | ?      | ?      | ?         | ?         | ?       | ?   | ?
+Platform: iOS                  | ?      | ?      | ?      | ?      | ?      | ?         | ?         | ?       | ?   | ?
+Engine: Unity                  | ?      | ?      | Yes    | ?      | ?      | ?         | ?         | ?       | ?   | ?
+Primary authors (github)       | gwvo   | gwvo   | ev*/js*| rw     | rw     | evanw/ev* | kr        | mik*    | ch* | rw

  * ev = evolutional
  * js = jonsimantov
  * mik = mikkelfj
  * ch = chobie
+  * kr = krojew

 <br>
--- a/docs/source/Tutorial.md
+++ b/docs/source/Tutorial.md
@@ -27,6 +27,7 @@ Please select your desired language for our quest:
  <input type="radio" name="language" value="go">Go</input>
  <input type="radio" name="language" value="python">Python</input>
  <input type="radio" name="language" value="javascript">JavaScript</input>
+  <input type="radio" name="language" value="typescript">TypeScript</input>
  <input type="radio" name="language" value="php">PHP</input>
  <input type="radio" name="language" value="c">C</input>
 </form>
@@ -122,6 +123,9 @@ For your chosen language, please cross-reference with:
 <div class="language-javascript">
 [samplebinary.js](https://github.com/google/flatbuffers/blob/master/samples/samplebinary.js)
 </div>
+<div class="language-typescript">
+<em>none yet</em>
+</div>
 <div class="language-php">
 [SampleBinary.php](https://github.com/google/flatbuffers/blob/master/samples/SampleBinary.php)
 </div>
@@ -284,7 +288,13 @@ Please be aware of the difference between `flatc` and `flatcc` tools.
 <div class="language-javascript">
 ~~~{.sh}
  cd flatbuffers/sample
-  ./../flatc --javascript samples/monster.fbs
+  ./../flatc --js samples/monster.fbs
+~~~
+</div>
+<div class="language-typescript">
+~~~{.sh}
+  cd flatbuffers/sample
+  ./../flatc --ts samples/monster.fbs
 ~~~
 </div>
 <div class="language-php">
@@ -372,6 +382,11 @@ The first step is to import/include the library, generated files, etc.
  <script src="monster_generated.js"></script> // Generated by `flatc`.
 ~~~
 </div>
+<div class="language-typescript">
+  // note: import flabuffers with your desired import method
+
+  import { MyGame } from './monster_generated';
+</div>
 <div class="language-php">
 ~~~{.php}
  // It is recommended that your use PSR autoload when using FlatBuffers in PHP.
@@ -454,6 +469,13 @@ which will grow automatically if needed:
  var builder = new flatbuffers.Builder(1024);
 ~~~
 </div>
+<div class="language-typescript">
+~~~{.ts}
+  // Create a `flatbuffer.Builder`, which will be used to create our
+  // monsters' FlatBuffers.
+  let builder = new flatbuffers.Builder(1024);
+~~~
+</div>
 <div class="language-php">
 ~~~{.php}
  // Create a `FlatBufferBuilder`, which will be used to create our
@@ -566,6 +588,24 @@ our `orc` Monster, lets create some `Weapon`s: a `Sword` and an `Axe`.
  var axe = MyGame.Sample.Weapon.endWeapon(builder);
 ~~~
 </div>
+<div class="language-typescript">
+~~~{.js}
+  let weaponOne = builder.createString('Sword');
+  let weaponTwo = builder.createString('Axe');
+
+  // Create the first `Weapon` ('Sword').
+  MyGame.Sample.Weapon.startWeapon(builder);
+  MyGame.Sample.Weapon.addName(builder, weaponOne);
+  MyGame.Sample.Weapon.addDamage(builder, 3);
+  let sword = MyGame.Sample.Weapon.endWeapon(builder);
+
+  // Create the second `Weapon` ('Axe').
+  MyGame.Sample.Weapon.startWeapon(builder);
+  MyGame.Sample.Weapon.addName(builder, weaponTwo);
+  MyGame.Sample.Weapon.addDamage(builder, 5);
+  let axe = MyGame.Sample.Weapon.endWeapon(builder);
+~~~
+</div>
 <div class="language-php">
 ~~~{.php}
  // Create the `Weapon`s using the `createWeapon()` helper function.
@@ -684,6 +724,17 @@ traversal. This is generally easy to do on any tree structures.
  var inv = MyGame.Sample.Monster.createInventoryVector(builder, treasure);
 ~~~
 </div>
+<div class="language-typescript">
+~~~{.js}
+  // Serialize a name for our monster, called 'Orc'.
+  let name = builder.createString('Orc');
+
+  // Create a `vector` representing the inventory of the Orc. Each number
+  // could correspond to an item that can be claimed after he is slain.
+  let treasure = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+  let inv = MyGame.Sample.Monster.createInventoryVector(builder, treasure);
+~~~
+</div>
 <div class="language-php">
 ~~~{.php}
  // Serialize a name for our monster, called "Orc".
@@ -787,6 +838,14 @@ offsets.
  var weapons = MyGame.Sample.Monster.createWeaponsVector(builder, weaps);
 ~~~
 </div>
+<div class="language-typescript">
+~~~{.ts}
+  // Create an array from the two `Weapon`s and pass it to the
+  // `createWeaponsVector()` method to create a FlatBuffer vector.
+  let weaps = [sword, axe];
+  let weapons = MyGame.Sample.Monster.createWeaponsVector(builder, weaps);
+~~~
+</div>
 <div class="language-php">
 ~~~{.php}
  // Create an array from the two `Weapon`s and pass it to the
@@ -863,6 +922,14 @@ for the `path` field above:
  var path = builder.endVector();
 ~~~
 </div>
+<div class="language-typescript">
+~~~{.ts}
+  MyGame.Sample.Monster.startPathVector(builder, 2);
+  MyGame.Sample.Vec3.createVec3(builder, 1.0, 2.0, 3.0);
+  MyGame.Sample.Vec3.createVec3(builder, 4.0, 5.0, 6.0);
+  let path = builder.endVector();
+~~~
+</div>
 <div class="language-php">
 ~~~{.php}
  \MyGame\Example\Monster::StartPathVector($builder, 2);
@@ -977,6 +1044,23 @@ can serialize the monster itself:
  var orc = MyGame.Sample.Monster.endMonster(builder);
 ~~~
 </div>
+<div class="language-typescript">
+~~~{.ts}
+  // Create our monster by using `startMonster()` and `endMonster()`.
+  MyGame.Sample.Monster.startMonster(builder);
+  MyGame.Sample.Monster.addPos(builder,
+                         MyGame.Sample.Vec3.createVec3(builder, 1.0, 2.0, 3.0));
+  MyGame.Sample.Monster.addHp(builder, 300);
+  MyGame.Sample.Monster.addColor(builder, MyGame.Sample.Color.Red)
+  MyGame.Sample.Monster.addName(builder, name);
+  MyGame.Sample.Monster.addInventory(builder, inv);
+  MyGame.Sample.Monster.addWeapons(builder, weapons);
+  MyGame.Sample.Monster.addEquippedType(builder, MyGame.Sample.Equipment.Weapon);
+  MyGame.Sample.Monster.addEquipped(builder, axe);
+  MyGame.Sample.Monster.addPath(builder, path);
+  let orc = MyGame.Sample.Monster.endMonster(builder);
+~~~
+</div>
 <div class="language-php">
 ~~~{.php}
  // Create our monster by using `StartMonster()` and `EndMonster()`.
@@ -1122,6 +1206,12 @@ Here is a repetition these lines, to help highlight them more clearly:
    MyGame.Sample.Monster.addEquipped(builder, axe); // Union data
  ~~~
 </div>
+<div class="language-typescript">
+  ~~~{.ts}
+    MyGame.Sample.Monster.addEquippedType(builder, MyGame.Sample.Equipment.Weapon); // Union type
+    MyGame.Sample.Monster.addEquipped(builder, axe); // Union data
+  ~~~
+</div>
 <div class="language-php">
  ~~~{.php}
    \MyGame\Sample\Monster::AddEquippedType($builder, \MyGame\Sample\Equipment::Weapon); // Union type
@@ -1180,6 +1270,13 @@ appropriate `finish` method.
                       //                                                                 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);`.
+~~~
+</div>
 <div class="language-php">
 ~~~{.php}
  // Call `finish()` to instruct the builder that this monster is complete.
@@ -1246,6 +1343,12 @@ like so:
  var buf = builder.asUint8Array(); // Of type `Uint8Array`.
 ~~~
 </div>
+<div class="language-typescript">
+~~~{.ts}
+  // This must be called after `finish()`.
+  let buf = builder.asUint8Array(); // Of type `Uint8Array`.
+~~~
+</div>
 <div class="language-php">
 ~~~{.php}
  // This must be called after `finish()`.
@@ -1347,6 +1450,13 @@ before:
  <script src="monster_generated.js"></script> // Generated by `flatc`.
 ~~~
 </div>
+<div class="language-typescript">
+~~~{.js}
+  // note: import flabuffers with your desired import method
+
+  import { MyGame } from './monster_generated';
+~~~
+</div>
 <div class="language-php">
 ~~~{.php}
  // It is recommended that your use PSR autoload when using FlatBuffers in PHP.
@@ -1451,6 +1561,15 @@ won't work**
  var monster = MyGame.Sample.Monster.getRootAsMonster(buf);
 ~~~
 </div>
+<div class="language-typescript">
+~~~{.ts}
+  let bytes = /* the data you just read, in an object of type "Uint8Array" */
+  let buf = new flatbuffers.ByteBuffer(bytes);
+
+  // Get an accessor to the root object inside the buffer.
+  let monster = MyGame.Sample.Monster.getRootAsMonster(buf);
+~~~
+</div>
 <div class="language-php">
 ~~~{.php}
  $bytes = /* the data you just read, in a string */
@@ -1518,6 +1637,13 @@ accessors for all non-`deprecated` fields. For example:
  var name = $monster.name();
 ~~~
 </div>
+<div class="language-typescript">
+~~~{.ts}
+  let hp = $monster.hp();
+  let mana = $monster.mana();
+  let name = $monster.name();
+~~~
+</div>
 <div class="language-php">
 ~~~{.php}
  $hp = $monster->getHp();
@@ -1593,6 +1719,14 @@ To access sub-objects, in the case of our `pos`, which is a `Vec3`:
  var z = pos.z();
 ~~~
 </div>
+<div class="language-typescript">
+~~~{.ts}
+  let pos = monster.pos();
+  let x = pos.x();
+  let y = pos.y();
+  let z = pos.z();
+~~~
+</div>
 <div class="language-php">
 ~~~{.php}
  $pos = $monster->getPos();
@@ -1655,6 +1789,12 @@ FlatBuffers `vector`.
  var thirdItem = monster.inventory(2);
 ~~~
 </div>
+<div class="language-typescript">
+~~~{.ts}
+  let invLength = monster.inventoryLength();
+  let thirdItem = monster.inventory(2);
+~~~
+</div>
 <div class="language-php">
 ~~~{.php}
  $inv_len = $monster->getInventoryLength();
@@ -1720,6 +1860,13 @@ except your need to handle the result as a FlatBuffer `table`:
  var secondWeaponDamage = monster.weapons(1).damage();
 ~~~
 </div>
+<div class="language-typescript">
+~~~{.ts}
+  let weaponsLength = monster.weaponsLength();
+  let secondWeaponName = monster.weapons(1).name();
+  let secondWeaponDamage = monster.weapons(1).damage();
+~~~
+</div>
 <div class="language-php">
 ~~~{.php}
  $weapons_len = $monster->getWeaponsLength();
@@ -1827,6 +1974,16 @@ We can access the type to dynamically cast the data as needed (since the
  }
 ~~~
 </div>
+<div class="language-typescript">
+~~~{.ts}
+  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
+  }
+~~~
+</div>
 <div class="language-php">
 ~~~{.php}
  $union_type = $monster->getEquippedType();
@@ -1905,7 +2062,12 @@ mutators like so:
 </div>
 <div class="language-javascript">
 ~~~{.js}
-  <API for mutating FlatBuffers is not yet support in JavaScript.>
+  <API for mutating FlatBuffers is not yet supported in JavaScript.>
+~~~
+</div>
+<div class="language-typescript">
+~~~{.ts}
+  <API for mutating FlatBuffers is not yet supported in TypeScript.>
 ~~~
 </div>
 <div class="language-php">
@@ -2019,6 +2181,9 @@ For your chosen language, see:
 <div class="language-javascript">
 [Use in JavaScript](@ref flatbuffers_guide_use_javascript)
 </div>
+<div class="language-typescript">
+[Use in TypeScript](@ref flatbuffers_guide_use_typescript)
+</div>
 <div class="language-php">
 [Use in PHP](@ref flatbuffers_guide_use_php)
 </div>
--- a/docs/source/TypeScriptUsage.md
+++ b/docs/source/TypeScriptUsage.md
@@ -0,0 +1,66 @@
+Use in TypeScript    {#flatbuffers_guide_use_typescript}
+=================
+
+## Before you get started
+
+Before diving into the FlatBuffers usage in TypeScript, it should be noted that
+the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to
+general FlatBuffers usage in all of the supported languages
+(including TypeScript). This page is specifically designed to cover the nuances
+of FlatBuffers usage in TypeScript.
+
+You should also have read the [Building](@ref flatbuffers_guide_building)
+documentation to build `flatc` and should be familiar with
+[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
+[Writing a schema](@ref flatbuffers_guide_writing_schema).
+
+## FlatBuffers TypeScript library code location
+
+The code for the FlatBuffers TypeScript library can be found at
+`flatbuffers/js` with typings available at @types/flatubffers.
+
+## Testing the FlatBuffers TypeScript library
+
+To run the tests, use the [TypeScriptTest.sh](https://github.com/google/
+flatbuffers/blob/master/tests/TypeScriptTest.sh) shell script.
+
+*Note: The TypeScript test file requires [Node.js](https://nodejs.org/en/).*
+
+## Using the FlatBuffers TypeScript libary
+
+*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
+example of how to use FlatBuffers in TypeScript.*
+
+FlatBuffers supports both reading and writing FlatBuffers in TypeScript.
+
+To use FlatBuffers in your own code, first generate TypeScript classes from your
+schema with the `--ts` option to `flatc`. Then you can include both FlatBuffers
+and the generated code to read or write a FlatBuffer.
+
+For example, here is how you would read a FlatBuffer binary file in TypeScript:
+First, include the library and generated code. Then read the file into an
+`Uint8Array`. Make a `flatbuffers.ByteBuffer` out of the `Uint8Array`, and pass
+the ByteBuffer to the `getRootAsMonster` function.
+
+~~~{.ts}
+  // note: import flabuffers with your desired import method
+
+  import { MyGame } from './monster_generated';
+
+  let data = new Uint8Array(fs.readFileSync('monster.dat'));
+  let buf = new flatbuffers.ByteBuffer(data);
+
+  let monster = MyGame.Example.Monster.getRootAsMonster(buf);
+~~~
+
+Now you can access values like this:
+
+~~~{.ts}
+  let hp = monster.hp();
+  let pos = monster.pos();
+~~~
+
+## Text parsing FlatBuffers in TypeScript
+
+There currently is no support for parsing text (Schema's and JSON) directly
+from TypeScript.
--- a/docs/source/groups
+++ b/docs/source/groups
@@ -13,6 +13,9 @@
 /// @defgroup flatbuffers_javascript_api JavaScript API
 /// @brief FlatBuffers API for JavaScript

+/// @defgroup flatbuffers_typescript_api TypeScript API
+/// @brief FlatBuffers API for TypeScript
+
 /// @defgroup flatbuffers_php_api PHP API
 /// @brief FlatBuffers API for PHP