# bare-zlib



<mark style="{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }">
  stable
</mark>

[`bare-zlib`](https://github.com/holepunchto/bare-zlib) — Stream-based zlib bindings for JavaScript. It is a native addon.

Mirrors the Node.js [`zlib`](https://nodejs.org/api/zlib.html) module.

```sh
npm i bare-zlib
```

## API [#api]

### Zlib [#zlib]

#### `Zlib.constants` [#zlibconstants]

```ts
Zlib.constants: {
  Z_NO_FLUSH: number
  Z_PARTIAL_FLUSH: number
  Z_SYNC_FLUSH: number
  Z_FULL_FLUSH: number
  Z_FINISH: number
  Z_BLOCK: number
  Z_TREES: number

  Z_FILTERED: number
  Z_HUFFMAN_ONLY: number
  Z_RLE: number
  Z_FIXED: number
  Z_DEFAULT_STRATEGY: number

  Z_NO_COMPRESSION: number
  Z_BEST_SPEED: number
  Z_BEST_COMPRESSION: number
  Z_DEFAULT_COMPRESSION: number

  Z_MIN_CHUNK: number
  Z_MAX_CHUNK: number
  Z_DEFAULT_CHUNK: number

  Z_MIN_MEMLEVEL: number
  Z_MAX_MEMLEVEL: number
  Z_DEFAULT_MEMLEVEL: number

  Z_MIN_LEVEL: number
  Z_MAX_LEVEL: number
  Z_DEFAULT_LEVEL: number

  Z_MIN_WINDOWBITS: number
  Z_MAX_WINDOWBITS: number
  Z_DEFAULT_WINDOWBITS: number

  Z_OK: number
  Z_STREAM_END: number
  Z_NEED_DICT: number
  Z_ERRNO: number
  Z_STREAM_ERROR: number
  Z_DATA_ERROR: number
  Z_MEM_ERROR: number
  Z_BUF_ERROR: number
  Z_VERSION_ERROR: number
}
```

Zlib-related constants such as flush modes, compression levels, strategies, and chunk/window/memory-level bounds.

#### `Zlib.createDeflate(opts?: ZlibOptions): Deflate` [#zlibcreatedeflateopts-zliboptions-deflate]

Create and return a new `Deflate` stream for streaming zlib compression.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

#### `Zlib.createDeflateRaw(opts?: ZlibOptions): DeflateRaw` [#zlibcreatedeflaterawopts-zliboptions-deflateraw]

Create and return a new `DeflateRaw` stream for streaming raw deflate compression, without a zlib header.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

#### `Zlib.createGunzip(opts?: ZlibOptions): Gunzip` [#zlibcreategunzipopts-zliboptions-gunzip]

Create and return a new `Gunzip` stream for streaming gzip decompression.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

#### `Zlib.createGzip(opts?: ZlibOptions): Gzip` [#zlibcreategzipopts-zliboptions-gzip]

Create and return a new `Gzip` stream for streaming gzip compression.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

#### `Zlib.createInflate(opts?: ZlibOptions): Inflate` [#zlibcreateinflateopts-zliboptions-inflate]

Create and return a new `Inflate` stream for streaming zlib decompression.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

#### `Zlib.createInflateRaw(opts?: ZlibOptions): InflateRaw` [#zlibcreateinflaterawopts-zliboptions-inflateraw]

Create and return a new `InflateRaw` stream for streaming raw deflate decompression, without a zlib header.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

#### `Zlib.deflate(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void` [#zlibdeflatebuffer-zlibinput-opts-zliboptions-cb-zlibcallback-void]

Compress `buffer` with deflate, calling `cb` with the resulting `Buffer`.

Overloads:

```ts
Zlib.deflate(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void
Zlib.deflate(buffer: ZlibInput, cb: ZlibCallback): void
```

**Parameters**

| Parameter | Type                            | Default | Description                                                                  |
| --------- | ------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `buffer`  | `ZlibInput`                     | —       | The data to compress.                                                        |
| `opts`    | [`ZlibOptions`](#zliboptions)   | —       | The zlib options to apply for this operation.                                |
| `cb`      | [`ZlibCallback`](#zlibcallback) | —       | Called with the resulting `Buffer`, or with an error if the operation fails. |

#### `Zlib.deflateRaw(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void` [#zlibdeflaterawbuffer-zlibinput-opts-zliboptions-cb-zlibcallback-void]

Compress `buffer` with raw deflate, without a zlib header, calling `cb` with the resulting `Buffer`.

Overloads:

```ts
Zlib.deflateRaw(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void
Zlib.deflateRaw(buffer: ZlibInput, cb: ZlibCallback): void
```

**Parameters**

| Parameter | Type                            | Default | Description                                                                  |
| --------- | ------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `buffer`  | `ZlibInput`                     | —       | The data to compress.                                                        |
| `opts`    | [`ZlibOptions`](#zliboptions)   | —       | The zlib options to apply for this operation.                                |
| `cb`      | [`ZlibCallback`](#zlibcallback) | —       | Called with the resulting `Buffer`, or with an error if the operation fails. |

#### `Zlib.deflateRawSync(buffer: ZlibInput, opts?: ZlibOptions): Buffer` [#zlibdeflaterawsyncbuffer-zlibinput-opts-zliboptions-buffer]

Synchronously compress `buffer` with raw deflate, without a zlib header, and return the resulting `Buffer`.

**Parameters**

| Parameter | Type                          | Default | Description                                                |
| --------- | ----------------------------- | ------- | ---------------------------------------------------------- |
| `buffer`  | `ZlibInput`                   | —       | The data to compress; a string is converted to a `Buffer`. |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | The zlib options to apply for this operation.              |

**Throws**

* `LIMIT_EXCEEDED` — the output exceeded `maxOutputLength`.
* `ZlibError` — the underlying zlib operation failed; `code` identifies the failure.

#### `Zlib.deflateSync(buffer: ZlibInput, opts?: ZlibOptions): Buffer` [#zlibdeflatesyncbuffer-zlibinput-opts-zliboptions-buffer]

Synchronously compress `buffer` with deflate and return the resulting `Buffer`.

**Parameters**

| Parameter | Type                          | Default | Description                                                |
| --------- | ----------------------------- | ------- | ---------------------------------------------------------- |
| `buffer`  | `ZlibInput`                   | —       | The data to compress; a string is converted to a `Buffer`. |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | The zlib options to apply for this operation.              |

**Throws**

* `LIMIT_EXCEEDED` — the output exceeded `maxOutputLength`.
* `ZlibError` — the underlying zlib operation failed; `code` identifies the failure.

#### `Zlib.gunzip(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void` [#zlibgunzipbuffer-zlibinput-opts-zliboptions-cb-zlibcallback-void]

Decompress `buffer` as gzip, calling `cb` with the resulting `Buffer`.

Overloads:

```ts
Zlib.gunzip(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void
Zlib.gunzip(buffer: ZlibInput, cb: ZlibCallback): void
```

**Parameters**

| Parameter | Type                            | Default | Description                                                                  |
| --------- | ------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `buffer`  | `ZlibInput`                     | —       | The data to decompress.                                                      |
| `opts`    | [`ZlibOptions`](#zliboptions)   | —       | The zlib options to apply for this operation.                                |
| `cb`      | [`ZlibCallback`](#zlibcallback) | —       | Called with the resulting `Buffer`, or with an error if the operation fails. |

#### `Zlib.gunzipSync(buffer: ZlibInput, opts?: ZlibOptions): Buffer` [#zlibgunzipsyncbuffer-zlibinput-opts-zliboptions-buffer]

Synchronously decompress `buffer` as gzip and return the resulting `Buffer`.

**Parameters**

| Parameter | Type                          | Default | Description                                                  |
| --------- | ----------------------------- | ------- | ------------------------------------------------------------ |
| `buffer`  | `ZlibInput`                   | —       | The data to decompress; a string is converted to a `Buffer`. |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | The zlib options to apply for this operation.                |

**Throws**

* `LIMIT_EXCEEDED` — the output exceeded `maxOutputLength`.
* `ZlibError` — the underlying zlib operation failed; `code` (such as `DATA_ERROR`) identifies the failure.

#### `Zlib.gzip(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void` [#zlibgzipbuffer-zlibinput-opts-zliboptions-cb-zlibcallback-void]

Compress `buffer` as gzip, calling `cb` with the resulting `Buffer`.

Overloads:

```ts
Zlib.gzip(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void
Zlib.gzip(buffer: ZlibInput, cb: ZlibCallback): void
```

**Parameters**

| Parameter | Type                            | Default | Description                                                                  |
| --------- | ------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `buffer`  | `ZlibInput`                     | —       | The data to compress.                                                        |
| `opts`    | [`ZlibOptions`](#zliboptions)   | —       | The zlib options to apply for this operation.                                |
| `cb`      | [`ZlibCallback`](#zlibcallback) | —       | Called with the resulting `Buffer`, or with an error if the operation fails. |

#### `Zlib.gzipSync(buffer: ZlibInput, opts?: ZlibOptions): Buffer` [#zlibgzipsyncbuffer-zlibinput-opts-zliboptions-buffer]

Synchronously compress `buffer` as gzip and return the resulting `Buffer`.

**Parameters**

| Parameter | Type                          | Default | Description                                                |
| --------- | ----------------------------- | ------- | ---------------------------------------------------------- |
| `buffer`  | `ZlibInput`                   | —       | The data to compress; a string is converted to a `Buffer`. |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | The zlib options to apply for this operation.              |

**Throws**

* `LIMIT_EXCEEDED` — the output exceeded `maxOutputLength`.
* `ZlibError` — the underlying zlib operation failed; `code` identifies the failure.

#### `Zlib.inflate(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void` [#zlibinflatebuffer-zlibinput-opts-zliboptions-cb-zlibcallback-void]

Decompress `buffer` with inflate, calling `cb` with the resulting `Buffer`.

Overloads:

```ts
Zlib.inflate(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void
Zlib.inflate(buffer: ZlibInput, cb: ZlibCallback): void
```

**Parameters**

| Parameter | Type                            | Default | Description                                                                  |
| --------- | ------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `buffer`  | `ZlibInput`                     | —       | The data to decompress.                                                      |
| `opts`    | [`ZlibOptions`](#zliboptions)   | —       | The zlib options to apply for this operation.                                |
| `cb`      | [`ZlibCallback`](#zlibcallback) | —       | Called with the resulting `Buffer`, or with an error if the operation fails. |

#### `Zlib.inflateRaw(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void` [#zlibinflaterawbuffer-zlibinput-opts-zliboptions-cb-zlibcallback-void]

Decompress `buffer` with raw inflate, without a zlib header, calling `cb` with the resulting `Buffer`.

Overloads:

```ts
Zlib.inflateRaw(buffer: ZlibInput, opts: ZlibOptions, cb: ZlibCallback): void
Zlib.inflateRaw(buffer: ZlibInput, cb: ZlibCallback): void
```

**Parameters**

| Parameter | Type                            | Default | Description                                                                  |
| --------- | ------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `buffer`  | `ZlibInput`                     | —       | The data to decompress.                                                      |
| `opts`    | [`ZlibOptions`](#zliboptions)   | —       | The zlib options to apply for this operation.                                |
| `cb`      | [`ZlibCallback`](#zlibcallback) | —       | Called with the resulting `Buffer`, or with an error if the operation fails. |

#### `Zlib.inflateRawSync(buffer: ZlibInput, opts?: ZlibOptions): Buffer` [#zlibinflaterawsyncbuffer-zlibinput-opts-zliboptions-buffer]

Synchronously decompress `buffer` with raw inflate, without a zlib header, and return the resulting `Buffer`.

**Parameters**

| Parameter | Type                          | Default | Description                                                  |
| --------- | ----------------------------- | ------- | ------------------------------------------------------------ |
| `buffer`  | `ZlibInput`                   | —       | The data to decompress; a string is converted to a `Buffer`. |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | The zlib options to apply for this operation.                |

**Throws**

* `LIMIT_EXCEEDED` — the output exceeded `maxOutputLength`.
* `ZlibError` — the underlying zlib operation failed; `code` (such as `DATA_ERROR`) identifies the failure.

#### `Zlib.inflateSync(buffer: ZlibInput, opts?: ZlibOptions): Buffer` [#zlibinflatesyncbuffer-zlibinput-opts-zliboptions-buffer]

Synchronously decompress `buffer` with inflate and return the resulting `Buffer`.

**Parameters**

| Parameter | Type                          | Default | Description                                                  |
| --------- | ----------------------------- | ------- | ------------------------------------------------------------ |
| `buffer`  | `ZlibInput`                   | —       | The data to decompress; a string is converted to a `Buffer`. |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | The zlib options to apply for this operation.                |

**Throws**

* `LIMIT_EXCEEDED` — the output exceeded `maxOutputLength`.
* `ZlibError` — the underlying zlib operation failed; `code` (such as `DATA_ERROR`) identifies the failure.

#### `Zlib.ZlibInput` [#zlibzlibinput]

```ts
type ZlibInput = string | Buffer | Uint8Array
```

The input accepted by the one-shot functions: a string, `Buffer`, or `Uint8Array`.

### ZlibStream [#zlibstream]

#### `flush(mode?: number, cb?: ZlibFlushCallback): Promise<void>` [#flushmode-number-cb-zlibflushcallback-promisevoid]

Flush queued data through the stream immediately using the given flush `mode`, resolving once it has drained.

Overloads:

```ts
flush(mode?: number, cb?: ZlibFlushCallback): Promise<void>
flush(cb: ZlibFlushCallback): Promise<void>
```

**Parameters**

| Parameter | Type                                      | Default | Description                                                                                        |
| --------- | ----------------------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `mode?`   | `number`                                  | —       | The flush mode, from `constants` (default `Z_FULL_FLUSH`).                                         |
| `cb?`     | [`ZlibFlushCallback`](#zlibflushcallback) | —       | Called once the flush completes, for Node.js compatibility; the returned promise resolves as well. |

#### `reset(): void` [#reset-void]

Reset the underlying compressor or decompressor to its initial state.

**Throws**

* `STREAM_CLOSED` — the stream has already closed.

### Deflate [#deflate]

#### `new Deflate(opts?: ZlibOptions)` [#new-deflateopts-zliboptions]

Create a `Deflate` stream with the given `opts`.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

### Inflate [#inflate]

#### `new Inflate(opts?: ZlibOptions)` [#new-inflateopts-zliboptions]

Create an `Inflate` stream with the given `opts`.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

### DeflateRaw [#deflateraw]

#### `new DeflateRaw(opts?: ZlibOptions)` [#new-deflaterawopts-zliboptions]

Create a `DeflateRaw` stream with the given `opts`.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

### InflateRaw [#inflateraw]

#### `new InflateRaw(opts?: ZlibOptions)` [#new-inflaterawopts-zliboptions]

Create an `InflateRaw` stream with the given `opts`.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

### Gzip [#gzip]

#### `new Gzip(opts?: ZlibOptions)` [#new-gzipopts-zliboptions]

Create a `Gzip` stream with the given `opts`.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

### Gunzip [#gunzip]

#### `new Gunzip(opts?: ZlibOptions)` [#new-gunzipopts-zliboptions]

Create a `Gunzip` stream with the given `opts`.

**Parameters**

| Parameter | Type                          | Default | Description                                           |
| --------- | ----------------------------- | ------- | ----------------------------------------------------- |
| `opts?`   | [`ZlibOptions`](#zliboptions) | —       | Options for the stream and the underlying zlib state. |

### Types [#types]

#### `ZlibOptions` [#zliboptions]

```ts
interface ZlibOptions<S extends ZlibStream = ZlibStream> {
  flush?: number
  finishFlush?: number
  chunkSize?: number
  level?: number
  windowBits?: number
  memLevel?: number
  strategy?: number
  maxOutputLength?: number
  transform?(this: S, data: unknown, encoding: StreamEncoding, cb: StreamCallback): void
  encoding?: BufferEncoding
  highWaterMark?: number
  read?(this: S, size: number): void
  eagerOpen?: boolean
  signal?: AbortSignal
  open?(this: S, cb: StreamCallback): void
  predestroy?(this: S): void
  destroy?(this: S, err: Error | null, cb: StreamCallback): void
  write?(this: S, data: unknown, encoding: StreamEncoding, cb: StreamCallback): void
  writev?(this: S, batch: { chunk: unknown; encoding: StreamEncoding }[], cb: StreamCallback): void
  final?(this: S, cb: StreamCallback): void
}
```

#### `ZlibCallback` [#zlibcallback]

```ts
interface ZlibCallback {
}
```

Callback for the one-shot asynchronous functions, called with an error or the resulting `Buffer`.

#### `ZlibFlushCallback` [#zlibflushcallback]

```ts
interface ZlibFlushCallback {
}
```

Callback invoked once a `flush()` completes.

### Classes [#classes]

#### `ZlibError` [#zliberror]

```ts
class ZlibError {
  code: ZlibErrorCode
  name: 'ZlibError'
}
```

An error thrown by a zlib operation, carrying a `code` identifying the underlying zlib failure (such as `DATA_ERROR` or `MEM_ERROR`).

## `bare-zlib/constants` [#bare-zlibconstants]

### Constants and variables [#constants-and-variables]

#### `constants` [#constants]

```ts
constants: {
  Z_NO_FLUSH: number
  Z_PARTIAL_FLUSH: number
  Z_SYNC_FLUSH: number
  Z_FULL_FLUSH: number
  Z_FINISH: number
  Z_BLOCK: number
  Z_TREES: number

  Z_FILTERED: number
  Z_HUFFMAN_ONLY: number
  Z_RLE: number
  Z_FIXED: number
  Z_DEFAULT_STRATEGY: number

  Z_NO_COMPRESSION: number
  Z_BEST_SPEED: number
  Z_BEST_COMPRESSION: number
  Z_DEFAULT_COMPRESSION: number

  Z_MIN_CHUNK: number
  Z_MAX_CHUNK: number
  Z_DEFAULT_CHUNK: number

  Z_MIN_MEMLEVEL: number
  Z_MAX_MEMLEVEL: number
  Z_DEFAULT_MEMLEVEL: number

  Z_MIN_LEVEL: number
  Z_MAX_LEVEL: number
  Z_DEFAULT_LEVEL: number

  Z_MIN_WINDOWBITS: number
  Z_MAX_WINDOWBITS: number
  Z_DEFAULT_WINDOWBITS: number

  Z_OK: number
  Z_STREAM_END: number
  Z_NEED_DICT: number
  Z_ERRNO: number
  Z_STREAM_ERROR: number
  Z_DATA_ERROR: number
  Z_MEM_ERROR: number
  Z_BUF_ERROR: number
  Z_VERSION_ERROR: number
}
```

Zlib-related constants such as flush modes, compression levels, strategies, and chunk/window/memory-level bounds.

## `bare-zlib/errors` [#bare-zliberrors]

### Classes [#classes-1]

#### `errors.ZlibError` [#errorszliberror]

An error thrown by a zlib operation, carrying a `code` identifying the underlying zlib failure (such as `DATA_ERROR` or `MEM_ERROR`).

## See also [#see-also]

* Builds on `bare-stream`.
* [Bare modules](/bare/reference/bare/modules) — the full `bare-*` catalog.
* [Bare runtime API](/bare/reference/bare/runtime) — the runtime these modules extend.