@synode/core 1.0.0

package/LICENSE

@@ -0,0 +1,35 @@
+Synode Proprietary License
+
+Copyright (c) 2026 Digitl Cloud GmbH. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of this software and associated documentation files (the
+"Software"), to use the Software for personal, internal, and commercial
+purposes, subject to the following conditions:
+
+1. PERMITTED USE. You may use, copy, and modify the Software for your own
+   personal, internal, or commercial purposes.
+
+2. NO REDISTRIBUTION. You may not distribute, publish, sublicense, or
+   otherwise make the Software or any derivative works available to third
+   parties, whether in source code or compiled form, free of charge or for
+   a fee.
+
+3. NO RESALE. You may not sell, rent, lease, or otherwise commercially
+   exploit the Software itself as a standalone product or as part of a
+   software distribution.
+
+4. NO HOSTING AS A SERVICE. You may not offer the Software to third parties
+   as a hosted, managed, or software-as-a-service product where the primary
+   value derives from the Software.
+
+5. ATTRIBUTION. You must retain this license notice and copyright notice in
+   all copies or substantial portions of the Software.
+
+6. NO WARRANTY. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+   IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES
+   OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+   OTHER DEALINGS IN THE SOFTWARE.

package/dist/engine-CgLY6SKJ.cjs

