updated JS docs to reflect current status (#6436)
authorKamil Rojewski <kamil.rojewski@gmail.com>
Fri, 19 Feb 2021 20:05:02 +0000 (21:05 +0100)
committerGitHub <noreply@github.com>
Fri, 19 Feb 2021 20:05:02 +0000 (12:05 -0800)
docs/source/JavaScriptUsage.md
docs/source/Tutorial.md
docs/source/TypeScriptUsage.md
samples/samplebinary.js [deleted file]

index c321c95..2f0d379 100644 (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.*
-
-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).
   <script src="../js/flatbuffers.js"></script>
   <script src="monster_generated.js"></script>
index 181c677..041e1d9 100644 (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`.
index 59fbbf6..437b49d 100644 (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';
 
diff --git a/samples/samplebinary.js b/samples/samplebinary.js
deleted file mode 100644 (file)
index 9c8c908..0000000
+++ /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();