@ak--47/dungeon-master 1.0.0

package/lib/templates/schema.d.ts

@@ -0,0 +1,173 @@
+/**
+ * A "ValueValid" can be:
+ * - A primitive value (string, number, boolean)
+ * - An array of primitives (the system picks one randomly)
+ * - A function call object: { "functionName": "...", "args": [...] }
+ * - An arrow function object: { "functionName": "arrow", "body": "..." }
+ *
+ * This is the building block for all property values in the dungeon.
+ */
+type Primitives = string | number | boolean;
+type FunctionCall = { functionName: string; args?: any[]; body?: string };
+type ValueValid = Primitives | Primitives[] | FunctionCall;
+
+
+/**
+ * The main configuration object for the entire data generation spec, known as a "Dungeon".
+ * This is the high-level object you will be constructing.
+ *
+ * REQUIRED fields: events, funnels, superProps, userProps
+ * OPTIONAL fields: scdProps, groupKeys, groupProps, groupEvents
+ */
+export interface Dungeon {
+    /** REQUIRED: A list of all possible events that can occur in the simulation. */
+    events: EventConfig[];
+
+    /** REQUIRED: A list of event sequences that represent user journeys (e.g., sign-up, purchase). */
+    funnels: Funnel[];
+
+    /** REQUIRED: Properties that are attached to every event for all users. */
+    superProps: Record<string, ValueValid>;
+
+    /** REQUIRED: Properties that define the characteristics of individual users. */
+    userProps: Record<string, ValueValid>;
+
+    /** OPTIONAL: Properties that change for users or groups over time (Slowly Changing Dimensions). Only include when properties explicitly change over time. */
+    scdProps?: Record<string, SCDProp>;
+
+    /** OPTIONAL: Defines group entities (companies, teams). Format: [["group_key", count], ...]. ONLY for B2B/SaaS scenarios. */
+    groupKeys?: [string, number][];
+
+    /** OPTIONAL: Properties for groups defined in groupKeys. ONLY include if groupKeys is defined. */
+    groupProps?: Record<string, Record<string, ValueValid>>;
+
+    /** OPTIONAL: Events attributed to groups on a schedule (e.g., monthly billing). Rarely needed. */
+    groupEvents?: GroupEventConfig[];
+}
+
+
+/**
+ * Defines a single event, its properties, and its likelihood of occurring.
+ *
+ * The "weight" determines relative frequency - an event with weight 10 occurs
+ * roughly 10x more often than an event with weight 1.
+ */
+interface EventConfig {
+    /** REQUIRED: The name of the event (e.g., "Page View", "Add to Cart", "checkout"). */
+    event: string;
+
+    /** OPTIONAL: The relative frequency of this event. Higher numbers = more frequent. Default: 1 */
+    weight?: number;
+
+    /** OPTIONAL: Properties associated with this event. Each property can be a value or array. */
+    properties?: Record<string, ValueValid>;
+
+    /** OPTIONAL: If true, this event will be the first event for a new user (e.g., "sign up"). Only one event should have this. */
+    isFirstEvent?: boolean;
+
+    /** OPTIONAL: If true, this event signifies that a user has churned (e.g., "account deleted"). */
+    isChurnEvent?: boolean;
+}
+
+
+/**
+ * Defines a sequence of events that represents a meaningful user journey or workflow.
+ *
+ * Funnels model how users progress through your product - from sign-up to purchase,
+ * from onboarding to activation, etc. The conversionRate determines what percentage
+ * of users who start the funnel will complete it.
+ */
+interface Funnel {
+    /** REQUIRED: Event names that make up this journey. Must match event names in the events array. */
+    sequence: string[];
+
+    /** REQUIRED: Percentage (0-100) of users who complete the funnel. 15 means 15% conversion. */
+    conversionRate: number;
+
+    /** OPTIONAL: The name of the funnel (e.g., "Purchase Funnel", "Onboarding Flow"). */
+    name?: string;
+
+    /** OPTIONAL: The likelihood that a user will attempt this funnel vs others. Default: 1 */
+    weight?: number;
+
+    /** OPTIONAL: If true, this is an initial user experience funnel (e.g., onboarding). */
+    isFirstFunnel?: boolean;
+
+    /** OPTIONAL: Average hours to complete the funnel. Default: 1 */
+    timeToConvert?: number;
+
+    /**
+     * OPTIONAL: How events are ordered within the funnel.
+     * - "sequential" (default): Events happen in exact order
+     * - "random": Events can happen in any order
+     * - "first-fixed": First event is fixed, rest are random
+     * - "last-fixed": Last event is fixed, rest are random
+     * - "first-and-last-fixed": First and last are fixed, middle is random
+     */
+    order?: "sequential" | "random" | "first-fixed" | "last-fixed" | "first-and-last-fixed";
+
+    /** OPTIONAL: Properties attached to every event in this funnel (e.g., experiment_variant, traffic_source). */
+    props?: Record<string, ValueValid>;
+
+    /** OPTIONAL: User property conditions for eligibility. Only users matching these values run this funnel. */
+    conditions?: Record<string, ValueValid>;
+
+    /** OPTIONAL: If true, generates 3 variants with different conversion rates for A/B testing analysis. */
+    experiment?: boolean;
+}
+
+
+/**
+ * Defines a "Slowly Changing Dimension" - a property of a user or group
+ * that changes periodically over time (e.g., subscription plan, user role).
+ *
+ * ONLY include SCDs when properties explicitly need to change over time.
+ * For static properties, just use userProps or groupProps.
+ */
+interface SCDProp {
+    /** OPTIONAL: The entity type - 'user' or a group key like 'company_id'. Default: 'user' */
+    type?: "user" | string;
+
+    /** REQUIRED: How often this property can change. */
+    frequency: "day" | "week" | "month" | "year";
+
+    /** REQUIRED: Possible values for this property. */
+    values: ValueValid;
+
+    /**
+     * REQUIRED: When changes occur.
+     * - "fixed": Changes occur exactly on the frequency interval
+     * - "fuzzy": Changes occur randomly around the interval
+     */
+    timing: "fixed" | "fuzzy";
+
+    /** OPTIONAL: Maximum number of times this property can change per entity. Default: 100 */
+    max?: number;
+}
+
+
+/**
+ * Defines an event attributed to a group on a regular schedule.
+ * Example: monthly subscription charges, weekly reports, etc.
+ *
+ * This is rarely needed - only use for B2B scenarios with recurring group-level events.
+ */
+interface GroupEventConfig {
+    /** REQUIRED: The name of the event. */
+    event: string;
+
+    /** REQUIRED: How often the event occurs (in days). e.g., 30 for monthly. */
+    frequency: number;
+
+    /** REQUIRED: The group key this event belongs to (e.g., "company_id"). */
+    group_key: string;
+
+    /** OPTIONAL: If true, a random user in the group is also attributed to the event. */
+    attribute_to_user?: boolean;
+
+    /** OPTIONAL: Properties for this event. */
+    properties?: Record<string, ValueValid>;
+
+    /** OPTIONAL: Relative frequency of this event. */
+    weight?: number;
+}

