mojo/public/js/README.md - platform/external/libchrome - Git at Google

 # Mojo JavaScript Bindings API
 This document is a subset of the [Mojo documentation](/mojo/README.md).

 [TOC]

 ## Getting Started
 The bindings API is defined in the `mojo` namespace and implemented in
 `mojo_bindings.js`, which could be generated by the GN target
 `//mojo/public/js:bindings`.

 When a Mojom IDL file is processed by the bindings generator, JavaScript code is
 emitted in a `.js` file with the name based on the input `.mojom` file. Suppose
 we create the following Mojom file at
 `//services/echo/public/interfaces/echo.mojom`:

 ```
 module test.echo.mojom;

 interface Echo {
   EchoInteger(int32 value) => (int32 result);
 };
 ```

 And a GN target to generate the bindings in
 `//services/echo/public/interfaces/BUILD.gn`:

 ```
 import("//mojo/public/tools/bindings/mojom.gni")

 mojom("interfaces") {
   sources = [
     "echo.mojom",
   ]
 }
 ```

 Bindings are generated by building one of these implicitly generated targets
 (where "foo" is the target name):
 * `foo_js` JavaScript bindings; used as compile-time dependency.
 * `foo_js_data_deps` JavaScript bindings; used as run-time dependency.

 If we then build this target:
 ```
 ninja -C out/r services/echo/public/interfaces:interfaces_js
 ```

 This will produce several generated source files. The one relevant to JavaScript
 bindings is:
 ```
 out/gen/services/echo/public/interfaces/echo.mojom.js
 ```

 In order to use the definitions in `echo.mojom`, you will need to include two
 files in your html page using `<script>` tags:
 * `mojo_bindings.js`
   __Note: This file must be included before any `.mojom.js` files.__
 * `echo.mojom.js`

 ``` html
 <!DOCTYPE html>
 <script src="URL/to/mojo_bindings.js"></script>
 <script src="URL/to/echo.mojom.js"></script>
 <script>

 var echoPtr = new test.echo.mojom.EchoPtr();
 var echoRequest = mojo.makeRequest(echoPtr);
 // ...

 </script>
 ```

 ## Interfaces
 Similar to the C++ bindings API, we have:
 * `mojo.InterfacePtrInfo` and `mojo.InterfaceRequest` encapsulate two ends of a
   message pipe. They represent the client end and service end of an interface
   connection, respectively.
 * For each Mojom interface `Foo`, there is a generated `FooPtr` class. It owns
   an `InterfacePtrInfo`; provides methods to send interface calls using the
   message pipe handle from the `InterfacePtrInfo`.
 * `mojo.Binding` owns an `InterfaceRequest`. It listens on the message pipe
   handle and dispatches incoming messages to a user-defined interface
   implementation.

 Let's consider the `echo.mojom` example above. The following shows how to create
 an `Echo` interface connection and use it to make a call.

 ``` html
 <!DOCTYPE html>
 <script src="URL/to/mojo_bindings.js"></script>
 <script src="URL/to/echo.mojom.js"></script>
 <script>

 function EchoImpl() {}
 EchoImpl.prototype.echoInteger = function(value) {
   return Promise.resolve({result: value});
 };

 var echoServicePtr = new test.echo.mojom.EchoPtr();
 var echoServiceRequest = mojo.makeRequest(echoServicePtr);
 var echoServiceBinding = new mojo.Binding(test.echo.mojom.Echo,
                                           new EchoImpl(),
                                           echoServiceRequest);
 echoServicePtr.echoInteger({value: 123}).then(function(response) {
   console.log('The result is ' + response.value);
 });

 </script>
 ```

 ### Interface Pointers and Requests
 In the example above, `test.echo.mojom.EchoPtr` is an interface pointer class.
 `EchoPtr` represents the client end of an interface connection. For method
 `EchoInteger` in the `Echo` Mojom interface, there is a corresponding
 `echoInteger` method defined in `EchoPtr`. (Please note that the format of the
 generated method name is `camelCaseWithLowerInitial`.)

 There are some control methods shared by all interface pointer classes. For
 example, binding/extracting `InterfacePtrInfo`, setting connection error
 handler, querying version information, etc. In order to avoid name collision,
 they are defined in `mojo.InterfacePtrController` and exposed as the `ptr` field
 of every interface pointer class.

 In the example above, `echoServiceRequest` is an `InterfaceRequest` instance. It
 represents the service end of an interface connection.

 `mojo.makeRequest` creates a message pipe; populates the output argument (which
 could be an `InterfacePtrInfo` or an interface pointer) with one end of the
 pipe; returns the other end wrapped in an `InterfaceRequest` instance.

 ### Binding an InterfaceRequest
 A `mojo.Binding` bridges an implementation of an interface and a message pipe
 endpoint, dispatching incoming messages to the implementation.

 In the example above, `echoServiceBinding` listens for incoming `EchoInteger`
 method calls on the messsage pipe, and dispatches those calls to the `EchoImpl`
 instance.

 ### Receiving Responses
 Some Mojom interface methods expect a response, such as `EchoInteger`. The
 corresponding JavaScript method returns a Promise. This Promise is resolved when
 the service side sends back a response. It is rejected if the interface is
 disconnected.

 ### Connection Errors
 If a pipe is disconnected, both endpoints will be able to observe the connection
 error (unless the disconnection is caused by closing/destroying an endpoint, in
 which case that endpoint won't get such a notification). If there are remaining
 incoming messages for an endpoint on disconnection, the connection error won't
 be triggered until the messages are drained.

 Pipe disconnecition may be caused by:
 * Mojo system-level causes: process terminated, resource exhausted, etc.
 * The bindings close the pipe due to a validation error when processing a
   received message.
 * The peer endpoint is closed. For example, the remote side is a bound interface
   pointer and it is destroyed.

 Regardless of the underlying cause, when a connection error is encountered on
 a binding endpoint, that endpoint's **connection error handler** (if set) is
 invoked. This handler may only be invoked *once* as long as the endpoint is
 bound to the same pipe. Typically clients and implementations use this handler
 to do some kind of cleanup or recovery.

 ``` js
 // Assume echoServicePtr is already bound.
 echoServicePtr.ptr.setConnectionErrorHandler(function() {
   DoImportantCleanUp();
 });

 // Assume echoServiceBinding is already bound:
 echoServiceBinding.setConnectionErrorHandler(function() {
   DoImportantCleanUpToo();
 });
 ```

 **Note:** Closing one end of a pipe will eventually trigger a connection error
 on the other end. However it's ordered with respect to any other event (*e.g.*
 writing a message) on the pipe. Therefore, it is safe to make an `echoInteger`
 call on `echoServicePtr` and reset it immediately (which results in
 disconnection), `echoServiceBinding` will receive the `echoInteger` call before
 it observes the connection error.

 ## Associated Interfaces
 An associated interface connection doesn't have its own underlying message pipe.
 It is associated with an existing message pipe (i.e., interface connection).

 Similar to the non-associated interface case, we have:
 * `mojo.AssociatedInterfacePtrInfo` and `mojo.AssociatedInterfaceRequest`
   encapsulate a *route ID*, representing a logical connection over a message
   pipe.
 * For each Mojom interface `Foo`, there is a generated `FooAssociatedPtr` class.
   It owns an `AssociatedInterfacePtrInfo`. It is the client side of an
   interface.
 * `mojo.AssociatedBinding` owns an `AssociatedInterfaceRequest`. It listens on
   the connection and dispatches incoming messages to a user-defined interface
   implementation.

 See [this document](https://www.chromium.org/developers/design-documents/mojo/associated-interfaces)
 for more details.

 ## Automatic and Manual Dependency Loading
 By default, generated `.mojom.js` files automatically load Mojom dependencies.
 For example, if `foo.mojom` imports `bar.mojom`, loading `foo.mojom.js` will
 insert a `<script>` tag to load `bar.mojom.js`, if it hasn't been loaded.

 The URL of `bar.mojom.js` is determined by:
 * the path of `bar.mojom` relative to the position of `foo.mojom` at build time;
 * the URL of `foo.mojom.js`.

 For exmple, if at build time the two Mojom files are located at:
 ```
 a/b/c/foo.mojom
 a/b/d/bar.mojom
 ```

 The URL of `foo.mojom.js` is:
 ```
 http://example.org/scripts/b/c/foo.mojom.js
 ```

 Then the URL of `bar.mojom.js` is supposed to be:
 ```
 http://example.org/scripts/b/d/bar.mojom.js
 ```

 If you would like `bar.mojom.js` to live at a different location, you need to
 set `mojo.config.autoLoadMojomDeps` to `false` before loading `foo.mojom.js`,
 and manually load `bar.mojom.js` yourself. Similarly, you need to turn off this
 option if you merge `bar.mojom.js` and `foo.mojom.js` into a single file.

 ``` html
 <!-- Automatic dependency loading -->
 <script src="http://example.org/scripts/mojo_bindings.js"></script>
 <script src="http://example.org/scripts/b/c/foo.mojom.js"></script>


 <!-- Manual dependency loading -->
 <script src="http://example.org/scripts/mojo_bindings.js"></script>
 <script>
   mojo.config.autoLoadMojomDeps = false;
 </script>
 <script src="http://example.org/scripts/b/d/bar.mojom.js"></script>
 <script src="http://example.org/scripts/b/c/foo.mojom.js"></script>
 ```

 ### Performance Tip: Avoid Loading the Same .mojom.js File Multiple Times
 If `mojo.config.autoLoadMojomDeps` is set to `true` (which is the default
 value), you might accidentally load the same `.mojom.js` file multiple times if
 you are not careful. Although it doesn't cause fatal errors, it hurts
 performance and therefore should be avoided.

 ``` html
 <!-- Assume that mojo.config.autoLoadMojomDeps is set to true: -->

 <!-- No duplicate loading; recommended. -->
 <script src="http://example.org/scripts/b/c/foo.mojom.js"></script>

 <!-- No duplicate loading, although unnecessary. -->
 <script src="http://example.org/scripts/b/d/bar.mojom.js"></script>
 <script src="http://example.org/scripts/b/c/foo.mojom.js"></script>

 <!-- Load bar.mojom.js twice; should be avoided. -->
 <!-- when foo.mojom.js is loaded, it sees that bar.mojom.js is not yet loaded,
      so it inserts another <script> tag for bar.mojom.js. -->
 <script src="http://example.org/scripts/b/c/foo.mojom.js"></script>
 <script src="http://example.org/scripts/b/d/bar.mojom.js"></script>
 ```

 If a `.mojom.js` file is loaded for a second time, a warnings will be showed
 using `console.warn()` to bring it to developers' attention.

 ## Name Formatting
 As a general rule, Mojom definitions follow the C++ formatting style. To make
 the generated JavaScript bindings conforms to our JavaScript style guide, the
 code generator does the following conversions:

 | In Mojom             | In generated .mojom.js |
 |----------------------|------------------------|
 | MethodLikeThis       | methodLikeThis
 | parameter_like_this  | parameterLikeThis
 | field_like_this      | fieldLikeThis
 | name_space.like_this | nameSpace.likeThis
	# Mojo JavaScript Bindings API
	This document is a subset of the [Mojo documentation](/mojo/README.md).

	[TOC]

	## Getting Started
	The bindings API is defined in the `mojo` namespace and implemented in
	`mojo_bindings.js`, which could be generated by the GN target
	`//mojo/public/js:bindings`.

	When a Mojom IDL file is processed by the bindings generator, JavaScript code is
	emitted in a `.js` file with the name based on the input `.mojom` file. Suppose
	we create the following Mojom file at
	`//services/echo/public/interfaces/echo.mojom`:

	```
	module test.echo.mojom;

	interface Echo {
	EchoInteger(int32 value) => (int32 result);
	};
	```

	And a GN target to generate the bindings in
	`//services/echo/public/interfaces/BUILD.gn`:

	```
	import("//mojo/public/tools/bindings/mojom.gni")

	mojom("interfaces") {
	sources = [
	"echo.mojom",
	]
	}
	```

	Bindings are generated by building one of these implicitly generated targets
	(where "foo" is the target name):
	* `foo_js` JavaScript bindings; used as compile-time dependency.
	* `foo_js_data_deps` JavaScript bindings; used as run-time dependency.

	If we then build this target:
	```
	ninja -C out/r services/echo/public/interfaces:interfaces_js
	```

	This will produce several generated source files. The one relevant to JavaScript
	bindings is:
	```
	out/gen/services/echo/public/interfaces/echo.mojom.js
	```

	In order to use the definitions in `echo.mojom`, you will need to include two
	files in your html page using `<script>` tags:
	* `mojo_bindings.js`
	__Note: This file must be included before any `.mojom.js` files.__
	* `echo.mojom.js`

	``` html
	<!DOCTYPE html>
	<script src="URL/to/mojo_bindings.js"></script>
	<script src="URL/to/echo.mojom.js"></script>
	<script>

	var echoPtr = new test.echo.mojom.EchoPtr();
	var echoRequest = mojo.makeRequest(echoPtr);
	// ...

	</script>
	```

	## Interfaces
	Similar to the C++ bindings API, we have:
	* `mojo.InterfacePtrInfo` and `mojo.InterfaceRequest` encapsulate two ends of a
	message pipe. They represent the client end and service end of an interface
	connection, respectively.
	* For each Mojom interface `Foo`, there is a generated `FooPtr` class. It owns
	an `InterfacePtrInfo`; provides methods to send interface calls using the
	message pipe handle from the `InterfacePtrInfo`.
	* `mojo.Binding` owns an `InterfaceRequest`. It listens on the message pipe
	handle and dispatches incoming messages to a user-defined interface
	implementation.

	Let's consider the `echo.mojom` example above. The following shows how to create
	an `Echo` interface connection and use it to make a call.

	``` html
	<!DOCTYPE html>
	<script src="URL/to/mojo_bindings.js"></script>
	<script src="URL/to/echo.mojom.js"></script>
	<script>

	function EchoImpl() {}
	EchoImpl.prototype.echoInteger = function(value) {
	return Promise.resolve({result: value});
	};

	var echoServicePtr = new test.echo.mojom.EchoPtr();
	var echoServiceRequest = mojo.makeRequest(echoServicePtr);
	var echoServiceBinding = new mojo.Binding(test.echo.mojom.Echo,
	new EchoImpl(),
	echoServiceRequest);
	echoServicePtr.echoInteger({value: 123}).then(function(response) {
	console.log('The result is ' + response.value);
	});

	</script>
	```

	### Interface Pointers and Requests
	In the example above, `test.echo.mojom.EchoPtr` is an interface pointer class.
	`EchoPtr` represents the client end of an interface connection. For method
	`EchoInteger` in the `Echo` Mojom interface, there is a corresponding
	`echoInteger` method defined in `EchoPtr`. (Please note that the format of the
	generated method name is `camelCaseWithLowerInitial`.)

	There are some control methods shared by all interface pointer classes. For
	example, binding/extracting `InterfacePtrInfo`, setting connection error
	handler, querying version information, etc. In order to avoid name collision,
	they are defined in `mojo.InterfacePtrController` and exposed as the `ptr` field
	of every interface pointer class.

	In the example above, `echoServiceRequest` is an `InterfaceRequest` instance. It
	represents the service end of an interface connection.

	`mojo.makeRequest` creates a message pipe; populates the output argument (which
	could be an `InterfacePtrInfo` or an interface pointer) with one end of the
	pipe; returns the other end wrapped in an `InterfaceRequest` instance.

	### Binding an InterfaceRequest
	A `mojo.Binding` bridges an implementation of an interface and a message pipe
	endpoint, dispatching incoming messages to the implementation.

	In the example above, `echoServiceBinding` listens for incoming `EchoInteger`
	method calls on the messsage pipe, and dispatches those calls to the `EchoImpl`
	instance.

	### Receiving Responses
	Some Mojom interface methods expect a response, such as `EchoInteger`. The
	corresponding JavaScript method returns a Promise. This Promise is resolved when
	the service side sends back a response. It is rejected if the interface is
	disconnected.

	### Connection Errors
	If a pipe is disconnected, both endpoints will be able to observe the connection
	error (unless the disconnection is caused by closing/destroying an endpoint, in
	which case that endpoint won't get such a notification). If there are remaining
	incoming messages for an endpoint on disconnection, the connection error won't
	be triggered until the messages are drained.

	Pipe disconnecition may be caused by:
	* Mojo system-level causes: process terminated, resource exhausted, etc.
	* The bindings close the pipe due to a validation error when processing a
	received message.
	* The peer endpoint is closed. For example, the remote side is a bound interface
	pointer and it is destroyed.

	Regardless of the underlying cause, when a connection error is encountered on
	a binding endpoint, that endpoint's connection error handler (if set) is
	invoked. This handler may only be invoked once as long as the endpoint is
	bound to the same pipe. Typically clients and implementations use this handler
	to do some kind of cleanup or recovery.

	``` js
	// Assume echoServicePtr is already bound.
	echoServicePtr.ptr.setConnectionErrorHandler(function() {
	DoImportantCleanUp();
	});

	// Assume echoServiceBinding is already bound:
	echoServiceBinding.setConnectionErrorHandler(function() {
	DoImportantCleanUpToo();
	});
	```

	Note: Closing one end of a pipe will eventually trigger a connection error
	on the other end. However it's ordered with respect to any other event (e.g.
	writing a message) on the pipe. Therefore, it is safe to make an `echoInteger`
	call on `echoServicePtr` and reset it immediately (which results in
	disconnection), `echoServiceBinding` will receive the `echoInteger` call before
	it observes the connection error.

	## Associated Interfaces
	An associated interface connection doesn't have its own underlying message pipe.
	It is associated with an existing message pipe (i.e., interface connection).

	Similar to the non-associated interface case, we have:
	* `mojo.AssociatedInterfacePtrInfo` and `mojo.AssociatedInterfaceRequest`
	encapsulate a route ID, representing a logical connection over a message
	pipe.
	* For each Mojom interface `Foo`, there is a generated `FooAssociatedPtr` class.
	It owns an `AssociatedInterfacePtrInfo`. It is the client side of an
	interface.
	* `mojo.AssociatedBinding` owns an `AssociatedInterfaceRequest`. It listens on
	the connection and dispatches incoming messages to a user-defined interface
	implementation.

	See [this document](https://www.chromium.org/developers/design-documents/mojo/associated-interfaces)
	for more details.

	## Automatic and Manual Dependency Loading
	By default, generated `.mojom.js` files automatically load Mojom dependencies.
	For example, if `foo.mojom` imports `bar.mojom`, loading `foo.mojom.js` will
	insert a `<script>` tag to load `bar.mojom.js`, if it hasn't been loaded.

	The URL of `bar.mojom.js` is determined by:
	* the path of `bar.mojom` relative to the position of `foo.mojom` at build time;
	* the URL of `foo.mojom.js`.

	For exmple, if at build time the two Mojom files are located at:
	```
	a/b/c/foo.mojom
	a/b/d/bar.mojom
	```

	The URL of `foo.mojom.js` is:
	```
	http://example.org/scripts/b/c/foo.mojom.js
	```

	Then the URL of `bar.mojom.js` is supposed to be:
	```
	http://example.org/scripts/b/d/bar.mojom.js
	```

	If you would like `bar.mojom.js` to live at a different location, you need to
	set `mojo.config.autoLoadMojomDeps` to `false` before loading `foo.mojom.js`,
	and manually load `bar.mojom.js` yourself. Similarly, you need to turn off this
	option if you merge `bar.mojom.js` and `foo.mojom.js` into a single file.

	``` html
	<!-- Automatic dependency loading -->
	<script src="http://example.org/scripts/mojo_bindings.js"></script>
	<script src="http://example.org/scripts/b/c/foo.mojom.js"></script>


	<!-- Manual dependency loading -->
	<script src="http://example.org/scripts/mojo_bindings.js"></script>
	<script>
	mojo.config.autoLoadMojomDeps = false;
	</script>
	<script src="http://example.org/scripts/b/d/bar.mojom.js"></script>
	<script src="http://example.org/scripts/b/c/foo.mojom.js"></script>
	```

	### Performance Tip: Avoid Loading the Same .mojom.js File Multiple Times
	If `mojo.config.autoLoadMojomDeps` is set to `true` (which is the default
	value), you might accidentally load the same `.mojom.js` file multiple times if
	you are not careful. Although it doesn't cause fatal errors, it hurts
	performance and therefore should be avoided.

	``` html
	<!-- Assume that mojo.config.autoLoadMojomDeps is set to true: -->

	<!-- No duplicate loading; recommended. -->
	<script src="http://example.org/scripts/b/c/foo.mojom.js"></script>

	<!-- No duplicate loading, although unnecessary. -->
	<script src="http://example.org/scripts/b/d/bar.mojom.js"></script>
	<script src="http://example.org/scripts/b/c/foo.mojom.js"></script>

	<!-- Load bar.mojom.js twice; should be avoided. -->
	<!-- when foo.mojom.js is loaded, it sees that bar.mojom.js is not yet loaded,
	so it inserts another <script> tag for bar.mojom.js. -->
	<script src="http://example.org/scripts/b/c/foo.mojom.js"></script>
	<script src="http://example.org/scripts/b/d/bar.mojom.js"></script>
	```

	If a `.mojom.js` file is loaded for a second time, a warnings will be showed
	using `console.warn()` to bring it to developers' attention.

	## Name Formatting
	As a general rule, Mojom definitions follow the C++ formatting style. To make
	the generated JavaScript bindings conforms to our JavaScript style guide, the
	code generator does the following conversions:

	\| In Mojom \| In generated .mojom.js \|
	\|----------------------\|------------------------\|
	\| MethodLikeThis \| methodLikeThis
	\| parameter_like_this \| parameterLikeThis
	\| field_like_this \| fieldLikeThis
	\| name_space.like_this \| nameSpace.likeThis