Per-API Compression Control

By adding the compress option to Sonamu’s @api decorator, you can finely control compression on a per-API basis.

Basic Usage

Adding to @api Decorator

import { BaseModelClass, api, CompressPresets } from "sonamu";

class ProductModelClass extends BaseModelClass {
  @api({
    httpMethod: 'GET',
    compress: CompressPresets.aggressive,  // Aggressive compression for this API only
  })
  async findAll() {
    return this.findMany({});
  }
}

Configuration Methods

Using Presets
boolean
Custom Options

The simplest method

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

Enable/disable compression

// Disable compression
@api({
  httpMethod: 'GET',
  compress: false,
})
async getImage() {
  return this.sendImageFile();
}

// Enable compression (when global: false)
@api({
  httpMethod: 'GET',
  compress: true,
})
async getLargeData() {
  return this.findMany({ num: 10000 });
}

Fine-grained control

@api({
  httpMethod: 'GET',
  compress: {
    threshold: 512,  // Only compress 512B or larger
    encodings: ["br", "gzip"],  // brotli and gzip only
  }
})
async getData() {
  return this.findMany({});
}

Priority

Compression settings are applied in the following order:

compress in @api decorator (highest priority)
Global plugins.compress setting
Default (no compression)

Example

// sonamu.config.ts
plugins: {
  compress: CompressPresets.default,  // Global: default compression
}

// Model
@api({
  httpMethod: 'GET',
  compress: CompressPresets.aggressive,  // This API only: aggressive compression
})
async getData() { ... }

Result: aggressive applied (decorator takes priority)

Disabling Compression

To not compress a specific API:

@api({
  httpMethod: 'GET',
  compress: false,  // Ignore global settings, no compression
})
async getAlreadyCompressed() {
  return this.sendCompressedFile();
}

Use cases:

Already compressed files (images, videos, zip)
Very small responses (< 100 bytes)
Real-time streaming
Avoiding decompression errors

Selective Compression (global: false)

To not compress by default and selectively compress specific APIs:

// sonamu.config.ts
export const config: SonamuConfig = {
  server: {
    plugins: {
      compress: {
        global: false,  // No compression by default
        threshold: 1024,
        encodings: ["br", "gzip", "deflate"],
      }
    }
  }
};

// Model - selective compression
class DataModelClass extends BaseModelClass {
  // Compress only this API
  @api({
    httpMethod: 'GET',
    compress: true,
  })
  async getLargeData() {
    return this.findMany({ num: 10000 });
  }

  // No compression (default)
  @api({
    httpMethod: 'GET',
  })
  async getSmallData() {
    return { status: "ok" };
  }
}

Advantages:

Prevent unnecessary compression
Minimize CPU usage
Precise control

Strategy by Response Size

Small Responses (< 1KB)

@api({
  httpMethod: 'GET',
  compress: false,  // Disable compression
})
async getStatus() {
  return { status: "ok", timestamp: Date.now() };
}

Reason: Compression overhead is greater than the benefit

Medium Responses (1KB-100KB)

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

Reason: Good compression effectiveness

Large Responses (> 100KB)

@api({
  httpMethod: 'GET',
  compress: CompressPresets.aggressive,  // Aggressive compression
})
async exportData() {
  return this.findMany({ num: 10000 });
}

Reason: Network time savings far outweigh compression time

Strategy by Content Type

JSON API

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

Characteristic: JSON compresses very well (70-90% reduction)

Images/Binary

@api({
  httpMethod: 'GET',
  compress: false,  // Disable compression
})
async getImage(id: number) {
  return this.sendFile(`images/${id}.jpg`);
}

Reason: Already compressed formats (JPEG, PNG, MP4, etc.)

HTML/CSS

@api({
  httpMethod: 'GET',
  compress: CompressPresets.aggressive,
})
async getHTML() {
  return this.renderTemplate();
}

Characteristic: Text-based, very good compression effectiveness

Practical Examples

1. E-commerce API

class ProductModelClass extends BaseModelClass {
  // Product list: default compression
  @api({
    httpMethod: 'GET',
    compress: CompressPresets.default,
  })
  async findAll(page: number) {
    return this.findMany({ page, num: 20 });
  }

  // Product detail: default compression
  @api({
    httpMethod: 'GET',
    compress: CompressPresets.default,
  })
  async findById(id: number) {
    return this.findOne(['id', id]);
  }

  // Bulk data export: aggressive compression
  @api({
    httpMethod: 'GET',
    compress: CompressPresets.aggressive,
  })
  async exportAll() {
    return this.findMany({ num: 100000 });
  }

  // Product image: no compression
  @api({
    httpMethod: 'GET',
    compress: false,
  })
  async getImage(id: number) {
    return this.sendFile(`products/${id}.jpg`);
  }

  // Create/update: no compression (small response)
  @api({
    httpMethod: 'POST',
    compress: false,
  })
  async create(data: ProductSave) {
    return this.saveOne(data);
  }
}

2. File Download API

class FileModelClass extends BaseModelClass {
  // JSON file: aggressive compression
  @api({
    httpMethod: 'GET',
    compress: CompressPresets.aggressive,
  })
  async downloadJSON(id: number) {
    return this.getJSONFile(id);
  }

  // Already compressed file: no compression
  @api({
    httpMethod: 'GET',
    compress: false,
  })
  async downloadZip(id: number) {
    return this.getZipFile(id);
  }

  // Text file: default compression
  @api({
    httpMethod: 'GET',
    compress: CompressPresets.default,
  })
  async downloadText(id: number) {
    return this.getTextFile(id);
  }
}

