From: Kamil Rojewski Date: Fri, 19 Feb 2021 20:05:02 +0000 (+0100) Subject: updated JS docs to reflect current status (#6436) X-Git-Tag: v2.0.0~72 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=e6b911d40cc1d480e103ea89573e4f16c4b5f741;p=platform%2Fupstream%2Fflatbuffers.git updated JS docs to reflect current status (#6436) --- diff --git a/docs/source/JavaScriptUsage.md b/docs/source/JavaScriptUsage.md index c321c95..2f0d379 100644 --- a/docs/source/JavaScriptUsage.md +++ b/docs/source/JavaScriptUsage.md @@ -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.* - -FlatBuffers supports both reading and writing FlatBuffers in JavaScript. +example of how to use FlatBuffers.* -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. +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. -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. +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: -*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). diff --git a/docs/source/Tutorial.md b/docs/source/Tutorial.md index 181c677..041e1d9 100644 --- a/docs/source/Tutorial.md +++ b/docs/source/Tutorial.md @@ -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)
-[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.
none yet @@ -321,7 +321,9 @@ Please be aware of the difference between `flatc` and `flatcc` tools.
~~~{.sh} cd flatbuffers/samples - ./../flatc --js monster.fbs + ./../flatc --ts monster.fbs + # customize your TS -> JS transpilation + tsc monster_generated.ts ~~~
@@ -439,8 +441,7 @@ The first step is to import/include the library, generated files, etc.
~~~{.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:
~~~{.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). // Generated by `flatc`. diff --git a/docs/source/TypeScriptUsage.md b/docs/source/TypeScriptUsage.md index 59fbbf6..437b49d 100644 --- a/docs/source/TypeScriptUsage.md +++ b/docs/source/TypeScriptUsage.md @@ -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'; diff --git a/samples/samplebinary.js b/samples/samplebinary.js deleted file mode 100644 index 9c8c908..0000000 --- a/samples/samplebinary.js +++ /dev/null @@ -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();