Compression Presets - 🌲 Sonamu

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

Configuration
When to Use
Example

false

// 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();
}

default

Balanced default settings.

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

Configuration
When to Use
Example

{
  threshold: 1024,  // Only compress 1KB or larger
  encodings: ["br", "gzip", "deflate"]  // All algorithms
}

// Global configuration
export const config: SonamuConfig = {
  server: {
    plugins: {
      compress: CompressPresets.default
    }
  }
};

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

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"]
}

Configuration
When to Use
Example

{
  threshold: 256,  // Only compress 256B or larger
  encodings: ["br", "gzip", "deflate"]
}

// 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() };
}

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
}

Configuration
When to Use
Example

{
  threshold: 4096,  // Only compress 4KB or larger
  encodings: ["gzip", "deflate"]  // Fast algorithms only
}

// 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 });
}

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
}

Configuration
When to Use
Example

{
  threshold: 1024,
  encodings: ["gzip"]  // Uses gzip only
}

// 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();
}

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

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 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

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:

Presets are starting points: Adjust according to your situation

// Customizing based on preset
compress: {
  ...CompressPresets.default,
  threshold: 2048,  // Adjust to 2KB
}

aggressive increases CPU load: Monitor server performance

// Warning: High CPU usage
compress: CompressPresets.aggressive

conservative doesn’t compress small responses: Reduced network efficiency

// conservative: Does not compress under 4KB
compress: CompressPresets.conservative

disabled disables all compression: Increased transfer volume

// Avoid disabling in production
compress: CompressPresets.disabled

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

Compression Configuration

Global compression plugin settings

Per-API Control

Compression settings in @api decorator

Performance Optimization

Compression optimization strategies

​CompressPresets Overview

​Complete Preset List

disabled

default

aggressive

conservative

gzipOnly

​Preset Details

​disabled

​default

​aggressive

​conservative

​gzipOnly

​Preset Comparison Table

​Compression Ratio Comparison

​Recommended Presets by Scenario

​Production API Server

​Mobile App Backend

​High-Performance Real-Time API

​Legacy Browser Support

​Development Environment

​Combining Presets

​Per-API Presets

​Environment-Based Presets

​Precautions

​Performance Measurement

​Next Steps

Compression Configuration

Per-API Control

Performance Optimization

CompressPresets Overview

Complete Preset List

Preset Details

disabled

default

aggressive

conservative

gzipOnly

Preset Comparison Table

Compression Ratio Comparison

Recommended Presets by Scenario

Production API Server

Mobile App Backend

High-Performance Real-Time API

Legacy Browser Support

Development Environment

Combining Presets

Per-API Presets

Environment-Based Presets

Precautions

Performance Measurement

Next Steps