LocalStorage Watcher

A powerful and efficient localStorage watcher that helps you monitor localStorage changes across browser tabs.

一个强大高效的 localStorage 监听器，帮助你监控跨浏览器标签页的 localStorage 变化。

Features 特性

• 🔄 Real-time localStorage change detection

  实时检测 localStorage 变化

• 🌐 Cross-tab synchronization

  跨标签页同步

• ⚡️ Debounce support for high-frequency updates

  支持高频更新防抖

• 🛡️ Type-safe with TypeScript

  TypeScript 类型安全

• 🎯 Single instance pattern

  单例模式

Installation 安装

npm install localstorage-watcher-powerful

Usage 使用方法

Basic Usage 基本用法

import LocalStorageWatcher from 'localstorage-watcher-powerful';

// Initialize the watcher
// 初始化监听器
LocalStorageWatcher.init();

// Watch for changes to a specific key
// 监听特定 key 的变化
LocalStorageWatcher.watch('user-preferences', (newValue, oldValue) => {
  console.log('New value:', newValue);
  console.log('Old value:', oldValue);
});

// Set a value (will trigger watchers)
// 设置值（会触发监听器）
localStorage.setItem('user-preferences', JSON.stringify({ theme: 'dark' }));

Debounced Watching 防抖监听

// Watch with debounce (300ms default)
// 使用防抖监听（默认 300ms）
LocalStorageWatcher.watchWithDebounce('frequently-updated-key', (newValue, oldValue) => {
  console.log('Debounced update:', newValue);
}, 500); // Optional custom delay 可选的自定义延迟

Debug Mode 调试模式

// Enable debug logging
// 启用调试日志
LocalStorageWatcher.enableDebug();

Cleanup 清理

// Remove a specific watcher
// 移除特定的监听器
LocalStorageWatcher.unwatch('user-preferences');

// Clear all watchers
// 清除所有监听器
LocalStorageWatcher.clearWatchers();

// Completely destroy the watcher
// 完全销毁监听器
LocalStorageWatcher.destroy();

API Reference API 参考

Methods 方法

init()

Initializes the localStorage watcher. Must be called before using other methods. 初始化 localStorage 监听器。在使用其他方法前必须调用。

watch(key: string, handler: (newValue: any, oldValue: any) => void)

Watches for changes to a specific localStorage key. 监听特定 localStorage 键的变化。

watchWithDebounce(key: string, handler: (newValue: any, oldValue: any) => void, delay?: number)

Watches for changes with debounce support. 使用防抖方式监听变化。

unwatch(key: string)

Removes the watcher for a specific key. 移除特定键的监听器。

clearWatchers()

Removes all watchers. 移除所有监听器。

destroy()

Completely destroys the watcher instance. 完全销毁监听器实例。

enableDebug()

Enables debug logging. 启用调试日志。

Notes 注意事项

• Values are automatically serialized/deserialized as JSON

  值会自动进行 JSON 序列化/反序列化

• Maximum 10 watchers per key by default

  默认每个键最多支持 10 个监听器

• Works across different browser tabs/windows

  支持跨浏览器标签页/窗口工作

License 许可证

MIT