# 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 ` ``` ## 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 ``` ### 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 ` ``` ### 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 ``` 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