flowcraft 2.10.0 → 2.10.1

package/dist/context.mjs

@@ -0,0 +1,145 @@
+//#region src/context.ts
+/**
+* A default, high-performance, in-memory implementation of ISyncContext using a Map.
+*/
+var Context = class {
+	type = "sync";
+	data;
+	constructor(initialData = {}) {
+		this.data = new Map(Object.entries(initialData));
+	}
+	get(key) {
+		return this.data.get(key);
+	}
+	set(key, value) {
+		this.data.set(key, value);
+	}
+	has(key) {
+		return this.data.has(key);
+	}
+	delete(key) {
+		return this.data.delete(key);
+	}
+	toJSON() {
+		return Object.fromEntries(this.data);
+	}
+};
+/**
+* An adapter that provides a consistent, Promise-based view of a synchronous context.
+* This is created by the runtime and is transparent to the node author.
+*/
+var AsyncContextView = class {
+	type = "async";
+	constructor(syncContext) {
+		this.syncContext = syncContext;
+	}
+	get(key) {
+		return Promise.resolve(this.syncContext.get(key));
+	}
+	set(key, value) {
+		this.syncContext.set(key, value);
+		return Promise.resolve();
+	}
+	has(key) {
+		return Promise.resolve(this.syncContext.has(key));
+	}
+	delete(key) {
+		return Promise.resolve(this.syncContext.delete(key));
+	}
+	toJSON() {
+		return Promise.resolve(this.syncContext.toJSON());
+	}
+	async patch(_operations) {
+		throw new Error("Patch operations not supported by AsyncContextView");
+	}
+};
+/**
+* A proxy wrapper that tracks changes to an async context for delta-based persistence.
+* Records all mutations (set/delete operations) to enable efficient partial updates.
+*/
+var TrackedAsyncContext = class {
+	type = "async";
+	deltas = [];
+	innerContext;
+	eventBus;
+	executionId;
+	sourceNode;
+	constructor(innerContext, eventBus, executionId, sourceNode) {
+		this.innerContext = innerContext;
+		this.eventBus = eventBus;
+		this.executionId = executionId;
+		this.sourceNode = sourceNode;
+	}
+	async get(key) {
+		return this.innerContext.get(key);
+	}
+	async set(key, value) {
+		this.deltas.push({
+			op: "set",
+			key,
+			value
+		});
+		await this.innerContext.set(key, value);
+		if (this.eventBus && this.executionId) await this.eventBus.emit({
+			type: "context:change",
+			payload: {
+				sourceNode: this.sourceNode || "unknown",
+				key,
+				op: "set",
+				value,
+				executionId: this.executionId
+			}
+		});
+	}
+	async has(key) {
+		return this.innerContext.has(key);
+	}
+	async delete(key) {
+		this.deltas.push({
+			op: "delete",
+			key
+		});
+		const result = await this.innerContext.delete(key);
+		if (this.eventBus && this.executionId && result) await this.eventBus.emit({
+			type: "context:change",
+			payload: {
+				sourceNode: this.sourceNode || "unknown",
+				key,
+				op: "delete",
+				executionId: this.executionId
+			}
+		});
+		return result;
+	}
+	toJSON() {
+		return this.innerContext.toJSON();
+	}
+	async patch(operations) {
+		if (this.innerContext.patch) return this.innerContext.patch(operations);
+		for (const op of operations) if (op.op === "set") await this.innerContext.set(op.key, op.value);
+		else if (op.op === "delete") await this.innerContext.delete(op.key);
+	}
+	getDeltas() {
+		return [...this.deltas];
+	}
+	clearDeltas() {
+		this.deltas = [];
+	}
+	/**
+	* Configures the event emitter for tracking context changes.
+	* This enables the context to emit events when set/delete operations occur,
+	* allowing for external monitoring and persistence of context mutations.
+	*
+	* @param eventBus - The event bus instance to emit context change events
+	* @param executionId - The unique identifier for the current workflow execution
+	* @param sourceNode - Optional identifier for the node that triggered the context change
+	*/
+	configureEventEmitter(eventBus, executionId, sourceNode) {
+		this.eventBus = eventBus;
+		this.executionId = executionId;
+		this.sourceNode = sourceNode;
+	}
+};
+
+//#endregion
+export { AsyncContextView, Context, TrackedAsyncContext };

