Generate Javascript serialization classes for Capnproto.

Installation and preferred use

• Ensure that you have up-to-date versions of libtool, autoconf, and automake.
  • On OSX: brew upgrade libtool autoconf automake
• Install by npm: npm install capnp-js-plugin.
• This plugin checks out and then builds the Capnproto compiler.
  • The build takes about 5 minutes on my system, so I use a global install: npm install -g capnp-js-plugin.
  • For each project that uses a Capnproto schema, I include the plugin as a devDependency: npm install --save-dev capnp-js-plugin.
  • I avoid including the plugin as a dependency, because this would result in absurdly long build times for non-dev users.
  • Under this arrangement, I must distribute generated-code instead of creating it client-side--I feel that the build time-savings warrants the source-of-truth confusion.

Usage

• The compiler is invoked with capnp compile -ojs someSchema.capnp to generate a someSchema.capnp.d directory that contains the schema's AMD files.
• Run capnp help compile for additional options.
• To obtain Node modules, I convert the generated AMD modules with a fork of Nodefy called Nfy. See this nfy script for an example. I suspect that AMDefine provides an alternate solution, but I won't chase any upstream bugs related to the use of AMDefine.

This plugin generates serialization classes similar to those of the c++ reference implementation. Given a schema someSchema.capnp, capnp compile -ojs someSchema.capnp will generate someSchema.capnp.d/readers.js, someSchema.capnp.d/builders.js, and some internal files:

Javascript implementation of readers for members of someSchema.capnp. See Readers from the reference implementation's documentation.

Javascript implementation of builders for members of someSchema.capnp. See Builders from the reference implementation's documentation.

The following files exist under someSchema.capnp.d/, but should not be imported by user code. These files facilitate circular reference resolution by creating types and accumulating them, without calling any prototype methods.

• someSchema.capnp.d/rTypes.js: Reader types defined in someSchema.capnp.
• someSchema.capnp.d/rScope.js: Merge all Reader types imported by someSchema.capnp with those created within someSchema.capnp.
• someSchema.capnp.d/bTypes.js: Analogous to rTypes.js.
• someSchema.capnp.d/bScope.js: Analogous to rScope.js.

The Javascript plugin maps absolute imports to absolute AMD paths. Consider the messaging example from the rtc-github repository:

• Its capnp/server.capnp schema lists an absolute import: using import "/rtc-github-protocol/user.capnp".User;.
• The package's rtc-github-protocol dependency exposes the user.capnp schema as node_modules/rtc-github-protocol/user.capnp.
• The package's capnp script, capnp compile -ojs:resources --src-prefix=capnp -I node_modules/ capnp/*.capnp, yields an absolute path in resources/server.capnp.d/readers.js, among others.
• Now I just need to point my AMD loader at rtc-github-protocol, e.g. index.htm.

You should minify the generated code for production builds. The generated code contains console.warn calls for development purposes--use something like uglifyjs -c drop_console to eliminate them.