@serenity-js/core 3.0.0-rc.9 → 3.0.1

package/lib/screenplay/questions/expectations/ExpectationDetails.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExpectationDetails = void 0;
+const tiny_types_1 = require("tiny-types");
+const io_1 = require("../../../io");
+const model_1 = require("../../../model");
+const Unanswered_1 = require("../Unanswered");
+/**
+ * Used with {@apilink ExpectationOutcome} to describe an {@apilink Expectation} and the arguments it's been executed with.
+ *
+ * @group Expectations
+ */
+class ExpectationDetails extends tiny_types_1.TinyType {
+    static of(functionName, ...functionArguments) {
+        return new ExpectationDetails(new model_1.Name(functionName), functionArguments);
+    }
+    static fromJSON(o) {
+        return new ExpectationDetails(model_1.Name.fromJSON(o.name), o.args.map(arg => {
+            if (arg.type === Unanswered_1.Unanswered.name) {
+                return new Unanswered_1.Unanswered();
+            }
+            if (arg.type === ExpectationDetails.name) {
+                return ExpectationDetails.fromJSON(arg.value);
+            }
+            // must be a JSONValue then
+            return arg.value;
+        }));
+    }
+    constructor(name, args) {
+        super();
+        this.name = name;
+        this.args = args;
+        (0, tiny_types_1.ensure)('name', name, (0, tiny_types_1.isDefined)());
+        (0, tiny_types_1.ensure)('args', args, (0, tiny_types_1.isArray)());
+    }
+    toString() {
+        const argumentValues = this.args.map(arg => arg instanceof ExpectationDetails
+            ? arg.toString()
+            : (0, io_1.inspected)(arg, { compact: true })).join(', ');
+        return `${this.name.value}(${argumentValues})`;
+    }
+    toJSON() {
+        return {
+            name: this.name.value,
+            args: this.args.map(arg => ({
+                type: (0, io_1.typeOf)(arg),
+                value: arg['toJSON']
+                    ? arg.toJSON()
+                    : arg,
+            })),
+        };
+    }
+}
+exports.ExpectationDetails = ExpectationDetails;
+//# sourceMappingURL=ExpectationDetails.js.map

package/lib/screenplay/questions/expectations/ExpectationDetails.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpectationDetails.js","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationDetails.ts"],"names":[],"mappings":";;;AAAA,2CAAyF;AAEzF,oCAAgD;AAChD,0CAAsC;AACtC,8CAA2C;AAE3C;;;;GAIG;AACH,MAAa,kBAAmB,SAAQ,qBAAQ;IAE5C,MAAM,CAAC,EAAE,CAAC,YAAoB,EAAE,GAAG,iBAAqE;QACpG,OAAO,IAAI,kBAAkB,CAAC,IAAI,YAAI,CAAC,YAAY,CAAC,EAAE,iBAAiB,CAAC,CAAC;IAC7E,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,CAAa;QACzB,OAAO,IAAI,kBAAkB,CACzB,YAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAc,CAAC,EAC9B,CAAC,CAAC,IAAkD,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;YAC5D,IAAI,GAAG,CAAC,IAAI,KAAK,uBAAU,CAAC,IAAI,EAAE;gBAC9B,OAAO,IAAI,uBAAU,EAAE,CAAC;aAC3B;YACD,IAAI,GAAG,CAAC,IAAI,KAAK,kBAAkB,CAAC,IAAI,EAAE;gBACtC,OAAO,kBAAkB,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAmB,CAAC,CAAA;aAC9D;YACD,2BAA2B;YAC3B,OAAO,GAAG,CAAC,KAAK,CAAC;QACrB,CAAC,CAAC,CACL,CAAC;IACN,CAAC;IAED,YACoB,IAAU,EACV,IAAwD;QAExE,KAAK,EAAE,CAAC;QAHQ,SAAI,GAAJ,IAAI,CAAM;QACV,SAAI,GAAJ,IAAI,CAAoD;QAGxE,IAAA,mBAAM,EAAC,MAAM,EAAE,IAAI,EAAE,IAAA,sBAAS,GAAE,CAAC,CAAC;QAClC,IAAA,mBAAM,EAAC,MAAM,EAAE,IAAI,EAAE,IAAA,oBAAO,GAAE,CAAC,CAAC;IACpC,CAAC;IAED,QAAQ;QACJ,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CACvC,GAAG,YAAY,kBAAkB;YAC7B,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE;YAChB,CAAC,CAAC,IAAA,cAAS,EAAC,GAAG,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAC1C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,OAAO,GAAI,IAAI,CAAC,IAAI,CAAC,KAAM,IAAK,cAAe,GAAG,CAAC;IACvD,CAAC;IAED,MAAM;QACF,OAAO;YACH,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK;YACrB,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACxB,IAAI,EAAE,IAAA,WAAM,EAAC,GAAG,CAAC;gBACjB,KAAK,EAAE,GAAG,CAAC,QAAQ,CAAC;oBAChB,CAAC,CAAE,GAAW,CAAC,MAAM,EAAE;oBACvB,CAAC,CAAC,GAAG;aACZ,CAAC,CAAC;SACN,CAAA;IACL,CAAC;CACJ;AApDD,gDAoDC"}