package/dist/error-mapper-BAv_YQMQ.d.mts

@@ -0,0 +1,14 @@
+import { w as WorkflowBlueprint } from "./types-BcrXJEPI.mjs";
+
+//#region src/error-mapper.d.ts
+/**
+ * Creates an error mapper function that enhances runtime errors with source location information.
+ * The mapper looks up node IDs in the provided manifest blueprints and returns enhanced errors
+ * that point to the original TypeScript source code.
+ *
+ * @param manifestBlueprints - The compiled blueprint manifest containing source location data
+ * @returns A function that maps errors to enhanced errors with source location information
+ */
+declare function createErrorMapper(manifestBlueprints: Record<string, WorkflowBlueprint>): (error: Error) => Error;
+//#endregion
+export { createErrorMapper as t };

package/dist/error-mapper.d.mts

@@ -0,0 +1,2 @@
+import { t as createErrorMapper } from "./error-mapper-BAv_YQMQ.mjs";
+export { createErrorMapper };

package/dist/error-mapper.mjs

@@ -0,0 +1,37 @@
+import { FlowcraftError } from "./errors.mjs";
+
+//#region src/error-mapper.ts
+/**
+* Creates an error mapper function that enhances runtime errors with source location information.
+* The mapper looks up node IDs in the provided manifest blueprints and returns enhanced errors
+* that point to the original TypeScript source code.
+*
+* @param manifestBlueprints - The compiled blueprint manifest containing source location data
+* @returns A function that maps errors to enhanced errors with source location information
+*/
+function createErrorMapper(manifestBlueprints) {
+	const locationMap = /* @__PURE__ */ new Map();
+	for (const blueprint of Object.values(manifestBlueprints)) {
+		for (const node of blueprint.nodes) if (node._sourceLocation) locationMap.set(node.id, node._sourceLocation);
+		for (const edge of blueprint.edges) if (edge._sourceLocation) {
+			const edgeKey = `${edge.source}-${edge.target}`;
+			locationMap.set(edgeKey, edge._sourceLocation);
+		}
+	}
+	return function mapError(error) {
+		if (error instanceof FlowcraftError && error.nodeId) {
+			const location = locationMap.get(error.nodeId);
+			if (location) return /* @__PURE__ */ new Error(`Workflow error at ${location.file}:${location.line}:${location.column}. Original error: ${error.message}`);
+		}
+		const nodeIdMatch = error.message.match(/nodeId[:\s]+([^\s,]+)/i);
+		if (nodeIdMatch) {
+			const nodeId = nodeIdMatch[1];
+			const location = locationMap.get(nodeId);
+			if (location) return /* @__PURE__ */ new Error(`Workflow error at ${location.file}:${location.line}:${location.column}. Original error: ${error.message}`);
+		}
+		return error;
+	};
+}
+
+//#endregion
+export { createErrorMapper };

package/dist/errors-CyyIj3OO.d.mts

@@ -0,0 +1,21 @@
+//#region src/errors.d.ts
+/**
+ * A single, comprehensive error class for the framework.
+ * Use this for all errors to ensure consistent structure and easy debugging.
+ */
+declare class FlowcraftError extends Error {
+  readonly message: string;
+  readonly nodeId?: string;
+  readonly blueprintId?: string;
+  readonly executionId?: string;
+  readonly isFatal: boolean;
+  constructor(message: string, options?: {
+    cause?: Error;
+    nodeId?: string;
+    blueprintId?: string;
+    executionId?: string;
+    isFatal?: boolean;
+  });
+}
+//#endregion
+export { FlowcraftError as t };

