Caching

NotPixel includes an in-memory cache with TTL (Time-To-Live) to reduce API calls and improve performance.

Enable Caching

import Ads from 'notpixel';
 
const ads = new Ads({
  publisherId: 'pub_10565',
  model: 'openai/gpt-5.2',
  input: 'Recommend monitoring tools for a production Postgres cluster.',
  cache: true,
});

Custom Configuration

You can customize the cache behavior:

const ads = new Ads({
  publisherId: 'pub_10565',
  model: 'openai/gpt-5.2',
  input: 'Recommend monitoring tools for a production Postgres cluster.',
  cache: {
    ttlMs: 300000,  // 5 minutes (default: 5 min)
    maxSize: 100,   // max entries (default: 100)
  },
});

Cache API

Access cache statistics and management:

// Get cache stats
const stats = ads.cache.stats();
console.log(stats);
// { size: 10, hits: 50, misses: 5, hitRate: 0.91 }
 
// Clear all cached entries
ads.cache.clear();
 
// Remove expired entries only
ads.cache.cleanup();

How It Works

1. When you call ads.getAd(), the SDK checks if a cached response exists for that input
2. If found and not expired, returns the cached ad immediately
3. If not found or expired, fetches from API and caches the result
4. Cache automatically evicts oldest entries when maxSize is reached

Best Practices

• Enable caching for high-traffic applications to reduce latency
• Adjust ttlMs based on how often your ad inventory changes
• Monitor hitRate to ensure caching is effective
• Call cleanup() periodically in long-running processes