0
# Pako
1

2
Pako is a high-performance JavaScript port of the zlib compression library, enabling developers to perform deflate/inflate compression and decompression operations directly in JavaScript environments including browsers and Node.js. It offers binary-compatible results with the original zlib library while achieving near-native performance in modern JavaScript engines.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
import pako from 'pako';
15
import { deflate, inflate, Deflate, Inflate, constants } from 'pako';
16
```
17

18
For CommonJS:
19

20
```javascript
21
const pako = require('pako');
22
const { deflate, inflate, Deflate, Inflate, constants } = require('pako');
23
```
24

25
## Basic Usage
26

27
```javascript
28
import { deflate, inflate } from 'pako';
29

30
// Compress string data (automatically converted to UTF-8 bytes)
31
const input = "Hello World!";
32
const compressed = deflate(input);
33

34
// Decompress back to original
35
const decompressed = inflate(compressed, { to: 'string' });
36
console.log(decompressed); // "Hello World!"
37

38
// Working with binary data
39
const binaryData = new Uint8Array([1, 2, 3, 4, 5]);
40
const compressedBinary = deflate(binaryData);
41
const decompressedBinary = inflate(compressedBinary);
42

43
// All input types supported: string, Uint8Array, ArrayBuffer
44
const arrayBuffer = new ArrayBuffer(10);
45
const compressedFromBuffer = deflate(arrayBuffer);
46
```
47

48
## Architecture
49

50
Pako is built around several key components:
51

52
- **Function API**: Simple one-shot compression/decompression functions (`deflate`, `inflate`, `gzip`, `ungzip`)
53
- **Class API**: Streaming interfaces (`Deflate`, `Inflate`) for processing large data chunks
54
- **Format Support**: Raw deflate, deflate with wrapper, and gzip formats
55
- **Data Handling**: Automatic type conversion with configurable UTF-8 encoding
56
- **Browser Optimization**: Separate builds for deflate-only and inflate-only operations
57

58
## Data Type Handling
59

60
Pako automatically handles different input types:
61

62
**Input Types Supported:**
63
- `string` - Automatically converted to UTF-8 bytes using TextEncoder when available, or manual UTF-8 encoding
64
- `Uint8Array` - Used directly as binary data
65
- `ArrayBuffer` - Converted to Uint8Array for processing
66

67
**Output Types:**
68
- Default output is `Uint8Array` for all compression functions and binary decompression
69
- String output available for decompression functions when `{ to: 'string' }` option is specified
70
- String output uses UTF-8 decoding via TextDecoder when available, or manual UTF-8 decoding
71

72
## Capabilities
73

74
### Compression Operations
75

76
High-performance data compression using deflate algorithm with support for raw deflate, standard deflate with wrapper, and gzip formats.
77

78
```javascript { .api }
79
function deflate(input: Uint8Array | ArrayBuffer | string, options?: DeflateOptions): Uint8Array;
80
function deflateRaw(input: Uint8Array | ArrayBuffer | string, options?: DeflateOptions): Uint8Array;
81
function gzip(input: Uint8Array | ArrayBuffer | string, options?: DeflateOptions): Uint8Array;
82

83
class Deflate {
84
  constructor(options?: DeflateOptions);
85
  push(data: Uint8Array | ArrayBuffer | string, flush_mode?: number | boolean): boolean;
86
  result: Uint8Array;
87
  err: number;
88
  msg: string;
89
  chunks: Array<Uint8Array>;
90
  ended: boolean;
91
  options: DeflateOptions;
92
  strm: any;
93
}
94
```
95

96
[Compression](./compression.md)
97

98
### Decompression Operations
99

100
Fast data decompression with automatic format detection for deflate and gzip formats, supporting both binary and string output.
101

102
```javascript { .api }
103
function inflate(input: Uint8Array | ArrayBuffer, options?: InflateOptions): Uint8Array | string;
104
function inflateRaw(input: Uint8Array | ArrayBuffer, options?: InflateOptions): Uint8Array | string;
105
function ungzip(input: Uint8Array | ArrayBuffer, options?: InflateOptions): Uint8Array | string;
106

107
class Inflate {
108
  constructor(options?: InflateOptions);
109
  push(data: Uint8Array | ArrayBuffer, flush_mode?: number | boolean): boolean;
110
  result: Uint8Array | string;
111
  err: number;
112
  msg: string;
113
  chunks: Array<Uint8Array>;
114
  ended: boolean;
115
  options: InflateOptions;
116
  strm: any;
117
  header: any;
118
}
119
```
120

121
[Decompression](./decompression.md)
122

123
## Types
124

125
```javascript { .api }
126
interface DeflateOptions {
127
  level?: number;          // Compression level (-1 for default, 0-9)
128
  windowBits?: number;     // Window size (15 default, 8-15 range)
129
  memLevel?: number;       // Memory usage level (8 default, 1-9 range)
130
  strategy?: number;       // Compression strategy (0 default)
131
  dictionary?: Uint8Array | ArrayBuffer | string; // Preset dictionary
132
  chunkSize?: number;      // Output chunk size (16384 default)
133
  raw?: boolean;           // Raw deflate without wrapper
134
  gzip?: boolean;          // Create gzip wrapper
135
  header?: GzipHeader;     // Custom gzip header
136
}
137

138
interface InflateOptions {
139
  windowBits?: number;     // Window size (15 default, 8-15 range)
140
  dictionary?: Uint8Array | ArrayBuffer | string; // Preset dictionary
141
  chunkSize?: number;      // Output chunk size (65536 default)
142
  raw?: boolean;           // Raw inflate without wrapper
143
  to?: string;             // Output format ('string' for UTF-16, default binary)
144
}
145

146
interface GzipHeader {
147
  text?: boolean;          // Compressed data is text
148
  time?: number;           // Unix timestamp
149
  os?: number;             // Operating system code
150
  extra?: Array<number>;   // Extra data bytes (max 65536)
151
  name?: string;           // File name
152
  comment?: string;        // Comment
153
  hcrc?: boolean;          // Add header CRC
154
}
155
```
156

157
## Constants
158

159
```javascript { .api }
160
const constants: {
161
  // Flush values
162
  Z_NO_FLUSH: 0;
163
  Z_PARTIAL_FLUSH: 1;
164
  Z_SYNC_FLUSH: 2;
165
  Z_FULL_FLUSH: 3;
166
  Z_FINISH: 4;
167
  Z_BLOCK: 5;
168
  Z_TREES: 6;
169
  
170
  // Return codes
171
  Z_OK: 0;
172
  Z_STREAM_END: 1;
173
  Z_NEED_DICT: 2;
174
  Z_ERRNO: -1;
175
  Z_STREAM_ERROR: -2;
176
  Z_DATA_ERROR: -3;
177
  Z_MEM_ERROR: -4;
178
  Z_BUF_ERROR: -5;
179
  
180
  // Compression levels
181
  Z_NO_COMPRESSION: 0;
182
  Z_BEST_SPEED: 1;
183
  Z_BEST_COMPRESSION: 9;
184
  Z_DEFAULT_COMPRESSION: -1;
185
  
186
  // Compression strategies
187
  Z_FILTERED: 1;
188
  Z_HUFFMAN_ONLY: 2;
189
  Z_RLE: 3;
190
  Z_FIXED: 4;
191
  Z_DEFAULT_STRATEGY: 0;
192
  
193
  // Data types
194
  Z_BINARY: 0;
195
  Z_TEXT: 1;
196
  Z_UNKNOWN: 2;
197
  
198
  // Compression method
199
  Z_DEFLATED: 8;
200
};
201
```