0
# Jest Serializer
1

2
Jest Serializer is a module for serializing and deserializing JavaScript objects using Node.js v8 APIs. It provides both in-memory serialization functions that work with Buffer objects and synchronous filesystem functions for persistent storage. The library leverages v8's native serialization capabilities to handle complex JavaScript types that JSON cannot serialize, including Map, Set, undefined, NaN, and other advanced types.
3

4
**Note:** This package is deprecated. Use Node.js v8 APIs directly: https://nodejs.org/api/v8.html#serialization-api
5

6
## Package Information
7

8
- **Package Name**: jest-serializer
9
- **Package Type**: npm
10
- **Language**: TypeScript
11
- **Installation**: `npm install jest-serializer`
12
- **Version**: 28.0.0
13
- **License**: MIT
14

15
## Core Imports
16

17
```typescript
18
import { serialize, deserialize, readFileSync, writeFileSync } from "jest-serializer";
19
```
20

21
For CommonJS:
22

23
```javascript
24
const { serialize, deserialize, readFileSync, writeFileSync } = require("jest-serializer");
25
```
26

27
Default import (object containing all functions):
28

29
```typescript
30
import serializer from "jest-serializer";
31
```
32

33
## Basic Usage
34

35
```typescript
36
import { serialize, deserialize, readFileSync, writeFileSync } from "jest-serializer";
37

38
// In-memory serialization
39
const myObject = {
40
  foo: 'bar',
41
  baz: [0, true, '2', [], {}],
42
  special: { map: new Map([[NaN, 4]]), set: new Set([undefined, NaN]) }
43
};
44

45
const buffer = serialize(myObject);
46
const restored = deserialize(buffer);
47

48
// Filesystem serialization
49
const filePath = '/tmp/my-data';
50
writeFileSync(filePath, myObject);
51
const restoredFromFile = readFileSync(filePath);
52
```
53

54
## Capabilities
55

56
### In-Memory Serialization
57

58
Converts JavaScript objects to/from Buffer objects using Node.js v8 serialization APIs.
59

60
```typescript { .api }
61
/**
62
 * Serializes a JavaScript value to a Buffer using v8.serialize
63
 * @param content - Any JavaScript value to serialize
64
 * @returns Buffer containing serialized data
65
 */
66
function serialize(content: unknown): Buffer;
67

68
/**
69
 * Deserializes a Buffer back to a JavaScript value using v8.deserialize
70
 * @param buffer - Buffer containing v8-serialized data
71
 * @returns Deserialized JavaScript value
72
 * @throws Error if buffer contains invalid serialization data
73
 */
74
function deserialize(buffer: Buffer): unknown;
75
```
76

77
**Usage Examples:**
78

79
```typescript
80
import { serialize, deserialize } from "jest-serializer";
81

82
// Serialize complex data structures
83
const complexData = {
84
  number: 42,
85
  string: "hello",
86
  date: new Date(),
87
  map: new Map([["key1", "value1"], [NaN, "nan-value"]]),
88
  set: new Set([1, 2, undefined]),
89
  buffer: Buffer.from([1, 2, 3])
90
};
91

92
const serialized = serialize(complexData);
93
console.log(serialized); // <Buffer 1f 2d ...>
94

95
const deserialized = deserialize(serialized);
96
console.log(deserialized); // Original object restored with all types preserved
97
```
98

99
### Filesystem Serialization
100

101
Synchronously reads/writes serialized objects to/from the filesystem.
102

103
```typescript { .api }
104
/**
105
 * Synchronously writes a serialized object to the filesystem
106
 * @param filePath - Path where to write the serialized file
107
 * @param content - Any JavaScript value to serialize and write
108
 * @returns void
109
 * @throws Error for filesystem errors (permission, path issues, etc.)
110
 */
111
function writeFileSync(filePath: string, content: unknown): void;
112

113
/**
114
 * Synchronously reads and deserializes an object from the filesystem
115
 * @param filePath - Path to the file to read and deserialize
116
 * @returns Deserialized JavaScript value
117
 * @throws Error if file doesn't exist, permission errors, or invalid serialized data
118
 */
119
function readFileSync(filePath: string): unknown;
120
```
121

122
**Usage Examples:**
123

124
```typescript
125
import { readFileSync, writeFileSync } from "jest-serializer";
126

127
// Save application state to disk
128
const applicationState = {
129
  user: { id: 123, preferences: new Map([["theme", "dark"]]) },
130
  cache: new Set(["item1", "item2"]),
131
  timestamp: new Date()
132
};
133

134
const stateFile = "./app-state.data";
135
writeFileSync(stateFile, applicationState);
136

137
// Restore application state later
138
const restoredState = readFileSync(stateFile);
139
console.log(restoredState.user.preferences instanceof Map); // true
140
```
141

142
### Default Export
143

144
The package also provides a default export containing all functions as an object.
145

146
```typescript { .api }
147
interface SerializerInterface {
148
  serialize: (content: unknown) => Buffer;
149
  deserialize: (buffer: Buffer) => unknown;
150
  writeFileSync: (filePath: string, content: unknown) => void;
151
  readFileSync: (filePath: string) => unknown;
152
}
153

154
declare const serializer: SerializerInterface;
155
export default serializer;
156
```
157

158
**Usage Example:**
159

160
```typescript
161
import serializer from "jest-serializer";
162

163
const data = { test: "value" };
164
const buffer = serializer.serialize(data);
165
const restored = serializer.deserialize(buffer);
166

167
serializer.writeFileSync("./data.bin", data);
168
const fromFile = serializer.readFileSync("./data.bin");
169
```
170

171
## Supported Data Types
172

173
Jest Serializer supports all data types that Node.js v8 serialization can handle:
174

175
- **Primitives**: `number`, `string`, `boolean`, `null`, `undefined`, `BigInt`
176
- **Objects**: Plain objects, arrays
177
- **Special Values**: `NaN`, `Infinity`, `-Infinity`
178
- **Built-in Objects**: `Date`, `RegExp`, `Map`, `Set`, `Buffer`, `ArrayBuffer`, typed arrays
179
- **Complex Structures**: Nested objects and arrays with any combination of above types
180

181
## Error Handling
182

183
Functions may throw errors in the following cases:
184

185
- **`deserialize(buffer)`**: Throws if the buffer contains invalid v8 serialization data
186
- **`readFileSync(filePath)`**: Throws for file system errors (file not found, permission denied) or invalid serialization data
187
- **`writeFileSync(filePath, content)`**: Throws for file system errors (path not writable, disk full, permission denied)
188

189
```typescript
190
import { deserialize, readFileSync } from "jest-serializer";
191

192
try {
193
  const invalidBuffer = Buffer.from([0, 85, 170, 255]);
194
  deserialize(invalidBuffer); // Throws error
195
} catch (error) {
196
  console.error("Invalid serialization data:", error.message);
197
}
198

199
try {
200
  readFileSync("./nonexistent-file.data"); // Throws error
201
} catch (error) {
202
  console.error("File read error:", error.message);
203
}
204
```
205

206
## Dependencies
207

208
- **graceful-fs**: Robust filesystem operations (used internally for file I/O)
209
- **@types/node**: TypeScript definitions for Node.js APIs