Cache Presets - 🌲 Sonamu

Sonamu provides frequently used Cache-Control patterns as CachePresets. Using presets instead of writing configurations manually allows you to easily apply consistent and validated caching strategies.

CachePresets Overview

import { CachePresets } from "sonamu";

// Using in API
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.shortLived,
})

// Using in SSR
registerSSR({
  path: '/products',
  cacheControl: CachePresets.ssr,
});

Complete Preset List

noStore

No cache storage

noCache

Revalidate every time

shortLived

1 minute cache

ssr

SSR optimized (10 seconds + SWR)

mediumLived

5 minute cache

longLived

1 hour cache

immutable

Permanent cache (static files)

private

Personalized data

Preset Details

noStore

Completely prohibits cache storage.

CachePresets.noStore
// Generated header: Cache-Control: no-store

Configuration
When to Use
Example

{
  noStore: true
}

// Payment API
@api({
  httpMethod: 'POST',
  cacheControl: CachePresets.noStore,
})
async createPayment(data: PaymentSave) {
  return this.processPayment(data);
}

// Private data retrieval
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.noStore,
})
async getPrivateData(ctx: Context) {
  return this.getSensitiveData(ctx.user.id);
}

noCache

Stores cache but revalidates every time.

CachePresets.noCache
// Generated header: Cache-Control: no-cache

Configuration
When to Use
Example

{
  noCache: true
}

// Inventory info (frequently changes)
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.noCache,
})
async getInventory(productId: number) {
  return this.checkStock(productId);
}

Benefits of no-cache:

1st request: GET /api/data → 200 OK + ETag: "abc123"
2nd request: GET /api/data (If-None-Match: "abc123")
→ 304 Not Modified (no body, fast)

shortLived

1 minute cache - Suitable for frequently changing data.

CachePresets.shortLived
// Generated header: Cache-Control: public, max-age=60

Configuration
When to Use
Example

{
  visibility: 'public',
  maxAge: 60  // 60 seconds = 1 minute
}

// Post list
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.shortLived,
})
async getPosts(page: number) {
  return this.findMany({ page, num: 20 });
}

// CSR fallback
registerSSR({
  path: '/*',  // catch-all
  cacheControl: CachePresets.shortLived,
});

ssr

SSR page optimization - 10 second cache + Stale-While-Revalidate 30 seconds

CachePresets.ssr
// Generated header: Cache-Control: public, max-age=10, stale-while-revalidate=30

Configuration
How It Works
When to Use
Example

{
  visibility: 'public',
  maxAge: 10,  // Fresh for 10 seconds
  staleWhileRevalidate: 30  // Use stale for the next 30 seconds
}

// Product detail page
registerSSR({
  path: '/products/:id',
  cacheControl: CachePresets.ssr,
  Component: ProductDetail,
});

// Blog post
registerSSR({
  path: '/blog/:slug',
  cacheControl: CachePresets.ssr,
  Component: BlogPost,
});

mediumLived

5 minute cache - Suitable for rarely changing data.

CachePresets.mediumLived
// Generated header: Cache-Control: public, max-age=300

Configuration
When to Use
Example

{
  visibility: 'public',
  maxAge: 300  // 300 seconds = 5 minutes
}

// Category tree
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.mediumLived,
})
async getCategoryTree() {
  return this.buildTree();
}

// Terms of service
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.mediumLived,
})
async getTerms() {
  return this.findOne(['type', 'terms']);
}

longLived

1 hour cache - Suitable for static content.

CachePresets.longLived
// Generated header: Cache-Control: public, max-age=3600

Configuration
When to Use
Example

{
  visibility: 'public',
  maxAge: 3600  // 3600 seconds = 1 hour
}

// Country list
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.longLived,
})
async getCountries() {
  return this.findMany({});
}

// Static configuration
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.longLived,
})
async getConfig() {
  return this.config;
}

immutable

Permanent cache - For static files with hash

CachePresets.immutable
// Generated header: Cache-Control: public, max-age=31536000, immutable

Configuration
When to Use
Example

{
  visibility: 'public',
  maxAge: 31536000,  // 1 year (in seconds)
  immutable: true  // Never changes
}

Filenames with hash
- bundle-abc123.js
- styles-def456.css
- image-789xyz.png
When filename changes if content changes

// Built static files
server.get('/assets/:filename', (req, reply) => {
  const filename = req.params.filename;

  // Files with hash use immutable
  if (/\-[a-f0-9]{8,}\.(js|css|png)$/.test(filename)) {
    applyCacheHeaders(reply, CachePresets.immutable);
  }

  return reply.sendFile(filename);
});

Benefits of immutable:

Uses only cache without revalidation (fastest)
When file changes → new hash → new filename → automatic cache update

private

Personalized data - Different response per user

CachePresets.private
// Generated header: Cache-Control: private, no-cache

Configuration
When to Use
Example

{
  visibility: 'private',
  noCache: true
}

// My profile
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.private,
})
async getMyProfile(ctx: Context) {
  return this.findOne(['id', ctx.user.id]);
}

// My order list
@api({
  httpMethod: 'GET',
  cacheControl: CachePresets.private,
})
async getMyOrders(ctx: Context) {
  return this.findMany({
    where: [['user_id', ctx.user.id]]
  });
}

private vs public:

private: Cached only in browser (not on CDN)
public: Cached everywhere (browser + CDN)

Preset Comparison Table

