CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-pbf

A low-level, lightweight protocol buffers implementation for JavaScript with high-performance binary serialization and deserialization capabilities.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

cli-tool.mddocs/

CLI Tool

Command-line interface for compiling .proto files directly to JavaScript modules. The CLI tool provides a simple way to generate optimized JavaScript code from protocol buffer schema files.

Installation and Usage

Global Installation

npm install -g pbf

Usage

// Command signature
pbf <proto_path> [--no-write] [--no-read] [--legacy]

Basic Commands

# Compile a .proto file to JavaScript (outputs to stdout)
pbf example.proto > example.js

# Compile and save to a file
pbf schema.proto --legacy > schema.js

# Generate only read functions
pbf data.proto --no-write > data-reader.js

# Generate only write functions  
pbf data.proto --no-read > data-writer.js

Command Options

Option: --no-write

Exclude write functions from the generated code:

pbf example.proto --no-write > example-reader.js

Generated code will only contain read functions:

export function readExample(pbf, end) { /* ... */ }
// writeExample function will not be generated

Option: --no-read

Exclude read functions from the generated code:

pbf example.proto --no-read > example-writer.js

Generated code will only contain write functions:

export function writeExample(obj, pbf) { /* ... */ }
// readExample function will not be generated

Option: --legacy

Generate CommonJS module instead of ES6 module:

pbf example.proto --legacy > example.js

ES6 Module Output (default):

export function readExample(pbf, end) { /* ... */ }
export function writeExample(obj, pbf) { /* ... */ }

CommonJS Output (with --legacy):

exports.readExample = readExample;
function readExample(pbf, end) { /* ... */ }

exports.writeExample = writeExample;
function writeExample(obj, pbf) { /* ... */ }

Examples

Basic Proto File

Given a person.proto file:

syntax = "proto3";

message Person {
    string name = 1;
    int32 id = 2;
    string email = 3;
    repeated string phone_numbers = 4;
}

Generate JavaScript module:

pbf person.proto > person.js

Generated person.js:

export function readPerson(pbf, end) {
    return pbf.readFields(readPersonField, {name: "", id: 0, email: "", phone_numbers: []}, end);
}
function readPersonField(tag, obj, pbf) {
    if (tag === 1) obj.name = pbf.readString();
    else if (tag === 2) obj.id = pbf.readVarint();
    else if (tag === 3) obj.email = pbf.readString();
    else if (tag === 4) obj.phone_numbers.push(pbf.readString());
}
export function writePerson(obj, pbf) {
    if (obj.name) pbf.writeStringField(1, obj.name);
    if (obj.id) pbf.writeVarintField(2, obj.id);
    if (obj.email) pbf.writeStringField(3, obj.email);
    for (const item of obj.phone_numbers) pbf.writeStringField(4, item);
}

Complex Schema with Nested Messages

Given a addressbook.proto file:

syntax = "proto3";

message AddressBook {
    repeated Person people = 1;
}

message Person {
    string name = 1;
    int32 id = 2;
    string email = 3;
    repeated PhoneNumber phones = 4;
}

message PhoneNumber {
    string number = 1;
    PhoneType type = 2;
}

enum PhoneType {
    MOBILE = 0;
    HOME = 1;
    WORK = 2;
}

Generate with options:

pbf addressbook.proto --legacy > addressbook.js

The generated code will include:

  • readAddressBook / writeAddressBook
  • readPerson / writePerson
  • readPhoneNumber / writePhoneNumber
  • PhoneType enum constant

Workflow Integration

Integrate proto compilation into build process:

package.json scripts:

{
  "scripts": {
    "build:proto": "pbf schema/data.proto > src/generated/data.js",
    "build:proto:types": "pbf schema/data.proto --no-write > src/generated/data-reader.js",
    "build": "npm run build:proto && webpack"
  }
}

Makefile integration:

src/generated/%.js: schema/%.proto
	pbf $< > $@

build: src/generated/data.js src/generated/user.js
	webpack

Development Workflow

# During development - generate readable code
pbf schema.proto > generated.js

# For production - generate optimized code  
pbf schema.proto --no-comments > generated.min.js

Usage with Generated Code

Importing Generated Functions

// Using generated ES6 module
import { readPerson, writePerson } from "./person.js";
import Pbf from "pbf";

// Reading
const person = readPerson(new Pbf(buffer));

// Writing  
const pbf = new Pbf();
writePerson(person, pbf);
const encoded = pbf.finish();

CommonJS Usage

// Using generated CommonJS module
const { readPerson, writePerson } = require("./person.js");
const Pbf = require("pbf");

// Same usage pattern
const person = readPerson(new Pbf(buffer));

Error Handling

The CLI tool will exit with error codes for various failure conditions:

# No arguments provided
pbf
# Error: Usage: pbf [file.proto] [--no-read] [--no-write] [--legacy]

# Invalid proto file
pbf nonexistent.proto  
# Error: Cannot read proto file

# Invalid proto syntax
pbf invalid.proto
# Error: Proto parsing failed

Check exit codes in scripts:

if pbf schema.proto > generated.js; then
    echo "Compilation successful"
else
    echo "Compilation failed with exit code $?"
    exit 1
fi

Dependencies

The CLI tool requires:

  • resolve-protobuf-schema - For parsing .proto files
  • Node.js - Runtime environment

Ensure these are available in your environment when using the CLI tool programmatically or in build systems.

Install with Tessl CLI

npx tessl i tessl/npm-pbf

docs

buffer-operations.md

cli-tool.md

index.md

schema-compilation.md

tile.json