0
# msgpackr
1

2
msgpackr is an ultra-fast MessagePack implementation for JavaScript/NodeJS that provides high-performance binary data serialization and deserialization. It offers significant speed improvements over JSON and other MessagePack implementations through optimized algorithms and optional native acceleration. The library supports structured cloning, record structure extensions for compact encoding, and streaming functionality across multiple runtime environments.
3

4
## Package Information
5

6
- **Package Name**: msgpackr
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install msgpackr`
10

11
## Core Imports
12

13
Basic imports (works in all environments):
14

15
```javascript
16
import { pack, unpack, Packr, Unpackr } from "msgpackr";
17
```
18

19
Node.js imports (includes streaming and native acceleration):
20

21
```javascript
22
import { pack, unpack, Packr, Unpackr, PackrStream, UnpackrStream } from "msgpackr";
23
```
24

25
For individual functionality:
26

27
```javascript
28
import { pack, encode } from "msgpackr/pack";
29
import { unpack, decode, unpackMultiple } from "msgpackr/unpack";
30
```
31

32
CommonJS:
33

34
```javascript
35
const { pack, unpack, Packr, Unpackr, PackrStream, UnpackrStream } = require("msgpackr");
36
```
37

38
## Basic Usage
39

40
```javascript
41
import { pack, unpack } from "msgpackr";
42

43
// Basic serialization
44
const data = { name: "Alice", age: 25, tags: ["user", "active"] };
45
const packed = pack(data);
46
const unpacked = unpack(packed);
47

48
// Using class instances for advanced features
49
import { Packr } from "msgpackr";
50
const packr = new Packr({ useRecords: true });
51
const serialized = packr.pack(data);
52
const deserialized = packr.unpack(serialized);
53
```
54

55
## Architecture
56

57
msgpackr is built around several key components:
58

59
- **Core Functions**: Standalone `pack`/`unpack` functions for basic MessagePack operations
60
- **Class-based API**: `Packr`/`Unpackr` classes providing configurable instances with advanced features
61
- **Record Extensions**: Automatic structure sharing for optimized encoding of repeated object structures
62
- **Streaming Interface**: Transform streams for continuous data processing
63
- **Iterator Support**: Lazy processing capabilities for large datasets
64
- **Native Acceleration**: Optional native addon for maximum performance
65
- **Multi-platform Support**: Browser, Node.js, Deno, and Bun compatibility
66

67
## Capabilities
68

69
### Core Packing and Unpacking
70

71
Basic MessagePack serialization and deserialization with high-performance implementations.
72

73
```javascript { .api }
74
function pack(value: any, encodeOptions?: number): Buffer;
75
function encode(value: any, encodeOptions?: number): Buffer;
76
function unpack(messagePack: Buffer | Uint8Array, options?: UnpackOptions): any;
77
function decode(messagePack: Buffer | Uint8Array, options?: UnpackOptions): any;
78
function unpackMultiple(messagePack: Buffer | Uint8Array): any[];
79

80
type UnpackOptions = { start?: number; end?: number; lazy?: boolean; } | number;
81
```
82

83
[Core Operations](./core-operations.md)
84

85
### Advanced Packr and Unpackr Classes
86

87
Configurable class instances providing advanced features like record structures, structured cloning, and custom extensions.
88

89
```javascript { .api }
90
class Packr extends Unpackr {
91
  constructor(options?: Options);
92
  pack(value: any, encodeOptions?: number): Buffer;
93
  encode(value: any, encodeOptions?: number): Buffer;
94
  useBuffer(buffer: Buffer | Uint8Array): void;
95
  clearSharedData(): void;
96
}
97

98
class Unpackr {
99
  constructor(options?: Options);
100
  unpack(messagePack: Buffer | Uint8Array, options?: UnpackOptions): any;
101
  decode(messagePack: Buffer | Uint8Array, options?: UnpackOptions): any;
102
  unpackMultiple(messagePack: Buffer | Uint8Array): any[];
103
}
104

105
interface Options {
106
  useFloat32?: FLOAT32_OPTIONS;
107
  useRecords?: boolean | ((value: any) => boolean);
108
  structures?: {}[];
109
  moreTypes?: boolean;
110
  sequential?: boolean;
111
  structuredClone?: boolean;
112
  mapsAsObjects?: boolean;
113
  // ... additional options
114
}
115
```
116

117
[Advanced Classes](./advanced-classes.md)
118

119
### Streaming Operations
120

121
Transform streams for processing continuous data flows with automatic MessagePack encoding/decoding.
122

123
```javascript { .api }
124
class PackrStream extends Transform {
125
  constructor(options?: Options | StreamOptions);
126
}
127

128
class UnpackrStream extends Transform {
129
  constructor(options?: Options | StreamOptions);
130
}
131
```
132

133
[Streaming](./streaming.md)
134

135
### Iterator-based Processing
136

137
Lazy evaluation support for processing large datasets efficiently.
138

139
```javascript { .api }
140
function packIter(
141
  objectIterator: Iterable | AsyncIterable, 
142
  options?: Options
143
): IterableIterator | AsyncIterableIterator;
144

145
function unpackIter(
146
  bufferIterator: Iterable | AsyncIterable, 
147
  options?: Options
148
): IterableIterator | AsyncIterableIterator;
149

150
// Aliases
151
const encodeIter: typeof packIter;
152
const decodeIter: typeof unpackIter;
153
```
154

155
[Iterator Support](./iterators.md)
156

157
### Extensions and Customization
158

159
Custom MessagePack extensions and utility functions for specialized use cases.
160

161
```javascript { .api }
162
function addExtension(extension: Extension): void;
163
function clearSource(): void;
164
function roundFloat32(float32Number: number): number;
165

166
interface Extension {
167
  Class?: Function;
168
  type?: number;
169
  pack?(value: any): Buffer | Uint8Array;
170
  unpack?(messagePack: Buffer | Uint8Array): any;
171
  read?(datum: any): any;
172
  write?(instance: any): any;
173
}
174
```
175

176
[Extensions](./extensions.md)
177

178
## Types
179

180
```javascript { .api }
181
enum FLOAT32_OPTIONS {
182
  NEVER = 0,
183
  ALWAYS = 1,
184
  DECIMAL_ROUND = 3,
185
  DECIMAL_FIT = 4
186
}
187

188
// Individual Float32 option constants (also exported separately)
189
const NEVER: 0;
190
const ALWAYS: 1;
191
const DECIMAL_ROUND: 3;
192
const DECIMAL_FIT: 4;
193

194
// Buffer mode constants
195
const REUSE_BUFFER_MODE: number;
196
const RESET_BUFFER_MODE: number;
197
const RESERVE_START_SPACE: number;
198

199
// Utility constants
200
const C1: {};
201
let isNativeAccelerationEnabled: boolean;
202

203
// Configuration defaults for main module
204
const useRecords: false;
205
const mapsAsObjects: true;
206
```