@cache Decorator

You can use the @cache decorator to automatically cache the results of Model or Frame methods.

Basic Usage

Simple Example

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

class UserModelClass extends BaseModelClass {
  @cache({ ttl: "10m" })
  @api()
  async findById(id: number) {
    // This method is cached for 10 minutes
    return this.findOne(['id', id]);
  }
}

How It Works:

First call: DB query → Cache result
Second call (within 10 minutes): Return from cache (no DB query)
After 10 minutes: Query DB again → Refresh cache

Decorator Options

All Options

@cache({
  key?: string | ((...args: unknown[]) => string),  // Cache key
  store?: string,           // Store to use
  ttl?: string | number,    // Expiration time
  grace?: string | number,  // Grace period (Stale-While-Revalidate)
  tags?: string[],          // Tag list
  forceFresh?: boolean,     // Ignore cache and force refresh
})

key: Cache Key Configuration

If no key is specified, it is automatically generated.

Auto-generated (Default)
String Key
Function Key

class UserModelClass extends BaseModelClass {
  @cache({ ttl: "10m" })
  async findById(id: number) {
    return this.findOne(['id', id]);
  }
}

// Call: userModel.findById(123)
// Auto-generated key: "User.findById:123"

Pattern: ModelName.methodName:serializedArgsArgument Serialization Rules:

Single primitive (string/number/boolean): Used as-is
Complex objects: Uses JSON.stringify
No arguments: ModelName.methodName without suffix

@cache({ key: "user-list", ttl: "5m" })
async findAll() {
  return this.findMany({});
}

// Call: userModel.findAll()
// Key: "user-list"

@cache({ key: "user", ttl: "10m" })
async findById(id: number) {
  return this.findOne(['id', id]);
}

// Call: userModel.findById(123)
// Key: "user:123" (arguments auto-appended as suffix)

When arguments exist: Auto-generated in key:args format

@cache({
  key: (userId: number, status: string) => `user:${userId}:${status}`,
  ttl: "10m"
})
async findByStatus(userId: number, status: string) {
  return this.findMany({ user_id: userId, status });
}

// Call: model.findByStatus(123, "active")
// Key: "user:123:active"

Useful for complex key generation

ttl: Expiration Time

TTL (Time To Live) is the duration the cache remains valid.

// String format (recommended)
@cache({ ttl: "10s" })   // 10 seconds
@cache({ ttl: "5m" })    // 5 minutes
@cache({ ttl: "1h" })    // 1 hour
@cache({ ttl: "1d" })    // 1 day
@cache({ ttl: "1w" })    // 1 week
@cache({ ttl: "forever" }) // Permanent

// Number format (milliseconds)
@cache({ ttl: 60000 })  // 60000ms = 1 minute

Without TTL: BentoCache default value applies (typically unlimited)

grace: Stale-While-Revalidate

Grace period is a feature that returns stale cache after TTL expiration while refreshing in the background.

@cache({
  ttl: "1m",      // Expires after 1 minute
  grace: "10m"    // Return stale value for 10 minutes after expiration
})
async getExpensiveData() {
  // Long-running operation
  return await this.heavyComputation();
}

How It Works:

0~1 minute: Return fresh cache
1~11 minutes: Immediately return stale cache + background refresh
After 11 minutes: Cache miss, recalculate

Advantages:

Users always get fast response (even if stale, returns immediately)
Refreshed in background so next user gets fresh data

tags: Tag-based Invalidation

You can use tags to invalidate related caches as a group.

class ProductModelClass extends BaseModelClass {
  @cache({ ttl: "1h", tags: ["product", "list"] })
  @api()
  async findAll() {
    return this.findMany({});
  }

  @cache({ ttl: "1h", tags: ["product"] })
  @api()
  async findById(id: number) {
    return this.findOne(['id', id]);
  }

  @api()
  async update(id: number, data: Partial<Product>) {
    const result = await this.updateOne(['id', id], data);

    // Invalidate all caches with product tag
    await Sonamu.cache.deleteByTag({ tags: ["product"] });

    return result;
  }
}