package/lib/screenplay/questions/expectations/ExpectationMet.d.ts

@@ -1,3 +1,9 @@
 import { ExpectationOutcome } from './ExpectationOutcome';
-export declare class ExpectationMet<Expected, Actual> extends ExpectationOutcome<Expected, Actual> {
+/**
+ * Indicates that an {@apilink Expectation} was met.
+ *
+ * @group Expectations
+ */
+export declare class ExpectationMet extends ExpectationOutcome {
 }
+//# sourceMappingURL=ExpectationMet.d.ts.map

package/lib/screenplay/questions/expectations/ExpectationMet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpectationMet.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationMet.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,kBAAkB;CAAG"}

package/lib/screenplay/questions/expectations/ExpectationMet.js

@@ -2,6 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExpectationMet = void 0;
 const ExpectationOutcome_1 = require("./ExpectationOutcome");
+/**
+ * Indicates that an {@apilink Expectation} was met.
+ *
+ * @group Expectations
+ */
 class ExpectationMet extends ExpectationOutcome_1.ExpectationOutcome {
 }
 exports.ExpectationMet = ExpectationMet;

package/lib/screenplay/questions/expectations/ExpectationMet.js.map

@@ -1 +1 @@
-{"version":3,"file":"ExpectationMet.js","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationMet.ts"],"names":[],"mappings":";;;AAAA,6DAA0D;AAE1D,MAAa,cAAiC,SAAQ,uCAAoC;CAAG;AAA7F,wCAA6F"}
+{"version":3,"file":"ExpectationMet.js","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationMet.ts"],"names":[],"mappings":";;;AAAA,6DAA0D;AAE1D;;;;GAIG;AACH,MAAa,cAAe,SAAQ,uCAAkB;CAAG;AAAzD,wCAAyD"}

package/lib/screenplay/questions/expectations/ExpectationNotMet.d.ts

@@ -1,3 +1,9 @@
 import { ExpectationOutcome } from './ExpectationOutcome';
-export declare class ExpectationNotMet<Expected, Actual> extends ExpectationOutcome<Expected, Actual> {
+/**
+ * Indicates that an {@apilink Expectation} was not met.
+ *
+ * @group Expectations
+ */
+export declare class ExpectationNotMet extends ExpectationOutcome {
 }
+//# sourceMappingURL=ExpectationNotMet.d.ts.map

package/lib/screenplay/questions/expectations/ExpectationNotMet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpectationNotMet.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationNotMet.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,kBAAkB;CAAG"}

package/lib/screenplay/questions/expectations/ExpectationNotMet.js

@@ -2,6 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExpectationNotMet = void 0;
 const ExpectationOutcome_1 = require("./ExpectationOutcome");
+/**
+ * Indicates that an {@apilink Expectation} was not met.
+ *
+ * @group Expectations
+ */
 class ExpectationNotMet extends ExpectationOutcome_1.ExpectationOutcome {
 }
 exports.ExpectationNotMet = ExpectationNotMet;

package/lib/screenplay/questions/expectations/ExpectationNotMet.js.map

@@ -1 +1 @@
-{"version":3,"file":"ExpectationNotMet.js","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationNotMet.ts"],"names":[],"mappings":";;;AAAA,6DAA0D;AAE1D,MAAa,iBAAoC,SAAQ,uCAAoC;CAAG;AAAhG,8CAAgG"}
+{"version":3,"file":"ExpectationNotMet.js","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationNotMet.ts"],"names":[],"mappings":";;;AAAA,6DAA0D;AAE1D;;;;GAIG;AACH,MAAa,iBAAkB,SAAQ,uCAAkB;CAAG;AAA5D,8CAA4D"}

