0
# Core Operations
1

2
Basic MessagePack serialization and deserialization functions providing high-performance encoding and decoding of JavaScript values to/from binary MessagePack format.
3

4
## Capabilities
5

6
### Pack Function
7

8
Serializes a JavaScript value to MessagePack binary format using the default packr instance.
9

10
```javascript { .api }
11
/**
12
 * Serializes a JavaScript value to MessagePack binary format
13
 * @param value - The value to serialize
14
 * @param encodeOptions - Optional encoding options (buffer mode flags)
15
 * @returns Buffer containing the MessagePack encoded data
16
 */
17
function pack(value: any, encodeOptions?: number): Buffer;
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
import { pack } from "msgpackr";
24

25
// Basic serialization
26
const data = { name: "Alice", age: 25, active: true };
27
const packed = pack(data);
28

29
// With arrays and nested objects
30
const complex = {
31
  users: [
32
    { id: 1, name: "Alice" },
33
    { id: 2, name: "Bob" }
34
  ],
35
  metadata: { version: "1.0", timestamp: new Date() }
36
};
37
const packedComplex = pack(complex);
38

39
// With buffer mode options
40
const packedWithOptions = pack(data, REUSE_BUFFER_MODE);
41
```
42

43
### Encode Function
44

45
Alias for the pack function, providing the same functionality with alternative naming.
46

47
```javascript { .api }
48
/**
49
 * Alias for pack - serializes a JavaScript value to MessagePack binary format
50
 * @param value - The value to serialize
51
 * @param encodeOptions - Optional encoding options (buffer mode flags)
52
 * @returns Buffer containing the MessagePack encoded data
53
 */
54
function encode(value: any, encodeOptions?: number): Buffer;
55
```
56

57
### Unpack Function
58

59
Deserializes MessagePack binary data back to JavaScript values using the default unpackr instance.
60

61
```javascript { .api }
62
/**
63
 * Deserializes MessagePack binary data back to JavaScript values
64
 * @param messagePack - Buffer or Uint8Array containing MessagePack data
65
 * @param options - Optional unpacking options or byte offset
66
 * @returns The deserialized JavaScript value
67
 */
68
function unpack(messagePack: Buffer | Uint8Array, options?: UnpackOptions): any;
69

70
type UnpackOptions = { 
71
  start?: number;    // Starting byte offset
72
  end?: number;      // Ending byte offset  
73
  lazy?: boolean;    // Enable lazy unpacking
74
} | number;          // Or just a numeric offset
75
```
76

77
**Usage Examples:**
78

79
```javascript
80
import { unpack } from "msgpackr";
81

82
// Basic deserialization
83
const packed = /* MessagePack buffer */;
84
const data = unpack(packed);
85

86
// With byte range options
87
const partialData = unpack(packed, { start: 10, end: 50 });
88

89
// With numeric offset
90
const offsetData = unpack(packed, 10);
91

92
// With lazy unpacking
93
const lazyData = unpack(packed, { lazy: true });
94
```
95

96
### Decode Function
97

98
Alias for the unpack function, providing the same functionality with alternative naming.
99

100
```javascript { .api }
101
/**
102
 * Alias for unpack - deserializes MessagePack binary data back to JavaScript values
103
 * @param messagePack - Buffer or Uint8Array containing MessagePack data
104
 * @param options - Optional unpacking options or byte offset
105
 * @returns The deserialized JavaScript value
106
 */
107
function decode(messagePack: Buffer | Uint8Array, options?: UnpackOptions): any;
108
```
109

110
### Unpack Multiple Function
111

112
Deserializes multiple MessagePack values from a single buffer, either returning an array or processing via callback.
113

114
```javascript { .api }
115
/**
116
 * Deserializes multiple MessagePack values from a single buffer
117
 * @param messagePack - Buffer containing multiple MessagePack encoded values
118
 * @returns Array of deserialized values
119
 */
120
function unpackMultiple(messagePack: Buffer | Uint8Array): any[];
121

122
/**
123
 * Deserializes multiple MessagePack values with callback processing
124
 * @param messagePack - Buffer containing multiple MessagePack encoded values
125
 * @param forEach - Callback function called for each unpacked value
126
 */
127
function unpackMultiple(
128
  messagePack: Buffer | Uint8Array, 
129
  forEach: (value: any, start?: number, end?: number) => any
130
): void;
131
```
132

133
**Usage Examples:**
134

135
```javascript
136
import { unpackMultiple } from "msgpackr";
137

138
// Unpack to array
139
const buffer = /* Buffer with multiple MessagePack values */;
140
const values = unpackMultiple(buffer);
141
console.log(values); // [value1, value2, value3, ...]
142

143
// Process with callback
144
unpackMultiple(buffer, (value, start, end) => {
145
  console.log(`Value: ${value}, range: ${start}-${end}`);
146
  // Process each value individually
147
});
148

149
// Stream-like processing
150
const results = [];
151
unpackMultiple(buffer, (value) => {
152
  if (value.type === 'important') {
153
    results.push(value);
154
  }
155
});
156
```
157

158
## Error Handling
159

160
The core functions may throw errors in the following scenarios:
161

162
- **Invalid MessagePack data**: When the input buffer contains malformed MessagePack data
163
- **Buffer underrun**: When the buffer ends unexpectedly during unpacking
164
- **Type errors**: When trying to pack unsupported JavaScript values
165
- **Memory errors**: When buffers are too large or system memory is exhausted
166

167
```javascript
168
import { pack, unpack } from "msgpackr";
169

170
try {
171
  const packed = pack(someData);
172
  const unpacked = unpack(packed);
173
} catch (error) {
174
  if (error.incomplete) {
175
    // Handle incomplete MessagePack data
176
    console.log('Incomplete data at position:', error.lastPosition);
177
    console.log('Partial values:', error.values);
178
  } else {
179
    // Handle other errors
180
    console.error('Packing/unpacking error:', error.message);
181
  }
182
}
183
```
184

185
## Constants
186

187
```javascript { .api }
188
const REUSE_BUFFER_MODE: number;     // Reuse internal buffers for performance
189
const RESET_BUFFER_MODE: number;    // Reset buffers between operations
190
const RESERVE_START_SPACE: number;  // Reserve space at buffer start
191
```