Files

232 lines
5.6 KiB
TypeScript

export type PersistentCacheEntry = { value: unknown; touchedAt: number }
/** Storage for persisted entries; `null` in `write` deletes the key. */
export type PersistentCacheBackend = {
loadAll(): Promise<Array<[string, PersistentCacheEntry]>>
write(writes: Array<[string, PersistentCacheEntry | null]>): Promise<void>
clear(): Promise<void>
}
export type PersistentCacheOptions = {
/** Keys are `<prefix>:<rest>`; prefixes without a limit are never evicted. */
maxEntriesByPrefix: Record<string, number>
writeDelayMs?: number
}
const DEFAULT_WRITE_DELAY_MS = 250
const memory = new Map<string, PersistentCacheEntry>()
const prefixCounts = new Map<string, number>()
const listeners = new Map<string, Set<() => void>>()
const loadListeners = new Set<() => void>()
const pendingWrites = new Map<string, PersistentCacheEntry | null>()
let flushTimer: ReturnType<typeof setTimeout> | null = null
let loadPromise: Promise<void> | null = null
let loaded = false
let backend: PersistentCacheBackend | null = null
let options: PersistentCacheOptions = { maxEntriesByPrefix: {} }
let resolveConfigured: () => void
const configured = new Promise<void>((resolve) => {
resolveConfigured = resolve
})
/**
* Must be called once per app before the cache is used. Loading waits until
* then, so modules can read the cache before the app picks a backend.
*/
export function configurePersistentCache(
nextBackend: PersistentCacheBackend,
nextOptions: PersistentCacheOptions
) {
backend = nextBackend
options = nextOptions
resolveConfigured()
}
function notify(key: string) {
for (const listener of listeners.get(key) ?? []) {
listener()
}
}
function notifyAll() {
for (const key of listeners.keys()) {
notify(key)
}
for (const listener of loadListeners) {
listener()
}
}
async function flushWrites() {
flushTimer = null
if (pendingWrites.size === 0 || !backend) {
return
}
const writes = [...pendingWrites]
pendingWrites.clear()
try {
await backend.write(writes)
} catch {
// Persisting is best-effort; the in-memory copy stays authoritative.
}
}
function scheduleWrite(key: string, entry: PersistentCacheEntry | null) {
pendingWrites.set(key, entry)
if (flushTimer === null) {
flushTimer = setTimeout(
() => void flushWrites(),
options.writeDelayMs ?? DEFAULT_WRITE_DELAY_MS
)
}
}
function entryPrefix(key: string) {
const index = key.indexOf(":")
return index === -1 ? key : key.slice(0, index)
}
function evictOldEntries(prefix: string, force = false) {
const limit = options.maxEntriesByPrefix[prefix]
const count = prefixCounts.get(prefix) ?? 0
if (limit === undefined || count <= (force ? limit : limit * 1.25)) {
return
}
const oldest = [...memory.entries()]
.filter(([key]) => entryPrefix(key) === prefix)
.sort(([, a], [, b]) => a.touchedAt - b.touchedAt)
.slice(0, count - limit)
for (const [key] of oldest) {
removeFromMemory(key)
scheduleWrite(key, null)
}
}
function setInMemory(key: string, entry: PersistentCacheEntry) {
if (!memory.has(key)) {
const prefix = entryPrefix(key)
prefixCounts.set(prefix, (prefixCounts.get(prefix) ?? 0) + 1)
}
memory.set(key, entry)
}
function removeFromMemory(key: string) {
if (memory.delete(key)) {
const prefix = entryPrefix(key)
prefixCounts.set(prefix, (prefixCounts.get(prefix) ?? 1) - 1)
}
}
/** Writes pending entries now instead of after the batching delay. */
export function flushPersistentCache() {
if (flushTimer !== null) {
clearTimeout(flushTimer)
}
void flushWrites()
}
export function loadPersistentCache() {
if (loadPromise) {
return loadPromise
}
loadPromise = (async () => {
await configured
try {
const entries = (await backend?.loadAll()) ?? []
for (const [key, entry] of entries) {
if (!memory.has(key)) {
setInMemory(key, entry)
}
}
for (const prefix of Object.keys(options.maxEntriesByPrefix)) {
evictOldEntries(prefix, true)
}
} catch {
// Treat an unreadable cache as empty.
}
loaded = true
notifyAll()
})()
return loadPromise
}
export function isPersistentCacheLoaded() {
return loaded
}
export function readCache<T>(key: string): T | undefined {
return memory.get(key)?.value as T | undefined
}
export function writeCache(
key: string,
value: unknown,
writeOptions: { notify?: boolean } = {}
) {
const entry = { value, touchedAt: Date.now() }
setInMemory(key, entry)
scheduleWrite(key, entry)
evictOldEntries(entryPrefix(key))
if (writeOptions.notify) {
notify(key)
}
}
export async function clearPersistentCache() {
memory.clear()
prefixCounts.clear()
pendingWrites.clear()
if (flushTimer !== null) {
clearTimeout(flushTimer)
flushTimer = null
}
notifyAll()
try {
await backend?.clear()
} catch {
// Ignore; stale entries are scoped per user and evicted over time.
}
}
/** Deletes every entry whose key starts with `<prefix>:`. */
export function clearCachePrefix(prefix: string) {
for (const key of [...memory.keys()]) {
if (entryPrefix(key) !== prefix) continue
removeFromMemory(key)
scheduleWrite(key, null)
}
}
export function subscribeCache(key: string, listener: () => void) {
let keyListeners = listeners.get(key)
if (!keyListeners) {
keyListeners = new Set()
listeners.set(key, keyListeners)
}
keyListeners.add(listener)
return () => {
keyListeners.delete(listener)
if (keyListeners.size === 0) {
listeners.delete(key)
}
}
}
export function subscribeCacheLoaded(listener: () => void) {
loadListeners.add(listener)
return () => {
loadListeners.delete(listener)
}
}