From baddd50d25b31aec7ef5a74ce9724491f95edef9 Mon Sep 17 00:00:00 2001
From: Ariel Melendez <ariel@ardrive.io>
Date: Fri, 27 Jun 2025 00:10:17 -0700
Subject: [PATCH 1/2] feat(metrics): drop cacheId in favor of prefix PE-8242

---
 src/metrics.test.ts | 109 +++++++++++---------------------------------
 src/metrics.ts      |  10 ++--
 2 files changed, 30 insertions(+), 89 deletions(-)

diff --git a/src/metrics.test.ts b/src/metrics.test.ts
index 7469bf8..c5d7880 100644
--- a/src/metrics.test.ts
+++ b/src/metrics.test.ts
@@ -38,7 +38,6 @@ describe('Metrics functionality', () => {
         cacheCapacity: 10,
         cacheTTL: 60000,
         metricsConfig: {
-          cacheId: 'test_cache',
           registry,
           prefix: 'test_prefix',
           labels: { test_label: 'test_value' },
@@ -55,10 +54,10 @@ describe('Metrics functionality', () => {
 
       const metrics = await registry.metrics();
       expect(metrics).to.include(
-        'test_prefix_hits_total{cache_id="test_cache",test_label="test_value"} 1',
+        'test_prefix_hits_total{test_label="test_value"} 1',
       );
       expect(metrics).to.include(
-        'test_prefix_misses_total{cache_id="test_cache",test_label="test_value"} 1',
+        'test_prefix_misses_total{test_label="test_value"} 1',
       );
     });
 
@@ -66,89 +65,77 @@ describe('Metrics functionality', () => {
       const cache = new PromiseCache<string, string>({
         cacheCapacity: 10,
         cacheTTL: 60000,
-        metricsConfig: {
-          cacheId: 'test_cache',
-          registry,
-          prefix: 'test_prefix',
-        },
+        metricsConfig: { registry, prefix: 'test_prefix' },
       });
 
       await cache.put('key1', Promise.resolve('value1'));
       await cache.put('key2', Promise.resolve('value2'));
 
       const metrics = await registry.metrics();
-      expect(metrics).to.include(
-        'test_prefix_puts_total{cache_id="test_cache"} 2',
-      );
+      expect(metrics).to.include('test_prefix_puts_total 2');
     });
 
     it('should track cache size', async () => {
       const cache = new PromiseCache<string, string>({
         cacheCapacity: 10,
         cacheTTL: 60000,
-        metricsConfig: { cacheId: 'test_cache', registry },
+        metricsConfig: { registry, prefix: 'test_prefix' },
       });
 
       await cache.put('key1', Promise.resolve('value1'));
       await cache.put('key2', Promise.resolve('value2'));
 
       const metrics = await registry.metrics();
-      expect(metrics).to.include('promise_cache_size{cache_id="test_cache"} 2');
+      expect(metrics).to.include('test_prefix_size 2');
     });
 
     it('should track remove operations', async () => {
       const cache = new PromiseCache<string, string>({
         cacheCapacity: 10,
         cacheTTL: 60000,
-        metricsConfig: { cacheId: 'test_cache', registry },
+        metricsConfig: { registry, prefix: 'test_prefix' },
       });
 
       await cache.put('key1', Promise.resolve('value1'));
       cache.remove('key1');
 
       const metrics = await registry.metrics();
-      expect(metrics).to.include(
-        'promise_cache_removes_total{cache_id="test_cache"} 1',
-      );
+      expect(metrics).to.include('test_prefix_removes_total 1');
     });
 
     it('should track clear operations', async () => {
       const cache = new PromiseCache<string, string>({
         cacheCapacity: 10,
         cacheTTL: 60000,
-        metricsConfig: { cacheId: 'test_cache', registry },
+        metricsConfig: { registry, prefix: 'test_prefix' },
       });
 
       await cache.put('key1', Promise.resolve('value1'));
       cache.clear();
 
       const metrics = await registry.metrics();
-      expect(metrics).to.include(
-        'promise_cache_clears_total{cache_id="test_cache"} 1',
-      );
+      expect(metrics).to.include('test_prefix_clears_total 1');
     });
 
     it('should track eviction operations when called directly', async () => {
       const cache = new PromiseCache<string, string>({
         cacheCapacity: 2,
         cacheTTL: 60000,
-        metricsConfig: { cacheId: 'test_cache', registry },
+        metricsConfig: { registry, prefix: 'test_prefix' },
       });
 
       const metrics = cache.getMetrics();
       metrics!.recordEviction();
 
       const metricsOutput = await registry.metrics();
-      expect(metricsOutput).to.include(
-        'promise_cache_evictions_total{cache_id="test_cache"} 1',
-      );
+      expect(metricsOutput).to.include('test_prefix_evictions_total 1');
     });
 
     it('should provide access to metrics objects', () => {
       const cache = new PromiseCache<string, string>({
         cacheCapacity: 10,
         cacheTTL: 60000,
-        metricsConfig: { cacheId: 'test_cache', registry },
+        metricsConfig: { registry, prefix: 'test_prefix' },
       });
 
       const metrics = cache.getMetrics();
@@ -170,11 +157,7 @@ describe('Metrics functionality', () => {
       const cache = new ReadThroughPromiseCache<string, string>({
         cacheParams: { cacheCapacity: 10, cacheTTL: 60000 },
         readThroughFunction: async (key: string) => `value-${key}`,
-        metricsConfig: {
-          cacheId: 'test_cache',
-          registry,
-          prefix: 'test_rt_cache_1',
-        },
+        metricsConfig: { registry, prefix: 'test_rt_cache_1' },
       });
 
       // First access should be a miss
@@ -184,12 +167,8 @@ describe('Metrics functionality', () => {
       await cache.get('key1');
 
       const metrics = await registry.metrics();
-      expect(metrics).to.include(
-        'test_rt_cache_1_hits_total{cache_id="test_cache"} 1',
-      );
-      expect(metrics).to.include(
-        'test_rt_cache_1_misses_total{cache_id="test_cache"} 1',
-      );
+      expect(metrics).to.include('test_rt_cache_1_hits_total 1');
+      expect(metrics).to.include('test_rt_cache_1_misses_total 1');
     });
 
     it('should remove failed promises from cache in getWithStatus', async () => {
@@ -201,11 +180,7 @@ describe('Metrics functionality', () => {
           }
           return `value-${key}`;
         },
-        metricsConfig: {
-          cacheId: 'test_cache',
-          registry,
-          prefix: 'test_rt_cache_3',
-        },
+        metricsConfig: { registry, prefix: 'test_rt_cache_3' },
       });
 
       try {
@@ -234,74 +209,46 @@ describe('Metrics functionality', () => {
       const cache = new ReadThroughPromiseCache<string, string>({
         cacheParams: { cacheCapacity: 10, cacheTTL: 60000 },
         readThroughFunction: async (key: string) => `value-${key}`,
-        metricsConfig: { cacheId: 'test_cache' },
+        metricsConfig: { prefix: 'test_cache' },
       });
 
       await cache.get('key1');
 
       const metrics = await register.metrics();
-      expect(metrics).to.include(
-        'promise_cache_misses_total{cache_id="test_cache"} 1',
-      );
+      expect(metrics).to.include('test_cache_misses_total 1');
     });
 
-    it('should handle undefined prefix in metricsConfig', async () => {
+    it('should default to prefix "promise_cache" for a zero length prefix', async () => {
       const cache = new ReadThroughPromiseCache<string, string>({
         cacheParams: { cacheCapacity: 10, cacheTTL: 60000 },
         readThroughFunction: async (key: string) => `value-${key}`,
-        metricsConfig: { cacheId: 'test_cache', registry },
-      });
-
-      await cache.get('key1');
-
-      const metrics = await registry.metrics();
-      expect(metrics).to.include(
-        'promise_cache_misses_total{cache_id="test_cache"} 1',
-      );
-    });
-
-    it('should handle a zero length prefix', async () => {
-      const cache = new ReadThroughPromiseCache<string, string>({
-        cacheParams: { cacheCapacity: 10, cacheTTL: 60000 },
-        readThroughFunction: async (key: string) => `value-${key}`,
-        metricsConfig: { cacheId: 'test_cache', prefix: '' },
+        metricsConfig: { prefix: '' },
       });
 
       await cache.get('key1');
 
       const metrics = await register.metrics();
-      expect(metrics).to.include(
-        'promise_cache_misses_total{cache_id="test_cache"} 1',
-      );
+      expect(metrics).to.include('promise_cache_misses_total 1');
     });
 
     it('should handle empty registry in metricsConfig', async () => {
       const cache = new ReadThroughPromiseCache<string, string>({
         cacheParams: { cacheCapacity: 10, cacheTTL: 60000 },
         readThroughFunction: async (key: string) => `value-${key}`,
-        metricsConfig: {
-          cacheId: 'test_cache',
-          prefix: 'test_rt_cache_empty_registry',
-        },
+        metricsConfig: { prefix: 'test_rt_cache_empty_registry' },
       });
 
       await cache.get('key1');
 
       const metrics = await register.metrics();
-      expect(metrics).to.include(
-        'test_rt_cache_empty_registry_misses_total{cache_id="test_cache"} 1',
-      );
+      expect(metrics).to.include('test_rt_cache_empty_registry_misses_total 1');
     });
 
     it('should provide access to metrics objects', () => {
       const cache = new ReadThroughPromiseCache<string, string>({
         cacheParams: { cacheCapacity: 10, cacheTTL: 60000 },
         readThroughFunction: async (key: string) => `value-${key}`,
-        metricsConfig: {
-          cacheId: 'test_cache',
-          registry,
-          prefix: 'test_rt_cache_metrics_obj',
-        },
+        metricsConfig: { registry, prefix: 'test_rt_cache_metrics_obj' },
       });
 
       const metrics = cache.getMetrics();
@@ -323,12 +270,10 @@ describe('Metrics functionality', () => {
 
   describe('CacheMetrics constructor', () => {
     it('should create metrics with default values', async () => {
-      const cacheMetrics = new CacheMetrics({ cacheId: 'test_cache' });
+      const cacheMetrics = new CacheMetrics({ prefix: 'test_cache' });
       cacheMetrics.recordHit();
       const metrics = await register.metrics();
-      expect(metrics).to.include(
-        'promise_cache_hits_total{cache_id="test_cache"} 1',
-      );
+      expect(metrics).to.include('test_cache_hits_total 1');
     });
   });
 });
diff --git a/src/metrics.ts b/src/metrics.ts
index 6aa0a9a..fe82437 100644
--- a/src/metrics.ts
+++ b/src/metrics.ts
@@ -20,9 +20,8 @@ import { Counter, Gauge, Registry, register } from 'prom-client';
 // Resulting metrics will be of the form:
 // <prefix ?? "promise_cache">_<metric name>{cache_id=<cacheId>, <label name 1>=<label value 1>, ..., <label name N>=<label value N>} <metric value>
 export interface CacheMetricsConfig {
-  cacheId: string;
+  prefix: string;
   registry?: Registry;
-  prefix?: string;
   labels?: Record<string, string>;
 }
 
@@ -39,11 +38,8 @@ export class CacheMetrics {
 
   constructor(config: CacheMetricsConfig) {
     const registry = config.registry || register;
-    this.prefix =
-      config.prefix != undefined && config.prefix.length > 0
-        ? config.prefix
-        : 'promise_cache';
-    this.defaultLabels = { cache_id: config.cacheId, ...config.labels };
+    this.prefix = config.prefix || 'promise_cache';
+    this.defaultLabels = { ...config.labels };
     const labelNames = Object.keys(this.defaultLabels);
 
     this.hitCounter = new Counter({

From 397baeab1d1949c0715030dba1b33bee6b272b78 Mon Sep 17 00:00:00 2001
From: Ariel Melendez <ariel@ardrive.io>
Date: Fri, 27 Jun 2025 00:11:13 -0700
Subject: [PATCH 2/2] feat(cache): deprecate cacheTTL in favor of cacheTTLMills
 PE-8242

---
 src/promiseCache.test.ts |  2 +-
 src/promiseCache.ts      | 32 +++++++++++++++++++++++++-------
 2 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/src/promiseCache.test.ts b/src/promiseCache.test.ts
index 86a5eef..d4659b0 100644
--- a/src/promiseCache.test.ts
+++ b/src/promiseCache.test.ts
@@ -23,7 +23,7 @@ describe('PromiseCache class', () => {
   it('constructor takes a capacity that is not exceeded by excessive puts', async () => {
     const cache = new PromiseCache<string, string>({
       cacheCapacity: 1,
-      cacheTTL: 60,
+      cacheTTLMillis: 60,
     });
     cache.put('1', Promise.resolve('one'));
     cache.put('2', Promise.resolve('two'));
diff --git a/src/promiseCache.ts b/src/promiseCache.ts
index 2459811..4d8790d 100644
--- a/src/promiseCache.ts
+++ b/src/promiseCache.ts
@@ -18,17 +18,35 @@
 import { Cache, EphemeralCache } from '@alexsasharegan/simple-cache';
 import { CacheMetrics, CacheMetricsConfig } from './metrics';
 
-export interface CacheParams {
-  cacheCapacity: number;
-  cacheTTL: number;
-  metricsConfig?: CacheMetricsConfig;
-}
+export type CacheParams =
+  | {
+      cacheCapacity: number;
+      /** Time-to-live in milliseconds (deprecated, use cacheTTLMillis instead) */
+      cacheTTL: number;
+      cacheTTLMillis?: never;
+      metricsConfig?: CacheMetricsConfig;
+    }
+  | {
+      cacheCapacity: number;
+      cacheTTL?: never;
+      /** Time-to-live in milliseconds */
+      cacheTTLMillis: number;
+      metricsConfig?: CacheMetricsConfig;
+    };
 export class PromiseCache<K, V> {
   private readonly cache: Cache<string, Promise<V>>;
   protected readonly metrics?: CacheMetrics;
 
-  constructor({ cacheCapacity, cacheTTL, metricsConfig }: CacheParams) {
-    this.cache = EphemeralCache<string, Promise<V>>(cacheCapacity, cacheTTL);
+  constructor({
+    cacheCapacity,
+    cacheTTL,
+    cacheTTLMillis,
+    metricsConfig,
+  }: CacheParams) {
+    this.cache = EphemeralCache<string, Promise<V>>(
+      cacheCapacity,
+      cacheTTLMillis ?? cacheTTL,
+    );
 
     if (metricsConfig !== undefined) {
       this.metrics = new CacheMetrics(metricsConfig);