feat: add limit option to useResponseCaching for entry eviction (#737)

Author: ascott18

CHANGELOG.md

@@ -12,6 +12,7 @@
 - API callers (`ItemApiState`, `ListApiState`) are now awaitable. `await caller` now resolves to `caller.result` after the current operation is complete, or resolves immediately to the previous result if no operation is in progress.
 - `useAppUpdateCheck` now also listens for Vite's `vite:preloadError` event, showing the update notification when dynamic imports fail due to stale chunks after a deployment.
 - `useAppUpdateCheck` now persists the observed build in `sessionStorage` (keyed by a fingerprint of loaded script URLs), enabling detection of server updates after a browser discards and restores a tab from cached HTML.
+- Added `limit` option to `useResponseCaching` to cap the number (`maxEntries`) or total size (`maxBytes`) of cached responses per endpoint group. Oldest entries are evicted first when limits are exceeded.
 - Added `returnViewModel` prop to `c-select`, enabling ViewModel instances to be returned directly when bound with `for="TypeName"`.
 - Added `adminOverrides` option to `createCoalesceVuetify()`, allowing custom Vue components to replace the default input and/or display components used in admin pages (`c-admin-editor`, `c-admin-method`, `c-table`) for specific model properties, method parameters, or method return values.
 - `c-datetime-picker`: Assorted UI and UX improvements and fixes.

docs/stacks/vue/layers/api-clients.md

@@ -340,6 +340,8 @@ Enables response caching on the API Caller.
 
   Only [HTTP GET methods](/modeling/model-components/attributes/controller-action.md) are supported, and [file-returning methods](/modeling/model-components/methods.md#file-downloads) are not supported. Call with `false` to disable caching after it was previously enabled.
 
+  The `limit` option can be used to cap the number or total size of cached responses in a group. When limits are exceeded, the oldest entries are evicted first. By default, entries are grouped by endpoint URL path (without query parameters), but a custom `key` can be provided to group entries differently. Group metadata is stored alongside cache entries in the same `Storage`.
+
 - **Example**
 
   ```ts
@@ -350,6 +352,14 @@ Enables response caching on the API Caller.
   });
   ```
 
+  ```ts
+  // Limit cached responses to 10 entries per endpoint
+  const caller = client.$makeCaller("item", (c, id: number) => c.getItem(id));
+  caller.useResponseCaching({
+    limit: { maxEntries: 10 },
+  });
+  ```
+
 ### useSimultaneousRequestCaching() {#usesimultaneousrequestcaching-caller}
 
 Enables simultaneous request caching on the API Caller.

src/coalesce-vue/src/api-client.ts

@@ -1448,6 +1448,19 @@ export type ResponseCachingConfiguration = {
 
   /** The Storage (default `sessionStorage`) that will hold cached responses. */
   storage?: Storage;
+
+  /** Limits for the number or total size of cached responses in a group.
+   * When limits are exceeded, the oldest entries are evicted first.
+   */
+  limit?: {
+    /** The group key for this set of cached responses. Entries sharing the same group key share a limit.
+     * Defaults to the endpoint URL path without query parameters. */
+    key?: string | ((req: AxiosRequestConfig, defaultKey: string) => string);
+    /** Maximum total size in bytes of serialized cached responses in this group. */
+    maxBytes?: number;
+    /** Maximum number of cached entries in this group. */
+    maxEntries?: number;
+  };
 };
 
 // Base class for ApiState that contains nothing but the logic for
@@ -1849,6 +1862,7 @@ export abstract class ApiState<
             key: keyFunc,
             storage = sessionStorage,
             maxAgeSeconds: configuredMaxAge = 3600,
+            limit,
           } = responseCacheConfig!;
 
           if (request.method?.toUpperCase() != "GET") {
@@ -1922,18 +1936,38 @@ export abstract class ApiState<
           const data = resp.data;
           try {
             purgeStaleCacheEntries(storage);
-            storage.setItem(
-              key,
-              JSON.stringify(
-                {
-                  time: Date.now() / 1000,
-                  maxAge: configuredMaxAge,
-                  result: data,
-                },
-                (key, value) =>
-                  key == "$metadata" || value === null ? undefined : value,
-              ),
+            const nowSeconds = Date.now() / 1000;
+            const serialized = JSON.stringify(
+              {
+                time: nowSeconds,
+                maxAge: configuredMaxAge,
+                result: data,
+              },
+              (key, value) =>
+                key == "$metadata" || value === null ? undefined : value,
             );
+            storage.setItem(key, serialized);
+
+            if (limit) {
+              const entrySizeBytes =
+                typeof TextEncoder !== "undefined"
+                  ? new TextEncoder().encode(serialized).length
+                  : serialized.length;
+
+              enforceGroupLimits(
+                storage,
+                limit.key
+                  ? typeof limit.key === "function"
+                    ? limit.key(request, defaultKey)
+                    : limit.key
+                  : defaultKey.split("?")[0],
+                key,
+                entrySizeBytes,
+                nowSeconds,
+                limit.maxEntries,
+                limit.maxBytes,
+              );
+            }
           } catch (e) {
             console.warn(
               "coalesce: useResponseCaching: Unable to store response",
@@ -2108,6 +2142,79 @@ function purgeStaleCacheEntries(storage: Storage) {
   }
 }
 
+interface CacheGroupEntry {
+  time: number;
+  size: number;
+}
+
+interface CacheGroupMetadata {
+  entries: Record<string, CacheGroupEntry>;
+}
+
+function enforceGroupLimits(
+  storage: Storage,
+  groupKey: string,
+  cacheKey: string,
+  entrySize: number,
+  entryTime: number,
+  maxEntries?: number,
+  maxBytes?: number,
+) {
+  const groupStorageKey = `coalesce:group:${groupKey}`;
+  let metadata: CacheGroupMetadata;
+
+  try {
+    const raw = storage.getItem(groupStorageKey);
+    const parsed = raw ? (JSON.parse(raw) as unknown) : null;
+
+    metadata =
+      parsed &&
+      typeof parsed === "object" &&
+      "entries" in parsed &&
+      (parsed as any).entries &&
+      typeof (parsed as any).entries === "object"
+        ? (parsed as CacheGroupMetadata)
+        : { entries: {} };
+  } catch {
+    metadata = { entries: {} };
+  }
+
+  // Add/update current entry
+  metadata.entries[cacheKey] = { time: entryTime, size: entrySize };
+
+  // Remove references to entries that no longer exist in storage
+  for (const key of Object.keys(metadata.entries)) {
+    if (key !== cacheKey && storage.getItem(key) === null) {
+      delete metadata.entries[key];
+    }
+  }
+
+  // Sort entries by time (oldest first) for eviction
+  const sortedEntries = Object.entries(metadata.entries).sort(
+    ([, a], [, b]) => a.time - b.time,
+  );
+
+  // Evict oldest entries to satisfy maxEntries
+  while (maxEntries != null && sortedEntries.length > maxEntries) {
+    const [evictKey] = sortedEntries.shift()!;
+    storage.removeItem(evictKey);
+    delete metadata.entries[evictKey];
+  }
+
+  // Evict oldest entries to satisfy maxBytes (always keep at least the newest entry)
+  if (maxBytes != null) {
+    let totalSize = sortedEntries.reduce((sum, [, e]) => sum + e.size, 0);
+    while (totalSize > maxBytes && sortedEntries.length > 1) {
+      const [evictKey, evictEntry] = sortedEntries.shift()!;
+      totalSize -= evictEntry.size;
+      storage.removeItem(evictKey);
+      delete metadata.entries[evictKey];
+    }
+  }
+
+  storage.setItem(groupStorageKey, JSON.stringify(metadata));
+}
+
 purgeStaleCacheEntries(localStorage);
 purgeStaleCacheEntries(sessionStorage);
 

src/coalesce-vue/test/api-client.spec.ts

@@ -1383,6 +1383,185 @@ describe("$makeCaller", () => {
       await delay(1);
       expect(caller2.result).toBe("response2");
     });
+
+    describe("limit", () => {
+      test("maxEntries evicts oldest entries", async () => {
+        let callNum = 0;
+        AxiosClient.defaults.adapter = () =>
+          makeEndpointMock("result" + ++callNum)();
+
+        const makeCaller = (id: number) => {
+          const caller = new PersonApiClient().$makeCaller("item", (c) =>
+            c.fullNameAndAge(id),
+          );
+          caller.useResponseCaching({
+            limit: { maxEntries: 2 },
+          });
+          return caller;
+        };
+
+        // Populate three entries with different ids (different cache keys)
+        await makeCaller(1)();
+        await makeCaller(2)();
+        await makeCaller(3)();
+
+        // The group should have evicted the oldest (id=1) entry.
+        // Make a new caller for id=1 - it should NOT get a cached result.
+        const check1 = makeCaller(1);
+        check1();
+        expect(check1.result).toBe(null);
+
+        // Make a new caller for id=2 - it SHOULD get a cached result.
+        const check2 = makeCaller(2);
+        check2();
+        expect(check2.result).toBe("result2");
+
+        // Make a new caller for id=3 - it SHOULD get a cached result.
+        const check3 = makeCaller(3);
+        check3();
+        expect(check3.result).toBe("result3");
+      });
+
+      test("maxBytes evicts oldest entries", async () => {
+        let callNum = 0;
+        AxiosClient.defaults.adapter = () =>
+          makeEndpointMock("result" + ++callNum)();
+
+        const makeCaller = (id: number) => {
+          const caller = new PersonApiClient().$makeCaller("item", (c) =>
+            c.fullNameAndAge(id),
+          );
+          caller.useResponseCaching({
+            // Set maxBytes very small so that only one entry fits
+            limit: { maxBytes: 1 },
+          });
+          return caller;
+        };
+
+        await makeCaller(1)();
+        await makeCaller(2)();
+
+        // id=1 should have been evicted because maxBytes is too small for two entries
+        const check1 = makeCaller(1);
+        check1();
+        expect(check1.result).toBe(null);
+
+        // id=2 should still be cached (most recent, always kept)
+        const check2 = makeCaller(2);
+        check2();
+        expect(check2.result).toBe("result2");
+      });
+
+      test("custom group key groups entries independently", async () => {
+        let callNum = 0;
+        AxiosClient.defaults.adapter = () =>
+          makeEndpointMock("result" + ++callNum)();
+
+        const makeCaller = (id: number, groupKey: string) => {
+          const caller = new PersonApiClient().$makeCaller("item", (c) =>
+            c.fullNameAndAge(id),
+          );
+          caller.useResponseCaching({
+            limit: { key: groupKey, maxEntries: 1 },
+          });
+          return caller;
+        };
+
+        // Populate two separate groups
+        await makeCaller(1, "groupA")();
+        await makeCaller(2, "groupB")();
+
+        // Add another entry to groupA, evicting id=1
+        await makeCaller(3, "groupA")();
+
+        // id=1 should be evicted from groupA
+        const check1 = makeCaller(1, "groupA");
+        check1();
+        expect(check1.result).toBe(null);
+
+        // id=3 should be in groupA
+        const check3 = makeCaller(3, "groupA");
+        check3();
+        expect(check3.result).toBe("result3");
+
+        // id=2 in groupB should be unaffected
+        const check2 = makeCaller(2, "groupB");
+        check2();
+        expect(check2.result).toBe("result2");
+      });
+
+      test("group key as function", async () => {
+        let callNum = 0;
+        AxiosClient.defaults.adapter = () =>
+          makeEndpointMock("result" + ++callNum)();
+
+        const makeCaller = (id: number) => {
+          const caller = new PersonApiClient().$makeCaller("item", (c) =>
+            c.fullNameAndAge(id),
+          );
+          caller.useResponseCaching({
+            limit: {
+              key: (_req, defaultKey) => "fn-" + defaultKey.split("?")[0],
+              maxEntries: 1,
+            },
+          });
+          return caller;
+        };
+
+        await makeCaller(1)();
+        await makeCaller(2)();
+
+        // id=1 should be evicted (maxEntries=1)
+        const check1 = makeCaller(1);
+        check1();
+        expect(check1.result).toBe(null);
+
+        // id=2 should still be cached
+        const check2 = makeCaller(2);
+        check2();
+        expect(check2.result).toBe("result2");
+
+        // Verify the group metadata key uses the function result
+        const groupMetaKey = Object.keys(sessionStorage).find((k) =>
+          k.startsWith("coalesce:group:fn-"),
+        );
+        expect(groupMetaKey).toBeTruthy();
+      });
+
+      test("group metadata cleans up stale references", async () => {
+        let callNum = 0;
+        AxiosClient.defaults.adapter = () =>
+          makeEndpointMock("result" + ++callNum)();
+
+        const makeCaller = (id: number) => {
+          const caller = new PersonApiClient().$makeCaller("item", (c) =>
+            c.fullNameAndAge(id),
+          );
+          caller.useResponseCaching({
+            maxAgeSeconds: 0.3,
+            limit: { maxEntries: 5 },
+          });
+          return caller;
+        };
+
+        await makeCaller(1)();
+        await makeCaller(2)();
+
+        // Wait for entries to expire
+        await delay(400);
+
+        // Add a new entry - the stale references should be cleaned up
+        await makeCaller(3)();
+
+        // Verify the group metadata only has the new entry
+        const groupMetaKey = Object.keys(sessionStorage).find((k) =>
+          k.startsWith("coalesce:group:"),
+        );
+        expect(groupMetaKey).toBeTruthy();
+        const parsed = JSON.parse(sessionStorage.getItem(groupMetaKey!)!);
+        expect(Object.keys(parsed.entries)).toHaveLength(1);
+      });
+    });
   });
 });