track library

📦 track Package

Persistent, plug-and-play tools for tracking streaks, counters, histories, activity, and records — all with zero boilerplate.

This package provides ready-to-use services for common time-based progress patterns, including:

  • 🔥 StreakTracker — track streaks over aligned periods (e.g. daily, weekly)
  • 🧾 HistoryTracker — store recent items with optional deduplication
  • 📈 PeriodicCounter — count events per fixed time window (e.g. daily, hourly)
  • ⏳ RolloverCounter — sliding window counters that reset after inactivity
  • 📆 ActivityCounter — detailed time-based analytics over hours, days, months, years

All tools are:

  • Async-safe and isolate-friendly
  • Automatically persisted across app restarts
  • Optimized with optional caching

Usage Example

import 'package:track/track.dart';

final streak = StreakTracker('daily_streak', period: TimePeriod.daily);
await streak.bump();
final count = await streak.currentStreak();

For complete documentation and examples, see the package README.

Classes

ActivityCounter
A utility class for tracking user activity over time across various spans such as hour, day, month, and year. It provides persistent storage and retrieval of activity data, making it suitable for usage statistics, trend analysis, and generating long-term activity reports.
BaseCounterService
An abstract class for tracking integer counters with expiration logic.
BaseTrackerService<T>
An abstract base class for tracking values with expiration logic.
BasicCounter
A simple persistent counter with no expiration or periodic reset.
BestRecord
Manages records, allowing storage and retrieval of the best record.
HistoryTracker<T>
A persisted, FIFO history tracker using a Prf<List<T>>.
PeriodicCounter
A persistent counter that automatically resets at the start of each aligned time period.
RecordEntry
Represents a record entry with a numerical value and a timestamp.
RolloverCounter
RolloverCounter is a persistent counter designed to automatically reset after a specified duration from the last update. This is particularly useful for tracking rolling activity windows, such as "submissions per hour" or "attempts every 10 minutes".
StreakTracker
A persistent streak tracker for managing activity streaks with automatic expiration logic.

Enums

RecordMode
Defines the mode of record tracking.
TimePeriod
Represents different time periods for tracking purposes.
TimeSpan
Enum representing the different spans of activity tracking.

Extensions

PrfListAdapterExtensions on PrfAdapter<List<T>>
Extensions for building a persisted history tracker from any PrfAdapter<List<T>>.
TimePeriodExt on TimePeriod
Extension on TimePeriod to provide additional functionality.