GitHub/flatbuffers
1
0
Fork 0
mirror of https://github.com/google/flatbuffers.git synced 2025-04-08 09:12:14 +08:00
Code Issues Packages Projects Releases Wiki Activity

updated JS docs to reflect current status (#6436)

Browse Source
This commit is contained in:
Kamil Rojewski 2021-02-19 21:05:02 +01:00 committed by GitHub
parent 0c7ae58164
commit e6b911d40c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 25 additions and 143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
docs/source/JavaScriptUsage.md
View File

@ -16,43 +16,31 @@ documentation to build `flatc` and should be familiar with
## FlatBuffers JavaScript library code location
The code for the FlatBuffers JavaScript library can be found at
`flatbuffers/js`. You can browse the library code on the [FlatBuffers
GitHub page](https://github.com/google/flatbuffers/tree/master/js).
The generated code for the FlatBuffers JavaScript library can be found at
https://www.npmjs.com/package/flatbuffers. To use it from sources:
## Testing the FlatBuffers JavaScript library
The code to test the JavaScript library can be found at `flatbuffers/tests`.
The test code itself is located in [JavaScriptTest.js](https://github.com/
google/flatbuffers/blob/master/tests/JavaScriptTest.js).
To run the tests, use the [JavaScriptTest.sh](https://github.com/google/
flatbuffers/blob/master/tests/JavaScriptTest.sh) shell script.
*Note: The JavaScript test file requires [Node.js](https://nodejs.org/en/).*
1. Run `npm run compile` from the main folder to generate JS files from TS.
1. In your project, install it as a normal dependency, using the flatbuffers
folder as the source.
## Using the FlatBuffers JavaScript libary
*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
example of how to use FlatBuffers in JavaScript.*
example of how to use FlatBuffers.*
FlatBuffers supports both reading and writing FlatBuffers in JavaScript.
Due to the complexity related with large amounts of JS flavors and module types,
native JS support has been replaced in 2.0 by transpilation from TypeScript.
To use FlatBuffers in your own code, first generate JavaScript classes from your
schema with the `--js` option to `flatc`. Then you can include both FlatBuffers
and the generated code to read or write a FlatBuffer.
Please look at [TypeScript usage](@ref flatbuffers_guide_use_typescript) and
transpile your sources to desired JS flavor. The minimal steps to get up and
running with JS are:
For example, here is how you would read a FlatBuffer binary file in Javascript:
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.
*Note: Both JavaScript module loaders (e.g. Node.js) and browser-based
HTML/JavaScript code segments are shown below in the following snippet:*
1. Generate TS files from `*.fbs` by using the `--ts` option.
1. Transpile resulting TS files to desired JS flavor using `tsc` (see
https://www.typescriptlang.org/download for installation instructions).
~~~{.js}
// Note: These require functions are specific to JavaScript module loaders
// (namely, Node.js). See below for a browser-based example.
// Note: These require functions are an example - use your desired module flavor.
var fs = require('fs');
var flatbuffers = require('../flatbuffers').flatbuffers;
@ -65,7 +53,7 @@ HTML/JavaScript code segments are shown below in the following snippet:*
//--------------------------------------------------------------------------//
// Note: This code is specific to browser-based HTML/JavaScript. See above
// Note: This code is an example of browser-based HTML/JavaScript. See above
// for the code using JavaScript module loaders (e.g. Node.js).
<script src="../js/flatbuffers.js"></script>
<script src="monster_generated.js"></script>

14
docs/source/Tutorial.md
View File

@ -130,7 +130,7 @@ For your chosen language, please cross-reference with:
[sample_binary.py](https://github.com/google/flatbuffers/blob/master/samples/sample_binary.py)
</div>
<div class="language-javascript">
[samplebinary.js](https://github.com/google/flatbuffers/blob/master/samples/samplebinary.js)
No sample binary is provided, since JS needs to be transpiled from TypeScript. Please see TypeScript support.
</div>
<div class="language-typescript">
<em>none yet</em>
@ -321,7 +321,9 @@ Please be aware of the difference between `flatc` and `flatcc` tools.
<div class="language-javascript">
~~~{.sh}
cd flatbuffers/samples
./../flatc --js monster.fbs
./../flatc --ts monster.fbs
# customize your TS -> JS transpilation
tsc monster_generated.ts
~~~
</div>
<div class="language-typescript">
@ -439,8 +441,7 @@ The first step is to import/include the library, generated files, etc.
</div>
<div class="language-javascript">
~~~{.js}
// The following code is for JavaScript module loaders (e.g. Node.js). See
// below for a browser-based HTML/JavaScript example of including the library.
// The following code is an example - use your desired module flavor by transpiling from TS.
var flatbuffers = require('/js/flatbuffers').flatbuffers;
var MyGame = require('./monster_generated').MyGame; // Generated by `flatc`.
@ -2224,14 +2225,13 @@ before:
</div>
<div class="language-javascript">
~~~{.js}
// The following code is for JavaScript module loaders (e.g. Node.js). See
// below for a browser-based HTML/JavaScript example of including the library.
// The following code is an example - use your desired module flavor by transpiling from TS.
var flatbuffers = require('/js/flatbuffers').flatbuffers;
var MyGame = require('./monster_generated').MyGame; // Generated by `flatc`.
//--------------------------------------------------------------------------//
// The following code is for browser-based HTML/JavaScript. Use the above code
// The following code an example for browser-based HTML/JavaScript. Use the above code
// for JavaScript module loaders (e.g. Node.js).
<script src="../js/flatbuffers.js"></script>
<script src="monster_generated.js"></script> // Generated by `flatc`.

4
docs/source/TypeScriptUsage.md
View File

@ -17,7 +17,7 @@ documentation to build `flatc` and should be familiar with
## FlatBuffers TypeScript library code location
The code for the FlatBuffers TypeScript library can be found at
`flatbuffers/js` with typings available at `@types/flatbuffers`.
https://www.npmjs.com/package/flatbuffers.
## Testing the FlatBuffers TypeScript library
@ -43,7 +43,7 @@ First, include the library and generated code. Then read the file into an
the ByteBuffer to the `getRootAsMonster` function.
~~~{.ts}
// note: import flatbuffers with your desired import method
import * as flatbuffers from 'flatbuffers';
import { MyGame } from './monster_generated';

106
samples/samplebinary.js
View File

@ -1,106 +0,0 @@
/*
* Copyright 2015 Google Inc. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
// To run, use the `javascript_sample.sh` script.
var assert = require('assert');
var flatbuffers = require('../js/flatbuffers').flatbuffers;
var MyGame = require('./monster_generated').MyGame;
// Example how to use FlatBuffers to create and read binary buffers.
function main() {
var builder = new flatbuffers.Builder(0);
// Create some weapons for our Monster ('Sword' and 'Axe').
var weaponOne = builder.createString('Sword');
var weaponTwo = builder.createString('Axe');
MyGame.Sample.Weapon.startWeapon(builder);
MyGame.Sample.Weapon.addName(builder, weaponOne);
MyGame.Sample.Weapon.addDamage(builder, 3);
var sword = MyGame.Sample.Weapon.endWeapon(builder);
MyGame.Sample.Weapon.startWeapon(builder);
MyGame.Sample.Weapon.addName(builder, weaponTwo);
MyGame.Sample.Weapon.addDamage(builder, 5);
var axe = MyGame.Sample.Weapon.endWeapon(builder);
// Serialize the FlatBuffer data.
var name = builder.createString('Orc');
var treasure = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
var inv = MyGame.Sample.Monster.createInventoryVector(builder, treasure);
var weaps = [sword, axe];
var weapons = MyGame.Sample.Monster.createWeaponsVector(builder, weaps);
var pos = MyGame.Sample.Vec3.createVec3(builder, 1.0, 2.0, 3.0);
MyGame.Sample.Monster.startMonster(builder);
MyGame.Sample.Monster.addPos(builder, pos);
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, weaps[1]);
var orc = MyGame.Sample.Monster.endMonster(builder);
builder.finish(orc); // You may also call 'MyGame.Example.Monster.finishMonsterBuffer(builder, orc);'.
// We now have a FlatBuffer that can be stored on disk or sent over a network.
// ...Code to store to disk or send over a network goes here...
// Instead, we are going to access it right away, as if we just received it.
var buf = builder.dataBuffer();
// Get access to the root:
var monster = MyGame.Sample.Monster.getRootAsMonster(buf);
// Note: We did not set the `mana` field explicitly, so we get back the default value.
assert.equal(monster.mana(), 150);
assert.equal(monster.hp(), 300);
assert.equal(monster.name(), 'Orc');
assert.equal(monster.color(), MyGame.Sample.Color.Red);
assert.equal(monster.pos().x(), 1.0);
assert.equal(monster.pos().y(), 2.0);
assert.equal(monster.pos().z(), 3.0);
// Get and test the `inventory` FlatBuffer `vector`.
for (var i = 0; i < monster.inventoryLength(); i++) {
assert.equal(monster.inventory(i), i);
}
// Get and test the `weapons` FlatBuffer `vector` of `table`s.
var expectedWeaponNames = ['Sword', 'Axe'];
var expectedWeaponDamages = [3, 5];
for (var i = 0; i < monster.weaponsLength(); i++) {
assert.equal(monster.weapons(i).name(), expectedWeaponNames[i]);
assert.equal(monster.weapons(i).damage(), expectedWeaponDamages[i]);
}
// Get and test the `equipped` FlatBuffer `union`.
assert.equal(monster.equippedType(), MyGame.Sample.Equipment.Weapon);
assert.equal(monster.equipped(new MyGame.Sample.Weapon()).name(), 'Axe');
assert.equal(monster.equipped(new MyGame.Sample.Weapon()).damage(), 5);
console.log('The FlatBuffer was successfully created and verified!');
}
main();