public/js/README.md

# 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