Efficiently manage interconnected caches with automatic dependency tracking and updates.
- Declare dependencies between caches
- Automatic invalidation and updates
- Sync and async cache creation functions
- Key-based namespace resolution
- Cache capacity and LRU (Least Recently Used) management
import { CacheEntanglementSync } from 'cache-entanglement'
const name = new CacheEntanglementSync((key, state, value: string) => value)
const age = new CacheEntanglementSync((key, state, value: number) => value)
const user = new CacheEntanglementSync((key, state) => {
const { name, age } = state
return { name: name.raw, age: age.raw }
}, {
dependencies: { name, age },
})
name.cache('john', 'John')
age.cache('john', 20)
user.cache('john/user')
user.get('john/user').raw // { name: 'John', age: 20 }
age.update('john', 21)
user.get('john/user').raw // { name: 'John', age: 21 }npm i cache-entanglement// CommonJS
const { CacheEntanglementSync, CacheEntanglementAsync } = require('cache-entanglement')
// ESM
import { CacheEntanglementSync, CacheEntanglementAsync } from 'cache-entanglement'import { CacheEntanglementSync, CacheEntanglementAsync } from 'https://cdn.jsdelivr.net/npm/cache-entanglement@1.x.x/+esm'Keys must reflect their dependency path. For example:
const company = new CacheEntanglementSync((key, state, name: string) => name)
const employee = new CacheEntanglementSync((key, { company }, name: string) => {
return { name, companyName: company.raw }
}, {
dependencies: { company },
})
company.cache('github', 'GitHub')
employee.cache('github/john', 'John')By naming the employee key as github/john, it indicates dependency on the github key from the company cache. Updates to company:github automatically propagate.
You can continue chaining dependencies:
const card = new CacheEntanglementSync((key, { employee }, tel: string) => ({
...employee.clone(),
tel,
}), {
dependencies: { employee },
})
card.cache('github/john/card', 'xxx-xxxx-xxxx')class FileManager {
constructor() {
this.content = new CacheEntanglementAsync(async (key, state, path: string) => {
return await fs.readFile(path)
})
}
async getContent(path: string) {
return await this.content.cache(`key:${path}`, path)
}
}const articleComments = new CacheEntanglementSync((key, state, comments: string[]) => comments)
const articleContent = new CacheEntanglementSync((key, state, content: string) => content)
const article = new CacheEntanglementSync((key, state) => {
return {
articleComments: state.articleComments.raw,
articleContent: state.articleContent.raw,
}
}, {
dependencies: { articleComments, articleContent },
})
function postArticle(content: string) {
const id = uuid()
articleComments.cache(id, [])
articleContent.cache(id, content)
article.cache(id)
}
function addComment(id: string, comment: string) {
if (!articleComments.exists(id)) throw new Error(`Missing article: ${id}`)
const comments = articleComments.get(id).clone('array-shallow-copy')
comments.push(comment)
articleComments.update(id, comments)
}Instances manage cache values using a Least Recently Used (LRU) strategy. If the number of cached items exceeds the capacity, the oldest accessed entries are automatically removed.
const cache = new CacheEntanglementSync((key, state, value: string) => value, {
capacity: 500 // Limit to 500 entries (Default: 100)
})
cache.cache('my-key', 'hello')This approach ensures stable memory usage and prevents the "infinite growth" problem, providing a better runtime experience than time-based expiration.
The lifespan option has been removed to improve reliability and prevent unexpected process hangs caused by setTimeout.
const cache = new CacheEntanglementSync(getter, { lifespan: '5m' })Use the capacity option to limit memory usage based on the number of entries.
const cache = new CacheEntanglementSync(getter, { capacity: 100 })Important
Since entries no longer "expire" based on time, they will remain in memory until the capacity is reached or they are manually deleted.
A hook you can use to pre-assign dependencies from within the parent:
const user = new CacheEntanglementSync((key, state, _name, _age) => {
return {
name: state.name.clone(),
age: state.age.clone(),
}
}, {
dependencies: { name, age },
beforeUpdateHook: (key, dependencyKey, _name, _age) => {
name.cache(key, _name)
age.cache(key, _age)
}
})
user.cache('john', 'John', 20).update() within beforeUpdateHook to prevent recursion.
The package also exports utility classes that are used internally but can be useful for general purposes.
A Map-like data structure that implements the Least Recently Used (LRU) eviction policy. Once the capacity is reached, the least recently accessed item is removed.
import { LRUMap } from 'cache-entanglement'
const cache = new LRUMap<string, string>(100) // capacity: 100
cache.set('key', 'value')
console.log(cache.get('key')) // 'value'A Map that holds weak references to its values rather than its keys. This is useful when you want to cache objects but allow them to be garbage collected if there are no other references to them.
import { InvertedWeakMap } from 'cache-entanglement'
const map = new InvertedWeakMap<string, object>()
let obj: object | null = { data: 'hello' }
map.set('obj1', obj)
console.log(map.get('obj1')) // { data: 'hello' }
obj = null // Now the object can be garbage collected
// After GC, map.get('obj1') will return undefinedimport { CacheEntanglementSync } from 'cache-entanglement'
class MyClass {
private readonly _myCache = new CacheEntanglementSync((key, state) => {
// your logic
})
}MIT