0.1.3. (#1)

* 0.1.3.

Author: b4rtaz

.github/workflows/main.yml

@@ -1,9 +1,11 @@
 name: main
 on:
+  pull_request:
+    branches:
+      - main
   push:
     branches:
       - main
-      - develop
 jobs:
   build:
     name: Build

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.1.3
+
+Added two new activities: `LoopActivity` and `BreakActivity`.
+
 ## 0.1.2
 
 Changed bundle format of the `sequential-workflow-machine` package to: UMD, ESM and CommonJS.

machine/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "sequential-workflow-machine",
 	"description": "Powerful sequential workflow machine for frontend and backend applications.",
-	"version": "0.1.2",
+	"version": "0.1.3",
 	"type": "module",
 	"main": "./lib/esm/index.js",
 	"types": "./lib/index.d.ts",
@@ -44,7 +44,7 @@
 	},
 	"peerDependencies": {
 		"sequential-workflow-model": "^0.1.1",
-		"xstate": "^4.37.0"
+		"xstate": "^4.37.2"
 	},
 	"devDependencies": {
 		"@types/jest": "^29.4.0",
@@ -60,7 +60,7 @@
 		"rollup-plugin-typescript2": "^0.34.1",
 		"@rollup/plugin-node-resolve": "^15.0.1",
 		"sequential-workflow-model": "^0.1.1",
-		"xstate": "^4.37.0"
+		"xstate": "^4.37.2"
 	},
 	"keywords": [
 		"workflow",

machine/src/activities/break-activity/break-activity-node-builder.ts

@@ -0,0 +1,62 @@
+import { BreakActivityConfig, BreakActivityState } from './types';
+import { getLoopStack } from '../loop-stack';
+import { Step } from 'sequential-workflow-model';
+import {
+	ActivityNodeBuilder,
+	ActivityNodeConfig,
+	BuildingContext,
+	MachineContext,
+	STATE_FAILED_TARGET,
+	STATE_INTERRUPTED_TARGET
+} from '../../types';
+import { ActivityStateAccessor, catchUnhandledError, getStepNodeId } from '../../core';
+import { isInterruptResult } from '../results';
+import { isBreakResult } from './break-result';
+
+export class BreakActivityNodeBuilder<TStep extends Step, GlobalState, ActivityState> implements ActivityNodeBuilder<GlobalState> {
+	public constructor(
+		private readonly activityStateAccessor: ActivityStateAccessor<GlobalState, BreakActivityState<ActivityState>>,
+		private readonly config: BreakActivityConfig<TStep, GlobalState, ActivityState>
+	) {}
+
+	public build(step: TStep, nextNodeTarget: string, buildingContext: BuildingContext): ActivityNodeConfig<GlobalState> {
+		const nodeId = getStepNodeId(step.id);
+
+		const loopName = this.config.loopName(step);
+		const leaveNodeTarget = getLoopStack(buildingContext).getNodeTarget(loopName);
+
+		return {
+			id: nodeId,
+			invoke: {
+				src: catchUnhandledError(async (context: MachineContext<GlobalState>) => {
+					const internalState = this.activityStateAccessor.get(context, nodeId);
+
+					const result = await this.config.handler(step, context.globalState, internalState.activityState);
+					if (isInterruptResult(result)) {
+						context.interrupted = nodeId;
+						return;
+					}
+
+					internalState.break = isBreakResult(result);
+				}),
+				onDone: [
+					{
+						target: STATE_INTERRUPTED_TARGET,
+						cond: (context: MachineContext<GlobalState>) => Boolean(context.interrupted)
+					},
+					{
+						target: leaveNodeTarget,
+						cond: (context: MachineContext<GlobalState>) => {
+							const internalState = this.activityStateAccessor.get(context, nodeId);
+							return Boolean(internalState.break);
+						}
+					},
+					{
+						target: nextNodeTarget
+					}
+				],
+				onError: STATE_FAILED_TARGET
+			}
+		};
+	}
+}

machine/src/activities/break-activity/break-activity.spec.ts

@@ -0,0 +1,113 @@
+import { Definition, Sequence, SequentialStep, Step } from 'sequential-workflow-model';
+import { createLoopActivity } from '../loop-activity/loop-activity';
+import { createBreakActivity } from './break-activity';
+import { createActivitySet } from '../../core';
+import { createAtomActivity } from '../atom-activity';
+import { createWorkflowMachineBuilder } from '../../workflow-machine-builder';
+import { STATE_FINISHED_ID } from '../../types';
+import { break_ } from './break-result';
+
+interface TestGlobalState {
+	alfa: number;
+	trace: string;
+}
+
+function createLoopStep(id: string, loopName: string, sequence: Sequence): SequentialStep {
+	return {
+		id,
+		componentType: 'container',
+		type: 'loop',
+		sequence,
+		name: 'Loop',
+		properties: {
+			loopName
+		}
+	};
+}
+
+function createDecrementStep(id: string): Step {
+	return {
+		id,
+		componentType: 'task',
+		type: 'decrement',
+		name: 'Decrement',
+		properties: {}
+	};
+}
+
+function createBreakIfZeroStep(id: string, loopName: string): Step {
+	return {
+		id,
+		componentType: 'task',
+		type: 'breakIfZero',
+		name: 'Break',
+		properties: {
+			loopName
+		}
+	};
+}
+
+const definition: Definition = {
+	sequence: [createLoopStep('0x001', 'LOOP_1', [createDecrementStep('0x002'), createBreakIfZeroStep('0x003', 'LOOP_1')])],
+	properties: {}
+};
+
+const activitySet = createActivitySet<TestGlobalState>([
+	createLoopActivity<SequentialStep, TestGlobalState>({
+		stepType: 'loop',
+		loopName: step => String(step.properties['loopName']),
+		init: () => ({}),
+		condition: async (_, globalState) => {
+			globalState.trace += '(condition)';
+			return true;
+		}
+	}),
+
+	createAtomActivity({
+		stepType: 'decrement',
+		init: () => null,
+		handler: async (_, globalState) => {
+			globalState.trace += '(decrement)';
+			globalState.alfa--;
+		}
+	}),
+
+	createBreakActivity({
+		stepType: 'breakIfZero',
+		init: () => null,
+		handler: async (_, globalState) => {
+			globalState.trace += '(break)';
+			if (globalState.alfa === 0) {
+				return break_();
+			}
+		},
+		loopName: step => String(step.properties['loopName'])
+	})
+]);
+
+describe('BreakActivity', () => {
+	it('should break loop', done => {
+		const builder = createWorkflowMachineBuilder(activitySet);
+		const machine = builder.build(definition);
+		const interpreter = machine
+			.create({
+				init: () => ({
+					alfa: 3,
+					trace: ''
+				})
+			})
+			.start();
+
+		interpreter.onDone(() => {
+			const snapshot = interpreter.getSnapshot();
+
+			expect(snapshot.statePath[0]).toBe(STATE_FINISHED_ID);
+			expect(snapshot.globalState.trace).toBe(
+				'(condition)(decrement)(break)(condition)(decrement)(break)(condition)(decrement)(break)'
+			);
+			expect(snapshot.globalState.alfa).toBe(0);
+
+			done();
+		});
+	});
+});

machine/src/activities/break-activity/break-activity.ts

@@ -0,0 +1,18 @@
+import { BreakActivityConfig, BreakActivityState } from './types';
+import { BreakActivityNodeBuilder } from './break-activity-node-builder';
+import { Step } from 'sequential-workflow-model';
+import { Activity } from '../../types';
+import { ActivityStateAccessor } from '../../core';
+
+export function createBreakActivity<TStep extends Step = Step, GlobalState = object, ActivityState = object>(
+	config: BreakActivityConfig<TStep, GlobalState, ActivityState>
+): Activity<GlobalState> {
+	const activityStateAccessor = new ActivityStateAccessor<GlobalState, BreakActivityState<ActivityState>>(globalState => ({
+		activityState: config.init(globalState)
+	}));
+
+	return {
+		stepType: config.stepType,
+		nodeBuilderFactory: () => new BreakActivityNodeBuilder(activityStateAccessor, config)
+	};
+}

machine/src/activities/break-activity/break-result.ts

@@ -0,0 +1,11 @@
+export interface BreakResult {
+	break: true;
+}
+
+export function isBreakResult(result: unknown): result is BreakResult {
+	return typeof result === 'object' && (result as BreakResult).break;
+}
+
+export function break_(): BreakResult {
+	return { break: true };
+}

machine/src/activities/break-activity/index.ts

@@ -0,0 +1,3 @@
+export * from './break-activity';
+export * from './break-result';
+export * from './types';

machine/src/activities/break-activity/types.ts

@@ -0,0 +1,23 @@
+import { Step } from 'sequential-workflow-model';
+import { ActivityConfig, ActivityStateInitializer } from '../../types';
+import { InterruptResult } from '../results';
+import { BreakResult } from './break-result';
+
+export type BreakActivityHandler<TStep extends Step, GlobalState, ActivityState> = (
+	step: TStep,
+	globalState: GlobalState,
+	activityState: ActivityState
+) => Promise<BreakActivityHandlerResult>;
+
+export type BreakActivityHandlerResult = void | InterruptResult | BreakResult;
+
+export interface BreakActivityConfig<TStep extends Step, GlobalState, ActivityState> extends ActivityConfig<TStep> {
+	loopName: (step: TStep) => string;
+	init: ActivityStateInitializer<GlobalState, ActivityState>;
+	handler: BreakActivityHandler<TStep, GlobalState, ActivityState>;
+}
+
+export interface BreakActivityState<ActivityState> {
+	break?: boolean;
+	activityState: ActivityState;
+}

machine/src/activities/index.ts

@@ -1,5 +1,7 @@
 export * from './atom-activity';
+export * from './break-activity';
 export * from './container-activity';
 export * from './fork-activity';
 export * from './interruption-activity';
+export * from './loop-activity';
 export * from './results';

machine/src/activities/loop-activity/index.ts

@@ -0,0 +1,2 @@
+export * from './loop-activity';
+export * from './types';

machine/src/activities/loop-activity/loop-activity-node-builder.ts

@@ -0,0 +1,104 @@
+import { SequentialStep } from 'sequential-workflow-model';
+import { getLoopStack } from '../loop-stack';
+import { LoopActivityConfig, LoopActivityState } from './types';
+import { ActivityStateAccessor, SequenceNodeBuilder, catchUnhandledError, getStepNodeId } from '../../core';
+import {
+	ActivityNodeBuilder,
+	ActivityNodeConfig,
+	BuildingContext,
+	MachineContext,
+	STATE_FAILED_TARGET,
+	STATE_INTERRUPTED_TARGET
+} from '../../types';
+import { isInterruptResult } from '../results';
+
+export class LoopActivityNodeBuilder<TStep extends SequentialStep, GlobalState, ActivityState> implements ActivityNodeBuilder<GlobalState> {
+	public constructor(
+		private readonly sequenceNodeBuilder: SequenceNodeBuilder<GlobalState>,
+		private readonly activityStateAccessor: ActivityStateAccessor<GlobalState, LoopActivityState<ActivityState>>,
+		private readonly config: LoopActivityConfig<TStep, GlobalState, ActivityState>
+	) {}
+
+	public build(step: TStep, nextNodeTarget: string, buildingContext: BuildingContext): ActivityNodeConfig<GlobalState> {
+		const nodeId = getStepNodeId(step.id);
+
+		const conditionNodeId = `CONDITION.${nodeId}`;
+		const conditionNodeTarget = `#${conditionNodeId}`;
+		const leaveNodeId = `LEAVE.${nodeId}`;
+		const leaveNodeTarget = `#${leaveNodeId}`;
+
+		const loopName = this.config.loopName(step);
+		const loopStack = getLoopStack(buildingContext);
+		loopStack.push(loopName, leaveNodeTarget);
+
+		const LOOP = this.sequenceNodeBuilder.build(buildingContext, step.sequence, conditionNodeTarget);
+
+		loopStack.pop();
+
+		return {
+			id: nodeId,
+			initial: 'ENTER',
+			states: {
+				ENTER: {
+					invoke: {
+						src: catchUnhandledError(async (context: MachineContext<GlobalState>) => {
+							if (this.config.onEnter) {
+								const internalContext = this.activityStateAccessor.get(context, nodeId);
+								this.config.onEnter(step, context.globalState, internalContext.activityState);
+							}
+						}),
+						onDone: 'CONDITION',
+						onError: STATE_FAILED_TARGET
+					}
+				},
+				CONDITION: {
+					id: conditionNodeId,
+					invoke: {
+						src: catchUnhandledError(async (context: MachineContext<GlobalState>) => {
+							const internalState = this.activityStateAccessor.get(context, nodeId);
+
+							const result = await this.config.condition(step, context.globalState, internalState.activityState);
+							if (isInterruptResult(result)) {
+								context.interrupted = nodeId;
+								return;
+							}
+
+							internalState.continue = result;
+						}),
+						onDone: [
+							{
+								target: STATE_INTERRUPTED_TARGET,
+								cond: (context: MachineContext<GlobalState>) => Boolean(context.interrupted)
+							},
+							{
+								target: 'LOOP',
+								cond: (context: MachineContext<GlobalState>) => {
+									const activityState = this.activityStateAccessor.get(context, nodeId);
+									return Boolean(activityState.continue);
+								}
+							},
+							{
+								target: 'LEAVE'
+							}
+						],
+						onError: STATE_FAILED_TARGET
+					}
+				},
+				LOOP,
+				LEAVE: {
+					id: leaveNodeId,
+					invoke: {
+						src: catchUnhandledError(async (context: MachineContext<GlobalState>) => {
+							if (this.config.onLeave) {
+								const internalState = this.activityStateAccessor.get(context, nodeId);
+								this.config.onLeave(step, context.globalState, internalState.activityState);
+							}
+						}),
+						onDone: nextNodeTarget,
+						onError: STATE_FAILED_TARGET
+					}
+				}
+			}
+		};
+	}
+}