@pumped-fn/core-next 0.5.81 → 0.5.82

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @pumped-fn/core-next
 
+## 0.5.82
+
+### Patch Changes
+
+- 40be7e4: Fix unhandled promise rejections in Promised wrapper
+- 596bf02: Add flow execution tracking and extension authoring improvements
+
+  **Flow Execution Tracking:**
+
+  - FlowExecution return type with id, status, abort, ctx access
+  - Cancellation via AbortController with ctx.signal and ctx.throwIfAborted()
+  - Timeout support at scope.exec() and ctx.exec() levels
+  - Status tracking with observable status changes
+  - Execution registry with auto-cleanup
+
+  **Extension Authoring:**
+
+  - Extension authoring documentation and examples
+  - Scope capabilities and lifecycle documentation
+  - Real-world patterns for extensions
+
+  **API Changes:**
+
+  - scope.exec() now uses named parameters: `scope.exec({ flow, input, ...options })`
+  - scope.exec() returns FlowExecution<T> (thenable, backward compatible)
+
+  **Migration:**
+
+  ```ts
+  // Before
+  await scope.exec(myFlow, input);
+  await scope.exec(myFlow, input, { tags: [tag1] });
+
+  // After
+  await scope.exec({ flow: myFlow, input });
+  await scope.exec({ flow: myFlow, input, tags: [tag1] });
+  ```
+
 ## 0.5.81
 
 ### Patch Changes

package/dist/index.cjs

