0
# Compression Operations
1

2
High-performance data compression using the deflate algorithm with support for raw deflate, standard deflate with wrapper, and gzip formats. Provides both one-shot function API and streaming class API for different use cases.
3

4
## Capabilities
5

6
### Deflate Function
7

8
Compresses data using the deflate algorithm with optional wrapper.
9

10
```javascript { .api }
11
/**
12
 * Compress data with deflate algorithm
13
 * @param input - Data to compress (string, Uint8Array, or ArrayBuffer)
14
 * @param options - Compression options
15
 * @returns Compressed data as Uint8Array
16
 */
17
function deflate(input: Uint8Array | ArrayBuffer | string, options?: DeflateOptions): Uint8Array;
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
import { deflate } from 'pako';
24

25
// Compress string
26
const text = "Hello World!";
27
const compressed = deflate(text);
28

29
// Compress with options
30
const compressedFast = deflate(text, { level: 1 }); // Fast compression
31
const compressedBest = deflate(text, { level: 9 }); // Best compression
32

33
// Compress binary data
34
const binaryData = new Uint8Array([1, 2, 3, 4, 5]);
35
const compressedBinary = deflate(binaryData);
36
```
37

38
### Deflate Raw Function
39

40
Compresses data using raw deflate format (no wrapper/header).
41

42
```javascript { .api }
43
/**
44
 * Compress data with raw deflate (no wrapper/header)
45
 * @param input - Data to compress (string, Uint8Array, or ArrayBuffer)
46
 * @param options - Compression options (raw: true is automatically set)
47
 * @returns Compressed data as Uint8Array
48
 */
49
function deflateRaw(input: Uint8Array | ArrayBuffer | string, options?: DeflateOptions): Uint8Array;
50
```
51

52
**Usage Examples:**
53

54
```javascript
55
import { deflateRaw } from 'pako';
56

57
// Raw deflate compression
58
const text = "Hello World!";
59
const compressed = deflateRaw(text);
60

61
// With custom window size
62
const compressedCustom = deflateRaw(text, { windowBits: 12 });
63
```
64

65
### Gzip Function
66

67
Compresses data using gzip format with optional custom headers.
68

69
```javascript { .api }
70
/**
71
 * Compress data with gzip format
72
 * @param input - Data to compress (string, Uint8Array, or ArrayBuffer)
73
 * @param options - Compression options (gzip: true is automatically set)
74
 * @returns Compressed data as Uint8Array in gzip format
75
 */
76
function gzip(input: Uint8Array | ArrayBuffer | string, options?: DeflateOptions): Uint8Array;
77
```
78

79
**Usage Examples:**
80

81
```javascript
82
import { gzip } from 'pako';
83

84
// Basic gzip compression
85
const text = "Hello World!";
86
const compressed = gzip(text);
87

88
// Gzip with custom header
89
const compressedWithHeader = gzip(text, {
90
  header: {
91
    name: 'hello.txt',
92
    comment: 'Sample file',
93
    time: Date.now(),
94
    text: true
95
  }
96
});
97
```
98

99
### Deflate Class
100

101
Streaming compression interface for processing large data in chunks.
102

103
```javascript { .api }
104
/**
105
 * Generic streaming wrapper for zlib deflate operations (compression)
106
 * @param options - Compression options
107
 */
108
class Deflate {
109
  constructor(options?: DeflateOptions);
110
  
111
  /** Final compressed output (available after completion) */
112
  result: Uint8Array;
113
  
114
  /** Error code (0 = success) */
115
  err: number;
116
  
117
  /** Error message */
118
  msg: string;
119
  
120
  /** Internal output chunks */
121
  chunks: Array<Uint8Array>;
122
  
123
  /** Whether compression has ended */
124
  ended: boolean;
125
  
126
  /** Configuration options */
127
  options: DeflateOptions;
128
  
129
  /** Internal zlib stream structure */
130
  strm: any;
131
  
132
  /**
133
   * Process input data chunk
134
   * @param data - Input data chunk
135
   * @param flush_mode - Flush mode (false=Z_NO_FLUSH, true=Z_FINISH, or constant)
136
   * @returns true if successful, false on error
137
   */
138
  push(data: Uint8Array | ArrayBuffer | string, flush_mode?: number | boolean): boolean;
139
  
140
  /**
141
   * Data callback (override for custom handling)
142
   * @param chunk - Output data chunk
143
   */
144
  onData(chunk: Uint8Array): void;
145
  
146
  /**
147
   * Completion callback
148
   * @param status - Final status code
149
   */
150
  onEnd(status: number): void;
151
}
152
```
153