Invalidation Pattern:

// When update() is called
await Sonamu.cache.deleteByTag({ tags: ["product"] });

// Result: Both findAll() and findById() caches are deleted

For more details, see Cache Invalidation.

store: Using a Specific Store

When multiple stores are configured, you can specify a particular store.

// Define multiple stores in sonamu.config.ts
export const config: SonamuConfig = {
  server: {
    cache: {
      default: "api",
      stores: {
        api: store().useL1Layer(drivers.memory({ maxSize: "200mb" })),
        database: store()
          .useL1Layer(drivers.memory({ maxSize: "100mb" }))
          .useL2Layer(drivers.redis({ connection: redis })),
      },
    },
  },
};

// Specify store in Model
class UserModelClass extends BaseModelClass {
  // Use api store (default)
  @cache({ ttl: "5m" })
  @api()
  async findAll() {
    return this.findMany({});
  }

  // Use database store (Redis shared)
  @cache({ store: "database", ttl: "1h" })
  @api()
  async findById(id: number) {
    return this.findOne(['id', id]);
  }
}

forceFresh: Ignore Cache

Use when you always want to fetch fresh data.

@cache({
  ttl: "1h",
  forceFresh: true  // Ignore cache and always run factory
})
async getRealTimeData() {
  return await this.fetchFromExternalAPI();
}

Use Case: Only for debugging or special cases (generally unnecessary)

Practical Examples

1. API Response Caching

class PostModelClass extends BaseModelClass {
  // Post list (5 minute cache)
  @cache({ ttl: "5m", tags: ["post", "list"] })
  @api()
  async findAll(page: number = 1) {
    return this.findMany({
      num: 20,
      page,
      order: [['created_at', 'desc']]
    });
  }

  // Post detail (10 minute cache)
  @cache({ ttl: "10m", tags: ["post"] })
  @api()
  async findById(id: number) {
    return this.findOne(['id', id]);
  }

  // Popular posts (1 hour cache)
  @cache({
    key: "popular-posts",
    ttl: "1h",
    tags: ["post", "popular"]
  })
  @api()
  async findPopular() {
    return this.findMany({
      num: 10,
      where: [['view_count', '>', 1000]],
      order: [['view_count', 'desc']]
    });
  }
}

2. Cache Invalidation on Data Change

class ProductModelClass extends BaseModelClass {
  @cache({ ttl: "1h", tags: ["product"] })
  @api()
  async findById(id: number) {
    return this.findOne(['id', id]);
  }

  @cache({ ttl: "30m", tags: ["product", "list"] })
  @api()
  async findAll() {
    return this.findMany({});
  }

  @api()
  async create(data: ProductSave) {
    const result = await this.saveOne(data);

    // Invalidate only list tag (new item added to list)
    await Sonamu.cache.deleteByTag({ tags: ["list"] });

    return result;
  }

  @api()
  async update(id: number, data: Partial<ProductSave>) {
    const result = await this.updateOne(['id', id], data);

    // Invalidate all product tags (detail + list)
    await Sonamu.cache.deleteByTag({ tags: ["product"] });

    return result;
  }
}

3. Complex Key Generation

class OrderModelClass extends BaseModelClass {
  @cache({
    key: (userId: number, status: string, startDate: string) =>
      `order:user:${userId}:${status}:${startDate}`,
    ttl: "10m",
    tags: ["order"]
  })
  @api()
  async findByUserAndStatus(
    userId: number,
    status: string,
    startDate: string
  ) {
    return this.findMany({
      where: [
        ['user_id', userId],
        ['status', status],
        ['created_at', '>=', startDate]
      ]
    });
  }
}

// Call: model.findByUserAndStatus(123, "pending", "2025-01-01")
// Key: "order:user:123:pending:2025-01-01"

4. Using Stale-While-Revalidate