package/lib/templates/soup-presets.js

@@ -0,0 +1,188 @@
+/**
+ * TimeSoup preset configurations
+ * Each preset defines time distribution parameters that produce distinct patterns.
+ *
+ * Parameters:
+ * - peaks(numDays): function returning number of Gaussian clusters
+ * - deviation: controls peak width (higher = tighter)
+ * - mean: offset from chunk center (0 = centered)
+ * - dayOfWeekWeights: 7-element array [Sun..Sat], max=1.0, null to disable
+ * - hourOfDayWeights: 24-element array [0h..23h UTC], max=1.0, null to disable
+ *
+ * Some presets also suggest bornRecentBias and percentUsersBornInDataset,
+ * but those are top-level dungeon config — presets only set them if not already specified.
+ */
+
+// Real-world Mixpanel DOW pattern: weekday-heavy, Saturday valley
+export const REAL_DOW = [0.637, 1.0, 0.999, 0.998, 0.966, 0.802, 0.528];
+
+// Real-world Mixpanel HOD pattern: early-morning peak (UTC), afternoon valley
+export const REAL_HOD = [
+	0.949, 0.992, 0.998, 0.946, 0.895, 0.938, 1.0, 0.997,
+	0.938, 0.894, 0.827, 0.786, 0.726, 0.699, 0.688, 0.643,
+	0.584, 0.574, 0.554, 0.576, 0.604, 0.655, 0.722, 0.816
+];
+
+// Flat weights (no cyclical pattern)
+export const FLAT_DOW = [1, 1, 1, 1, 1, 1, 1];
+export const FLAT_HOD = [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1];
+
+/** @type {Record<string, {peaks: (numDays: number) => number, deviation: number, mean: number, dayOfWeekWeights: number[]|null, hourOfDayWeights: number[]|null, bornRecentBias?: number, percentUsersBornInDataset?: number}>} */
+export const SOUP_PRESETS = {
+	/**
+	 * steady — Mature SaaS / Stable Product
+	 * Nearly flat day-over-day, slight weekly pattern, minimal growth trend.
+	 */
+	steady: {
+		peaks: (numDays) => Math.max(5, numDays * 2),
+		deviation: 1.5,
+		mean: 0,
+		dayOfWeekWeights: REAL_DOW,
+		hourOfDayWeights: REAL_HOD,
+		bornRecentBias: 0.1,
+		percentUsersBornInDataset: 10,
+	},
+
+	/**
+	 * growth — Growing Startup (DEFAULT)
+	 * Gradual uptrend with visible weekly peaks. This is the default behavior.
+	 */
+	growth: {
+		peaks: (numDays) => Math.max(5, numDays * 2),
+		deviation: 2,
+		mean: 0,
+		dayOfWeekWeights: REAL_DOW,
+		hourOfDayWeights: REAL_HOD,
+		bornRecentBias: 0.3,
+		percentUsersBornInDataset: 15,
+	},
+
+	/**
+	 * spiky — Event-Driven / Bursty
+	 * Clear peaks and valleys, dramatic variation. Fewer Gaussian clusters + tight deviation.
+	 */
+	spiky: {
+		peaks: (numDays) => Math.max(5, Math.ceil(numDays / 10)),
+		deviation: 3.5,
+		mean: 0,
+		dayOfWeekWeights: REAL_DOW,
+		hourOfDayWeights: REAL_HOD,
+		bornRecentBias: 0.3,
+		percentUsersBornInDataset: 20,
+	},
+
+	/**
+	 * seasonal — Strong Cyclical Patterns
+	 * 3-4 major waves across the dataset. Very few peaks create dramatic macro trends.
+	 */
+	seasonal: {
+		peaks: () => 4,
+		deviation: 2.5,
+		mean: 0,
+		dayOfWeekWeights: REAL_DOW,
+		hourOfDayWeights: REAL_HOD,
+		bornRecentBias: 0.2,
+		percentUsersBornInDataset: 25,
+	},
+
+	/**
+	 * global — Distributed Users Across Timezones
+	 * Very flat hourly + daily distribution. No cyclical patterns.
+	 */
+	global: {
+		peaks: (numDays) => Math.max(5, numDays * 2),
+		deviation: 1,
+		mean: 0,
+		dayOfWeekWeights: FLAT_DOW,
+		hourOfDayWeights: FLAT_HOD,
+		bornRecentBias: 0,
+		percentUsersBornInDataset: 10,
+	},
+
+	/**
+	 * churny — High Churn / Declining Product
+	 * Flat distribution (no growth trend). All users pre-exist the dataset,
+	 * so there's no acceleration. Combine with an "everything" hook that
+	 * filters late events to create a true declining shape.
+	 */
+	churny: {
+		peaks: (numDays) => Math.max(5, numDays * 2),
+		deviation: 2,
+		mean: 0,
+		dayOfWeekWeights: REAL_DOW,
+		hourOfDayWeights: REAL_HOD,
+		bornRecentBias: 0,
+		percentUsersBornInDataset: 5,
+	},
+
+	/**
+	 * chaotic — Unpredictable / Irregular Patterns
+	 * Few peaks + very tight clustering = dramatic bursts separated by quiet stretches.
+	 */
+	chaotic: {
+		peaks: (numDays) => Math.max(3, Math.ceil(numDays / 20)),
+		deviation: 4,
+		mean: 0,
+		dayOfWeekWeights: REAL_DOW,
+		hourOfDayWeights: REAL_HOD,
+		bornRecentBias: 0.5,
+		percentUsersBornInDataset: 40,
+	},
+};
+
+/** @type {string[]} */
+export const PRESET_NAMES = Object.keys(SOUP_PRESETS);
+
+/**
+ * Resolves a soup config — handles string presets, preset+overrides, and raw objects.
+ * @param {string | object} soup - Soup config from dungeon
+ * @param {number} numDays - Number of days in the dataset
+ * @returns {{ soup: object, suggestedBornRecentBias?: number, suggestedPercentUsersBornInDataset?: number }}
+ */
+export function resolveSoup(soup, numDays) {
+	if (!soup) return { soup: {} };
+
+	// String preset: "growth", "spiky", etc.
+	if (typeof soup === 'string') {
+		const preset = SOUP_PRESETS[soup];
+		if (!preset) {
+			throw new Error(`Unknown soup preset: "${soup}". Valid presets: ${PRESET_NAMES.join(', ')}`);
+		}
+		return {
+			soup: {
+				peaks: preset.peaks(numDays),
+				deviation: preset.deviation,
+				mean: preset.mean,
+				dayOfWeekWeights: preset.dayOfWeekWeights,
+				hourOfDayWeights: preset.hourOfDayWeights,
+			},
+			suggestedBornRecentBias: preset.bornRecentBias,
+			suggestedPercentUsersBornInDataset: preset.percentUsersBornInDataset,
+		};
+	}
+
+	// Object with preset key: { preset: "growth", deviation: 3 }
+	if (typeof soup === 'object' && soup.preset) {
+		const preset = SOUP_PRESETS[soup.preset];
+		if (!preset) {
+			throw new Error(`Unknown soup preset: "${soup.preset}". Valid presets: ${PRESET_NAMES.join(', ')}`);
+		}
+		const base = {
+			peaks: preset.peaks(numDays),
+			deviation: preset.deviation,
+			mean: preset.mean,
+			dayOfWeekWeights: preset.dayOfWeekWeights,
+			hourOfDayWeights: preset.hourOfDayWeights,
+		};
+		// Apply overrides (excluding the 'preset' key itself)
+		const { preset: _, ...overrides } = soup;
+		return {
+			soup: { ...base, ...overrides },
+			suggestedBornRecentBias: preset.bornRecentBias,
+			suggestedPercentUsersBornInDataset: preset.percentUsersBornInDataset,
+		};
+	}
+
+	// Raw object: { peaks: 10, deviation: 2 } — pass through unchanged
+	return { soup };
+}

