> ## Documentation Index
> Fetch the complete documentation index at: https://sonamu.cartanova.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Compression Presets

> Using predefined compression settings

Sonamu provides frequently used compression patterns as **CompressPresets**. You can easily configure compression by selecting the appropriate preset for your situation.

## CompressPresets Overview

```typescript theme={null}
import { CompressPresets } from "sonamu";

// Usage in API
@api({
  httpMethod: 'GET',
  compress: CompressPresets.aggressive,
})

// Global configuration
plugins: {
  compress: CompressPresets.default
}
```

## Complete Preset List

<CardGroup cols={2}>
  <Card title="disabled" icon="ban">
    Disable compression
  </Card>

  <Card title="default" icon="check">
    Default settings (1KB, br/gzip/deflate)
  </Card>

  <Card title="aggressive" icon="fire">
    Aggressive compression (256B)
  </Card>

  <Card title="conservative" icon="shield">
    Conservative compression (4KB, gzip only)
  </Card>

  <Card title="gzipOnly" icon="file-zipper">
    gzip only
  </Card>
</CardGroup>

## Preset Details

### disabled

**Completely disables compression**.

```typescript theme={null}
CompressPresets.disabled
// Value: false
```

<Tabs>
  <Tab title="Configuration" icon="gear">
    ```typescript theme={null}
    false
    ```
  </Tab>

  <Tab title="When to Use" icon="lightbulb">
    * Development environment (easier debugging)
    * Already compressed content (images, videos)
    * Very small responses (\< 100 bytes)
    * Minimizing CPU load
  </Tab>

  <Tab title="Example" icon="code">
    ```typescript theme={null}
    // Development environment
    export const config: SonamuConfig = {
      server: {
        plugins: {
          compress: process.env.NODE_ENV === 'development'
            ? CompressPresets.disabled
            : CompressPresets.default
        }
      }
    };

    // Already compressed image API
    @api({
      httpMethod: 'GET',
      compress: CompressPresets.disabled,
    })
    async getImage() {
      return this.sendImageFile();
    }
    ```
  </Tab>
</Tabs>

### default

**Balanced default settings**.

```typescript theme={null}
CompressPresets.default
// Generated configuration:
{
  threshold: 1024,  // 1KB
  encodings: ["br", "gzip", "deflate"]
}
```

<Tabs>
  <Tab title="Configuration" icon="gear">
    ```typescript theme={null}
    {
      threshold: 1024,  // Only compress 1KB or larger
      encodings: ["br", "gzip", "deflate"]  // All algorithms
    }
    ```
  </Tab>

  <Tab title="When to Use" icon="lightbulb">
    * General API servers
    * Most cases (recommended)
    * When no special optimization is needed
  </Tab>

  <Tab title="Example" icon="code">
    ```typescript theme={null}
    // Global configuration
    export const config: SonamuConfig = {
      server: {
        plugins: {
          compress: CompressPresets.default
        }
      }
    };

    // Individual API
    @api({
      httpMethod: 'GET',
      compress: CompressPresets.default,
    })
    async getData() {
      return this.findMany({});
    }
    ```
  </Tab>
</Tabs>

**Characteristics**:

* Under 1KB: No compression (prevents overhead)
* 1KB and above: Compression in order of brotli > gzip > deflate
* Modern browsers: brotli (best compression ratio)
* Legacy browsers: gzip (compatibility)

### aggressive

**Aggressive compression for bandwidth optimization**.

```typescript theme={null}
CompressPresets.aggressive
// Generated configuration:
{
  threshold: 256,  // 256 bytes
  encodings: ["br", "gzip", "deflate"]
}
```

<Tabs>
  <Tab title="Configuration" icon="gear">
    ```typescript theme={null}
    {
      threshold: 256,  // Only compress 256B or larger
      encodings: ["br", "gzip", "deflate"]
    }
    ```
  </Tab>

  <Tab title="When to Use" icon="lightbulb">
    * Environments with expensive bandwidth
    * Mobile network targets
    * Minimizing CDN transfer volume
    * Many small responses
  </Tab>

  <Tab title="Example" icon="code">
    ```typescript theme={null}
    // Mobile API
    export const config: SonamuConfig = {
      server: {
        plugins: {
          compress: CompressPresets.aggressive
        }
      }
    };

    // Compress even small JSON
    @api({
      httpMethod: 'GET',
      compress: CompressPresets.aggressive,
    })
    async getStatus() {
      return { status: "ok", timestamp: Date.now() };
    }
    ```
  </Tab>
