README

Protocol Buffers are a language-neutral, platform-neutral, extensible way of serializing structured data for use in communications protocols, data storage, and more, originally designed at Google (see).

Shaft, using proto js generates Backbone Models and Collections from Potocol Buffers.

Features

Dynamic Message -> Backbone Model generation
Nested Messages support
Packages support
Imported proto Message support
Scalar types field support
Defaults handling
Any field support
Enum (internal/external) field support
Repeated fields support

Usage
How to include protobuf.js in your project.
Examples
A few examples to get you started.
Documentation
A list of available documentation resources.
Building
How to build the library and its components yourself.

Usage

Installation

Shaft.js is directly available from npm.

npm install shaft.js

Examples

Requisite

Proto definitions must be loaded using Protobuf-js, cf examples here.

Loading

Shaft Models/Collections must be loaded from those proto definitions using loadAll method.

protobuf.load([
    "proto/pga-tour.proto",
    "proto/european-tour.proto"
], function(err, protos) {
  shaft.loadAll(protos);
});

If you only want to load some of the proto, then just use load

protobuf.load([
    "proto/pga_tour.proto",
    "proto/european_tour.proto"
], function(err, protos) {
  shaft.load(protos.pga_tour);
});

Backbone Models and Collections

Given the following proto:

package pga;
syntax = "proto3";

message Player {
    string name = 1;
    int rank = 2;
}

Using shaft.js you can simply use Player Message as a plain Backbone Model:

const Player = shaft.model.get("pga", "Player");
const tiger = new Player();

Same goes for Collections:

const Players = shaft.model.get("pga", "Player");
const pgaAmericaPlayers = new Players();
pgaAmericaPlayers.add({
  name: "Jordan Spieth",
  rank: 1
});
pgaAmericaPlayers.add({
  name: "Phil Mickelson",
  rank: 2
});

Enumerations

package golf;
syntax = "proto3";

enum ShotKind {
  PUTT:1,
  DRIVE: 2
}

message Player {
    string name = 1
    ShotKind speciality = 2;
}

Enumerations can be imported as plain objects:

const ShotKind = shaft.enumeration.get("golf", "ShotKind");
// ShotKind = { PUTT:1, DRIVE: 2 }

But is automacally attached to a Message when defined as field.

const Player = shaft.model.get("golf", "Player");
const dustin = new Player({ name: "Dustin Jonhson", speciality: "DRIVE" });
const jordan = new Player({ name: "Jordan Spieth", speciality: "PUTT" });

Documentation

API documentation

Building

To build the library or its components yourself, clone it from GitHub and install the development dependencies:

gt; git clone https://github.com/fairway-digital/shaft
gt; cd shaft.js
gt; npm install

Building version to dist/:

gt; npm run build

Building production version to dist/:

gt; npm run uglify

Running tests in CI:

gt; npm test

Running tests in DEV:

gt; testem

Generate Code Coverage report to coverage/lcov-report/index.html:

gt; npm run coverage

Building the documentation to documentation/:

gt; npm run tsdoc

shaft.js

Usage no npm install needed!