Skip to content

F
flatbuffers
Commit cc549638 authored by Kamil Rojewski's avatar Kamil Rojewski Committed by Wouter van Oortmerssen
Browse files
Options

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
parent 79f62ee3
Hide whitespace changes
Inline Side-by-side
Showing with 255 additions and 20 deletions
docs/source/FlatBuffers.md
View file @ cc549638
......@@ -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.
......
docs/source/Support.md
View file @ cc549638
......@@ -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>
docs/source/Tutorial.md
View file @ cc549638
......@@ -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>
......
docs/source/TypeScriptUsage.md 0 → 100644
View file @ cc549638
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.
docs/source/groups
View file @ cc549638
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment