@thalorlabs/cache

A TypeScript caching package for ThalorLabs projects, providing a reusable caching layer for storing, retrieving, and managing cached API responses and computed data across services.

Installation

npm install @thalorlabs/cache

Purpose

This package provides a centralized caching solution for ThalorLabs services, handling:

• Storage & Retrieval: Store and retrieve cached data with expiration support
• Expiration Management: Automatic cleanup of expired cache entries
• Cache Statistics: Monitor cache effectiveness and performance
• Request Key Management: Generate consistent cache keys for API responses
• Database Integration: Works with shared database connections via @thalorlabs/db

Usage

Import Cache Components

import {
  CacheEntry,
  CacheEntryWithId,
  CacheEntryPartial,
  CacheStats,
  CacheService,
  CacheKeyGenerator,
} from '@thalorlabs/cache';

Import Individual Types

import { CacheEntry } from '@thalorlabs/cache/types/CacheEntry';
import { CacheService } from '@thalorlabs/cache/services/CacheService';

Available Types

Cache Entry Types

| Type | Description | Usage | | ------------------ | --------------------------------------------- | ------------------------------------ | | CacheEntry | Core cache entry data without MongoDB metadata | CacheEntry.parse(cacheData) | | CacheEntryWithId | Complete cache entry with MongoDB metadata | CacheEntryWithId.parse(fullCacheData) | | CacheEntryPartial| Partial cache entry for update operations | CacheEntryPartial.parse(updateData) |

Cache Management Types

| Type | Description | Usage | | ------------------ | ----------------------------------- | ----------------------------- | | CacheStats | Cache performance statistics | CacheStats.parse(statsData) | | CacheKeyGenerator| Utility for generating cache keys | new CacheKeyGenerator() |

Mongoose Schemas

| Schema | Description | Usage | | ----------------- | ----------------------------------- | ----------------------------- | | CacheEntrySchema| Mongoose schema for MongoDB storage | new Schema(CacheEntrySchema) |

Examples

Basic Cache Entry Creation

import { CacheEntry } from '@thalorlabs/cache';

const cacheData = {
  key: 'api-users-list',
  value: '{"users": [{"id": 1, "name": "John"}]}',
  expiresAt: new Date(Date.now() + 3600000), // 1 hour from now
  service: 'user-service',
  requestHash: 'abc123def456',
  metadata: {
    endpoint: '/api/users',
    method: 'GET',
    statusCode: 200,
  },
  createdAt: new Date(),
};

const cacheEntry = CacheEntry.parse(cacheData);

Cache Service Usage

import { CacheService, CacheKeyGenerator } from '@thalorlabs/cache';

// Initialize cache service
const cacheService = new CacheService(mongoConnection, CacheEntryModel);
const keyGenerator = new CacheKeyGenerator();

// Generate cache key for API request
const cacheKey = keyGenerator.generateKey({
  service: 'user-service',
  endpoint: '/api/users',
  method: 'GET',
  queryParams: { page: 1, limit: 10 },
});

// Store cache entry
await cacheService.setCache(cacheKey, {
  value: JSON.stringify(usersData),
  expiresAt: new Date(Date.now() + 1800000), // 30 minutes
  service: 'user-service',
  requestHash: 'abc123def456',
});

// Retrieve cache entry
const cachedData = await cacheService.getCache(cacheKey);
if (cachedData && !cacheService.isExpired(cachedData)) {
  return JSON.parse(cachedData.value);
}

Cache Statistics

import { CacheStats } from '@thalorlabs/cache';

const stats = await cacheService.getCacheStats();

const cacheStats = CacheStats.parse({
  totalEntries: stats.totalEntries,
  hitCount: stats.hitCount,
  missCount: stats.missCount,
  hitRate: stats.hitRate,
  expiredEntries: stats.expiredEntries,
  lastCleanup: stats.lastCleanup,
  service: 'user-service',
  timestamp: new Date(),
});

MongoDB Integration

import { CacheEntryWithId, CacheEntrySchema } from '@thalorlabs/cache';
import { ObjectId } from 'bson';
import mongoose from 'mongoose';

