getOrFetch(key)
  │
  ├─ 1. L1 Check (process memory, ~0.001ms)
  │    ├─ HIT + fresh? → Return immediately ✅
  │    ├─ HIT + stale? → Return stale + background revalidate 🔄
  │    └─ MISS → continue
  │
  ├─ 2. L2 Check (Redis/Postgres via Storage adapter, ~1-5ms)
  │    ├─ HIT + fresh? → Populate L1, return ✅
  │    ├─ HIT + stale? → Populate L1, return stale + revalidate 🔄
  │    └─ MISS → continue
  │
  ├─ 3. Negative Cache Check
  │    ├─ Key is cached as "not found"? → Return null ✅
  │    └─ No negative entry → continue
  │
  ├─ 4. Stampede Protection
  │    ├─ Single-flight dedup: another request for same key in-flight?
  │    │   YES → Wait for the in-flight request, share result
  │    ├─ Cluster lock: clusterLock enabled?
  │    │   YES → Acquire distributed lock (only 1 server fetches)
  │    │   NO  → Local single-flight only
  │    └─ continue
  │
  ├─ 5. Execute Fetcher
  │    ├─ Inline fetcher provided? → Use it
  │    ├─ Global fetcher defined? → Use it
  │    └─ Neither? → Return undefined
  │
  ├─ 6. Fetcher returned value:
  │    ├─ null + negativeCache enabled? → Cache as negative, return null
  │    ├─ value → Write to L1 + L2, return value ✅
  │    └─ error + staleIfErrorMs? → Return stale data if available
  │
  └─ 7. Release cluster lock (if acquired)

import { cache } from 'oqronkit';
import { db } from '../db';

export interface Product {
  id: string;
  tenantId: string;
  name: string;
  price: number;
  stock: number;
}

export const productCache = cache<Product>({
  name: 'products',
  
  // Cache for 1 hour. We can use a function to make it dynamic!
  ttlMs: (product) => product.stock === 0 ? 60_000 : 3600_000, // Cache out-of-stock items for only 1 min
  
  // Define tags so we can easily invalidate groups of products later
  tags: ['ecommerce', 'catalog'],

  // Highly optimized database batching. 
  // If we request 50 products and 10 are missing from L1/L2, this fetcher only runs ONCE for the 10 missing keys!
  fetcherMany: async (keys, ctx) => {
    const products = await db.products.findMany({ where: { id: { in: keys } } });
    
    return products.reduce((acc, product) => {
      acc[product.id] = product;
      
      // We dynamically tag each cache entry with its tenant.
      // This allows us to purge an entire tenant's products instantly.
      ctx.log.info(`Fetched product ${product.id}`);
      return acc;
    }, {} as Record<string, Product>);
  },
  
  // Prevent database hammering during a cache miss
  stampedeProtection: {
    clusterLock: true,        // Only 1 server in the whole cluster can fetch a missing key
    lockTtlMs: 10_000         // Fetcher has 10 seconds to finish before lock releases
  }
});

import { productCache } from '../services/product.cache';

// Fetch multiple products at once
app.get('/api/products/batch', async (req, res) => {
  const ids = req.query.ids.split(','); // e.g. "prod_1,prod_2,prod_3"
  
  // Automatically hits L1 RAM -> L2 Redis -> Database (fetcherMany)
  const productsMap = await productCache.getOrFetchMany(ids);
  
  res.json(productsMap);
});

// Admin Route: Update a product and invalidate its cache
app.patch('/api/admin/products/:id', async (req, res) => {
  await db.products.update(req.params.id, req.body);
  
  // Instantly invalidates this specific key across all L1/L2 tiers on all servers
  await productCache.invalidate(req.params.id); 
  res.send('Updated');
});

// Admin Route: Purge an entire tenant's catalog instantly
app.post('/api/admin/tenants/:tenantId/purge-products', async (req, res) => {
  // If you manually tagged entries during set() or fetcherMany(), you can invalidate by tag!
  await productCache.invalidateTags([`tenant:${req.params.tenantId}`]);
  res.send('Tenant catalog purged');
});

import { cache } from 'oqronkit';
import { authService } from '../auth';

export interface SessionData {
  userId: string;
  role: 'admin' | 'user';
  permissions: string[];
}

export const sessionCache = cache<SessionData | null>({
  name: 'user-sessions',
  ttlMs: 300_000, // 5 minutes
  
  // Security: Only keep sessions in Node.js RAM (L1). Do not write to Redis/Postgres (L2).
  l2: { enabled: false },
  
  // Security: If an attacker tries millions of random session IDs, 
  // cache the "Not Found" (null) result for 30 seconds so we don't hammer the database!
  negativeCache: {
    enabled: true,
    ttlMs: 30_000,
    shouldCache: (value, error) => value === null || error !== undefined
  },
  
  fetcher: async (sessionId, ctx) => {
    try {
      const session = await authService.validateSession(sessionId);
      return session; // Returns null if invalid
    } catch (err) {
      ctx.log.error(`Session validation failed for ${sessionId}`);
      throw err;
    }
  }
});

import { sessionCache } from '../services/session.cache';

export async function requireAuth(req, res, next) {
  const sessionId = req.cookies['session_id'];
  if (!sessionId) return res.status(401).send('Unauthorized');
  
  // Because L2 is disabled, this checks local RAM. If miss, it runs the fetcher.
  const session = await sessionCache.getOrFetch(sessionId);
  
  if (!session) {
    return res.status(401).send('Invalid Session');
  }
  
  req.user = session;
  next();
}

