@epochlab/epoch-protos

Browser-compatible TypeScript/JavaScript library for EpochFolio Protocol Buffers. This package provides fully typed protobuf definitions with encode/decode functionality that works in both Node.js and browser environments.

Installation

npm install @epochlab/epoch-protos

or

yarn add @epochlab/epoch-protos

Features

• ✅ Browser-Compatible: Works in all modern browsers without polyfills
• ✅ TypeScript Support: Full TypeScript definitions included
• ✅ Tree-Shakeable: Optimized for minimal bundle size
• ✅ Multiple Formats: CommonJS, ESM, and minified browser builds
• ✅ Static Code Generation: Uses protobufjs static code for optimal performance
• ✅ No Node.js Dependencies: Pure JavaScript implementation
• ✅ Full Encode/Decode: Both encoding and decoding of protobuf messages

Usage

Browser (ES Modules)

import * as EpochProtos from '@epochlab/epoch-protos';

// Decode binary protobuf data
const binaryData = new Uint8Array([...]); // Your protobuf binary
const decoded = EpochProtos.epoch_proto.CardDef.decode(binaryData);

console.log(decoded);

Node.js (CommonJS)

const EpochProtos = require('@epochlab/epoch-protos');

// Decode binary protobuf data
const binaryData = Buffer.from([...]); // Your protobuf binary
const decoded = EpochProtos.epoch_proto.CardDef.decode(binaryData);

console.log(decoded);

TypeScript

import * as EpochProtos from '@epochlab/epoch-protos';
import type { Table, ChartDef, CardDef } from '@epochlab/epoch-protos';

// Full type safety
const table: Table = EpochProtos.epoch_proto.Table.decode(binaryData);

Available Message Types

Core Types

• CardDef - Dashboard card definitions
• CardData - Individual card data
• ChartDef - Chart definitions (supports multiple chart types)
• Table - Table data with schema
• TearSheet - Complete dashboard definition
• FullTearSheet - Extended dashboard with additional metadata

Chart Types

• BarDef - Bar chart definition
• LinesDef - Line chart definition
• HeatMapDef - Heatmap visualization
• HistogramDef - Histogram data
• BoxPlotDef - Box plot statistics
• XRangeDef - Range chart data
• PieDef - Pie chart definition

Supporting Types

• ColumnDef - Table column schema
• TableData - Table row data
• TableRow - Individual table row
• Scalar - Multi-type value container
• EpochFolioDashboardWidget - Widget type enumeration
• EpochFolioType - Data type enumeration
• AxisType - Axis configuration

Examples

Decoding a Table

import * as EpochProtos from '@epochlab/epoch-protos';

async function decodeTableFromAPI(url) {
  // Fetch binary protobuf data
  const response = await fetch(url, {
    headers: { 'Accept': 'application/x-protobuf' }
  });
  
  const arrayBuffer = await response.arrayBuffer();
  const binaryData = new Uint8Array(arrayBuffer);
  
  // Decode the protobuf
  const table = EpochProtos.epoch_proto.Table.decode(binaryData);
  
  console.log('Table:', {
    title: table.title,
    columns: table.columns,
    rows: table.data?.rows?.length
  });
  
  return table;
}

Creating and Encoding Messages

import * as EpochProtos from '@epochlab/epoch-protos';

function createTable() {
  const { Table, ColumnDef, TableData, TableRow, Scalar } = EpochProtos.epoch_proto;
  
  // Create a table message
  const table = Table.create({
    type: 0, // EpochFolioDashboardWidget.TABLE
    category: 'financial',
    title: 'Portfolio Performance',
    columns: [
      ColumnDef.create({
        id: 'ticker',
        name: 'Ticker',
        type: 0 // EpochFolioType.STRING
      }),
      ColumnDef.create({
        id: 'price',
        name: 'Price',
        type: 1 // EpochFolioType.DOUBLE
      })
    ],
    data: TableData.create({
      rows: [
        TableRow.create({
          values: [
            Scalar.create({ stringValue: 'AAPL' }),
            Scalar.create({ doubleValue: 150.25 })
          ]
        })
      ]
    })
  });
  
  // Encode to binary
  const buffer = Table.encode(table).finish();
  return buffer; // Uint8Array
}

React/Next.js Integration

import { useEffect, useState } from 'react';
import * as EpochProtos from '@epochlab/epoch-protos';

function useProtobufData(url, MessageType) {
  const [data, setData] = useState(null);
  
  useEffect(() => {
    fetch(url, { headers: { 'Accept': 'application/x-protobuf' } })
      .then(res => res.arrayBuffer())
      .then(buffer => {
        const decoded = MessageType.decode(new Uint8Array(buffer));
        setData(decoded);
      });
  }, [url]);
  
  return data;
}

// Usage in component
function Dashboard() {
  const table = useProtobufData('/api/table', EpochProtos.epoch_proto.Table);
  
  if (!table) return <div>Loading...</div>;
  
  return (
    <div>
      <h1>{table.title}</h1>
      {/* Render table data */}
    </div>
  );
}

Bundle Sizes

• CommonJS: ~236KB (uncompressed)
• ESM: ~234KB (uncompressed)
• Minified: ~121KB (compressed)

The library is tree-shakeable, so your final bundle will only include the message types you actually use.

Browser Support

• Chrome 60+
• Firefox 60+
• Safari 12+
• Edge 79+
• Node.js 16+

Development

Building from Source

# Install dependencies
npm install

# Generate protobuf code
npm run generate:protos

# Build bundles
npm run build:bundles

# Run tests
npm test

Publishing to NPM

# Build and test
npm run build
npm test

# Publish to NPM (requires authentication)
npm publish --access public

# Or use the dedicated NPM publish script
./scripts/publish-npm.sh

# For a dry run to see what would be published
./scripts/publish-npm.sh dry-run

Project Structure

typescript_package/
├── proto/          # Protocol buffer definitions
├── src/            # Generated source code
├── dist/           # Built bundles
├── test/           # Test files
├── examples/       # Usage examples
└── scripts/        # Build scripts

API Reference

Static Methods

Each message type provides these static methods:

• create(properties?) - Create a new message instance
• encode(message) - Encode a message to a writer
• decode(reader) - Decode a message from binary
• verify(message) - Verify a message object
• fromObject(object) - Create from a plain object
• toObject(message) - Convert to a plain object

Example

const { Table } = EpochProtos.epoch_proto;

// Create
const table = Table.create({ title: 'My Table' });

// Encode
const buffer = Table.encode(table).finish();

// Decode
const decoded = Table.decode(buffer);

// Verify
const error = Table.verify(decoded);
if (error) throw Error(error);

// Convert to plain object
const plain = Table.toObject(decoded);

Version Compatibility

• 1.0.3 - Current version with full browser support and decode functionality
• 1.0.0-1.0.2 - Initial releases (deprecated)

License

MIT

Support

For issues and feature requests, please visit: GitHub Issues

Credits

Built with protobuf.js for optimal browser compatibility.