0
# Proto File Loading
1

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

4
## Capabilities
5

6
### Load Function (Async)
7

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

10
```javascript { .api }
11
/**
12
 * Loads proto files asynchronously with callback
13
 * @param filename - Single file path or array of file paths to load
14
 * @param callback - Callback function receiving error and root
15
 */
16
function load(filename: string | string[], callback: LoadCallback): void;
17

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

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

34
interface LoadCallback {
35
  (error: Error | null, root?: Root): void;
36
}
37
```
38

39
**Usage Examples:**
40

41
```javascript
42
const protobuf = require("protobufjs");
43

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

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

56
// Promise-based usage
57
protobuf.load("schema.proto")
58
    .then(root => {
59
        const MyMessage = root.lookupType("MyMessage");
60
    })
61
    .catch(err => console.error(err));
62

63
// Multiple files
64
protobuf.load(["file1.proto", "file2.proto"], function(err, root) {
65
    // All files loaded into single root namespace
66
});
67
```
68

69
### LoadSync Function (Sync)
70

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

73
```javascript { .api }
74
/**
75
 * Synchronously loads proto files (Node.js only)
76
 * @param filename - Single file path or array of file paths to load
77
 * @param root - Optional root namespace to load into
78
 * @returns Root namespace with loaded definitions
79
 * @throws Error if file syntax is invalid or fetching not supported
80
 */
81
function loadSync(filename: string | string[], root?: Root): Root;
82
```
83

84
**Usage Examples:**
85

86
```javascript
87
const protobuf = require("protobufjs");
88

89
// Synchronous loading
90
try {
91
    const root = protobuf.loadSync("schema.proto");
92
    const MyMessage = root.lookupType("MyMessage");
93
} catch (err) {
94
    console.error("Failed to load proto:", err);
95
}
96

97
// With custom root
98
const customRoot = new protobuf.Root();
99
protobuf.loadSync("schema.proto", customRoot);
100
```
101

102
### Root Loading Methods
103

104
Methods available on Root instances for loading additional definitions.
105

106
```javascript { .api }
107
class Root extends Namespace {
108
  /**
109
   * Loads proto files into this root instance asynchronously
110
   * @param filename - File path(s) to load
111
   * @param callback - Callback receiving error and this root
112
   * @returns This root instance
113
   */
114
  load(filename: string | string[], callback: LoadCallback): Root;
115
  
116
  /**
117
   * Loads proto files into this root instance synchronously
118
   * @param filename - File path(s) to load
119
   * @returns This root instance
120
   * @throws Error if file syntax is invalid
121
   */
122
  loadSync(filename: string | string[]): Root;
123
}
124
```
125

126
**Usage Examples:**
127

128
```javascript
129
const root = new protobuf.Root();
130

131
// Instance method loading
132
root.load("schema.proto", function(err, loadedRoot) {
133
    console.log(loadedRoot === root); // true
134
    
135
    // Load additional files into same root
136
    root.load("additional.proto", function(err) {
137
        // Both files now available in root
138
    });
139
});
140

141
// Synchronous instance loading
142
try {
143
    root.loadSync("schema.proto");
144
    root.loadSync("additional.proto");
145
} catch (err) {
146
    console.error("Loading failed:", err);  
147
}
148
```
149

150
### File Format Support
151

152
Supported file formats and their characteristics.
153

154
```javascript { .api }
155
// Supported file types:
156
// - .proto files: Standard protobuf definition files
157
// - .json files: Preprocessed protobuf definitions in JSON format
158

159
interface FileSupport {
160
  protoFiles: string[];    // Standard .proto syntax files
161
  jsonFiles: string[];     // Preprocessed JSON descriptor files
162
  mixedFormats: boolean;   // Can load both formats in single call
163
}
164
```
165

166
**Usage Examples:**
167

168
```javascript
169
// Loading .proto files
170
protobuf.load("messages.proto", callback);
171

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

175
// Mixed format loading
176
protobuf.load(["schema.proto", "compiled.json"], callback);
177
```
178

179
### Error Handling
180

181
Common error conditions and handling patterns.
182

183
```javascript { .api }
184
interface LoadError extends Error {
185
  name: string;           // Error type identifier
186
  message: string;        // Detailed error message  
187
  filename?: string;      // File that caused error
188
  line?: number;          // Line number if parse error
189
  column?: number;        // Column number if parse error
190
}
191
```
192

193
**Usage Examples:**
194

195
```javascript
196
protobuf.load("invalid.proto", function(err, root) {
197
    if (err) {
198
        console.error("Load failed:", err.message);
199
        if (err.filename) {
200
            console.error("File:", err.filename);
201
        }
202
        if (err.line) {
203
            console.error("Line:", err.line, "Column:", err.column);
204
        }
205
        return;
206
    }
207
    
208
    // Success - use root
209
});
210
```
211

212
## Types
213

214
```javascript { .api }
215
interface LoadCallback {
216
  /**
217
   * Callback function for async loading operations
218
   * @param error - Error if loading failed, null on success
219
   * @param root - Root namespace if loading succeeded
220
   */
221
  (error: Error | null, root?: Root): void;
222
}
223
```