This module provides a way for the browser to run Node modules like fs, net, etc.
The server-side proxies are regular classes that call native Node functions. The only thing special about them is that they must return promises and they must return serializable values.
The only exception to the promise rule are event-related methods such as onEvent and onDone (these are synchronous). The server will simply immediately bind and push all events it can to the client. It doesn't wait for the client to start listening. This prevents issues with the server not receiving the client's request to start listening in time.
However, there is a way to specify events that should not bind immediately and should wait for the client to request it, because some events (like data on a stream) cannot be bound immediately (because doing so changes how the stream behaves).
Client-side proxies are Proxy instances. They simply make remote calls for any method you call on it using a web socket. The only exception is for events. Each client proxy has a local emitter which it uses in place of a remote call (this allows the call to be completed synchronously on the client). Then when an event is received from the server, it gets emitted on that local emitter.
When an event is listened to, the proxy also notifies the server so it can start listening in case it isn't already (see the data example above). This only works for events that only fire after they are bound.
The client-side fills implement the actual Node API and make calls to the server-side proxies using the client-side proxies.
When a proxy returns a proxy (for example fs.createWriteStream), that proxy is a
promise (since communicating with the server is asynchronous). We have to return
the fill from fs.createWriteStream synchronously, so that means the fill has to
contain a proxy promise. To eliminate the need for calling then and to keep
the code looking clean every time you use the proxy, the proxy is itself wrapped
in another proxy which just calls the method after a then. This works since
all the methods return promises (aside from the event methods, but those are not
used by the fills directly—they are only used internally to forward events to
the fill if it is an event emitter).