serenity-process 0.0.0-stage → 0.1.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,73 @@
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
+ ## Nested processes
30
+
31
+ A step can itself be a process. `subprocess(child, mapping)` binds the child's roles to roles of the
32
+ enclosing process:
33
+
34
+ ```ts
35
+ import { Process, step, subprocess } from 'serenity-process';
36
+
37
+ const purchase = Process.where('#buyer pays #seller',
38
+ step('buyer', pay()),
39
+ step('seller', ship()),
40
+ );
41
+
42
+ const checkout = Process.where('#customer checks out, #agent follows up',
43
+ step('customer', browse()),
44
+ subprocess(purchase, { buyer: 'customer', seller: 'agent' }),
45
+ step('agent', sendInvoice()),
46
+ );
47
+
48
+ await When(checkout.with({ customer: chidi, agent: priya }));
49
+ ```
50
+
51
+ - Child roles not listed in the mapping keep their name; with no mapping at all the roles pass straight through.
52
+ - Several child roles may map to the same parent role (one actor plays both).
53
+ - The parent's roles (and what `.with()` requires) are inferred by TypeScript, nested ones included.
54
+ - Nesting can go as deep as you like; the first failing step stops everything.
55
+ - Report descriptions show the path: `Priya, as seller, in: Chidi checks out, Priya follows up > Chidi pays Priya`.
56
+
57
+ ## Install
58
+
59
+ ```bash
60
+ npm install serenity-process
61
+ ```
62
+
63
+ Requires `@serenity-js/core` ^3 as a peer dependency.
64
+
65
+ ## Development
66
+
67
+ ```bash
68
+ npm install
69
+ npm test
70
+ npm run build
71
+ ```
72
+
73
+ 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,29 @@
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
+ * A step of a {@link Process}: the role that performs it, and its activities.
25
+ *
26
+ * @example
27
+ * step('customer', raiseTicket())
28
+ */
29
+ export declare const step: <Role extends string>(role: Role, ...activities: Activity[]) => Step<Role>;
package/lib/Step.js ADDED
@@ -0,0 +1,17 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.step = void 0;
4
+ const core_1 = require("@serenity-js/core");
5
+ /**
6
+ * A step of a {@link Process}: the role that performs it, and its activities.
7
+ *
8
+ * @example
9
+ * step('customer', raiseTicket())
10
+ */
11
+ const step = (role, ...activities) => ({
12
+ roles: [role],
13
+ async perform(bindings, context) {
14
+ await bindings[role].attemptsTo(core_1.Task.where(`#actor, as ${role}, in: ${context}`, ...activities));
15
+ },
16
+ });
17
+ exports.step = step;
@@ -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 } from './Step';
3
+ export type { Step, RoleBindings, RolesOf } from './Step';
4
+ export { subprocess } from './Subprocess';
5
+ export type { RoleMapping, MappedRoles } from './Subprocess';
package/lib/index.js ADDED
@@ -0,0 +1,9 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.subprocess = 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
+ var Subprocess_1 = require("./Subprocess");
9
+ Object.defineProperty(exports, "subprocess", { enumerable: true, get: function () { return Subprocess_1.subprocess; } });
package/package.json CHANGED
@@ -1,6 +1,26 @@
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.1.0",
4
+ "description": "Process: like a Serenity/JS Task, but performed by several actors, each playing a role",
5
+ "keywords": ["serenity-js", "serenity", "testing", "bdd", "screenplay", "multi-actor", "process"],
6
+ "license": "MIT",
7
+ "main": "./lib/index.js",
8
+ "types": "./lib/index.d.ts",
9
+ "files": ["lib", "README.md", "LICENSE"],
10
+ "engines": { "node": ">=18" },
11
+ "scripts": {
12
+ "build": "tsc -p tsconfig.build.json",
13
+ "test": "vitest run",
14
+ "typecheck": "tsc --noEmit",
15
+ "prepublishOnly": "npm run typecheck && npm test && npm run build"
16
+ },
17
+ "peerDependencies": {
18
+ "@serenity-js/core": "^3.0.0"
19
+ },
20
+ "devDependencies": {
21
+ "@serenity-js/core": "^3.49.0",
22
+ "@types/node": "^22.0.0",
23
+ "typescript": "^5.6.0",
24
+ "vitest": "^2.1.0"
25
+ }
26
+ }