package/lib/screenplay/questions/expectations/ExpectationOutcome.d.ts

@@ -1,7 +1,16 @@
 import { TinyType } from 'tiny-types';
-export declare class ExpectationOutcome<Expected, Actual> extends TinyType {
+import { ExpectationDetails } from './ExpectationDetails';
+/**
+ * An outcome of an {@apilink Expectation},
+ * which could be either {@apilink ExpectationMet|met} or {@apilink ExpectationNotMet|not met}.
+ *
+ * @group Expectations
+ */
+export declare class ExpectationOutcome extends TinyType {
     readonly message: string;
-    readonly expected: Expected;
-    readonly actual: Actual;
-    constructor(message: string, expected: Expected, actual: Actual);
+    readonly expectation: ExpectationDetails;
+    readonly expected: unknown;
+    readonly actual: unknown;
+    constructor(message: string, expectation: ExpectationDetails, expected: unknown, actual: unknown);
 }
+//# sourceMappingURL=ExpectationOutcome.d.ts.map

package/lib/screenplay/questions/expectations/ExpectationOutcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpectationOutcome.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationOutcome.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;aAExB,OAAO,EAAE,MAAM;aACf,WAAW,EAAE,kBAAkB;aAC/B,QAAQ,EAAE,OAAO;aACjB,MAAM,EAAE,OAAO;gBAHf,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,kBAAkB,EAC/B,QAAQ,EAAE,OAAO,EACjB,MAAM,EAAE,OAAO;CAItC"}

package/lib/screenplay/questions/expectations/ExpectationOutcome.js

@@ -2,10 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExpectationOutcome = void 0;
 const tiny_types_1 = require("tiny-types");
+/**
+ * An outcome of an {@apilink Expectation},
+ * which could be either {@apilink ExpectationMet|met} or {@apilink ExpectationNotMet|not met}.
+ *
+ * @group Expectations
+ */
 class ExpectationOutcome extends tiny_types_1.TinyType {
-    constructor(message, expected, actual) {
+    constructor(message, expectation, expected, actual) {
         super();
         this.message = message;
+        this.expectation = expectation;
         this.expected = expected;
         this.actual = actual;
     }

package/lib/screenplay/questions/expectations/ExpectationOutcome.js.map

@@ -1 +1 @@
-{"version":3,"file":"ExpectationOutcome.js","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationOutcome.ts"],"names":[],"mappings":";;;AAAA,2CAAsC;AAEtC,MAAa,kBAAqC,SAAQ,qBAAQ;IAC9D,YACoB,OAAe,EACf,QAAkB,EAClB,MAAc;QAE9B,KAAK,EAAE,CAAC;QAJQ,YAAO,GAAP,OAAO,CAAQ;QACf,aAAQ,GAAR,QAAQ,CAAU;QAClB,WAAM,GAAN,MAAM,CAAQ;IAGlC,CAAC;CACJ;AARD,gDAQC"}
+{"version":3,"file":"ExpectationOutcome.js","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationOutcome.ts"],"names":[],"mappings":";;;AAAA,2CAAsC;AAItC;;;;;GAKG;AACH,MAAa,kBAAmB,SAAQ,qBAAQ;IAC5C,YACoB,OAAe,EACf,WAA+B,EAC/B,QAAiB,EACjB,MAAe;QAE/B,KAAK,EAAE,CAAC;QALQ,YAAO,GAAP,OAAO,CAAQ;QACf,gBAAW,GAAX,WAAW,CAAoB;QAC/B,aAAQ,GAAR,QAAQ,CAAS;QACjB,WAAM,GAAN,MAAM,CAAS;IAGnC,CAAC;CACJ;AATD,gDASC"}

package/lib/screenplay/questions/expectations/index.d.ts

@@ -1,3 +1,5 @@
+export * from './ExpectationDetails';
 export * from './ExpectationMet';
 export * from './ExpectationNotMet';
 export * from './ExpectationOutcome';
+//# sourceMappingURL=index.d.ts.map

package/lib/screenplay/questions/expectations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}

