serenity-process 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Timber Kerkvliet
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,96 @@
1
- # Temporary Holding Version
1
+ # serenity-process
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A **Process** is like a [Serenity/JS](https://serenity-js.org) `Task`, but performed by
4
+ **several actors**, each playing a role.
5
+
6
+ ```ts
7
+ import { Process, step } from 'serenity-process';
8
+
9
+ const escalation = Process.where('#customer raises an urgent ticket that #agent resolves',
10
+ step('customer', raiseTicket({ priority: 'urgent' })),
11
+ step('agent', resolveTicket()),
12
+ );
13
+
14
+ await When(escalation.with({ customer: chidi, agent: priya }));
15
+ ```
16
+
17
+ Report output reads: `Chidi, as customer, in: Chidi raises an urgent ticket that Priya resolves`.
18
+
19
+ ## Behaviour
20
+
21
+ - Steps run **in order**, one after another; the process **stops at the first failing step**.
22
+ - A role may appear in **more than one step**.
23
+ - Actors are bound only when running (`.with(...)`), so a process can be **reused** with other actors.
24
+ - `.with()` throws a `LogicError` if a role has no actor (and TypeScript checks the role names).
25
+ - `#role` in the description is replaced by the playing actor's name.
26
+ - `.with()` returns `() => Promise<void>`, so it can be passed straight to `Given`, `When` or `Then`.
27
+ - `process.roles()` lists the roles in order of first appearance.
28
+
29
+ ## Referring to other actors
30
+
31
+ `referringTo(...roles, activity)` builds an activity that refers to other actors. The names of the
32
+ actors playing those roles are passed to `activity` in the same order, so the parameters can be
33
+ named freely:
34
+
35
+ ```ts
36
+ import { Process, referringTo, step } from 'serenity-process';
37
+
38
+ const contest = Process.where('#jury judges #singer and #dancer',
39
+ step('singer', sing()),
40
+ step('dancer', dance()),
41
+ step('jury', referringTo('singer', 'dancer', (s, d) => Compare(s).with(d))),
42
+ );
43
+
44
+ await When(contest.with({ singer: piet, dancer: klaas, jury: han })); // Compare('Piet').with('Klaas')
45
+ ```
46
+
47
+ - Referred roles are roles of the process: TypeScript and `.with()` require an actor for them.
48
+ - TypeScript checks that the function takes as many names as there are roles.
49
+ - It can be mixed with plain activities in one step, and runs with the actors bound at run time.
50
+ - In a nested process, referred roles are mapped by `subprocess` like any other role.
51
+
52
+ ## Nested processes
53
+
54
+ A step can itself be a process. `subprocess(child, mapping)` binds the child's roles to roles of the
55
+ enclosing process:
56
+
57
+ ```ts
58
+ import { Process, step, subprocess } from 'serenity-process';
59
+
60
+ const purchase = Process.where('#buyer pays #seller',
61
+ step('buyer', pay()),
62
+ step('seller', ship()),
63
+ );
64
+
65
+ const checkout = Process.where('#customer checks out, #agent follows up',
66
+ step('customer', browse()),
67
+ subprocess(purchase, { buyer: 'customer', seller: 'agent' }),
68
+ step('agent', sendInvoice()),
69
+ );
70
+
71
+ await When(checkout.with({ customer: chidi, agent: priya }));
72
+ ```
73
+
74
+ - Child roles not listed in the mapping keep their name; with no mapping at all the roles pass straight through.
75
+ - Several child roles may map to the same parent role (one actor plays both).
76
+ - The parent's roles (and what `.with()` requires) are inferred by TypeScript, nested ones included.
77
+ - Nesting can go as deep as you like; the first failing step stops everything.
78
+ - Report descriptions show the path: `Priya, as seller, in: Chidi checks out, Priya follows up > Chidi pays Priya`.
79
+
80
+ ## Install
81
+
82
+ ```bash
83
+ npm install serenity-process
84
+ ```
85
+
86
+ Requires `@serenity-js/core` ^3 as a peer dependency.
87
+
88
+ ## Development
89
+
90
+ ```bash
91
+ npm install
92
+ npm test
93
+ npm run build
94
+ ```
95
+
96
+ MIT licensed.
@@ -0,0 +1,44 @@
1
+ import { RoleBindings, RolesOf, Step } from './Step';
2
+ /**
3
+ * Like a `Task`, but performed by several actors, each playing a role.
4
+ *
5
+ * The steps run in the order given, one after another, and the process stops at
6
+ * the first step that fails. A role may appear in more than one step. The actors
7
+ * are only chosen when the process is run, with {@link Process.with}, so the same
8
+ * process can be reused with other actors.
9
+ *
10
+ * In the description, `#role` is replaced by the name of the actor playing it.
11
+ * A step may itself be a process, see {@link subprocess}.
12
+ *
13
+ * @example
14
+ * const escalation = Process.where('#customer raises an urgent ticket that #agent resolves',
15
+ * step('customer', raiseTicket({ priority: 'urgent' })),
16
+ * step('agent', resolveTicket()),
17
+ * );
18
+ *
19
+ * await When(escalation.with({ customer: chidi, agent: priya }));
20
+ */
21
+ export declare class Process<Role extends string> {
22
+ private readonly description;
23
+ private readonly steps;
24
+ static where<Steps extends [Step<string>, ...Step<string>[]]>(description: string, ...steps: Steps): Process<RolesOf<Steps[number]>>;
25
+ private constructor();
26
+ /** The roles in this process, in order of first appearance. */
27
+ roles(): Role[];
28
+ /**
29
+ * Binds an actor to every role. Returns a function that runs the process,
30
+ * so it can be passed straight to `Given`, `When` or `Then`.
31
+ */
32
+ with(bindings: RoleBindings<Role>): () => Promise<void>;
33
+ /**
34
+ * Runs the steps in order with the given actors. `context` is the description
35
+ * of the enclosing process when this one is nested, and is used by
36
+ * {@link subprocess} - call {@link Process.with} instead.
37
+ *
38
+ * @internal
39
+ */
40
+ run(bindings: RoleBindings<Role>, context?: string): Promise<void>;
41
+ /** The description with every `#role` replaced by the name of its actor. */
42
+ describedFor(bindings: RoleBindings<Role>): string;
43
+ toString(): string;
44
+ }
package/lib/Process.js ADDED
@@ -0,0 +1,75 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.Process = void 0;
4
+ const core_1 = require("@serenity-js/core");
5
+ /**
6
+ * Like a `Task`, but performed by several actors, each playing a role.
7
+ *
8
+ * The steps run in the order given, one after another, and the process stops at
9
+ * the first step that fails. A role may appear in more than one step. The actors
10
+ * are only chosen when the process is run, with {@link Process.with}, so the same
11
+ * process can be reused with other actors.
12
+ *
13
+ * In the description, `#role` is replaced by the name of the actor playing it.
14
+ * A step may itself be a process, see {@link subprocess}.
15
+ *
16
+ * @example
17
+ * const escalation = Process.where('#customer raises an urgent ticket that #agent resolves',
18
+ * step('customer', raiseTicket({ priority: 'urgent' })),
19
+ * step('agent', resolveTicket()),
20
+ * );
21
+ *
22
+ * await When(escalation.with({ customer: chidi, agent: priya }));
23
+ */
24
+ class Process {
25
+ static where(description, ...steps) {
26
+ return new Process(description, steps);
27
+ }
28
+ constructor(description, steps) {
29
+ this.description = description;
30
+ this.steps = steps;
31
+ }
32
+ /** The roles in this process, in order of first appearance. */
33
+ roles() {
34
+ return [...new Set(this.steps.flatMap(s => s.roles))];
35
+ }
36
+ /**
37
+ * Binds an actor to every role. Returns a function that runs the process,
38
+ * so it can be passed straight to `Given`, `When` or `Then`.
39
+ */
40
+ with(bindings) {
41
+ const missing = this.roles().filter(name => !bindings[name]);
42
+ if (missing.length > 0) {
43
+ throw new core_1.LogicError(`Nobody plays ${missing.join(', ')} in "${this.description}"`);
44
+ }
45
+ return () => this.run(bindings);
46
+ }
47
+ /**
48
+ * Runs the steps in order with the given actors. `context` is the description
49
+ * of the enclosing process when this one is nested, and is used by
50
+ * {@link subprocess} - call {@link Process.with} instead.
51
+ *
52
+ * @internal
53
+ */
54
+ async run(bindings, context) {
55
+ const own = this.describedFor(bindings);
56
+ const description = context ? `${context} > ${own}` : own;
57
+ for (const s of this.steps) {
58
+ await s.perform(bindings, description);
59
+ }
60
+ }
61
+ /** The description with every `#role` replaced by the name of its actor. */
62
+ describedFor(bindings) {
63
+ return this.roles()
64
+ // longest first, so #agent doesn't eat the start of #agentLead
65
+ .sort((a, b) => b.length - a.length)
66
+ .reduce((text, name) => text.replace(new RegExp(`#${escapeRegExp(name)}(?![\\w])`, 'g'), () => bindings[name].name), this.description);
67
+ }
68
+ toString() {
69
+ return this.description;
70
+ }
71
+ }
72
+ exports.Process = Process;
73
+ function escapeRegExp(text) {
74
+ return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
75
+ }
package/lib/Step.d.ts ADDED
@@ -0,0 +1,59 @@
1
+ import { Activity, Actor } from '@serenity-js/core';
2
+ /** Maps every role of a process to the actor who plays it. */
3
+ export type RoleBindings<Role extends string> = {
4
+ readonly [R in Role]: Actor;
5
+ };
6
+ /**
7
+ * One step of a {@link Process}. Either a {@link step} performed by a single role,
8
+ * or a {@link subprocess} that involves several.
9
+ */
10
+ export interface Step<Role extends string> {
11
+ /** The roles involved in this step, in order of first appearance. */
12
+ readonly roles: readonly Role[];
13
+ /**
14
+ * Performs the step.
15
+ *
16
+ * @param bindings The actors playing each role
17
+ * @param context The description of the (nested) process this step belongs to
18
+ */
19
+ perform(bindings: RoleBindings<Role>, context: string): Promise<void>;
20
+ }
21
+ /** The roles of a step type. */
22
+ export type RolesOf<S> = S extends Step<infer Role> ? Role : never;
23
+ /**
24
+ * An activity that refers to other actors in the process, built by {@link referringTo}.
25
+ * Its roles become roles of the step, and of the process.
26
+ */
27
+ export interface Referring<Role extends string> {
28
+ /** The roles referred to, in the order their names are passed on. */
29
+ readonly roles: readonly Role[];
30
+ /** Builds the activity from the actors playing the roles. */
31
+ activityFor(bindings: RoleBindings<Role>): Activity;
32
+ }
33
+ /** What a {@link step} performs: an activity, or one that refers to other actors. */
34
+ export type StepActivity = Activity | Referring<string>;
35
+ /** The roles referred to by the activities of a step. */
36
+ export type ReferredRolesOf<A> = A extends Referring<infer Role> ? Role : never;
37
+ /**
38
+ * An activity that refers to other actors in the process. The names of the actors
39
+ * playing `roles` are passed to `activity` in the same order, so its parameters
40
+ * can be named freely. The roles become part of the process: `.with()` requires
41
+ * an actor for them, and a nested process maps them like any other role.
42
+ *
43
+ * @example
44
+ * step('judge', referringTo('performer', 'singer', (p, s) => Compare(p).with(s)))
45
+ */
46
+ export declare function referringTo<const Roles extends [string, ...string[]]>(...args: [...roles: Roles, activity: (...names: {
47
+ [K in keyof Roles]: string;
48
+ }) => Activity]): Referring<Roles[number]>;
49
+ /**
50
+ * A step of a {@link Process}: the role that performs it, and its activities.
51
+ * Use {@link referringTo} for an activity that refers to other actors.
52
+ *
53
+ * @example
54
+ * step('customer', raiseTicket())
55
+ *
56
+ * @example
57
+ * step('judge', referringTo('performer', performer => JudgeTheWorkOf(performer)))
58
+ */
59
+ export declare const step: <Role extends string, const Activities extends StepActivity[]>(role: Role, ...activities: Activities) => Step<Role | ReferredRolesOf<Activities[number]>>;
package/lib/Step.js ADDED
@@ -0,0 +1,42 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.step = void 0;
4
+ exports.referringTo = referringTo;
5
+ const core_1 = require("@serenity-js/core");
6
+ /**
7
+ * An activity that refers to other actors in the process. The names of the actors
8
+ * playing `roles` are passed to `activity` in the same order, so its parameters
9
+ * can be named freely. The roles become part of the process: `.with()` requires
10
+ * an actor for them, and a nested process maps them like any other role.
11
+ *
12
+ * @example
13
+ * step('judge', referringTo('performer', 'singer', (p, s) => Compare(p).with(s)))
14
+ */
15
+ function referringTo(...args) {
16
+ const roles = args.slice(0, -1);
17
+ const activity = args[args.length - 1];
18
+ return {
19
+ roles,
20
+ activityFor: bindings => activity(...roles.map(role => bindings[role].name)),
21
+ };
22
+ }
23
+ /**
24
+ * A step of a {@link Process}: the role that performs it, and its activities.
25
+ * Use {@link referringTo} for an activity that refers to other actors.
26
+ *
27
+ * @example
28
+ * step('customer', raiseTicket())
29
+ *
30
+ * @example
31
+ * step('judge', referringTo('performer', performer => JudgeTheWorkOf(performer)))
32
+ */
33
+ const step = (role, ...activities) => ({
34
+ roles: [...new Set([role, ...activities.flatMap(a => isReferring(a) ? a.roles : [])])],
35
+ async perform(bindings, context) {
36
+ await bindings[role].attemptsTo(core_1.Task.where(`#actor, as ${role}, in: ${context}`, ...activities.map(a => isReferring(a) ? a.activityFor(bindings) : a)));
37
+ },
38
+ });
39
+ exports.step = step;
40
+ function isReferring(activity) {
41
+ return typeof activity.activityFor === 'function';
42
+ }
@@ -0,0 +1,27 @@
1
+ import { Process } from './Process';
2
+ import { Step } from './Step';
3
+ /** Maps (some of) the roles of a nested process to roles of the enclosing process. */
4
+ export type RoleMapping<ChildRole extends string> = {
5
+ readonly [R in ChildRole]?: string;
6
+ };
7
+ /** The roles a nested process contributes to its parent: mapped ones renamed, the rest unchanged. */
8
+ export type MappedRoles<ChildRole extends string, Mapping extends RoleMapping<ChildRole>> = {
9
+ [R in ChildRole]: R extends keyof Mapping ? Extract<Mapping[R], string> : R;
10
+ }[ChildRole];
11
+ /**
12
+ * A step of a {@link Process} that is itself a process.
13
+ *
14
+ * Roles of the nested process are played by the actors of the roles they are
15
+ * mapped to in the enclosing process. Roles not mentioned in `mapping` keep
16
+ * their name, so a nested process whose roles match its parent's needs no mapping.
17
+ * Several child roles may map to the same parent role.
18
+ *
19
+ * @example
20
+ * const purchase = Process.where('#buyer pays #seller', step('buyer', pay()), step('seller', ship()));
21
+ *
22
+ * const checkout = Process.where('#customer checks out and #agent follows up',
23
+ * subprocess(purchase, { buyer: 'customer', seller: 'agent' }),
24
+ * step('agent', sendInvoice()),
25
+ * );
26
+ */
27
+ export declare function subprocess<ChildRole extends string, const Mapping extends RoleMapping<ChildRole> = {}>(child: Process<ChildRole>, mapping?: Mapping): Step<MappedRoles<ChildRole, Mapping>>;
@@ -0,0 +1,29 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.subprocess = subprocess;
4
+ /**
5
+ * A step of a {@link Process} that is itself a process.
6
+ *
7
+ * Roles of the nested process are played by the actors of the roles they are
8
+ * mapped to in the enclosing process. Roles not mentioned in `mapping` keep
9
+ * their name, so a nested process whose roles match its parent's needs no mapping.
10
+ * Several child roles may map to the same parent role.
11
+ *
12
+ * @example
13
+ * const purchase = Process.where('#buyer pays #seller', step('buyer', pay()), step('seller', ship()));
14
+ *
15
+ * const checkout = Process.where('#customer checks out and #agent follows up',
16
+ * subprocess(purchase, { buyer: 'customer', seller: 'agent' }),
17
+ * step('agent', sendInvoice()),
18
+ * );
19
+ */
20
+ function subprocess(child, mapping) {
21
+ const parentRole = (role) => mapping?.[role] ?? role;
22
+ return {
23
+ roles: [...new Set(child.roles().map(parentRole))],
24
+ async perform(bindings, context) {
25
+ const childBindings = Object.fromEntries(child.roles().map(role => [role, bindings[parentRole(role)]]));
26
+ await child.run(childBindings, context);
27
+ },
28
+ };
29
+ }
package/lib/index.d.ts ADDED
@@ -0,0 +1,5 @@
1
+ export { Process } from './Process';
2
+ export { step, referringTo } from './Step';
3
+ export type { Step, RoleBindings, RolesOf, Referring, ReferredRolesOf, StepActivity } from './Step';
4
+ export { subprocess } from './Subprocess';
5
+ export type { RoleMapping, MappedRoles } from './Subprocess';
package/lib/index.js ADDED
@@ -0,0 +1,10 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.subprocess = exports.referringTo = exports.step = exports.Process = void 0;
4
+ var Process_1 = require("./Process");
5
+ Object.defineProperty(exports, "Process", { enumerable: true, get: function () { return Process_1.Process; } });
6
+ var Step_1 = require("./Step");
7
+ Object.defineProperty(exports, "step", { enumerable: true, get: function () { return Step_1.step; } });
8
+ Object.defineProperty(exports, "referringTo", { enumerable: true, get: function () { return Step_1.referringTo; } });
9
+ var Subprocess_1 = require("./Subprocess");
10
+ Object.defineProperty(exports, "subprocess", { enumerable: true, get: function () { return Subprocess_1.subprocess; } });
package/package.json CHANGED
@@ -1,6 +1,40 @@
1
1
  {
2
2
  "name": "serenity-process",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "Process: like a Serenity/JS Task, but performed by several actors, each playing a role",
5
+ "keywords": [
6
+ "serenity-js",
7
+ "serenity",
8
+ "testing",
9
+ "bdd",
10
+ "screenplay",
11
+ "multi-actor",
12
+ "process"
13
+ ],
14
+ "license": "MIT",
15
+ "main": "./lib/index.js",
16
+ "types": "./lib/index.d.ts",
17
+ "files": [
18
+ "lib",
19
+ "README.md",
20
+ "LICENSE"
21
+ ],
22
+ "engines": {
23
+ "node": ">=18"
24
+ },
25
+ "scripts": {
26
+ "build": "tsc -p tsconfig.build.json",
27
+ "test": "vitest run",
28
+ "typecheck": "tsc --noEmit",
29
+ "prepublishOnly": "npm run typecheck && npm test && npm run build"
30
+ },
31
+ "peerDependencies": {
32
+ "@serenity-js/core": "^3.0.0"
33
+ },
34
+ "devDependencies": {
35
+ "@serenity-js/core": "^3.49.0",
36
+ "@types/node": "^22.0.0",
37
+ "typescript": "^5.6.0",
38
+ "vitest": "^2.1.0"
39
+ }
40
+ }