🛡️ Cache Shield SDK

Clear browser caches from client-side with ease. Service Workers, Storage, IndexedDB, Cookies & more.

✨ Features

• 🧹 Clear All Cache Types - Service Workers, Cache API, localStorage, sessionStorage, IndexedDB, Cookies
• ⚡ Lightweight - ~4KB gzipped, zero dependencies
• 🎯 Selective Clearing - Target specific caches, preserve essential data
• 🛡️ Mobile Optimized - BfCache protection & Smart Reloading for iOS/Android
• 🔌 Framework Plugins - React, Vue, Svelte, Preact
• 📦 TypeScript - Full type definitions included
• 🌐 Universal - Works in any browser environment

📦 Installation

npm install cache-shield-sdk
# or
yarn add cache-shield-sdk
# or
pnpm add cache-shield-sdk

📂 Examples

Check out the examples directory for complete working demos:

• Basic - Vanilla JS implementation
• React - React Hook & Component usage
• Vue 3 - Vue Composable & Plugin usage

🚀 Quick Start

Basic Usage

import CacheShield from 'cache-shield-sdk';

// Create instance
const shield = new CacheShield();

// Clear all caches
await shield.clear();

// Clear specific types
await shield.clearServiceWorkers();
await shield.clearLocalStorage();
await shield.clearCookies();

One-liner

import { clearCache } from 'cache-shield-sdk';

await clearCache(); // Clears everything!

With Options

const shield = new CacheShield({
  targets: ['localStorage', 'sessionStorage', 'cookies'],
  cookies: {
    preserveEssential: true,
    essentialCookies: ['auth_token', 'csrf']
  },
  storage: {
    preserveKeys: ['user_preferences']
  },
  debug: true,
  autoReload: true
});

const result = await shield.clear();
console.log(`Cleared ${result.cleared.length} cache types`);

⚛️ React

import { CacheShieldProvider, useCacheShield, ClearCacheButton } from 'cache-shield-sdk/react';

// Wrap your app
function App() {
  return (
    <CacheShieldProvider config={{ debug: true }}>
      <MyComponent />
    </CacheShieldProvider>
  );
}

// Use the hook
function MyComponent() {
  const { clear, isClearing, lastResult } = useCacheShield();

  return (
    <div>
      <button onClick={() => clear()} disabled={isClearing}>
        {isClearing ? 'Clearing...' : 'Clear Cache'}
      </button>
      
      {/* Or use the built-in button */}
      <ClearCacheButton onSuccess={(result) => console.log(result)} />
    </div>
  );
}

💚 Vue 3

// main.ts
import { createApp } from 'vue';
import { CacheShieldPlugin } from 'cache-shield-sdk/vue';

const app = createApp(App);
app.use(CacheShieldPlugin, { debug: true });
app.mount('#app');

// Component
<script setup>
import { useCacheShield } from 'cache-shield-sdk/vue';

const { clear, isClearing, capabilities } = useCacheShield();
</script>

<template>
  <button @click="clear()" :disabled="isClearing">
    {{ isClearing ? 'Clearing...' : 'Clear Cache' }}
  </button>
</template>

🧡 Svelte

// App.svelte
<script>
  import { onMount } from 'svelte';
  import { createCacheShieldStore, setCacheShield } from 'cache-shield-sdk/svelte';
  
  const store = createCacheShieldStore({ debug: true });
  setCacheShield(store);
</script>

<slot />

// Component.svelte
<script>
  import { useCacheShield } from 'cache-shield-sdk/svelte';
  const { clear, isClearing } = useCacheShield();
</script>

<button on:click={() => clear()} disabled={$isClearing}>
  {$isClearing ? 'Clearing...' : 'Clear Cache'}
</button>

⚛️ Preact

import { CacheShieldProvider, useCacheShield } from 'cache-shield-sdk/preact';

function App() {
  return (
    <CacheShieldProvider config={{ debug: true }}>
      <MyComponent />
    </CacheShieldProvider>
  );
}

🌐 CDN / Browser

<script src="https://unpkg.com/cache-shield-sdk"></script>
<script>
  const shield = new CacheShield.default();
  shield.clear().then(result => {
    console.log('Cache cleared!', result);
  });
</script>

📋 API Reference

CacheShield

Constructor Options

Option	Type	Default	Description
targets	CacheType[]	['all']	Cache types to clear
include	(string | RegExp)[]	[]	Only clear matching patterns
exclude	(string | RegExp)[]	[]	Skip matching patterns
cookies	CookieOptions	{}	Cookie-specific options
storage	StorageOptions	{}	Storage-specific options
indexedDB	IndexedDBOptions	{}	IndexedDB-specific options
debug	boolean	false	Enable debug logging
autoReload	boolean	false	Reload after clearing
preventBfCache	boolean	false	Force reload on back button (iOS fix)
hooks	CacheShieldHooks	{}	Lifecycle callbacks

Methods

Method	Returns	Description
clear(options?)	Promise<ClearResult>	Clear all targeted caches
clearServiceWorkers()	Promise<CacheTypeResult>	Clear only Service Workers
clearCacheAPI()	Promise<CacheTypeResult>	Clear only Cache API
clearLocalStorage()	Promise<CacheTypeResult>	Clear only localStorage
clearSessionStorage()	Promise<CacheTypeResult>	Clear only sessionStorage
clearIndexedDB()	Promise<CacheTypeResult>	Clear only IndexedDB
clearCookies()	Promise<CacheTypeResult>	Clear only cookies
hardReload()	void	Force reload bypassing cache
clearAndReload(options?)	Promise<void>	Clear then reload
getStorageEstimate()	Promise<StorageEstimate>	Get storage usage
getCapabilities()	Capabilities	Check browser support

Types

type CacheType = 
  | 'all'
  | 'serviceWorker'
  | 'cacheAPI'
  | 'localStorage'
  | 'sessionStorage'
  | 'indexedDB'
  | 'cookies';

interface ClearResult {
  success: boolean;
  cleared: CacheTypeResult[];
  failed: CacheTypeResult[];
  timestamp: number;
  duration: number;
}

🎯 Common Use Cases

PWA Update Handler

const shield = new CacheShield({
  targets: ['serviceWorker', 'cacheAPI'],
  hooks: {
    onAfterClear: () => {
      // Show "New version available" toast
      showUpdateNotification();
    }
  }
});

// When user clicks "Update"
await shield.clearAndReload();

Logout Cleanup

async function logout() {
  await shield.clear({
    targets: ['localStorage', 'sessionStorage', 'cookies', 'indexedDB'],
    cookies: {
      preserveEssential: false // Clear everything including auth
    }
  });
  
  window.location.href = '/login';
}

Debug Mode

const shield = new CacheShield({
  debug: true,
  hooks: {
    onProgress: ({ current, percentage }) => {
      console.log(`Clearing ${current}: ${percentage}%`);
    }
  }
});

📊 Browser Support

Feature	Chrome	Firefox	Safari	Edge
Service Workers	✅ 40+	✅ 44+	✅ 11.1+	✅ 17+
Cache API	✅ 40+	✅ 39+	✅ 11.1+	✅ 16+
localStorage	✅ All	✅ All	✅ All	✅ All
IndexedDB	✅ 23+	✅ 10+	✅ 10+	✅ 12+

📄 License

MIT Suneel Kumar