@oxy.so/core 1.1.1 → 1.1.2

package/dist/types/utils/cache.d.ts

@@ -118,10 +118,7 @@ export declare function createCache<T>(ttl?: number): TTLCache<T>;
  * @param cache Cache instance to register
  */
 export declare function registerCacheForCleanup(cache: TTLCache<any>): void;
-/**
- * Unregister a cache from automatic cleanup
- * @param cache Cache instance to unregister
- */
+/** Unregister a cache without changing its entries or TTL behavior. */
 export declare function unregisterCacheFromCleanup(cache: TTLCache<any>): void;
 /**
  * Stop all cleanup intervals (useful for testing)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/utils/__tests__/cacheLifecycle.test.ts

@@ -0,0 +1,65 @@
+import { TTLCache, registerCacheForCleanup, unregisterCacheFromCleanup, stopAllCleanupIntervals } from '../cache';
+
+afterEach(() => { stopAllCleanupIntervals(); jest.useRealTimers(); });
+
+test('empty registration is inert and first data starts one shared cleanup timer', () => {
+  jest.useFakeTimers();
+  const a = new TTLCache<string>(10);
+  const b = new TTLCache<string>(10);
+  registerCacheForCleanup(a);
+  registerCacheForCleanup(b);
+  expect(jest.getTimerCount()).toBe(0);
+  a.set('a', 'value');
+  b.set('b', 'value');
+  expect(jest.getTimerCount()).toBe(1);
+  jest.advanceTimersByTime(11);
+  expect(a.get('a')).toBeNull();
+  expect(b.has('b')).toBe(false);
+  jest.advanceTimersByTime(60_000);
+  expect(jest.getTimerCount()).toBe(0);
+});
+test('periodic cleanup expires unread entries and clear restarts lazily without losing registration', () => {
+  jest.useFakeTimers();
+  const a = new TTLCache<string>(10);
+  registerCacheForCleanup(a);
+  a.set('expired', 'value');
+  jest.advanceTimersByTime(60_000);
+  expect(a.size()).toBe(0);
+  expect(jest.getTimerCount()).toBe(0);
+  a.set('again', 'value');
+  expect(jest.getTimerCount()).toBe(1);
+  a.clear();
+  expect(jest.getTimerCount()).toBe(0);
+  a.set('after-clear', 'value');
+  expect(jest.getTimerCount()).toBe(1);
+});
+test('unregister and stop preserve entries but prevent writes restarting automatic cleanup', () => {
+  jest.useFakeTimers();
+  const a = new TTLCache<string>(100_000);
+  const b = new TTLCache<string>(100_000);
+  a.set('a', 'value');
+  registerCacheForCleanup(a);
+  registerCacheForCleanup(b);
+  b.set('b', 'value');
+  unregisterCacheFromCleanup(a);
+  expect(jest.getTimerCount()).toBe(1);
+  b.delete('b');
+  expect(jest.getTimerCount()).toBe(0);
+  a.set('unregistered', 'value');
+  expect(jest.getTimerCount()).toBe(0);
+  registerCacheForCleanup(a);
+  expect(jest.getTimerCount()).toBe(1);
+  stopAllCleanupIntervals();
+  a.set('stopped', 'value');
+  expect(jest.getTimerCount()).toBe(0);
+  expect(a.get('a')).toBe('value');
+});
+test('server barrel imports and client construction start no background timers', () => {
+  jest.useFakeTimers();
+  jest.isolateModules(() => {
+    const server = require('../../server');
+    expect(typeof server.createEcosystemTraffic).toBe('function');
+    expect(jest.getTimerCount()).toBe(0);
+    require('../cache').stopAllCleanupIntervals();
+  });
+});

package/src/utils/cache.ts

@@ -104,6 +104,7 @@ export class TTLCache<T> {
     const effectiveTTL = ttl === undefined ? this.defaultTTL : ttl;
     const expiresAt = now + effectiveTTL;
     this.cache.set(key, { data, timestamp: now, expiresAt });
+    if (!cleanupInterval && activeCaches.has(this)) updateCleanupInterval();
   }
 
   /**
@@ -112,7 +113,9 @@ export class TTLCache<T> {
    * @returns true if entry was deleted, false if not found
    */
   delete(key: string): boolean {
-    return this.cache.delete(key);
+    const deleted = this.cache.delete(key);
+    if (activeCaches.has(this)) updateCleanupInterval();
+    return deleted;
   }
 
   /**
@@ -122,6 +125,7 @@ export class TTLCache<T> {
     this.cache.clear();
     this.hits = 0;
     this.misses = 0;
+    if (activeCaches.has(this)) updateCleanupInterval();
   }
 
   /**
@@ -232,31 +236,29 @@ const activeCaches = new Set<TTLCache<any>>();
  */
 export function registerCacheForCleanup(cache: TTLCache<any>): void {
   activeCaches.add(cache);
+  updateCleanupInterval();
+}
 
-  // Start cleanup interval if not already running
-  if (!cleanupInterval) {
-    cleanupInterval = setInterval(() => {
-      for (const cache of activeCaches) {
-        cache.cleanup();
-      }
-    }, 60000); // Every minute
-    // Never block process/worker exit on a housekeeping timer.
-    cleanupInterval.unref?.();
+/** Empty registered caches need no timer; importing a client must stay inert. */
+function updateCleanupInterval(): void {
+  const hasEntries = [...activeCaches].some(cache => cache.size() > 0);
+  if (!hasEntries) {
+    if (cleanupInterval) clearInterval(cleanupInterval);
+    cleanupInterval = null;
+    return;
   }
+  if (cleanupInterval) return;
+  cleanupInterval = setInterval(() => {
+    for (const cache of activeCaches) cache.cleanup();
+    updateCleanupInterval();
+  }, 60_000);
+  cleanupInterval.unref?.();
 }
 
-/**
- * Unregister a cache from automatic cleanup
- * @param cache Cache instance to unregister
- */
+/** Unregister a cache without changing its entries or TTL behavior. */
 export function unregisterCacheFromCleanup(cache: TTLCache<any>): void {
   activeCaches.delete(cache);
-
-  // Stop cleanup interval if no caches are registered
-  if (activeCaches.size === 0 && cleanupInterval) {
-    clearInterval(cleanupInterval);
-    cleanupInterval = null;
-  }
+  updateCleanupInterval();
 }
 
 /**