package/dist/errors.d.mts

@@ -0,0 +1,2 @@
+import { t as FlowcraftError } from "./errors-CyyIj3OO.mjs";
+export { FlowcraftError };

package/dist/errors.mjs

@@ -0,0 +1,24 @@
+//#region src/errors.ts
+/**
+* A single, comprehensive error class for the framework.
+* Use this for all errors to ensure consistent structure and easy debugging.
+*/
+var FlowcraftError = class extends Error {
+	message;
+	nodeId;
+	blueprintId;
+	executionId;
+	isFatal;
+	constructor(message, options = {}) {
+		super(message, { cause: options.cause });
+		this.name = "FlowcraftError";
+		this.message = message;
+		this.nodeId = options.nodeId;
+		this.blueprintId = options.blueprintId;
+		this.executionId = options.executionId;
+		this.isFatal = options.isFatal ?? false;
+	}
+};
+
+//#endregion
+export { FlowcraftError };

package/dist/evaluator-Dnj5qJ92.d.mts

@@ -0,0 +1,31 @@
+import { a as IEvaluator } from "./types-BcrXJEPI.mjs";
+
+//#region src/evaluator.d.ts
+/**
+ * A safe evaluator that only allows simple property access.
+ * It cannot execute arbitrary code and is secure for untrusted inputs.
+ *
+ * Example expressions:
+ * - "result.output.status"
+ * - "context.user.isAdmin"
+ * - "input.value"
+ */
+declare class PropertyEvaluator implements IEvaluator {
+  evaluate(expression: string, context: Record<string, any>): any;
+}
+/**
+ * @warning This evaluator uses `new Function()` and can execute arbitrary
+ * JavaScript code. It poses a significant security risk if the expressions
+ * are not from a trusted source (e.g., user input).
+ *
+ * It should only be used in controlled environments where all workflow
+ * definitions are static and authored by trusted developers.
+ *
+ * For safer evaluation, use the default `PropertyEvaluator` or install a
+ * sandboxed library like `jsep` to create a custom, secure evaluator.
+ */
+declare class UnsafeEvaluator implements IEvaluator {
+  evaluate(expression: string, context: Record<string, any>): any;
+}
+//#endregion
+export { UnsafeEvaluator as n, PropertyEvaluator as t };

package/dist/evaluator.d.mts

@@ -0,0 +1,2 @@
+import { n as UnsafeEvaluator, t as PropertyEvaluator } from "./evaluator-Dnj5qJ92.mjs";
+export { PropertyEvaluator, UnsafeEvaluator };

package/dist/evaluator.mjs

