asc
v2.1.5
Published
A middleware layer between a service and a client. The service could be an in-process library, a file, an external web service, anything. Any time the results from a resource call can be cached, you can use ASC as a proxy to that resource.
Downloads
90
Readme
ASC (Asynchronous Self-Updating Cache)
ASC is a tiered caching middleware that sits between your application and cacheable services. It allows you to define multiple caching layers that ASC will automatically manage and update as needed. The name "ASC" stands for Asynchronous Self-Updating Cache.
Features
- Tiered Caching: Define multiple cache layers (memory, Redis, Memcached, DynamoDB, etc.)
- Automatic Cache Population: When a lower layer has data, ASC automatically populates higher layers
- Flexible Configuration: Built-in memory cache is optional and fully configurable
- Request Deduplication: Parallel requests for the same key are handled efficiently
- Type-Safe: Full TypeScript support with generic types for keys and values
Installation
npm install asc
Basic Usage
TypeScript Example
import ASC from 'asc';
// Create a cache instance for string keys and number values
const cache = new ASC<string, number>({
memory: {
ttl: 60000, // 60 seconds
disabled: false
},
get: async (key: string) => {
// Fetch data from your source (database, API, etc.)
const value = await someExpensiveOperation(key);
return value;
}
});
// Using the cache
async function example() {
try {
const value = await cache.get('myKey');
console.log('Retrieved value:', value);
} catch (error) {
console.error('Error fetching data:', error);
}
}
JavaScript Example
const ASC = require('asc');
// Create a cache instance
const cache = new ASC({
memory: {
ttl: 60000, // 60 seconds
disabled: false
},
get: async (key) => {
// Fetch data from your source (database, API, etc.)
const value = await someExpensiveOperation(key);
return value;
}
});
// Using the cache
async function example() {
try {
const value = await cache.get('myKey');
console.log('Retrieved value:', value);
} catch (error) {
console.error('Error fetching data:', error);
}
}
Advanced Usage: Multi-Layer Caching
TypeScript Example with Redis and Database Layers
import ASC from 'asc';
import Redis from 'ioredis';
import { Database } from './your-database';
interface UserData {
id: string;
name: string;
email: string;
}
const redis = new Redis();
const db = new Database();
const userCache = new ASC<string, UserData>({
memory: {
ttl: 30000, // 30 seconds
disabled: false
},
layers: [
// Redis Layer
{
get: async (key) => {
const data = await redis.get(key);
if (data) {
return JSON.parse(data);
}
return undefined;
},
set: async (key, data) => {
await redis.set(key, JSON.stringify(data), 'EX', 300); // 5 minutes
},
clear: async (key) => {
await redis.del(key);
}
},
// Database Layer
{
get: async (key) => {
return await db.users.findOne({ id: key });
}
}
]
});
// Usage
async function getUser(userId: string): Promise<UserData> {
return await userCache.get(userId);
}
JavaScript Example with Redis and Database Layers
const ASC = require('asc');
const Redis = require('ioredis');
const { Database } = require('./your-database');
const redis = new Redis();
const db = new Database();
const userCache = new ASC({
memory: {
ttl: 30000, // 30 seconds
disabled: false
},
layers: [
// Redis Layer
{
get: async (key) => {
const data = await redis.get(key);
if (data) {
return JSON.parse(data);
}
return undefined;
},
set: async (key, data) => {
await redis.set(key, JSON.stringify(data), 'EX', 300); // 5 minutes
},
clear: async (key) => {
await redis.del(key);
}
},
// Database Layer
{
get: async (key) => {
return await db.users.findOne({ id: key });
}
}
]
});
// Usage
async function getUser(userId) {
return await userCache.get(userId);
}
Cache Layer Priorities
Layers are prioritized in the following order:
- In-memory cache (if enabled)
- User-defined layers (in the order they are defined)
- The final get method (ground truth)
When get()
is called, ASC:
- Checks each layer in order until data is found
- Returns the first found data
- Automatically populates all higher layers with the found data
- Uses the
set()
method of each layer (if provided) to store the data
Memory Cache Considerations
The built-in memory cache uses your process's memory. For optimal performance:
- Set appropriate TTLs to prevent memory exhaustion
- Consider your Node.js memory limits (512MB on 32-bit, 1GB on 64-bit systems)
- Disable memory cache if you prefer external caching only
- If you disable in-memory cache and all layers, the ASC library will still de-dup requests to the origin.
When to Use ASC
ASC is ideal when:
- You need tiered data storage with automatic population
- You want to reduce load on expensive operations
- You need geographical data distribution
- You want to simplify cache management in your application
When Not to Use ASC
ASC may not be suitable when:
- You need real-time data without caching
- Your data cannot be serialized (e.g., contains file handles or streams)
- Your keys cannot be serialized with JSON.stringify()
API Reference
Constructor Options
interface MemoryParams {
disabled?: boolean; // Disable in-memory cache
ttl?: number; // Time-to-live in milliseconds
}
interface CacheLayer<K, V> {
get: (key: K) => Promise<V | undefined>;
set?: (key: K, data: V) => Promise<void>;
clear?: (key: K) => Promise<void>;
}
interface ConstructorParams<K, V> {
memory?: MemoryParams;
layers?: Array<CacheLayer<K, V>>;
get?: (key: K) => Promise<V | undefined>;
}
Methods
class ASC<K, V> {
constructor(params: ConstructorParams<K, V>);
get(key: K): Promise<V>;
set(key: K, data: V): Promise<void>;
clear(key: K): Promise<void>;
}
Contributing
- Fork the project on GitHub
- Create a feature branch from develop:
feature/your-feature-name
- Ensure code follows the .eslintrc configuration
- Add tests for your changes
- Verify all tests pass:
npm test
- Submit a pull request to the develop branch
License
MIT License - See LICENSE file for details.