# LocalStorageWatcher

**Repository Path**: daojixing/LocalStorageWatcher

## Basic Information

- **Project Name**: LocalStorageWatcher
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-18
- **Last Updated**: 2026-01-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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 安装

```bash
npm install localstorage-watcher-powerful
```

## Usage 使用方法

### Basic Usage 基本用法

```typescript
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 防抖监听

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

### Debug Mode 调试模式

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

### Cleanup 清理

```typescript
// 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