class AnalyticsModelClass extends BaseModelClass {
  @cache({
    ttl: "5m",      // Expires after 5 minutes
    grace: "1h",    // Use stale value for 1 hour
    tags: ["analytics"]
  })
  @api()
  async getDashboardStats() {
    // Heavy aggregation query
    const [users, orders, revenue] = await Promise.all([
      this.countUsers(),
      this.countOrders(),
      this.calculateRevenue(),
    ]);

    return { users, orders, revenue };
  }
}

Scenario:

0~5 minutes: Fresh cache
5~65 minutes: Immediately return stale cache + background recalculation
After 65 minutes: Cache miss, recalculate

5. Permanent Caching for Configuration Values

class ConfigModelClass extends BaseModelClass {
  @cache({
    key: "app-config",
    ttl: "forever",  // Permanent caching
    tags: ["config"]
  })
  @api()
  async getAppConfig() {
    return this.findOne(['key', 'app_config']);
  }

  @api()
  async updateConfig(data: ConfigSave) {
    const result = await this.saveOne(data);

    // Invalidate cache on config change
    await Sonamu.cache.deleteByTag({ tags: ["config"] });

    return result;
  }
}

Cache is also shared when calling other methods within a Model.

class UserModelClass extends BaseModelClass {
  // Apply cache to findMany
  @cache({ ttl: "10m", tags: ["user"] })
  @api()
  async findMany(params: FindManyParams<User>) {
    return super.findMany(params);
  }

  // findById internally calls findMany
  async findById(id: number) {
    const { rows } = await this.findMany({
      where: [['id', id]],
      num: 1
    });
    return rows[0];
  }
}

How It Works:

// First call
await userModel.findById(123);
// → Calls findMany({ where: [['id', 123]], num: 1 })
// → DB query and caching

// Second call (same parameters)
await userModel.findById(123);
// → Calls findMany({ where: [['id', 123]], num: 1 })
// → Return from cache (no DB query)

// Direct findMany call also uses same cache
await userModel.findMany({ where: [['id', 123]], num: 1 });
// → Return from cache

Cache Key Generation Logic

Argument Serialization

// Inside decorator.ts
function serializeArgs(args: unknown[]): string {
  if (args.length === 0) return "";

  // Single primitive value
  if (args.length === 1) {
    const arg = args[0];
    if (arg === null || arg === undefined) return "";
    if (typeof arg === "string" || typeof arg === "number" || typeof arg === "boolean") {
      return String(arg);
    }
  }

  // Complex values are JSON serialized
  try {
    return JSON.stringify(args);
  } catch {
    // Use toString on serialization failure
    return args.map((arg) => String(arg)).join(":");
  }
}

Examples:

// Single primitive
serializeArgs([123]) → "123"
serializeArgs(["hello"]) → "hello"

// Complex object
serializeArgs([{ id: 1, name: "test" }]) → '[{"id":1,"name":"test"}]'

// Multiple arguments
serializeArgs([123, "active"]) → '[123,"active"]'

Full Key Generation

function generateCacheKey(
  modelName: string,
  methodName: string,
  args: unknown[],
  keyOption?: string | Function,
): string {
  // 1. Custom key function
  if (typeof keyOption === "function") {
    return keyOption(...args);
  }

  // 2. String key + args suffix
  if (typeof keyOption === "string") {
    const argsSuffix = serializeArgs(args);
    return argsSuffix ? `${keyOption}:${argsSuffix}` : keyOption;
  }

  // 3. Auto-generated
  const baseKey = `${modelName}.${methodName}`;
  const argsSuffix = serializeArgs(args);
  return argsSuffix ? `${baseKey}:${argsSuffix}` : baseKey;
}

Direct Cache Manipulation

You can also manipulate the cache directly without decorators.

import { Sonamu } from "sonamu";

class UserModelClass extends BaseModelClass {
  @api()
  async findById(id: number) {
    const cacheKey = `user:${id}`;

    // Check cache
    const cached = await Sonamu.cache.get({ key: cacheKey });
    if (cached) {
      return cached;
    }

    // DB query
    const user = await this.findOne(['id', id]);

    // Cache
    await Sonamu.cache.set({
      key: cacheKey,
      value: user,
      ttl: "10m",
      tags: ["user"]
    });

    return user;
  }
}

