From cc54963830c4a30eef6ea3c366d478c643cb71d7 Mon Sep 17 00:00:00 2001 From: Kamil Rojewski Date: Fri, 23 Mar 2018 17:01:39 +0100 Subject: [PATCH] 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 --- docs/source/FlatBuffers.md | 2 +- docs/source/Support.md | 35 +++---- docs/source/Tutorial.md | 169 ++++++++++++++++++++++++++++++++- docs/source/TypeScriptUsage.md | 66 +++++++++++++ docs/source/groups | 3 + 5 files changed, 255 insertions(+), 20 deletions(-) create mode 100644 docs/source/TypeScriptUsage.md diff --git a/docs/source/FlatBuffers.md b/docs/source/FlatBuffers.md index d228bd402..b1239b00d 100644 --- 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. diff --git a/docs/source/Support.md b/docs/source/Support.md index 9833ccdb2..e1fc56334 100644 --- 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
diff --git a/docs/source/Tutorial.md b/docs/source/Tutorial.md index daa8ee1d1..cecfb5a99 100644 --- a/docs/source/Tutorial.md +++ b/docs/source/Tutorial.md @@ -27,6 +27,7 @@ Please select your desired language for our quest: Go Python JavaScript + TypeScript PHP C @@ -122,6 +123,9 @@ For your chosen language, please cross-reference with:
[samplebinary.js](https://github.com/google/flatbuffers/blob/master/samples/samplebinary.js)
+
+none yet +
[SampleBinary.php](https://github.com/google/flatbuffers/blob/master/samples/SampleBinary.php)
@@ -284,7 +288,13 @@ Please be aware of the difference between `flatc` and `flatcc` tools.
~~~{.sh} cd flatbuffers/sample - ./../flatc --javascript samples/monster.fbs + ./../flatc --js samples/monster.fbs +~~~ +
+
+~~~{.sh} + cd flatbuffers/sample + ./../flatc --ts samples/monster.fbs ~~~
@@ -372,6 +382,11 @@ The first step is to import/include the library, generated files, etc. // Generated by `flatc`. ~~~
+
+ // note: import flabuffers with your desired import method + + import { MyGame } from './monster_generated'; +
~~~{.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); ~~~
+
+~~~{.ts} + // Create a `flatbuffer.Builder`, which will be used to create our + // monsters' FlatBuffers. + let builder = new flatbuffers.Builder(1024); +~~~ +
~~~{.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); ~~~
+
+~~~{.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); +~~~ +
~~~{.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); ~~~
+
+~~~{.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); +~~~ +
~~~{.php} // Serialize a name for our monster, called "Orc". @@ -787,6 +838,14 @@ offsets. var weapons = MyGame.Sample.Monster.createWeaponsVector(builder, weaps); ~~~
+
+~~~{.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); +~~~ +
~~~{.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(); ~~~
+
+~~~{.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(); +~~~ +
~~~{.php} \MyGame\Example\Monster::StartPathVector($builder, 2); @@ -977,6 +1044,23 @@ can serialize the monster itself: var orc = MyGame.Sample.Monster.endMonster(builder); ~~~
+
+~~~{.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); +~~~ +
~~~{.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 ~~~
+
+ ~~~{.ts} + MyGame.Sample.Monster.addEquippedType(builder, MyGame.Sample.Equipment.Weapon); // Union type + MyGame.Sample.Monster.addEquipped(builder, axe); // Union data + ~~~ +
~~~{.php} \MyGame\Sample\Monster::AddEquippedType($builder, \MyGame\Sample\Equipment::Weapon); // Union type @@ -1180,6 +1270,13 @@ appropriate `finish` method. // orc);`. ~~~
+
+~~~{.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);`. +~~~ +
~~~{.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`. ~~~
+
+~~~{.ts} + // This must be called after `finish()`. + let buf = builder.asUint8Array(); // Of type `Uint8Array`. +~~~ +
~~~{.php} // This must be called after `finish()`. @@ -1347,6 +1450,13 @@ before: // Generated by `flatc`. ~~~
+
+~~~{.js} + // note: import flabuffers with your desired import method + + import { MyGame } from './monster_generated'; +~~~ +
~~~{.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); ~~~
+
+~~~{.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); +~~~ +
~~~{.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(); ~~~
+
+~~~{.ts} + let hp = $monster.hp(); + let mana = $monster.mana(); + let name = $monster.name(); +~~~ +
~~~{.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(); ~~~
+
+~~~{.ts} + let pos = monster.pos(); + let x = pos.x(); + let y = pos.y(); + let z = pos.z(); +~~~ +
~~~{.php} $pos = $monster->getPos(); @@ -1655,6 +1789,12 @@ FlatBuffers `vector`. var thirdItem = monster.inventory(2); ~~~
+
+~~~{.ts} + let invLength = monster.inventoryLength(); + let thirdItem = monster.inventory(2); +~~~ +
~~~{.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(); ~~~
+
+~~~{.ts} + let weaponsLength = monster.weaponsLength(); + let secondWeaponName = monster.weapons(1).name(); + let secondWeaponDamage = monster.weapons(1).damage(); +~~~ +
~~~{.php} $weapons_len = $monster->getWeaponsLength(); @@ -1827,6 +1974,16 @@ We can access the type to dynamically cast the data as needed (since the } ~~~
+
+~~~{.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 + } +~~~ +
~~~{.php} $union_type = $monster->getEquippedType(); @@ -1905,7 +2062,12 @@ mutators like so:
~~~{.js} - + +~~~ +
+
+~~~{.ts} + ~~~
@@ -2019,6 +2181,9 @@ For your chosen language, see:
[Use in JavaScript](@ref flatbuffers_guide_use_javascript)
+
+[Use in TypeScript](@ref flatbuffers_guide_use_typescript) +
[Use in PHP](@ref flatbuffers_guide_use_php)
diff --git a/docs/source/TypeScriptUsage.md b/docs/source/TypeScriptUsage.md new file mode 100644 index 000000000..b773fdfd7 --- /dev/null +++ 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. diff --git a/docs/source/groups b/docs/source/groups index e0d97a7ac..c3aea18ec 100644 --- 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