package/lib/utils/function-registry.js

@@ -0,0 +1,302 @@
+/**
+ * Registry of valid functions that can be called in dungeon configurations
+ * This replaces the old string-based function parsing with a clean JSON structure
+ */
+
+import { dataLogger as logger } from './logger.js';
+
+export const FUNCTION_REGISTRY = {
+	// Utility functions from utils.js
+	weighNumRange: {
+		minArgs: 2,
+		maxArgs: 3,
+		description: 'Generate weighted random number in range'
+	},
+	range: {
+		minArgs: 2,
+		maxArgs: 2,
+		description: 'Generate array of numbers in range'
+	},
+	date: {
+		minArgs: 1,
+		maxArgs: 3,
+		description: 'Generate date string'
+	},
+	choose: {
+		minArgs: 1,
+		maxArgs: 1,
+		description: 'Choose from array'
+	},
+	integer: {
+		minArgs: 1,
+		maxArgs: 2,
+		description: 'Generate random integer'
+	},
+	exhaust: {
+		minArgs: 1,
+		maxArgs: 1,
+		description: 'Exhaust values from array'
+	},
+
+	// Additional utility functions
+	maybe: {
+		minArgs: 1,
+		maxArgs: 2,
+		description: 'Return value or null based on probability'
+	},
+	takeSome: {
+		minArgs: 1,
+		maxArgs: 3,
+		description: 'Take random subset from array'
+	},
+	randomElement: {
+		minArgs: 1,
+		maxArgs: 1,
+		description: 'Return random element from array'
+	},
+	randomInt: {
+		minArgs: 2,
+		maxArgs: 2,
+		description: 'Generate random integer'
+	},
+
+	// Text generation functions
+	createTextGenerator: {
+		minArgs: 1,
+		maxArgs: 1,
+		description: 'Create text generator with config'
+	},
+	generateBatch: {
+		minArgs: 2,
+		maxArgs: 2,
+		description: 'Generate batch of text'
+	},
+
+	// Chance.js functions (using dot notation)
+	'chance.word': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random word'
+	},
+	'chance.sentence': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random sentence'
+	},
+	'chance.paragraph': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random paragraph'
+	},
+	'chance.name': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random name'
+	},
+	'chance.first': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random first name'
+	},
+	'chance.last': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random last name'
+	},
+	'chance.email': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random email'
+	},
+	'chance.company': {
+		minArgs: 0,
+		maxArgs: 0,
+		description: 'Generate random company name'
+	},
+	'chance.profession': {
+		minArgs: 0,
+		maxArgs: 0,
+		description: 'Generate random profession'
+	},
+	'chance.industry': {
+		minArgs: 0,
+		maxArgs: 0,
+		description: 'Generate random industry'
+	},
+	'chance.country': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random country'
+	},
+	'chance.city': {
+		minArgs: 0,
+		maxArgs: 0,
+		description: 'Generate random city'
+	},
+	'chance.state': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random state'
+	},
+	'chance.address': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random address'
+	},
+	'chance.phone': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random phone number'
+	},
+	'chance.url': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random URL'
+	},
+	'chance.domain': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random domain'
+	},
+	'chance.ip': {
+		minArgs: 0,
+		maxArgs: 0,
+		description: 'Generate random IP address'
+	},
+	'chance.guid': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random GUID'
+	},
+	'chance.hash': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random hash'
+	},
+	'chance.integer': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random integer with options'
+	},
+	'chance.floating': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random float'
+	},
+	'chance.bool': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random boolean'
+	},
+	'chance.character': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random character'
+	},
+	'chance.string': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate random string'
+	},
+	'chance.pick': {
+		minArgs: 1,
+		maxArgs: 2,
+		description: 'Pick random element from array'
+	},
+	'chance.pickone': {
+		minArgs: 1,
+		maxArgs: 1,
+		description: 'Pick one random element from array'
+	},
+	'chance.pickset': {
+		minArgs: 2,
+		maxArgs: 2,
+		description: 'Pick set of random elements from array'
+	},
+	'chance.cc': {
+		minArgs: 0,
+		maxArgs: 1,
+		description: 'Generate credit card number'
+	},
+	'chance.android_id': {
+		minArgs: 0,
+		maxArgs: 0,
+		description: 'Generate Android device ID'
+	},
+
+	// Commonly used utility functions from dungeons
+	pickAWinner: {
+		minArgs: 1,
+		maxArgs: 2,
+		description: 'Pick from array with power-law weighting (most common values first)'
+	},
+	weighChoices: {
+		minArgs: 1,
+		maxArgs: 1,
+		description: 'Weight choices by frequency in array (more duplicates = higher weight)'
+	},
+	decimal: {
+		minArgs: 0,
+		maxArgs: 3,
+		description: 'Generate random decimal (min, max, fixed decimal places)'
+	},
+
+	// Special function for arrow functions
+	arrow: {
+		minArgs: 1,
+		maxArgs: 1,
+		description: 'Raw arrow function with body',
+		special: true
+	}
+};
+
+/**
+ * Validate a function call structure
+ * @param {Object} funcCall - The function call object with functionName and args
+ * @returns {boolean} - Whether the function call is valid
+ */
+export function validateFunctionCall(funcCall) {
+	if (!funcCall || typeof funcCall !== 'object') {
+		return false;
+	}
+
+	const { functionName, args, body } = funcCall;
+
+	if (!functionName || typeof functionName !== 'string') {
+		return false;
+	}
+
+	// Special handling for arrow functions
+	if (functionName === 'arrow') {
+		return typeof body === 'string' && body.length > 0;
+	}
+
+	const funcDef = FUNCTION_REGISTRY[functionName];
+	if (!funcDef) {
+		logger.warn({ functionName }, `Unknown function: ${functionName}`);
+		return false;
+	}
+
+	// Check args
+	if (!Array.isArray(args)) {
+		if (funcDef.minArgs === 0 && !args) {
+			return true; // No args required and none provided
+		}
+		return false;
+	}
+
+	if (args.length < funcDef.minArgs || args.length > funcDef.maxArgs) {
+		logger.warn({ functionName, expected: `${funcDef.minArgs}-${funcDef.maxArgs}`, actual: args.length }, `Function ${functionName} expects ${funcDef.minArgs}-${funcDef.maxArgs} args, got ${args.length}`);
+		return false;
+	}
+
+	return true;
+}
+
+/**
+ * Get list of all valid function names
+ * @returns {string[]} Array of function names
+ */
+export function getValidFunctionNames() {
+	return Object.keys(FUNCTION_REGISTRY);
+}