<!-- BusyBot node reference — https://busybot.net/tools/compression/ -->

> Node: Compression (`compression`) · Action (binary) · v1
> Category: Core Nodes · Credentials: none
> Updated: 2026-08-16

# Compression

> Compress and decompress files using zip or gzip

## Overview

The Compression tool performs local file compression and decompression. It supports two formats: zip (combine multiple files into a single archive) and gzip (compress/decompress individual files). For zip compression, it uses smart compression levels — already-compressed formats (jpg, png, pdf, zip, etc.) are stored without re-compression (level 0), while other formats use standard compression (level 6). For zip decompression, it extracts all files from the archive into separate binary properties, filtering out macOS resource fork artifacts (__MACOSX entries). For gzip, it compresses or decompresses individual binary properties. No external API calls — all processing is performed locally.

**Category:** Core Nodes  
**Tool Name:** `compression`  
**Version:** 1

**Appearance:** Icon: `lucide-Archive` | Color: `#408000`

## Node Type

**Action (Binary)** — handles file/binary data operations

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool does not require any credentials.

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Compress | `compress` | Compress files into a zip or gzip archive |
| Decompress | `decompress` | Decompress zip or gzip archives |

### Parameters

#### Compress (`compress`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Input Binary Field(s) | `string` | Yes | `data` | The name of the input binary field(s) containing the file(s). To process more than one file, use a comma-separated list of binary field names. Names are case-sensitive — see the upstream node's Binary Data panel for the exact names to use. |
| Output Format | `options` | No | `zip` | Format of the compressed output. |
| | | | | Options: `gzip`, `zip` |
| File Name | `string` | Yes | — | Name of the output zip file. _(shown when Output Format is `zip`)_ |
| File Name | `string` | No | — | Name of the output file (optional). If not set, uses original filename. _(shown when Output Format is `gzip`)_ |
| Put Output File in Field | `string` | No | `data` | The name of the output binary field to put the compressed file in. Names are case-sensitive — see the upstream node's Binary Data panel for the exact names to use. |

#### Decompress (`decompress`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Input Binary Field(s) | `string` | Yes | `data` | The name of the input binary field(s) containing the file(s) to decompress. To process more than one file, use a comma-separated list of binary field names. Names are case-sensitive — see the upstream node's Binary Data panel for the exact names to use. |
| Output Prefix | `string` | Yes | `file_` | Prefix to add to decompressed file binary property names (e.g. file_0, file_1, ...). |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item. The item JSON passes through unchanged — this node writes nothing to `json`. What changes is the binary: the node **replaces** the item's binary properties with the files it produced, so a property you did not name as an output no longer exists downstream. Keep a copy upstream if you still need the originals.

| Operation and format | Binary properties on the output item |
|----------------------|--------------------------------------|
| Compress, `zip` | One property, named by **Put Output File in Field**. Its file name is **File Name** (or `archive.zip` when left empty) and its MIME type is `application/zip`. Every named input field becomes an entry inside the archive, stored under that field's original file name. |
| Compress, `gzip` | One property per named input field: the first is **Put Output File in Field**, the rest get a numeric suffix (`data`, `data1`, `data2`, …). Each file name ends in `.gz` and the MIME type is `application/gzip`. |
| Decompress, zip archive | One property per archive entry, numbered from the **Output Prefix** (`file_0`, `file_1`, …). Each keeps the entry's path from inside the archive as its file name, and its MIME type is detected from that name. macOS `__MACOSX` resource-fork entries are skipped. |
| Decompress, gzip file | One property per named input field, numbered from the **Output Prefix**. The original name and extension are recovered from the archive's file name where possible (`data.json.gz` becomes `data.json`), and the MIME type follows from it. |

Reference the result downstream by binary property name, for example by setting a later node's Input Binary Field to `file_0`.

Decompress identifies the archive format from the **file name** of the incoming binary, not from its contents: the name must end in `.zip`, `.gz` or `.gzip`. A binary with no extension, or with any other extension, fails that item.

## Usage Examples

- Compress multiple files into a zip archive
- Decompress a zip file and extract all contained files
- Gzip compress a single file
- Decompress a .gz file and detect original MIME type
- Create a zip archive from email attachments

## Example Configuration

Compress one file into a zip archive:

```json
{
  "type": "compression",
  "parameters": {
    "operation": "compress",
    "binaryPropertyName": "data",
    "outputFormat": "zip",
    "fileName": "archive.zip",
    "binaryPropertyOutput": "compressedArchive",
    "maxConcurrency": 5
  }
}
```

Compress several binary fields into one zip archive:

```json
{
  "type": "compression",
  "parameters": {
    "operation": "compress",
    "binaryPropertyName": "file1,file2,file3",
    "outputFormat": "zip",
    "fileName": "multi-files.zip",
    "binaryPropertyOutput": "zipOutput"
  }
}
```

Gzip a single file under a chosen name:

```json
{
  "type": "compression",
  "parameters": {
    "operation": "compress",
    "binaryPropertyName": "document",
    "outputFormat": "gzip",
    "fileName": "document.gz",
    "binaryPropertyOutput": "gzipData"
  }
}
```

Gzip a file and let the node derive the name from the original:

```json
{
  "type": "compression",
  "parameters": {
    "operation": "compress",
    "binaryPropertyName": "data",
    "outputFormat": "gzip",
    "binaryPropertyOutput": "compressedFile"
  }
}
```

Extract every file from an archive:

```json
{
  "type": "compression",
  "parameters": {
    "operation": "decompress",
    "binaryPropertyName": "archive",
    "outputPrefix": "extracted_",
    "maxConcurrency": 8
  }
}
```

Extract several archives held on the same item:

```json
{
  "type": "compression",
  "parameters": {
    "operation": "decompress",
    "binaryPropertyName": "zip1,zip2,backup",
    "outputPrefix": "file_"
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Compress files into zip/gzip archives or decompress zip/gzip archives into their original files — all processing done locally.

### Common Patterns

- **Basic file compression** — name one binary field, choose `zip`, give the archive a file name, and pick the output field to write it to.
- **Archive extraction** — point **Input Binary Field(s)** at an uploaded or downloaded archive and give the extracted files a readable **Output Prefix** such as `extracted_`.
- **Batch processing** — list several binary fields in one go and raise **Max Concurrency** when many items arrive at once.
- **Single large file** — prefer `gzip` over `zip` when you are compressing one file and want the lightest possible processing.

### Parameter Relationships

- **Input Binary Field(s)** is required for both operations, but serves different purposes — the files to pack when compressing, the archives to open when decompressing.
- **Output Format** and **Put Output File in Field** apply to Compress only.
- **File Name** behaves differently per format: for `zip` it names the archive and is required; for `gzip` it is optional and the original file name is used when it is empty.
- **Output Prefix** applies to Decompress only, and numbers the extracted files systematically.