:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { context, propagation, trace } from '@opentelemetry/api'
import {
InMemorySpanExporter,
NodeTracerProvider,
ReadableSpan,
SimpleSpanProcessor,
} from '@opentelemetry/sdk-trace-node'
import { LazyLoader } from './lazy-loader'
import { delay } from './utils'
describe('LazyLoader', () => {
jest.setTimeout(1000)
let loader: jest.Mock
let lazyLoader: LazyLoader<string>
let start: number
beforeEach(() => {
start = Date.now()
jest.spyOn(Date, 'now').mockReturnValue(start)
loader = jest.fn()
lazyLoader = new LazyLoader({
name: 'test',
loader,
})
})
afterEach(() => {
jest.restoreAllMocks()
})
describe('constructor', () => {
it('should throw if refreshBackgroundAgeMs is greater than refreshAgeMs', () => {
expect(
() =>
new LazyLoader({
name: 'test',
loader,
refreshAgeMs: 1000 * 60 * 2,
refreshBackgroundAgeMs: 1000 * 60 * 3,
})
).toThrow('refreshBackgroundAgeMs must be smaller than refreshAgeMs')
})
it('should set defaults if not provided', () => {
const lazyLoader = new LazyLoader({
name: 'test',
loader,
})
expect(lazyLoader['refreshAgeMs']).toBe(300000)
expect(lazyLoader['refreshNullAgeMs']).toBe(300000)
expect(lazyLoader['refreshBackgroundAgeMs']).toBe(undefined)
expect(lazyLoader['refreshJitterMs']).toBe(60000)
})
it('should derive values based on refreshAgeMs', () => {
const refreshAgeMs = 1000 * 60 * 2
const lazyLoader = new LazyLoader({
name: 'test',
loader,
refreshAgeMs,
})
expect(lazyLoader['refreshAgeMs']).toBe(refreshAgeMs)
expect(lazyLoader['refreshNullAgeMs']).toBe(refreshAgeMs)
expect(lazyLoader['refreshBackgroundAgeMs']).toBe(undefined)
expect(lazyLoader['refreshJitterMs']).toBe(refreshAgeMs / 5)
})
})
describe('get', () => {
it('loads and caches a single value', async () => {
loader.mockResolvedValue({ key1: 'value1' })
const result = await lazyLoader.get('key1')
expect(result).toBe('value1')
expect(loader).toHaveBeenCalledTimes(1)
expect(loader).toHaveBeenCalledWith(['key1'])
// Second call should use cache
const result2 = await lazyLoader.get('key1')
expect(result2).toBe('value1')
expect(loader).toHaveBeenCalledTimes(1)
})
it('handles null values', async () => {
loader.mockResolvedValue({ key1: null })
const result = await lazyLoader.get('key1')
expect(result).toBeNull()
const result2 = await lazyLoader.get('key1')
expect(result2).toBeNull()
expect(loader).toHaveBeenCalledTimes(1)
})
it('handles undefined values', async () => {
loader.mockResolvedValue({ key1: undefined })
const result = await lazyLoader.get('key1')
expect(result).toBeNull()
const result2 = await lazyLoader.get('key1')
expect(result2).toBeNull()
expect(loader).toHaveBeenCalledTimes(1)
})
it('can add additional keys to the cache', async () => {
loader.mockResolvedValue({ key1: 'value1', key2: 'value2' })
const result = await lazyLoader.get('key1')
expect(result).toBe('value1')
expect(lazyLoader.getCache()).toEqual({ key1: 'value1', key2: 'value2' })
const result2 = await lazyLoader.get('key2')
expect(result2).toBe('value2')
expect(loader).toHaveBeenCalledTimes(1)
})
it('treats a key naming an Object.prototype member as a normal miss', async () => {
// Ingest tokens become cache keys verbatim, so a token of `__proto__` must miss rather
// than resolve up the prototype chain and let a write land on a shared builtin.
loader.mockResolvedValue({})
const builtinFields = new Set(Object.getOwnPropertyNames(Object.prototype))
try {
expect(await lazyLoader.get('__proto__')).toBeNull()
expect(loader).toHaveBeenCalledWith(['__proto__'])
expect(Object.getOwnPropertyNames(Object.prototype)).not.toContain('lastUsed')
// And it caches like any other null rather than reloading on every lookup.
expect(await lazyLoader.get('__proto__')).toBeNull()
expect(loader).toHaveBeenCalledTimes(1)
} finally {
// On regression the assertions above fail; strip whatever leaked so the rest of the
// file isn't debugging a mutated builtin instead of the real failure.
for (const field of Object.getOwnPropertyNames(Object.prototype)) {
if (!builtinFields.has(field)) {
delete (Object.prototype as Record<string, unknown>)[field]
}
}
}
})
})
describe('getMany with flush', () => {
it('issues the buffered load at once, carrying keys already buffered, and later gets join it', async () => {
const slowBufferLoader = new LazyLoader<string>({ name: 'test', loader, bufferMs: 5000 })
loader.mockImplementation(async (keys: string[]) => {
await delay(20)
return Object.fromEntries(keys.map((key) => [key, { val: key }]))
})
const buffered = slowBufferLoader.get('key1')
const flushed = slowBufferLoader.getMany(['key2'], { flush: true })
const joined = slowBufferLoader.get('key1')
const results = await Promise.all([buffered, flushed, joined])
expect(loader).toHaveBeenCalledTimes(1)
expect(loader).toHaveBeenCalledWith(['key1', 'key2'])
expect(results).toEqual([{ val: 'key1' }, { key2: { val: 'key2' } }, { val: 'key1' }])
})
})
describe('getMany', () => {
it('loads and caches multiple values', async () => {
loader.mockResolvedValue({ key1: 'value1', key2: 'value2' })
const result = await lazyLoader.getMany(['key1', 'key2'])
expect(result).toEqual({ key1: 'value1', key2: 'value2' })
expect(loader).toHaveBeenCalledTimes(1)
expect(loader).toHaveBeenCalledWith(['key1', 'key2'])
// Second call should use cache
const result2 = await lazyLoader.getMany(['key1', 'key2'])
expect(result2).toEqual({ key1: 'value1', key2: 'value2' })
expect(loader).toHaveBeenCalledTimes(1)
})
it('handles partial cache hits', async () => {
loader.mockResolvedValueOnce({ key1: 'value1', key2: 'value2' }).mockResolvedValueOnce({ key3: 'value3' })
const result = await lazyLoader.getMany(['key1', 'key2'])
expect(result).toEqual({ key1: 'value1', key2: 'value2' })
const result2 = await lazyLoader.getMany(['key1', 'key2', 'key3'])
expect(result2).toEqual({ key1: 'value1', key2: 'value2', key3: 'value3' })
expect(loader).toHaveBeenCalledTimes(2)
expect(loader.mock.calls).toMatchInlineSnapshot(`
[
[
[
"key1",
"key2",
],
],
[
[
"key3",
],
],
]
`)
})
})
describe('spans', () => {
let exporter: InMemorySpanExporter
let provider: NodeTracerProvider
beforeEach(() => {
exporter = new InMemorySpanExporter()
provider = new NodeTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] })
provider.register()
})
afterEach(async () => {
await provider.shutdown()
trace.disable()
context.disable()
propagation.disable()
})
const loadSpans = (): ReadableSpan[] =>
exporter.getFinishedSpans().filter((span) => span.name === 'lazyLoader.loadViaCache')
it('spans loads and in-flight waits, and skips the span on a full cache hit', async () => {
loader.mockResolvedValue({ key1: 'value1' })
const first = lazyLoader.get('key1')
const second = lazyLoader.get('key1')
await Promise.all([first, second])
expect(loadSpans().map((span) => span.attributes['lazyloader.outcome'])).toEqual([
'loaded',
'waited_pending',
])
expect(loadSpans()[1].attributes).toMatchObject({
'lazyloader.name': 'test',
'lazyloader.keys': 1,
'lazyloader.misses': 1,
'lazyloader.outcome': 'waited_pending',
})
await lazyLoader.get('key1')
expect(loadSpans()).toHaveLength(2)
})
})
describe('refresh behavior', () => {
it('refreshes values after refreshAge', async () => {
loader.mockResolvedValueOnce({ key1: 'value1' }).mockResolvedValueOnce({ key1: 'value2' })
await lazyLoader.get('key1')
expect(loader).toHaveBeenCalledTimes(1)
// Fast forward past refresh age
jest.spyOn(Date, 'now').mockReturnValue(start + 1000 * 60 * 6)
await lazyLoader.get('key1')
expect(loader).toHaveBeenCalledTimes(2)
})
it('respects custom refreshAge', async () => {
const customLoader = new LazyLoader({
name: 'test',
loader,
refreshAgeMs: 1000 * 60 * 2, // 2 minutes
})
loader.mockResolvedValueOnce({ key1: 'value1' }).mockResolvedValueOnce({ key1: 'value2' })
await customLoader.get('key1')
expect(loader).toHaveBeenCalledTimes(1)
// Fast forward past custom refresh age
jest.spyOn(Date, 'now').mockReturnValue(start + 1000 * 60 * 3) // 3 minutes
await customLoader.get('key1')
expect(loader).toHaveBeenCalledTimes(2)
})
})
describe('error handling', () => {
it('throws errors by default', async () => {
loader.mockRejectedValue(new Error('Test error'))
await expect(lazyLoader.get('key1')).rejects.toThrow('Test error')
})
})
describe('markForRefresh', () => {
it('forces refresh of specified keys', async () => {
loader.mockResolvedValueOnce({ key1: 'value1' }).mockResolvedValueOnce({ key1: 'value2' })
await lazyLoader.get('key1')
expect(loader).toHaveBeenCalledTimes(1)
lazyLoader.markForRefresh('key1')
await lazyLoader.get('key1')
expect(loader).toHaveBeenCalledTimes(2)
})
it('handles multiple keys', async () => {
loader
.mockResolvedValueOnce({ key1: 'value1', key2: 'value2' })
.mockResolvedValueOnce({ key1: 'value3', key2: 'value4' })
await lazyLoader.getMany(['key1', 'key2'])
expect(loader).toHaveBeenCalledTimes(1)
lazyLoader.markForRefresh(['key1', 'key2'])
await lazyLoader.getMany(['key1', 'key2'])
expect(loader).toHaveBeenCalledTimes(2)
})
})
describe('parallel loading', () => {
it('should bundle loads for the same key', async () => {
loader.mockResolvedValue({ key1: { foo: 'bar' } })
const results = await Promise.all([lazyLoader.get('key1'), lazyLoader.get('key1'), lazyLoader.get('key2')])
expect(results).toEqual([{ foo: 'bar' }, { foo: 'bar' }, null])
expect(results[0]).toBe(results[1])
expect(loader).toHaveBeenCalledTimes(1)
expect(loader).toHaveBeenCalledWith(['key1', 'key2'])
})
it('should load multiple values in parallel', async () => {
loader.mockImplementation(async (keys) => {
await new Promise((resolve) => setTimeout(resolve, 100))
return keys.reduce(
(acc: any, key: string) => {
acc[key] = { val: key }
return acc
},
{} as Record<string, any>
)
})
const result1 = lazyLoader.get('key1')
// Should join first request
const result2 = lazyLoader.get('key2')
await delay(50)
// Should load key2 and join second request
const result3 = lazyLoader.get('key3')
const result4 = lazyLoader.getMany(['key1', 'key2', 'key3'])
const results = await Promise.all([result1, result2, result3, result4])
expect(results).toMatchInlineSnapshot(`
[
{
"val": "key1",
},
{
"val": "key2",
},
{
"val": "key3",
},
{
"key1": {
"val": "key1",
},
"key2": {
"val": "key2",
},
"key3": {
"val": "key3",
},
},
]
`)
expect(loader).toHaveBeenCalledTimes(2)
expect(loader).toHaveBeenNthCalledWith(1, ['key1', 'key2'])
expect(loader).toHaveBeenNthCalledWith(2, ['key3'])
})
})
describe('background refreshing', () => {
let loadSpy: jest.SpyInstance
beforeEach(() => {
lazyLoader = new LazyLoader({
name: 'test',
loader,
refreshAgeMs: 1000 * 60 * 2, // 2 minutes
refreshBackgroundAgeMs: 1000 * 60 * 1, // 1 minute
refreshJitterMs: 0, // Simplify the tests
})
loadSpy = jest.spyOn(lazyLoader as any, 'load')
})
it('should refresh in the background if between ages', async () => {
let count = 0
loader.mockImplementation(() => {
count++
return { key1: 'value' + count }
})
const result = await lazyLoader.get('key1')
expect(loadSpy).toHaveBeenCalledTimes(1)
expect(loader).toHaveBeenCalledTimes(1)
expect(result).toBe('value1')
loadSpy.mockClear()
loader.mockClear()
// Fast forward past refresh background age
jest.spyOn(Date, 'now').mockReturnValue(start + 1000 * 60 * 1.5)
const result2 = await lazyLoader.get('key1')
expect(result2).toBe('value1') // Value should immediately be returned
expect(loadSpy).toHaveBeenCalledTimes(1) // Load was called
expect(loader).toHaveBeenCalledTimes(0) // But it didnt block
loadSpy.mockClear()
loader.mockClear()
// Check in flight cache
const result3 = await lazyLoader.get('key1')
expect(result3).toBe('value1')
expect(loadSpy).toHaveBeenCalledTimes(1)
expect(loader).toHaveBeenCalledTimes(0)
loadSpy.mockClear()
loader.mockClear()
// Let the background refresh complete
await delay(100)
const result4 = await lazyLoader.get('key1')
expect(result4).toBe('value2')
expect(loadSpy).toHaveBeenCalledTimes(0)
expect(loader).toHaveBeenCalledTimes(1)
})
it('does not background-refresh a key whose value has become null', async () => {
loader.mockResolvedValueOnce({ key1: 'value1' })
expect(await lazyLoader.get('key1')).toBe('value1')
// Past refreshAgeMs, so this get reloads. The loader omits key1, caching it as null.
jest.spyOn(Date, 'now').mockReturnValue(start + 1000 * 60 * 2.5)
loader.mockResolvedValue({})
expect(await lazyLoader.get('key1')).toBeNull()
loader.mockClear()
loadSpy.mockClear()
// Still inside refreshNullAgeMs, so the null is served from cache. The background
// deadline from when key1 held a real value is long past, so one left behind on the
// entry would reload the key on every lookup until the null expires.
jest.spyOn(Date, 'now').mockReturnValue(start + 1000 * 60 * 3)
expect(await lazyLoader.get('key1')).toBeNull()
// loadSpy, not loader: a background refresh calls load() synchronously during the get,
// so this observes a scheduled reload without waiting out the buffer for it to surface.
expect(loadSpy).toHaveBeenCalledTimes(0)
expect(loader).toHaveBeenCalledTimes(0)
// Past where the background deadline would sit if the null were stamped with
// refreshBackgroundAgeMs (start+3.5min), still inside the null TTL that runs to
// start+4.5min.
jest.spyOn(Date, 'now').mockReturnValue(start + 1000 * 60 * 4)
expect(await lazyLoader.get('key1')).toBeNull()
expect(loadSpy).toHaveBeenCalledTimes(0)
expect(loader).toHaveBeenCalledTimes(0)
})
it('re-caches a key that reloads from null to null', async () => {
loader.mockResolvedValueOnce({ key1: 'value1' })
expect(await lazyLoader.get('key1')).toBe('value1')
// Past refreshAgeMs, so this get reloads. The loader omits key1, caching it as null.
jest.spyOn(Date, 'now').mockReturnValue(start + 1000 * 60 * 2.5)
loader.mockResolvedValue({})
expect(await lazyLoader.get('key1')).toBeNull()
// Past the null TTL, so this get reloads and the loader omits key1 again. The reload
// has to stamp a fresh null TTL, otherwise the entry stays expired forever.
jest.spyOn(Date, 'now').mockReturnValue(start + 1000 * 60 * 5)
expect(await lazyLoader.get('key1')).toBeNull()
loader.mockClear()
// Inside the new null TTL, so this is a cache hit rather than another blocking load.
jest.spyOn(Date, 'now').mockReturnValue(start + 1000 * 60 * 5.5)
expect(await lazyLoader.get('key1')).toBeNull()
expect(loader).toHaveBeenCalledTimes(0)
})
})
describe('LRU eviction with maxSize', () => {
it('should evict least recently used entries when maxSize is exceeded', async () => {
const customLoader = new LazyLoader({
name: 'test',
loader,
maxSize: 3,
refreshJitterMs: 0,
})
// Add 3 entries
loader.mockResolvedValueOnce({ key1: 'value1', key2: 'value2', key3: 'value3' })
await customLoader.getMany(['key1', 'key2', 'key3'])
expect(Object.keys(customLoader.getCache()).length).toBe(3)
// Access key1 and key2 to update their lastUsed times
jest.spyOn(Date, 'now').mockReturnValue(start + 1000)
await customLoader.get('key1')
jest.spyOn(Date, 'now').mockReturnValue(start + 2000)
await customLoader.get('key2')
// Add a 4th entry - should evict key3 (least recently used)
jest.spyOn(Date, 'now').mockReturnValue(start + 3000)
loader.mockResolvedValueOnce({ key4: 'value4' })
await customLoader.get('key4')
const cache = customLoader.getCache()
expect(Object.keys(cache).length).toBe(3)
expect(cache).toEqual({ key1: 'value1', key2: 'value2', key4: 'value4' })
})
it('does not evict when refreshing a key already in the cache', async () => {
const customLoader = new LazyLoader({
name: 'test',
loader,
maxSize: 3,
refreshJitterMs: 0,
})
loader.mockResolvedValueOnce({ key1: 'value1', key2: 'value2', key3: 'value3' })
await customLoader.getMany(['key1', 'key2', 'key3'])
// Reloading an expired key replaces its entry rather than adding one, so the cache is
// still at maxSize and nothing live gets evicted.
jest.spyOn(Date, 'now').mockReturnValue(start + 1000 * 60 * 6)
loader.mockResolvedValueOnce({ key1: 'value1-refreshed' })
await customLoader.get('key1')
expect(customLoader.getCache()).toEqual({
key1: 'value1-refreshed',
key2: 'value2',
key3: 'value3',
})
})
it('should handle bulk additions that exceed maxSize', async () => {
const customLoader = new LazyLoader({
name: 'test',
loader,
maxSize: 2,
refreshJitterMs: 0,
})
// Add 5 entries at once - should keep only 2
loader.mockResolvedValueOnce({
key1: 'value1',
key2: 'value2',
key3: 'value3',
key4: 'value4',
key5: 'value5',
})
await customLoader.getMany(['key1', 'key2', 'key3', 'key4', 'key5'])
const cache = customLoader.getCache()
expect(Object.keys(cache).length).toBe(2)
// When all have the same lastUsed time, eviction order depends on iteration order
// Just verify we have exactly 2 entries
})
it('evicts down to maxSize when the loader omits every requested key', async () => {
const customLoader = new LazyLoader({
name: 'test',
loader,
maxSize: 2,
refreshJitterMs: 0,
})
// Nulls for omitted keys are cached like any other value, so they count against maxSize.
loader.mockResolvedValueOnce({})
await customLoader.getMany(['key1', 'key2', 'key3'])
expect(Object.keys(customLoader.getCache()).length).toBe(2)
})
})
describe('loaderRetry', () => {
const retriable = (message: string) => Object.assign(new Error(message), { isRetriable: true })
const makeRetryLoader = () => {
const retryLoader = jest.fn()
return {
retryLoader,
retryLazyLoader: new LazyLoader<string>({
name: 'test-retry',
loader: retryLoader,
loaderRetry: { retryIntervalMs: 1, retryJitterMs: 0, maxElapsedMs: 1000 },
}),
}
}
it('retries a retriable loader failure and then succeeds', async () => {
const { retryLoader, retryLazyLoader } = makeRetryLoader()
retryLoader.mockRejectedValueOnce(retriable('blip'))
retryLoader.mockResolvedValueOnce({ key1: 'value1' })
const result = await retryLazyLoader.get('key1')
expect(result).toBe('value1')
expect(retryLoader).toHaveBeenCalledTimes(2)
// Re-invoked with the keys on every attempt (re-evaluated fresh at retry time)
expect(retryLoader).toHaveBeenNthCalledWith(1, ['key1'])
expect(retryLoader).toHaveBeenNthCalledWith(2, ['key1'])
})
it('does not retry a non-retriable loader failure', async () => {
const { retryLoader, retryLazyLoader } = makeRetryLoader()
retryLoader.mockRejectedValue(new Error('boom'))
await expect(retryLazyLoader.get('key1')).rejects.toThrow('boom')
expect(retryLoader).toHaveBeenCalledTimes(1)
})
it('gives up and rethrows once maxElapsedMs is exceeded', async () => {
let elapsed = 0
jest.spyOn(performance, 'now').mockImplementation(() => elapsed)
const { retryLoader, retryLazyLoader } = makeRetryLoader()
// Each attempt advances the clock by 600ms; the 1000ms budget allows only one retry.
retryLoader.mockImplementation(() => {
elapsed += 600
return Promise.reject(retriable('blip'))
})
await expect(retryLazyLoader.get('key1')).rejects.toThrow('blip')
expect(retryLoader).toHaveBeenCalledTimes(2)
})
it('does not retry when no loaderRetry is configured', async () => {
const noRetryLoader = jest.fn().mockRejectedValue(retriable('blip'))
const noRetryLazyLoader = new LazyLoader<string>({ name: 'test-no-retry', loader: noRetryLoader })
await expect(noRetryLazyLoader.get('key1')).rejects.toThrow('blip')
expect(noRetryLoader).toHaveBeenCalledTimes(1)
})
it('serves a get() for a different key while the loader is retrying, without hanging', async () => {
const { retryLoader, retryLazyLoader } = makeRetryLoader()
let allowAToSucceed = false
retryLoader.mockImplementation((keys: string[]) => {
if (keys.includes('A')) {
return allowAToSucceed ? Promise.resolve({ A: 'valueA' }) : Promise.reject(retriable('blip'))
}
return Promise.resolve({ B: 'valueB' })
})
// Start A; it fails and enters the retry loop (its buffer has already fired and cleared).
const aPromise = retryLazyLoader.get('A')
for (let i = 0; i < 100 && !retryLoader.mock.calls.some((c) => c[0].includes('A')); i++) {
await delay(2)
}
// A get() for a different key must resolve on its own buffer, not block on A's retry.
await expect(retryLazyLoader.get('B')).resolves.toBe('valueB')
// A still completes once its dependency recovers.
allowAToSucceed = true
await expect(aPromise).resolves.toBe('valueA')
// B was loaded by its own independent loader call, not merged into A's retry.
expect(retryLoader).toHaveBeenCalledWith(['B'])
})
})
})