3. Statistics/Report API

class ReportModelClass extends BaseModelClass {
  // Real-time stats: conservative compression (fast response)
  @api({
    httpMethod: 'GET',
    compress: CompressPresets.conservative,
  })
  async getRealTimeStats() {
    return this.calculateRealTimeStats();
  }

  // Daily report: default compression
  @api({
    httpMethod: 'GET',
    compress: CompressPresets.default,
  })
  async getDailyReport(date: string) {
    return this.generateDailyReport(date);
  }

  // Large-scale analysis: aggressive compression
  @api({
    httpMethod: 'GET',
    compress: CompressPresets.aggressive,
  })
  async getFullAnalysis(startDate: string, endDate: string) {
    return this.generateFullAnalysis(startDate, endDate);
  }
}

4. Streaming API

class StreamModelClass extends BaseModelClass {
  // SSE stream: no compression
  @stream({
    type: 'sse',
    events: z.object({
      message: z.string(),
    }),
  })
  @api({
    compress: false,  // No compression for streaming
  })
  async *streamUpdates() {
    yield { message: "update 1" };
    yield { message: "update 2" };
  }
}

SSR Page Compression

Compression settings are also available for SSR routes.

import { registerSSR, CompressPresets } from "sonamu";

// HTML page: aggressive compression
registerSSR({
  path: '/products/:id',
  Component: ProductDetail,
  compress: CompressPresets.aggressive,
});

// Small page: default compression
registerSSR({
  path: '/about',
  Component: About,
  compress: CompressPresets.default,
});

// Disable compression
registerSSR({
  path: '/stream',
  Component: StreamPage,
  compress: false,
});

Conditional Compression

While you cannot control compression at runtime based on conditions, you can separate into multiple APIs:

// Compressed version
@api({
  httpMethod: 'GET',
  path: '/products',
  compress: CompressPresets.aggressive,
})
async getProducts() {
  return this.findMany({});
}

// Uncompressed version (for special clients)
@api({
  httpMethod: 'GET',
  path: '/products/raw',
  compress: false,
})
async getProductsRaw() {
  return this.findMany({});
}

Compression Option Override

You can change only part of the global settings:

// Global: default preset
plugins: {
  compress: CompressPresets.default,  // threshold: 1024
}

// API: change threshold only
@api({
  httpMethod: 'GET',
  compress: {
    threshold: 2048,  // Change to 2KB
    // encodings keeps global settings
  }
})
async getData() {
  return this.findMany({});
}

Monitoring

To verify compression effectiveness:

@api({
  httpMethod: 'GET',
  compress: CompressPresets.default,
})
async getData() {
  const data = this.findMany({});

  // Log size in development environment
  if (process.env.NODE_ENV === 'development') {
    const size = JSON.stringify(data).length;
    console.log(`Response size: ${size} bytes`);
  }

  return data;
}

Check in browser developer tools:

Network tab -> Select request -> Headers tab

Response Headers:
  Content-Encoding: gzip
  Content-Length: 1234 (compressed size)

Size:
  1.2 KB (compressed)
  10.5 KB (original)

Precautions

Precautions for per-API compression control:

Disable for already compressed content: images, videos, zip

// Good example
@api({ compress: false })
async getImage() { return this.sendImageFile(); }

Compression is inefficient for small responses: Better not to compress < 1KB

// Small response
@api({ compress: false })
async getStatus() { return { status: "ok" }; }

Disable compression for streaming: SSE, WebSocket

// Streaming
@stream({ type: 'sse', events: ... })
@api({ compress: false })
async *streamData() { ... }

Use consistent strategy: Similar APIs should have the same settings

// Consistency
// All query APIs: default
// All bulk exports: aggressive
// All binary: false

Monitor performance: Check CPU load due to compression

// Server CPU usage monitoring needed when using aggressive

Debugging Tips

1. Verify Compression is Applied

# Check with curl
curl -H "Accept-Encoding: gzip" http://localhost:3000/api/products -v

# Check response header
< Content-Encoding: gzip

2. Compare Compression Sizes

# Without compression
curl http://localhost:3000/api/products > uncompressed.json
ls -lh uncompressed.json  # 100KB

# With compression
curl -H "Accept-Encoding: gzip" http://localhost:3000/api/products --compressed > compressed.json
ls -lh compressed.json  # 10KB

3. Check Compression Algorithm

// Check in test code
const response = await server.inject({
  method: 'GET',
  url: '/api/products',
  headers: { 'accept-encoding': 'br, gzip' }
});

console.log(response.headers['content-encoding']);  // "br" or "gzip"

Next Steps

Compression Configuration

Global compression plugin settings

Compression Presets

Predefined compression settings

Performance Optimization

Compression optimization strategies

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

​Basic Usage

​Adding to @api Decorator

​Configuration Methods

​Priority

​Example

​Disabling Compression

​Selective Compression (global: false)

​Strategy by Response Size

​Small Responses (< 1KB)

​Medium Responses (1KB-100KB)

​Large Responses (> 100KB)

​Strategy by Content Type

​JSON API

​Images/Binary

​HTML/CSS

​Practical Examples

​1. E-commerce API

​2. File Download API

​3. Statistics/Report API

​4. Streaming API

​SSR Page Compression

​Conditional Compression

​Compression Option Override

​Monitoring

​Precautions

​Debugging Tips

​1. Verify Compression is Applied

​2. Compare Compression Sizes

​3. Check Compression Algorithm

​Next Steps