0
# Protocol Parsing
1

2
Stream-based parsing of PostgreSQL wire protocol messages providing a callback-based interface for handling incoming protocol data.
3

4
## Capabilities
5

6
### Parse Function
7

8
Main entry point for parsing PostgreSQL protocol streams. Attaches to a readable stream and calls the provided callback for each parsed message.
9

10
```typescript { .api }
11
/**
12
 * Parse PostgreSQL protocol messages from a stream
13
 * @param stream - Readable stream containing protocol data
14
 * @param callback - Function called for each parsed message
15
 * @returns Promise that resolves when stream ends
16
 */
17
function parse(
18
  stream: NodeJS.ReadableStream, 
19
  callback: MessageCallback
20
): Promise<void>;
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { parse } from "pg-protocol";
27

28
// Basic stream parsing
29
const callback = (message) => {
30
  switch (message.name) {
31
    case 'dataRow':
32
      console.log('Data row:', message);
33
      break;
34
    case 'commandComplete':
35
      console.log('Command completed:', message.text);
36
      break;
37
    case 'error':
38
      console.error('Database error:', message);
39
      break;
40
  }
41
};
42

43
await parse(stream, callback);
44
```
45

46
### Parser Class (Internal)
47

48
The `Parser` class is used internally by the `parse` function and is not part of the public API. It provides stateful parsing with buffer management for the protocol stream.
49

50
```typescript { .api }
51
/**
52
 * Internal stateful PostgreSQL protocol parser
53
 * Note: This class is not exported and is used internally by the parse function
54
 */
55
class Parser {
56
  /**
57
   * Create a new parser instance
58
   * @param opts - Optional stream options
59
   */
60
  constructor(opts?: StreamOptions);
61
  
62
  /**
63
   * Parse buffer data and call callback for each complete message
64
   * @param buffer - Raw protocol data buffer
65
   * @param callback - Function called for each parsed message
66
   */
67
  parse(buffer: Buffer, callback: MessageCallback): void;
68
}
69

70
interface StreamOptions {
71
  mode?: Mode;
72
}
73
```
74

75
### Message Callback
76

77
Callback function signature for handling parsed protocol messages.
78

79
```typescript { .api }
80
/**
81
 * Callback function for handling parsed protocol messages
82
 * @param msg - Parsed protocol message
83
 */
84
type MessageCallback = (msg: BackendMessage) => void;
85
```
86

87
### Stream Options
88

89
Configuration options for the Parser constructor.
90

91
```typescript { .api }
92
interface StreamOptions {
93
  /** Data format mode - 'text' or 'binary' (binary not yet supported) */
94
  mode?: Mode;
95
}
96
```
97

98
## Error Handling
99

100
The parser handles malformed protocol data by creating `DatabaseError` instances:
101

102
```typescript
103
// Invalid message codes result in DatabaseError
104
const errorMessage = new DatabaseError(
105
  'received invalid response: ' + code.toString(16),
106
  length,
107
  'error'
108
);
109
```
110

111
## Protocol Support
112

113
The parser supports the complete PostgreSQL wire protocol including:
114

115
- Authentication messages (OK, MD5, SASL, etc.)
116
- Query execution messages (DataRow, CommandComplete, etc.)
117
- Prepared statement messages (ParseComplete, BindComplete, etc.)
118
- Administrative messages (ParameterStatus, BackendKeyData, etc.)
119
- Copy protocol messages (CopyIn, CopyOut, CopyData, etc.)
120
- Error and notice messages with detailed field parsing