154
**Usage Examples:**
155

156
```javascript
157
import { Deflate, constants } from 'pako';
158

159
// Basic streaming compression
160
const deflater = new Deflate();
161
deflater.push('Hello ', false);
162
deflater.push('World!', true); // true = Z_FINISH
163
console.log(deflater.result); // Uint8Array with compressed data
164

165
// Custom chunk processing
166
const deflater2 = new Deflate({ level: 6 });
167
deflater2.onData = function(chunk) {
168
  console.log('Compressed chunk:', chunk);
169
};
170
deflater2.onEnd = function(status) {
171
  console.log('Compression finished with status:', status);
172
};
173

174
deflater2.push('Large data chunk 1', constants.Z_NO_FLUSH);
175
deflater2.push('Large data chunk 2', constants.Z_NO_FLUSH);
176
deflater2.push('Final chunk', constants.Z_FINISH);
177

178
// Gzip streaming
179
const gzipper = new Deflate({
180
  gzip: true,
181
  header: {
182
    name: 'data.txt',
183
    text: true
184
  }
185
});
186
gzipper.push('Text content', true);
187
```
188

189
## Options Reference
190

191
### DeflateOptions
192

193
```javascript { .api }
194
interface DeflateOptions {
195
  /** Compression level (-1 for default, 0 = no compression, 1 = best speed, 9 = best compression) */
196
  level?: number;
197
  
198
  /** Window size (8-15, default 15) - larger values use more memory but may compress better */
199
  windowBits?: number;
200
  
201
  /** Memory usage level (1-9, default 8) - higher values use more memory but may be faster */
202
  memLevel?: number;
203
  
204
  /** Compression strategy (0 = default, 1 = filtered, 2 = huffman only, 3 = RLE, 4 = fixed) */
205
  strategy?: number;
206
  
207
  /** Preset dictionary for improved compression of similar data */
208
  dictionary?: Uint8Array | ArrayBuffer | string;
209
  
210
  /** Output chunk size in bytes (default 16384) */
211
  chunkSize?: number;
212
  
213
  /** Use raw deflate format without wrapper */
214
  raw?: boolean;
215
  
216
  /** Create gzip wrapper instead of deflate wrapper */
217
  gzip?: boolean;
218
  
219
  /** Custom gzip header (only used when gzip: true) */
220
  header?: GzipHeader;
221
}
222

223
interface GzipHeader {
224
  /** Mark compressed data as text */
225
  text?: boolean;
226
  
227
  /** Unix timestamp */
228
  time?: number;
229
  
230
  /** Operating system code */
231
  os?: number;
232
  
233
  /** Extra data bytes (max 65536) */
234
  extra?: Array<number>;
235
  
236
  /** Original file name */
237
  name?: string;
238
  
239
  /** Comment string */
240
  comment?: string;
241
  
242
  /** Add header CRC */
243
  hcrc?: boolean;
244
}
245
```
246

247
## Error Handling
248

249
Check the `err` property of Deflate instances for error codes:
250

251
```javascript
252
import { Deflate, constants } from 'pako';
253

254
const deflater = new Deflate();
255
deflater.push('data', true);
256

257
if (deflater.err !== constants.Z_OK) {
258
  console.error('Compression error:', deflater.msg);
259
} else {
260
  console.log('Compression successful');
261
}
262
```