🔥 capnp-es

Warning

This is an alpha-quality software. please use at your own risk (project status).

TypeScript implementation of the Cap'n Proto serialization protocol.

Cap’n Proto is an insanely fast data interchange format and capability-based RPC system. Think JSON, except binary. Or think Protocol Buffers, except faster. Cap’n Proto was built by Kenton Varda to be used in Sandstorm and is now heavily used in Cloudflare.

Usage

Compiling schema

Note

Make sure capnpc command is available. You can find install instructions here to install it.

Install capnp-es dependency:

npx nypm install capnp-es

You can use capnp-es to compile a schema file into typeScript/javascript source code:

npx capnp-es path/to/myschema.capnp -ojs,ts,dts

This will generate path/to/myschema.{js,ts,dts}.

Use npx capnp-es --help for full usage info.

See playground for examples and learn more about .capnp schema in language docs.

Reading Messages

Here's a quick usage example:

import * as capnp from "capnp-es";
import { MyStruct } from "./myschema.js";

const message = capnp.Message.fromArrayBuffer(buffer);
const struct = message.getRoot(MyStruct);

RPC Protocol

Experimental RPC protocol is supported (level 1).

See tests for some examples.

Status

This project is a rework of jdiaz5513/capnp-ts by Julián Díaz and is under development.

Changes from capnp-ts

• Internal refactors and simplifications as was playing around.
• Compiler, runtime, and std lib published via a single and compact ESM-only package with subpath exports.
• Compiler updated to use Typescript v5 API
• Output files can be .ts (new), .js (ESM instead of CJS), and .d.ts and has no .capnp suffix.
• Compiler API can be used via the capnp-es/compiler subpath export programmatically.
• Use native TextEncoder and TextDecoder for utf8 encoding
• Enums are typed plain JS objects (this way .ts files work with strip-only ts loaders without enum support.)
• Compiler CLI can directly accept a path to .capnp files and internally use capnpc
• Built-in schemas are compiled from source (compiler, compiles itself. so cool right?)
• Use reflection (getter setters) to access structs.
• RPC level-1 merged from jdiaz5513/capnp-ts#169.
• List interface implements Array object (custom methods removed).
• Pointers had been improved to feel (inspected and serialized) like native JS values as much as possible.
• Basic JSDocs generated for class and getter

Contribution

Feedback and PRs are more than welcome. 🙏

Local development

• Clone this repository
• Install the latest LTS version of Node.js
• Enable Corepack using corepack enable
• Install dependencies using pnpm install
• Run interactive tests using pnpm dev

License

🔀 Forked from jdiaz5513/capnp-ts by Julián Díaz.

💛 Published under the MIT license.