PD Cooldown

中文文档 | English Documentation

Features

• 🚀 High Performance: Uses synchronous locks to ensure thread safety
• 🎯 Ease of Use: Clean API design with multiple usage patterns
• 🔧 Configurable: Supports custom logging and error handling
• 🎨 UI Components: Built-in debounce and throttle button widgets
• 📦 Modular: Clear code architecture, easy to maintain and extend

Installation

Add the dependency to pubspec.yaml:

dependencies:
  pd_cooldown: ^0.3.1

Then run:

flutter pub get

Quick Start

1. Import the package

import 'package:pd_cooldown/pd_cooldown.dart';

2. Basic Usage

Debounce/Throttle Core Functionality

// Create a debounce/throttle instance
final cooldown = PDCooldown.withDefaults(
  cooldownDuration: const Duration(seconds: 3),
);

// Execute debounce/throttle operation
final result = await cooldown.execute<String>(() async {
  // Your async operation
  await Future.delayed(const Duration(milliseconds: 500));
  return 'Operation completed';
}, onCooldown: (remaining) {
  print('Cooldown in progress, remaining time: ${remaining.inSeconds} seconds');
});

if (result != null) {
  print('Execution result: $result');
} else {
  print('Operation was cooldown-limited');
}

UI Components Usage

// Throttle Button - Responds immediately to first click, ignores subsequent clicks during cooldown
PDThrottleButton(
  buttonType: PDButtonType.elevated,
  debounceDuration: const Duration(seconds: 2),
  onPressed: () {
    print('Throttle button clicked');
  },
  child: const Text('Throttle Button'),
)

// Debounce Button - Delays response, only triggers when no new clicks occur within specified time
PDDebounceButton(
  buttonType: PDButtonType.elevated,
  debounceDuration: const Duration(milliseconds: 800),
  onPressed: () {
    print('Debounce button clicked');
  },
  child: const Text('Debounce Button'),
)

Advanced Usage

Custom Logging and Error Handling

final cooldown = PDCooldown.withCallbacks(
  cooldownDuration: const Duration(seconds: 5),
  onDebug: (message) => print('Debug: $message'),
  onError: (message) => print('Error: $message'),
  onErrorHandler: (error, stackTrace, prefix) {
    // Custom error handling logic
    print('$prefix: $error');
  },
);

Check Cooldown Status

// Check if in cooldown
if (cooldown.isInCooldown()) {
  final remaining = cooldown.getRemainingCooldown();
  print('Need to wait ${remaining.inSeconds} more seconds');
}

// Reset cooldown state
cooldown.reset();

API Documentation

PDCooldown

The core debounce/throttle class, providing the following methods:

Constructors

• PDCooldown() - Basic constructor
• PDCooldown.withDefaults() - Uses default logging and error handling
• PDCooldown.withCallbacks() - Uses custom callbacks

Main Methods

• execute<T>() - Execute debounce/throttle operation
• isInCooldown() - Check if currently in cooldown
• getRemainingCooldown() - Get remaining cooldown time
• reset() - Reset cooldown state

UI Components

PDThrottleButton

Throttle button component, main properties:

• onPressed - Click callback
• child - Child widget
• debounceDuration - Cooldown duration
• buttonType - Button type
• cooldownOpacity - Opacity during cooldown

PDDebounceButton

Debounce button component, main properties:

• onPressed - Click callback
• child - Child widget
• debounceDuration - Debounce duration
• buttonType - Button type
• debounceOpacity - Opacity during debounce

Examples

Check the example directory for complete usage examples.

Contributing

Issues and Pull Requests are welcome!

License

This project is licensed under the MIT License.