or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

binary-io.mdcli-tools.mdcode-generation.mdindex.mdproto-loading.mdreflection.mdrpc-services.mdserialization.md
tile.json

tessl/npm-protobufjs

Protocol Buffers for JavaScript with TypeScript support, providing pure JavaScript implementation for serializing and deserializing structured data using Google's Protocol Buffer format.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/protobufjs@7.5.x

To install, run

npx @tessl/cli install tessl/npm-protobufjs@7.5.0

index.mddocs/

protobufjs

protobufjs is a pure JavaScript implementation of Protocol Buffers for JavaScript and TypeScript environments. It provides comprehensive functionality for parsing .proto files, runtime reflection, and efficient binary serialization/deserialization, supporting both Node.js and browser environments with zero native dependencies.

Package Information

  • Package Name: protobufjs
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install protobufjs

Core Imports

// Full build - includes parser and reflection
const protobuf = require("protobufjs");
// Light build - reflection without parser  
const protobuf = require("protobufjs/light");
// Minimal build - core serialization only
const protobuf = require("protobufjs/minimal");

ES Module imports:

import protobuf from "protobufjs";
import * as protobuf from "protobufjs";

TypeScript:

import * as protobuf from "protobufjs";
import { Root, Type, Field, Message } from "protobufjs";

Basic Usage

const protobuf = require("protobufjs");

// Load a .proto file
protobuf.load("awesome.proto", function(err, root) {
    if (err) throw err;

    // Obtain a message type
    const AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage");

    // Create a message instance
    const payload = { awesomeField: "AwesomeString" };
    
    // Verify the payload if necessary
    const errMsg = AwesomeMessage.verify(payload);
    if (errMsg) throw Error(errMsg);

    // Create and encode a message
    const message = AwesomeMessage.create(payload);
    const buffer = AwesomeMessage.encode(message).finish();

    // Decode the message
    const decoded = AwesomeMessage.decode(buffer);
    console.log(decoded);
});

Architecture

protobufjs is built around several key architectural components:

  • Build Variants: Three different builds (full, light, minimal) for different use cases and bundle sizes
  • Reflection System: Runtime representation of .proto definitions with full type information
  • Parser: .proto file parser for dynamic loading and compilation (full build only)
  • Code Generation: Static code generation via CLI tools for optimal performance
  • Serialization Engine: Efficient binary encoding/decoding with type safety
  • RPC Framework: Built-in support for service definitions and RPC implementations

Build Variants Comparison

FeatureMinimalLightFull
Bundle Size~6KB~16KB~26KB
Writer/Reader✅✅✅
Message Encoding/Decoding✅✅✅
Root/Type/Field Classes❌✅✅
Runtime Reflection❌✅✅
Dynamic Loading (.proto)❌✅✅
Parser (.proto to JSON)❌❌✅
Tokenizer❌❌✅
Common Google Types❌❌✅
Use CasePre-compiledRuntime ReflectionFull Development

Choosing a Build:

  • Minimal: Use with pre-compiled/generated code for smallest bundle size
  • Light: Use when you need runtime reflection but not parsing capabilities
  • Full: Use for development, dynamic loading, or when parsing .proto files

Capabilities

Proto File Loading

Dynamic loading and parsing of .proto files with full reflection support. Enables runtime schema loading and type discovery.

function load(filename: string | string[], callback: LoadCallback): void;
function load(filename: string | string[], root: Root, callback: LoadCallback): void;
function loadSync(filename: string | string[], root?: Root): Root;

interface LoadCallback {
  (error: Error | null, root?: Root): void;
}

Proto Loading

Reflection System

Complete runtime reflection API for working with protobuf types, services, and schemas. Provides programmatic access to all protobuf constructs.

class Root extends Namespace {
  static fromJSON(json: object): Root;
  load(filename: string | string[], callback: LoadCallback): Root;
  loadSync(filename: string | string[]): Root;
}

class Type extends Namespace {
  static fromJSON(name: string, json: object): Type;
  create(properties?: object): Message;
  encode(message: Message | object): Writer;
  decode(reader: Reader | Uint8Array): Message;
  verify(message: object): string | null;
}

Reflection

Message Serialization

High-performance binary serialization and deserialization with full type safety and validation.

class Message {
  static create(properties?: object): Message;
  static encode(message: Message | object): Writer;
  static encodeDelimited(message: Message | object): Writer;
  static decode(reader: Reader | Uint8Array): Message;
  static decodeDelimited(reader: Reader | Uint8Array): Message;
  static verify(message: object): string | null;
  static fromObject(object: object): Message;
  static toObject(message: Message, options?: IConversionOptions): object;
}

Serialization

Binary I/O Operations

Low-level binary reading and writing operations for custom serialization needs and performance optimization.

class Writer {
  static create(): Writer;
  uint32(value: number): Writer;
  int32(value: number): Writer;
  string(value: string): Writer;
  bytes(value: Uint8Array): Writer;
  finish(): Uint8Array;
}