// Using the Mongoose schema
const CacheEntryModel = mongoose.model('CacheEntry', CacheEntrySchema);

// Creating a complete cache entry with MongoDB metadata
const fullCacheEntry = {
  _id: new ObjectId(),
  key: 'api-users-list',
  value: '{"users": []}',
  expiresAt: new Date(Date.now() + 3600000),
  service: 'user-service',
  requestHash: 'abc123def456',
  createdAt: new Date(),
  updatedAt: new Date(),
};

const validatedCacheEntry = CacheEntryWithId.parse(fullCacheEntry);

// Save to MongoDB
const savedEntry = await CacheEntryModel.create(validatedCacheEntry);

Cache Cleanup

import { CacheService } from '@thalorlabs/cache';

const cacheService = new CacheService(mongoConnection, CacheEntryModel);

// Clean up expired entries
const cleanupResult = await cacheService.cleanupExpiredEntries();
console.log(`Cleaned up ${cleanupResult.deletedCount} expired entries`);

// Clear all cache entries for a service
await cacheService.clearServiceCache('user-service');

// Clear specific cache entry
await cacheService.clearCache('api-users-list');

Cache Entry Fields

Core Cache Data

• key - Unique cache key identifier
• value - Cached data (typically JSON string)
• expiresAt - Expiration timestamp
• service - Service name that created the cache entry
• requestHash - Hash of the original request parameters

Metadata

• metadata - Additional context about the cached data
  • endpoint - API endpoint that was cached
  • method - HTTP method (GET, POST, etc.)
  • statusCode - HTTP response status code
  • responseTime - Original response time in milliseconds
  • requestSize - Size of original request
  • responseSize - Size of cached response

Performance Tracking

• hitCount - Number of times this cache entry was accessed
• lastAccessed - Timestamp of last access
• createdAt - Cache entry creation timestamp
• updatedAt - Last update timestamp

Project Structure

src/
├── index.ts                    # Main exports
├── types/                      # Type definitions
│   ├── CacheEntry.ts          # Cache entry types and schemas
│   └── CacheStats.ts          # Cache statistics types
├── services/                   # Cache services
│   ├── CacheService.ts        # Main cache service
│   └── CacheKeyGenerator.ts   # Cache key generation utility
└── cacheEntries/              # Mongoose schemas
    ├── index.ts               # Schema exports
    └── cacheEntrySchema.ts    # Mongoose CacheEntry schema

TypeScript Support

This package includes full TypeScript support with:

• Complete type definitions
• Zod schema validation
• IntelliSense support
• Compile-time type checking
• Mongoose integration

Caching Best Practices

Cache Key Generation

Use consistent key generation patterns across services:

const keyGenerator = new CacheKeyGenerator();

// For API responses
const apiKey = keyGenerator.generateKey({
  service: 'user-service',
  endpoint: '/api/users',
  method: 'GET',
  queryParams: { page: 1, limit: 10 },
});

// For computed data
const computedKey = keyGenerator.generateKey({
  service: 'analytics-service',
  operation: 'user-stats',
  parameters: { userId: '123', period: 'monthly' },
});

Expiration Strategy

• Short-lived data: 5-15 minutes (real-time data, user sessions)
• Medium-lived data: 30-60 minutes (API responses, computed metrics)
• Long-lived data: 1-24 hours (reference data, configuration)

Cache Invalidation

// Invalidate related cache entries when data changes
await cacheService.invalidatePattern('user-service:user-*');
await cacheService.invalidatePattern('analytics-service:stats-*');

Monitoring Cache Performance

// Regular cache health checks
const stats = await cacheService.getCacheStats();
if (stats.hitRate < 0.7) {
  console.warn('Low cache hit rate:', stats.hitRate);
}

// Monitor expired entries
if (stats.expiredEntries > stats.totalEntries * 0.1) {
  await cacheService.cleanupExpiredEntries();
}

Development

Building

npm run build

Type Checking

npx tsc --noEmit

License

ISC