@soham20/smart-offline-sdk 0.1.4 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soham20/smart-offline-sdk",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Smart offline-first JavaScript SDK with intelligent caching for web applications",
   "main": "./src/index.cjs.js",
   "module": "./src/index.js",

package/smart-offline-sw.js

@@ -15,6 +15,9 @@ let SDK_CONFIG = {
   maxResourceSize: Infinity,
   networkQuality: "auto", // 'auto' | 'fast' | 'slow'
   significance: {}, // { urlPattern: 'high' | 'normal' | 'low' }
+  weights: { frequency: 1, recency: 1, size: 1 },
+  customPriorityFn: null,
+  enableDetailedLogs: false
 };
 
 /**
@@ -24,12 +27,66 @@ self.addEventListener("message", (event) => {
   if (event.data && event.data.type === "INIT_CONFIG") {
     SDK_CONFIG = event.data.payload;
 
+    // Deserialize custom priority function if provided
+    if (SDK_CONFIG.customPriorityFn && typeof SDK_CONFIG.customPriorityFn === 'string') {
+      try {
+        SDK_CONFIG.customPriorityFn = eval(`(${SDK_CONFIG.customPriorityFn})`);
+      } catch (e) {
+        console.error('[SmartOffline] Failed to parse customPriorityFn:', e);
+        SDK_CONFIG.customPriorityFn = null;
+      }
+    }
+
     if (SDK_CONFIG.debug) {
       console.log("[SmartOffline] Config received:", SDK_CONFIG);
     }
   }
 });
 
+/**
+ * Log cache events to IndexedDB
+ */
+function logEvent(type, url, reason, metadata = {}) {
+  if (!SDK_CONFIG.enableDetailedLogs) return;
+
+  const request = indexedDB.open("smart-offline-logs", 1);
+
+  request.onupgradeneeded = () => {
+    const db = request.result;
+    if (!db.objectStoreNames.contains("logs")) {
+      db.createObjectStore("logs", { autoIncrement: true });
+    }
+  };
+
+  request.onsuccess = () => {
+    const db = request.result;
+    const tx = db.transaction("logs", "readwrite");
+    const store = tx.objectStore("logs");
+
+    store.add({
+      type,
+      url,
+      reason,
+      metadata,
+      timestamp: Date.now(),
+      date: new Date().toISOString()
+    });
+  };
+
+  // Also send to main thread
+  self.clients.matchAll().then(clients => {
+    clients.forEach(client => {
+      client.postMessage({
+        type: `CACHE_${type.toUpperCase()}`,
+        url,
+        reason,
+        metadata,
+        timestamp: Date.now()
+      });
+    });
+  });
+}
+
 /**
  * -------- Usage Tracking (IndexedDB) --------
  * Tracks frequency + recency per URL
@@ -86,9 +143,19 @@ function getUsage(url) {
 }
 
 /**
- * Decide priority based on real usage and developer-tuned config
+ * Decide priority based on real usage and developer-tuned config with weights
  */
 function isHighPriority(usage, url) {
+  // Custom priority function override
+  if (SDK_CONFIG.customPriorityFn && typeof SDK_CONFIG.customPriorityFn === 'function') {
+    try {
+      const score = SDK_CONFIG.customPriorityFn(usage, url, SDK_CONFIG);
+      return score > 50; // Scores above 50 are high priority
+    } catch (e) {
+      console.error('[SmartOffline] Custom priority function error:', e);
+    }
+  }
+
   // Manual significance override
   for (const pattern in SDK_CONFIG.significance) {
     if (url.includes(pattern)) {
@@ -101,10 +168,25 @@ function isHighPriority(usage, url) {
 
   if (!usage) return false;
 
-  const frequent = usage.count >= SDK_CONFIG.frequencyThreshold;
-  const recent = Date.now() - usage.lastAccessed <= SDK_CONFIG.recencyThreshold;
-
-  return frequent || recent;
+  // Weighted priority calculation
+  const weights = SDK_CONFIG.weights || { frequency: 1, recency: 1, size: 1 };
+  
+  // Frequency score (0-100)
+  const frequencyScore = Math.min(100, (usage.count / SDK_CONFIG.frequencyThreshold) * 100);
+  
+  // Recency score (0-100)
+  const timeSinceAccess = Date.now() - usage.lastAccessed;
+  const recencyScore = Math.max(0, 100 - (timeSinceAccess / SDK_CONFIG.recencyThreshold) * 100);
+  
+  // Weighted total
+  const totalWeight = weights.frequency + weights.recency;
+  const weightedScore = (
+    (frequencyScore * weights.frequency) + 
+    (recencyScore * weights.recency)
+  ) / totalWeight;
+  
+  // High priority if weighted score > 50
+  return weightedScore > 50;
 }
 
 /**
@@ -182,6 +264,11 @@ self.addEventListener("fetch", (event) => {
         const contentLength = response.headers.get("content-length");
         const size = contentLength ? parseInt(contentLength, 10) : 0;
         if (size > SDK_CONFIG.maxResourceSize) {
+          logEvent('skip', request.url, 'size_limit_exceeded', { 
+            size, 
+            limit: SDK_CONFIG.maxResourceSize 
+          });
+          
           if (SDK_CONFIG.debug) {
             console.log(
               `[SmartOffline] Skipped caching (size ${size} > ${SDK_CONFIG.maxResourceSize}):`,
@@ -193,8 +280,15 @@ self.addEventListener("fetch", (event) => {
 
         // Network quality aware caching
         const netQuality = getEffectiveNetworkQuality();
-        if (netQuality === "slow" && !isHighPriority(null, request.url)) {
-          // On slow network, skip caching low priority resources proactively
+        const usage = await getUsage(request.url);
+        const highPriority = isHighPriority(usage, request.url);
+        
+        if (netQuality === "slow" && !highPriority) {
+          logEvent('skip', request.url, 'slow_network_low_priority', { 
+            networkQuality: netQuality,
+            priority: 'low'
+          });
+          
           if (SDK_CONFIG.debug) {
             console.log(
               `[SmartOffline] Skipped caching (slow network, not high priority):`,
@@ -207,6 +301,11 @@ self.addEventListener("fetch", (event) => {
         const clone = response.clone();
         caches.open(CACHE_NAME).then((cache) => {
           cache.put(request.url, clone);
+          logEvent('cache', request.url, 'network_fetch_success', {
+            type: isAPI ? 'API' : 'PAGE',
+            size,
+            priority: highPriority ? 'high' : 'normal'
+          });
         });
 
         if (SDK_CONFIG.debug) {
@@ -218,25 +317,33 @@ self.addEventListener("fetch", (event) => {
 
         return response;
       })
-      .catch(() => {
+      .catch(async () => {
         // Offline / network failure
         trackUsage(request.url);
 
-        return getUsage(request.url).then((usage) => {
-          const highPriority = isHighPriority(usage, request.url);
+        const usage = await getUsage(request.url);
+        const highPriority = isHighPriority(usage, request.url);
+        const cached = await caches.match(request.url);
+
+        if (cached) {
+          logEvent('serve', request.url, 'offline_cache_hit', {
+            priority: highPriority ? 'high' : 'normal',
+            usage: usage ? { count: usage.count, lastAccessed: usage.lastAccessed } : null
+          });
 
           if (SDK_CONFIG.debug) {
             console.log(
-              `[SmartOffline] ${
-                highPriority ? "HIGH" : "NORMAL"
-              } priority:`,
+              `[SmartOffline] Served from cache (${highPriority ? "HIGH" : "NORMAL"} priority):`,
               request.url
             );
           }
+        } else {
+          logEvent('error', request.url, 'cache_miss_offline', {
+            priority: highPriority ? 'high' : 'normal'
+          });
+        }
 
-          // v1 behavior: both return cache, but priority is decided & logged
-          return caches.match(request.url);
-        });
+        return cached;
       })
   );
 });

package/src/index.cjs.js

@@ -1,6 +1,14 @@
 /**
  * SmartOffline SDK (CommonJS version)
  */
+const eventListeners = {
+  cache: [],
+  skip: [],
+  serve: [],
+  clear: [],
+  error: []
+};
+
 function init(config = {}) {
   if (typeof navigator === "undefined" || !("serviceWorker" in navigator)) {
     console.warn("Service Workers not supported");
@@ -16,11 +24,34 @@ function init(config = {}) {
     maxResourceSize: config.maxResourceSize ?? Infinity,
     networkQuality: config.networkQuality ?? "auto",
     significance: config.significance ?? {},
+    weights: {
+      frequency: config.weights?.frequency ?? 1,
+      recency: config.weights?.recency ?? 1,
+      size: config.weights?.size ?? 1
+    },
+    customPriorityFn: config.customPriorityFn ? config.customPriorityFn.toString() : null,
+    enableDetailedLogs: config.enableDetailedLogs ?? false
   };
 
+  if (config.onCacheEvent) {
+    eventListeners.cache.push(config.onCacheEvent);
+    eventListeners.skip.push(config.onCacheEvent);
+    eventListeners.serve.push(config.onCacheEvent);
+    eventListeners.clear.push(config.onCacheEvent);
+    eventListeners.error.push(config.onCacheEvent);
+  }
+
   navigator.serviceWorker.register("/smart-offline-sw.js").then(() => {
     console.log("Smart Offline Service Worker registered");
 
+    navigator.serviceWorker.addEventListener('message', (event) => {
+      if (event.data && event.data.type) {
+        const eventType = event.data.type.replace('CACHE_', '').toLowerCase();
+        const listeners = eventListeners[eventType] || [];
+        listeners.forEach(fn => fn(event.data));
+      }
+    });
+
     navigator.serviceWorker.ready.then(() => {
       if (navigator.serviceWorker.controller) {
         navigator.serviceWorker.controller.postMessage({
@@ -52,7 +83,54 @@ function init(config = {}) {
   });
 }
 
-const SmartOffline = { init };
+function on(eventType, callback) {
+  if (eventListeners[eventType]) {
+    eventListeners[eventType].push(callback);
+  }
+}
+
+function off(eventType, callback) {
+  if (eventListeners[eventType]) {
+    const index = eventListeners[eventType].indexOf(callback);
+    if (index > -1) {
+      eventListeners[eventType].splice(index, 1);
+    }
+  }
+}
+
+async function getCacheLogs() {
+  const db = await openDB('smart-offline-logs', 1);
+  const tx = db.transaction('logs', 'readonly');
+  const store = tx.objectStore('logs');
+  return new Promise((resolve) => {
+    const request = store.getAll();
+    request.onsuccess = () => resolve(request.result || []);
+    request.onerror = () => resolve([]);
+  });
+}
+
+async function clearCacheLogs() {
+  const db = await openDB('smart-offline-logs', 1);
+  const tx = db.transaction('logs', 'readwrite');
+  const store = tx.objectStore('logs');
+  store.clear();
+}
+
+function openDB(name, version) {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(name, version);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains('logs')) {
+        db.createObjectStore('logs', { autoIncrement: true });
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+
+const SmartOffline = { init, on, off, getCacheLogs, clearCacheLogs };
 
 module.exports = { SmartOffline };
 module.exports.default = SmartOffline;

package/src/index.d.ts

@@ -1,3 +1,32 @@
+export interface UsageData {
+  url: string;
+  count: number;
+  lastAccessed: number;
+}
+
+export interface CacheWeights {
+  /** Weight for frequency score (default: 1) */
+  frequency?: number;
+  /** Weight for recency score (default: 1) */
+  recency?: number;
+  /** Weight for size consideration (default: 1) */
+  size?: number;
+}
+
+export interface CacheEvent {
+  type: 'CACHE_CACHE' | 'CACHE_SKIP' | 'CACHE_SERVE' | 'CACHE_CLEAR' | 'CACHE_ERROR';
+  url: string;
+  reason: string;
+  metadata?: any;
+  timestamp: number;
+}
+
+export type CustomPriorityFunction = (
+  usage: UsageData | null, 
+  url: string, 
+  config: SmartOfflineConfig
+) => number; // Return 0-100, >50 is high priority
+
 export interface SmartOfflineConfig {
   /** Array of page URL patterns to cache */
   pages?: string[];
@@ -12,14 +41,36 @@ export interface SmartOfflineConfig {
   /** Max bytes to cache per resource; larger resources skipped (default: Infinity) */
   maxResourceSize?: number;
   /** Network quality setting: 'auto' | 'fast' | 'slow' (default: 'auto') */
-  networkQuality?: 'auto' | 'fast' | 'slow';
+  networkQuality?: "auto" | "fast" | "slow";
   /** Manual priority overrides by URL pattern */
-  significance?: Record<string, 'high' | 'normal' | 'low'>;
+  significance?: Record<string, "high" | "normal" | "low">;
+  /** Weights for priority calculation (default: all 1) */
+  weights?: CacheWeights;
+  /** Custom priority function for complete control */
+  customPriorityFn?: CustomPriorityFunction;
+  /** Enable detailed event logging to IndexedDB */
+  enableDetailedLogs?: boolean;
+  /** Callback for all cache events */
+  onCacheEvent?: (event: CacheEvent) => void;
+}
+
+export interface CacheLog {
+  type: string;
+  url: string;
+  reason: string;
+  metadata?: any;
+  timestamp: number;
+  date: string;
 }
 
 export interface SmartOfflineSDK {
   init(config?: SmartOfflineConfig): void;
+  on(eventType: 'cache' | 'skip' | 'serve' | 'clear' | 'error', callback: (event: CacheEvent) => void): void;
+  off(eventType: 'cache' | 'skip' | 'serve' | 'clear' | 'error', callback: (event: CacheEvent) => void): void;
+  getCacheLogs(): Promise<CacheLog[]>;
+  clearCacheLogs(): Promise<void>;
 }
 
 export declare const SmartOffline: SmartOfflineSDK;
 export default SmartOffline;
+

package/src/index.js

@@ -7,7 +7,20 @@
  * - maxResourceSize: max bytes to cache per resource; larger resources skipped (default Infinity)
  * - networkQuality: 'auto' | 'fast' | 'slow' — affects caching aggressiveness (default 'auto')
  * - significance: { [urlPattern]: 'high' | 'normal' | 'low' } — manual priority overrides
+ * - weights: { frequency: number, recency: number, size: number } — priority weights (default all 1)
+ * - customPriorityFn: (usage, url, config) => number — custom priority function (0-100)
+ * - onCacheEvent: (event) => void — callback for cache events (cache, skip, serve, clear)
  */
+
+// Event listener registry
+const eventListeners = {
+  cache: [],
+  skip: [],
+  serve: [],
+  clear: [],
+  error: []
+};
+
 function init(config = {}) {
   if (!("serviceWorker" in navigator)) {
     console.warn("Service Workers not supported");
@@ -23,11 +36,38 @@ function init(config = {}) {
     maxResourceSize: config.maxResourceSize ?? Infinity,
     networkQuality: config.networkQuality ?? "auto",
     significance: config.significance ?? {},
+    
+    // New features
+    weights: {
+      frequency: config.weights?.frequency ?? 1,
+      recency: config.weights?.recency ?? 1,
+      size: config.weights?.size ?? 1
+    },
+    customPriorityFn: config.customPriorityFn ? config.customPriorityFn.toString() : null,
+    enableDetailedLogs: config.enableDetailedLogs ?? false
   };
 
-  navigator.serviceWorker.register("/smart-offline-sw.js").then(() => {
+  // Register event listener if provided
+  if (config.onCacheEvent) {
+    eventListeners.cache.push(config.onCacheEvent);
+    eventListeners.skip.push(config.onCacheEvent);
+    eventListeners.serve.push(config.onCacheEvent);
+    eventListeners.clear.push(config.onCacheEvent);
+    eventListeners.error.push(config.onCacheEvent);
+  }
+
+  navigator.serviceWorker.register("/smart-offline-sw.js").then((registration) => {
     console.log("Smart Offline Service Worker registered");
 
+    // Listen for messages from SW
+    navigator.serviceWorker.addEventListener('message', (event) => {
+      if (event.data && event.data.type) {
+        const eventType = event.data.type.replace('CACHE_', '').toLowerCase();
+        const listeners = eventListeners[eventType] || [];
+        listeners.forEach(fn => fn(event.data));
+      }
+    });
+
     navigator.serviceWorker.ready.then(() => {
       if (navigator.serviceWorker.controller) {
         navigator.serviceWorker.controller.postMessage({
@@ -59,7 +99,63 @@ function init(config = {}) {
   });
 }
 
-const SmartOffline = { init };
+// API for managing event listeners
+function on(eventType, callback) {
+  if (eventListeners[eventType]) {
+    eventListeners[eventType].push(callback);
+  }
+}
+
+function off(eventType, callback) {
+  if (eventListeners[eventType]) {
+    const index = eventListeners[eventType].indexOf(callback);
+    if (index > -1) {
+      eventListeners[eventType].splice(index, 1);
+    }
+  }
+}
+
+// API to get cache logs
+async function getCacheLogs() {
+  const db = await openDB('smart-offline-logs', 1);
+  const tx = db.transaction('logs', 'readonly');
+  const store = tx.objectStore('logs');
+  return new Promise((resolve) => {
+    const request = store.getAll();
+    request.onsuccess = () => resolve(request.result || []);
+    request.onerror = () => resolve([]);
+  });
+}
+
+// API to clear cache logs
+async function clearCacheLogs() {
+  const db = await openDB('smart-offline-logs', 1);
+  const tx = db.transaction('logs', 'readwrite');
+  const store = tx.objectStore('logs');
+  store.clear();
+}
+
+function openDB(name, version) {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(name, version);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains('logs')) {
+        db.createObjectStore('logs', { autoIncrement: true });
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+
+const SmartOffline = { 
+  init, 
+  on, 
+  off, 
+  getCacheLogs, 
+  clearCacheLogs 
+};
 
 export { SmartOffline }; // ✅ named export
 export default SmartOffline; // ✅ default export