@@ -0,0 +1,80 @@
+//#region src/evaluator.ts
+/**
+* A safe evaluator that only allows simple property access.
+* It cannot execute arbitrary code and is secure for untrusted inputs.
+*
+* Example expressions:
+* - "result.output.status"
+* - "context.user.isAdmin"
+* - "input.value"
+*/
+var PropertyEvaluator = class {
+	evaluate(expression, context) {
+		try {
+			if (!/^[a-zA-Z0-9_$.]+$/.test(expression)) {
+				console.error(`Error evaluating expression: "${expression}" contains invalid characters.`);
+				return;
+			}
+			const parts = expression.split(".");
+			const startKey = parts[0];
+			if (!Object.hasOwn(context, startKey)) return;
+			let current = context[startKey];
+			for (let i = 1; i < parts.length; i++) {
+				if (current === null || current === void 0) return;
+				current = current[parts[i]];
+			}
+			return current;
+		} catch (error) {
+			console.error(`Error evaluating property expression "${expression}":`, error);
+			return;
+		}
+	}
+};
+/**
+* Rewrites an expression so that hyphenated identifiers use bracket notation.
+* E.g. "foo-bar.total" → 'context["foo-bar"].total'
+*/
+function rewriteHyphenatedIdentifiers(expression, hyphenatedKeys) {
+	let result = expression;
+	const sortedKeys = [...hyphenatedKeys].toSorted((a, b) => b.length - a.length);
+	for (const key of sortedKeys) {
+		if (!key.includes("-")) continue;
+		const regex = new RegExp(`(?<![\\w$])${escapeRegex(key)}(?![\\w$-])`, "g");
+		result = result.replace(regex, `context["${key}"]`);
+	}
+	return result;
+}
+function escapeRegex(str) {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* @warning This evaluator uses `new Function()` and can execute arbitrary
+* JavaScript code. It poses a significant security risk if the expressions
+* are not from a trusted source (e.g., user input).
+*
+* It should only be used in controlled environments where all workflow
+* definitions are static and authored by trusted developers.
+*
+* For safer evaluation, use the default `PropertyEvaluator` or install a
+* sandboxed library like `jsep` to create a custom, secure evaluator.
+*/
+var UnsafeEvaluator = class {
+	evaluate(expression, context) {
+		try {
+			const validIdentifierRegex = /^[a-z_$][\w$]*$/i;
+			const validKeys = Object.keys(context).filter((key) => validIdentifierRegex.test(key));
+			const hyphenatedKeys = Object.keys(context).filter((key) => !validIdentifierRegex.test(key) && /^[a-zA-Z0-9_$-]+$/.test(key));
+			const validContext = {};
+			for (const key of validKeys) validContext[key] = context[key];
+			for (const key of hyphenatedKeys) validContext[key] = context[key];
+			let rewrittenExpression = rewriteHyphenatedIdentifiers(expression, hyphenatedKeys);
+			return new Function("context", ...validKeys, `return ${rewrittenExpression}`)(validContext, ...validKeys.map((k) => validContext[k]));
+		} catch (error) {
+			console.error(`Error evaluating expression "${expression}":`, error);
+			return;
+		}
+	}
+};
+
+//#endregion
+export { PropertyEvaluator, UnsafeEvaluator };

package/dist/flow-CZGpYpl-.d.mts

@@ -0,0 +1,94 @@
+import { A as FlowRuntime, C as UIGraph, D as WorkflowResult, d as NodeClass, h as NodeFunction, m as NodeDefinition, n as EdgeDefinition, w as WorkflowBlueprint } from "./types-BcrXJEPI.mjs";
+
+//#region src/flow.d.ts
+/**
+ * A fluent API for programmatically constructing a WorkflowBlueprint.
+ */
+declare class FlowBuilder<TContext extends Record<string, any> = Record<string, any>, TDependencies extends Record<string, any> = Record<string, any>> {
+  private blueprint;
+  private functionRegistry;
+  private loopDefinitions;
+  private batchDefinitions;
+  private cycleEntryPoints;
+  constructor(id: string);
+  node<TInput = any, TOutput = any, TAction extends string = string>(id: string, implementation: NodeFunction<TContext, TDependencies, TInput, TOutput, TAction> | NodeClass<TContext, TDependencies, TInput, TOutput, TAction>, options?: Omit<NodeDefinition, 'id' | 'uses'>): this;
+  edge(source: string, target: string, options?: Omit<EdgeDefinition, 'source' | 'target'>): this;
+  /**
+   * Creates a batch processing pattern.
+   * It takes an input array, runs a worker node on each item in parallel, and gathers the results.
+   * This method augments the Flow's TContext with a new key for the output array.
+   *
+   * @param id The base ID for this batch operation.
+   * @param worker The node implementation to run on each item.
+   * @param options Configuration for the batch operation.
+   * @returns The Flow instance with an updated context type for chaining.
+   */
+  batch<TWorkerInput, TWorkerOutput, TWorkerAction extends string, TOutputKey extends string>(id: string, worker: NodeFunction<TContext, TDependencies, TWorkerInput, TWorkerOutput, TWorkerAction> | NodeClass<TContext, TDependencies, TWorkerInput, TWorkerOutput, TWorkerAction>, options: {
+    /** The key in the context that holds the input array for the batch. */inputKey: keyof TContext; /** The key in the context where the array of results will be stored. */
+    outputKey: TOutputKey; /** The number of items to process in each chunk to limit memory usage. */
+    chunkSize?: number;
+  }): FlowBuilder<TContext & { [K in TOutputKey]: TWorkerOutput[] }, TDependencies>;
+  /**
+   * Creates a sleep node that pauses workflow execution for a specified duration.
+   * @param id A unique identifier for the sleep node.
+   * @param options Configuration for the sleep duration.
+   */
+  sleep(id: string, options: {
+    /** The duration to sleep in milliseconds or a string like '5s', '1m', '2h', '1d'. */duration: number | string;
+  }): this;
+  /**
+   * Creates a wait node that pauses workflow execution for external input.
+   * @param id A unique identifier for the wait node.
+   * @param options Optional configuration for the wait node.
+   */
+  wait(id: string, options?: Omit<NodeDefinition, 'id' | 'uses'>): this;
+  /**
+   * Creates a loop pattern in the workflow graph.
+   * @param id A unique identifier for the loop construct.
+   * @param options Defines the start, end, and continuation condition of the loop.
+   * @param options.startNodeId The ID of the first node inside the loop body.
+   * @param options.endNodeId The ID of the last node inside the loop body.
+   * @param options.condition An expression that, if true, causes the loop to run again.
+   */
+  loop(id: string, options: {
+    /** The ID of the first node inside the loop body. */startNodeId: string; /** The ID of the last node inside the loop body. */
+    endNodeId: string; /** An expression that, if true, causes the loop to run again. */
+    condition: string;
+  }): this;
+  /**
+   * Sets the preferred entry point for a cycle in non-DAG workflows.
+   * This helps remove ambiguity when the runtime needs to choose a starting node for cycles.
+   * @param nodeId The ID of the node to use as the entry point for cycles containing this node.
+   */
+  setCycleEntryPoint(nodeId: string): this;
+  toBlueprint(): WorkflowBlueprint;
+  getFunctionRegistry(): Map<string, NodeFunction | NodeClass>;
+  /**
+   * Runs this flow on the given runtime, automatically passing the function registry.
+   * Convenience wrapper around `runtime.run(blueprint, initialState, { functionRegistry })`.
+   */
+  run(runtime: FlowRuntime<TContext, TDependencies>, initialState?: Partial<TContext> | string, options?: {
+    strict?: boolean;
+    signal?: AbortSignal;
+    concurrency?: number;
+  }): Promise<WorkflowResult<TContext>>;
+  /**
+   * Resumes this flow on the given runtime, automatically passing the function registry.
+   * Convenience wrapper around `runtime.resume(blueprint, ...)`.
+   */
+  resume(runtime: FlowRuntime<TContext, TDependencies>, serializedContext: string, resumeData: {
+    output?: any;
+    action?: string;
+  }, nodeId?: string, options?: {
+    strict?: boolean;
+    signal?: AbortSignal;
+    concurrency?: number;
+  }): Promise<WorkflowResult<TContext>>;
+  toGraphRepresentation(): UIGraph;
+}
+/**
+ * Helper function to create a new Flow builder instance.
+ */
+declare function createFlow<TContext extends Record<string, any> = Record<string, any>, TDependencies extends Record<string, any> = Record<string, any>>(id: string): FlowBuilder<TContext, TDependencies>;
+//#endregion
+export { createFlow as n, FlowBuilder as t };

package/dist/flow.d.mts

@@ -0,0 +1,2 @@
+import { n as createFlow, t as FlowBuilder } from "./flow-CZGpYpl-.mjs";
+export { FlowBuilder, createFlow };