Refactored to return undefined instead of null on cache miss

This will be more straightforward and enable e.g. setting value to null. It's also algined to how other caching tool apis looks like

Author: oskardudycz

src/packages/pongo/src/core/cache/cacheWrapper.ts

@@ -1,4 +1,5 @@
-import type { CacheHooks, PongoCache } from './types';
+import type { PongoDocument } from '../typing';
+import type { CacheHooks, PongoCache, PongoDocumentCacheKey } from './types';
 
 export const pongoCacheWrapper = (options: {
   provider: PongoCache;
@@ -14,10 +15,12 @@ export const pongoCacheWrapper = (options: {
 
   return {
     cacheType: provider.cacheType,
-    async get(key) {
+    async get<Doc extends PongoDocument = PongoDocument>(
+      key: PongoDocumentCacheKey,
+    ) {
       try {
-        const result = await provider.get(key);
-        if (result != null) {
+        const result = await provider.get<Doc>(key);
+        if (result !== undefined) {
           hooks?.onHit?.(key);
         } else {
           hooks?.onMiss?.(key);
@@ -26,7 +29,7 @@ export const pongoCacheWrapper = (options: {
       } catch (error) {
         onError(error, 'get');
         hooks?.onMiss?.(key);
-        return null;
+        return undefined;
       }
     },
 

src/packages/pongo/src/core/cache/cacheWrapper.unit.spec.ts

@@ -76,7 +76,7 @@ describe('pongoCacheWrapper — error swallowing', () => {
       throw new Error('boom');
     });
     const wrapper = pongoCacheWrapper({ provider });
-    expect(await wrapper.get(`${dbName}:${collectionName}:x`)).toBeNull();
+    expect(await wrapper.get(`${dbName}:${collectionName}:x`)).toBeUndefined();
   });
 
   it('set silently succeeds when provider throws', async () => {
@@ -150,7 +150,7 @@ describe('pongoCacheWrapper — event hooks', () => {
     expect(onHit).toHaveBeenCalledWith(`${dbName}:${collectionName}:x`);
   });
 
-  it('onMiss called when get returns null/undefined', async () => {
+  it('onMiss called when get returns undefined', async () => {
     const provider = identityMapCache();
     const onMiss = vi.fn();
     const wrapper = pongoCacheWrapper({ provider, hooks: { onMiss } });

src/packages/pongo/src/core/cache/pongoCache.ts

@@ -5,7 +5,7 @@ import type { CacheConfig, CacheSettings, PongoCache } from './types';
 const DEFAULT_CONFIG: CacheSettings = { type: 'in-memory' };
 
 export const pongoCache = (
-  options: CacheConfig | 'disabled' | PongoCache | undefined,
+  options?: CacheConfig | 'disabled' | PongoCache | undefined,
 ): PongoCache => {
   if (options === undefined || options === 'disabled') return noopCacheProvider;
 

src/packages/pongo/src/core/cache/pongoCache.unit.spec.ts

@@ -36,11 +36,11 @@ describe('pongoCache factory', () => {
     });
 
     it('defaults to disabled when no config provided', async () => {
-      const cache = pongoCache(undefined);
+      const cache = pongoCache();
 
       await cache.set('db:col:1', { _id: '1', name: 'Bob' });
       const result = await cache.get('db:col:1');
-      expect(result).toBeNull();
+      expect(result).toBeUndefined();
     });
 
     it('in-memory LRU evicts when over max', async () => {
@@ -52,7 +52,7 @@ describe('pongoCache factory', () => {
 
       // Oldest entry should be evicted
       const first = await cache.get('db:col:0');
-      expect(first).toBeNull();
+      expect(first).toBeUndefined();
     });
   });
 
@@ -62,7 +62,7 @@ describe('pongoCache factory', () => {
 
       await cache.set('db:col:1', { _id: '1', name: 'Carol' });
       const result = await cache.get('db:col:1');
-      expect(result).toBeNull();
+      expect(result).toBeUndefined();
     });
   });
 

src/packages/pongo/src/core/cache/providers/identityMapCache.ts

@@ -1,12 +1,15 @@
 import type { PongoDocument } from '../../typing';
-import type { PongoCache } from '../types';
+import type { PongoCache, PongoDocumentCacheKey } from '../types';
 
 export const identityMapCache = (): PongoCache => {
   const store = new Map<string, PongoDocument>();
 
   return {
     cacheType: 'pongo:cache:identity-map',
-    get: (key) => Promise.resolve(store.get(key) ?? null),
+    get: <Doc extends PongoDocument = PongoDocument>(
+      key: PongoDocumentCacheKey,
+    ): Promise<Doc | undefined> =>
+      Promise.resolve(store.get(key) as Doc | undefined),
     set: (key, value) => {
       store.set(key, value);
     },
@@ -21,8 +24,9 @@ export const identityMapCache = (): PongoCache => {
     delete: (key) => {
       store.delete(key);
     },
-    getMany: (keys) =>
-      keys.map((k) => store.get(k)).filter((v) => v !== undefined),
+    getMany: <Doc extends PongoDocument = PongoDocument>(
+      keys: PongoDocumentCacheKey[],
+    ): (Doc | undefined)[] => keys.map((k) => store.get(k) as Doc | undefined),
     setMany: (entries) => {
       for (const { key, value } of entries) store.set(key, value);
     },

src/packages/pongo/src/core/cache/providers/lruCache.ts

@@ -1,6 +1,6 @@
 import { LRUCache } from 'lru-cache';
-import type { PongoDocument } from '../../typing';
-import type { PongoCache } from '../types';
+import type { MaybePromise, PongoDocument } from '../../typing';
+import type { PongoCache, PongoDocumentCacheKey } from '../types';
 
 export type LRUCacheOptions = Omit<
   LRUCache.Options<string, PongoDocument, unknown>,
@@ -20,7 +20,10 @@ export const lruCache = (options?: LRUCacheOptions): PongoCache => {
 
   return {
     cacheType: 'pongo:cache:lru',
-    get: (key) => cache.get(key) ?? null,
+    get: <Doc extends PongoDocument = PongoDocument>(
+      key: PongoDocumentCacheKey,
+    ): MaybePromise<Doc | undefined> =>
+      cache.get(key) as MaybePromise<Doc | undefined>,
     set: (key, value, opts) => {
       cache.set(
         key,
@@ -40,8 +43,9 @@ export const lruCache = (options?: LRUCacheOptions): PongoCache => {
       //   cache.set(key, updated, opts?.ttl !== undefined ? { ttl: opts.ttl } : undefined);
       // }
     },
-    getMany: (keys) =>
-      keys.map((k) => cache.get(k)).filter((v) => v !== undefined),
+    getMany: <Doc extends PongoDocument = PongoDocument>(
+      keys: PongoDocumentCacheKey[],
+    ): (Doc | undefined)[] => keys.map((k) => cache.get(k) as Doc | undefined),
     setMany: (entries) => {
       for (const { key, value, ttl: entryTtl } of entries) {
         cache.set(

src/packages/pongo/src/core/cache/providers/lruCache.unit.spec.ts

@@ -2,9 +2,9 @@ import { describe, expect, it } from 'vitest';
 import { lruCache } from './lruCache';
 
 describe('inMemoryCacheProvider', () => {
-  it('returns null for missing keys', () => {
+  it('returns undefined for missing keys', () => {
     const cache = lruCache();
-    expect(cache.get('db:collection:missing')).toBeNull();
+    expect(cache.get('db:collection:missing')).toBeUndefined();
   });
 
   it('set then get returns the stored document', () => {
@@ -19,28 +19,29 @@ describe('inMemoryCacheProvider', () => {
     cache.set('db:collection:x', { _id: 'x' });
     expect(cache.get('db:collection:x')).toBeDefined();
     await new Promise((r) => setTimeout(r, 100));
-    expect(cache.get('db:collection:x')).toBeNull();
+    expect(cache.get('db:collection:x')).toBeUndefined();
   });
 
   it('delete removes a cached entry', () => {
     const cache = lruCache();
     cache.set('db:collection:a', { _id: 'a' });
     cache.delete('db:collection:a');
-    expect(cache.get('db:collection:a')).toBeNull();
+    expect(cache.get('db:collection:a')).toBeUndefined();
   });
 
-  it('getMany returns documents for found keys and nothing for missing', () => {
+  it('getMany returns documents for found keys and undefined for missing', () => {
     const cache = lruCache();
     cache.set('db:collection:k1', { _id: 'k1' });
     cache.set('db:collection:k2', { _id: 'k2' });
     const results = cache.getMany([
       'db:collection:k1',
       'db:collection:missing',
       'db:collection:k2',
-    ]) as (Record<string, unknown> | null | undefined)[];
-    expect(results).toHaveLength(2); // Only returns found entries
+    ]) as (Record<string, unknown> | undefined)[];
+    expect(results).toHaveLength(3);
     expect(results[0]).toEqual({ _id: 'k1' });
-    expect(results[1]).toEqual({ _id: 'k2' });
+    expect(results[1]).toBeUndefined();
+    expect(results[2]).toEqual({ _id: 'k2' });
   });
 
   it('setMany stores multiple documents retrievable via get', () => {
@@ -61,8 +62,8 @@ describe('inMemoryCacheProvider', () => {
       { key: 'db:collection:c', value: { _id: 'c' } },
     ]);
     cache.deleteMany(['db:collection:a', 'db:collection:b']);
-    expect(cache.get('db:collection:a')).toBeNull();
-    expect(cache.get('db:collection:b')).toBeNull();
+    expect(cache.get('db:collection:a')).toBeUndefined();
+    expect(cache.get('db:collection:b')).toBeUndefined();
     expect(cache.get('db:collection:c')).toEqual({ _id: 'c' });
   });
 
@@ -73,8 +74,8 @@ describe('inMemoryCacheProvider', () => {
       { key: 'db:collection:b', value: { _id: 'b' } },
     ]);
     cache.clear();
-    expect(cache.get('db:collection:a')).toBeNull();
-    expect(cache.get('db:collection:b')).toBeNull();
+    expect(cache.get('db:collection:a')).toBeUndefined();
+    expect(cache.get('db:collection:b')).toBeUndefined();
   });
 
   it('respects max — LRU entry is evicted when full', () => {
@@ -85,7 +86,7 @@ describe('inMemoryCacheProvider', () => {
     cache.set('db:collection:c', { _id: 'c' });
     expect(cache.get('db:collection:a')).toBeDefined();
     expect(cache.get('db:collection:c')).toBeDefined();
-    expect(cache.get('db:collection:b')).toBeNull();
+    expect(cache.get('db:collection:b')).toBeUndefined();
   });
 
   it('returns values synchronously (not wrapped in Promises)', () => {

src/packages/pongo/src/core/cache/providers/noopCache.ts

@@ -2,7 +2,7 @@ import type { PongoCache } from '../types';
 
 export const noopCacheProvider: PongoCache = {
   cacheType: 'pongo:cache:no-op',
-  get: async () => await Promise.resolve(null),
+  get: () => undefined,
   set: () => {},
   update: () => {},
   delete: () => {},