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.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Proto File Loading

Name: tessl/npm-protobufjs
Author: tessl

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

Capabilities

Load Function (Async)

Loads one or multiple .proto or preprocessed .json files into a root namespace asynchronously.

/**
 * Loads proto files asynchronously with callback
 * @param filename - Single file path or array of file paths to load
 * @param callback - Callback function receiving error and root
 */
function load(filename: string | string[], callback: LoadCallback): void;

/**
 * Loads proto files into specific root namespace asynchronously
 * @param filename - Single file path or array of file paths to load  
 * @param root - Root namespace to load into, creates new if omitted
 * @param callback - Callback function receiving error and root
 */
function load(filename: string | string[], root: Root, callback: LoadCallback): void;

/**
 * Promise-based loading (when no callback provided)
 * @param filename - Single file path or array of file paths to load
 * @param root - Optional root namespace to load into
 * @returns Promise resolving to Root namespace
 */
function load(filename: string | string[], root?: Root): Promise<Root>;

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

Usage Examples:

const protobuf = require("protobufjs");

// Basic callback usage
protobuf.load("schema.proto", function(err, root) {
    if (err) throw err;
    const MyMessage = root.lookupType("MyMessage");
});

// With custom root namespace
const root = new protobuf.Root();
protobuf.load("schema.proto", root, function(err, loadedRoot) {
    console.log(loadedRoot === root); // true
});

// Promise-based usage
protobuf.load("schema.proto")
    .then(root => {
        const MyMessage = root.lookupType("MyMessage");
    })
    .catch(err => console.error(err));

// Multiple files
protobuf.load(["file1.proto", "file2.proto"], function(err, root) {
    // All files loaded into single root namespace
});

LoadSync Function (Sync)

Synchronously loads .proto files (Node.js only, not available in browsers).

/**
 * Synchronously loads proto files (Node.js only)
 * @param filename - Single file path or array of file paths to load
 * @param root - Optional root namespace to load into
 * @returns Root namespace with loaded definitions
 * @throws Error if file syntax is invalid or fetching not supported
 */
function loadSync(filename: string | string[], root?: Root): Root;

Usage Examples:

const protobuf = require("protobufjs");

// Synchronous loading
try {
    const root = protobuf.loadSync("schema.proto");
    const MyMessage = root.lookupType("MyMessage");
} catch (err) {
    console.error("Failed to load proto:", err);
}

// With custom root
const customRoot = new protobuf.Root();
protobuf.loadSync("schema.proto", customRoot);

Root Loading Methods

Methods available on Root instances for loading additional definitions.

class Root extends Namespace {
  /**
   * Loads proto files into this root instance asynchronously
   * @param filename - File path(s) to load
   * @param callback - Callback receiving error and this root
   * @returns This root instance
   */
  load(filename: string | string[], callback: LoadCallback): Root;
  
  /**
   * Loads proto files into this root instance synchronously
   * @param filename - File path(s) to load
   * @returns This root instance
   * @throws Error if file syntax is invalid
   */
  loadSync(filename: string | string[]): Root;
}

Usage Examples:

const root = new protobuf.Root();

// Instance method loading
root.load("schema.proto", function(err, loadedRoot) {
    console.log(loadedRoot === root); // true
    
    // Load additional files into same root
    root.load("additional.proto", function(err) {
        // Both files now available in root
    });
});

// Synchronous instance loading
try {
    root.loadSync("schema.proto");
    root.loadSync("additional.proto");
} catch (err) {
    console.error("Loading failed:", err);  
}

File Format Support

Supported file formats and their characteristics.

// Supported file types:
// - .proto files: Standard protobuf definition files
// - .json files: Preprocessed protobuf definitions in JSON format

interface FileSupport {
  protoFiles: string[];    // Standard .proto syntax files
  jsonFiles: string[];     // Preprocessed JSON descriptor files
  mixedFormats: boolean;   // Can load both formats in single call
}

Usage Examples:

// Loading .proto files
protobuf.load("messages.proto", callback);

// Loading preprocessed JSON
protobuf.load("compiled.json", callback);

// Mixed format loading
protobuf.load(["schema.proto", "compiled.json"], callback);

Error Handling

Common error conditions and handling patterns.

interface LoadError extends Error {
  name: string;           // Error type identifier
  message: string;        // Detailed error message  
  filename?: string;      // File that caused error
  line?: number;          // Line number if parse error
  column?: number;        // Column number if parse error
}

Usage Examples:

protobuf.load("invalid.proto", function(err, root) {
    if (err) {
        console.error("Load failed:", err.message);
        if (err.filename) {
            console.error("File:", err.filename);
        }
        if (err.line) {
            console.error("Line:", err.line, "Column:", err.column);
        }
        return;
    }
    
    // Success - use root
});

Types

interface LoadCallback {
  /**
   * Callback function for async loading operations
   * @param error - Error if loading failed, null on success
   * @param root - Root namespace if loading succeeded
   */
  (error: Error | null, root?: Root): void;
}

Install with Tessl CLI