@ak--47/dungeon-master 1.2.0 → 1.2.2

package/lib/utils/utils.js

@@ -1314,15 +1314,7 @@ function person(userId, bornDaysAgo = 30, isAnonymous = false, hasAvatar = false
 
 	if (!hasAnonIds) delete user.anonymousIds;
 
-	//session Ids
-	if (hasSessionIds) {
-		const sessionSize = integer(5, 30);
-		for (let i = 0; i < sessionSize; i++) {
-			const sessionId = [uid(5), uid(5), uid(5), uid(5)].join("-");
-			user.sessionIds.push(sessionId);
-		}
-	}
-
+	// Session IDs are now assigned post-hoc in user-loop.js based on temporal gaps
 	if (!hasSessionIds) delete user.sessionIds;
 
 	return user;
@@ -1436,6 +1428,131 @@ function deepClone(thing, opts) {
 };
 
 
+/**
+ * Generates a session ID in the standard format
+ * @returns {string} Session ID like "xxxxx-xxxxx-xxxxx-xxxxx"
+ */
+function generateSessionId() {
+	return [uid(5), uid(5), uid(5), uid(5)].join("-");
+}
+
+/**
+ * Redistributes events into temporal clusters (sessions).
+ *
+ * Algorithm:
+ * 1. Sort events by time
+ * 2. Determine number of sessions (total events / avg events per session)
+ * 3. Generate session anchor times using TimeSoup
+ * 4. Assign events round-robin to sessions
+ * 5. Within each session, retime events with tight spacing (5-300s apart)
+ * 6. Regenerate insert_ids for retimed events
+ * 7. Re-sort by time
+ *
+ * Mutates events in place. Does NOT assign session_id (call assignSessionIds after).
+ *
+ * @param {Object[]} events - Array of event objects with .time (ISO string)
+ * @param {number} timeoutMinutes - Session timeout in minutes (used to determine intra-session spacing)
+ * @param {Object} soupParams - Parameters for TimeSoup anchor generation
+ */
+function bunchIntoSessions(events, timeoutMinutes, soupParams) {
+	if (events.length < 2) return;
+
+	const chance = getChance();
+	const { earliestTime, latestTime, peaks, deviation, mean,
+		dayOfWeekWeights, hourOfDayWeights, timeShiftSeconds, maxTime } = soupParams;
+
+	// Sort by time first
+	events.sort((a, b) => a.time < b.time ? -1 : a.time > b.time ? 1 : 0);
+
+	// Determine number of sessions: target 3-8 events per session
+	const eventsPerSession = chance.integer({ min: 3, max: 8 });
+	const numSessions = Math.max(1, Math.ceil(events.length / eventsPerSession));
+
+	// Generate session anchor times using TimeSoup
+	const anchors = [];
+	for (let i = 0; i < numSessions; i++) {
+		const soupTime = TimeSoup(earliestTime, latestTime, peaks, deviation, mean,
+			dayOfWeekWeights, hourOfDayWeights, timeShiftSeconds);
+		anchors.push(soupTime + timeShiftSeconds); // shifted to present time
+	}
+	anchors.sort((a, b) => a - b);
+
+	// Distribute events across sessions round-robin (preserving original order → temporal order)
+	const sessionBuckets = anchors.map(() => []);
+	for (let i = 0; i < events.length; i++) {
+		const bucketIndex = Math.min(i % numSessions, numSessions - 1);
+		sessionBuckets[bucketIndex].push(events[i]);
+	}
+
+	// Retime events within each session
+	let writeIndex = 0;
+	for (let s = 0; s < numSessions; s++) {
+		const bucket = sessionBuckets[s];
+		if (bucket.length === 0) continue;
+
+		let currentTime = anchors[s];
+		for (let e = 0; e < bucket.length; e++) {
+			const ev = bucket[e];
+			const clampedTime = Math.min(currentTime, maxTime);
+
+			ev.time = dayjs.unix(clampedTime).toISOString();
+			// Regenerate insert_id to match new time
+			const distinctId = ev.user_id || ev.device_id || ev.distinct_id || '';
+			ev.insert_id = quickHash(`${ev.event}-${ev.time}-${distinctId}`);
+
+			if (currentTime > maxTime) {
+				ev._drop = true;
+			}
+
+			// Advance time within session: 5-300 seconds (5s to 5min)
+			currentTime += chance.integer({ min: 5, max: 300 });
+		}
+	}
+
+	// Re-sort by time
+	events.sort((a, b) => a.time < b.time ? -1 : a.time > b.time ? 1 : 0);
+}
+
+/**
+ * Assigns session IDs to a chronologically sorted array of events.
+ * A new session starts when:
+ *   - Gap between consecutive events exceeds timeoutMinutes
+ *   - Session duration exceeds 24 hours
+ *
+ * Events MUST be sorted by time before calling this function.
+ * Mutates events in place (adds session_id property).
+ *
+ * @param {Object[]} events - Sorted array of event objects with .time (ISO string)
+ * @param {number} timeoutMinutes - Session timeout in minutes (default 30)
+ * @returns {Object[]} Same array, with session_id added to each event
+ */
+function assignSessionIds(events, timeoutMinutes = 30) {
+	if (!events.length) return events;
+
+	const timeoutMs = timeoutMinutes * 60 * 1000;
+	const maxSessionMs = 24 * 60 * 60 * 1000;
+
+	let currentSessionId = generateSessionId();
+	let sessionStartMs = new Date(events[0].time).getTime();
+	let lastEventMs = sessionStartMs;
+
+	for (const event of events) {
+		const eventMs = new Date(event.time).getTime();
+		const gapFromLast = eventMs - lastEventMs;
+		const sessionDuration = eventMs - sessionStartMs;
+
+		if (gapFromLast > timeoutMs || sessionDuration > maxSessionMs) {
+			currentSessionId = generateSessionId();
+			sessionStartMs = eventMs;
+		}
+
+		event.session_id = currentSessionId;
+		lastEventMs = eventMs;
+	}
+
+	return events;
+}
+
 export {
 	pick,
 	date,
@@ -1486,4 +1603,7 @@ export {
 	wrapFunc,
 	bytesHuman,
 	formatDuration,
+	generateSessionId,
+	assignSessionIds,
+	bunchIntoSessions,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ak--47/dungeon-master",
-	"version": "1.2.0",
+	"version": "1.2.2",
 	"description": "generate fancy datasets",
 	"type": "module",
 	"main": "index.js",
@@ -66,7 +66,7 @@
 		"dotenv": "^16.4.5",
 		"hyparquet-writer": "^0.6.1",
 		"mixpanel": "^0.18.0",
-		"mixpanel-import": "^3.2.8",
+		"mixpanel-import": "^3.2.9",
 		"p-limit": "^3.1.0",
 		"pino": "^9.0.0",
 		"pino-pretty": "^11.0.0",

package/types.d.ts

@@ -72,8 +72,10 @@ export interface Dungeon {
     verbose?: boolean;
     /** If true, users get anonymous device IDs in addition to distinct_id. */
     hasAnonIds?: boolean;
-    /** If true, users get session IDs attached to events. */
+    /** If true, users get session IDs attached to events based on temporal clustering. */
     hasSessionIds?: boolean;
+    /** Session timeout in minutes. Events with gaps exceeding this start a new session. Default: 30. Only used when hasSessionIds is true. */
+    sessionTimeout?: number;
     /** If true, auto-generates funnels from the events array in addition to any explicit funnels. */
     alsoInferFunnels?: boolean;
     /** Restrict all location data to a single country (e.g., "US", "GB"). */
@@ -231,8 +233,8 @@ export interface hookArrayOptions<T> {
  * an enriched array is an array that has a hookPush method that can be used to transform-then-push items into the array
  */
 export interface HookedArray<T> extends Array<T> {
-    hookPush: (item: T | T[], ...meta: any[]) => any;
-    flush: () => void;
+    hookPush: (item: T | T[], ...meta: any[]) => Promise<any>;
+    flush: () => Promise<void>;
     getWriteDir: () => string;
     getWritePath: () => string;
     [key: string]: any;