react-tab-refresh 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [TAIJUL AMAN]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,362 @@
+# react-tab-refresh
+
+**Stop the Memory Bloat** — Automatically prune and re-hydrate your long-lived React apps to keep the browser fast.
+
+[![npm version](https://img.shields.io/npm/v/react-tab-refresh.svg)](https://www.npmjs.com/package/react-tab-refresh)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/react-tab-refresh)](https://bundlephobia.com/package/react-tab-refresh)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 📋 The Problem
+
+In 2026, users keep tabs open for **weeks**. Even with optimized code, DOM nodes, event listeners, and JS heaps grow over time. This leads to:
+
+- **Tab Crashing**: Browser kills the process due to high memory usage
+- **System Slowdown**: Your app slows down the user's entire OS
+- **Stale Data**: Background tabs show data from 3 days ago
+
+## ✨ The Solution
+
+`react-tab-refresh` monitors your app's health. When a tab is hidden and exceeds memory limits or inactivity timers:
+
+1. **Serializes** your essential state to sessionStorage
+2. **Unmounts** the entire heavy React tree (freeing the heap)
+3. **Re-mounts** and restores everything instantly when the user returns
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install react-tab-refresh
+# or
+yarn add react-tab-refresh
+# or
+pnpm add react-tab-refresh
+```
+
+### 1. Wrap Your App
+
+```tsx
+import { PruneProvider } from 'react-tab-refresh';
+
+function App() {
+  return (
+    <PruneProvider config={{ pruneAfter: '30m' }}>
+      <MainDashboard />
+    </PruneProvider>
+  );
+}
+```
+
+### 2. Mark "Essential" State
+
+Replace `useState` with `usePrunableState` for data that must survive the pruning process.
+
+```tsx
+import { usePrunableState } from 'react-tab-refresh';
+
+function SearchComponent() {
+  // This state will be saved to sessionStorage before the component is unmounted
+  // and restored automatically upon return.
+  const [results, setResults] = usePrunableState('search_results', []);
+  const [query, setQuery] = usePrunableState('search_query', '');
+
+  return (
+    <div>
+      <input
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        placeholder="Search..."
+      />
+      {results.map((result) => (
+        <div key={result.id}>{result.title}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+That's it! Your app will now automatically prune and rehydrate.
+
+---
+
+## 📚 API Reference
+
+### `<PruneProvider>`
+
+The main provider component that wraps your app.
+
+```tsx
+<PruneProvider
+  config={{
+    pruneAfter: '30m',              // When to prune (default: 30 minutes)
+    maxMemoryMb: 600,               // Memory threshold (Chrome only)
+    enableMemoryMonitoring: false,  // Enable memory-based pruning
+    maxDomNodes: 10000,             // DOM node threshold
+    onPrune: () => {},              // Callback before pruning
+    onRehydrate: () => {},          // Callback after rehydration
+    debug: false,                   // Enable debug logging
+  }}
+  placeholder={<LoadingScreen />}   // Show during rehydration
+>
+  <App />
+</PruneProvider>
+```
+
+#### Config Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pruneAfter` | `string \| number` | `'30m'` | Inactivity time before pruning. Supports: `'30m'`, `'1h'`, `'2d'`, or milliseconds |
+| `maxMemoryMb` | `number` | `undefined` | Memory threshold in MB (Chrome only) |
+| `enableMemoryMonitoring` | `boolean` | `false` | Enable memory-based pruning |
+| `maxDomNodes` | `number` | `undefined` | Maximum DOM nodes before pruning |
+| `onPrune` | `() => void \| Promise<void>` | `undefined` | Callback before pruning (for cleanup) |
+| `onRehydrate` | `() => void \| Promise<void>` | `undefined` | Callback after rehydration (for reconnection) |
+| `debug` | `boolean` | `false` | Enable debug logging |
+
+### `usePrunableState()`
+
+Drop-in replacement for `useState` with automatic persistence.
+
+```tsx
+const [state, setState] = usePrunableState(key, initialValue, options);
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `key` | `string` | Unique storage key |
+| `initialValue` | `T` | Initial value (used if no stored value) |
+| `options` | `PrunableStateOptions<T>` | Optional configuration |
+
+#### Options
+
+```tsx
+interface PrunableStateOptions<T> {
+  serialize?: (value: T) => string;        // Custom serializer
+  deserialize?: (value: string) => T;      // Custom deserializer
+  validate?: (value: T) => boolean;        // Validate restored data
+  ttl?: number;                            // Time-to-live in ms
+  onExpired?: () => void;                  // Callback when data expires
+  debug?: boolean;                         // Enable debug logging
+}
+```
+
+#### Example with Options
+
+```tsx
+const [user, setUser] = usePrunableState(
+  'current_user',
+  { id: null, name: '' },
+  {
+    validate: (value) => value.id !== null,
+    ttl: 24 * 60 * 60 * 1000, // 24 hours
+    onExpired: () => fetchFreshUserData(),
+  }
+);
+```
+
+### `usePruningState()`
+
+Access pruning state and utilities.
+
+```tsx
+const {
+  isPruned,           // Whether app is currently pruned
+  isRehydrating,      // Whether app is rehydrating
+  metrics,            // Current metrics (inactiveMs, memoryMb, etc.)
+  forceRehydrate,     // Force immediate rehydration
+  registerCleanup,    // Register cleanup function
+  unregisterCleanup,  // Unregister cleanup function
+} = usePruningState();
+```
+
+#### Example: WebSocket Cleanup
+
+```tsx
+import { usePruningState } from 'react-tab-refresh';
+
+function ChatComponent() {
+  const { registerCleanup } = usePruningState();
+
+  useEffect(() => {
+    const ws = new WebSocket('wss://api.example.com/chat');
+
+    // Register cleanup to close WebSocket before pruning
+    registerCleanup('websocket', () => {
+      ws.close();
+    });
+
+    return () => ws.close();
+  }, [registerCleanup]);
+
+  return <div>Chat UI</div>;
+}
+```
+
+---
+
+## ⚠️ Common Issues & Solutions
+
+### Issue: State Loss
+
+**Cause**: Non-serializable data (Functions, Classes) in state.
+
+**Solution**: Use the `transform` option or avoid storing non-serializable data.
+
+```tsx
+// ❌ Bad: Functions can't be serialized
+const [handler, setHandler] = usePrunableState('handler', () => {});
+
+// ✅ Good: Store serializable data only
+const [config, setConfig] = usePrunableState('config', { url: '/api' });
+```
+
+### Issue: Flicker on Return
+
+**Cause**: Re-mounting large trees takes time.
+
+**Solution**: Use the `placeholder` prop to show a skeleton screen.
+
+```tsx
+<PruneProvider
+  config={{ pruneAfter: '30m' }}
+  placeholder={<SkeletonScreen />}
+>
+  <App />
+</PruneProvider>
+```
+
+### Issue: WebSocket Drop
+
+**Cause**: Unmounting closes active connections.
+
+**Solution**: Use `registerCleanup` to gracefully close and `onRehydrate` to reconnect.
+
+```tsx
+const { registerCleanup } = usePruningState();
+
+useEffect(() => {
+  const ws = new WebSocket(url);
+
+  registerCleanup('websocket', () => {
+    ws.close();
+  });
+
+  return () => ws.close();
+}, []);
+```
+
+### Issue: Quota Exceeded
+
+**Cause**: SessionStorage has a 5-10MB limit.
+
+**Solution**: Reduce state size or use selective persistence.
+
+```tsx
+// Only persist essential data
+const [largeData, setLargeData] = useState([]); // Not persisted
+const [essentialData, setEssentialData] = usePrunableState('essential', {}); // Persisted
+```
+
+---
+
+## 🎯 Advanced Usage
+
+### Custom Serialization
+
+For complex data types (Dates, Maps, Sets):
+
+```tsx
+const [timestamp, setTimestamp] = usePrunableState(
+  'timestamp',
+  new Date(),
+  {
+    serialize: (date) => date.toISOString(),
+    deserialize: (str) => new Date(str),
+  }
+);
+```
+
+### Conditional Pruning
+
+```tsx
+const { isPruned, forceRehydrate } = usePruningState();
+
+if (isPruned && userClickedButton) {
+  forceRehydrate();
+}
+```
+
+### Monitoring Metrics
+
+```tsx
+const { metrics } = usePruningState();
+
+console.log(`Inactive for: ${metrics.inactiveMs}ms`);
+console.log(`Memory usage: ${metrics.memoryMb}MB`);
+console.log(`DOM nodes: ${metrics.domNodes}`);
+```
+
+---
+
+## 🧪 Testing
+
+The package includes comprehensive tests. Run them with:
+
+```bash
+npm test
+```
+
+For coverage:
+
+```bash
+npm run test:coverage
+```
+
+---
+
+## 📦 Bundle Size
+
+`react-tab-refresh` is designed to be lightweight:
+
+- **Minified**: ~8KB
+- **Gzipped**: ~3KB
+
+---
+
+## 🌐 Browser Support
+
+| Feature | Chrome | Firefox | Safari | Edge |
+|---------|--------|---------|--------|------|
+| Page Visibility API | ✅ | ✅ | ✅ | ✅ |
+| SessionStorage | ✅ | ✅ | ✅ | ✅ |
+| Memory Monitoring | ✅ | ❌ | ❌ | ✅ |
+
+**Note**: Memory monitoring (`performance.memory`) is Chrome/Edge only. The package gracefully degrades to time-based pruning on other browsers.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+---
+
+## 📄 License
+
+MIT © TAIJULAMAN
+
+---
+
+## 🙏 Acknowledgments
+
+Inspired by the real-world problem of tab bloat in modern web applications. Built for the 2026 web where apps live in tabs for weeks.
+
+---

package/dist/__tests__/setup.d.ts

@@ -0,0 +1,2 @@
+import '@testing-library/jest-dom';
+//# sourceMappingURL=setup.d.ts.map

package/dist/__tests__/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/__tests__/setup.ts"],"names":[],"mappings":"AAEA,OAAO,2BAA2B,CAAC"}

package/dist/components/PruneProvider.d.ts

@@ -0,0 +1,3 @@
+import type { PruneProviderProps } from '../types';
+export declare function PruneProvider({ children, config, placeholder, }: PruneProviderProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=PruneProvider.d.ts.map

package/dist/components/PruneProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PruneProvider.d.ts","sourceRoot":"","sources":["../../src/components/PruneProvider.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAuC,MAAM,UAAU,CAAC;AAexF,wBAAgB,aAAa,CAAC,EAC1B,QAAQ,EACR,MAAW,EACX,WAAW,GACd,EAAE,kBAAkB,kDAuMpB"}

package/dist/context/PruningContext.d.ts

@@ -0,0 +1,3 @@
+import type { PruningContextValue } from '../types';
+export declare const PruningContext: import("react").Context<PruningContextValue | null>;
+//# sourceMappingURL=PruningContext.d.ts.map

package/dist/context/PruningContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PruningContext.d.ts","sourceRoot":"","sources":["../../src/context/PruningContext.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAKpD,eAAO,MAAM,cAAc,qDAAkD,CAAC"}

package/dist/core/InactivityMonitor.d.ts

@@ -0,0 +1,26 @@
+import type { MonitorConfig, MonitorEvent, MonitorCallback, PruningMetrics } from '../types';
+export declare class InactivityMonitor {
+    private config;
+    private logger;
+    private listeners;
+    private intervalId;
+    private hiddenAt;
+    private isRunning;
+    constructor(config: Partial<MonitorConfig>);
+    start(): void;
+    stop(): void;
+    on(event: MonitorEvent, callback: MonitorCallback): void;
+    off(event: MonitorEvent, callback: MonitorCallback): void;
+    getCurrentMetrics(): PruningMetrics;
+    private checkThresholds;
+    private emit;
+    private setupVisibilityListener;
+    private removeVisibilityListener;
+    private handleVisibilityChange;
+    private getInactiveTime;
+    private startPolling;
+    private stopPolling;
+    updateConfig(config: Partial<MonitorConfig>): void;
+    reset(): void;
+}
+//# sourceMappingURL=InactivityMonitor.d.ts.map

package/dist/core/InactivityMonitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InactivityMonitor.d.ts","sourceRoot":"","sources":["../../src/core/InactivityMonitor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,aAAa,EACb,YAAY,EACZ,eAAe,EACf,cAAc,EACjB,MAAM,UAAU,CAAC;AAalB,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,SAAS,CAAsD;IACvE,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC;IAsB1C,KAAK,IAAI,IAAI;IAyBb,IAAI,IAAI,IAAI;IAeZ,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI;IAUxD,GAAG,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI;IAUzD,iBAAiB,IAAI,cAAc;IAiBnC,OAAO,CAAC,eAAe;IAkDvB,OAAO,CAAC,IAAI;IAgBZ,OAAO,CAAC,uBAAuB;IAO/B,OAAO,CAAC,wBAAwB;IAUhC,OAAO,CAAC,sBAAsB,CAU5B;IAKF,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,WAAW;IAUnB,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI;IAQlD,KAAK,IAAI,IAAI;CAIhB"}

package/dist/hooks/usePrunableState.d.ts

@@ -0,0 +1,5 @@
+import type { PrunableStateOptions } from '../types';
+export declare function usePrunableState<T>(key: string, initialValue: T, options?: PrunableStateOptions<T>): [T, (value: T | ((prev: T) => T)) => void];
+export declare function useClearPrunableState(): (key: string) => void;
+export declare function useStorageUsage(): import("../types").StorageUsage;
+//# sourceMappingURL=usePrunableState.d.ts.map

package/dist/hooks/usePrunableState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePrunableState.d.ts","sourceRoot":"","sources":["../../src/hooks/usePrunableState.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAQrD,wBAAgB,gBAAgB,CAAC,CAAC,EAC9B,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,EACf,OAAO,GAAE,oBAAoB,CAAC,CAAC,CAAM,GACtC,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CA4G5C;AAKD,wBAAgB,qBAAqB,UAIvB,MAAM,UAKnB;AAKD,wBAAgB,eAAe,oCAa9B"}

package/dist/hooks/usePruningState.d.ts

@@ -0,0 +1,3 @@
+import type { PruningContextValue } from '../types';
+export declare function usePruningState(): PruningContextValue;
+//# sourceMappingURL=usePruningState.d.ts.map

package/dist/hooks/usePruningState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePruningState.d.ts","sourceRoot":"","sources":["../../src/hooks/usePruningState.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,wBAAgB,eAAe,IAAI,mBAAmB,CAerD"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { PruneProvider } from './components/PruneProvider';
+export { usePrunableState, useClearPrunableState, useStorageUsage } from './hooks/usePrunableState';
+export { usePruningState } from './hooks/usePruningState';
+export type { PrunableStateOptions, PruneProviderConfig, PruneProviderProps, PruningContextValue, PruningMetrics, StorageAdapter, StorageUsage, } from './types';
+export { createStorageAdapter } from './utils/StorageManager';
+export { InactivityMonitor } from './core/InactivityMonitor';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAG3D,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AACpG,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG1D,YAAY,EACR,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,YAAY,GACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC"}