Mojo JS Bindings: Update User's Guide, examples

examples/js/users-guide.md

Index: examples/js/users-guide.md
diff --git a/examples/js/users-guide.md b/examples/js/users-guide.md
index 0152d832405890d51cc74e05ef15b701b3338422..52ee2b379394d87bf7457ff08093abd2c42cae23 100644
--- a/examples/js/users-guide.md
+++ b/examples/js/users-guide.md
@@ -84,10 +84,10 @@ Mojo shell's client.
 
 The intiailize() method is called once, after the constructor has run
 and before any calls to acceptConnection(). The value of its parameter
-is argument list specified for this application with
+is the argument list specified for this application with
 mojo_shell. Arguments can be specified using the mojo_shell
 `--args-for` command line argument or by just adding them after the
-application's URL and enclosing the entire expression in quotes.
+application's URL and enclosing the entire expression in quotes:
 
 ```
   mojo_shell '<js-application-url> arg1 arg2'
@@ -99,14 +99,16 @@ to this one. The first call corresponds the mojo_shell's initial connection.
 The serviceProvider parameter is a JS ServiceProvider, see the "Requesting
 and Providing Services" section below.
 
-## JS Bindings
+# JS Bindings
 
-To use or implement a service you'll need the JS "bindings" for the
-Mojo interface. The bindings are generated by the build system and end
+The JS bindings map from incoming Mojo messages to JS values, and
+similarly from outgoing JS values to Mojo messages.
+
+To use or implement a service you'll need the JS bindings for the
+service's Mojo interface. The bindings are generated by the build system and end
 up in files whose name is the same as the '.mojom' file with a '.js'
 suffix. It's often helpful to look at the generated '.mojom.js' files.
 
-
 The JS bindings for a Mojo interface's API are delivered as a JS module whose
 name is based on the '.mojom' file's path. For example, to use the Mojo network
 service you need the JS module based on network_service.mojom:
@@ -149,20 +151,155 @@ var NetworkService = {
 The 'proxyClass' is used to access another application's NetworkService and the
 'stubClass' is used to create an implementation of NetworkService. 
 
-## The JS Shell Class
+## JS Bindings for Basic Types
 
-The JS Shell class simplifies connecting to applications and services. It's a
-wrapper for the Application's appShell argument. The Application constructor
-creates a Shell and assigns it to `this.shell`.
+In most cases the mapping from Mojo types to JS types is simple. 
 
-The Shell's connectToService() method returns a "proxy" to a service provided by
-another application.
+Mojo Type  | JS Type
+------------- | -------------
+bool  | true or false
+int8, uint8  | Number
+int16, uint16  | Number
+int32, uint32  | Number
+int64, uint64  | Number*
+float, double  | Number
+string  | String
+array | Array
+map | Map
 
-In the netService case above the Shell connects to the Mojo application at
-"mojo:network_service", then connects to its service called 
-NetworkService.name with an instance of NetworkService.proxyClass. The proxy
-instance is returned. The netService proxy can be used immediately.
+The support for 64 bit integers is currently limited to 53 bits per
+the current JS standard. Only integer values in the range from
+``Number.MIN_SAFE_INTEGER`` to ``Number.MAX_SAFE_INTEGER`` can be
+represented exactly. Larger and smaller values are approximated by
+double precision Numbers.
+
+Unspecified bool parameter or struct field values default to false
+unless an explicit Mojo default was specified.
+
+Unspecified integer values similarly default to 0.
+
+Unspecified nullable string, array, and map values similarly default to
+null and can be specified as null. In Mojom a nullable type has a
+``?`` suffix.
+
+## JS Bindings for Structs
+
+Mojo structs are mapped to JS objects. An eponymous class is generated for each
+struct type. The struct class constructor has an object-valued parameter to make
+it a little easier to specify a struct value. For example:
+
+```javascript
+// Mojom definitions
+struct Foo {
+  string? name;
+  array<int32>? values;
+};
+
+interface I {
+  PassFoo(Foo foo);
+}
+
+// JavaScript Usage, assuming we have a proxy for I, iProxy
+
+// Rough and ready struct construction:
+var foo = new Foo;
+foo.name = "foo";
+foo.values = [1,2,3];
+iProxy.PassFoo(foo);
+
+// Using the Foo constructor parameter:
+iProxy.PassFoo(new Foo({name: "foo", values: [1,2,3]}));
+iProxy.PassFoo(new Foo); // name, values are null
+iProxy.PassFoo(new Foo({name: null}); // Same as previous line.
+```
+
+An unspecified nullable struct parameter or struct field value defaults to 
+null.
+
+
+## JS Bindings for Interface Parameters
+
+## Stubs and Proxies
+
+TODO: briefly introduce message pipes. 
+TODO: explain what stubs and proxies are, explain what's meant by "local" and "remote". 
+TODO: explain the StubBindings and ProxyBindings functions.
+TODO: support creating a proxy from a handle new MyProxy(someHandle);
+TODO: explain the Connection object and how it relates to this stuff.
+
+From a user's point of view, the bindings are in terms of the (remote)
+proxy class and the (local) stub class. Properties are added to instances
+of these classes using functions called StubBindings and ProxyBindings.
+
+The caller and callee use cases that follow are  in terms of the following mojom:
+
+```
+[Client=Bar]
+interface Foo {
+}
+
+[Client=Foo] // Redundant but always implicitly true.
+interface Bar {
+}
+
+interface I {
+  provideFoo(Foo foo);
+  requestFoo(Foo& foo); // effectively: provideFoo(Bar bar)
+} 
+```
 
+## Callers
+
+Assuming that we have a proxy for interface I, iProxy.
+
+An iProxy.provideFoo() call implies that we have an implementation of
+Foo, and want a proxy for Bar (Foo's client).
+
+```javascript
+var barProxy;
+iProxy.provideFoo(function(remote) {
+  barProxy = remote;
+  return myFooImpl;
+});
+```
+
+An iProxy.requestFoo() call implies that we have an implementation of
+Bar and want a proxy for Foo (Bar's client).
+
+```javascript
+var fooProxy;
+iProxy.requestFoo(function(remote) {
+  fooProxy = remote;
+  return myBarImpl;
+});
+```
+
+In the requestFoo() case, if no client were defined for Bar the function
+parameter need not return anything.
+
+The wget.js example includes a request for the URLLoader service.
+
+## Callees
+
+An implementation of provideFoo(Foo foo) implies that we have an
+implementation of Bar (Foo's client) and want a proxy to the Foo
+that has been passed to us.
+
+```javascript
+void provideFoo(fooProxy) {
+  ProxyBindings(fooProxy).setLocalDelegate(myMyBarImpl);
+}
+```
+
+An implementation of requestFoo(Foo& foo) implies that we have an
+implementation of Foo and want a proxy for the Bar (Foo's client)
+that's been passed to us.
+
+```javascript
+void requestFoo(barProxy) {
+  ProxyBindings(barProxy).setLocallocalDelegate(myFooImpl);
+}
+```
 
 ## Mojo Responses are Promises
 
@@ -192,6 +329,42 @@ MyEchoStringImpl.prototype.EchoString = function(s) {
 };
 ```
 
+# The JS Shell Class
+
+The JS Shell class simplifies connecting to applications and services. It's a
+wrapper for the Application's appShell argument. The Application constructor
+creates a Shell and assigns it to `this.shell`.
+
+The Shell's connectToService() method returns a "proxy" to a service provided by
+another application.
+
+```javascript
+  define("main", [
+    "mojo/services/network/public/interfaces/network_service.mojom",
+    "mojo/services/public/js/application",
+  ]
+    function(net, application) {
+      class MyApplication extends application.Application {
+        initialize(args) {
+          var netService = this.shell.connectToService(
+              "mojo:network_service", net.NetworkService);
+          // Use netService's NetworkService methods.
+        }
+        ...
+      }
+      ...
+    }
+    return MyApplication;
+  });
+```
+
+In the netService case above the Shell connects to the Mojo application at
+"mojo:network_service", then connects to its service called 
+NetworkService.name with an instance of NetworkService.proxyClass. The proxy
+instance is returned. The netService proxy can be used immediately.
+
+The wget.js example demonstrates using the network service.
+
 ## Requesting and Providing Services
 
 Mojo applications can connect to services provided by other applications and
@@ -249,6 +422,9 @@ interface EchoService {
 
 ### Requesting a Service Using the Application's Shell
 
+The Shell's `connectToService()` method returns a proxy to a Mojo
+service provided by another application. The proxy can be used immediately.
+
 Given the URL of a Mojo application that implements the EchoService we
 can use the application's shell to get an EchoService proxy. Here's a
 complete application:
@@ -275,8 +451,17 @@ define("main", [
 });
 ```
 
+### Requesting a Service from an Application's ServiceProvider
 
-### Providing a Service
+The Shell's `connectToApplication()` method returns a JS ServiceProvider
+object that serves as a proxy to a ServiceProvider implemented by the
+target application. The ServiceProvider can be used to request services
+from the target application and to provide services to the target application.
+
+The echo_share.js and echo_share_target.js applications demonstrate this.
+
+
+### Providing a Service with an Application's ServiceProvider
 
 A complete application that unconditionally provides the EchoService
 looks like this:
@@ -314,6 +499,7 @@ Each time another application connects to this one, the EchoServiceImpl
 function will be called. The caller will be able to run the
 echoString() method and will get its response via a Promise.
 
+The echo_share.js and echo_share_target.js applications demonstrate this.
 
 ## Final note
 
@@ -322,88 +508,3 @@ request or provide services at any time, not just from within
 application's acceptConnection() method.
 
 
-# Interface Parameters
-
-The caller and callee use cases that follow are  in terms of the following mojom:
-
-```
-[Client=Bar]
-interface Foo {
-}
-
-[Client=Foo] // Redundant but always implicitly true.
-interface Bar {
-}
-
-interface I {
-  provideFoo(Foo foo);
-  requestFoo(Foo& foo); // effectively: provideFoo(Bar bar)
-} 
-```
-
-## Stubs and Proxies
-
-TODO: briefly introduce message pipes. 
-TODO: explain what stubs and proxies are, explain what's meant by "local" and "remote". 
-TODO: explain the StubBindings and ProxyBindings functions.
-TODO: support creating a proxy from a handle new MyProxy(someHandle);
-TODO: explain the Connection object and how it relates to this stuff.
-
-From a user's point of view, the bindings are in terms of the (remote)
-proxy class and the (local) stub class. Properties are added to instances
-of these classes using functions called StubBindings and ProxyBindings.
-
-
-
-## Callers
-
-Assuming that we have a proxy for interface I, iProxy.
-
-An iProxy.provideFoo() call implies that we have an implementation of
-Foo, and want a proxy for Bar (Foo's client).
-
-```javascript
-var barProxy;
-iProxy.provideFoo(function(remote) {
-  barProxy = remote;
-  return myFooImpl;
-});
-```
-
-An iProxy.requestFoo() call implies that we have an implementation of
-Bar and want a proxy for Foo (Bar's client).
-
-```javascript
-var fooProxy;
-iProxy.requestFoo(function(remote) {
-  fooProxy = remote;
-  return myBarImpl;
-});
-```
-
-In the requestFoo() case, if no client were defined for Bar the function
-parameter need not return anything.
-
-The wget.js example includes a request for the URLLoader service.
-
-## Callees
-
-An implementation of provideFoo(Foo foo) implies that we have an
-implementation of Bar (Foo's client) and want a proxy to the Foo
-that has been passed to us.
-
-```javascript
-void provideFoo(fooProxy) {
-  ProxyBindings(fooProxy).setLocalDelegate(myMyBarImpl);
-}
-```
-
-An implementation of requestFoo(Foo& foo) implies that we have an
-implementation of Foo and want a proxy for the Bar (Foo's client)
-that's been passed to us.
-
-```javascript
-void requestFoo(barProxy) {
-  ProxyBindings(barProxy).setLocallocalDelegate(myFooImpl);
-}
-```