@@ -0,0 +1,593 @@
+const require_index = require('./index.cjs');
+let __faker_js_faker = require("@faker-js/faker");
+
+//#region src/errors.ts
+const PATH_LABELS = [
+	"Journey",
+	"Adventure",
+	"Action",
+	"Step"
+];
+/**
+* Formats an error message with a hierarchical path prefix and optional suggestion.
+*
+* @param message - The base error message
+* @param path - Hierarchical path segments labeled Journey/Adventure/Action/Step
+* @param suggestion - Optional suggestion appended on a new line
+* @returns The formatted message string
+*/
+function formatErrorMessage(message, path, suggestion) {
+	let formatted = message;
+	if (path.length > 0) formatted = `[${path.map((segment, i) => `${PATH_LABELS[Math.min(i, PATH_LABELS.length - 1)]} "${segment}"`).join(" > ")}] ${message}`;
+	if (suggestion) formatted += `\n${suggestion}`;
+	return formatted;
+}
+/**
+* Structured error class for all Synode validation and runtime errors.
+*
+* @example
+* ```typescript
+* throw new SynodeError({
+*   code: 'INVALID_BOUNCE_CHANCE',
+*   message: 'Bounce chance must be between 0 and 1',
+*   path: ['Purchase Flow', 'Checkout', 'Submit Order'],
+*   expected: 'number between 0 and 1',
+*   received: '1.5',
+* });
+* ```
+*/
+var SynodeError = class extends Error {
+	/** Structured error code identifying the error type. */
+	code;
+	/** Hierarchical path where the error occurred. */
+	path;
+	/** Optional suggestion for fixing the error. */
+	suggestion;
+	/** The original unformatted error message. */
+	rawMessage;
+	/** Optional description of the expected value. */
+	expected;
+	/** Optional description of the actual value received. */
+	received;
+	constructor(options) {
+		const formatted = formatErrorMessage(options.message, options.path, options.suggestion);
+		super(formatted, { cause: options.cause });
+		this.name = "SynodeError";
+		this.code = options.code;
+		this.path = options.path;
+		this.suggestion = options.suggestion;
+		this.rawMessage = options.message;
+		this.expected = options.expected;
+		this.received = options.received;
+	}
+	/**
+	* Produces a structured multi-line representation of the error for human-readable output.
+	*
+	* Format:
+	* ```
+	* [ERROR_CODE] rawMessage
+	*   Path: Journey 'x' > Adventure 'y' > Action 'z'
+	*   Expected: what was expected
+	*   Received: what was provided
+	*   Fix: suggestion
+	* ```
+	*
+	* Path is omitted when path is empty. Expected/Received are omitted when not provided.
+	* Fix is omitted when there is no suggestion.
+	*
+	* @returns A formatted string representation of the error.
+	*/
+	format() {
+		const lines = [`[${this.code}] ${this.rawMessage}`];
+		if (this.path.length > 0) {
+			const segments = this.path.map((segment, i) => `${PATH_LABELS[Math.min(i, PATH_LABELS.length - 1)]} '${segment}'`);
+			lines.push(`  Path: ${segments.join(" > ")}`);
+		}
+		if (this.expected !== void 0) lines.push(`  Expected: ${this.expected}`);
+		if (this.received !== void 0) lines.push(`  Received: ${this.received}`);
+		if (this.suggestion) lines.push(`  Fix: ${this.suggestion}`);
+		return lines.join("\n");
+	}
+};
+/**
+* Computes the Levenshtein edit distance between two strings using a space-efficient
+* two-row approach.
+*
+* @param a - First string
+* @param b - Second string
+* @returns The minimum number of single-character edits (insertions, deletions, substitutions)
+*/
+function levenshtein(a, b) {
+	if (a === b) return 0;
+	if (a.length === 0) return b.length;
+	if (b.length === 0) return a.length;
+	let prev = new Array(b.length + 1);
+	let curr = new Array(b.length + 1);
+	for (let j = 0; j <= b.length; j++) prev[j] = j;
+	for (let i = 1; i <= a.length; i++) {
+		curr[0] = i;
+		for (let j = 1; j <= b.length; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+		}
+		[prev, curr] = [curr, prev];
+	}
+	return prev[b.length];
+}
+/**
+* Finds the closest matching string from a list of candidates using Levenshtein distance.
+* Returns undefined if no candidate is within the dynamic threshold.
+*
+* The threshold is `max(3, floor(maxLen * 0.4))` where maxLen is the longer of the
+* input and candidate strings.
+*
+* @param input - The string to match against candidates
+* @param candidates - List of valid strings to compare against
+* @returns The closest matching candidate, or undefined if none is close enough
+*/
+function suggestClosest(input, candidates) {
+	if (candidates.length === 0) return void 0;
+	let bestMatch;
+	let bestDistance = Infinity;
+	for (const candidate of candidates) {
+		const distance = levenshtein(input, candidate);
+		const maxLen = Math.max(input.length, candidate.length);
+		if (distance <= Math.max(3, Math.floor(maxLen * .4)) && distance < bestDistance) {
+			bestDistance = distance;
+			bestMatch = candidate;
+		}
+	}
+	return bestMatch;
+}
+/**
+* Builds a human-readable suggestion string for a not-found error, including
+* the closest match (if any) and the full list of available options.
+*
+* @param kind - The kind of entity (e.g., "dataset", "journey")
+* @param requested - The name that was requested but not found
+* @param available - List of valid names
+* @returns A suggestion string with "Did you mean..." and/or available options
+*/
+function buildNotFoundSuggestion(kind, requested, available) {
+	const closest = suggestClosest(requested, available);
+	const parts = [];
+	if (closest) parts.push(`Did you mean '${closest}'?`);
+	parts.push(`Available ${kind}s: [${available.join(", ")}]`);
+	return parts.join(" ");
+}
+
+//#endregion
+//#region src/state/ids.ts
+/**
+* Default ID generator using crypto.randomUUID.
+*/
+const defaultIdGenerator = { generate(prefix) {
+	const uuid = crypto.randomUUID();
+	return prefix ? `${prefix}_${uuid}` : uuid;
+} };
+
+//#endregion
+//#region src/state/context.ts
+var SynodeContext = class {
+	state = /* @__PURE__ */ new Map();
+	fieldMetadata = /* @__PURE__ */ new Map();
+	currentTime;
+	_userId;
+	_sessionId;
+	_faker;
+	completedJourneys = /* @__PURE__ */ new Set();
+	datasets = /* @__PURE__ */ new Map();
+	constructor(startTime = /* @__PURE__ */ new Date(), idGenerator = defaultIdGenerator, locale = "en") {
+		this.idGenerator = idGenerator;
+		this.locale = locale;
+		this.currentTime = new Date(startTime);
+		this._userId = idGenerator.generate("user");
+		this._sessionId = idGenerator.generate("session");
+		const localeDef = __faker_js_faker.allLocales[locale];
+		this._faker = new __faker_js_faker.Faker({ locale: localeDef });
+	}
+	get faker() {
+		return this._faker;
+	}
+	get userId() {
+		return this._userId;
+	}
+	get sessionId() {
+		return this._sessionId;
+	}
+	get(key) {
+		return this.state.get(key);
+	}
+	/**
+	* Set a context field value with optional scope for automatic cleanup.
+	*
+	* @param key - The field name
+	* @param value - The field value
+	* @param options - Optional settings including lifecycle scope
+	*
+	* @remarks
+	* When calling `set()` multiple times on the same field with different scopes,
+	* the most recent scope setting will be used. For example, if a field is first
+	* set with `scope: 'adventure'` and later set again with `scope: 'action'`,
+	* it will be cleared at the end of the action rather than the adventure.
+	*
+	* @example
+	* ```typescript
+	* ctx.set('cartItems', [], { scope: 'adventure' });
+	* // Later in the same adventure...
+	* ctx.set('cartItems', ['item1'], { scope: 'action' }); // Now scoped to action
+	* ```
+	*/
+	set(key, value, options) {
+		this.state.set(key, value);
+		if (options?.scope) this.fieldMetadata.set(key, { scope: options.scope });
+		else this.fieldMetadata.delete(key);
+	}
+	now() {
+		return new Date(this.currentTime);
+	}
+	generateId(prefix) {
+		return this.idGenerator.generate(prefix);
+	}
+	hasCompletedJourney(journeyId) {
+		return this.completedJourneys.has(journeyId);
+	}
+	markJourneyComplete(journeyId) {
+		this.completedJourneys.add(journeyId);
+	}
+	dataset(id) {
+		const ds = this.datasets.get(id);
+		if (!ds) {
+			const available = [...this.datasets.keys()];
+			const suggestion = available.length > 0 ? buildNotFoundSuggestion("dataset", id, available) : void 0;
+			throw new SynodeError({
+				code: "DATASET_NOT_FOUND",
+				message: `Dataset '${id}' not found in context`,
+				path: [],
+				suggestion
+			});
+		}
+		return new DatasetHandleImpl(ds);
+	}
+	typedDataset(id) {
+		const ds = this.datasets.get(id);
+		if (!ds) {
+			const available = [...this.datasets.keys()];
+			const suggestion = available.length > 0 ? buildNotFoundSuggestion("dataset", id, available) : void 0;
+			throw new SynodeError({
+				code: "DATASET_NOT_FOUND",
+				message: `Dataset '${id}' not found in context`,
+				path: [],
+				suggestion
+			});
+		}
+		return new DatasetHandleImpl(ds);
+	}
+	/**
+	* Internal: Register a dataset for use in this context.
+	*/
+	registerDataset(dataset) {
+		this.datasets.set(dataset.id, dataset);
+	}
+	/**
+	* Internal: Advance the simulation time.
+	*/
+	advanceTime(ms) {
+		this.currentTime = new Date(this.currentTime.getTime() + ms);
+	}
+	/**
+	* Internal: Rotate the session ID.
+	*/
+	rotateSession() {
+		this._sessionId = this.idGenerator.generate("session");
+	}
+	/**
+	* Internal: Clear all fields with the specified scope.
+	* Called by the engine when a scope ends.
+	*/
+	clearScope(scope) {
+		const keysToDelete = [];
+		for (const [key, metadata] of this.fieldMetadata.entries()) if (metadata.scope === scope) keysToDelete.push(key);
+		for (const key of keysToDelete) {
+			this.state.delete(key);
+			this.fieldMetadata.delete(key);
+		}
+	}
+};
+/**
+* Internal implementation of DatasetHandle.
+*/
+var DatasetHandleImpl = class {
+	constructor(dataset) {
+		this.dataset = dataset;
+	}
+	randomRow() {
+		if (this.dataset.rows.length === 0) throw new Error(`Dataset '${this.dataset.id}' is empty.`);
+		const index = Math.floor(Math.random() * this.dataset.rows.length);
+		return this.dataset.rows[index];
+	}
+	getRowById(id) {
+		return this.dataset.rows.find((row) => {
+			for (const key of Object.keys(row)) if (row[key] === id) return true;
+			return false;
+		});
+	}
+	getRowByIndex(index) {
+		return this.dataset.rows[index];
+	}
+	getAllRows() {
+		return [...this.dataset.rows];
+	}
+	size() {
+		return this.dataset.rows.length;
+	}
+};
+
+//#endregion
+//#region src/generators/persona.ts
+/**
+* Defines a new persona.
+*/
+function definePersona(config) {
+	return config;
+}
+/**
+* Generates a concrete persona instance from a definition.
+* This resolves all dynamic fields and weighted distributions.
+*/
+async function generatePersona(definition, baseContext) {
+	const attributes = {};
+	for (const [key, generator] of Object.entries(definition.attributes)) if (typeof generator === "function") attributes[key] = await generator(baseContext, attributes);
+	else attributes[key] = generator;
+	return {
+		id: definition.id,
+		name: definition.name,
+		attributes
+	};
+}
+
+//#endregion
+//#region src/generators/dataset.ts
+/**
+* Defines a new dataset with type inference support.
+*
+* @example
+* ```typescript
+* const products = defineDataset({
+*   id: 'products',
+*   name: 'Products',
+*   count: 100,
+*   fields: {
+*     id: (ctx, row) => `prod-${row.index}`,
+*     name: (ctx) => ctx.faker.commerce.productName(),
+*     price: (ctx) => ctx.faker.number.float({ min: 10, max: 500 }),
+*   },
+* });
+*
+* // Type inference works automatically
+* type Product = InferDatasetRow<typeof products>;
+* ```
+*/
+function defineDataset(config) {
+	return config;
+}
+/**
+* Generates a concrete dataset from a definition.
+* @param definition The dataset definition.
+* @param context Context providing access to faker, other datasets, and user data.
+*/
+async function generateDataset(definition, context) {
+	if (!Number.isFinite(definition.count) || definition.count < 0 || definition.count > 1e7) throw new Error(`Dataset '${definition.id}' count must be a finite number between 0 and 10,000,000, got ${String(definition.count)}`);
+	const rows = [];
+	for (let index = 0; index < definition.count; index++) {
+		const row = {};
+		for (const [key, generator] of Object.entries(definition.fields)) if (typeof generator === "function") row[key] = await generator(context, {
+			index,
+			data: row
+		});
+		else row[key] = generator;
+		rows.push(row);
+	}
+	return {
+		id: definition.id,
+		name: definition.name,
+		rows
+	};
+}
+
+//#endregion
+//#region src/monitoring/timing.ts
+/**
+* Generates a delay in milliseconds based on a time span configuration.
+*/
+function generateDelay(timeSpan) {
+	const { min, max, distribution = "uniform" } = timeSpan;
+	switch (distribution) {
+		case "uniform": return min + Math.random() * (max - min);
+		case "gaussian": {
+			const mean = (min + max) / 2;
+			const stdDev = (max - min) / 6;
+			const u1 = Math.random();
+			const u2 = Math.random();
+			const value = mean + Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2) * stdDev;
+			return Math.max(min, Math.min(max, value));
+		}
+		case "exponential": {
+			const lambda = 1 / (max - min);
+			const value = min - Math.log(1 - Math.random()) / lambda;
+			return Math.min(max, value);
+		}
+		default: return min + Math.random() * (max - min);
+	}
+}
+/**
+* Checks if a bounce should occur based on probability.
+*/
+function shouldBounce(bounceChance) {
+	if (!bounceChance) return false;
+	return Math.random() < bounceChance;
+}
+
+//#endregion
+//#region src/execution/engine.ts
+var Engine = class {
+	constructor(journey) {
+		this.journey = journey;
+	}
+	/**
+	* Executes the journey and yields events.
+	* @param context Optional context to use. If not provided, a new one is created.
+	*/
+	async *run(context) {
+		const ctx = context ?? new SynodeContext();
+		ctx.rotateSession();
+		if (this.journey.requires) {
+			for (const requiredJourneyId of this.journey.requires) if (!ctx.hasCompletedJourney(requiredJourneyId)) return;
+		}
+		if (shouldBounce(this.journey.bounceChance)) {
+			if (this.journey.suppressionPeriod) {
+				const suppressionDelay = generateDelay(this.journey.suppressionPeriod);
+				ctx.advanceTime(suppressionDelay);
+			}
+			return;
+		}
+		for (const adventure of this.journey.adventures) {
+			if (shouldBounce(adventure.bounceChance)) if (adventure.onBounce === "skip") {
+				ctx.clearScope("adventure");
+				continue;
+			} else {
+				ctx.clearScope("adventure");
+				break;
+			}
+			for (const action of adventure.actions) {
+				if (shouldBounce(action.bounceChance)) {
+					ctx.clearScope("action");
+					break;
+				}
+				if (adventure.timeSpan) {
+					const delay = generateDelay(adventure.timeSpan);
+					ctx.advanceTime(delay);
+				}
+				const actionPath = [
+					this.journey.id,
+					adventure.id,
+					action.id
+				];
+				let events;
+				try {
+					events = await action.handler(ctx);
+				} catch (err) {
+					if (err instanceof SynodeError) throw err;
+					throw new SynodeError({
+						code: "HANDLER_ERROR",
+						message: `${err instanceof Error ? err.constructor.name : "UnknownError"}: ${err instanceof Error ? err.message : String(err)} (userId: ${ctx.userId}, sessionId: ${ctx.sessionId})`,
+						path: actionPath,
+						cause: err
+					});
+				}
+				if (!Array.isArray(events)) throw new SynodeError({
+					code: "INVALID_HANDLER_RETURN",
+					message: `Action handler must return an array of Events, got ${typeof events}`,
+					path: actionPath
+				});
+				for (let i = 0; i < events.length; i++) {
+					if (i > 0 && action.timeSpan) {
+						const delay = generateDelay(action.timeSpan);
+						ctx.advanceTime(delay);
+						events[i].timestamp = ctx.now();
+					}
+					yield events[i];
+				}
+				ctx.clearScope("action");
+			}
+			ctx.clearScope("adventure");
+		}
+		ctx.markJourneyComplete(this.journey.id);
+		ctx.clearScope("journey");
+		if (this.journey.suppressionPeriod) {
+			const suppressionDelay = generateDelay(this.journey.suppressionPeriod);
+			ctx.advanceTime(suppressionDelay);
+		}
+	}
+};
+
+//#endregion
+Object.defineProperty(exports, 'Engine', {
+  enumerable: true,
+  get: function () {
+    return Engine;
+  }
+});
+Object.defineProperty(exports, 'SynodeContext', {
+  enumerable: true,
+  get: function () {
+    return SynodeContext;
+  }
+});
+Object.defineProperty(exports, 'SynodeError', {
+  enumerable: true,
+  get: function () {
+    return SynodeError;
+  }
+});
+Object.defineProperty(exports, 'buildNotFoundSuggestion', {
+  enumerable: true,
+  get: function () {
+    return buildNotFoundSuggestion;
+  }
+});
+Object.defineProperty(exports, 'defineDataset', {
+  enumerable: true,
+  get: function () {
+    return defineDataset;
+  }
+});
+Object.defineProperty(exports, 'definePersona', {
+  enumerable: true,
+  get: function () {
+    return definePersona;
+  }
+});
+Object.defineProperty(exports, 'formatErrorMessage', {
+  enumerable: true,
+  get: function () {
+    return formatErrorMessage;
+  }
+});
+Object.defineProperty(exports, 'generateDataset', {
+  enumerable: true,
+  get: function () {
+    return generateDataset;
+  }
+});
+Object.defineProperty(exports, 'generateDelay', {
+  enumerable: true,
+  get: function () {
+    return generateDelay;
+  }
+});
+Object.defineProperty(exports, 'generatePersona', {
+  enumerable: true,
+  get: function () {
+    return generatePersona;
+  }
+});
+Object.defineProperty(exports, 'levenshtein', {
+  enumerable: true,
+  get: function () {
+    return levenshtein;
+  }
+});
+Object.defineProperty(exports, 'shouldBounce', {
+  enumerable: true,
+  get: function () {
+    return shouldBounce;
+  }
+});
+Object.defineProperty(exports, 'suggestClosest', {
+  enumerable: true,
+  get: function () {
+    return suggestClosest;
+  }
+});
+//# sourceMappingURL=engine-CgLY6SKJ.cjs.map