@@ -372,6 +372,7 @@ var Promised = class Promised {
 	constructor(promise, executionDataPromise) {
 		this.promise = promise instanceof Promised ? promise.promise : promise;
 		this.executionDataPromise = executionDataPromise;
+		this.promise.catch(() => {});
 	}
 	static create(promise, executionDataPromise) {
 		return new Promised(promise, executionDataPromise);
@@ -738,12 +739,20 @@ var FlowContext = class FlowContext {
 	scope;
 	reversedExtensions;
 	tags;
-	constructor(scope, extensions, tags, parent) {
+	abortController;
+	constructor(scope, extensions, tags, parent, abortController) {
 		this.extensions = extensions;
 		this.parent = parent;
 		this.scope = scope;
 		this.reversedExtensions = [...extensions].reverse();
 		this.tags = tags;
+		this.abortController = abortController || new AbortController();
+	}
+	get signal() {
+		return this.abortController.signal;
+	}
+	throwIfAborted() {
+		if (this.signal.aborted) throw new Error("Flow execution cancelled");
 	}
 	resolve(executor) {
 		return this.scope.resolve(executor);
@@ -792,45 +801,133 @@ var FlowContext = class FlowContext {
 		this.contextData.set(key, value);
 		return value;
 	}
-	run(key, fn, ...params) {
-		if (!this.journal) this.journal = /* @__PURE__ */ new Map();
-		const flowName = this.find(flowMeta.flowName) || "unknown";
-		const depth = this.get(flowMeta.depth);
-		const journalKey = `${flowName}:${depth}:${key}`;
-		const promise = (async () => {
-			const journal = this.journal;
-			const isReplay = journal.has(journalKey);
-			const executeCore = () => {
-				if (isReplay) {
-					const entry = journal.get(journalKey);
-					if (isErrorEntry(entry)) throw entry.error;
-					return Promised.create(Promise.resolve(entry));
-				}
-				return Promised.try(async () => {
-					const result = params.length > 0 ? await fn(...params) : await fn();
-					journal.set(journalKey, result);
-					return result;
-				}).catch((error) => {
-					journal.set(journalKey, {
-						__error: true,
-						error
-					});
-					throw error;
+	exec(keyOrFlowOrConfig, flowOrInput, inputOrUndefined) {
+		if (typeof keyOrFlowOrConfig === "object" && keyOrFlowOrConfig !== null && !("factory" in keyOrFlowOrConfig)) {
+			const config = keyOrFlowOrConfig;
+			this.throwIfAborted();
+			const childAbort = new AbortController();
+			let timeoutId;
+			if (config.timeout) timeoutId = setTimeout(() => {
+				if (!childAbort.signal.aborted) childAbort.abort(/* @__PURE__ */ new Error(`Operation timeout after ${config.timeout}ms`));
+			}, config.timeout);
+			if (this.signal.aborted) {
+				if (timeoutId) clearTimeout(timeoutId);
+				childAbort.abort(this.signal.reason);
+			} else this.signal.addEventListener("abort", () => {
+				if (timeoutId) clearTimeout(timeoutId);
+				childAbort.abort(this.signal.reason);
+			}, { once: true });
+			if ("flow" in config) {
+				const flow$2 = config.flow;
+				const input$1 = config.input;
+				if (config.key) {
+					if (!this.journal) this.journal = /* @__PURE__ */ new Map();
+					const journalKey = `${this.find(flowMeta.flowName) || "unknown"}:${this.get(flowMeta.depth)}:${config.key}`;
+					const promise$1 = (async () => {
+						const journal = this.journal;
+						if (journal.has(journalKey)) {
+							const entry = journal.get(journalKey);
+							if (isErrorEntry(entry)) throw entry.error;
+							return entry;
+						}
+						this.throwIfAborted();
+						const handler = await this.scope.resolve(flow$2);
+						const definition = flowDefinitionMeta.readFrom(flow$2);
+						if (definition) {
+							const validated = validate(definition.input, input$1);
+							const childContext = new FlowContext(this.scope, this.extensions, config.tags, this, childAbort);
+							childContext.initializeExecutionContext(definition.name, false);
+							try {
+								const result = await handler(childContext, validated);
+								validate(definition.output, result);
+								journal.set(journalKey, result);
+								return result;
+							} catch (error) {
+								journal.set(journalKey, {
+									__error: true,
+									error
+								});
+								throw error;
+							} finally {
+								if (timeoutId) clearTimeout(timeoutId);
+							}
+						} else throw new Error("Flow definition not found");
+					})();
+					return Promised.create(promise$1);
+				} else return this.scope.resolve(flow$2).map(async (handler) => {
+					this.throwIfAborted();
+					const definition = flowDefinitionMeta.readFrom(flow$2);
+					if (definition) {
+						const validated = validate(definition.input, input$1);
+						const childContext = new FlowContext(this.scope, this.extensions, config.tags, this, childAbort);
+						childContext.initializeExecutionContext(definition.name, false);
+						try {
+							const result = await handler(childContext, validated);
+							validate(definition.output, result);
+							return result;
+						} finally {
+							if (timeoutId) clearTimeout(timeoutId);
+						}
+					} else throw new Error("Flow definition not found");
 				});
-			};
-			return this.wrapWithExtensions(executeCore, {
-				kind: "journal",
-				key,
-				flowName,
-				depth,
-				isReplay,
-				context: this,
-				params: params.length > 0 ? params : void 0
-			})();
-		})();
-		return Promised.create(promise);
-	}
-	exec(keyOrFlow, flowOrInput, inputOrUndefined) {
+			} else if ("fn" in config) {
+				const fn = config.fn;
+				const params = "params" in config ? config.params || [] : [];
+				if (config.key) {
+					if (!this.journal) this.journal = /* @__PURE__ */ new Map();
+					const flowName = this.find(flowMeta.flowName) || "unknown";
+					const depth = this.get(flowMeta.depth);
+					const journalKey = `${flowName}:${depth}:${config.key}`;
+					const promise$1 = (async () => {
+						const journal = this.journal;
+						const isReplay = journal.has(journalKey);
+						const executeCore = () => {
+							if (isReplay) {
+								const entry = journal.get(journalKey);
+								if (isErrorEntry(entry)) throw entry.error;
+								return Promised.create(Promise.resolve(entry));
+							}
+							return Promised.try(async () => {
+								const result = await fn(...params);
+								journal.set(journalKey, result);
+								return result;
+							}).catch((error) => {
+								journal.set(journalKey, {
+									__error: true,
+									error
+								});
+								throw error;
+							});
+						};
+						const executor = this.wrapWithExtensions(executeCore, {
+							kind: "journal",
+							key: config.key,
+							flowName,
+							depth,
+							isReplay,
+							context: this,
+							params: params.length > 0 ? params : void 0
+						});
+						try {
+							return await executor();
+						} finally {
+							if (timeoutId) clearTimeout(timeoutId);
+						}
+					})();
+					return Promised.create(promise$1);
+				} else {
+					this.throwIfAborted();
+					return Promised.try(async () => {
+						try {
+							return await fn(...params);
+						} finally {
+							if (timeoutId) clearTimeout(timeoutId);
+						}
+					});
+				}
+			} else throw new Error("Invalid config: must have either 'flow' or 'fn'");
+		}
+		const keyOrFlow = keyOrFlowOrConfig;
 		if (typeof keyOrFlow === "string") {
 			if (!this.journal) this.journal = /* @__PURE__ */ new Map();
 			const key = keyOrFlow;
@@ -999,11 +1096,29 @@ var FlowContext = class FlowContext {
 };
 function execute(flow$1, input, options) {
 	if (options && "scope" in options) {
-		if (options.details === true) return options.scope.exec(flow$1, input, {
-			tags: options.executionTags,
-			details: true
+		const execution$1 = options.scope.exec({
+			flow: flow$1,
+			input,
+			tags: options.executionTags
 		});
-		return options.scope.exec(flow$1, input, { tags: options.executionTags });
+		if (options.details === true) return Promised.create(execution$1.result.then(async (r) => {
+			const ctx = await execution$1.result.ctx();
+			if (!ctx) throw new Error("Execution context not available");
+			return {
+				success: true,
+				result: r,
+				ctx
+			};
+		}).catch(async (error) => {
+			const ctx = await execution$1.result.ctx();
+			if (!ctx) throw new Error("Execution context not available");
+			return {
+				success: false,
+				error,
+				ctx
+			};
+		}));
+		return execution$1.result;
 	}
 	const scope = options ? createScope({
 		initialValues: options.initialValues,
@@ -1011,15 +1126,31 @@ function execute(flow$1, input, options) {
 		extensions: options.extensions,
 		tags: options.scopeTags
 	}) : createScope();
-	if (options?.details === true) {
-		const result$1 = scope.exec(flow$1, input, {
-			tags: options.executionTags,
-			details: true
-		});
-		return Promised.create(result$1.then((r) => scope.dispose().then(() => r)), result$1.ctx());
-	}
-	const result = scope.exec(flow$1, input, { tags: options?.executionTags });
-	return Promised.create(result.then((r) => scope.dispose().then(() => r)), result.ctx());
+	const execution = scope.exec({
+		flow: flow$1,
+		input,
+		tags: options?.executionTags
+	});
+	if (options?.details === true) return Promised.create(execution.result.then(async (r) => {
+		await scope.dispose();
+		const ctx = await execution.result.ctx();
+		if (!ctx) throw new Error("Execution context not available");
+		return {
+			success: true,
+			result: r,
+			ctx
+		};
+	}).catch(async (error) => {
+		await scope.dispose();
+		const ctx = await execution.result.ctx();
+		if (!ctx) throw new Error("Execution context not available");
+		return {
+			success: false,
+			error,
+			ctx
+		};
+	}));
+	return Promised.create(execution.result.then((r) => scope.dispose().then(() => r)), execution.result.ctx());
 }
 function flowImpl(first, second, third) {
 	if (typeof first === "function") {
@@ -1071,6 +1202,78 @@ function flowImpl(first, second, third) {
 }
 const flow = Object.assign(flowImpl, { execute });
 
+//#endregion
+//#region src/flow-execution.ts
+var FlowExecutionImpl = class {
+	result;
+	id;
+	flowName;
+	abort;
+	_status = "pending";
+	statusCallbacks = /* @__PURE__ */ new Set();
+	callbackErrors = [];
+	_ctx;
+	statusTracking;
+	statusTrackingActive = false;
+	constructor(config) {
+		this.id = config.id;
+		this.flowName = config.flowName;
+		this.abort = config.abort;
+		this._ctx = config.ctx;
+		this.result = config.result;
+		this.statusTracking = config.statusTracking ?? null;
+	}
+	get status() {
+		this["~ensureStatusTracking"]();
+		return this._status;
+	}
+	get ctx() {
+		return this._ctx ?? void 0;
+	}
+	get statusCallbackErrors() {
+		return this.callbackErrors;
+	}
+	"~setStatus"(newStatus) {
+		if (this._status === newStatus) return;
+		this._status = newStatus;
+		for (const callback of this.statusCallbacks) Promise.resolve(callback(newStatus, this)).catch((err) => {
+			const error = err instanceof Error ? err : new Error(String(err));
+			this.callbackErrors.push(error);
+			console.error("Error in status change callback:", err);
+		});
+	}
+	"~setCtx"(ctx) {
+		this._ctx = ctx;
+	}
+	"~ensureStatusTracking"() {
+		if (this.statusTrackingActive || !this.statusTracking) return;
+		this.statusTrackingActive = true;
+		const { promise, timeoutId, abortController } = this.statusTracking;
+		promise.then(async () => {
+			const ctx = await promise.ctx().catch(() => void 0);
+			if (ctx) this["~setCtx"](ctx);
+			this["~setStatus"]("completed");
+		}).catch(async () => {
+			const ctx = await promise.ctx().catch(() => void 0);
+			if (ctx) this["~setCtx"](ctx);
+			if (abortController.signal.aborted) this["~setStatus"]("cancelled");
+			else this["~setStatus"]("failed");
+		}).finally(() => {
+			if (timeoutId) clearTimeout(timeoutId);
+		});
+	}
+	onStatusChange(callback) {
+		this["~ensureStatusTracking"]();
+		this.statusCallbacks.add(callback);
+		return () => {
+			this.statusCallbacks.delete(callback);
+		};
+	}
+	then(onfulfilled, onrejected) {
+		return this.result.then(onfulfilled, onrejected);
+	}
+};
+
 //#endregion
 //#region src/scope.ts
 var AccessorImpl = class {
@@ -1279,6 +1482,7 @@ function getExecutor(e) {
 var BaseScope = class {
 	disposed = false;
 	cache = /* @__PURE__ */ new Map();
+	executions = /* @__PURE__ */ new Map();
 	onEvents = {
 		change: /* @__PURE__ */ new Set(),
 		release: /* @__PURE__ */ new Set(),
@@ -1570,6 +1774,7 @@ var BaseScope = class {
 			this.onEvents.change.clear();
 			this.onEvents.release.clear();
 			this.onEvents.error.clear();
+			this.executions.clear();
 		})());
 	}
 	onUpdate(e, cb) {
@@ -1647,37 +1852,56 @@ var BaseScope = class {
 	use(extension$1) {
 		return this.useExtension(extension$1);
 	}
-	exec(flow$1, input, options) {
+	exec(config) {
 		this["~ensureNotDisposed"]();
-		if (options?.details === true) {
-			const result = this["~executeFlow"](flow$1, input, options.tags);
-			return Promised.create(result.then(async (r) => {
-				const ctx = await result.ctx();
-				if (!ctx) throw new Error("Execution context not available");
-				return {
-					success: true,
-					result: r,
-					ctx
-				};
-			}).catch(async (error) => {
-				const ctx = await result.ctx();
-				if (!ctx) throw new Error("Execution context not available");
-				return {
-					success: false,
-					error,
-					ctx
-				};
-			}));
+		const executionId = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : `exec-${Date.now()}-${Math.random()}`;
+		const abortController = new AbortController();
+		let timeoutId;
+		if (config.timeout) timeoutId = setTimeout(() => {
+			if (!abortController.signal.aborted) abortController.abort(/* @__PURE__ */ new Error(`Flow execution timeout after ${config.timeout}ms`));
+		}, config.timeout);
+		let flowPromise;
+		let flowName;
+		if ("flow" in config) {
+			flowPromise = this["~executeFlow"](config.flow, config.input, config.tags, abortController);
+			flowName = flowDefinitionMeta.readFrom(config.flow)?.name;
+		} else {
+			flowPromise = Promised.create((async () => {
+				const deps = await this["~resolveDependencies"](config.dependencies, { [executorSymbol]: "main" });
+				if ("input" in config) return config.fn(deps, config.input);
+				else return config.fn(deps);
+			})());
+			flowName = void 0;
 		}
-		return this["~executeFlow"](flow$1, input, options?.tags);
+		const execution = new FlowExecutionImpl({
+			id: executionId,
+			flowName,
+			abort: abortController,
+			result: flowPromise,
+			ctx: null,
+			statusTracking: {
+				promise: flowPromise,
+				timeoutId: timeoutId ?? null,
+				abortController
+			}
+		});
+		this.executions.set(executionId, {
+			execution,
+			startTime: Date.now()
+		});
+		flowPromise.finally(() => {
+			this.executions.delete(executionId);
+		});
+		execution["~setStatus"]("running");
+		return execution;
 	}
-	"~executeFlow"(flow$1, input, executionTags) {
+	"~executeFlow"(flow$1, input, executionTags, abortController) {
 		let resolveSnapshot;
 		const snapshotPromise = new Promise((resolve) => {
 			resolveSnapshot = resolve;
 		});
 		const promise = (async () => {
-			const context = new FlowContext(this, this.extensions, executionTags);
+			const context = new FlowContext(this, this.extensions, executionTags, void 0, abortController);
 			try {
 				const executeCore = () => {
 					return this.resolve(flow$1).map(async (handler) => {

package/dist/index.d.cts

@@ -229,14 +229,25 @@ declare namespace Core {
     onError<T>(executor: Executor<T>, callback: ErrorCallback<T>): Cleanup;
     onError(callback: GlobalErrorCallback): Cleanup;
     useExtension(extension: Extension.Extension): Cleanup;
-    exec<S, I = undefined>(flow: Core.Executor<Flow.Handler<S, I>>, input?: I, options?: {
+    exec<S, I>(config: {
+      flow: Executor<Flow.Handler<S, I>>;
+      input?: I;
+      timeout?: number;
       tags?: Tag.Tagged[];
-      details?: false;
-    }): Promised<S>;
-    exec<S, I = undefined>(flow: Core.Executor<Flow.Handler<S, I>>, input: I | undefined, options: {
+    }): Flow.FlowExecution<S>;
+    exec<S, D extends DependencyLike>(config: {
+      dependencies: D;
+      fn: (deps: InferOutput<D>) => S | Promise<S>;
+      timeout?: number;
       tags?: Tag.Tagged[];
-      details: true;
-    }): Promised<Flow.ExecutionDetails<S>>;
+    }): Flow.FlowExecution<S>;
+    exec<S, I, D extends DependencyLike>(config: {
+      dependencies: D;
+      fn: (deps: InferOutput<D>, input: I) => S | Promise<S>;
+      input: I;
+      timeout?: number;
+      tags?: Tag.Tagged[];
+    }): Flow.FlowExecution<S>;
   }
 }
 declare class FlowError extends Error {
@@ -306,14 +317,38 @@ declare namespace Flow {
   type C = {
     readonly scope: Core.Scope;
     readonly tags: Tag.Tagged[] | undefined;
+    readonly signal: AbortSignal;
+    throwIfAborted(): void;
     get<T>(accessor: Tag.Tag<T, false> | Tag.Tag<T, true>): T;
     find<T>(accessor: Tag.Tag<T, false>): T | undefined;
     find<T>(accessor: Tag.Tag<T, true>): T;
     set<T>(accessor: Tag.Tag<T, false> | Tag.Tag<T, true>, value: T): void;
-    run<T>(key: string, fn: () => Promised<T> | T): Promised<T>;
-    run<T, P extends readonly unknown[]>(key: string, fn: (...args: P) => Promised<T> | T, ...params: P): Promised<T>;
     exec<F extends UFlow>(flow: F, input: InferInput<F>): Promised<InferOutput<F>>;
     exec<F extends UFlow>(key: string, flow: F, input: InferInput<F>): Promised<InferOutput<F>>;
+    exec<F extends UFlow>(config: {
+      flow: F;
+      input: InferInput<F>;
+      key?: string;
+      timeout?: number;
+      retry?: number;
+      tags?: Tag.Tagged[];
+    }): Promised<InferOutput<F>>;
+    exec<T>(config: {
+      fn: () => T | Promise<T>;
+      params?: never;
+      key?: string;
+      timeout?: number;
+      retry?: number;
+      tags?: Tag.Tagged[];
+    }): Promised<T>;
+    exec<Fn extends (...args: any[]) => any>(config: {
+      fn: Fn;
+      params: Parameters<Fn>;
+      key?: string;
+      timeout?: number;
+      retry?: number;
+      tags?: Tag.Tagged[];
+    }): Promised<ReturnType<Fn>>;
     parallel<T extends readonly Promised<any>[]>(promises: [...T]): Promised<ParallelResult<{ [K in keyof T]: T[K] extends Promised<infer R> ? R : never }>>;
     parallelSettled<T extends readonly Promised<any>[]>(promises: [...T]): Promised<ParallelSettledResult<{ [K in keyof T]: T[K] extends Promised<infer R> ? R : never }>>;
   };
@@ -334,6 +369,18 @@ declare namespace Flow {
     error: unknown;
     ctx: ExecutionData;
   };
+  type ExecutionStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
+  interface FlowExecution<T> {
+    readonly result: Promised<T>;
+    readonly id: string;
+    readonly flowName: string | undefined;
+    readonly status: ExecutionStatus;
+    readonly ctx: ExecutionData | undefined;
+    readonly abort: AbortController;
+    readonly statusCallbackErrors: readonly Error[];
+    onStatusChange(callback: (status: ExecutionStatus, execution: FlowExecution<T>) => void | Promise<void>): Core.Cleanup;
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null | undefined): PromiseLike<TResult1 | TResult2>;
+  }
 }
 declare namespace Extension {
   type Operation = {