collections/session_clustering_utils library

Gap-based sessionization of timestamped items (roadmap #485).

Groups a flat list of timestamped items into "sessions": runs of items where each consecutive pair is no more than maxGap apart. A new session begins whenever the gap to the previous item exceeds maxGap. This is the classic analytics sessionization used for clickstreams, login activity, GPS tracks, and log bursts — turning a timeline into discrete bouts of activity.

Input may be unsorted; both entry points sort by timestamp first, so the returned sessions are always in chronological order.

Functions

clusterIntoSessions<T>(List<T> items, {required DateTime timestamp(T), required Duration maxGap}) → List<List<T>>

Splits items into chronological sessions, starting a new session whenever the gap between an item and its predecessor exceeds maxGap.

sessionsWithBounds<T>(List<T> items, {required DateTime timestamp(T), required Duration maxGap}) → List<({DateTime end, List<T> items, DateTime start})>

Same sessionization as clusterIntoSessions, but each session is returned as a record carrying its start and end timestamps alongside its items.