@wooksjs/event-wf 0.6.6 → 0.7.0

package/README.md

@@ -1,7 +1,5 @@
 # @wooksjs/event-wf
 
-**!!! This is work-in-progress library, breaking changes are expected !!!**
-
 <p align="center">
 <img src="../../wooks-logo.png" width="450px"><br>
 <a  href="https://github.com/wooksjs/wooksjs/blob/main/LICENSE">
@@ -9,71 +7,17 @@
 </a>
 </p>
 
-The `@wooksjs/event-wf` is a component of the `wooks` event processing framework built on top of [@prostojs/wf](https://github.com/prostojs/wf). It provides a way to manage complex workflows and processes using the underlying workflow engine.
-
-The primary features of `@wooksjs/event-wf` include:
-
-- Support for conditional workflow branching based on dynamic conditions.
-- Support for parametric steps and workflows.
-- Support for user input requirements and interaction during the workflows.
+Workflow event processing for the Wooks framework. Manage complex workflows with conditional branching, parametric steps, and user input requirements, built on top of [@prostojs/wf](https://github.com/prostojs/wf).
 
 ## Installation
 
-To install `@wooksjs/event-wf`, you can use npm:
-
 ```sh
-npm install wooks @wooksjs/event-wf
-```
-
-## Quick Start
-
-```js
-import { useRouteParams } from '@wooksjs/event-core'
-import { createWfApp } from '@wooksjs/event-wf'
-
-const app = createWfApp<{ result: number }>()
-
-app.step('add', {
-    input: 'number',
-    handler: 'ctx.result += input',
-})
-
-app.step('add/:n', {
-    handler: (ctx) => {
-        ctx.result += Number(useRouteParams().get('n'))
-    },
-})
-
-app.flow('adding', [
-    { id: 'add', input: 5 },
-    { id: 'add', input: 2 },
-    {
-        condition: 'result < 10',
-        steps: [{ id: 'add', input: 3 }, { id: 'add', input: 4 }],
-    },
-])
-
-app.flow('adding-parametric', [
-    'add/5',
-    'add/2',
-    {
-        condition: 'result < 10',
-        steps: ['add/3', 'add/4'],
-    },
-])
-
-// Run the 'adding' workflow
-const output = await app.start('adding', { result: 0 })
-console.log(output.state.context) // { result: 14 }
+npm install @wooksjs/event-wf
 ```
 
 ## Documentation
 
-For more detailed documentation, please visit [wooks.moost.org](https://wooks.moost.org/wf/).
-
-## Contributing
-
-Contributions to the `@wooksjs/event-wf` project are welcome. If you find any bugs or have a feature request, please open an issue on [the GitHub repository](https://github.com/wooksjs/wooksjs).
+For full documentation, visit [wooks.moost.org/wf](https://wooks.moost.org/wf/).
 
 ## AI Agent Skills
 
@@ -81,10 +25,10 @@ This package ships with structured skill files for AI coding agents (Claude Code
 
 ```bash
 # Project-local (recommended — version-locked, commits with your repo)
-npx @wooksjs/event-wf setup-skills
+npx wooksjs-event-wf-skill
 
 # Global (available across all your projects)
-npx @wooksjs/event-wf setup-skills --global
+npx wooksjs-event-wf-skill --global
 ```
 
 To keep skills automatically up-to-date, add a postinstall script to your `package.json`:
@@ -92,13 +36,11 @@ To keep skills automatically up-to-date, add a postinstall script to your `packa
 ```json
 {
   "scripts": {
-    "postinstall": "npx @wooksjs/event-wf setup-skills --postinstall"
+    "postinstall": "wooksjs-event-wf-skill --postinstall"
   }
 }
 ```
 
-This ensures the skill files are refreshed whenever dependencies are installed, without needing a separate command.
-
 ## License
 
-`@wooksjs/event-wf` is licensed under the [MIT license](https://github.com/wooksjs/wooksjs/blob/main/LICENSE).
+MIT

package/dist/index.cjs

@@ -6,11 +6,11 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key$1; i < n; i++) {
+		key$1 = keys[i];
+		if (!__hasOwnProp.call(to, key$1) && key$1 !== except) __defProp(to, key$1, {
+			get: ((k) => from[k]).bind(null, key$1),
+			enumerable: !(desc = __getOwnPropDesc(from, key$1)) || desc.enumerable
 		});
 	}
 	return to;
@@ -25,37 +25,15 @@ const __wooksjs_event_core = __toESM(require("@wooksjs/event-core"));
 const __prostojs_wf = __toESM(require("@prostojs/wf"));
 const wooks = __toESM(require("wooks"));
 
-//#region packages/event-wf/src/event-wf.ts
-/** Creates a new async event context for a fresh workflow execution. */
-function createWfContext(data, options) {
-	return (0, __wooksjs_event_core.createAsyncEventContext)({
-		event: {
-			...data,
-			type: "WF"
-		},
-		resume: false,
-		options
-	});
-}
-/** Creates an async event context for resuming a paused workflow. */
-function resumeWfContext(data, options) {
-	return (0, __wooksjs_event_core.createAsyncEventContext)({
-		event: {
-			...data,
-			type: "WF"
-		},
-		resume: true,
-		options
-	});
-}
-/**
-* Wrapper on top of useEventContext that provides
-* proper context types for WF event
-* @returns set of hooks { getCtx, restoreCtx, clearCtx, hookStore, getStore, setStore }
-*/
-function useWFContext() {
-	return (0, __wooksjs_event_core.useAsyncEventContext)("WF");
-}
+//#region packages/event-wf/src/wf-kind.ts
+const wfKind = (0, __wooksjs_event_core.defineEventKind)("WF", {
+	schemaId: (0, __wooksjs_event_core.slot)(),
+	stepId: (0, __wooksjs_event_core.slot)(),
+	inputContext: (0, __wooksjs_event_core.slot)(),
+	indexes: (0, __wooksjs_event_core.slot)(),
+	input: (0, __wooksjs_event_core.slot)()
+});
+const resumeKey = (0, __wooksjs_event_core.key)("wf.resume");
 
 //#endregion
 //#region packages/event-wf/src/composables/wf-state.ts
@@ -69,18 +47,58 @@ function useWFContext() {
 * ```
 */
 function useWfState() {
-	const { store, getCtx } = useWFContext();
-	const event = store("event");
+	const c = (0, __wooksjs_event_core.current)();
 	return {
-		ctx: () => event.get("inputContext"),
-		input: () => event.get("input"),
-		schemaId: event.get("schemaId"),
-		stepId: () => event.get("stepId"),
-		indexes: () => event.get("indexes"),
-		resume: getCtx().resume
+		ctx: () => c.get(wfKind.keys.inputContext),
+		input: () => c.get(wfKind.keys.input),
+		schemaId: c.get(wfKind.keys.schemaId),
+		stepId: () => c.get(wfKind.keys.stepId),
+		indexes: () => c.get(wfKind.keys.indexes),
+		resume: c.get(resumeKey)
 	};
 }
 
+//#endregion
+//#region packages/event-wf/src/event-wf.ts
+const wfSeeds = (data) => ({
+	schemaId: data.schemaId,
+	stepId: data.stepId,
+	inputContext: data.inputContext,
+	indexes: data.indexes,
+	input: data.input
+});
+/**
+* Creates a new event context for a fresh workflow execution.
+* When `parentCtx` is provided, the workflow creates a child context
+* linked to the parent, so step handlers can transparently access
+* composables from the parent scope (e.g. HTTP) via the parent chain.
+*/
+function createWfContext(data, options, parentCtx) {
+	const ctx = new __wooksjs_event_core.EventContext(parentCtx ? {
+		...options,
+		parent: parentCtx
+	} : options);
+	return (fn) => (0, __wooksjs_event_core.run)(ctx, () => {
+		ctx.set(resumeKey, false);
+		return ctx.seed(wfKind, wfSeeds(data), fn);
+	});
+}
+/**
+* Creates an event context for resuming a paused workflow.
+* When `parentCtx` is provided, the workflow creates a child context
+* linked to the parent.
+*/
+function resumeWfContext(data, options, parentCtx) {
+	const ctx = new __wooksjs_event_core.EventContext(parentCtx ? {
+		...options,
+		parent: parentCtx
+	} : options);
+	return (fn) => (0, __wooksjs_event_core.run)(ctx, () => {
+		ctx.set(resumeKey, true);
+		return ctx.seed(wfKind, wfSeeds(data), fn);
+	});
+}
+
 //#endregion
 //#region packages/event-wf/src/workflow.ts
 /** Workflow engine that resolves steps via Wooks router lookup. */
@@ -92,10 +110,10 @@ var WooksWorkflow = class extends __prostojs_wf.Workflow {
 	resolveStep(stepId) {
 		const stepIdNorm = `/${stepId}`.replace(/\/{2,}/gu, "/");
 		try {
-			const store = useWFContext().store("event");
+			const ctx = (0, __wooksjs_event_core.current)();
 			const found = this.wooks.lookup("WF_STEP", stepIdNorm);
 			if (found.handlers?.length) {
-				store.set("stepId", stepIdNorm);
+				ctx.set(wfKind.keys.stepId, stepIdNorm);
 				return found.handlers[0]();
 			}
 		} catch {
@@ -145,15 +163,40 @@ var WooksWf = class extends wooks.WooksAdapterBase {
 			id
 		}));
 	}
-	/** Starts a new workflow execution from the beginning. */
-	start(schemaId, inputContext, input, spy, cleanup) {
-		return this._start(schemaId, inputContext, void 0, input, spy, cleanup);
+	/**
+	* Starts a new workflow execution from the beginning.
+	*
+	* @example
+	* ```ts
+	* // Simple
+	* await app.start('my-flow', { result: 0 })
+	*
+	* // With options
+	* await app.start('my-flow', { result: 0 }, { input: 5, eventContext: current() })
+	* ```
+	*/
+	start(schemaId, inputContext, opts) {
+		const parentCtx = opts?.eventContext;
+		return this._start(schemaId, inputContext, void 0, opts, parentCtx);
 	}
-	/** Resumes a previously paused workflow from saved state. */
-	resume(state, input, spy, cleanup) {
-		return this._start(state.schemaId, state.context, state.indexes, input, spy, cleanup);
+	/**
+	* Resumes a previously paused workflow from saved state.
+	*
+	* @example
+	* ```ts
+	* // With user input
+	* await app.resume(output.state, { input: userInput })
+	*
+	* // Simple retry (no input)
+	* await app.resume(output.state)
+	* ```
+	*/
+	resume(state, opts) {
+		const parentCtx = opts?.eventContext;
+		return this._start(state.schemaId, state.context, state.indexes, opts, parentCtx);
 	}
-	async _start(schemaId, inputContext, indexes, input, spy, cleanup) {
+	async _start(schemaId, inputContext, indexes, opts, parentCtx) {
+		const { input, spy, cleanup } = opts ?? {};
 		const resume = !!indexes?.length;
 		const runInContext = (resume ? resumeWfContext : createWfContext)({
 			inputContext,
@@ -161,7 +204,7 @@ var WooksWf = class extends wooks.WooksAdapterBase {
 			stepId: null,
 			indexes,
 			input
-		}, this.mergeEventOptions(this.opts?.eventOptions));
+		}, this.getEventContextOptions(), parentCtx);
 		return runInContext(async () => {
 			const { handlers: foundHandlers } = this.wooks.lookup("WF_FLOW", `/${schemaId}`.replace(/^\/+/u, "/"));
 			const handlers = foundHandlers || this.opts?.onNotFound && [this.opts.onNotFound] || null;
@@ -172,8 +215,8 @@ var WooksWf = class extends wooks.WooksAdapterBase {
 					if (spy) spy(...args);
 					if (firstStep && args[0] === "step") {
 						firstStep = false;
-						const { store } = useWFContext();
-						store("event").set("input", void 0);
+						const ctx = (0, __wooksjs_event_core.current)();
+						ctx.set(wfKind.keys.input, void 0);
 					}
 				};
 				try {
@@ -197,7 +240,11 @@ var WooksWf = class extends wooks.WooksAdapterBase {
 					throw error;
 				}
 				clean();
-				if (result.resume) result.resume = (_input) => this.resume(result.state, _input, spy, cleanup);
+				if (result.resume) result.resume = (_input) => this.resume(result.state, {
+					input: _input,
+					spy,
+					cleanup
+				});
 				return result;
 			}
 			clean();
@@ -228,7 +275,7 @@ var WooksWf = class extends wooks.WooksAdapterBase {
 * ```ts
 * const app = createWfApp()
 * app.step('process', { handler: (ctx) => ctx })
-* app.flow('my-flow', [{ step: 'process' }])
+* app.flow('my-flow', ['process'])
 * await app.start('my-flow', { data: 'hello' })
 * ```
 */
@@ -246,7 +293,20 @@ Object.defineProperty(exports, 'StepRetriableError', {
 exports.WooksWf = WooksWf;
 exports.createWfApp = createWfApp;
 exports.createWfContext = createWfContext;
+exports.resumeKey = resumeKey;
 exports.resumeWfContext = resumeWfContext;
-exports.useWFContext = useWFContext;
+Object.defineProperty(exports, 'useLogger', {
+  enumerable: true,
+  get: function () {
+    return __wooksjs_event_core.useLogger;
+  }
+});
+Object.defineProperty(exports, 'useRouteParams', {
+  enumerable: true,
+  get: function () {
+    return __wooksjs_event_core.useRouteParams;
+  }
+});
 exports.useWfState = useWfState;
+exports.wfKind = wfKind;
 exports.wfShortcuts = wfShortcuts;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as _wooksjs_event_core from '@wooksjs/event-core';
-import { TEventOptions, TEmpty } from '@wooksjs/event-core';
+import { EventContextOptions, EventContext } from '@wooksjs/event-core';
+export { EventContext, EventContextOptions, useLogger, useRouteParams } from '@wooksjs/event-core';
 import * as wooks from 'wooks';
 import { Wooks, TWooksHandler, TWooksOptions, WooksAdapterBase } from 'wooks';
 import { TConsoleBase } from '@prostojs/logger';
@@ -18,36 +19,34 @@ export { StepRetriableError, TStepHandler, TWorkflowSchema } from '@prostojs/wf'
 declare function useWfState(): {
     ctx: <T>() => T;
     input: <I>() => I | undefined;
-    schemaId: string | undefined;
-    stepId: () => string | null | undefined;
+    schemaId: string;
+    stepId: () => string | null;
     indexes: () => number[] | undefined;
     resume: boolean;
 };
 
-/** Event data describing a workflow execution instance. */
-interface TWFEventData {
+/** Input data for creating a workflow event context. */
+interface TWFEventInput {
     schemaId: string;
     stepId: string | null;
     inputContext: unknown;
     indexes?: number[];
     input?: unknown;
-    type: 'WF';
-}
-/** Context store for workflow events, tracking resume state. */
-interface TWFContextStore {
-    resume: boolean;
 }
 
-/** Creates a new async event context for a fresh workflow execution. */
-declare function createWfContext(data: Omit<TWFEventData, 'type'>, options: TEventOptions): <T>(cb: (...a: unknown[]) => T) => T;
-/** Creates an async event context for resuming a paused workflow. */
-declare function resumeWfContext(data: Omit<TWFEventData, 'type'>, options: TEventOptions): <T>(cb: (...a: unknown[]) => T) => T;
 /**
- * Wrapper on top of useEventContext that provides
- * proper context types for WF event
- * @returns set of hooks { getCtx, restoreCtx, clearCtx, hookStore, getStore, setStore }
+ * Creates a new event context for a fresh workflow execution.
+ * When `parentCtx` is provided, the workflow creates a child context
+ * linked to the parent, so step handlers can transparently access
+ * composables from the parent scope (e.g. HTTP) via the parent chain.
  */
-declare function useWFContext<T extends TEmpty>(): _wooksjs_event_core.TCtxHelpers<TWFContextStore & T & _wooksjs_event_core.TGenericContextStore<TWFEventData>>;
+declare function createWfContext(data: TWFEventInput, options: EventContextOptions, parentCtx?: EventContext): <R>(fn: () => R) => R;
+/**
+ * Creates an event context for resuming a paused workflow.
+ * When `parentCtx` is provided, the workflow creates a child context
+ * linked to the parent.
+ */
+declare function resumeWfContext(data: TWFEventInput, options: EventContextOptions, parentCtx?: EventContext): <R>(fn: () => R) => R;
 
 /** Workflow engine that resolves steps via Wooks router lookup. */
 declare class WooksWorkflow<T, IR> extends Workflow<T, IR> {
@@ -67,9 +66,26 @@ interface TWooksWfOptions {
     onNotFound?: TWooksHandler;
     onUnknownFlow?: (schemaId: string, raiseError: () => void) => unknown;
     logger?: TConsoleBase;
-    eventOptions?: TEventOptions;
+    eventOptions?: EventContextOptions;
     router?: TWooksOptions['router'];
 }
+/** Options for {@link WooksWf.start} and {@link WooksWf.resume}. */
+interface TWfRunOptions<I = unknown, T = unknown, IR = unknown> {
+    /** Input for the current step (consumed after execution). */
+    input?: I;
+    /** Spy function to observe step execution. */
+    spy?: TWorkflowSpy<T, I, IR>;
+    /** Cleanup function called when execution ends. */
+    cleanup?: () => void;
+    /**
+     * Parent event context. When provided, the workflow creates a child context
+     * linked to this parent, so step handlers can transparently read composables
+     * from the parent scope (e.g. HTTP composables) via the parent chain.
+     *
+     * Pass `current()` from within an active event scope (HTTP handler, etc.).
+     */
+    eventContext?: EventContext;
+}
 /** Wooks adapter for defining and executing workflow schemas with step-based routing. */
 declare class WooksWf<T = any, IR = any> extends WooksAdapterBase {
     protected opts?: TWooksWfOptions | undefined;
@@ -87,15 +103,37 @@ declare class WooksWf<T = any, IR = any> extends WooksAdapterBase {
     }): wooks.TProstoRouterPathHandle<Record<string, string | string[]>>;
     /** Registers a workflow flow schema with the given id. */
     flow(id: string, schema: TWorkflowSchema<T>, prefix?: string, init?: () => void | Promise<void>): wooks.TProstoRouterPathHandle<Record<string, string | string[]>>;
-    /** Starts a new workflow execution from the beginning. */
-    start<I>(schemaId: string, inputContext: T, input?: I, spy?: TWorkflowSpy<T, I, IR>, cleanup?: () => void): Promise<TFlowOutput<T, I, IR>>;
-    /** Resumes a previously paused workflow from saved state. */
+    /**
+     * Starts a new workflow execution from the beginning.
+     *
+     * @example
+     * ```ts
+     * // Simple
+     * await app.start('my-flow', { result: 0 })
+     *
+     * // With options
+     * await app.start('my-flow', { result: 0 }, { input: 5, eventContext: current() })
+     * ```
+     */
+    start<I>(schemaId: string, inputContext: T, opts?: TWfRunOptions<I, T, IR>): Promise<TFlowOutput<T, I, IR>>;
+    /**
+     * Resumes a previously paused workflow from saved state.
+     *
+     * @example
+     * ```ts
+     * // With user input
+     * await app.resume(output.state, { input: userInput })
+     *
+     * // Simple retry (no input)
+     * await app.resume(output.state)
+     * ```
+     */
     resume<I>(state: {
         schemaId: string;
         indexes: number[];
         context: T;
-    }, input?: I, spy?: TWorkflowSpy<T, I, IR>, cleanup?: () => void): Promise<TFlowOutput<T, I, IR>>;
-    protected _start<I>(schemaId: string, inputContext: T, indexes?: number[], input?: I, spy?: TWorkflowSpy<T, I, IR>, cleanup?: () => void): Promise<TFlowOutput<T, I, IR>>;
+    }, opts?: TWfRunOptions<I, T, IR>): Promise<TFlowOutput<T, I, IR>>;
+    protected _start<I>(schemaId: string, inputContext: T, indexes?: number[], opts?: TWfRunOptions<I, T, IR>, parentCtx?: EventContext): Promise<TFlowOutput<T, I, IR>>;
     protected onError(e: Error): void;
     protected error(e: string | Error): void;
 }
@@ -108,11 +146,20 @@ declare class WooksWf<T = any, IR = any> extends WooksAdapterBase {
  * ```ts
  * const app = createWfApp()
  * app.step('process', { handler: (ctx) => ctx })
- * app.flow('my-flow', [{ step: 'process' }])
+ * app.flow('my-flow', ['process'])
  * await app.start('my-flow', { data: 'hello' })
  * ```
  */
 declare function createWfApp<T>(opts?: TWooksWfOptions, wooks?: Wooks | WooksAdapterBase): WooksWf<T, any>;
 
-export { WooksWf, createWfApp, createWfContext, resumeWfContext, useWFContext, useWfState, wfShortcuts };
-export type { TWFContextStore, TWFEventData, TWooksWfOptions };
+declare const wfKind: _wooksjs_event_core.EventKind<{
+    schemaId: _wooksjs_event_core.SlotMarker<string>;
+    stepId: _wooksjs_event_core.SlotMarker<string | null>;
+    inputContext: _wooksjs_event_core.SlotMarker<unknown>;
+    indexes: _wooksjs_event_core.SlotMarker<number[] | undefined>;
+    input: _wooksjs_event_core.SlotMarker<unknown>;
+}>;
+declare const resumeKey: _wooksjs_event_core.Key<boolean>;
+
+export { WooksWf, createWfApp, createWfContext, resumeKey, resumeWfContext, useWfState, wfKind, wfShortcuts };
+export type { TWFEventInput, TWfRunOptions, TWooksWfOptions };