add namespace option for cache isolation

Author: sushichan044

src/cache.ts

@@ -1,3 +1,4 @@
+import { hash } from 'ohash'
 import { version } from '../package.json'
 
 type Awaitable<T> = T | Promise<T>
@@ -22,23 +23,67 @@ export function memoryStorage() {
 
 const ONE_WEEK = 1000 * 60 * 60 * 24 * 7
 
-export function createCachedAsyncStorage(storage: Storage) {
+interface CachedStorageOptions {
+  /**
+   * Array of values used to create an isolated cache key namespace.
+   * Each element is stringified or hashed to form a unique cache key prefix.
+   *
+   * @example
+   * ```ts
+   * const providerName = 'google-fonts'
+   * const providerOptions = { apiKey: 'xxx', subset: 'latin' }
+   * createCachedAsyncStorage(storage, {
+   *   namespace: [providerName, providerOptions]
+   * })
+   * // Results in cache keys like: 'google-fonts:hash_of_options:actual_key'
+   * ```
+   */
+  namespace?: any[]
+}
+
+export function createCachedAsyncStorage(storage: Storage, options: CachedStorageOptions = {}) {
+  function resolveKey(key: string): string {
+    if (!options?.namespace || options.namespace.length === 0) {
+      return key
+    }
+
+    return `${createCacheKey(...options.namespace)}:${key}`
+  }
+
   return {
     async getItem<T = unknown>(key: string, init?: () => T | Promise<T>) {
+      const resolvedKey = resolveKey(key)
       const now = Date.now()
-      const res = await storage.getItem(key)
+      const res = await storage.getItem(resolvedKey)
       if (res && res.expires > now && res.version === version) {
         return res.data
       }
       if (!init) {
         return null
       }
       const data = await init()
-      await storage.setItem(key, { expires: now + ONE_WEEK, version, data })
+      await storage.setItem(resolvedKey, { expires: now + ONE_WEEK, version, data })
       return data
     },
     async setItem(key: string, data: unknown) {
-      await storage.setItem(key, { expires: Date.now() + ONE_WEEK, version, data })
+      await storage.setItem(resolveKey(key), { expires: Date.now() + ONE_WEEK, version, data })
     },
   }
 }
+
+function createCacheKey(...fragments: any[]): string {
+  const parts = fragments.map((f) => {
+    // Don't hash string values to maintain readability.
+    const part = typeof f === 'string' ? f : hash(f)
+    return sanitize(part)
+  })
+
+  return parts.join(':')
+}
+
+function sanitize(input: string): string {
+  if (!input)
+    return ''
+
+  return input.replace(/[^\w.-]/g, '_')
+}

test/cache.test.ts

@@ -50,4 +50,68 @@ describe('cache storage', () => {
     expect(customStorage.setItem).toHaveBeenCalledWith('key', expect.objectContaining({ data: 'value' }))
     expect(customStorage.setItem).toHaveBeenCalledWith('another-key', expect.objectContaining({ data: 'value' }))
   })
+
+  describe('keyFragments option', () => {
+    it('preserves string fragments in cache key', async () => {
+      const storage = {
+        getItem: vi.fn(),
+        setItem: vi.fn(),
+      }
+      const cached = createCachedAsyncStorage(storage, {
+        namespace: ['provider-name', { a: 1 }, 'variant-a'],
+      })
+      await cached.setItem('test-key', 'data')
+
+      expect(storage.setItem).toHaveBeenCalledExactlyOnceWith(
+        expect.stringMatching(/^provider-name:.+:variant-a:.+$/),
+        expect.objectContaining({ data: 'data' }),
+      )
+    })
+
+    it('generates different keys for different object fragments', async () => {
+      const storage = {
+        getItem: vi.fn(),
+        setItem: vi.fn(),
+      }
+
+      const cachedA = createCachedAsyncStorage(storage, {
+        namespace: [{ variant: 'A' }],
+      })
+      const cachedB = createCachedAsyncStorage(storage, {
+        namespace: [{ variant: 'B' }],
+      })
+      await cachedA.setItem('key', 'data')
+      await cachedB.setItem('key', 'data')
+
+      const keyA = storage.setItem.mock.calls.at(0)?.at(0) as string | undefined
+      const keyB = storage.setItem.mock.calls.at(1)?.at(0) as string | undefined
+
+      expect(storage.setItem).toHaveBeenCalledTimes(2)
+      expect(keyA).toBeDefined()
+      expect(keyB).toBeDefined()
+      expect(keyA).not.toBe(keyB)
+    })
+
+    it.each([
+      { input: 'provider/name' },
+      { input: 'provider@v2' },
+      { input: 'provider name' },
+      { input: 'provider:name' },
+    ])('sanitizes "$input" in fragments', async ({ input }) => {
+      const storage = {
+        getItem: vi.fn(),
+        setItem: vi.fn(),
+      }
+      const cached = createCachedAsyncStorage(storage, {
+        namespace: [input],
+      })
+
+      await cached.setItem('test-key', 'data')
+
+      expect(storage.setItem).toHaveBeenCalledExactlyOnceWith(
+        expect.not.stringContaining(input),
+        expect.objectContaining({ data: 'data' }),
+      )
+    })
+  })
 })