@soham20/smart-offline-sdk 0.2.1 → 1.0.1

package/src/index.cjs

@@ -0,0 +1,576 @@
+/**
+ * SmartOffline SDK (CommonJS version) - v2.0
+ *
+ * Complete, reliable offline-first caching SDK for web applications.
+ *
+ * Usage:
+ * ```javascript
+ * const { SmartOffline, setupSmartOffline } = require('@soham20/smart-offline-sdk')
+ *
+ * // Initialize early in your app
+ * setupSmartOffline({
+ *   pages: ['/dashboard/*', '/products/*'],
+ *   apis: ['/api/v1/*'],
+ *   debug: true
+ * }).then(result => {
+ *   if (result.success) {
+ *     console.log('SmartOffline ready!')
+ *   }
+ * })
+ * ```
+ */
+
+// ============================================================================
+// DEFAULT CONFIGURATION
+// ============================================================================
+
+const DEFAULT_CONFIG = {
+    pages: [],
+    apis: [],
+    debug: typeof process !== "undefined" && process.env && process.env.NODE_ENV !== "production",
+    frequencyThreshold: 3,
+    recencyThreshold: 24 * 60 * 60 * 1000, // 24 hours
+    maxResourceSize: 10 * 1024 * 1024, // 10MB
+    networkQuality: "auto",
+    significance: {},
+    weights: { frequency: 1, recency: 1, size: 1 },
+    customPriorityFn: null,
+    enableDetailedLogs: false,
+    serviceWorkerPath: "/smart-offline-sw.js",
+    serviceWorkerScope: "/",
+}
+
+// ============================================================================
+// STATE
+// ============================================================================
+
+let isInitialized = false
+let serviceWorkerRegistration = null
+let currentConfig = { ...DEFAULT_CONFIG }
+
+// Event listener registry
+const eventListeners = {
+    cache: [],
+    skip: [],
+    serve: [],
+    clear: [],
+    error: [],
+}
+
+// ============================================================================
+// MAIN SETUP FUNCTION
+// ============================================================================
+
+/**
+ * Initialize the SmartOffline SDK with complete setup
+ */
+async function setupSmartOffline(config = {}) {
+    // Merge with defaults
+    currentConfig = { ...DEFAULT_CONFIG, ...config }
+
+    // Check if already initialized
+    if (isInitialized) {
+        if (currentConfig.debug) {
+            console.warn("[SmartOffline] Already initialized, updating config...")
+        }
+        await sendConfigToServiceWorker()
+        return { success: true, registration: serviceWorkerRegistration }
+    }
+
+    // Check browser support
+    if (typeof navigator === "undefined" || !("serviceWorker" in navigator)) {
+        console.error("[SmartOffline] Service Workers not supported in this browser")
+        return { success: false, error: "Service Workers not supported" }
+    }
+
+    if (typeof window === "undefined" || !("caches" in window)) {
+        console.error("[SmartOffline] Cache API not supported in this browser")
+        return { success: false, error: "Cache API not supported" }
+    }
+
+    try {
+        // Register service worker
+        if (currentConfig.debug) {
+            console.log("[SmartOffline] Registering service worker...")
+        }
+
+        serviceWorkerRegistration = await navigator.serviceWorker.register(
+            currentConfig.serviceWorkerPath,
+            { scope: currentConfig.serviceWorkerScope }
+        )
+
+        if (currentConfig.debug) {
+            console.log(
+                "[SmartOffline] Service worker registered:",
+                serviceWorkerRegistration.scope
+            )
+        }
+
+        // Wait for the service worker to be ready
+        await navigator.serviceWorker.ready
+
+        if (currentConfig.debug) {
+            console.log("[SmartOffline] Service worker ready")
+        }
+
+        // Send configuration to service worker
+        await sendConfigToServiceWorker()
+
+        // Set up event listeners
+        setupEventListeners()
+
+        isInitialized = true
+
+        if (currentConfig.debug) {
+            console.log("[SmartOffline] Setup complete! Configuration:", {
+                pages: currentConfig.pages,
+                apis: currentConfig.apis,
+                frequencyThreshold: currentConfig.frequencyThreshold,
+                recencyThreshold: currentConfig.recencyThreshold / (60 * 60 * 1000) + "h",
+            })
+        }
+
+        return { success: true, registration: serviceWorkerRegistration }
+    } catch (error) {
+        console.error("[SmartOffline] Setup failed:", error)
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        }
+    }
+}
+
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+
+async function sendConfigToServiceWorker() {
+    const controller = navigator.serviceWorker.controller
+
+    if (!controller) {
+        await new Promise((resolve) => setTimeout(resolve, 100))
+        const reg = await navigator.serviceWorker.ready
+        const worker = reg.active
+
+        if (worker) {
+            sendConfigMessage(worker)
+        }
+    } else {
+        sendConfigMessage(controller)
+    }
+}
+
+function sendConfigMessage(worker) {
+    const transferableConfig = {
+        ...currentConfig,
+        customPriorityFn: currentConfig.customPriorityFn
+            ? currentConfig.customPriorityFn.toString()
+            : null,
+        onCacheEvent: undefined,
+    }
+
+    worker.postMessage({
+        type: "INIT_CONFIG",
+        payload: transferableConfig,
+    })
+
+    if (currentConfig.debug) {
+        console.log("[SmartOffline] Config sent to service worker")
+    }
+}
+
+function setupEventListeners() {
+    navigator.serviceWorker.addEventListener("message", (event) => {
+        if (event.data && typeof event.data.type === "string") {
+            if (event.data.type.startsWith("CACHE_")) {
+                const cacheEvent = {
+                    type: event.data.type,
+                    url: event.data.url,
+                    reason: event.data.reason,
+                    metadata: event.data.metadata || {},
+                    timestamp: event.data.timestamp || Date.now(),
+                }
+
+                // Call user callback if provided
+                if (currentConfig.onCacheEvent) {
+                    currentConfig.onCacheEvent(cacheEvent)
+                }
+
+                // Call registered event listeners
+                const eventType = cacheEvent.type.replace("CACHE_", "").toLowerCase()
+                const listeners = eventListeners[eventType] || []
+                listeners.forEach((fn) => fn(cacheEvent))
+
+                // Debug logging
+                if (currentConfig.debug) {
+                    const icon = {
+                        CACHE_CACHE: "💾",
+                        CACHE_SKIP: "⏭️",
+                        CACHE_SERVE: "📤",
+                        CACHE_ERROR: "❌",
+                    }
+
+                    console.log(
+                        "[SmartOffline] " + (icon[cacheEvent.type] || "📝") + " " + cacheEvent.type.replace("CACHE_", "") + ":",
+                        cacheEvent.url.replace(typeof window !== "undefined" ? window.location.origin : "", ""),
+                        "(" + cacheEvent.reason + ")"
+                    )
+                }
+            }
+        }
+    })
+}
+
+function openDB(name, version) {
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.open(name, version)
+        request.onupgradeneeded = () => {
+            const db = request.result
+            if (name === "smart-offline-logs-v2" && !db.objectStoreNames.contains("logs")) {
+                db.createObjectStore("logs", { autoIncrement: true })
+            }
+            if (name === "smart-offline-usage-v2" && !db.objectStoreNames.contains("usage")) {
+                db.createObjectStore("usage", { keyPath: "url" })
+            }
+        }
+        request.onsuccess = () => resolve(request.result)
+        request.onerror = () => reject(request.error)
+    })
+}
+
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+
+async function updateConfig(newConfig) {
+    currentConfig = { ...currentConfig, ...newConfig }
+    await sendConfigToServiceWorker()
+}
+
+function getConfig() {
+    return { ...currentConfig }
+}
+
+function isSmartOfflineReady() {
+    return isInitialized
+}
+
+function getServiceWorkerRegistration() {
+    return serviceWorkerRegistration
+}
+
+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() {
+    try {
+        const db = await openDB("smart-offline-logs-v2", 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([])
+        })
+    } catch {
+        return []
+    }
+}
+
+async function clearCacheLogs() {
+    try {
+        const db = await openDB("smart-offline-logs-v2", 1)
+        const tx = db.transaction("logs", "readwrite")
+        const store = tx.objectStore("logs")
+        store.clear()
+    } catch {
+        // Ignore errors
+    }
+}
+
+async function clearAllCache() {
+    const cacheNames = await caches.keys()
+    for (const name of cacheNames) {
+        if (name.startsWith("smart-offline")) {
+            await caches.delete(name)
+        }
+    }
+
+    const dbNames = ["smart-offline-usage-v2", "smart-offline-logs-v2"]
+    for (const dbName of dbNames) {
+        try {
+            indexedDB.deleteDatabase(dbName)
+        } catch {
+            // Ignore errors
+        }
+    }
+
+    if (currentConfig.debug) {
+        console.log("[SmartOffline] All cache data cleared")
+    }
+}
+
+async function getCacheStats() {
+    let cachedItems = 0
+    let cacheSize = 0
+    let trackedUrls = 0
+
+    try {
+        const cache = await caches.open("smart-offline-cache-v2")
+        const keys = await cache.keys()
+        cachedItems = keys.length
+
+        for (const request of keys) {
+            const response = await cache.match(request)
+            if (response) {
+                const size = parseInt(response.headers.get("content-length") || "0", 10)
+                cacheSize += size
+            }
+        }
+    } catch {
+        // Ignore errors
+    }
+
+    try {
+        const count = await new Promise((resolve) => {
+            const request = indexedDB.open("smart-offline-usage-v2", 1)
+            request.onsuccess = () => {
+                const db = request.result
+                try {
+                    const tx = db.transaction("usage", "readonly")
+                    const store = tx.objectStore("usage")
+                    const countReq = store.count()
+                    countReq.onsuccess = () => resolve(countReq.result)
+                    countReq.onerror = () => resolve(0)
+                } catch {
+                    resolve(0)
+                }
+            }
+            request.onerror = () => resolve(0)
+        })
+        trackedUrls = count
+    } catch {
+        // Ignore errors
+    }
+
+    return { cachedItems, trackedUrls, cacheSize }
+}
+
+async function forceUpdate() {
+    if (serviceWorkerRegistration) {
+        await serviceWorkerRegistration.update()
+        if (currentConfig.debug) {
+            console.log("[SmartOffline] Service worker update triggered")
+        }
+    }
+}
+
+async function uninstall() {
+    if (serviceWorkerRegistration) {
+        await serviceWorkerRegistration.unregister()
+    }
+    await clearAllCache()
+    isInitialized = false
+    serviceWorkerRegistration = null
+
+    if (currentConfig.debug) {
+        console.log("[SmartOffline] Uninstalled and cleaned up")
+    }
+}
+
+function init(config = {}) {
+    setupSmartOffline(config)
+}
+
+// ============================================================================
+// TEST UTILITIES
+// ============================================================================
+
+function matchesPattern(url, pattern) {
+    if (!pattern.includes("*")) {
+        return url.includes(pattern)
+    }
+    const regexPattern = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*")
+    return new RegExp(regexPattern).test(url)
+}
+
+function isHighPriority(usage, url, config = {}) {
+    const finalConfig = { ...DEFAULT_CONFIG, ...config }
+
+    if (finalConfig.customPriorityFn && typeof finalConfig.customPriorityFn === "function") {
+        try {
+            return finalConfig.customPriorityFn(usage, url, finalConfig) > 50
+        } catch (e) {
+            console.error("Custom priority function error:", e)
+        }
+    }
+
+    for (const pattern in finalConfig.significance) {
+        if (url.includes(pattern)) {
+            if (finalConfig.significance[pattern] === "high") return true
+            if (finalConfig.significance[pattern] === "low") return false
+        }
+    }
+
+    if (!usage) return false
+
+    const weights = finalConfig.weights || { frequency: 1, recency: 1, size: 1 }
+    const frequencyScore = Math.min(100, (usage.count / finalConfig.frequencyThreshold) * 100)
+    const timeSinceAccess = Date.now() - usage.lastAccessed
+    const recencyScore = Math.max(0, 100 - (timeSinceAccess / finalConfig.recencyThreshold) * 100)
+    const totalWeight = weights.frequency + weights.recency
+    const weightedScore = (frequencyScore * weights.frequency + recencyScore * weights.recency) / totalWeight
+
+    return weightedScore > 50
+}
+
+function shouldCacheUrl(url, config = {}) {
+    const pages = config.pages || []
+    const apis = config.apis || []
+    const isPage = pages.some((p) => matchesPattern(url, p))
+    const isAPI = apis.some((a) => matchesPattern(url, a))
+    return { isPage, isAPI }
+}
+
+// SmartOfflineTestSuite class
+function SmartOfflineTestSuite(config = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config }
+    this.results = []
+}
+
+SmartOfflineTestSuite.prototype.runAll = async function() {
+    this.results = []
+    // Add basic algorithm tests
+    this.testPatternMatching()
+    this.testFrequencyPriority()
+    return this.results
+}
+
+SmartOfflineTestSuite.prototype.testPatternMatching = function() {
+    const tests = [
+        { url: "/admin/charts", pattern: "/admin/charts", expected: true },
+        { url: "/admin/charts/123", pattern: "/admin/charts/*", expected: true },
+    ]
+    let passed = true
+    for (const test of tests) {
+        if (matchesPattern(test.url, test.pattern) !== test.expected) {
+            passed = false
+            break
+        }
+    }
+    this.results.push({ name: "Pattern Matching", passed, message: passed ? "All patterns matched" : "Pattern matching failed" })
+}
+
+SmartOfflineTestSuite.prototype.testFrequencyPriority = function() {
+    const highUsage = { url: "/test", count: 5, lastAccessed: Date.now() }
+    const result = isHighPriority(highUsage, "/test", this.config)
+    this.results.push({ name: "Frequency Priority", passed: result, message: result ? "High frequency works" : "Frequency check failed" })
+}
+
+SmartOfflineTestSuite.prototype.printResults = function() {
+    console.info("\n========================================")
+    console.info("  SmartOffline SDK Test Results")
+    console.info("========================================\n")
+    for (const result of this.results) {
+        console.info((result.passed ? "✅" : "❌") + " " + result.name + ": " + result.message)
+    }
+}
+
+// CacheInspector class
+function CacheInspector() {}
+
+CacheInspector.prototype.getCachedItems = async function() {
+    try {
+        const cache = await caches.open("smart-offline-cache-v2")
+        const keys = await cache.keys()
+        const items = []
+        for (const request of keys) {
+            const response = await cache.match(request)
+            if (response) {
+                items.push({
+                    url: request.url,
+                    size: parseInt(response.headers.get("content-length") || "0", 10),
+                    contentType: response.headers.get("content-type") || "unknown",
+                })
+            }
+        }
+        return items
+    } catch {
+        return []
+    }
+}
+
+CacheInspector.prototype.showAll = async function() {
+    const items = await this.getCachedItems()
+    console.info("\n🔍 SmartOffline Cache Inspector")
+    console.info("📦 Cached Items (" + items.length + "):")
+    console.table(items)
+}
+
+async function runSmartOfflineTests(config) {
+    const suite = new SmartOfflineTestSuite(config)
+    const results = await suite.runAll()
+    suite.printResults()
+    return results
+}
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+const SmartOffline = {
+    setup: setupSmartOffline,
+    init,
+    updateConfig,
+    getConfig,
+    isReady: isSmartOfflineReady,
+    getRegistration: getServiceWorkerRegistration,
+    on,
+    off,
+    clearCache: clearAllCache,
+    getStats: getCacheStats,
+    getCacheLogs,
+    clearCacheLogs,
+    forceUpdate,
+    uninstall,
+}
+
+module.exports = {
+    SmartOffline,
+    setupSmartOffline,
+    updateConfig,
+    getConfig,
+    isSmartOfflineReady,
+    getServiceWorkerRegistration,
+    on,
+    off,
+    clearAllCache,
+    getCacheStats,
+    getCacheLogs,
+    clearCacheLogs,
+    forceUpdate,
+    uninstall,
+    init,
+    matchesPattern,
+    isHighPriority,
+    shouldCacheUrl,
+    SmartOfflineTestSuite,
+    CacheInspector,
+    runSmartOfflineTests,
+}
+
+module.exports.default = SmartOffline