Decorator vs Direct Manipulation:

Decorator: Concise, declarative, automatic key generation
Direct Manipulation: Complex logic, conditional caching, fine-grained control

Cautions

@cache Decorator Cautions:

Cache Manager Initialization Required: Error if no cache configuration in sonamu.config.ts

// Error: CacheManager is not initialized
@cache({ ttl: "10m" })
async findById(id: number) { ... }

Async Methods Only: Cannot be used with synchronous methods

// ❌ Error
@cache({ ttl: "10m" })
findByIdSync(id: number) { ... }

// ✅ OK
@cache({ ttl: "10m" })
async findById(id: number) { ... }

Store Name Matching: The store option must match names defined in configuration

// sonamu.config.ts
stores: {
  myStore: store()...
}

// ❌ Error
@cache({ store: "wrongName", ttl: "10m" })

// ✅ OK
@cache({ store: "myStore", ttl: "10m" })

Serializable Values Only: Functions, Symbols, etc. cannot be cached

// ❌ Bad example
@cache({ ttl: "10m" })
async getProcessor() {
  return {
    process: () => { ... }  // Functions cannot be serialized
  };
}

// ✅ Good example
@cache({ ttl: "10m" })
async getData() {
  return {
    id: 1,
    name: "test",
    values: [1, 2, 3]
  };
}

Argument Order Matters: Same values in different order result in different keys

@cache({ ttl: "10m" })
async find(name: string, age: number) { ... }

find("John", 30)  // Key: "Model.find:["John",30]"
find(30, "John")  // Key: "Model.find:[30,"John"]" (different key!)

Next Steps

Cache Configuration

Configure Stores and Drivers

Cache Invalidation

Tag-based cache invalidation

Cache Strategies

TTL, Grace, Namespace usage

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

Basic Usage

Simple Example

Decorator Options

All Options

key: Cache Key Configuration

ttl: Expiration Time

grace: Stale-While-Revalidate

tags: Tag-based Invalidation

store: Using a Specific Store

forceFresh: Ignore Cache

Practical Examples

1. API Response Caching

2. Cache Invalidation on Data Change

3. Complex Key Generation

4. Using Stale-While-Revalidate

5. Permanent Caching for Configuration Values

Cache Key Generation Logic

Argument Serialization

Full Key Generation

Direct Cache Manipulation

Cautions

Next Steps

Cache Configuration

Cache Invalidation

Cache Strategies

​Basic Usage

​Simple Example

​Decorator Options

​All Options

​key: Cache Key Configuration

​ttl: Expiration Time

​grace: Stale-While-Revalidate

​tags: Tag-based Invalidation

​store: Using a Specific Store

​forceFresh: Ignore Cache

​Practical Examples

​1. API Response Caching

​2. Cache Invalidation on Data Change

​3. Complex Key Generation

​4. Using Stale-While-Revalidate

​5. Permanent Caching for Configuration Values

​Internal Method Calls and Cache Sharing

​Cache Key Generation Logic

​Argument Serialization

​Full Key Generation

​Direct Cache Manipulation

​Cautions

​Next Steps

Cache Configuration

Cache Invalidation

Cache Strategies

Basic Usage

Simple Example

Decorator Options

All Options

key: Cache Key Configuration

ttl: Expiration Time

grace: Stale-While-Revalidate

tags: Tag-based Invalidation

store: Using a Specific Store

forceFresh: Ignore Cache

Practical Examples

1. API Response Caching

2. Cache Invalidation on Data Change

3. Complex Key Generation

4. Using Stale-While-Revalidate

5. Permanent Caching for Configuration Values

Internal Method Calls and Cache Sharing

Cache Key Generation Logic

Argument Serialization

Full Key Generation

Direct Cache Manipulation

Cautions

Next Steps