app.post('/api/logout', async (req, res) => {
  // Purge the session from RAM immediately
  await sessionCache.delete(req.cookies['session_id']);
  res.clearCookie('session_id').send('Logged out');
});

import { cache } from 'oqronkit';

export const githubStarsCache = cache<number>({
  name: 'github-stars',
  ttlMs: 60_000, // Consider data fresh for 1 minute
  
  // If the data is older than 1 minute, but less than 1 hour old:
  // 1. Immediately return the stale data to the user (0ms latency!)
  // 2. In the background, run the fetcher and update the cache.
  staleWhileRevalidateMs: 3600_000, // 1 hour
  
  // If GitHub API goes down, serve stale data for up to 24 hours to keep the site alive.
  staleIfErrorMs: 86400_000,
  
  fetcher: async (repoName) => {
    const res = await fetch(`https://api.github.com/repos/${repoName}`);
    if (!res.ok) throw new Error('GitHub API Error');
    const data = await res.json();
    return data.stargazers_count;
  }
});

// In your API:
app.get('/api/stars/:owner/:repo', async (req, res) => {
  const repo = `${req.params.owner}/${req.params.repo}`;
  
  // This will return instantly if the cache is hot OR if it's stale (kicking off a background refresh).
  const stars = await githubStarsCache.getOrFetch(repo);
  res.json({ stars });
});

import { cache } from 'oqronkit'

// Just name and TTL. Beautifully simple.
// Gets L1 memory cache, L2 Storage, and local single-flight deduping out of the box.
export const simpleCache = cache<string>({
  name: 'simple',
  ttlMs: 60_000,
  
  fetcher: async (id) => await db.findById(id)
})

import { cache } from 'oqronkit';

// No fetcher defined here — this cache is purely a storage shell.
export const socialProfileCache = cache<SocialProfile>({
  name: 'social-profiles',
  ttlMs: 600_000, // 10 minutes
});

import { socialProfileCache } from '../services/social.cache';

app.get('/api/users/:id/social', async (req, res) => {
  const authToken = req.headers.authorization;
  const tenantId = req.headers['x-tenant-id'];
  
  // The fetcher is injected RIGHT HERE, with full access to request context.
  const profile = await socialProfileCache.getOrFetch(req.params.id, {
    fetcher: async (key, ctx) => {
      ctx.log.info(`Fetching social profile for ${key}`);
      // Use auth token from the current request — impossible to do in a global fetcher!
      return await socialApi.getProfile(key, { 
        token: authToken,
        tenant: tenantId 
      });
    },
    // You can also override TTL, tags, and timeout per call
    ttlMs: 120_000,
    tags: [`tenant:${tenantId}`],
    timeoutMs: 5000,
  });
  
  res.json(profile);
});

import { socialProfileCache } from '../services/social.cache';

app.get('/api/dashboard/team', async (req, res) => {
  const teamMemberIds = req.query.ids.split(',');
  const authToken = req.headers.authorization;
  
  // Inline fetcherMany — only called for keys that miss L1 and L2.
  const profiles = await socialProfileCache.getOrFetchMany(teamMemberIds, {
    fetcherMany: async (missingKeys, ctx) => {
      ctx.log.info(`Batch fetching ${missingKeys.length} profiles`);
      
      // One single API call for all missing keys
      const results = await socialApi.getProfiles(missingKeys, { token: authToken });
      
      // Return a Record<string, T> mapping each key to its value
      return results.reduce((acc, profile) => {
        acc[profile.id] = profile;
        return acc;
      }, {} as Record<string, SocialProfile>);
    },
    // Control concurrency if falling back to individual fetcher calls
    concurrency: 3,
    // Stop on first error, or continue fetching remaining keys
    stopOnError: false,
  });
  
  res.json(profiles);
});

export const productCache = cache<Product>({
  name: 'products',
  ttlMs: 3600_000,
  fetcher: async (id) => db.products.findById(id), // Default: hit our own database
});

// In a specific controller, override to fetch from an external partner API instead
app.get('/api/partner/products/:id', async (req, res) => {
  const product = await productCache.getOrFetch(req.params.id, {
    fetcher: async (id) => partnerApi.fetchProduct(id, { apiKey: req.query.key }),
    forceRefresh: true, // Always bypass cache and re-fetch from partner
  });
  res.json(product);
});

export const topArticlesCache = cache<Article>({
  name: 'top-articles',
  ttlMs: 3600_000, // 1 hour TTL
  
  prewarm: {
    intervalMs: 1800_000, // Every 30 minutes
    concurrency: 5,       // Process 5 articles at a time
    
    // Discover the most critical keys to keep hot in RAM
    keys: async () => await analyticsDb.getTrendingSlugs({ limit: 100 })
  },
  
  fetcher: async (slug) => await db.articles.findBySlug(slug)
});

// 1. Forcing a background refresh
await productCache.getOrFetch('hot_item', { forceRefresh: true });

// 2. Hanging DB Protection (Timeouts)
await productCache.getOrFetch('slow_query', {
  timeoutMs: 5000 // If DB takes >5s, abandon fetcher and return stale data
});

// 3. Tier Isolation (L1 Only)
await productCache.set('user:1:card', creditCardData, {
  ignoreL2: true // This highly sensitive data lives ONLY in Node.js process memory.
});