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

CompressPresets Overview

import { CompressPresets } from "sonamu";

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

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

Complete Preset List

disabled

Disable compression

default

Default settings (1KB, br/gzip/deflate)

aggressive

Aggressive compression (256B)

conservative

Conservative compression (4KB, gzip only)

gzipOnly

gzip only

Preset Details

disabled

Completely disables compression.
CompressPresets.disabled
// Value: false
false

default

Balanced default settings.
CompressPresets.default
// Generated configuration:
{
  threshold: 1024,  // 1KB
  encodings: ["br", "gzip", "deflate"]
}
{
  threshold: 1024,  // Only compress 1KB or larger
  encodings: ["br", "gzip", "deflate"]  // All algorithms
}
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.
CompressPresets.aggressive
// Generated configuration:
{
  threshold: 256,  // 256 bytes
  encodings: ["br", "gzip", "deflate"]
}
{
  threshold: 256,  // Only compress 256B or larger
  encodings: ["br", "gzip", "deflate"]
}
Effects:
  • Compresses everything 256 bytes and above
  • Minimizes network transfer volume
  • Slight increase in CPU overhead

conservative

Conservative compression that minimizes CPU load.
CompressPresets.conservative
// Generated configuration:
{
  threshold: 4096,  // 4KB
  encodings: ["gzip", "deflate"]  // Excludes brotli
}
{
  threshold: 4096,  // Only compress 4KB or larger
  encodings: ["gzip", "deflate"]  // Fast algorithms only
}
Characteristics:
  • Under 4KB: No compression
  • Excludes brotli (saves CPU)
  • Uses gzip only (fast + compatible)

gzipOnly

Configuration that uses only gzip.
CompressPresets.gzipOnly
// Generated configuration:
{
  threshold: 1024,  // 1KB
  encodings: ["gzip"]  // gzip only
}
{
  threshold: 1024,
  encodings: ["gzip"]  // Uses gzip only
}
Characteristics:
  • Fastest compression
  • Supported by all browsers
  • Stable

Preset Comparison Table

PresetThresholdAlgorithmsCPU UsageCompression RatioUse Case
disabled-NoneMinimal0%Development, already compressed content
default1KBbr/gzip/deflateMediumHighGeneral cases (recommended)
aggressive256Bbr/gzip/deflateHighBestBandwidth optimization
conservative4KBgzip/deflateLowMediumCPU saving, high performance
gzipOnly1KBgzipLowMediumLegacy support, stability

Compression Ratio Comparison

Based on actual 100KB JSON data:
AlgorithmCompressed SizeCompression RatioSpeed
No compression100KB0%-
deflate15KB85%Fast
gzip14KB86%Fast
brotli (br)12KB88%Slow

Production API Server

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

Mobile App Backend

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

High-Performance Real-Time API

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

Legacy Browser Support

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

Development Environment

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

Combining Presets

You can customize based on presets.
// 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

class DataModelClass extends BaseModel {
  // 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

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

Precautions when using presets:
  1. Presets are starting points: Adjust according to your situation
    // Customizing based on preset
    compress: {
      ...CompressPresets.default,
      threshold: 2048,  // Adjust to 2KB
    }
    
  2. aggressive increases CPU load: Monitor server performance
    // Warning: High CPU usage
    compress: CompressPresets.aggressive
    
  3. conservative doesn’t compress small responses: Reduced network efficiency
    // conservative: Does not compress under 4KB
    compress: CompressPresets.conservative
    
  4. disabled disables all compression: Increased transfer volume
    // Avoid disabling in production
    compress: CompressPresets.disabled
    

Performance Measurement

Performance comparison by preset (based on 100KB JSON):
PresetCompression TimeCompressed SizeNetworkTotal Time
disabled0ms100KB1000ms1000ms
gzipOnly2ms14KB140ms142ms
conservative2ms14KB140ms142ms
default5ms12KB120ms125ms
aggressive5ms12KB120ms125ms
Conclusion: brotli takes slightly longer to compress but is overall faster due to network time savings

Next Steps