class Reader {
  static create(buffer: Uint8Array): Reader;
  uint32(): number;
  int32(): number;
  string(): string;
  bytes(): Uint8Array;
}

Binary I/O

Code Generation

Static code generation and compilation utilities for creating optimized protobuf implementations.

function encoder(mtype: Type): Codegen;
function decoder(mtype: Type): Codegen;
function verifier(mtype: Type): Codegen;

namespace converter {
  function fromObject(mtype: Type): Codegen;
  function toObject(mtype: Type): Codegen;
}

Code Generation

RPC Services

Built-in RPC service framework for implementing and consuming protobuf-based services.

class Service extends Namespace {
  static fromJSON(name: string, json: object): Service;
  create(rpcImpl: RPCImpl, requestDelimited?: boolean, responseDelimited?: boolean): rpc.Service;
}

interface RPCImpl {
  (method: Method, requestData: Uint8Array, callback: RPCImplCallback): void;
}

RPC Services

Proto Tokenization

Low-level tokenization of .proto source files for advanced parsing and analysis use cases. Available in full build only.

function tokenize(source: string, alternateCommentMode: boolean): ITokenizerHandle;

namespace tokenize {
  function unescape(str: string): string;
}

interface ITokenizerHandle {
  next(): string | null;
  peek(): string | null;
  push(token: string): void;
  skip(expected?: string, optional?: boolean): boolean;
  cmnt(trailingLine?: number): string | null;
  line: number;
}

Google Protocol Buffer Types

Built-in support for Google's well-known types with automatic handling and type definitions. Available in full build only.

function common(name: string, json: { [k: string]: any }): void;

namespace common {
  function get(file: string): object | null;
  
  interface IAny {
    typeUrl?: string;
    bytes?: Uint8Array;
  }
  
  interface IDuration {
    seconds?: (number | Long);
    nanos?: number;
  }
  
  interface ITimestamp {
    seconds?: (number | Long);
    nanos?: number;
  }
  
  interface IEmpty {}
  
  interface IStruct {
    fields?: { [k: string]: IValue };
  }
  
  interface IValue {
    kind?: string;
    nullValue?: 0;
    numberValue?: number;
    stringValue?: string;
    boolValue?: boolean;
    structValue?: IStruct;
    listValue?: IListValue;
  }
  
  interface IListValue {
    values?: IValue[];
  }
}

CLI Tools

Command-line utilities for static code generation and TypeScript definition generation.

# Generate static JavaScript code
pbjs -t static-module -w commonjs -o compiled.js file1.proto file2.proto

# Generate TypeScript definitions  
pbts -o compiled.d.ts compiled.js

CLI Tools

Utility Functions

Common utility functions for type checking, string manipulation, and low-level operations.

namespace util {
  // Type checking utilities
  function isInteger(value: any): boolean;
  function isString(value: any): boolean;
  function isObject(value: any): boolean;
  function isSet(obj: object, prop: string): boolean;
  
  // String manipulation
  function lcFirst(str: string): string;
  
  // Buffer operations  
  function newBuffer(sizeOrArray: number | number[]): Uint8Array;
  
  // Long integer utilities
  function longToHash(value: Long | number): string;
  function longFromHash(hash: string, unsigned?: boolean): Long;
  
  // OneOf field helpers
  function oneOfGetter(fieldNames: string[]): () => string | undefined;
  function oneOfSetter(fieldNames: string[]): (name?: string) => void;
  
  // Low-level bit manipulation
  class LongBits {
    constructor(lo: number, hi: number);
    lo: number;
    hi: number;
    static zero: LongBits;
    static fromNumber(value: number): LongBits;
    static from(value: Long | number | string): LongBits;
    toNumber(unsigned?: boolean): number;
    toLong(unsigned?: boolean): Long;
    zzEncode(): LongBits;
    zzDecode(): LongBits;
  }
}

Types

interface IConversionOptions {
  longs?: typeof String | typeof Number | typeof Long;
  enums?: typeof String;
  bytes?: typeof Array | typeof String;
  defaults?: boolean;
  arrays?: boolean;
  objects?: boolean;
  oneofs?: boolean;
}

interface Long {
  low: number;
  high: number;
  unsigned: boolean;
  toNumber(): number;
  toString(): string;
}

interface LoadCallback {
  (error: Error | null, root?: Root): void;
}

interface RPCImplCallback {
  (error: Error | null, response?: Uint8Array): void;
}

interface ITokenizerHandle {
  next(): string | null;
  peek(): string | null;
  push(token: string): void;
  skip(expected?: string, optional?: boolean): boolean;
  cmnt(trailingLine?: number): string | null;
  line: number;
}

interface IFetchOptions {
  binary?: boolean;
  xhr?: boolean;
}

type FetchCallback = (error: Error, contents?: string) => void;
type PoolAllocator = (size: number) => Uint8Array;
type PoolSlicer = (start: number, end: number) => Uint8Array;