package/lib/screenplay/questions/expectations/index.js

@@ -1,7 +1,11 @@
 "use strict";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
 }) : (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
@@ -10,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ExpectationDetails"), exports);
 __exportStar(require("./ExpectationMet"), exports);
 __exportStar(require("./ExpectationNotMet"), exports);
 __exportStar(require("./ExpectationOutcome"), exports);

package/lib/screenplay/questions/expectations/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,mDAAiC;AACjC,sDAAoC;AACpC,uDAAqC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,uDAAqC;AACrC,mDAAiC;AACjC,sDAAoC;AACpC,uDAAqC"}

package/lib/screenplay/questions/index.d.ts

@@ -1,7 +1,9 @@
+export * from './AnswersQuestions';
 export * from './Check';
 export * from './Expectation';
 export * from './expectations';
 export * from './List';
 export * from './MetaQuestion';
-export * from './Note';
 export * from './q';
+export * from './Unanswered';
+//# sourceMappingURL=index.d.ts.map

package/lib/screenplay/questions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,KAAK,CAAC;AACpB,cAAc,cAAc,CAAC"}

package/lib/screenplay/questions/index.js

@@ -1,7 +1,11 @@
 "use strict";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
 }) : (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
@@ -10,11 +14,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./AnswersQuestions"), exports);
 __exportStar(require("./Check"), exports);
 __exportStar(require("./Expectation"), exports);
 __exportStar(require("./expectations"), exports);
 __exportStar(require("./List"), exports);
 __exportStar(require("./MetaQuestion"), exports);
-__exportStar(require("./Note"), exports);
 __exportStar(require("./q"), exports);
+__exportStar(require("./Unanswered"), exports);
 //# sourceMappingURL=index.js.map

package/lib/screenplay/questions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/questions/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,0CAAwB;AACxB,gDAA8B;AAC9B,iDAA+B;AAC/B,yCAAuB;AACvB,iDAA+B;AAC/B,yCAAuB;AACvB,sCAAoB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/questions/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,0CAAwB;AACxB,gDAA8B;AAC9B,iDAA+B;AAC/B,yCAAuB;AACvB,iDAA+B;AAC/B,sCAAoB;AACpB,+CAA6B"}

package/lib/screenplay/questions/q.d.ts

@@ -1,35 +1,66 @@
 import { Answerable } from '../Answerable';
-import { Question } from '../Question';
+import { QuestionAdapter } from '../Question';
 /**
- * @desc
- *  A Screenplay-flavour of a [tagged template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates),
- *  `q` is a tag function capable of resolving any `Answerable<string | number>` you parametrise it with (i.e. a {@link Question}).
+ * A Serenity/JS Screenplay Pattern-flavour
+ * of a [tagged template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates),
+ * `q` is a tag function capable of resolving any `Answerable<string>` or `Answerable<number>`
+ * you parametrise it with, and returning a `QuestionAdapter<string>`.
  *
- * @example <caption>Interpolating `Questions`</caption>
- *  import { q, actorCalled } from '@serenity-js/core';
- *  import { Send, DeleteRequest } from '@serenity-js/rest';
+ * Use `q` to concatenate `string` and `number` values returned from synchronous an asynchronous sources.
  *
- *  actorCalled('Alice').attemptsTo(
- *      Send.a(DeleteRequest.to(
- *          q `/articles/${ Text.of(Article.id()) }`
- *      ))
- *  )
+ * ## Interpolating questions
  *
- * @example <caption>Using a custom description</caption>
- *  import { q, actorCalled } from '@serenity-js/core';
- *  import { Send, DeleteRequest } from '@serenity-js/rest';
+ * ```ts
+ * import { q, actorCalled } from '@serenity-js/core'
+ * import { Send, DeleteRequest } from '@serenity-js/rest'
+ * import { Text } from '@serenity-js/web'
  *
- *  actorCalled('Alice').attemptsTo(
- *      Send.a(DeleteRequest.to(
- *          q `/articles/${ Text.of(Article.id()) }`.describedAs('/articles/:id')
- *      ))
- *  )
+ * await actorCalled('Alice').attemptsTo(
+ *   Send.a(DeleteRequest.to(
+ *     q `/articles/${ Text.of(Article.id()) }`
+ *   ))
+ * )
+ * ```
  *
- * @param {TemplateStringsArray} templates
- * @param {Array<Answerable<string | number>>} parameters
+ * ## Using a custom description
  *
- * @returns {Question<Promise<string>>}
+ * ```ts
+ * import { q, actorCalled } from '@serenity-js/core'
+ * import { Send, DeleteRequest } from '@serenity-js/rest'
  *
- * @see {@link Question}
+ * await actorCalled('Alice').attemptsTo(
+ *   Send.a(DeleteRequest.to(
+ *     q `/articles/${ Text.of(Article.id()) }`.describedAs('/articles/:id')
+ *   ))
+ * )
+ * ```
+ *
+ * ## Transforming the interpolated string
+ *
+ * The mechanism presented below relies on {@apilink QuestionAdapter}.
+ *
+ * ```ts
+ * import { q, actorCalled } from '@serenity-js/core'
+ * import { Send, DeleteRequest } from '@serenity-js/rest'
+ *
+ * await actorCalled('Alice').attemptsTo(
+ *   Send.a(DeleteRequest.to(
+ *     q `/articles/${ Text.of(Article.id()) }`.toLocaleLowerCase()
+ *   ))
+ * )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - {@apilink Answerable}
+ * - {@apilink Question}
+ * - {@apilink Question.describedAs}
+ * - {@apilink QuestionAdapter}
+ *
+ * @group Questions
+ *
+ * @param templates
+ * @param parameters
  */
-export declare function q(templates: TemplateStringsArray, ...parameters: Array<Answerable<string | number>>): Question<Promise<string>>;
+export declare function q(templates: TemplateStringsArray, ...parameters: Array<Answerable<string | number>>): QuestionAdapter<string>;
+//# sourceMappingURL=q.d.ts.map

package/lib/screenplay/questions/q.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"q.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/q.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAY,eAAe,EAAE,MAAM,aAAa,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,wBAAgB,CAAC,CAAC,SAAS,EAAE,oBAAoB,EAAE,GAAG,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,CAe7H"}