</Tabs>

**Effects**:

* Compresses everything 256 bytes and above
* Minimizes network transfer volume
* Slight increase in CPU overhead

### conservative

**Conservative compression that minimizes CPU load**.

```typescript theme={null}
CompressPresets.conservative
// Generated configuration:
{
  threshold: 4096,  // 4KB
  encodings: ["gzip", "deflate"]  // Excludes brotli
}
```

<Tabs>
  <Tab title="Configuration" icon="gear">
    ```typescript theme={null}
    {
      threshold: 4096,  // Only compress 4KB or larger
      encodings: ["gzip", "deflate"]  // Fast algorithms only
    }
    ```
  </Tab>

  <Tab title="When to Use" icon="lightbulb">
    * Environments with limited CPU resources
    * High TPS (Transactions Per Second)
    * Minimizing response latency
    * Compressing only large responses
  </Tab>

  <Tab title="Example" icon="code">
    ```typescript theme={null}
    // High-performance API
    export const config: SonamuConfig = {
      server: {
        plugins: {
          compress: CompressPresets.conservative
        }
      }
    };

    // Compress only large responses
    @api({
      httpMethod: 'GET',
      compress: CompressPresets.conservative,
    })
    async getLargeDataset() {
      return this.findMany({ num: 10000 });
    }
    ```
  </Tab>
</Tabs>

**Characteristics**:

* Under 4KB: No compression
* Excludes brotli (saves CPU)
* Uses gzip only (fast + compatible)

### gzipOnly

**Configuration that uses only gzip**.

```typescript theme={null}
CompressPresets.gzipOnly
// Generated configuration:
{
  threshold: 1024,  // 1KB
  encodings: ["gzip"]  // gzip only
}
```

<Tabs>
  <Tab title="Configuration" icon="gear">
    ```typescript theme={null}
    {
      threshold: 1024,
      encodings: ["gzip"]  // Uses gzip only
    }
    ```
  </Tab>

  <Tab title="When to Use" icon="lightbulb">
    * Legacy browser support (IE)
    * Stability priority
    * Browser compatibility issues
    * Real-time compression (fast processing)
  </Tab>

  <Tab title="Example" icon="code">
    ```typescript theme={null}
    // Legacy support
    export const config: SonamuConfig = {
      server: {
        plugins: {
          compress: CompressPresets.gzipOnly
        }
      }
    };

    // Real-time API
    @api({
      httpMethod: 'GET',
      compress: CompressPresets.gzipOnly,
    })
    async getRealtimeData() {
      return this.getRealTimeStats();
    }
    ```
  </Tab>
</Tabs>

**Characteristics**:

* Fastest compression
* Supported by all browsers
* Stable

## Preset Comparison Table

| Preset         | Threshold | Algorithms      | CPU Usage | Compression Ratio | Use Case                                |
| -------------- | --------- | --------------- | --------- | ----------------- | --------------------------------------- |
| `disabled`     | -         | None            | Minimal   | 0%                | Development, already compressed content |
| `default`      | 1KB       | br/gzip/deflate | Medium    | High              | General cases (recommended)             |
| `aggressive`   | 256B      | br/gzip/deflate | High      | Best              | Bandwidth optimization                  |
| `conservative` | 4KB       | gzip/deflate    | Low       | Medium            | CPU saving, high performance            |
| `gzipOnly`     | 1KB       | gzip            | Low       | Medium            | Legacy support, stability               |

## Compression Ratio Comparison

Based on actual 100KB JSON data:

| Algorithm      | Compressed Size | Compression Ratio | Speed |
| -------------- | --------------- | ----------------- | ----- |
| No compression | 100KB           | 0%                | -     |
| deflate        | 15KB            | 85%               | Fast  |
| gzip           | 14KB            | 86%               | Fast  |
| brotli (br)    | 12KB            | 88%               | Slow  |

## Recommended Presets by Scenario

### Production API Server

```typescript theme={null}
export const config: SonamuConfig = {
  server: {
    plugins: {
      compress: CompressPresets.default,  // Balanced settings
    }
  }
};
```

### Mobile App Backend

```typescript theme={null}
export const config: SonamuConfig = {
  server: {
    plugins: {
      compress: CompressPresets.aggressive,  // Maximum compression
    }
  }
};
```

### High-Performance Real-Time API