Preset	Header	Use Case	TTL
`noStore`	`no-store`	Sensitive data, Mutations	None
`noCache`	`no-cache`	Requires revalidation	None (revalidate)
`shortLived`	`public, max-age=60`	Frequently changes	1 minute
`ssr`	`public, max-age=10, stale-while-revalidate=30`	SSR pages	10 seconds + SWR 30 seconds
`mediumLived`	`public, max-age=300`	Rarely changes	5 minutes
`longLived`	`public, max-age=3600`	Static content	1 hour
`immutable`	`public, max-age=31536000, immutable`	Hashed files	1 year (permanent)
`private`	`private, no-cache`	Personalized data	None (private)

Custom Configuration

If presets don’t fit, you can write your own configuration.

// CDN optimization (Browser: 1 minute, CDN: 5 minutes)
@api({
  httpMethod: 'GET',
  cacheControl: {
    visibility: 'public',
    maxAge: 60,      // Browser
    sMaxAge: 300,    // CDN
  }
})
async getData() {
  return this.findMany({});
}

// Adding Stale-If-Error
@api({
  httpMethod: 'GET',
  cacheControl: {
    visibility: 'public',
    maxAge: 300,
    staleIfError: 86400,  // Use stale for 1 day on error
  }
})
async getCriticalData() {
  return this.getData();
}

Global Handler

You can dynamically set Cache-Control for all requests.

// sonamu.config.ts
export const config: SonamuConfig = {
  server: {
    apiConfig: {
      cacheControlHandler: (req) => {
        // API requests
        if (req.type === 'api') {
          if (req.method !== 'GET') {
            return CachePresets.noStore;  // Mutations use no-store
          }
          return CachePresets.shortLived;  // GET uses 1 minute cache
        }

        // Static files
        if (req.type === 'assets') {
          if (req.path.includes('-')) {  // Contains hash
            return CachePresets.immutable;
          }
          return CachePresets.longLived;
        }

        // SSR
        if (req.type === 'ssr') {
          return CachePresets.ssr;
        }

        return undefined;  // Default
      }
    }
  }
};

Practical Usage

Strategy by API

class ProductModelClass extends BaseModel {
  // List: Frequently changes → Short cache
  @api({
    httpMethod: 'GET',
    cacheControl: CachePresets.shortLived,
  })
  async findAll() {
    return this.findMany({});
  }

  // Detail: Less frequent changes → Medium cache
  @api({
    httpMethod: 'GET',
    cacheControl: CachePresets.mediumLived,
  })
  async findById(id: number) {
    return this.findOne(['id', id]);
  }

  // Categories: Rarely changes → Long cache
  @api({
    httpMethod: 'GET',
    cacheControl: CachePresets.longLived,
  })
  async getCategories() {
    return this.categories;
  }

  // Create/Update: Mutation → no-store
  @api({
    httpMethod: 'POST',
    cacheControl: CachePresets.noStore,
  })
  async create(data: ProductSave) {
    return this.saveOne(data);
  }
}

SSR Pages

// Homepage: SSR optimized
registerSSR({
  path: '/',
  cacheControl: CachePresets.ssr,
  Component: HomePage,
});

// Product list: Short cache
registerSSR({
  path: '/products',
  cacheControl: CachePresets.shortLived,
  Component: ProductList,
});

// Terms: Long cache
registerSSR({
  path: '/terms',
  cacheControl: CachePresets.longLived,
  Component: Terms,
});

Precautions

Precautions when using presets:

Presets are starting points: Customize as needed

// ✅ Adjust for your situation
cacheControl: {
  ...CachePresets.shortLived,
  maxAge: 120,  // Adjusted 1 minute → 2 minutes
}

Only cache GET: Use noStore for POST, PUT, DELETE

// ❌ Wrong example
@api({
  httpMethod: 'POST',
  cacheControl: CachePresets.shortLived,
})

// ✅ Correct example
@api({
  httpMethod: 'POST',
  cacheControl: CachePresets.noStore,
})

Private data must be private: Prevent CDN caching

// ❌ Dangerous: Personal data cached on CDN
@api({
  cacheControl: CachePresets.shortLived,  // public
})
async getMyData() { ... }

// ✅ Safe
@api({
  cacheControl: CachePresets.private,
})
async getMyData() { ... }

immutable only for hashed files: Must change filename to update

// ❌ Wrong usage
// main.js (no hash) → Cache persists even if content changes
cacheControl: CachePresets.immutable

// ✅ Correct usage
// main-abc123.js (has hash) → Filename changes when content changes
cacheControl: CachePresets.immutable

Next Steps

What is Cache-Control?

HTTP caching fundamentals

Using in APIs

Apply to @api decorators

Using in SSR

Apply to SSR pages

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

​CachePresets Overview

​Complete Preset List

noStore

noCache

shortLived

ssr

mediumLived

longLived

immutable

private

​Preset Details

​noStore

​noCache

​shortLived

​ssr

​mediumLived

​longLived

​immutable

​private

​Preset Comparison Table

​Custom Configuration

​Global Handler

​Practical Usage

​Strategy by API

​SSR Pages

​Precautions

​Next Steps

What is Cache-Control?

Using in APIs

Using in SSR

CachePresets Overview

Complete Preset List

Preset Details

noStore

noCache

shortLived

ssr

mediumLived

longLived

immutable

private

Preset Comparison Table

Custom Configuration

Global Handler

Practical Usage

Strategy by API

SSR Pages

Precautions

Next Steps