package/lib/screenplay/questions/q.js

@@ -3,36 +3,66 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.q = void 0;
 const Question_1 = require("../Question");
 /**
- * @desc
- *  A Screenplay-flavour of a [tagged template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates),
- *  `q` is a tag function capable of resolving any `Answerable<string | number>` you parametrise it with (i.e. a {@link Question}).
+ * A Serenity/JS Screenplay Pattern-flavour
+ * of a [tagged template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates),
+ * `q` is a tag function capable of resolving any `Answerable<string>` or `Answerable<number>`
+ * you parametrise it with, and returning a `QuestionAdapter<string>`.
  *
- * @example <caption>Interpolating `Questions`</caption>
- *  import { q, actorCalled } from '@serenity-js/core';
- *  import { Send, DeleteRequest } from '@serenity-js/rest';
+ * Use `q` to concatenate `string` and `number` values returned from synchronous an asynchronous sources.
  *
- *  actorCalled('Alice').attemptsTo(
- *      Send.a(DeleteRequest.to(
- *          q `/articles/${ Text.of(Article.id()) }`
- *      ))
- *  )
+ * ## Interpolating questions
  *
- * @example <caption>Using a custom description</caption>
- *  import { q, actorCalled } from '@serenity-js/core';
- *  import { Send, DeleteRequest } from '@serenity-js/rest';
+ * ```ts
+ * import { q, actorCalled } from '@serenity-js/core'
+ * import { Send, DeleteRequest } from '@serenity-js/rest'
+ * import { Text } from '@serenity-js/web'
  *
- *  actorCalled('Alice').attemptsTo(
- *      Send.a(DeleteRequest.to(
- *          q `/articles/${ Text.of(Article.id()) }`.describedAs('/articles/:id')
- *      ))
- *  )
+ * await actorCalled('Alice').attemptsTo(
+ *   Send.a(DeleteRequest.to(
+ *     q `/articles/${ Text.of(Article.id()) }`
+ *   ))
+ * )
+ * ```
  *
- * @param {TemplateStringsArray} templates
- * @param {Array<Answerable<string | number>>} parameters
+ * ## Using a custom description
  *
- * @returns {Question<Promise<string>>}
+ * ```ts
+ * import { q, actorCalled } from '@serenity-js/core'
+ * import { Send, DeleteRequest } from '@serenity-js/rest'
  *
- * @see {@link Question}
+ * await actorCalled('Alice').attemptsTo(
+ *   Send.a(DeleteRequest.to(
+ *     q `/articles/${ Text.of(Article.id()) }`.describedAs('/articles/:id')
+ *   ))
+ * )
+ * ```
+ *
+ * ## Transforming the interpolated string
+ *
+ * The mechanism presented below relies on {@apilink QuestionAdapter}.
+ *
+ * ```ts
+ * import { q, actorCalled } from '@serenity-js/core'
+ * import { Send, DeleteRequest } from '@serenity-js/rest'
+ *
+ * await actorCalled('Alice').attemptsTo(
+ *   Send.a(DeleteRequest.to(
+ *     q `/articles/${ Text.of(Article.id()) }`.toLocaleLowerCase()
+ *   ))
+ * )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - {@apilink Answerable}
+ * - {@apilink Question}
+ * - {@apilink Question.describedAs}
+ * - {@apilink QuestionAdapter}
+ *
+ * @group Questions
+ *
+ * @param templates
+ * @param parameters
  */
 function q(templates, ...parameters) {
     return Question_1.Question.about(templates.join('{}'), actor => Promise.all(parameters.map(parameter => actor.answer(parameter)))

package/lib/screenplay/questions/q.js.map

@@ -1 +1 @@
-{"version":3,"file":"q.js","sourceRoot":"","sources":["../../../src/screenplay/questions/q.ts"],"names":[],"mappings":";;;AACA,0CAAuC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,SAAgB,CAAC,CAAC,SAA+B,EAAE,GAAG,UAA8C;IAChG,OAAO,mBAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,EAAE,CAChD,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;SAC5D,IAAI,CAAC,OAAO,CAAC,EAAE,CACZ,SAAS;SACJ,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,CACjB,CAAC,GAAG,OAAO,CAAC,MAAM;QACd,CAAC,CAAC,CAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAE;QAC1B,CAAC,CAAC,CAAE,QAAQ,CAAE,CAAC;SACtB,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CACnB,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CACpB;SACA,IAAI,CAAC,EAAE,CAAC,CAChB,CACR,CAAC;AACN,CAAC;AAfD,cAeC"}
+{"version":3,"file":"q.js","sourceRoot":"","sources":["../../../src/screenplay/questions/q.ts"],"names":[],"mappings":";;;AACA,0CAAwD;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,SAAgB,CAAC,CAAC,SAA+B,EAAE,GAAG,UAA8C;IAChG,OAAO,mBAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,EAAE,CAChD,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;SAC5D,IAAI,CAAC,OAAO,CAAC,EAAE,CACZ,SAAS;SACJ,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,CACjB,CAAC,GAAG,OAAO,CAAC,MAAM;QACd,CAAC,CAAC,CAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAE;QAC1B,CAAC,CAAC,CAAE,QAAQ,CAAE,CAAC;SACtB,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CACnB,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CACpB;SACA,IAAI,CAAC,EAAE,CAAC,CAChB,CACR,CAAC;AACN,CAAC;AAfD,cAeC"}

package/lib/screenplay/time/abilities/ScheduleWork.d.ts

@@ -0,0 +1,26 @@
+import { Ability, Discardable, Initialisable } from '../../abilities';
+import { Clock, DelayedCallback, Duration, RepeatUntilLimits } from '../models';
+/**
+ * An {@apilink Ability} that enables an {@apilink Actor} to schedule a callback function
+ * to be executed with a delay, or until some condition is met.
+ *
+ * Used internally by the {@apilink Interaction|interaction} to {@apilink Wait}.
+ *
+ * @experimental
+ *
+ * @group Time
+ */
+export declare class ScheduleWork extends Ability implements Initialisable, Discardable {
+    private readonly scheduler;
+    constructor(clock: Clock, interactionTimeout: Duration);
+    initialise(): void;
+    isInitialised(): boolean;
+    /**
+     * @param callback
+     * @param limits
+     */
+    repeatUntil<Result>(callback: DelayedCallback<Result>, limits?: RepeatUntilLimits<Result>): Promise<Result>;
+    waitFor(delay: Duration): Promise<void>;
+    discard(): void;
+}
+//# sourceMappingURL=ScheduleWork.d.ts.map

package/lib/screenplay/time/abilities/ScheduleWork.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScheduleWork.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/time/abilities/ScheduleWork.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,iBAAiB,EAAa,MAAM,WAAW,CAAC;AAE3F;;;;;;;;;GASG;AACH,qBAAa,YAAa,SAAQ,OAAQ,YAAW,aAAa,EAAE,WAAW;IAE3E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;gBAE1B,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAE,QAAQ;IAKtD,UAAU,IAAI,IAAI;IAIlB,aAAa,IAAI,OAAO;IAIxB;;;OAGG;IACH,WAAW,CAAC,MAAM,EACd,QAAQ,EAAE,eAAe,CAAC,MAAM,CAAC,EACjC,MAAM,CAAC,EAAE,iBAAiB,CAAC,MAAM,CAAC,GACnC,OAAO,CAAC,MAAM,CAAC;IAIlB,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvC,OAAO,IAAI,IAAI;CAGlB"}

package/lib/screenplay/time/abilities/ScheduleWork.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScheduleWork = void 0;
+const abilities_1 = require("../../abilities");
+const models_1 = require("../models");
+/**
+ * An {@apilink Ability} that enables an {@apilink Actor} to schedule a callback function
+ * to be executed with a delay, or until some condition is met.
+ *
+ * Used internally by the {@apilink Interaction|interaction} to {@apilink Wait}.
+ *
+ * @experimental
+ *
+ * @group Time
+ */
+class ScheduleWork extends abilities_1.Ability {
+    constructor(clock, interactionTimeout) {
+        super();
+        this.scheduler = new models_1.Scheduler(clock, interactionTimeout);
+    }
+    initialise() {
+        this.scheduler.start();
+    }
+    isInitialised() {
+        return this.scheduler.isRunning();
+    }
+    /**
+     * @param callback
+     * @param limits
+     */
+    repeatUntil(callback, limits) {
+        return this.scheduler.repeatUntil(callback, limits);
+    }
+    waitFor(delay) {
+        this.scheduler.start();
+        return this.scheduler.after(delay, () => {
+            // do nothing
+        });
+    }
+    discard() {
+        this.scheduler.stop();
+    }
+}
+exports.ScheduleWork = ScheduleWork;
+//# sourceMappingURL=ScheduleWork.js.map

package/lib/screenplay/time/abilities/ScheduleWork.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScheduleWork.js","sourceRoot":"","sources":["../../../../src/screenplay/time/abilities/ScheduleWork.ts"],"names":[],"mappings":";;;AAAA,+CAAsE;AACtE,sCAA2F;AAE3F;;;;;;;;;GASG;AACH,MAAa,YAAa,SAAQ,mBAAO;IAIrC,YAAY,KAAY,EAAE,kBAA4B;QAClD,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,SAAS,GAAG,IAAI,kBAAS,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAC;IAC9D,CAAC;IAED,UAAU;QACN,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;IAED,aAAa;QACT,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,CAAC;IACtC,CAAC;IAED;;;OAGG;IACH,WAAW,CACP,QAAiC,EACjC,MAAkC;QAElC,OAAO,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,CAAC,KAAe;QACnB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE;YACpC,aAAa;QACjB,CAAC,CAAC,CAAA;IACN,CAAC;IAED,OAAO;QACH,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;CACJ;AAtCD,oCAsCC"}

package/lib/screenplay/time/abilities/index.d.ts

@@ -0,0 +1,2 @@
+export * from './ScheduleWork';
+//# sourceMappingURL=index.d.ts.map

package/lib/screenplay/time/abilities/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/time/abilities/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/lib/{io/json → screenplay/time/abilities}/index.js

@@ -1,7 +1,11 @@
 "use strict";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
 }) : (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
@@ -10,5 +14,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./cycle"), exports);
+__exportStar(require("./ScheduleWork"), exports);
 //# sourceMappingURL=index.js.map

package/lib/screenplay/time/abilities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/screenplay/time/abilities/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA+B"}