0
# PBF
1

2
A low-level, lightweight protocol buffers implementation for JavaScript with high-performance binary serialization and deserialization capabilities. PBF provides ultra-fast encoding and decoding of protocol buffer messages, supporting both Node.js and browser environments with lazy decoding and custom reading/writing functions.
3

4
## Package Information
5

6
- **Package Name**: pbf
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install pbf`
10
- **Size**: 3KB gzipped
11
- **Environments**: Node.js, Browser
12

13
## Core Imports
14

15
ESM (ES6 modules):
16
```typescript
17
import Pbf from "pbf";
18
import { compile, compileRaw } from "pbf/compile";
19
```
20

21
CommonJS:
22
```javascript
23
const Pbf = require("pbf");
24
const { compile, compileRaw } = require("pbf/compile");
25
```
26

27
## Basic Usage
28

29
### Reading Protocol Buffer Data
30

31
```typescript
32
import Pbf from "pbf";
33

34
// Read from buffer
35
const pbf = new Pbf(buffer);
36
const data = pbf.readFields(readDataField, {});
37

38
function readDataField(tag, data, pbf) {
39
    if (tag === 1) data.name = pbf.readString();
40
    else if (tag === 2) data.version = pbf.readVarint();
41
}
42
```
43

44
### Writing Protocol Buffer Data
45

46
```typescript
47
import Pbf from "pbf";
48

49
// Write to buffer
50
const pbf = new Pbf();
51
writeData(data, pbf);
52
const buffer = pbf.finish();
53

54
function writeData(data, pbf) {
55
    pbf.writeStringField(1, data.name);
56
    pbf.writeVarintField(2, data.version);
57
}
58
```
59

60
## Architecture
61

62
PBF provides three main interfaces:
63

64
1. **Low-level API** - Direct buffer manipulation for custom protocols
65
2. **Schema Compilation** - Generate optimized read/write functions from .proto files
66
3. **CLI Tool** - Command-line proto-to-JavaScript compilation
67

68
## Capabilities
69

70
### Buffer Reading and Writing
71

72
Core protocol buffer reading and writing functionality with support for all protocol buffer data types and packed fields.
73

74
```typescript { .api }
75
class Pbf {
76
    constructor(buf?: Uint8Array | ArrayBuffer);
77
    
78
    // Buffer state and data
79
    buf: Uint8Array;
80
    dataView: DataView;
81
    pos: number;
82
    type: number;
83
    length: number;
84
    
85
    // Field-level reading
86
    readFields<T>(readField: (tag: number, result: T, pbf: Pbf) => void, result: T, end?: number): T;
87
    readMessage<T>(readField: (tag: number, result: T, pbf: Pbf) => void, result: T): T;
88
    
89
    // Basic data type reading
90
    readVarint(isSigned?: boolean): number;
91
    readString(): string;
92
    readBytes(): Uint8Array;
93
    readBoolean(): boolean;
94
    
95
    // Buffer management
96
    realloc(min: number): void;
97
    finish(): Uint8Array;
98
    
99
    // Basic data type writing
100
    writeVarint(val: number): void;
101
    writeString(str: string): void;
102
    writeBytes(buffer: Uint8Array): void;
103
    writeBoolean(val: boolean): void;
104
}
105
```
106

107
[Buffer Reading and Writing](./buffer-operations.md)
108

109
### Schema Compilation
110

111
Compile protocol buffer schema files (.proto) into optimized JavaScript read/write functions.
112

113
```typescript { .api }
114
interface CompileOptions {
115
    dev?: boolean;
116
    legacy?: boolean;
117
    noRead?: boolean;
118
    noWrite?: boolean;
119
}
120

121
// Compile schema to executable functions
122
function compile(proto: object): Record<string, Function>;
123

124
// Compile schema to raw JavaScript code
125
function compileRaw(proto: object, options?: CompileOptions): string;
126
```
127

128
[Schema Compilation](./schema-compilation.md)
129

130
### CLI Tool
131

132
Command-line interface for compiling .proto files to JavaScript modules.
133

134
```bash
135
# Basic compilation
136
pbf example.proto > example.js
137

138
# Options
139
pbf example.proto --no-read --legacy
140
```
141

142
[CLI Tool](./cli-tool.md)
143

144
## Types
145

146
```typescript { .api }
147
// Field reading callback function
148
interface FieldReader<T> {
149
    (tag: number, result: T, pbf: Pbf): void;
150
}
151

152
// Compilation options
153
interface CompileOptions {
154
    dev?: boolean;        // Include development mode features
155
    legacy?: boolean;     // Generate CommonJS instead of ESM
156
    noRead?: boolean;     // Skip generating read functions
157
    noWrite?: boolean;    // Skip generating write functions
158
}
159

160
// Protocol buffer field types
161
type PBFType = 
162
    | 'string'
163
    | 'float' | 'double'
164
    | 'bool'
165
    | 'uint32' | 'uint64'
166
    | 'int32' | 'int64'
167
    | 'sint32' | 'sint64'
168
    | 'fixed32' | 'fixed64'
169
    | 'sfixed32' | 'sfixed64'
170
    | 'bytes';
171

172
// Wire format constants
173
declare const PBF_VARINT: 0;
174
declare const PBF_FIXED64: 1;
175
declare const PBF_BYTES: 2;
176
declare const PBF_FIXED32: 5;
177
```