```typescript theme={null}
export const config: SonamuConfig = {
  server: {
    plugins: {
      compress: CompressPresets.conservative,  // Save CPU
    }
  }
};
```

### Legacy Browser Support

```typescript theme={null}
export const config: SonamuConfig = {
  server: {
    plugins: {
      compress: CompressPresets.gzipOnly,  // Compatibility
    }
  }
};
```

### Development Environment

```typescript theme={null}
export const config: SonamuConfig = {
  server: {
    plugins: {
      compress: CompressPresets.disabled,  // Easier debugging
    }
  }
};
```

## Combining Presets

You can customize based on presets.

```typescript theme={null}
// Based on default + adjust threshold
plugins: {
  compress: {
    ...CompressPresets.default,
    threshold: 512,  // Change to 512B
  }
}

// Based on aggressive + gzip only
plugins: {
  compress: {
    ...CompressPresets.aggressive,
    encodings: ["gzip"],  // Exclude brotli
  }
}
```

## Per-API Presets

```typescript theme={null}
class DataModelClass extends BaseModelClass {
  // Small response: aggressive
  @api({
    httpMethod: 'GET',
    compress: CompressPresets.aggressive,
  })
  async getStatus() {
    return { status: "ok" };
  }

  // Medium response: default
  @api({
    httpMethod: 'GET',
    compress: CompressPresets.default,
  })
  async getList() {
    return this.findMany({ num: 100 });
  }

  // Large response: conservative (save CPU)
  @api({
    httpMethod: 'GET',
    compress: CompressPresets.conservative,
  })
  async exportData() {
    return this.findMany({ num: 100000 });
  }

  // Already compressed file: disabled
  @api({
    httpMethod: 'GET',
    compress: CompressPresets.disabled,
  })
  async downloadImage() {
    return this.sendFile('image.png');
  }
}
```

## Environment-Based Presets

```typescript theme={null}
const isDevelopment = process.env.NODE_ENV === 'development';
const isProduction = process.env.NODE_ENV === 'production';

export const config: SonamuConfig = {
  server: {
    plugins: {
      compress: isDevelopment
        ? CompressPresets.disabled       // Development: no compression
        : isProduction
        ? CompressPresets.aggressive     // Production: maximum compression
        : CompressPresets.default        // Others: default settings
    }
  }
};
```

## Precautions

<Warning>
  **Precautions when using presets**:

  1. **Presets are starting points**: Adjust according to your situation
     ```typescript theme={null}
     // Customizing based on preset
     compress: {
       ...CompressPresets.default,
       threshold: 2048,  // Adjust to 2KB
     }
     ```

  2. **aggressive increases CPU load**: Monitor server performance
     ```typescript theme={null}
     // Warning: High CPU usage
     compress: CompressPresets.aggressive
     ```

  3. **conservative doesn't compress small responses**: Reduced network efficiency
     ```typescript theme={null}
     // conservative: Does not compress under 4KB
     compress: CompressPresets.conservative
     ```

  4. **disabled disables all compression**: Increased transfer volume
     ```typescript theme={null}
     // Avoid disabling in production
     compress: CompressPresets.disabled
     ```
</Warning>

## Performance Measurement

Performance comparison by preset (based on 100KB JSON):

| Preset         | Compression Time | Compressed Size | Network | Total Time |
| -------------- | ---------------- | --------------- | ------- | ---------- |
| `disabled`     | 0ms              | 100KB           | 1000ms  | 1000ms     |
| `gzipOnly`     | 2ms              | 14KB            | 140ms   | 142ms      |
| `conservative` | 2ms              | 14KB            | 140ms   | 142ms      |
| `default`      | 5ms              | 12KB            | 120ms   | 125ms      |
| `aggressive`   | 5ms              | 12KB            | 120ms   | 125ms      |

**Conclusion**: brotli takes slightly longer to compress but is overall faster due to network time savings

## Next Steps

<CardGroup cols={2}>
  <Card title="Compression Configuration" icon="gear" href="/en/advanced-features/compress/compress-configuration">
    Global compression plugin settings
  </Card>

  <Card title="Per-API Control" icon="code" href="/en/advanced-features/compress/per-api-control">
    Compression settings in @api decorator
  </Card>

  <Card title="Performance Optimization" icon="gauge-high" href="/en/advanced-features/compress/performance-optimization">
    Compression optimization strategies
  </Card>
</CardGroup>